|
| 1 | +# Transparent Proxy Hardening Design |
| 2 | + |
| 3 | +## Context |
| 4 | + |
| 5 | +PR #2462 adds transparent authoring proxies for browser-hostile codecs. Its server-side |
| 6 | +FFmpeg architecture is the correct foundation: Chrome Headless Shell cannot decode HEVC |
| 7 | +through WebCodecs, and MediaBunny server support ultimately wraps FFmpeg through NodeAV. |
| 8 | +The review found lifecycle, policy, and coverage gaps that must be resolved before merge. |
| 9 | + |
| 10 | +## Goals |
| 11 | + |
| 12 | +- Preserve transparent preview recovery for hostile HEVC and ProRes media. |
| 13 | +- Never destroy alpha as an accidental fallback. |
| 14 | +- Bound CPU, memory, queue, cache, and caller wait time. |
| 15 | +- Apply one proxy policy consistently across scan, runtime rescue, check, and publish. |
| 16 | +- Make path lookup safe across Unicode/case differences without allowing project escapes. |
| 17 | +- Make partial publish behavior explicit and test render/publish separation with real media. |
| 18 | +- Preserve the existing system-FFmpeg subprocess boundary and zero new media runtime dependency. |
| 19 | + |
| 20 | +## Non-goals |
| 21 | + |
| 22 | +- Replacing FFmpeg with MediaBunny or NodeAV in this PR. |
| 23 | +- Proxying alpha-bearing media to opaque H.264. |
| 24 | +- Changing final render inputs or silently publishing incomplete hostile-media coverage. |
| 25 | + |
| 26 | +## Architecture |
| 27 | + |
| 28 | +### 1. Canonical project media identity |
| 29 | + |
| 30 | +Create one resolver used by codec-map lookup and proxy resolution: |
| 31 | + |
| 32 | +1. Resolve the authored path exactly first. |
| 33 | +2. Build a project-relative index normalized to POSIX separators, Unicode NFC, and lowercase. |
| 34 | +3. Use the normalized fallback only when it maps to exactly one file; ambiguous case/Unicode |
| 35 | + collisions fail explicitly. |
| 36 | +4. Resolve symlinks with real paths and reject any source outside the real project root. |
| 37 | + |
| 38 | +The codec map stores canonical relative identities so scan and runtime rescue cannot disagree. |
| 39 | + |
| 40 | +### 2. One alpha-aware proxy policy |
| 41 | + |
| 42 | +Centralize the decision into a single policy function consumed by: |
| 43 | + |
| 44 | +- initial scan and prewarm, |
| 45 | +- mapped runtime recovery, |
| 46 | +- unlisted/runtime rescue, |
| 47 | +- check-browser recovery, |
| 48 | +- publish bake. |
| 49 | + |
| 50 | +Unknown/unlisted media is probed before transcoding. Alpha-bearing media is returned as an |
| 51 | +explicit unsupported result and is never sent through the opaque H.264 proxy path. Browser-safe |
| 52 | +mapped media follows the same policy at every runtime fallback tier. |
| 53 | + |
| 54 | +### 3. Bounded transcode lifecycle |
| 55 | + |
| 56 | +- Keep the two-process transcode semaphore. |
| 57 | +- Add a bounded wait queue and a typed overload error mapped to HTTP 503 plus Retry-After. |
| 58 | +- Deduplicate in-flight work by canonical cache key. |
| 59 | +- Cache transient failures only for a short TTL; keep FFmpeg-unavailable recoverable immediately. |
| 60 | +- Give publish/check callers explicit bounded waits. Caller timeout does not cancel shared work; |
| 61 | + it returns a typed timeout while the deduplicated transcode may finish and warm the cache. |
| 62 | +- Preserve subprocess timeout/SIGKILL and atomic temp-then-rename behavior. |
| 63 | + |
| 64 | +### 4. Bounded cache |
| 65 | + |
| 66 | +Maintain cache metadata from file stat data and sweep opportunistically at a rate-limited cadence. |
| 67 | +Defaults: |
| 68 | + |
| 69 | +- 30-day maximum idle age, |
| 70 | +- 10 GiB maximum total size, |
| 71 | +- oldest-accessed entries removed first, |
| 72 | +- active/in-flight entries excluded, |
| 73 | +- stale temp files removed separately. |
| 74 | + |
| 75 | +Environment/config overrides allow constrained machines to lower the cap. Cache cleanup failures |
| 76 | +are warnings, never preview failures. |
| 77 | + |
| 78 | +### 5. Complete CLI/config plumbing |
| 79 | + |
| 80 | +Carry the resolved proxy setting through regular preview, dev, local-studio, and static server |
| 81 | +spawn paths. Both positive and negative CLI flags override config consistently. Add contract tests |
| 82 | +that exercise the final staticProjectServer arguments instead of only parser-level values. |
| 83 | + |
| 84 | +### 6. Explicit publish outcome |
| 85 | + |
| 86 | +Publish bake returns a structured manifest containing proxied, intentionally skipped, and failed |
| 87 | +assets. Hostile non-alpha failures stop publish with the asset list; alpha skips remain explicit. |
| 88 | +Callers surface the manifest in diagnostics so an incomplete publish cannot become a silent black |
| 89 | +frame. Final render/cloud-render archive creation remains on the original-media path. |
| 90 | + |
| 91 | +### 7. Regression coverage |
| 92 | + |
| 93 | +Tests must cover: |
| 94 | + |
| 95 | +- unlisted alpha rescue never invoking H.264 transcode, |
| 96 | +- transient failure expiry, |
| 97 | +- queue overload and HTTP 503 mapping, |
| 98 | +- case/Unicode fallback plus ambiguity rejection, |
| 99 | +- symlink/project containment, |
| 100 | +- publish/check caller timeout, |
| 101 | +- complete proxy flag forwarding, |
| 102 | +- cache size/age eviction while preserving in-flight entries, |
| 103 | +- publish manifest behavior, |
| 104 | +- reactive/tertiary policy parity, |
| 105 | +- bounded probe caches and global probe concurrency, |
| 106 | +- preview-script escaping, |
| 107 | +- a real hostile-codec fixture proving publish bake changes authoring archives while |
| 108 | + render/cloud-render archives remain byte-identical and proxy-free. |
| 109 | + |
| 110 | +## Alternatives |
| 111 | + |
| 112 | +### Explicit pre-bake only |
| 113 | + |
| 114 | +This removes on-demand queueing but loses transparent cold-preview recovery. Rejected because it |
| 115 | +regresses the core authoring experience #2462 is meant to provide. |
| 116 | + |
| 117 | +### MediaBunny replacement or hybrid |
| 118 | + |
| 119 | +Browser MediaBunny inherits WebCodecs HEVC limits; its ProRes path adds a WASM extension and its |
| 120 | +server path adds NodeAV native bindings over FFmpeg. It would remove little application lifecycle |
| 121 | +code while weakening subprocess isolation. Rejected for this PR; a metadata-only spike can be |
| 122 | +evaluated independently later. |
| 123 | + |
| 124 | +## Rollout and merge gate |
| 125 | + |
| 126 | +The material head requires fresh adversarial review from Via and Rames, all required CI green, |
| 127 | +mergeable/dependency-clean state, and no unresolved human feedback. Skill-facing files already in |
| 128 | +the PR require Wenbo and Miao visibility before merge. |
0 commit comments