F22.10 — FastAPI adapters with clear validation boundaries
| State | Closed |
| Parent | E22 |
| Iteration | Release 9 |
| Start Date | 2026-11-14 |
| Closed Date | 2026-11-16 |
| Predecessors | F22.8 for shared-policy changes |
Stories: 3 Closed
| Story | State | Depends on |
|---|---|---|
| S22.10.1 — Validate only where required | Closed (2026-11-14) | — |
| S22.10.2 — Keep route assembly thin | Closed (2026-11-16) | S22.8.2, S22.10.3 |
| S22.10.3 — Set the transfer resource targets | Closed (2026-11-16) | S22.3.2 |
Keep asynchronous orchestration in FastAPI and use shared policy for identity and HTTP decisions.
Context
idempotency.py:66-72 eagerly parses every body, even for safe methods, outside
normal validation. A Request-only endpoint can raise an unhandled
JSONDecodeError. Transfer spans response formats, parsing and five router
builders in 936 lines; auth routes/sessions/dependencies repeat neutral policy
and mix blocking work with async orchestration.
S22.10.1 — Validate only where required
State: Closed (2026-11-14)
Bypass idempotency work for safe methods before reading/parsing their body. Define the failure response for malformed unsafe JSON through the agreed web/framework error contract.
Acceptance:
- GET with arbitrary bytes reaches its handler without idempotency parsing.
- Malformed unsafe JSON, absent key, mismatch, in-flight and successful replay have explicit response and handler-count assertions.
- Original response headers survive first execution and the documented replay contract remains unchanged.
- Malformed unsafe JSON raises
fastapi.HTTPException(400, "Request body is not valid JSON"), rendered as thebad-requestproblem, matching DRF'sParseError. The body is still parsed before the key check; no newrn_forge.webexception.
Outcome: before this story, malformed JSON returned a 422 validation-error problem and a safe request's body was parsed; both are fixed.
S22.10.2 — Keep route assembly thin
State: Closed (2026-11-16) · Depends on: S22.8.2, S22.10.3
Consume F22.8 policy/codecs, and separate transfer parsing/serialization from router assembly by responsibility. Preserve the existing public module imports.
Acceptance:
- Settled by the owner in S22.10.3 (2026-11-16), per case in the S22.10.3 baseline: memory M1 (CSV export at most 1 MiB; import at most 25/230 MiB and batch create at most 36/350 MiB at 10,000/100,000 rows); loop delay L2 (batch create at most 75/750 ms, every other case within 25% of baseline); wall time W2 (CSV export at most 0.30/3.0 s through chunked streaming, every other case within 25% of baseline). XLSX library speed is out of scope (F25.2).
- Cookie/CSRF, inactive-account, tenant/scope and authorization-refresh cases pass through actual routes.
- Multipart/JSON imports, dry-run, batch atomicity, row errors and response headers retain integration coverage.
- Blocking provider/file/encoding work stays off the event loop where required; heartbeat tests use controlled coordination.
- Measured transfer memory/event-loop delay improves or stays within the target S22.10.3 set.
Outcome: CSV export streams 1,000-row chunks (100,000 rows: 0.79 s, peak 627
KB); batch create parses the body through a private threaded route class,
validates each item once in a worker thread and builds the response there
(100,000 rows: lag 0.50 s, peak 225 MB). Private helpers live in _tabular.py
and _batch.py; figures are in the performance baselines guide.
S22.10.3 — Set the transfer resource targets
State: Closed (2026-11-16) · Depends on: S22.3.2
Measure peak memory and event-loop delay for large transfer imports and exports, and set the target S22.10.2 must meet.
Acceptance:
- A recorded baseline and target name the inputs, environment, peak memory and event-loop delay.
Decision (owner, 2026-11-16): memory M1, loop delay L2, wall time W2, recorded
in S22.10.2's acceptance. Causes found: CSV export makes one worker-thread hop
per row (12.1 s for 100,000 rows); batch create parses and validates the body
twice on the loop (1.34 s stall); XLSX time is in write_xlsx and tablib
(parked as an idea).
Outcome: an 11-case opt-in FastAPI transfer measurement with an event-loop heartbeat, and its three-run baseline in the performance guide.
Acceptance
- S22.10.1: GET with arbitrary bytes reaches its handler without idempotency parsing.
- S22.10.2: Cookie/CSRF, inactive-account, tenant/scope and authorization-refresh cases pass through actual routes.
- S22.10.3: A recorded baseline and target bound transfer memory and delay.