router

func Bind ¶

func Bind(r *http.Request, v interface{}) error

Bind decodes the request body as JSON into v, then validates it using struct validate tags. Returns a *DomainError if decoding or validation fails. Bodies are capped at 1 MiB (413 beyond it); use BindMax to raise the cap for endpoints that legitimately accept larger payloads.

WARNING — unlike BindForm, Bind applies no mass-assignment guard: a client can set any json-exposed field, including server-owned ones such as model.BaseModel's id/created_at/updated_at. encoding/json offers no per-field skip-on-decode without also hiding the field from responses, so the guard cannot be applied transparently here. Bind JSON onto a dedicated input type that omits server-owned fields, or zero those fields after decoding, when the target embeds a persistence model.

func BindForm ¶

func BindForm(r *http.Request, v interface{}) error

BindForm decodes an application/x-www-form-urlencoded or multipart/form-data request into v, then validates it using struct validate tags — the form counterpart of Bind.

Field resolution order: a `form:"name"` tag wins, then `json:"name"`, then the case-insensitive field name (first match wins if two form keys differ only by case); `form:"-"` skips a field. Supported field kinds: string, bool, signed and unsigned integers, floats, time.Time (RFC 3339, the datetime-local format 2006-01-02T15:04 — parsed as UTC since the wire format carries no offset — or 2006-01-02) and pointers to those. Embedded value structs are flattened; pointer embeddings are not traversed. Form keys without a matching field are ignored; present-but-empty values leave the field at its zero value so optional numeric inputs submit cleanly. Checkbox values "on" bind as true. Bodies are capped at 10 MiB.

