Rust VOD Module
Replacing nginx-vod-module with a standalone Rust service for on-the-fly MP4 → HLS repackaging.
Why
The VOD delivery path runs on nginx-vod-module, a C module compiled into NGINX in remote mode. It fetches MP4 files from a CDN origin, parses the moov atom, and generates .m3u8 manifests plus .ts/.m4s segments on the fly, with no transcoding and no local storage. Metadata and responses are cached in shared memory; segments align to key frames at a 2-second target duration.
The module works, but its limits are structural. It bloats memory under high concurrency, exposes nothing beyond error_log for observability, and carries buffer-management issues with NGINX subrequests since 1.13. It offers no circuit breaker or graceful degradation when the upstream origin fails. Extending it means writing C tightly coupled to NGINX internals.
This research asks whether a standalone Rust service can own MP4 → HLS repackaging as its own process, keeping NGINX in front for TLS and static caching, while treating streaming, caching, and observability as first-class concerns.
Scope
- MVP target: on-the-fly MP4 → HLS repackaging as a remote proxy, fMP4 (
.m4s) output only, no transcoding. - Feature parity with the current
remotemode: metadata cache, response cache, segment-duration control, key-frame alignment, WebVTT pass-through. - New capabilities absent from the C module: structured
tracinglogs, Prometheus metrics, hot config reload, upstream graceful degradation. - Assessment of the Rust ecosystem:
mp4parsefor demuxing, Axum/Tokio for async streaming,reqwestfor ranged upstream fetches,mokafor concurrent caching. - Deferred past MVP: MPEG-TS segments, DASH manifests, DRM/encryption, multi-audio and multi-subtitle track selection.
Problems & Solutions
Moov atom positioning
Many MP4 files place moov at end of file. The service fetches the file tail first via an HTTP range request, parses the moov, then issues targeted range reads into mdat for sample data — the same two-pass strategy the C module uses, avoiding a full-file download.
Sample table navigation
Locating the exact byte range of each sample requires walking the stts→stsc→stsz→stco/co64 chain. mp4parse parses these tables but exposes no iterator, so the design adds a custom sample navigator that maps presentation time and sample index to concrete offsets.
Segment generation without a TS muxer
No production-grade MPEG-TS muxer exists in Rust. fMP4 sidesteps this entirely: segments are built by repackaging existing atoms rather than muxing an elementary stream, which modern HLS (v7+) plays natively. TS support moves to a later phase.
Key-frame alignment
Segment boundaries must land on sync samples. The builder reads the stss table and maps segment cuts to IDR frames, matching the module’s vod_align_segments_to_key_frames behavior.
Memory and observability under load
Streaming response bodies with backpressure through Axum, plus zero-copy buffers (bytes) and moka’s lock-free concurrent cache, keep per-connection memory low. tracing and metrics-exporter-prometheus give per-request visibility the C module never had.
Architecture
NGINX stays at the edge for TLS, static caching, and load balancing. The Rust service runs as a separate process: Axum routes each manifest or segment request, the parser and sample navigator resolve byte ranges, reqwest fetches only those ranges from the origin, and the segment builder emits fMP4 — with both moov metadata and generated responses cached in memory.