app

func RequireAuthenticated ¶ added in v0.2.0

func RequireAuthenticated() AuthorizationPolicy

RequireAuthenticated returns the policy that demands any identity at all.

Attach it per route with transport.Guard, which runs BEFORE decode — so an unauthenticated caller's malformed body is a 401, not a 400.

func RequireScope ¶ added in v0.2.0

func RequireScope(scopes ...string) AuthorizationPolicy

RequireScope returns the policy that demands an identity carrying every one of scopes.

It NEVER merges the two denial codes, because they answer different questions and map to different statuses:

no identity at all         → UNAUTHENTICATED (401): prove who you are
an identity, wrong scope   → PERMISSION_DENIED (403): you may not do this

Called with no scopes it is exactly RequireAuthenticated — an empty list demands nothing extra, and must not silently allow an anonymous caller, which is the shape a variadic helper like this usually fails in.

It is written entirely in core types with no dependency, which is what makes it the proof that AuthorizationPolicy is usable before warren/auth exists.

func Chain ¶

func Chain[Req, Res any](h Handler[Req, Res], mw ...Middleware[Req, Res]) Handler[Req, Res]

Chain composes middleware around a handler and returns the composed handler. mw[0] is the outermost: the first to see the request and the last to see the response, so the argument order reads in execution order.

Chain runs at boot, not per request — the result is stored in the route table as a pre-built closure, and invoking it allocates nothing.

A nil handler, a nil middleware, or a middleware that returns nil panics here, at composition time, with a message naming the position — a startup crash instead of the request-time nil dereference each of them would otherwise become. This is the boot-time panic AGENT.md § General names as sanctioned alongside di.MustResolve: Chain cannot return an error (the §3.2 signature is fixed), and deferring the failure to request 1 is the exact outcome the boot-ordering rule exists to prevent. Note a conditional middleware belongs in the slice only when enabled — append it, don't leave a nil hole. THE FIRST MIDDLEWARE IS THE OUTERMOST ONE, and the loop below is why: it wraps from the end, so mw[0] is applied last and therefore sees the request first. Chain(h, A, B) is A(B(h)).

That ordering is load-bearing for exactly one pair, and both spellings compile: Retrying BEFORE Transactional gives each attempt its own transaction, and the reverse wraps one transaction around every attempt. A field test wrote the reverse and measured zero retries across eight concurrent requests, with two callers refused for stock that existed.

The reverse is REFUSED, at boot, and the walk that finds it sees through every middleware Warren ships and through any of yours whose handler implements Unwrapper — including across a nested Chain. A middleware of yours that does not implement it is a wall the walk stops at, so a Retrying beneath it is invisible here; one method lifts that. There is deliberately no unchecked variant of this function.

func IdentityFromContext ¶ added in v0.2.0

func IdentityFromContext(ctx context.Context) (Identity, bool)

IdentityFromContext returns the caller's identity and whether there is one.

The ok-bool is the first and strongest of the three anti-ambiguity mechanisms, because it is enforced by the compiler rather than by review:

app.IdentityFromContext(ctx).Subject   // does not compile

A single-return accessor would make that line legal, and it writes rows owned by "". This is a deliberate asymmetry with log.CorrelationID, which does return a bare string — an absent correlation ID is cosmetic, one log line harder to join, while an absent identity is a security decision. transport.Params.Path already returns an ok-bool for the same reason.

Reading costs 0 allocations, present or absent.

func Authorized ¶

func Authorized[Req, Res any](policy AuthorizationPolicy) Middleware[Req, Res]

Authorized runs the policy before invoking the handler; a denial short-circuits — the handler is never called — and the policy's error returns unchanged, code intact. Because it is core-ring, the same check applies to HTTP, gRPC, and consumers. A nil policy panics at composition time, like Chain's guards.

func Metered ¶

func Metered[Req, Res any]() Middleware[Req, Res]

Metered records a duration histogram per handler and an error counter keyed by the warren/errors code, through the context-carried Telemetry — once per invocation, the error path included. On a context carrying no Telemetry it is an exact pass-through.

func Retrying ¶

func Retrying[Req, Res any](policy RetryPolicy) Middleware[Req, Res]

Retrying re-invokes the handler when the error's OUTERMOST code is CodeUnavailable or CodeContention — the two retryable codes. It is what optimistic concurrency needs: a stale write is CONTENTION, and re-invoking the handler re-reads the aggregate, which is the whole point. The outermost code decides, exactly as an adapter's status mapping does, because wrapping is recategorization: a handler that wraps an Unavailable inside Internal has declared the failure non-retryable, and this middleware agrees. A plain %w wrap (fmt.Errorf) leaves the outermost Warren error untouched and stays retryable. Every other code returns unretried.

When retries exhaust, or the context is cancelled during a wait, the handler's LAST error is returned: it is the freshest and still carries the code the adapter maps. A context that is already cancelled still reaches the handler once — the handler owns its own context checks; this middleware observes cancellation between attempts and during waits. A nil policy panics at composition time, like Chain's guards.

func RetryingOn ¶ added in v0.2.0

func RetryingOn[Req, Res any](policy RetryPolicy, codes ...errors.Code) Middleware[Req, Res]

RetryingOn is Retrying with the retryable set given explicitly. The legal set is CONTENTION, UNAVAILABLE and INTERNAL — the three codes for which the same request may succeed later. The other five are terminal, and composing on one panics at boot.