Mass-assignment protection: fields tagged `db:"pk"` or `db:"readonly"` are server-owned (model.BaseModel's ID/CreatedAt/UpdatedAt) and are never bound from request input — a client-submitted `id` or `created_at` is ignored, leaving whatever the caller pre-set (zero on a create, the loaded value on an update). This is skip, not clear: binding onto a loaded record preserves its identity. NOTE the asymmetry — Bind (JSON) does NOT yet apply this guard (encoding/json offers no per-field skip without also hiding the field from responses); callers binding JSON onto persistence models must still zero server-owned fields themselves or bind through an input type.

Returns a *DomainError if parsing, conversion, or validation fails.

func BindMax ¶

func BindMax(r *http.Request, v interface{}, maxBytes int64) error

BindMax is Bind with a caller-chosen body cap in bytes. maxBytes <= 0 falls back to the default 1 MiB cap — an accidental zero must never mean "unlimited".

func CORSMiddleware ¶

func CORSMiddleware(opts CORSOptions) func(http.Handler) http.Handler

CORSMiddleware returns middleware that handles Cross-Origin Resource Sharing. It processes preflight OPTIONS requests and sets the appropriate CORS headers on all responses.

func CSRFMiddleware ¶

func CSRFMiddleware(opts CSRFOptions) func(http.Handler) http.Handler

CSRFMiddleware returns middleware that protects against cross-site request forgery. It implements a two-layer approach (Laravel-style): 1. Origin verification via Sec-Fetch-Site header (if enabled) 2. Traditional CSRF token validation as fallback

Features: - Origin verification for modern browsers - Session-based or cookie-based token storage - Encrypted X-XSRF-TOKEN cookie for JavaScript frameworks - Token rotation for enhanced security - Configurable origin-only mode and same-site allowance

CSRFMiddleware panics on a misconfiguration (the regexp.MustCompile pattern) — a bad CSRF config is a deployment error that should crash the process at startup, not serve requests with a weak key. The panic fires once, at middleware-chain construction, never on the request path. Use NewCSRFMiddleware for a non-panicking, error-returning alternative. See ADR-006.

func CSRFToken ¶

func CSRFToken(r *http.Request) string

CSRFToken returns the CSRF token for the current request, for templates to embed in forms. When the CSRF middleware is in the chain it returns the exact token that middleware resolved (injected into the context) — authoritative across cookie/session storage and any configured session key. Absent the middleware it falls back to the default cookie/session lookup.

func Compress ¶

func Compress(level int) func(http.Handler) http.Handler

Compress returns middleware that gzip-compresses response bodies for clients that accept gzip encoding. level follows compress/flate constants.

func ContextHandler ¶

func ContextHandler(handlers ...Handler) http.HandlerFunc

ContextHandler adapts a Handler to http.HandlerFunc.

func Created ¶

func Created(w http.ResponseWriter, data interface{})

Created writes a 201 Created response with the given JSON data.

func DefaultStack ¶

func DefaultStack(logger *slog.Logger, opts *routerOpts) []func(http.Handler) http.Handler

DefaultStack returns the standard middleware chain for Nucleus applications.

func Error ¶

func Error(w http.ResponseWriter, r *http.Request, err error, logger ...*slog.Logger)

Error writes an error as a structured JSON response. If the error is a *DomainError, its status code and details are used; otherwise a generic 500 is returned.

func GetReqID ¶

func GetReqID(ctx context.Context) string

GetReqID returns the request ID from context, or empty string.

func IsWebSocketUpgrade ¶

func IsWebSocketUpgrade(r *http.Request) bool

func JSON ¶

func JSON(w http.ResponseWriter, status int, data interface{})

JSON writes a JSON response with the given status code and data.

func Matched ¶

func Matched(r *http.Request) bool

Matched reports whether a registered route serves the request, as the caller holds it. The dispatching Mux resolves the route against the request's method and path each time Matched is called, so a middleware mounted with Use can let an unregistered path fall through to the mux's own 404 instead of answering for a handler that does not exist — the framework's default-deny authorizer and the CSRF middleware both do, through WhenMatched. The decision follows the request as each middleware sees it: a middleware that rewrites the path changes the answer for everything after it.

The decision sees through mounted sub-routers (Route, or Mount with a *Mux): at the parent, a path under a mount prefix counts as matched only when the sub-router — or a sub-router of its own, any depth down — has a route for the rest of the path, so a gate mounted at the root judges the same route table a gate inside the mount would. A handler mounted with Mount that is not a Mux is opaque, and everything under its prefix reports true. A method-only mismatch (the path is registered for other methods) reports false, and the mux answers 405.

When no Mux has dispatched the request — the middleware is wrapped around a plain http.Handler, or the test calls it directly — there is no routing decision to consult and Matched reports true, so every security layer keeps enforcing as if the route existed.

func NewCSRFMiddleware ¶

func NewCSRFMiddleware(opts CSRFOptions) (func(http.Handler) http.Handler, error)

NewCSRFMiddleware builds the CSRF protection middleware, returning an error on a misconfiguration instead of panicking. Use this constructor when the caller wants to surface configuration errors through its own validation path; use CSRFMiddleware for the panic-on-misconfiguration (regexp.MustCompile-style) variant.

The error case today is EnableXSRFCookie set without a 32-byte EncryptionKey — see ADR-006.

func NoContent ¶

func NoContent(w http.ResponseWriter)

NoContent writes a 204 No Content response.

func Paginate ¶

func Paginate(r *http.Request, defaultSize int) (page, pageSize int)

Paginate extracts page and page_size from query parameters with defaults and bounds. page defaults to 1, page_size to defaultSize (max 100).

func RateLimitFromPolicy ¶

func RateLimitFromPolicy(policy RateLimitPolicy) func(http.Handler) http.Handler

RateLimitFromPolicy builds the request limiter DefaultStack would mount for policy, with the default key (tenant and user from the context, else client IP) and the default route and role dimensions. It exists so an application can mount the limiter AFTER its identity middleware: the key reads the user id, the claims and the tenant from the request context, and a limiter mounted before the bearer is decoded only ever sees an IP. A policy with Requests <= 0 yields a pass-through.

func RateLimitMiddleware ¶

func RateLimitMiddleware(opts RateLimitOptions) func(http.Handler) http.Handler

RateLimitMiddleware enforces a token-bucket request limit: capacity is Requests+Burst tokens, refilled continuously at Requests per Window. This is smoother than a fixed window (no boundary bursts of 2× the limit) — the historical "fixed-window" description here was wrong; the implementation has always been the token bucket below.

func RealIP ¶

func RealIP(next http.Handler) http.Handler

RealIP rewrites r.RemoteAddr with the client IP taken from X-Forwarded-For / X-Real-IP — but ONLY when the immediate peer is a trusted proxy. On its own (the exported middleware) no proxies are trusted, so forwarding headers are ignored and r.RemoteAddr is left untouched. Use the router's WithTrustedProxies option (wired from the `trusted_proxies` config key) to honor forwarding headers behind a known load balancer. Trusting these headers unconditionally lets any client spoof its IP — evading per-IP rate limits and poisoning audit logs (H-N3).

func Recoverer ¶

func Recoverer(next http.Handler) http.Handler

Recoverer catches panics in downstream handlers, logs the stack trace, and returns a 500 Internal Server Error response. It logs through the process default logger; DefaultStack uses RecovererWithLogger so the panic goes through the application's handler (redaction, attributes, sink) like every other line.

func RecovererWithLogger ¶

func RecovererWithLogger(logger *slog.Logger) func(http.Handler) http.Handler

RecovererWithLogger is Recoverer logging through logger; nil falls back to slog.Default().

func RequestID ¶

func RequestID(next http.Handler) http.Handler

RequestID generates a unique request identifier and stores it in the request context. The ID is also written as the X-Request-Id response header.

func RequestLogger ¶

func RequestLogger(logger *slog.Logger) func(http.Handler) http.Handler

RequestLogger returns middleware that logs each HTTP request with slog. It records method, path, status, duration, request_id, remote_addr, and user_agent.

func RouteFromContext ¶

func RouteFromContext(ctx context.Context) string

RouteFromContext returns the route template ("/users/{id}") the mux matched for this request, or "" when nothing has matched yet — inside a handler it is always set. It is what the telemetry reports as http.route.

func SecurityHeaders ¶

func SecurityHeaders(next http.Handler) http.Handler

SecurityHeaders sets standard security headers on every response. HSTS is emitted when the request arrives over a direct TLS connection. Behind a TLS-terminating proxy (r.TLS == nil) use the router's WithHSTS option / an `env: production` app so the header is still sent.

func TelemetryMiddleware ¶

func TelemetryMiddleware(next http.Handler) http.Handler

TelemetryMiddleware records OpenTelemetry spans and metrics for HTTP requests.

func TimeoutMiddleware ¶

func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler

TimeoutMiddleware wraps the stdlib http.TimeoutHandler to cancel requests that exceed the given duration. It automatically skips WebSocket upgrades and requests that accept text/event-stream.

func TimeoutMiddlewareWithExemptions ¶

func TimeoutMiddlewareWithExemptions(timeout time.Duration, exemptPrefixes []string) func(http.Handler) http.Handler

TimeoutMiddlewareWithExemptions is TimeoutMiddleware with URL path prefixes that bypass it. http.TimeoutHandler buffers the response and hides http.Flusher, so a streaming handler behind it cannot flush a byte until it returns; an exempt subtree gets the raw writer and no deadline. A timeout <= 0 disables the middleware for every route.