Documentation
¶
Overview ¶
Package errors provides small error helpers used across go-service.
This package is intentionally lightweight. It primarily re-exports a subset of the standard library errors package APIs (As, AsType, Is, Join, New) behind a stable go-service import path, and provides a small convenience helper (Prefix) for consistently attributing errors to a subsystem or component.
Re-exports ¶
The following functions mirror the behavior and semantics of the standard library equivalents:
- As: type-assert (via error chain traversal) into a target
- AsType: generic typed lookup in an error chain
- Is: match a target error in an error chain
- Join: combine multiple errors into one
- New: construct a sentinel error value
Prefixing errors ¶
Prefix is commonly used at module/service boundaries to add a stable component prefix to an error message while preserving the original error for unwrapping:
err := errors.Prefix("cache", underlyingErr)
Prefix returns nil when the input error is nil, which makes it convenient to use in return statements without additional nil checks.
Safe messages ¶
SafeMessenger lets error implementations expose a non-sensitive message for clients while retaining diagnostic Error text for logs and wrapping. SafeMessage walks wrapped and joined errors, returns the first non-empty safe message it finds, and otherwise returns the caller-provided fallback as supplied.
Start with As, AsType, Is, Join, New, Prefix, and SafeMessage.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶ added in v2.14.0
As reports whether any error in err's chain matches target, and if so sets target to that error value.
This is a thin wrapper around the standard library errors.As, provided so go-service code can depend on a stable import path.
func AsType ¶ added in v2.303.0
AsType reports whether any error in err's chain matches T, and if so returns the matched value.
This is a thin wrapper around the standard library errors.AsType. It is useful when callers want the matched typed value directly instead of allocating a temporary target variable first.
If no matching error is found, AsType returns the zero value of T and false.
func Is ¶ added in v2.14.0
Is reports whether any error in err's chain matches target.
This is a thin wrapper around the standard library errors.Is.
func Join ¶ added in v2.14.0
Join returns an error that wraps the given errors.
This is a thin wrapper around the standard library errors.Join. A nil error in errs is ignored. If all errors are nil, Join returns nil.
func New ¶ added in v2.14.0
New returns an error that formats as the given text.
This is a thin wrapper around the standard library errors.New. It is typically used to define sentinel errors for comparisons with Is.
func Prefix ¶
Prefix wraps err with a component prefix while preserving it for unwrapping.
It formats the returned error using:
fmt.Errorf("%v: %w", prefix, err)
If err is nil, Prefix returns nil. This makes it convenient to use in return statements without additional nil checks.
Example:
return errors.Prefix("database", err)
func SafeMessage ¶ added in v2.403.0
SafeMessage returns the first safe message in err's tree, or fallback when none is available.
SafeMessage checks err itself, then follows single-error wrappers and joined-error children in order. Empty safe messages are ignored. The fallback is returned as supplied, so callers that need a non-empty client message should pass a non-empty fallback.
Types ¶
type SafeMessenger ¶ added in v2.403.0
type SafeMessenger interface {
// SafeMessage returns a non-sensitive message suitable for clients.
//
// Returning an empty string means this error has no safe message of its own; [SafeMessage] will continue
// walking wrapped errors or use the caller-provided fallback.
SafeMessage() string
}
SafeMessenger allows an error to expose a message that is safe to send outside the process.
Error implementations can use this when Error contains diagnostic details that should be retained for logs or wrapping, but clients should receive a smaller, non-sensitive message.
Source Files