xerr

Documentation

Overview

Package xerr defines categorized errors with stable kinds for transport and application boundaries. Callers can inspect the category while preserving the underlying cause.

Index

• Constants
• func ErrChain(err error) []error
• func IsDev() bool
• func IsTransient(err error) bool
• func MapTransportError(err error) error
• func Print(err error)
• func Sprint(err error) string
• type AppError
  • func BadRequest(msg string, cause ...error) *AppError
  • func Canceled(msg string, cause ...error) *AppError
  • func CircuitBreaker(msg string, cause ...error) *AppError
  • func Conflict(msg string, cause ...error) *AppError
  • func Database(msg string, cause ...error) *AppError
  • func Forbidden(msg string, cause ...error) *AppError
  • func From(err error) *AppError
  • func FromPublic(response ErrorResponse) (*AppError, bool)
  • func Internal(msg string, cause ...error) *AppError
  • func MethodNotAllowed(msg string, cause ...error) *AppError
  • func NotFound(msg string, cause ...error) *AppError
  • func PanicRecovery(recovered any) *AppError
  • func RateLimit(msg string, cause ...error) *AppError
  • func ServiceUnavailable(msg string, cause ...error) *AppError
  • func Shutdown(msg string, cause ...error) *AppError
  • func Timeout(msg string, cause ...error) *AppError
  • func TooManyRequests(msg string, cause ...error) *AppError
  • func Unauthorized(msg string, cause ...error) *AppError
  • func Unavailable(msg string, cause ...error) *AppError
  • func Validation(msg string, cause ...error) *AppError
  • func (e *AppError) Error() string
  • func (e *AppError) IsTransient() bool
  • func (e *AppError) Public(reqID string) ErrorResponse
  • func (e *AppError) Unwrap() error
  • func (e *AppError) WithStack() *AppError
• type ErrorResponse
• type Kind
  • func AllKinds() []Kind
  • func KindFrom(err error) Kind
• type ValidationDetail
  • func (v ValidationDetail) String() string
• type ValidationDetails

Constants

const RemoteErrorHeader = "Nexss-Error"

RemoteErrorHeader marks a transport reply whose payload is an ErrorResponse. It is intentionally transport-neutral so all adapters share one safe-error contract.

Functions

func ErrChain

func ErrChain(err error) []error

ErrChain walks errors.Unwrap and returns the full cause chain as a slice.

func IsDev

func IsDev() bool

func IsTransient

func IsTransient(err error) bool

IsTransient is the package-level predicate used by retry and circuit-breaker logic.

func MapTransportError

func MapTransportError(err error) error

MapTransportError converts raw transport/network errors into the xerr taxonomy. Call this at every adapter boundary (HTTP, NATS, gRPC).

func Print

func Print(err error)

Print writes Sprint(err) to stderr.

func Sprint

func Sprint(err error) string

Sprint returns a formatted error string.

• Dev: full cause chain + resolved stack frames (file:line)
• Prod: kind + top-level message only — nothing internal leaks

Types

type AppError

type AppError struct {
	Kind              Kind
	Message           string
	Cause             error
	Stack             []uintptr
	ValidationDetails ValidationDetails
}

AppError is the single error type for all application errors.

func BadRequest

func BadRequest(msg string, cause ...error) *AppError

func Canceled

func Canceled(msg string, cause ...error) *AppError

func CircuitBreaker

func CircuitBreaker(msg string, cause ...error) *AppError

func Conflict

func Conflict(msg string, cause ...error) *AppError

func Database

func Database(msg string, cause ...error) *AppError

func Forbidden

func Forbidden(msg string, cause ...error) *AppError

func From

func From(err error) *AppError

From converts any error into an AppError. Never returns nil if err != nil.

func FromPublic

func FromPublic(response ErrorResponse) (*AppError, bool)

FromPublic reconstructs a safe AppError from an ErrorResponse received over a trusted transport boundary. It never restores a remote cause or stack trace. The bool is false when the response does not contain a recognized Nexss kind.

func Internal

func Internal(msg string, cause ...error) *AppError

Internal captures a stack trace — use only for unexpected bugs.

func MethodNotAllowed

func MethodNotAllowed(msg string, cause ...error) *AppError

func NotFound

func NotFound(msg string, cause ...error) *AppError

func PanicRecovery

func PanicRecovery(recovered any) *AppError

PanicRecovery wraps a recovered panic value as an Internal error with stack trace.

func RateLimit

func RateLimit(msg string, cause ...error) *AppError

func ServiceUnavailable

func ServiceUnavailable(msg string, cause ...error) *AppError

func Shutdown

func Shutdown(msg string, cause ...error) *AppError

func Timeout

func Timeout(msg string, cause ...error) *AppError

func TooManyRequests

func TooManyRequests(msg string, cause ...error) *AppError

func Unauthorized

func Unauthorized(msg string, cause ...error) *AppError

func Unavailable

func Unavailable(msg string, cause ...error) *AppError

func Validation

func Validation(msg string, cause ...error) *AppError

Validation creates a typed validation error with structured details.

func (*AppError) Error

func (e *AppError) Error() string

func (*AppError) IsTransient

func (e *AppError) IsTransient() bool

IsTransient reports whether the error may succeed on retry. Used by RetryMiddleware and circuit breakers.

func (*AppError) Public

func (e *AppError) Public(reqID string) ErrorResponse

Public returns a safe, client-facing representation. Internal details never leak.

func (*AppError) Unwrap

func (e *AppError) Unwrap() error

func (*AppError) WithStack

func (e *AppError) WithStack() *AppError

WithStack re-captures the stack. Use for bugs / unexpected internal errors.

type ErrorResponse

type ErrorResponse struct {
	Error     string            `json:"error"`
	Message   string            `json:"message"`
	RequestID string            `json:"request_id,omitempty"`
	Details   ValidationDetails `json:"details,omitempty"`
}

ErrorResponse is the public contract sent to clients — never expose internals.

type Kind

type Kind string

Kind is the machine-readable error category.

const (
	KindBadRequest      Kind = "BadRequest"
	KindUnauthorized    Kind = "Unauthorized"
	KindForbidden       Kind = "Forbidden"
	KindNotFound        Kind = "NotFound"
	KindConflict        Kind = "Conflict"
	KindValidation      Kind = "Validation"
	KindTooManyRequests Kind = "TooManyRequests"
	KindTimeout         Kind = "Timeout"
	KindUnavailable     Kind = "Unavailable"
	KindInternal        Kind = "Internal"

	// Extended kinds
	KindMethodNotAllowed Kind = "MethodNotAllowed"
	KindRateLimit        Kind = "RateLimit"
	KindCanceled         Kind = "Canceled"
	KindDatabase         Kind = "Database"
	KindShutdown         Kind = "Shutdown"
	KindCircuitBreaker   Kind = "CircuitBreaker"
)

func AllKinds

func AllKinds() []Kind

func KindFrom

func KindFrom(err error) Kind

KindFrom extracts the Kind from an error. Defaults to KindInternal if the error is not an AppError.

type ValidationDetail

type ValidationDetail struct {
	Field      string `json:"field"`
	Validation string `json:"validation"`
	Value      string `json:"value,omitempty"`
}

ValidationDetail describes a single field validation failure.

func (ValidationDetail) String

func (v ValidationDetail) String() string

type ValidationDetails

type ValidationDetails []ValidationDetail