Documentation
¶
Overview ¶
Package errors provides shared sentinel errors and gRPC mapping for paper-board services. All public service errors should wrap one of these sentinels so callers can use errors.Is for routing.
Index ¶
- Variables
- func As(err error, target any) bool
- func CodeString(err error) string
- func FromGRPCStatus(err error) error
- func Is(err, target error) bool
- func IsPermanent(err error) bool
- func IsRetryable(err error) bool
- func Kind(err error) string
- func Message(err error) string
- func ToGRPCStatus(err error) error
- func ToHTTPStatus(err error) int
- func Unwrap(err error) error
- func Wrap(sentinel error, msg string, kvs ...any) error
- type Classification
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("not found") ErrConflict = errors.New("conflict") ErrPermissionDenied = errors.New("permission denied") ErrInvalidInput = errors.New("invalid input") ErrRateLimited = errors.New("rate limited") ErrInternal = errors.New("internal error") )
Sentinel errors.
Functions ¶
func CodeString ¶ added in v0.5.0
CodeString returns the canonical UPPERCASE gRPC code string for use in event payloads (e.g. "UNAVAILABLE"). Returns "" for non-gRPC errors. "OK" is never returned — the success path is err == nil.
func FromGRPCStatus ¶
FromGRPCStatus converts a gRPC status error back to a wrapped sentinel. Useful in client code to use errors.Is across the wire.
func IsPermanent ¶ added in v0.5.0
IsPermanent returns true iff ClassifyGRPC(err) == ClassificationPermanent.
func IsRetryable ¶ added in v0.5.0
IsRetryable returns true iff ClassifyGRPC(err) == ClassificationRetryable.
func Kind ¶ added in v0.2.0
Kind returns a snake_case slug identifying the sentinel an error wraps. Used by sdk/httpmw to derive HTTP error codes ("<svc>.<kind>") and by sdk/log.ErrorAttrs to populate the "error.kind" attribute.
Returns "internal" for nil-wrapped or unknown errors so callers do not need to pre-classify.
func Message ¶ added in v0.2.0
Message returns the canonical user-facing message for the sentinel an error wraps. Mirrors Kind. Use for HTTP error envelopes; the wrapped chain detail goes only to logs (avoid leaking internal context to clients).
func ToGRPCStatus ¶
ToGRPCStatus maps a wrapped sentinel error to a gRPC status. Used by service handlers to convert internal errors into RPC responses.
if err := repo.Get(ctx, id); err != nil {
return nil, errors.ToGRPCStatus(err)
}
func ToHTTPStatus ¶ added in v0.1.2
ToHTTPStatus maps a wrapped sentinel error to an HTTP status code. Used by sdk/httpmw.HandleErr as the central HTTP error boundary.
Mapping:
ErrNotFound → 404 ErrConflict → 409 ErrUnauthorized → 401 ErrPermissionDenied → 403 ErrInvalidInput → 400 ErrRateLimited → 429 ErrUnavailable → 503 ErrInternal → 500 nil or unknown → 500
Example:
if err := repo.Get(ctx, id); err != nil {
http.Error(w, err.Error(), errors.ToHTTPStatus(err))
return
}
Types ¶
type Classification ¶ added in v0.5.0
type Classification int
Classification categorises a gRPC error for retry decisions.
const ( // ClassificationUnknown is returned when the error is not a gRPC status // or when err is nil. sdk/retry treats Unknown as Permanent (fail-loud). ClassificationUnknown Classification = iota // ClassificationRetryable indicates the operation may succeed on retry. ClassificationRetryable // ClassificationPermanent indicates the operation will not succeed on retry. ClassificationPermanent )
func ClassifyGRPC ¶ added in v0.5.0
func ClassifyGRPC(err error) Classification
ClassifyGRPC inspects err for a wrapped gRPC status (errors.As walk, up to 3 levels). Non-gRPC errors return ClassificationUnknown. nil returns ClassificationUnknown (callers should branch on err != nil first).
Source Files