mapper

Documentation

Overview

Package mapper provides deterministic, immutable mappings from logical derrors codes (dirpx.dev/derrors/code) and optional reasons (dirpx.dev/derrors/reason) to transport-level statuses for HTTP and gRPC.

Overview

In dirpx errors are expressed in two parts:

1. a high-level Code (e.g. code.Unavailable, code.Invalid),
2. an optional, more specific Reason (e.g. "storage.pg.connect_timeout").

Transport layers (HTTP handlers, REST gateways, gRPC servers) need to turn this pair into concrete status codes. Package mapping does that in a way that is:

• immutable — a Mapper is a snapshot, safe for concurrent reuse;
• overridable — callers can change library defaults per Code;
• prefix-aware — callers can add fine-grained rules for specific reasons;
• dual — HTTP and gRPC are resolved with the same logic.

Resolution model

A Mapper resolves statuses in the following order:

1. exact override for the Code;
2. per-Code longest-prefix-match (LPM) on the Reason;
3. per-Code default (library or user-adjusted);
4. global fallback (500 / codes.Internal).

Prefix rules are segment-aware: reasons are treated as "."-separated segments, and "*" matches exactly one segment. For example:

WithHTTPPrefix(code.Unavailable, "storage.pg", http.StatusServiceUnavailable)
WithHTTPPrefix(code.Unavailable, "storage.*.connect", http.StatusServiceUnavailable)

The more specific prefix wins.

Library defaults

The package ships with sensible defaults for common dirpx codes, mapping them to standard net/http constants and grpc/codes values (e.g. code.Invalid -> 400 / InvalidArgument, code.Unauthenticated -> 401 / Unauthenticated, code.Unavailable -> 503 / Unavailable). These can be adjusted at build time.

Building a mapper

A Mapper is created once and reused:

m, err := mapping.New(
    mapping.WithHTTPOverride(code.Canceled, 499),           // nginx-style
    mapping.WithHTTPPrefix(code.Unavailable, "storage.pg", 503),
)
if err != nil {
    // invalid prefix, etc.
}

st := m.Status(code.Unavailable, reason.Of("storage.pg.connect_timeout"))
// st.HTTP == 503, st.GRPC == codes.Unavailable

Diagnostics

For debugging and tests, Mapper.Explain returns a human-readable trace of how a particular (code, reason) was resolved, including which tier matched and, for prefixes, which pattern was used.

This is intended for inspection and logging, not for stable machine parsing.

Immutability

All user-provided inputs are copied during New. After construction, the Mapper does not observe further changes to the caller's maps or slices. This makes it safe to share a single instance across handlers, goroutines, and requests.

Index

• func New(opts ...Option) (apis.Mapper, error)
• type Option
  • func WithGRPCDefault(c code.Code, grpc int) Option
  • func WithGRPCOverride(c code.Code, grpc int) Option
  • func WithGRPCPrefix(c code.Code, prefix string, grpc int) Option
  • func WithHTTPDefault(c code.Code, http int) Option
  • func WithHTTPOverride(c code.Code, http int) Option
  • func WithHTTPPrefix(c code.Code, prefix string, http int) Option

Functions

func New

func New(opts ...Option) (apis.Mapper, error)

New constructs an immutable apis.Mapper snapshot.

The resulting apis.Mapper is fully thread-safe and designed for long-lived reuse. Each build creates a self-contained mapper instance — no shared references to global state or user-provided structures remain.

Build process overview:

1. Seed the builder with library defaults (HTTP & gRPC).
2. Apply user-provided options (defaults, overrides, prefix rules).
3. Normalize and validate all reason prefixes (via reason.Normalize/Parse).
4. Build per-code segment tries (HTTP & gRPC) supporting longest-prefix-match with '*' as a single-segment wildcard.
5. Freeze all maps and tries into immutable copies (fresh allocations).

Errors returned from this function indicate invalid prefixes or configuration issues during normalization or trie construction.

Types

type Option

type Option func(*builder)

Option configures the Mapper at build time. All options are applied to an internal builder and then frozen into an immutable Mapper.

func WithGRPCDefault

func WithGRPCDefault(c code.Code, grpc int) Option

WithGRPCDefault sets or replaces the library-level default gRPC status for the given error code. This affects the fallback value used when no per-reason override is found.

func WithGRPCOverride

func WithGRPCOverride(c code.Code, grpc int) Option

WithGRPCOverride registers an exact gRPC override for the given code. Overrides take precedence over defaults but still sit below per-reason prefix matches (LPM) for that code.

func WithGRPCPrefix

func WithGRPCPrefix(c code.Code, prefix string, grpc int) Option

WithGRPCPrefix adds a gRPC longest-prefix-match rule for the given code. The rule is evaluated against the reason (dot-separated). A more specific prefix wins. Use "*" to match a single segment.

func WithHTTPDefault

func WithHTTPDefault(c code.Code, http int) Option

WithHTTPDefault sets or replaces the library-level default HTTP status for the given error code. This affects the fallback value used when no per-reason override is found.

func WithHTTPOverride

func WithHTTPOverride(c code.Code, http int) Option

WithHTTPOverride registers an exact HTTP override for the given code. Overrides take precedence over defaults but still sit below per-reason prefix matches (LPM) for that code.

func WithHTTPPrefix

func WithHTTPPrefix(c code.Code, prefix string, http int) Option

WithHTTPPrefix adds an HTTP longest-prefix-match rule for the given code. The rule is evaluated against the reason (dot-separated). A more specific prefix wins. Use "*" to match a single segment.