Adoption checklist
For an application's own review. Each item is phrased so the answer is checkable in the codebase rather than in someone's memory — the failure mode this catches is an application that uses the primitives almost everywhere.
Tracing
- [ ]
traceparent/tracestateare the only trace headers read or written. - [ ] The application configures a
TracerProvider(or runs underopentelemetry-instrument);rn_forge.webnever does. - [ ] The log configuration includes
rn_forge.commons.logging.structlog.otel_processor. - [ ] No module defines its own request-id ContextVar or header constant.
Errors
- [ ] Every error response goes through the registry.
grep -rn '"error"\|"detail":'finds no hand-built error body. - [ ] Domain exceptions are registered on the application's registry instance at startup, in one place.
- [ ] The registry is an instance, not a mutated module-level default.
- [ ] No handler branches on
status_codewhere a registration would do. - [ ] A 5xx response body has been eyeballed in a real failure: it contains no exception message, no stack frame and no connection string.
- [ ] Validation errors come out as RFC 6901 pointers, including for a nested object — tested, not assumed.
Concurrency
- [ ] Every mutating endpoint on a versioned resource either requires
If-Matchor has a written reason not to. - [ ] Read responses for those resources carry an
ETag. - [ ] No endpoint returns 409 for a stale precondition.
- [ ] No endpoint accepts a version from the request body in place of the header.
Pagination
- [ ] Every collection endpoint is cursor-paginated, or its specification says why it is page-number.
- [ ] No
pageSizevalidator rejects an over-large value. On FastAPI:grep -rn "le="finds nopageSizeconstraint. This is the single easiest divergence to introduce. - [ ]
nextPageTokenisnull, not absent, on the last page. - [ ]
totalSizeappears only where an endpoint opted in and pays for a count. - [ ] No client code, and no test, parses or constructs a
pageToken.
Idempotency
- [ ] Every unsafe endpoint a client may retry accepts
Idempotency-Key. - [ ] The store's claim is atomic —
cache.add(), orON CONFLICT DO NOTHING— and not agetfollowed by aset. - [ ] The cache backend is shared across worker processes. It is not
LocMemCache. - [ ] Replaying a key with a different body has been tested and returns 409.
- [ ]
scopedistinguishes endpoints (and tenants, where relevant).
Health
- [ ]
/healthztouches no dependency. - [ ]
/readyznames every external dependency the process needs, including the ones that are not configured yet — asskipped, not omitted. - [ ]
requiredcontains exactly the dependencies whose loss should take the instance out of the load-balancer pool, and no more. - [ ]
/readyzhas been exercised with a dependency actually down, and returned 503 rather than 500.
Auth
- [ ] Missing or invalid credentials → 401 with a challenge.
- [ ] Insufficient scope → 403 without one.
- [ ] The 401 body is byte-identical whether the token was expired, badly signed or issued by an unknown key.
- [ ] Basic auth, if enabled, is documented as non-production and is off in the production configuration.
Casing and schema
- [ ] The camelCase renderer/parser is wired globally, not per serializer.
- [ ] The emitted schema is OpenAPI 3.1.0.
- [ ]
ProblemDetail,Page,CheckResultandHealthReportappear incomponents/schemasunder exactly those names. - [ ]
ProblemDetailis present even though no route declares it as a response model — the explicit injection is in place. - [ ]
operationIds follow the shared convention.
Conformance
- [ ] The conformance driver is present and every case in
rn_forge.web.conformance.CASESpasses. - [ ] The driver asserts against the table, not against another stack's recorded output.
- [ ] The driver needs no redaction of its own beyond
redact. If it does, that is the finding — report it upstream rather than working around it.