Module server 

Available on crate feature std only.

LL-HLS origin engine (issue #663/#717 Stage 2; plan step 4): the blocking-reload + part-availability decision logic and playlist rendering, driven directly from a shared media_plane::Trunk — not a push-fed rolling-window store of its own.

Sans-IO shape

Nothing here ever .awaits or opens a socket. HlsOrigin implements media_plane::egress::ServedEgress: its resolve is a poll method returning media_plane::egress::EgressResponse — Ready, Await, BadRequest, or NotFound — never blocking the caller. The only asynchrony is media_plane::Trunk::listen, which hands back a runtime-agnostic event_listener::EventListener (a plain Future<Output = ()>) that any executor can await or time out — not a tokio::sync::watch.

The caller-driven wait loop

An async adapter (e.g. multimux’s Step 5 LL-HLS route) turns an Await into an actual wait like this — the same shape MediaStore’s own (now-deleted) wait loop used, unchanged in spirit:

loop {
    let listener = trunk.listen(); // register BEFORE re-checking (no missed-wakeup race)
    match origin.resolve(request, now, await_policy) {
        EgressResponse::Ready { body, .. } => return Ready(body),
        EgressResponse::BadRequest { .. } => return BadRequest,
        EgressResponse::NotFound => return NotFound,
        EgressResponse::Await { .. } => {
            // caller's own bounded timeout wraps `listener.await` here
        }
    }
}

The blocking-reload cap is media_plane::egress::AwaitPolicy; the actual .await/tokio::time::timeout lives entirely in the adapter — this module never assumes a clock.

std-only

Like media_plane::Trunk itself, this module needs std::sync::Mutex, so it is only compiled when this crate’s std feature is enabled (the default, and the only thing that pulls in the media-plane dependency at all — see this crate’s Cargo.toml). A caller building --no-default-features (e.g. an embedded playback-only client) gets crate::client but not server.

Structs

AudioRenditionDecl

A typed declaration of one audio rendition for a multivariant playlist (RFC 8216bis §4.4.6.1, Apple HLS authoring spec items 9.5-9.8). Consumed by HlsOriginBuilder::audio_renditions.

BlockingQuery

Blocking playlist reload query parameters (RFC 8216bis §6.2.5.2) — the sans-IO counterpart of an adapter’s own (likely serde-Deserialize) query-string type; the adapter maps its wire query params into this.

ClosedCaptionDecl

Operator override of how one detected caption stream is advertised (RFC 8216bis §4.4.6.1, Apple HLS authoring spec item 4.4). It never makes a stream appear: a stream is advertised only once the video is seen to carry it. Consumed by HlsOriginBuilder::closed_caption_overrides.

ClosedSegment

One closed segment’s identity/metadata as tracked by this origin’s Window — HlsOrigin::closed_segments’s return shape. Deliberately excludes the segment’s bytes: a caller merging this with another segment source (issue #900) fetches bytes through the normal ServedEgress::resolve resource path when it needs them, not through this snapshot.

Generation

An init-segment generation: the version counter in init-{track}-{instance}-{generation}.mp4, starting at 1.

HlsOrigin

The LL-HLS origin ServedEgress: renders playlists and resolves blocking-reload/part-availability requests for one stream, backed by a shared Trunk. See this module’s own doc for exactly what comes straight from the Trunk and what needs the small synced Window.

HlsOriginBuilder

Fluent builder for HlsOrigin (issue #873) — replaces the old four-positional HlsOrigin::new (deleted; this crate is at 0.4.0 unpublished, so there is no compatibility burden), which could not express “classic HLS, no low latency” at all since part_target_ms was a mandatory positional argument.

HttpPriority

HTTP Priority signalling data for an LL-HLS response (RFC 8216bis §6.2.6 / §6.3): the extensible priority scheme (RFC 9218) urgency the adapter should attach to the response. Playlists MUST have urgency 1; Media Segments urgencies 2 through 6; Partial Segments share the segment’s urgency band.

PartIndex

A part’s 0-based index within its parent segment.

RenditionSibling

A sibling rendition’s origin + the URI of its media playlist, used to render #EXT-X-RENDITION-REPORT (RFC 8216bis §4.4.5.4) into this origin’s media playlist. Stored as a Weak reference so origins can refer to each other without forming a reference cycle.

SegmentSeq

A segment sequence number: the Trunk’s own numbering of closed segments (the moof/mfhd number, before any Media Sequence Number offset is added). Also the parent-segment number of a part.

SubtitleRenditionDecl

A typed declaration of one WebVTT subtitle rendition for a multivariant playlist (RFC 8216 §4.3.4.1, Apple HLS Authoring Spec items 4.5-4.7, 5.11). Consumed by HlsOriginBuilder::subtitle_renditions. All renditions share the group SUBTITLES_GROUP_ID.

Enums

Container

Which container HlsOrigin serves segments/parts as — orthogonal to whether LL-HLS is enabled (HlsOriginBuilder::low_latency); issue #873.

HlsBody

ServedEgress::Body for HlsOrigin: the resolved body, typed by which HlsRequest produced it. A data-carrying ADT — see tests/label_coverage.rs’s SKIP list.

HlsMasterError

Error returned by HlsOrigin::master_playlist.

HlsOriginBuildError

Error returned by HlsOriginBuilder::build when a required field was never set — never a silently-defaulted value (issue #873).

HlsRequest

ServedEgress::Request for HlsOrigin: which wire resource is being asked for. A data-carrying dispatch ADT (matches this crate’s client::action::Action/ResourceId convention) — see tests/label_coverage.rs’s SKIP list.

SkipDirective

Typed value of the _HLS_skip Delivery Directive (RFC 8216bis §6.2.5.1): YES requests a delta update that skips older Media Segments, v2 also skips older EXT-X-DATERANGE tags.

Constants

CLOSED_CAPTIONS_GROUP_ID

GROUP-ID of the EXT-X-MEDIA TYPE=CLOSED-CAPTIONS group the master playlist advertises for detected captions.

DEFAULT_TRACK_ID

Track id for the single rendition served per stream (no multi-track/ multi-rendition support yet).

IFRAME_SEGMENT_PREFIX

Wire prefix for an I-frame (trick-play) segment resource (issue #1422).

SUBTITLES_GROUP_ID

GROUP-ID of the EXT-X-MEDIA TYPE=SUBTITLES group the master playlist advertises for declared subtitle renditions.

Functions

bcp47_language

Canonicalise an ISO 639-2 language code into a BCP 47 (RFC 5646) primary language subtag, as required by RFC 8216bis EXT-X-MEDIA LANGUAGE.

master_playlist_m3u8

A minimal single-variant master playlist pointing at media_playlist_name (the caller’s configured media-playlist filename — e.g. multimux’s Config::playlist_name, defaulting to "media.m3u8") — the same regardless of any stream state (no multi-rendition support yet), so this takes no Trunk/origin argument.

validate_audio_renditions

Validate a list of audio rendition declarations (RFC 8216bis §4.4.6.1).

validate_audio_renditions_relaxed

Relaxed validation for split-audio routes where LANGUAGE/NAME/CHANNELS may be left empty to be derived from the sibling audio track at render time (issue #1428 slice 3). Only structural rules that do not depend on those fields are enforced.

validate_closed_caption_overrides

Validate closed-caption overrides: well-formed, unique INSTREAM-IDs.

validate_subtitle_renditions

Validate subtitle rendition declarations (RFC 8216 §4.3.4.1.1; Apple HLS Authoring Spec item 4.7).