errors

Documentation

Overview

Package errors defines errors that can be transported safely across service boundaries without exposing their internal causes.

Index

• Constants
• func PublicValues(err error) (code int, message string, httpStatus int)
• type Catalog
  • func MergeCatalogs(catalogs ...*Catalog) (*Catalog, error)
  • func MustCatalog(definitions ...Definition) *Catalog
  • func MustMergeCatalogs(catalogs ...*Catalog) *Catalog
  • func NewCatalog(definitions ...Definition) (*Catalog, error)
  • func (c *Catalog) Definitions() []Definition
  • func (c *Catalog) FromCode(code int, message string) *Error
  • func (c *Catalog) HTTPStatus(code int) int
  • func (c *Catalog) LookupCode(code int) (Definition, bool)
  • func (c *Catalog) LookupName(name string) (Definition, bool)
• type Definition
  • func Define(code int, name, message string, httpStatus int) Definition
  • func (d Definition) Code() int
  • func (d Definition) HTTPStatus() int
  • func (d Definition) Message() string
  • func (d Definition) Name() string
  • func (d Definition) New() *Error
  • func (d Definition) Wrap(cause error) *Error
• type Error
  • func New(code int, message string, opts ...Option) *Error
  • func Wrap(cause error, code int, message string, opts ...Option) *Error
  • func (e *Error) Code() int
  • func (e *Error) Error() string
  • func (e *Error) HTTPStatus() int
  • func (e *Error) Message() string
  • func (e *Error) Unwrap() error
• type Option
  • func WithHTTPStatus(status int) Option

Constants

const (
	CodeOK              = 0
	CodeInvalidArgument = 10001
	CodeInternal        = 90001
	CodeTimeout         = 90002
	// CodeMax is the largest business code representable by JGO's standard
	// protobuf int32 response field.
	CodeMax = 1<<31 - 1
)

const (
	MessageInternal = "internal server error"
	MessageTimeout  = "request timeout"
)

Functions

func PublicValues

func PublicValues(err error) (code int, message string, httpStatus int)

PublicValues extracts client-safe values. Unknown errors always become a generic internal error, so their text cannot leak into API responses.

Types

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog validates and resolves a finite set of business error codes.

func MergeCatalogs

func MergeCatalogs(catalogs ...*Catalog) (*Catalog, error)

MergeCatalogs builds one process catalog from service-local and shared catalogs. Duplicate codes or names across module/repository boundaries are rejected by the same rules as NewCatalog.

func MustCatalog

func MustCatalog(definitions ...Definition) *Catalog

func MustMergeCatalogs

func MustMergeCatalogs(catalogs ...*Catalog) *Catalog

func NewCatalog

func NewCatalog(definitions ...Definition) (*Catalog, error)

func (*Catalog) Definitions

func (c *Catalog) Definitions() []Definition

Definitions returns a stable copy suitable for governance tooling and composing catalogs supplied by shared Go modules.

func (*Catalog) FromCode

func (c *Catalog) FromCode(code int, message string) *Error

FromCode converts a downstream RPC business code into an HTTP-aware Error. Unknown codes preserve their public code/message but deliberately map to 500.

func (*Catalog) HTTPStatus

func (c *Catalog) HTTPStatus(code int) int

HTTPStatus returns 500 for unknown codes so unmapped downstream business failures never masquerade as a successful HTTP response.

func (*Catalog) LookupCode

func (c *Catalog) LookupCode(code int) (Definition, bool)

func (*Catalog) LookupName

func (c *Catalog) LookupName(name string) (Definition, bool)

type Definition

type Definition struct {
	// contains filtered or unexported fields
}

Definition is one stable, transport-safe business error declaration.

func Define

func Define(code int, name, message string, httpStatus int) Definition

func (Definition) Code

func (d Definition) Code() int

func (Definition) HTTPStatus

func (d Definition) HTTPStatus() int

func (Definition) Message

func (d Definition) Message() string

func (Definition) Name

func (d Definition) Name() string

func (Definition) New

func (d Definition) New() *Error

func (Definition) Wrap

func (d Definition) Wrap(cause error) *Error

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is a public service error with an optional private cause.

func New

func New(code int, message string, opts ...Option) *Error

New creates a service error. Invalid public fields are replaced by safe internal-error defaults.

func Wrap

func Wrap(cause error, code int, message string, opts ...Option) *Error

Wrap creates a service error while preserving an internal cause for logs and errors.Is/errors.As. The cause is never returned by MessageOf.

func (*Error) Code

func (e *Error) Code() int

Code returns the public business error code.

func (*Error) Error

func (e *Error) Error() string

func (*Error) HTTPStatus

func (e *Error) HTTPStatus() int

HTTPStatus returns the HTTP status associated with the error.

func (*Error) Message

func (e *Error) Message() string

Message returns the public, client-safe message.

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Option

type Option func(*Error)

Option configures a service Error.

func WithHTTPStatus

func WithHTTPStatus(status int) Option

WithHTTPStatus associates an HTTP status with a service error.