go/xerrors
1
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity

1 Release 1 Tag

RSS Feed
  • v0.9.0 3cc36801a1
    Compare

    Release v0.9.0 Stable

    Rene Nochebuena released this 2026-03-18 13:12:17 -06:00 | 0 commits to main since this release

    v0.9.0

    code.nochebuena.dev/go/xerrors

    Overview

    xerrors provides a single structured error type — *Err — that carries a typed machine-readable Code, a human-readable message, an optional cause, and optional key-value context fields. It replaces ad-hoc string errors and sentinel variables with a consistent, JSON-serialisable error model that works uniformly across service boundaries, log pipelines, and HTTP transport layers. Error codes are stable wire values aligned with gRPC canonical status names, so they remain meaningful regardless of the transport protocol in use.

    What's Included

    • Code — string type alias for machine-readable error categories
    • ErrInvalidInput, ErrUnauthorized, ErrPermissionDenied, ErrNotFound, ErrAlreadyExists, ErrGone, ErrPreconditionFailed, ErrRateLimited, ErrCancelled, ErrInternal, ErrNotImplemented, ErrUnavailable, ErrDeadlineExceeded — twelve typed code constants
    • Code.Description() — human-readable description for each code
    • *Err — structured error type implementing error, errors.Unwrap, json.Marshaler, ErrorCode(), and ErrorContext()
    • New(code, message) — primary factory constructor
    • Wrap(code, message, cause) — factory constructor that wraps an existing error as the cause
    • InvalidInput(msg, args...), NotFound(msg, args...), Internal(msg, args...) — convenience constructors for the three most common codes
    • (*Err).WithContext(key, value) — builder method to attach a key-value field; chainable
    • (*Err).WithError(err) — builder method to set or replace the cause; chainable
    • (*Err).Code() — returns the typed Code
    • (*Err).Message() — returns the human-readable message string
    • (*Err).Fields() — returns a safe shallow copy of all attached context fields
    • (*Err).Detailed() — returns a verbose debug string including code, message, cause, and fields
    • (*Err).ErrorCode() — duck-type bridge satisfying logz's internal errorWithCode interface
    • (*Err).ErrorContext() — duck-type bridge satisfying logz's internal errorWithContext interface
    • (*Err).MarshalJSON() — JSON output as {"code":"...","message":"...","fields":{...}}

    Installation

    require code.nochebuena.dev/go/xerrors v0.9.0

    Design Highlights

    • Error codes are string type aliases with stable wire values matching gRPC canonical status names, making them safe to serialize, store, and compare across service versions (see docs/adr/ADR-001-typed-error-codes.md).
    • *Err implements errors.Unwrap, enabling full stdlib errors.Is / errors.As cause-chain traversal without any custom helpers (see docs/adr/ADR-002-stdlib-errors-compatibility.md).
    • The logz integration is zero-import: ErrorCode() and ErrorContext() satisfy private duck-typed interfaces inside logz, so passing an *Err to logger.Error automatically enriches the log record with error_code and context fields — without xerrors importing logz.
    • HTTP status mapping is deliberately excluded; that responsibility belongs to the transport layer, keeping this package dependency-free and protocol-agnostic.

    Known Limitations & Edge Cases

    • errors.As on a cause chain stops at the first *Err it encounters — if multiple *Err values are nested, only the outermost one's fields are surfaced in a single As call.
    • ErrorContext() returns the live internal fields map. Callers who receive an *Err and mutate the map returned by ErrorContext() will corrupt the error's state. Use Fields() for a safe copy.
    • Convenience constructors (InvalidInput, NotFound, Internal) cover only three of the twelve codes. Other codes require New or Wrap directly.
    • There is no HTTP status code mapping in this package. Applications must maintain their own Code → HTTP status table at the transport layer.
    • WithContext silently overwrites a field if the same key is set twice; no warning or error is produced.

    v0.9.0 → v1.0.0 Roadmap

    • Validate that all twelve codes have been exercised in at least one production service and that the mapping to HTTP status codes is stable and documented.
    • Consider adding a Codes registry or lookup helper so transport layers can map Code → HTTP status without each service maintaining its own switch statement.
    • Evaluate whether additional convenience constructors (e.g. PermissionDenied, Unauthorized) would reduce boilerplate enough to justify the addition.
    • Confirm that ErrorContext() returning the live map is acceptable in all log-enrichment paths, or document that it must be treated as read-only by callers.
    • Achieve production validation of the duck-type logz bridge under concurrent load.

    v0.9.0 rationale: The API is stable and intentional — designed through multiple architecture reviews and tested end-to-end via the todo-api POC (SQLite, RBAC, middleware stack, HTTP handlers). The module is not yet battle-tested in production for all edge cases, and the pre-1.0 designation preserves the option for minor API refinements based on real-world use.

    Downloads