Prefer Retrying. It already covers CONTENTION and UNAVAILABLE, which is what almost every handler wants and cannot spell wrongly. Two things are reachable only through this function.

FIRST, CodeInternal. Retrying never retries it — an unanticipated failure carries no promise that a second attempt helps — and no other middleware offers it. On a consumer-shaped handler, where a dead-letter queue is already behind the retry, spending a bounded budget before giving up costs one message's latency and saves the operator a redrive:

app.RetryingOn(policy, errors.CodeInternal, errors.CodeUnavailable)

SECOND, deliberate NARROWING — which is the shape of the argument, not widening. A handler safe to re-run on CONTENTION is not automatically safe to re-run on UNAVAILABLE: if it makes an outbound call, an UNAVAILABLE can mean the call arrived and only the reply was lost, so re-invoking the handler charges the card twice. A lost conditional write cannot say that — nothing was written — so name CONTENTION alone and leave UNAVAILABLE to the caller:

app.Chain(h, app.RetryingOn(policy, errors.CodeContention), app.Transactional(uow))

Under plain Retrying that same handler retries UNAVAILABLE too, and doubles the side effect. That is the trade this function exists to let you make.

The codes you name are the WHOLE set; nothing is inherited. Migrating Retrying(p) to RetryingOn(p, errors.CodeContention) STOPS retrying a dependency that was briefly away. Pass both when you want both —

app.RetryingOn(policy, errors.CodeContention, errors.CodeUnavailable)

— which is Retrying(policy) spelled out, and the reason optimistic concurrency needs no code list here at all. A stale write is CONTENTION, not CONFLICT, and Retrying covers it.

Everything else is Retrying's behaviour, including the rule that matters most: the OUTERMOST code decides, so a handler that wraps a CONTENTION inside an INTERNAL has declared the failure final and this agrees. The handler must RE-READ its aggregate on each attempt — this re-invokes the HANDLER, not the transaction, so one that closed over a stale version contends for ever. Retries are only safe on an idempotent handler; see Retrying.

At least one code is required. An empty set would retry nothing, silently, which is the failure mode a variadic helper like this usually has.

This comment said the opposite until 2026-08-09, and the correction is worth stating rather than hiding: it taught that a stale write was CONFLICT and that RetryingOn was the fix for the undersell a field test measured. The CONTENTION split (4a1d152) reassigned that case and gave it to Retrying, and the examples the old comment gave now panic at boot.

func Timeout ¶ added in v0.2.0

func Timeout[Req, Res any](d time.Duration) Middleware[Req, Res]

Timeout bounds the handler with a derived deadline.

Where you put it decides what it bounds ¶

Composed INSIDE Retrying it bounds each ATTEMPT; composed OUTSIDE it bounds the whole retried SEQUENCE. Chain applies its middleware so that the last argument is nearest the handler:

app.Chain(h, app.Retrying(p), app.Timeout(3*time.Second)) // per attempt
app.Chain(h, app.Timeout(3*time.Second), app.Retrying(p)) // per sequence

Those are materially different systems — three attempts of up to three seconds each, against three attempts sharing three seconds — and that is exactly why there is no Policy(Timeout(...), Retry(...)) combinator. A combinator would hide, inside a DSL, a choice Chain already makes visible on one line.

It signals; it does not interrupt ¶

A handler that ignores its context runs to completion, exactly as transport/http's ShutdownTimeout documents for the drain. Go has no way to kill a goroutine. What the deadline does is reach every adapter that respects a context — postgres, kafka, any http.Client you build — so the work a handler delegates is bounded even when the handler itself is not.

A caller's SHORTER deadline always wins: context.WithTimeout never extends one, so a request already bounded at 100ms stays bounded at 100ms.

The expiry surfaces as whatever the handler returns. An adapter that respects the context typically returns CodeUnavailable — postgres does — which app.Retrying then retries and every transport maps to 503.

func Traced ¶

func Traced[Req, Res any]() Middleware[Req, Res]

Traced opens one span per handler invocation, named with the "<module>.<handler>" the adapter seeded via WithHandlerName. The Telemetry rides the context (WithTelemetry); on a context carrying none, Traced is an exact pass-through.

func Transactional ¶

func Transactional[Req, Res any](uow UnitOfWork) Middleware[Req, Res]

Transactional wraps Handle in a unit of work, so the aggregate state the handler wrote and the outbox rows for the events it raised commit in one transaction — or neither does.

A handler that calls uow.Do itself under this middleware is joined, not nested: warren.md §10 shows both patterns, and the unit of work's own contract makes the inner call join the transaction in scope. The transaction's error passes through with its code intact, so a serialization failure arrives as CONTENTION (it was UNAVAILABLE until 4a1d152) and app.Retrying — composed OUTSIDE this middleware — re-runs the whole transaction rather than retrying inside a doomed one.

Composing it the other way round is REFUSED by Chain, with a panic naming the fix: one transaction around every attempt has no correct reading, and on Postgres it commits a failed attempt's staged writes alongside the next one's. A nil unit of work panics at composition time, like Chain's guards.

func TelemetryFromContext ¶

func TelemetryFromContext(ctx context.Context) Telemetry

TelemetryFromContext returns the Telemetry carried by ctx, or nil.