apperr

Documentation

Overview

Package apperr is Gortexa's central error model. A single table of Mapping rows is the one source of truth that drives all three transports: gRPC status codes, HTTP status codes (for the grpc-gateway error handler), and MCP tool-call error envelopes. Domain code constructs *Error values with a Category; the adapters translate them per transport. A hard invariant holds everywhere: an Internal error (or any non-*Error) never serializes its underlying cause — only the category's SafeMessage is exposed.

Index

• Variables
• func Is(err error, cat Category) bool
• func Register(m Mapping)
• func ToGRPCStatus(err error) *status.Status
• type Category
• type Error
  • func New(cat Category, msg string) *Error
  • func Wrap(cat Category, msg string, cause error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Fields() map[string]any
  • func (e *Error) GRPCStatus() *status.Status
  • func (e *Error) Unwrap() error
  • func (e *Error) With(key string, val any) *Error
• type ErrorBody
  • func ToHTTP(err error) (int, ErrorBody)
• type MCPError
  • func ToMCP(err error) MCPError
• type Mapping
  • func DefaultMappings() []Mapping
  • func Lookup(c Category) (Mapping, bool)
• type Registry
  • func NewRegistry(seed ...Mapping) *Registry
  • func (r *Registry) Lookup(c Category) (Mapping, bool)
  • func (r *Registry) Register(m Mapping)
  • func (r *Registry) ToGRPCStatus(err error) *status.Status
  • func (r *Registry) ToHTTP(err error) (int, ErrorBody)
  • func (r *Registry) ToMCP(err error) MCPError

Variables

var Default = NewRegistry(DefaultMappings()...)

Default is the process-wide registry seeded with DefaultMappings.

Functions

func Is

func Is(err error, cat Category) bool

Is reports whether err is an *Error with the given category.

func Register

func Register(m Mapping)

func ToGRPCStatus

func ToGRPCStatus(err error) *status.Status

Types

type Category

type Category string

Category is a transport-agnostic error class.

const (
	CatInvalidArgument    Category = "invalid_argument"
	CatUnauthenticated    Category = "unauthenticated"
	CatPermissionDenied   Category = "permission_denied"
	CatNotFound           Category = "not_found"
	CatAlreadyExists      Category = "already_exists"
	CatResourceExhausted  Category = "resource_exhausted"
	CatFailedPrecondition Category = "failed_precondition"
	CatAborted            Category = "aborted"
	CatDeadlineExceeded   Category = "deadline_exceeded"
	CatUnavailable        Category = "unavailable"
	CatUnimplemented      Category = "unimplemented"
	CatInternal           Category = "internal"
	CatCanceled           Category = "canceled"
	CatOutOfRange         Category = "out_of_range"
	CatDataLoss           Category = "data_loss"
)

type Error

type Error struct {
	Category Category
	Msg      string
	// contains filtered or unexported fields
}

Error is a domain error carrying a Category, a client-safe message and an optional wrapped cause (never exposed for Internal).

func New

func New(cat Category, msg string) *Error

New creates an Error with no cause.

func Wrap

func Wrap(cat Category, msg string, cause error) *Error

Wrap creates an Error wrapping cause.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Fields

func (e *Error) Fields() map[string]any

Fields returns the attached structured fields.

func (*Error) GRPCStatus

func (e *Error) GRPCStatus() *status.Status

GRPCStatus lets *Error satisfy the gRPC status interface so handlers may return it directly. Uses the default registry.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap exposes the cause to errors.Is/As.

func (*Error) With

func (e *Error) With(key string, val any) *Error

With attaches a structured field (for logging, never serialized to clients).

type ErrorBody

type ErrorBody struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id,omitempty"`
}

ErrorBody is the JSON body emitted by the HTTP gateway error handler.

func ToHTTP

func ToHTTP(err error) (int, ErrorBody)

type MCPError

type MCPError struct {
	IsError       bool   `json:"isError"`
	ErrorCategory string `json:"errorCategory"`
	IsRetryable   bool   `json:"isRetryable"`
	Message       string `json:"message"`
}

MCPError is embedded in an MCP tools/call result on failure.

func ToMCP

func ToMCP(err error) MCPError

type Mapping

type Mapping struct {
	Category    Category
	GRPCCode    codes.Code
	HTTPStatus  int
	Retryable   bool
	SafeMessage string
}

Mapping is one row of the error table.

func DefaultMappings

func DefaultMappings() []Mapping

DefaultMappings returns the seed error table.

func Lookup

func Lookup(c Category) (Mapping, bool)

type Registry

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

Registry maps categories to transport codes. Safe for concurrent use.

func NewRegistry

func NewRegistry(seed ...Mapping) *Registry

NewRegistry builds a registry seeded with the given mappings.

func (*Registry) Lookup

func (r *Registry) Lookup(c Category) (Mapping, bool)

Lookup returns the mapping for a category.

func (*Registry) Register

func (r *Registry) Register(m Mapping)

Register adds a mapping, panicking (fail-loud at startup) on a duplicate category or a duplicate gRPC code. Code uniqueness matters because a pre-built gRPC status arriving over the loopback is resolved back to a category by its code (resolve's byCode passthrough); two categories sharing a code would make that reverse mapping ambiguous, so it is rejected at registration.

func (*Registry) ToGRPCStatus

func (r *Registry) ToGRPCStatus(err error) *status.Status

ToGRPCStatus maps any error to a gRPC status. A nil error maps to OK.

func (*Registry) ToHTTP

func (r *Registry) ToHTTP(err error) (int, ErrorBody)

ToHTTP maps any error to an HTTP status and a client-safe body.

func (*Registry) ToMCP

func (r *Registry) ToMCP(err error) MCPError

ToMCP maps any error to an MCP tool-call error envelope.