Crate moq_net 

moq-net: Media over QUIC networking layer

moq-net is the networking layer for Media over QUIC: real-time pub/sub with built-in caching, fan-out, and prioritization, on top of QUIC. Sub-second latency at massive scale. At session setup it negotiates one of two wire protocols: the simplified moq-lite protocol (the default) or the full IETF moq-transport protocol.

API

The API is built around Producer/Consumer pairs, with the hierarchy:

• Origin: A collection of Broadcasts, produced by one or more Sessions.
• Broadcast: A collection of Tracks, produced by a single publisher.
• Track: A collection of Groups, delivered out-of-order until expired.
• Group: A collection of Frames, delivered in order until cancelled.
• Frame: Chunks of data with an upfront size.

Compatibility

The API exposes the intersection of features supported by both protocols, intentionally keeping it small rather than polluting it with half-baked features.

The library is forwards-compatible with the full IETF specification and supports moq-transport drafts 14+ via version negotiation. Everything will work perfectly, so long as your application uses the API as defined above.

For example, there’s no concept of “sub-group”. When connecting to a moq-transport implementation, we use sub-group=0 for all frames and silently drop any received frames not in sub-group=0. If your application genuinely needs multiple sub-groups, tell me why and we can figure something out.

Producers and Consumers

Each level of the hierarchy is split into a Producer / Consumer pair:

• The Producer is the writer: it appends new state (publishes a broadcast, starts a group, writes frames, closes a track).
• The Consumer is a reader: each consumer holds its own independent view of the producer’s state, with its own cursor through the stream.

Both halves are cheaply clonable so you can hand out multiple handles. Cloning a consumer creates another reader (each at its own cursor); cloning a producer gives another writer that contributes to the same shared state. Closing the last producer signals consumers that no more updates are coming.

Async

This library is async-first, using tokio for async I/O and task management. Any plain async method should be awaited from inside an active tokio runtime. Otherwise you risk a panic.

This requirement is being phased out as more methods grow poll_xxx counterparts built on kio, so you can drive them from custom executors without a tokio runtime. You can also call them synchronously, since kio is built on the standard std::task::Waker API and any std::task::Waker is a valid driver.

Re-exports

pub use bytes;

pub use kio;

Structs

BandwidthConsumer

Consumes bandwidth estimates, allowing reads and async change notifications.

BandwidthProducer

Produces bandwidth estimates, notifying consumers when the value changes.

BoundsExceeded

The number is too large to fit in a VarInt (62 bits).

Broadcast

A collection of media tracks that can be published and subscribed to.

BroadcastConsumer

Subscribe to arbitrary broadcast/tracks.

BroadcastDynamic

Handles on-demand track creation for a broadcast.

BroadcastProducer

Manages tracks within a broadcast.

BroadcastStats

A per-broadcast, tier-scoped handle. Cheap to clone.

BroadcastSubscription

RAII guard for one of a session’s per-broadcast subscriptions. See SessionBroadcasts::subscribe.

Client

A MoQ client session builder.

Counters

Cumulative atomic counters for a single (tier, role) on a broadcast.

Frame

A chunk of data with an upfront size.

FrameConsumer

Used to consume a frame’s worth of data, streaming as bytes arrive.

FrameProducer

Writes a frame’s payload in one or more chunks.

Group

A group contains a sequence number because they can arrive out of order.

GroupConsumer

Consume a group, frame-by-frame.

GroupProducer

Writes frames to a group in order.

Origin

A relay origin, identified by a 62-bit varint on the wire.

OriginConsumer

Consumes announced broadcasts matching against an optional prefix.

OriginList

Bounded list of Origin entries, typically the hop chain of a broadcast.

OriginProducer

Announces broadcasts to consumers over the network.

Path

A broadcast path that provides safe prefix matching operations.

PathPrefixes

A deduplicated list of path prefixes.

PublisherStats

RAII broadcast guard for the publisher role. See BroadcastStats::publisher.

PublisherTrack

RAII subscription guard for the publisher role.

Server

A MoQ server session builder.

Session

A MoQ transport session, wrapping a WebTransport connection.

SessionBroadcasts

Per-session tracker that turns a peer session’s per-broadcast subscription lifecycle into broadcasts / broadcasts_closed bumps.

SessionStats

RAII guard for a connected session, keyed by auth root and tier. Bumps sessions on construction and sessions_closed on drop. See StatsHandle::session.

Stats

Top-level stats aggregator. Cheap to clone (Arc inside for the shared runtime state). One instance per relay; sessions get tier-scoped handles via Stats::tier. Build it from a StatsConfig via Stats::new.

StatsConfig

Settings for a Stats aggregator. Construct with StatsConfig::new and chain the with_* setters (e.g. StatsConfig::new().with_origin(origin).with_prefix(".foo")), then hand it to Stats::new.

StatsHandle

Tier-scoped wrapper around Stats. What crate::Client::with_stats and crate::Server::with_stats accept. Cheap to clone.

SubscriberStats

RAII broadcast guard for the subscriber role. See BroadcastStats::subscriber.

SubscriberTrack

RAII subscription guard for the subscriber role.

TimeOverflow

Returned when a Timescale operation would exceed the QUIC VarInt range (2^62 - 1) or overflow during scale conversion or arithmetic.

Timescale

A timestamp representing the presentation time in a given scale. ex. 1000 for milliseconds.

TooManyOrigins

Returned when an operation would grow an OriginList past its hop-count cap.

Track

A track is a collection of groups, delivered out-of-order until expired.

TrackConsumer

A consumer for a track, used to read groups.

TrackProducer

A producer for a track, used to create new groups.

Versions

A set of supported MoQ versions.

Enums

DecodeError

A decode error.

EncodeError

An error that occurs during encoding.

Error

A list of possible errors that can occur during the session.

Tier

Distinguishes traffic classes so a single Stats can record customer-facing and cluster-peer traffic separately. Each tracked broadcast keeps per-tier Counters on both its publisher and subscriber sides.

Version

A MoQ protocol version.

Constants

ALPNS

ALPN strings for supported versions.

Traits

AsPath

A trait for types that can be converted to a Path.

Type Aliases

OriginAnnounce

A broadcast path and its associated consumer, or None if closed.

PathOwned

An owned version of Path with a 'static lifetime.

Result

Time

A timestamp representing the presentation time in milliseconds.