rn-forge-web¶
rn-forge-web holds the HTTP/API primitives that are genuinely
framework-agnostic — the wire semantics an application promises its callers,
shared by Django/DRF, FastAPI/Starlette and anything else that speaks HTTP.
It provides:
tracing— W3C Trace Context: reading the current OpenTelemetry span's trace and span idsproblem— RFC 9457 problem details, plus an exception→problem registry that resolves by MRO, the 5xx detail policy, the two validation-error normalizers, and the parse direction for consuming an upstream's problem bodyexceptions— the conflict, precondition, cursor, idempotency and auth exceptions, allAppExceptionsubclassesconcurrency— ETag validators and theIf-Matchprecondition check, with 412/428 rather than a blanket 409pagination— opaque cursors in Google AIP-158's spelling, with the page size clamped and never rejectedidempotency— the store protocol (sync and async), request hashing, and an in-memory doublehealth— readiness-check aggregation with four statuses, and the HTTP status derived once rather than per frameworkasgi— the request-body size limit, pure ASGI and Starlette-freeauth—Credentials, theAuthorizationheader parser and theWWW-Authenticatechallenge;Principaland the authenticator/authorizer protocols arern-forge-auth'sconformance— the scenario table both framework packages are tested against, shipped as framework-free datamodels,openapi,merge_patch,read_mask,soft_delete,transfer,operations,deprecation,security— see the API reference
Why this package exists¶
Every module here was implemented twice, independently, by two codebases that never shared code — a Django/DRF application and a FastAPI one. That the same seven concerns turned up in both is the evidence that they are real. That the two implementations disagreed — on the header name, on 409 versus 412, on whether to reset a ContextVar, on whether a page size above the cap is an error — is why they belong in one place rather than two.
Where they disagreed, this package picks one and says why in the module's own docstring. Those calls are the substance; the code is small.
Where it sits¶
It depends on rn-forge-commons and nothing else in the workspace, and it
imports no web framework, no rn_forge.cli and no rn_forge.tooling.
task lint proves it, and CI gates every other job on that.
Inbound, not outbound. Circuit breakers, retries and rate limiting are
transport-agnostic and live in rn-forge-commons — a worker retrying a database
call needs them and serves no HTTP. This package is about what a server promises
its callers.
Install¶
dependencies = ["rn-forge-web>=0.3,<0.4"]
Extras: security and testing. Minimum example:
Quickstart. Every exception here is an AppException
and renders as an RFC 9457 application/problem+json body; see
API conventions.
Where to start¶
- Writing an application specification? The API conventions page is normative and is meant to be read on its own.
- Wiring an existing application? Use the
plain Django recipe or the
rn-forge-fastapipackage's "Wiring an application" guide, then the checklist. - Just want the code? Quickstart.