Wiring an application
Promoted from rn-forge-web's interim FastAPI wiring guide, which was written
to become this package. What was a page of copy-paste handler, dependency and
router code there is a handful of calls here; what is left is the wiring an
application genuinely owns.
The wiring module
from fastapi import APIRouter, FastAPI
from rn_forge.fastapi import (
AppConfig,
FastApiApp,
)
from rn_forge.web import ProblemType, default_registry
from myapp.errors import OrderLocked
from myapp.settings import Settings
def build_app(*, settings: Settings, checks) -> FastAPI:
registry = default_registry(type_base=settings.problem_type_base)
registry.register(OrderLocked, ProblemType("order-locked", 409, "Order Locked"))
return FastApiApp(
AppConfig(
registry=registry,
checks=checks,
required_checks=("db",),
realm="orders",
log=settings.log,
),
routers=(orders.router,),
title="Orders",
)
FastApiApp installs the common adapters only. The application's composition
root constructs Settings, checks, routers and infrastructure explicitly, so
tests can pass fakes and the factory never reads the environment or starts a
resource.
The rules the wiring depends on
- Register domain exceptions on the registry before creating
AppConfig. Handlers are registered per exception type, because Starlette re-raises anything handled by anExceptionhandler. A row added later still renders correctly, but as a logged, re-raised server error. - Pass that registry to
AppConfig. Its statuses are the problem responses the schema declares on every operation. - Tracing.
FastApiAppinstruments itself withFastAPIInstrumentor.instrument_appby default (AppConfig.tracing), after the kit's own middleware, so the instrumentation wraps the whole stack regardless of add order. It also sets aTraceResponsePropagatoras the global response propagator, but only when nothing else has — an application that configures its own response propagator first is left alone.FastApiAppturns off FastAPI's native tracing unless the application passestelemetry=, soAppConfig.tracingalone decides whether server spans are recorded. Configure aTracerProviderand exporter in the application, or run underopentelemetry-instrument;FastApiAppnever does either. - Derive every model from
rn_forge.web.WireModel. camelCase on the wire is enforced by the base class, including in a hand-builtJSONResponse(model.model_dump(mode="json")). - Spell a non-CRUD route as a custom method.
POST /orders/{order_id}:cancelis namedordersCancelautomatically, on both stacks. The same action as a plain path segment (/orders/{order_id}/cancel) is indistinguishable from a sub-collection and needs an explicitoperation_id=.
Logging server errors
A 5xx problem body carries no detail, so the cause goes to the log.
AppConfig.log is None by default and logs nothing; pass
log=log_server_errors() to log each 5xx at ERROR with the original
traceback, status, request path and trace id:
from rn_forge.fastapi import AppConfig, log_server_errors
AppConfig(registry=registry, log=log_server_errors())
It logs through AppLogger.get_logger("rn_forge.fastapi.problem"); pass an
AppLogger to use another. A 4xx logs nothing.
Routes
from typing import Annotated
from fastapi import APIRouter, Depends
from rn_forge.fastapi import bearer_auth, page_params, require_if_match, requires
from rn_forge.auth import Principal, Requirement
from rn_forge.web import Cursor, Page, check_precondition
router = APIRouter()
caller = bearer_auth(authenticator=jwt_authenticator, log=log)
reader = requires(caller, Requirement(all_scopes=frozenset({"orders:read"})))
@router.get("/orders")
async def orders_list(
page: Annotated[tuple[int, Cursor | None], Depends(page_params(cap=100, default=20))],
principal: Annotated[Principal, Depends(reader)],
) -> Page[OrderOut]:
size, cursor = page # size already clamped; cursor already decoded
...
@router.patch("/orders/{order_id}")
async def orders_update(order_id: str, if_match: Annotated[str, Depends(require_if_match())]):
order = await repo.get(order_id)
check_precondition(if_match, current_version=order.version, entity_id=order_id, required=True)
...
Page[OrderOut] reaches the schema as pydantic's own name, Page_OrderOut_ —
document text is not held identical across stacks (only wire behaviour and
operationId are; see api-conventions.md §9). The DRF binding names its own
paginated component its own way too, PaginatedOrderOutList.
pageSize above the cap is clamped, never rejected — do not add a
Query(le=...) alongside page_params; that is a 422 and a specification
violation.
Merge patch
merge_patch_body() checks the media type and returns the raw body;
merge_into parses it, merges it into the current resource and validates the
result against the model. merge_patch_openapi() declares the request body.
Declare merge_patch_body() before the If-Match dependency, so the media type
answers first (415), and call check_precondition before merge_into, so a
stale request is 412 whatever the body says.
from fastapi import Depends, Header
from rn_forge.fastapi import merge_into, merge_patch_body, merge_patch_openapi
from rn_forge.web import check_precondition
@router.patch("/documents/{doc_id}", openapi_extra=merge_patch_openapi())
async def documents_update(
doc_id: str,
body: bytes = Depends(merge_patch_body()),
if_match: str | None = Header(default=None),
) -> DocumentOut:
document = await repo.get(doc_id)
check_precondition(if_match, current_version=document.version, entity_id=doc_id)
return merge_into(DocumentOut, document, body)
Use require_if_match() in place of the optional header to make it required
(428). A null on a non-nullable field is a 422 that reads
This field may not be null.
Partial responses
read_mask_param(Model) is a dependency yielding the parsed readMask, or
None for the whole resource. It reads the model's aliases, so a nested model,
Model | None or list[Model] field can be reached with a dotted path and
anything else is a leaf. A path that names nothing is a 400 problem before the
route runs. Apply the mask to the dumped body with mask.apply(...), or to a
page with masked(page, mask). Return a JSONResponse and declare
response_model for the documentation, because the pruned body no longer
validates as the full model.
from fastapi import Depends
from fastapi.responses import JSONResponse
from rn_forge.fastapi import masked, read_mask_param
from rn_forge.web import Page, ReadMask
@router.get("/profiles/{profile_id}", response_model=ProfileOut)
async def profiles_get(
profile_id: str, mask: ReadMask | None = Depends(read_mask_param(ProfileOut))
) -> JSONResponse:
body = ProfileOut.model_validate(await repo.get(profile_id)).model_dump(by_alias=True)
return JSONResponse(body if mask is None else mask.apply(body))
@router.get("/profiles", response_model=Page[ProfileOut])
async def profiles_list(
mask: ReadMask | None = Depends(read_mask_param(ProfileOut)),
) -> JSONResponse:
page = Page[ProfileOut](items=await repo.list(), next_page_token=None)
return JSONResponse(masked(page, mask))
batch_get_router accepts readMask unless it is built with read_mask=False.
Security headers
FastApiApp installs the OWASP REST Security Cheat Sheet response headers by
default (AppConfig.security_headers). Strict-Transport-Security is excluded
from the default preset and is opt-in — AppConfig(hsts=True) — for a
deployment that terminates TLS itself rather than behind a front end that
already sets it.
Service discovery
FastApiApp serves RFC 9727's /.well-known/api-catalog by default
(AppConfig.api_catalog), pointing at the OpenAPI document (openapi_url) and
docs UI (docs_url) it already serves, plus readiness. Set
AppConfig(api_catalog=False) to turn it off.
CORS
Opt-in, and the application owns the policy:
from rn_forge.fastapi import AppConfig, CorsPolicy
config = AppConfig(cors=CorsPolicy(allow_origins=("https://app.example.com",)))
CorsPolicy.expose_headers defaults to rn_forge.web.EXPOSED_HEADERS — the
response headers this kit emits that a browser cannot read unless a CORS policy
names them (ETag, Link, Content-Disposition, and so on). traceresponse
needs no entry here — the OpenTelemetry response propagator exposes it itself.
allow_origins has no default; naming them is the application's decision.
CorsPolicy(allow_credentials=True, allow_origins=("*",)) raises — browsers
reject that combination.
Deprecating a route
from datetime import UTC, datetime
from rn_forge.fastapi import deprecated
SUNSET_ANNOUNCED = datetime(2026, 1, 1, tzinfo=UTC)
SUNSET_DATE = datetime(2026, 7, 1, tzinfo=UTC)
@router.get(
"/orders/legacy-summary",
deprecated=True, # marks the OpenAPI operation
dependencies=[
Depends(deprecated(deprecated_at=SUNSET_ANNOUNCED, sunset=SUNSET_DATE))
],
)
async def orders_legacy_summary(): ...
deprecated=True and the deprecated(...) dependency are both needed: one
marks the document, the other stamps the Deprecation/Sunset/Link headers
on the wire (RFC 9745, RFC 8594).
Publishing a model no route references
A generated client sometimes needs a shape that never appears as a request or
response body — a webhook payload, an event published to a queue. Override
openapi() on a FastApiApp subclass and call super().openapi() first, the
same composition FastApiApp itself uses to repair the document:
from pydantic.json_schema import models_json_schema
class MyApp(FastApiApp):
def openapi(self):
schema = super().openapi()
_, definitions = models_json_schema(
[(OrderShippedEvent, "serialization")],
ref_template="#/components/schemas/{model}",
)
schema["components"]["schemas"].update(definitions.get("$defs", {}))
return schema
What an application still writes
-
The authenticator — unless it is OIDC. For bearer tokens from an identity provider, install
rn-forge-fastapi[oidc]and use the shared implementation rather than writing one:from rn_forge.auth.oidc import OidcAuthenticator authenticator = OidcAuthenticator.from_issuer( "https://idp.example.com/tenant", audience="api://orders" ) caller = bearer_auth(authenticator=authenticator, log=log)Pass
callertorequires(caller, Requirement(all_scopes=...)), then use the returned dependency on protected routes.FastApiAppregisters the problem handlers that render authentication failures as 401 with a challenge and authorization failures as 403 without one.Build it once at startup — it holds the JWKS cache. It is the same authenticator
rn-forge-djangouses, so both stacks accept the same tokens. For any other scheme,bearer_authtakes anyrn_forge.auth.AuthenticatororAsyncAuthenticator: verify the token, map claims to aPrincipal, and raiseAuthenticationFailedwith the reason — the reason reacheslog, never the body. A syncAuthenticatorruns in the threadpool, so a blocking JWKS fetch does not stall the event loop.basic_authis for local development and simple internal deployments only. -
The idempotency store. Implement
rn_forge.web.AsyncIdempotencyStoreover the application's database. Race safety comes from aUNIQUE (scope, key)constraint withINSERT … ON CONFLICT DO NOTHINGand a read-back, never a check-then-insert. Decorate the route withidempotent(store, scope=...)(rn_forge.fastapi.idempotent), which wrapsrn_forge.web.run_idempotent_async: the decorated route takesrequest: Requestand returns aResponse. -
The checks. Zero-argument callables, sync or async, returning a
boolor arn_forge.web.CheckResult. Passhealth_router(timeout=...)so a hung dependency is reported asfailrather than hanging/readyz; the default,None, waits indefinitely.
Server-sent events
The sse extra adds sse-starlette. sse_response wraps an async iterable of
ServerSentEvent in an EventSourceResponse:
from collections.abc import AsyncIterator
from fastapi import Header
from rn_forge.fastapi.sse import sse_response
from sse_starlette import ServerSentEvent
@router.get("/jobs/{job_id}/events")
async def job_events(job_id: str, last_event_id: str | None = Header(None)):
async def events() -> AsyncIterator[ServerSentEvent]:
async for update in job_updates(job_id, after=last_event_id):
yield ServerSentEvent(update.json(), id=update.id, event="update")
return sse_response(events(), instance=f"/jobs/{job_id}/events")
- Frames. The stream opens with a
retry: 5000frame, so a browserEventSourcewaits that long before it reconnects; passretry=Noneto omit it. A heartbeat comment is sent every 15 seconds while the stream is idle;ping=Noneturns it off. - Resuming. A reconnecting browser sends the last
idit received asLast-Event-ID. The route reads it and decides what to replay;sse_responsedoes not. - Rejected fields. An
idoreventcontaining\r,\nor\x00raisesWebError, wheresse-starlettealone would strip the line break and send a different field. Raised while streaming, the status line is already sent, so the rejection reaches the client as the terminal frame below. - Errors. The status line is sent before the first frame, so an exception
raised by the iterable cannot become an HTTP error. The stream ends with one
frame whose
eventiserrorand whosedatais the problem as JSON, built by the registry (default_registry()unlessregistry=is given) withinstanceand the currenttraceId. A 5xx problem carries the generic detail, so passlog=log_server_errors()to keep the cause: the application'sAppConfig.lognever sees it. A client disconnect or cancellation sends nothing. - Headers.
headers=is applied last and replaces the defaults, includingcache-controlandx-accel-buffering. - Shutdown. Importing the module makes
sse-starlettepatchuvicorn.Server.handle_exitso open streams end when the server is asked to exit.
Conformance
tests/test_conformance.py in this package is the FastAPI driver for the
rn-forge-web conformance table: a fresh application per case, built from the
adapters above, depends_on issued first, and equality asserted against the
table — never against Django's output.
Deploying it
rn-forge-web's "Deployment" guide maps /livez, /readyz, the security
headers' hsts flag, CORS and body-size limits onto Kubernetes, App Engine and
Azure App Service.