Life of a request

What happens between a client sending a request to a Full app and receiving the response, in order, with the file and function responsible for each step. Read it next to examples/full-single/internal/app/routes.go.

client
  │  POST /v1/projects   Authorization: Bearer …   {"name": "First"}
  ▼
http.Server (httpx.NewServer)          timeouts, APP_ADDR
  │
  ▼  middleware, outermost first (routes.go, buildHTTP)
Recover ─ RequestID ─ telemetry ─ AccessLog ─ SecureHeaders ─ CORS ─ CrossOrigin ─ BodyLimit ─ auth.Middleware ─ ratelimit
  │
  ▼
http.ServeMux                         method + path pattern
  │
  ▼
Huma operation (delivery/)            decode, validate → 422, call use case
  │
  ▼
use case (usecase/)                   actor.Require(permission), domain rules, transaction, audit event
  │
  ▼
repository (repository/)              hand-written SQL through pgx
  │
  ▼
PostgreSQL
  │
  ▼  back up the stack
use case returns a value or a domain error
delivery returns the response, or the error
httpx.Mapper turns a domain error into problem+json
AccessLog writes one line; the span ends

1. The server#

cmd/api/main.go loads configuration (app.LoadConfig), builds the app (app.New) and calls Run. Run starts httpx.NewServer(cfg.Addr, handler), next to the background workers (settings listener, job client, job definitions manager, release tracker), under apistock.dev/app's lifecycle: on SIGINT or SIGTERM, /readyz starts failing, the server waits the drain delay (5 s in production, 0 in development) so load balancers stop sending traffic, then gives the server and workers up to 25 s to finish, then the cleanup stack closes what New registered (the database pool, then telemetry) in reverse order of creation.

2. Middleware#

buildHTTP wraps the mux with httpx.Chain(mux, middlewares...); the first in the list runs first.

Order matters: a panic anywhere is caught; the request ID and span exist before anything logs; CORS answers preflights before the cross-origin check; the body limit applies before anything reads the body. The auth middleware and rate limiter are added only when the auth module exists, which is always in a Full app.

3. Authentication#

auth.Middleware never rejects a request for missing credentials: it only establishes who is calling. Endpoints decide whether that's required.

1. authlib.TokenFrom reads Authorization: Bearer <token>, or else the __Host-session cookie.
2. No token: continue anonymously.
3. The token is hashed with SHA-256 and looked up in auth_sessions with its user and roles. If the store fails, answer 503 auth_unavailable rather than treating the caller as anonymous.
4. Not found, expired (idle 14 days, absolute 90 days) or revoked: continue anonymously.
5. Found: put the principal (user, session, roles, whether the second factor was used and when) and its actor into the context. If the session's last-seen time is at least a minute old (authlib.SessionTouchInterval), update it, which also extends the idle expiry.

Roles are read on every request, so granting or revoking a role applies at once.

4. Routing and decoding#

http.ServeMux matches method and path pattern. Unmatched requests reach the catch-all, which answers 404 not_found with no route matches <METHOD> <path>.

API routes are Huma operations registered in each module's delivery/ package through registerModules (internal/app/modules.go). Huma decodes path, query, header and body into the operation's Go input type and validates it against the struct tags (minLength, enum, format, …). Invalid input never reaches the handler: it answers 422 validation_failed with errors[] naming each field. Unknown JSON fields are ignored (ADR-0027).

5. The use case#

The handler calls one use case method with plain values. A use case, such as projects.Service.Create:

1. Authorizes. actor.Require(ctx, permission) or the module's own ownership rule; unauthenticated callers get ErrUnauthenticated (401), missing permissions ErrForbidden (403), and roles that need a second factor without one mfa_required (403). Multi-tenant resources call orgs.RequireMember first and hide other organisations as 404.
2. Applies domain rules from domain/: validation beyond the API schema, state transitions.
3. Writes in a transaction through the TxManager port when more than one statement must commit together, such as the row and its audit event, or the row and a job.
4. Records an audit event through audit.Recorder (modules/auditpg), with the actor, request ID and resource. Audit writes use context.WithoutCancel, so a client disconnecting doesn't lose the record.
5. Returns a domain value or a domain error. Use cases never import net/http or pgx.

6. The repository#

Each operation is one Go file with one SQL constant, run through postgres.DBTX (the pool or a transaction). Expected database conditions become domain errors, such as a unique violation on the projects_owner_name index becoming ErrProjectNameTaken; anything else is wrapped with %v so driver types don't leak. Every query is a traced span with its SQL text and never its arguments.

7. The response or the error#

On success, Huma encodes the output type as JSON with the status the operation declares.

On error, the error travels up unchanged to the delivery layer, which hands it to the app's httpx.Mapper (built in buildHTTP):

1. An *httpx.Problem anywhere in the chain is used as it is.
2. Otherwise the first mapping whose error matches with errors.Is gives the status, code and detail. Mappings are registered by openapi.InstallErrors, by buildHTTP for pagination errors, and by each module_<name>.go.
3. Otherwise: 500 internal_error with a generic detail, and the full error is logged once with the request ID. Internal messages never reach the client.

httpx.WriteProblem writes application/problem+json with Cache-Control: no-store and fills request_id. See error handling.

8. After the response#

AccessLog writes its line, the span ends and is exported if OTEL_EXPORTER_OTLP_ENDPOINT is set. Work queued during the request, such as an email, is a River job row that committed with the request's transaction or on its own; a worker in the same process picks it up, carrying the request ID, trace and actor in the job's metadata (background jobs).

Following one request#

Every response carries X-Request-ID, and every problem body its request_id. Search the logs for it to find the access log line, any error logged for it, and (with tracing on) the trace with every SQL query and job it caused:

level=INFO msg="http request" service=acme-api method=POST route="/v1/projects" status=201 duration_ms=4 bytes=180 request_id=req_… trace_id=… span_id=…