Module context 

Execution contexts for queries and mutations.

Every function receives a context providing access to:

• Database connection (pool or transaction)
• Authentication state (user ID, roles, claims)
• Request metadata (request ID, trace ID, client IP)
• Environment variables
• Job/workflow dispatch (mutations only)

QueryContext vs MutationContext

Feature	QueryContext	MutationContext
Database	Pool (read-only)	Transaction or pool
Dispatch jobs	No	Yes
Start workflows	No	Yes
HTTP client	No	Yes (circuit breaker)

Transactional Mutations

When transactional = true (default), mutations run in a transaction. Jobs and workflows dispatched during the mutation are buffered and only inserted after the transaction commits successfully.

BEGIN
  ├── ctx.db().execute(...)
  ├── ctx.dispatch_job("send_email", ...)  // buffered
  └── return Ok(result)
COMMIT
  └── INSERT INTO forge_jobs (buffered jobs)

Structs

AuthContext

Authentication context available to all functions.

MutationContext

Context for mutation functions (transactional database access).

OutboxBuffer

PendingJob

PendingWorkflow

QueryContext

Context for query functions (read-only database access).

RequestMetadata

Request metadata available to all functions.

Enums

DbConn

Abstracts over pool and transaction connections so handlers can work with either.

ForgeConn

Connection wrapper that implements DerefMut<Target = PgConnection>, making it compatible with sqlx compile-time checked macros (query_as!, query!).

Traits

TokenIssuer

Token issuer for signing JWTs.

Type Aliases

JobInfoLookup

Callback type for looking up job info by name.