feat(moq-hls)!: expose a credential-aware serve surface for embedders

[kixelated]

Lets a consumer embed the fetch-on-demand HLS origin as a library and put its own authorization in front, without a policy hook inside this crate.

Motivation: moq.pro's relay serves live HLS off its in-process origin (moq-dev/moq.pro#695), authorizing each request against its existing token verifier and subscribe scoping.

The new public surface (4 items)

Server::broadcaster()        // the shared, fanned-out pool
Rendition::media_playlist()  // render this rendition's playlist (None until playable)
Rendition::segment()         // fetch one segment by sequence
Rendition::playable()        // await readiness

renditions and segments were already public and already expose this data — but as cursors (Consumer::next()), which is the right shape for a recorder walking a stream once and the wrong shape for a server answering arbitrary sequence numbers for many viewers sitting at different positions. Random access by sequence is the one capability those cursors cannot express; that's what this adds.

Everything an embedder can derive stayed private, so this does not re-widen what #2423 just narrowed:

• Snapshot, Segment, render_media remain crate-internal — media_playlist returns the rendered String instead of leaking the intermediate, and returns None when nothing is playable yet, which also subsumes is_playable.
• Broadcaster::is_empty — a ready() timeout already means the catalog is empty.
• Rendition::init — segments::Consumer::init is already public and literally delegates to it.

Server::broadcaster is the one genuinely new capability. The alternative — a consumer keeping its own broadcaster map — would need Broadcaster::{is_closed, closed} promoted instead (more surface) plus duplicated evict-on-close logic.

No Authorizer/callback trait: the dependency arrow stays one-way and this crate keeps knowing nothing about tokens.

Credential propagation

The renderers emit relative child URLs (<kind>/<name>/media.m3u8, init.mp4, seg/<n>.m4s). A stock player — Safari especially — does not replay request headers onto those follow-ups, so a token supplied only via Authorization/?jwt= on the master request is gone by the time the player fetches a segment. An optional query (e.g. jwt=<token>, no leading ?) is appended to every child URL. It's a plain value, not a policy: the caller decides the parameter name.

It's an argument rather than a Config field on purpose. Config is pool-wide (Server::new stores one, every broadcaster clones it) while one broadcaster fans out to viewers holding different tokens — so a credential in Config would embed one viewer's JWT in another viewer's playlist. Deployment-scoped policy (a future signing key) would belong in Config; this cannot.

Server::router() is unchanged in behaviour and still works as the no-auth convenience path; it now propagates whatever query reached each playlist, so it also works behind token-in-URL auth middleware.

Breaking

Broadcaster::master_playlist takes a query argument. render_media/render_master gained the same argument but are crate-private after #2423, so they aren't public API. Marked feat! + BREAKING CHANGE: so the release tooling classifies the bump.

Testing

cargo test -p moq-hls — 49 pass + doctests, including new coverage that a credential rides the EXT-X-MAP URI, every segment URI, and both audio and video child playlist URIs. clippy + fmt clean, with and without the server feature.

Not yet exercised against live media end-to-end; that check lives downstream in moq.pro and is still outstanding.

Note for reviewers

server/routes.rs matches the broadcast with a single {broadcast} path segment, so a multi-segment broadcast path (<pid>/<name>, or anything the RTMP gateway prefixes a project name onto) never routes. This PR doesn't change that — the downstream consumer works around it with its own catch-all — but it looks like a bug in the built-in router.

(written by Opus 4.8)

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}