apperrors

Documentation

Overview

Package apperrors defines shared error codes and exit-code mapping.

Index

• func AllExitCodes() []int
• func Configure(next Options)
• func ExitCode(err error) int
• func WriteJSON(w io.Writer, err error) error
• type AppError
  • func AsAppError(err error) *AppError
  • func FromHTTP(statusCode int, message string) *AppError
  • func New(code ErrorCode, message string, cause error) *AppError
  • func (e *AppError) Error() string
  • func (e *AppError) MarshalJSON() ([]byte, error)
  • func (e *AppError) Unwrap() error
  • func (e *AppError) WithSuggestion(suggestion string) *AppError
• type Code
• type ErrorCause
• type ErrorCode
  • func AllCodes() []ErrorCode
• type Options

Functions

func AllExitCodes

func AllExitCodes() []int

AllExitCodes returns every possible process exit code, including success.

func Configure

func Configure(next Options)

Configure sets package-level error rendering defaults for a consumer CLI.

func ExitCode

func ExitCode(err error) int

ExitCode returns the process exit code for an error.

func WriteJSON

func WriteJSON(w io.Writer, err error) error

WriteJSON writes a standard JSON error object.

Types

type AppError

type AppError struct {
	Code            ErrorCode   `json:"code"`
	Message         string      `json:"message"`
	Suggestion      string      `json:"suggestion,omitempty"`
	Cause           string      `json:"cause,omitempty"`
	StructuredCause *ErrorCause `json:"-"`
	HTTPStatus      int         `json:"-"`
	Retryable       bool        `json:"-"`
	Err             error       `json:"-"`
}

AppError carries structured error information for humans and JSON consumers.

func AsAppError

func AsAppError(err error) *AppError

AsAppError converts arbitrary errors to AppError.

func FromHTTP

func FromHTTP(statusCode int, message string) *AppError

FromHTTP maps an HTTP status to a structured AppError.

func New

func New(code ErrorCode, message string, cause error) *AppError

New creates an AppError.

func (*AppError) Error

func (e *AppError) Error() string

Error returns the human-readable message with wrapped cause when present.

func (*AppError) MarshalJSON

func (e *AppError) MarshalJSON() ([]byte, error)

MarshalJSON writes the stable public error shape. StructuredCause lets tools that need diagnostic subfields emit the same "cause" key without changing the string Cause field used by existing consumers.

func (*AppError) Unwrap

func (e *AppError) Unwrap() error

Unwrap returns the underlying cause.

func (*AppError) WithSuggestion

func (e *AppError) WithSuggestion(suggestion string) *AppError

WithSuggestion overrides the default recovery hint.

type Code

type Code = ErrorCode

Code is kept as a short alias for consumers that name error codes tersely.

type ErrorCause

type ErrorCause struct {
	Layer  string `json:"layer"`
	Detail string `json:"detail"`
}

ErrorCause is diagnostic-only. Machine consumers MUST use Code, not Cause.

type ErrorCode

type ErrorCode string

ErrorCode is a stable machine-readable error code.

const (
	CodeUsageError             ErrorCode = "USAGE_ERROR"
	CodeNetworkError           ErrorCode = "NETWORK_ERROR"
	CodeAuthFailed             ErrorCode = "AUTH_FAILED"
	CodeResourceNotFound       ErrorCode = "RESOURCE_NOT_FOUND"
	CodeResourceAlreadyExists  ErrorCode = "RESOURCE_ALREADY_EXISTS"
	CodeLocalIOError           ErrorCode = "LOCAL_IO_ERROR"
	CodeServerError            ErrorCode = "SERVER_ERROR"
	CodeBackendUnreachable     ErrorCode = "BACKEND_UNREACHABLE"
	CodeBackendError           ErrorCode = "BACKEND_ERROR"
	CodeAuthorizationRequired  ErrorCode = "AUTHORIZATION_REQUIRED"
	CodeValidationFailed       ErrorCode = "VALIDATION_FAILED"
	CodeConflict               ErrorCode = "CONFLICT"
	CodePartialFailure         ErrorCode = "PARTIAL_FAILURE"
	CodeNoChangeRequired       ErrorCode = "NO_CHANGE_REQUIRED"
	CodeUnsupportedProtocol    ErrorCode = "UNSUPPORTED_PROTOCOL"
	CodeNotImplemented         ErrorCode = "NOT_IMPLEMENTED"
	CodeCredentialStoreError   ErrorCode = "CREDENTIAL_STORE_ERROR"   //nolint:gosec // Error code constant, not a credential.
	CodeCredentialStoreMissing ErrorCode = "CREDENTIAL_STORE_MISSING" //nolint:gosec // Error code constant, not a credential.
)

func AllCodes

func AllCodes() []ErrorCode

AllCodes returns all defined error codes in declaration order.

type Options

type Options struct {
	APIVersion                 string
	Suggestions                map[ErrorCode]string
	Codes                      []ErrorCode
	ResourceNotFoundSubstrings []string
}

Options configures package-level error rendering defaults.