Quickstart¶
Five things nearly every application built on this kit wires. None of them
imports a web framework. For framework setup, see the
plain Django recipe, or the "Wiring an application" guide in
the rn-forge-fastapi package.
1. Tracing: W3C Trace Context through OpenTelemetry¶
There is no house request-id header. traceparent in, traceresponse out,
through OpenTelemetry's own ASGI/WSGI instrumentation (or
opentelemetry-instrument) — rn_forge.web reads the current span, and never
configures a TracerProvider or an exporter itself:
from rn_forge.web import current_trace_id, current_span_id
current_trace_id() # 32 lowercase hex chars, or None with no span recording
current_span_id() # 16 lowercase hex chars, or None
For structured logs, rn_forge.commons.logging.structlog.otel_processor adds
trace_id and span_id to every event. StructLogger installs it itself; in a
structlog chain of your own, list it as a processor.
2. Every error as an RFC 9457 problem¶
from rn_forge.web import default_registry, render_problem
registry = default_registry() # a fresh instance; never a shared singleton
def to_response(exc, path):
rendered = render_problem(registry, exc, instance=path)
# Content-Type: application/problem+json; the body carries the current trace id
return rendered.status, rendered.body, rendered.headers
Register your own domain exceptions once, and subclasses resolve for free:
from rn_forge.web import ProblemType
registry.register(OrderLocked, ProblemType("order-locked", 409, "Order Locked"))
A 5xx never carries str(exc) — the detail is a fixed generic string unless you
pass one explicitly.
3. Optimistic concurrency¶
from rn_forge.web import EntityVersionETagCodec, check_precondition
codec = EntityVersionETagCodec()
response["ETag"] = codec.format(entity_id=order.pk, version=order.version) # on read
check_precondition( # on write
request.headers.get("If-Match"),
current_version=order.version,
entity_id=order.pk,
required=True,
)
Absent and required is 428; a mismatch is 412; unparseable is 400; * passes.
4. Cursor pagination¶
from rn_forge.web import Page, clamp_page_size, decode_cursor, encode_cursor
size = clamp_page_size(request.query.get("pageSize"), default=20, cap=100)
cursor = decode_cursor(token) if (token := request.query.get("pageToken")) else None
rows = fetch(after=cursor, limit=size + 1) # one extra row probes for a next page
has_more, rows = len(rows) > size, rows[:size]
page = Page(
items=[serialize(r) for r in rows],
next_page_token=encode_cursor(str(rows[-1].create_time), str(rows[-1].pk))
if has_more
else None,
)
return page.as_body()
An over-large pageSize is clamped, never rejected. A Query(le=...)
constraint would violate that, and the conformance table has a case for it.
5. Readiness¶
from rn_forge.web import CheckResult, run_checks
report = await run_checks(
{
"db": check_db,
"queue": lambda: CheckResult(status="skipped", reason="not configured"),
},
required=["db"],
)
return report.http_status, report.as_body()
A failing check outside required degrades the reported status but keeps the
endpoint at 200. A check that raises becomes a failure, never a 500.
Next¶
The API conventions page is the normative version of all of the above, written so it can be pasted into an application's specification.