Skip to content

Wiring rn-forge-web into plain Django

This is a composition recipe for an application using plain Django/DRF with rn-forge-web. For the packaged adapters, use the rn-forge-django quickstart and its Django/DRF guides. Several pieces below already ship there; the examples show how an application can compose the shared HTTP primitives itself.

1. Tracing — instrument once, before Django loads

Tracing is W3C Trace Context, propagated and read through OpenTelemetry — not a house header or a WSGI middleware.

# manage.py, wsgi.py, asgi.py — before Django loads
from opentelemetry.instrumentation.django import DjangoInstrumentor

DjangoInstrumentor().instrument()

DjangoInstrumentor inserts its own middleware into MIDDLEWARE at position 0, so it wraps everything downstream — including the exception handler. rn_forge.django.tracing.instrument() (the otel extra) does this call and also installs a TraceResponsePropagator when the application has not already set one.

2. Errors — a DRF exception handler

# myapp/handlers.py
from rest_framework.exceptions import ValidationError
from rest_framework.response import Response

from rn_forge.web import PROBLEM_MEDIA_TYPE, default_registry, field_error, render_problem

REGISTRY = default_registry()   # register your domain exceptions here, once

def problem_exception_handler(exc, context):
    request = context.get("request")
    extensions = {}
    if isinstance(exc, ValidationError) and isinstance(exc.detail, dict):
        # The DRF-shaped part: {field: [messages]} to RFC 9457 field errors.
        extensions["errors"] = [
            field_error((name,), str(message))
            for name, messages in exc.detail.items()
            for message in messages
        ]
    rendered = render_problem(
        REGISTRY,
        exc,
        instance=request.path if request is not None else "",
        extensions=extensions,
    )
    response = Response(
        rendered.body, status=rendered.status, content_type=PROBLEM_MEDIA_TYPE
    )
    for name, value in rendered.headers.items():
        response[name] = value
    return response

render_problem adds the current trace id, masks a 401's detail and adds its challenge. rn-forge-django's handler also walks nested serializer errors.

Set EXCEPTION_HANDLER to it in REST_FRAMEWORK. Register DRF's own exception classes (NotFound, PermissionDenied, ...) on REGISTRY once, rather than branching in the handler — the MRO walk then covers their subclasses for free.

3. Concurrency

from rn_forge.web import EntityVersionETagCodec, check_precondition

CODEC = EntityVersionETagCodec()

class VersionedMixin:
    def finalize_response(self, request, response, *args, **kwargs):
        obj = getattr(self, "_etag_object", None)
        if obj is not None:
            response["ETag"] = CODEC.format(entity_id=obj.pk, version=obj.version)
        return super().finalize_response(request, response, *args, **kwargs)

    def check_version(self, obj, *, required=True):
        check_precondition(
            self.request.headers.get("If-Match"),
            current_version=obj.version,
            entity_id=obj.pk,
            required=required,
        )

4. Idempotency — a cache-backed store

cache.add() is load-bearing. It is an atomic set-if-absent; a get-then-set adapter silently loses the race safety the protocol requires, and no ordinary test will notice.

from django.core.cache import cache
from rn_forge.web import IdempotencyKeyReuse, StoredResponse, request_hash

TTL = 60 * 60 * 24

class CacheIdempotencyStore:
    def record_or_replay(self, *, scope, key, request_body):
        slot = f"idempotency:{len(scope)}:{scope}:{key}"  # length prefix: no ":" collisions
        digest = request_hash(request_body)

        if cache.add(slot, {"hash": digest, "response": None}, TTL):
            return None                                  # we claimed it; first sight

        entry = cache.get(slot)
        if entry is None:                                # expired between add and get
            return None
        if entry["hash"] != digest:
            raise IdempotencyKeyReuse(
                "Idempotency key {} was replayed with a different request body",
                key, error_code=409,
            )
        stored = entry["response"]
        if stored is None:
            return None                                  # claimed, still in flight
        return StoredResponse(status=stored["status"], body=stored["body"], replayed=True)

    def complete(self, *, scope, key, status, response_body):
        slot = f"idempotency:{len(scope)}:{scope}:{key}"
        entry = cache.get(slot) or {"hash": None, "response": None}
        entry["response"] = {"status": status, "body": dict(response_body)}
        cache.set(slot, entry, TTL)

Use a shared cache backend. LocMemCache gives each worker process its own dictionary, which makes the store a no-op under any real deployment.

5. Health — a view over the sync runner

from django.db import connection
from django.http import JsonResponse
from rn_forge.web import CheckResult, run_checks_sync

def check_db():
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
    return CheckResult(status="pass")

def readyz(request):
    report = run_checks_sync({"db": check_db}, required=["db"])
    return JsonResponse(report.as_body(), status=report.http_status)

def healthz(request):
    return JsonResponse({"status": "pass"})   # liveness touches nothing

run_checks_sync, not run_checks — and it will raise rather than let an async def check be reported as passing.

6. Casing

Wire a camelCase renderer and parser through REST_FRAMEWORK, so the rule holds by default rather than per serializer. rn-forge-django ships them; a recipe here would be a convention that holds until the first hurried endpoint.

7. Pagination

Subclass DRF's own CursorPagination and emit the AIP-158 envelope from get_paginated_response / get_paginated_response_schema. DRF's keyset filter compares one position and skips ties with an offset held in its cursor; the shared token carries a sort value and a primary key instead, so rn_forge.django.drf.pagination.CursorPagination overrides paginate_queryset to filter on that pair. Use it rather than writing another.

Conformance

Once the above is wired, the driver is short:

import pytest
from rn_forge.web.conformance import case_by_id, cases_provided_by, redact

def issue(client, case):
    return client.generic(
        case.request.method, case.request.path,
        data=case.request.body, headers=case.request.headers, **case.request.query,
    )

@pytest.mark.parametrize("case", cases_provided_by(), ids=lambda c: c.id)
def test_conformance(client, case):          # `client` must be a FRESH app per case
    for prerequisite in case.depends_on:     # a replay only replays something
        issue(client, case_by_id(prerequisite))

    response = issue(client, case)
    assert response.status_code == case.expect_status
    for name, value in case.expect_headers.items():
        assert response[name] == value
    for name in case.expect_absent_headers:
        assert name not in response
    assert redact(response.json()) == dict(case.expect_body)

cases_provided_by() omits the cases that need an optional capability (session-routes, csrf); pass the set the application serves to include them.

Two things this driver must get right: a fresh application per case (the idempotency store must not carry over), and depends_on issued first.

Assert against the table, never against what FastAPI produced.