Documentation
¶
Overview ¶
Package errors defines the framework-wide error model: ErrorCode enum, the Error interface, constructor helpers, and HTTP status mapping.
Every exported function in the orjanda framework that can fail must return a value implementing errors.Error (or wrap one via Unwrap()).
See TAD §1.1 for the full contract.
Index ¶
- Variables
- func As(err error, target *Error) bool
- func Is(err, target error) bool
- type Error
- func Auth(message string) Error
- func Conflict(message string) Error
- func Internal(message string, cause error) Error
- func New(code ErrorCode, message string, details map[string]any, cause error) Error
- func NotFound(message string) Error
- func Permission(message string) Error
- func Validation(message string, details map[string]any) Error
- func Wrap(code ErrorCode, message string, cause error) Error
- type ErrorCode
Constants ¶
This section is empty.
Variables ¶
var ( ErrValidation = &orjandaError{code: CodeValidation} ErrAuth = &orjandaError{code: CodeAuth} ErrPermission = &orjandaError{code: CodePermission} ErrNotFound = &orjandaError{code: CodeNotFound} ErrConflict = &orjandaError{code: CodeConflict} ErrInternal = &orjandaError{code: CodeInternal} )
Functions ¶
Types ¶
type Error ¶
type Error interface {
error // Error() string — human-readable, safe for logs.
// Code returns the stable ErrorCode category.
Code() ErrorCode
// Message returns a human- and LLM-safe description of the failure.
// It MUST NOT expose raw system internals (stack traces, SQL, DSNs).
Message() string
// Details returns structured supplementary information, e.g. per-field
// validation failures: {"email": "invalid format", "name": "required"}.
// May be nil when there is no additional context.
Details() map[string]any
// Unwrap returns the original underlying error for errors.As/Is chaining.
// May be nil when this error was not wrapping another.
Unwrap() error
}
Error is the framework-wide error interface. Every exported Orjanda function that can fail must return a value implementing Error (or wrap one via Unwrap so that errors.As/Is traversal still reaches an Error). See TAD §1.1.
func Internal ¶
Internal returns a CodeInternal error, wrapping the underlying cause. The message MUST be a generic, safe string — do not include raw cause details.
func New ¶
New constructs a bare errors.Error with code, message, optional details map, and an optional underlying cause. Prefer the named constructors below.
func Validation ¶
Validation returns a CodeValidation error. details may be nil.
type ErrorCode ¶
type ErrorCode string
ErrorCode is a stable, machine-readable identifier for an error category. Every exported Orjanda function that can fail returns an errors.Error whose Code() is one of the six values below. No package may introduce additional codes for conditions these six already cover. See TAD §1.1.
const ( // CodeValidation maps to HTTP 400. Used for schema violations (required // fields, format checks, uniqueness conflicts that are caught before the // DB write), invalid query parameters, and malformed request payloads. CodeValidation ErrorCode = "VALIDATION_ERROR" // CodeAuth maps to HTTP 401. Used when the caller supplies a missing, // expired, or cryptographically invalid authentication credential. CodeAuth ErrorCode = "AUTH_ERROR" // CodePermission maps to HTTP 403. Used when the caller's identity is // recognised but lacks the required role or rule for the requested action. // Must be returned by perm.Engine before any DAL call is made (PRD §25.1). CodePermission ErrorCode = "PERMISSION_DENIED" // CodeNotFound maps to HTTP 404. Used when a requested Document ID or // DocType does not exist in the Registry or database. CodeNotFound ErrorCode = "NOT_FOUND" // CodeConflict maps to HTTP 409. Used for optimistic-locking failures, // duplicate unique-field violations caught at the DB layer, and invalid // workflow transitions from the current state (TAD §8.1 step 2). CodeConflict ErrorCode = "CONFLICT" // CodeInternal maps to HTTP 500. Used for unexpected infrastructure // failures: DB connectivity, internal invariant violations, etc. // The Message() must never expose raw system details to end-users or LLMs. CodeInternal ErrorCode = "INTERNAL_ERROR" )
func (ErrorCode) HTTPStatus ¶
HTTPStatus returns the HTTP status code that corresponds to c. This is the canonical mapping table used by the API layer (Phase 6) and documented in TAD §1.1.
Source Files