Documentation
¶
Overview ¶
Package errors provides application error types and codes, and the request-scoped error sink that keeps a domain error's real cause behind its sanitized transport error.
The transport layer maps a domain error to a client-safe error (hiding SQL errors, stack traces, etc.) before returning it to the caller, discarding the real cause. The mapper Captures the real error into the request's sink (WithSink), and the request-logging interceptor reads it back with Captured after the handler returns — one log line per request, with the true cause, without every layer logging its own copy.
Index ¶
- Constants
- func Append(left, right error) error
- func As(err error, target any) bool
- func Capture(ctx context.Context, err error)
- func Captured(ctx context.Context) error
- func Combine(errs ...error) error
- func Errors(err error) []error
- func Is(err error, code ErrorCode) bool
- func IsPermanent(err error) bool
- func IsTransient(err error) bool
- func Join(errs ...error) error
- func LogError(logger *zap.Logger, msg string, err error)
- func LogErrors(logger *zap.Logger, msg string, combined error)
- func Sentinel(text string) error
- func SplitCode(text string) (code, rest string, ok bool)
- func StdIs(err, target error) bool
- func ToHTTPStatus(code ErrorCode) int
- func Unwrap(err error) error
- func WithSink(ctx context.Context) context.Context
- func Wrap(err error, code ErrorCode, message string) error
- func ZapError(err error) zap.Field
- func ZapFields(err *AppError) []zap.Field
- type AppError
- func Conflict(message string) *AppError
- func Forbidden(message string) *AppError
- func Ingestion(message string) *AppError
- func Internal(message string) *AppError
- func InvalidInput(message string) *AppError
- func New(code ErrorCode, message string) *AppError
- func NotFound(message string) *AppError
- func QualityFailed(message string) *AppError
- func Timeout(message string) *AppError
- func Unauthorized(message string) *AppError
- func Unavailable(message string) *AppError
- func Upstream(message string) *AppError
- func WithDetails(err *AppError, details map[string]string) *AppError
- type ErrorCode
Constants ¶
const ( // CodeUnknown is the fallback code for errors that are not AppErrors or carry no code. CodeUnknown ErrorCode = "UNKNOWN" // CodeInternal marks an unexpected server-side failure. CodeInternal ErrorCode = "INTERNAL" // CodeNotFound marks a missing resource. CodeNotFound ErrorCode = "NOT_FOUND" CodeUnauthorized ErrorCode = "UNAUTHORIZED" // CodeForbidden marks an authenticated caller lacking permission for the action. CodeForbidden ErrorCode = "FORBIDDEN" // CodeInvalidInput marks a malformed or otherwise rejected request payload. CodeInvalidInput ErrorCode = "INVALID_INPUT" // CodeConflict marks a state conflict (e.g. a duplicate or concurrent modification). CodeConflict ErrorCode = "CONFLICT" // CodeTimeout marks an operation that exceeded its deadline. CodeTimeout ErrorCode = "TIMEOUT" // CodeCanceled marks an operation that was canceled by the caller. CodeCanceled ErrorCode = "CANCELED" CodeUnavailable ErrorCode = "UNAVAILABLE" // CodeIngestion marks a failure in the document ingestion pipeline. CodeIngestion ErrorCode = "INGESTION_ERROR" // CodeQualityFailed marks a failed quality gate. CodeQualityFailed ErrorCode = "QUALITY_FAILED" // CodeUpstream marks a failure originating in an upstream dependency. CodeUpstream ErrorCode = "UPSTREAM" // CodeResourceExhausted marks a request rejected because a quota or budget is // spent. It is neither transient (retrying before the window resets only burns // the quota check) nor permanent (the request succeeds once the window resets). CodeResourceExhausted ErrorCode = "RESOURCE_EXHAUSTED" // ErrUnknown aliases CodeUnknown. ErrUnknown = CodeUnknown // ErrInternal aliases CodeInternal. ErrInternal = CodeInternal // ErrNotFound aliases CodeNotFound. ErrNotFound = CodeNotFound ErrUnauthorized = CodeUnauthorized // ErrForbidden aliases CodeForbidden. ErrForbidden = CodeForbidden // ErrInvalidInput aliases CodeInvalidInput. ErrInvalidInput = CodeInvalidInput // ErrConflict aliases CodeConflict. ErrConflict = CodeConflict // ErrTimeout aliases CodeTimeout. ErrTimeout = CodeTimeout ErrUnavailable = CodeUnavailable // ErrIngestion aliases CodeIngestion. ErrIngestion = CodeIngestion // ErrQualityFailed aliases CodeQualityFailed. ErrQualityFailed = CodeQualityFailed )
Error codes.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Append appends right into left, returning the combined error. Either value may be nil, in which case the other is returned unchanged. It delegates to multierr.Append.
func As ¶
As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Re-export of errors.As.
func Capture ¶ added in v0.0.7
Capture records err as the real error for the current request when a sink is present. It is a no-op if no sink was installed, so callers need not know whether they run inside a request.
func Captured ¶ added in v0.0.7
Captured returns the real error recorded for the current request, or nil if none was captured (or no sink is installed).
func Combine ¶
Combine merges multiple errors into a single error. nil errors are discarded. If all errors are nil, it returns nil. It delegates to multierr.Combine.
func Errors ¶
Errors extracts individual errors from a combined error. If the error is not a combined error, returns a single-element slice.
func IsPermanent ¶
IsPermanent returns true if the error represents a permanent failure that will not succeed on retry (not found, invalid input, unauthorized, forbidden, conflict). CodeResourceExhausted is not permanent: the request succeeds once the quota window resets.
func IsTransient ¶
IsTransient returns true if the error represents a transient failure that may succeed on retry (timeout, unavailable). CodeResourceExhausted is deliberately not transient: a spent quota does not recover within a retry backoff, only when its window resets.
func Join ¶
Join returns an error that wraps the given errors. Any nil error values are discarded. Re-export of errors.Join.
func LogError ¶
LogError logs a single error with structured AppError fields. Transient errors (timeout, unavailable) are logged at Warn level. All other errors are logged at Error level.
func LogErrors ¶
LogErrors logs a combined multi-error, emitting one log entry per individual error. Each error is logged via LogError with its own structured fields.
func Sentinel ¶
Sentinel creates a simple sentinel error value with the given message. Use this instead of importing the standard "errors" package for errors.New. For application errors with error codes, use New() instead.
func SplitCode ¶ added in v0.0.19
SplitCode splits a coded error's text, AppError.Error()'s "<CODE>: <rest>" form, into the code and the rest. ok is false when text has no ": " separator or its prefix is not code-shaped, so an uncoded message is never mistaken for a coded one. It is the one parser for that form, shared by a display edge that drops the code and a caller that recovers it.
func StdIs ¶
StdIs reports whether any error in err's tree matches target. Re-export of errors.Is. Named StdIs to avoid collision with the package-level Is(err, ErrorCode) function.
func ToHTTPStatus ¶
ToHTTPStatus maps an ErrorCode to the corresponding HTTP status code.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err. Re-export of errors.Unwrap.
func WithSink ¶ added in v0.0.7
WithSink returns a context carrying a fresh error sink. The request-logging interceptor installs one at the start of every request.
Types ¶
type AppError ¶
type AppError struct {
// Err is the underlying wrapped error, if any.
Err error
// Details holds optional key-value context about the error.
Details map[string]string
// Code is the application-level error code.
Code ErrorCode
// Message is a human-readable description of the error.
Message string
// contains filtered or unexported fields
}
AppError represents an application error with code and context.
func InvalidInput ¶
InvalidInput creates an invalid input error.
func QualityFailed ¶
QualityFailed creates a quality gate failure error.
func Unauthorized ¶
Unauthorized creates an unauthorized error.
func Unavailable ¶
Unavailable creates an unavailable error.
func WithDetails ¶
WithDetails returns a copy of the error with additional details.
func (*AppError) MarshalLogObject ¶
func (e *AppError) MarshalLogObject(enc zapcore.ObjectEncoder) error
MarshalLogObject implements zapcore.ObjectMarshaler for AppError. Encodes code, message, the wrapped cause, the origin stack, and details (nested object). The cause and stack are what make a wrapped error diagnosable: without them, a generic "failed to query database" hides the real underlying failure (e.g. a Postgres "column does not exist").
func (*AppError) StackTrace ¶
StackTrace renders the captured origin stack as a newline-separated "func\n\tfile:line" trace, skipping the leading frames that belong to this errors package so the trace starts at the application code that created the error. Returns an empty string when no stack was captured.
type ErrorCode ¶
type ErrorCode string
ErrorCode represents application error codes.
func Code ¶
Code extracts the ErrorCode from an error. Returns CodeUnknown if the error is not an AppError.
func CodeOr ¶
CodeOr extracts err's ErrorCode like Code, but returns fallback when err carries no code (an uncoded third-party error, or nil). Use it to wrap a client error without discarding a code the client already chose.
func ContextCode ¶
ContextCode extracts err's ErrorCode like CodeOr, but first maps an uncoded context error in the chain: context.DeadlineExceeded to CodeTimeout and context.Canceled to CodeCanceled. Use it to wrap the error of a wait that a context ended (ctx.Err(), a library's deadline error) with the code that keeps retry classification and the transport status right.
Source Files