gps-denied-onboard/_docs/03_implementation/batch_102_cycle2_report.md

Batch 102 — Cycle 2 — AZ-701

Date: 2026-05-20 Tasks: AZ-701 (HTTP replay API service). Story points: 5. Jira status: AZ-701 → In Testing.

What shipped

A new operator-side replay_api component — a FastAPI service that wraps the offline gps-denied-replay pipeline behind HTTP. Operators can POST a multipart (tlog + video [+ calibration]) payload and receive back either a synchronous result (small flights) or a 202-job-id for polling (large flights). Once a job completes, the JSONL emissions, the AZ-700 HTML map, and the AZ-699 accuracy report are served as static files under stable URLs.

Estimator code is unchanged — the service shells out to the existing gps-denied-replay and gps-denied-render-map console scripts. The contract explicitly forbids re-implementing the pipeline in the API layer.

Bearer-token auth is on by default (configurable env var), magic-byte validation rejects misnamed uploads at the door, and a thread-pool worker enforces a max_concurrent / max_queued cap with a 429 on overflow.

Files changed

Production (10):

• src/gps_denied_onboard/replay_api/__init__.py (new)
• src/gps_denied_onboard/replay_api/errors.py (new — typed HTTP error families with stable error_code strings)
• src/gps_denied_onboard/replay_api/interface.py (new — DTOs, JobState enum, ReplayRunner Protocol seam for DI)
• src/gps_denied_onboard/replay_api/storage.py (new — per-job temp-dir lifecycle)
• src/gps_denied_onboard/replay_api/jobs.py (new — JobRegistry with concurrency/queue limits and ThreadPoolExecutor)
• src/gps_denied_onboard/replay_api/handlers.py (new — magic-byte validation, size limits, bearer-token extraction)
• src/gps_denied_onboard/replay_api/app.py (new — FastAPI factory and SubprocessReplayRunner)
• src/gps_denied_onboard/cli/replay_api_entrypoint.py (new — replay-api console script)
• src/gps_denied_onboard/helpers/accuracy_report.py (promoted from tests/e2e/replay/_report_writer.py; needed at runtime by the API)
• src/gps_denied_onboard/helpers/__init__.py (re-exports)

Tests (1):

• tests/unit/replay_api/test_az701_replay_api.py (18 tests, all PASS local)

Docs / contract (2):

• _docs/02_document/contracts/replay_api/replay_api_protocol.md (new)
• _docs/02_document/contracts/replay_api/openapi.yaml (new — exported from the running FastAPI app)

Docker / CI (2):

• docker/replay-api.Dockerfile (new)
• e2e/docker/docker-compose.test.yml (added replay-api service + replay-api-storage volume, profile replay-api)

Build / packaging (1):

• pyproject.toml (fastapi, uvicorn, python-multipart added to [operator-tools] extra; replay-api console script registered)

Imports updated (re-pointed to promoted helper) (3):

• tests/e2e/replay/test_derkachi_real_tlog.py
• tests/unit/test_az699_report_writer.py
• tests/e2e/replay/_report_writer.py was deleted (replaced by the promoted production module)

AC coverage

AC	Status	Evidence
AC-1 sync 200	Pass	test_post_replay_sync_returns_200_with_result_urls + test_post_replay_serves_jsonl_and_map_for_done_job
AC-2 async 202	Pass	test_post_replay_async_returns_202_when_video_exceeds_sync_bytes
AC-3 job state	Pass	test_job_state_transitions_observable_via_polling, test_failed_runner_marks_job_failed, test_result_endpoints_409_when_job_not_done
AC-5 401 unauth	Pass	test_post_replay_returns_401_without_bearer_when_required, test_post_replay_accepts_correct_bearer
AC-6 health	Pass	test_healthz_always_returns_200, test_readyz_returns_503_when_binary_missing
AC-8 concurrency	Pass	test_concurrency_limit_queues_excess_jobs, test_queue_full_returns_429
AC-9 magic-byte	Pass	4 tests covering tlog + video validators (unit) and end-to-end POST rejection

Test run summary

• AZ-701 unit slice (tests/unit/replay_api/): 18/18 passed in 4 s.
• Full unit suite: 2251 passed, 86 skipped, 1 failed in 85 s.
  • The single failure is tests/unit/c12_operator_orchestrator/test_cli_console_script.py::TestConsoleScript::test_cold_start_under_500ms_p99. It is a pre-existing C12 CLI cold-start performance flake. AZ-701 doesn't touch C12 and the same failure shows up in batch 100 and batch 101 reports. Non-blocking for AZ-701.
• Mypy --strict on AZ-701 surface (src/gps_denied_onboard/replay_api/, helpers/accuracy_report.py, cli/replay_api_entrypoint.py): clean — 9 source files, 0 errors.

Strict typing

All new modules in src/gps_denied_onboard/replay_api/* are strict-typed (no implicit Any, no untyped defs, no untyped decorators). The folium-style untyped-third-party shim is not needed here — FastAPI, Pydantic, uvicorn, and python-multipart all ship typestubs that mypy --strict accepts.

Notable design decisions

• Subprocess runner, not in-process estimator. The contract invariant is "the API layer does NOT re-implement the pipeline." SubprocessReplayRunner shells out to gps-denied-replay --auto-trim and then gps-denied-render-map. Easy to swap for a fake in tests via the ReplayRunner Protocol DI seam.
• Magic-byte validation is mandatory (AC-9). Misnamed .tlog / .mp4 payloads are rejected at the door with a stable error_code. No content-type sniffing fallback.
• Bearer auth is opt-out, not opt-in. Default state of the service is "auth required, token missing → 503 at startup" unless the operator explicitly sets REPLAY_API_AUTH_REQUIRED=false for a dev environment.
• In-memory state by design. The contract says "no persistent state across restarts" — jobs don't survive a process restart and the storage root is wiped on shutdown. Operators wanting durability must layer it externally.
• from __future__ import annotations dropped in app.py only. FastAPI 0.119 + Pydantic v2 resolve route-parameter annotations at decoration time and reject forward-ref strings. The rest of the replay_api package keeps the future-annotations import. The reason is recorded in app.py's module docstring.
• _report_writer.py was promoted from tests/ to src/. The API needs to produce the AZ-699 Markdown accuracy report at runtime; that module was previously test-only. All AZ-699 imports re-pointed to gps_denied_onboard.helpers.accuracy_report.

Known limitations carried forward

• No request-body streaming — python-multipart buffers each part. Hard 2 GB cap guards memory.
• No rate limiting beyond max_concurrent / max_queued. A reverse proxy is the right layer for that.
• SubprocessReplayRunner discards stdout/stderr on the success path; operators wanting per-job audit logs need a follow-on.
• The Derkachi real-flight e2e test (AZ-699's test_derkachi_real_tlog.py) already exercises the underlying pipeline. A dedicated end-to-end replay_api test against real artefacts is not in scope here per the testing-environment policy (e2e → Jetson only).