Skip to content

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 the bad-request problem, matching DRF's ParseError. The body is still parsed before the key check; no new rn_forge.web exception.

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.