perf: serve video-detail cache entries as raw bytes, dropping the GIL-held parse

[groupthinking]

Canonical issue

Closes #1306

Outcome

GET /api/v2/videos/{video_id} no longer stalls the event loop in proportion to payload size. The handler only ever returned the parsed cache entry verbatim, so _read_video_analysis_sync now returns the entry's raw JSON bytes (read() releases the GIL) and the handler streams them back in a Response. This removes both the GIL-held json.load (~3 ms/MB, only relocated by #1304) and FastAPI's on-loop re-serialisation of the parsed dict, which paid the same size-proportional cost a second time.

Entries at or below _VALIDATION_MAX_BYTES (2 MiB — ~13× a typical one-hour transcript) are still parse-validated off-loop, so damaged entries keep surfacing as 500s. That threshold is the loop-stall bound: ~6 ms worst case, independent of video duration. Larger entries skip validation; the writer publishes atomically (temp file + os.replace), so a torn entry cannot be observed — only out-of-band corruption of an oversized entry would reach a client unflagged, accepted in exchange for the bounded stall.

The warm-cache regression disclosed in #1304 (executor hop costing more than the deferred 0.4 ms parse) is resolved by removing the parse and the on-loop re-serialisation outright; the fixed ~0.5 ms dispatch hop remains, deliberately, as insurance against unbounded filesystem latency.

Scope

• Included: _read_video_analysis_sync, the /api/v2/videos/{video_id} handler, and their tests. The characterisation test test_parse_still_stalls_the_loop_in_proportion_to_payload is replaced by its successor test_read_stall_no_longer_scales_with_payload, self-calibrated against json.loads of the same payload on the runner.
• Explicitly excluded: real_video_processor.py (held by perf: offload cache-directory scan off the event loop (#1231) #1237) — the entry-size cause (persisting the full transcript) is untouched.

Risk

• Risk level: low
• Failure mode: the response body is now the cache entry byte-for-byte instead of a re-serialised copy (semantically identical JSON; formatting/whitespace may differ). A corrupt entry above 2 MiB would be served verbatim instead of returning a 500.
• Rollback: revert the commit; the endpoint returns to parse-and-re-serialise.

Verification

• Focused tests: pytest tests/unit/test_real_api_endpoints.py — 107 passed at ec45eed, including new coverage for byte-for-byte passthrough, the inclusive validation boundary, oversized unvalidated entries, and the bounded-stall characterisation test (run 5× for flake resistance)
• Required CI
• Review threads resolved

Ruff/black were checked on the changed files; remaining findings are pre-existing in untouched regions.

Production evidence

Not applicable — backend perf change verified by the loop-gap characterisation test, which measures the stall directly against the old behaviour (json.loads of the same payload).

Agent provenance

Agent-authored via Linear agent session; run metadata is recorded in the linked Linear issue (GRV-282, agent session 36eebe27).

[linear-code]

GRV-282

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-uvai	Canceled	v0	Aug 4, 2026 6:17am

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• [‘architecture-gap’, ‘bug’, ‘ci-cd’, ‘ci/cd’, ‘copilot-rabbit’, ‘documentation’, ‘duplicate’, ‘enhancement’, ‘frontend’, ‘github_actions’, ‘good first issue’, ‘help wanted’, ‘high-priority’, ‘invalid’, ‘javascript’, ‘ml-model’, ‘needs-triage’, ‘pipeline-critical’, ‘placeholder-code’, ‘priority:high’, ‘python’, ‘python:uv’, ‘question’, ‘styling’, ‘tests’, ‘v0’]

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d79aef2e-3f84-4a39-a6ce-ae2acfa0227a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA ec45eed.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[github-actions]

Agent Completion Truth Gate: BLOCKED

Reasons: invalid_payload

Machine-readable verdict

{
  "details": {
    "collection_errors": [
      "incomplete_linked_issue_contract",
      "missing_intent_snapshot",
      "missing_agent_run_id",
      "missing_agent_login"
    ],
    "invalid_fields": [
      "policy.agent_login",
      "policy.run_id"
    ]
  },
  "reasons": [
    "invalid_payload"
  ],
  "verdict": "blocked"
}

Workflow evidence

[Copilot]

Pull request overview

Optimizes video-detail cache responses by eliminating payload-sized parsing and re-serialization from the request path.

Changes:

• Returns cached JSON as raw bytes with bounded validation.
• Serves bytes directly as an application/json response.
• Adds regression and boundary coverage for the new behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/youtube_extension/backend/real_api_endpoints.py	Implements validated raw-byte cache passthrough.
tests/unit/test_real_api_endpoints.py	Tests passthrough, validation boundaries, and loop responsiveness.