Context and correlation propagation

Status: Accepted (2026-09-14)

Context#

Requests, background jobs, audit events, logs and traces must be linkable: who acted, in which organisation, from which request. Misusing context.Context (loggers, transactions or optional parameters in context) hides dependencies. Work triggered by a request often continues in a job after the request ends, and some writes must survive client disconnects.

Options#

1. Pass everything explicitly through parameters.
2. Put everything in context (logger, transaction, config).
3. Context only for request-scoped identity and correlation; everything else explicit.

Decision#

Option 3.

Rules#

• ctx is the first parameter of every function that does I/O or may block; never stored in structs.
• Jobs: at enqueue, job metadata stores request ID, trace parent, actor and org ID; the worker restores them into context, with the actor marked as system acting on behalf of the original actor.
• Detached writes: audit records for failed or denied actions and security-critical writes (session revocation) use context.WithoutCancel(ctx) with their own timeout.
• Outgoing calls: derived contexts with timeouts; always defer cancel().
• Libraries never call slog.Default() or create root contexts, except main and the lifecycle helper.
• Log attributes: snake_case keys; log user_id and org_id, never emails, tokens or secrets.

Why#

Everything stays linkable without hiding real dependencies in context.

Trade-offs#

Jobs need a small amount of metadata handling (provided by the jobs module).

Consequences#

The e2e test suite asserts that a request's request_id appears in its log lines, audit event and any jobs it enqueued.