Module client 

LL-HLS playback client engine — a sans-IO Low-Latency HLS (RFC 8216bis) client (issue #717, slices 2-4; formerly the standalone ll-hls-client crate, folded in here as hls-runtime’s client module — see docs/superpowers/specs/2026-07-18-multimux-hub-design.md).

HlsClient is a driveable, caller-driven state machine — the same sans-IO shape as srt-runtime (issue #565): the core never opens a socket or reads a clock. The caller drains Actions (what to fetch, and how), performs the IO itself, and feeds the response back in via HlsClient::on_playlist / HlsClient::on_resource / HlsClient::on_error; decoded Outputs (the init segment, then ordered access units) drain out via HlsClient::next_output.

Reuse, not re-description

This module defines no playlist model of its own. Parsing is broadcast_hls::MediaPlaylist::parse (issue #717 slice 1 — the symmetric inverse of the LL-HLS origin’s own to_m3u8() renderer, so origin and client share one wire model); demuxing a fetched CMAF part or segment into access units is transmux::Fmp4Demux. client holds only the client engine: the reload scheduler, the fetch pipeline (prefetch/byte-range/dedup), and the output ordering — see HlsClient’s docs for the full behaviour.

Zero IO in the core

No tokio/reqwest/socket dependency in HlsClient itself, ever — it is driveable by hand (see the crate’s tests/origin_loop.rs for a complete in-process example against a real transmux::ll_hls::LlHlsSegmenter origin) with zero IO dependencies at all (verified by the --no-default-features gate).

The tokio feature (issue #717 slice 5)

Enabling the tokio cargo feature (NOT default) adds tokio_client::TokioClient, a thin async shell (tokio + reqwest/rustls) that drives HlsClient over real HTTP — blocking-reload/preload-hint query params, byte-range Range headers, per-request timeouts, and retry/backoff on transient failures. See tokio_client’s module docs for the full behaviour and its tests/glass_to_glass.rs for a loopback-HTTP, sub-second glass-to-glass proof against a real multimux-served LL-HLS origin. This feature is entirely additive — the sans-IO core above is completely unaffected by it either way.

Example

use hls_runtime::client::{Action, HlsClient};

let mut client = HlsClient::new("http://origin/live/stream.m3u8");
// The caller performs this GET; here we just inspect the first action.
match client.poll() {
    Some(Action::FetchPlaylist { url, blocking, .. }) => {
        assert_eq!(url, "http://origin/live/stream.m3u8");
        assert!(blocking.is_none()); // nothing fetched yet, so no LL info.
    }
    other => panic!("unexpected first action: {other:?}"),
}

Re-exports

pub use tokio_client::TokioClient;tokio

pub use tokio_client::TokioClientConfig;tokio

pub use tokio_client::TokioClientStats;tokio

pub use tokio_client::TokioError;tokio

Modules

tokio_clienttokio

TokioClient — a tokio + reqwest IO adapter driving crate::client::HlsClient over real HTTP (issue #717 slice 5).

Structs

BlockingReload

A pending blocking Playlist Reload request (RFC 8216bis §6.2.5.2): the client has consumed the playlist up to (and possibly including) a given Partial Segment and wants the server to hold the response until something newer exists.

HlsClient

A driveable, sans-IO Low-Latency HLS (RFC 8216bis) playback client.

Enums

Action

One unit of IO the caller must perform, in response to a crate::client::HlsClient::poll call. The client core never touches a socket or a clock itself — every Action names exactly what to fetch and, for a playlist reload, how to shape the request.

Error

Error variants crate::client::HlsClient can return.

Output

One unit of decoded output, drained in order via crate::client::HlsClient::next_output.

ResourceId

Identifies one fetchable resource: the initialisation segment, a Low-Latency HLS partial segment (“part”, RFC 8216bis §4.4.4.9), or a whole media segment. Used to correlate an Action::FetchResource with the matching crate::client::HlsClient::on_resource call.

Type Aliases

Result

Crate-wide result alias.