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::Consumer: A collection of broadcast::Consumers, produced by one or more Sessions.
• broadcast::Consumer: A collection of track::Consumers, produced by a single publisher.
• track::Consumer: A collection of group::Infos, delivered out-of-order until expired.
• group::Info: A collection of frame::Infos, delivered in order until cancelled.
• frame::Info: Chunks of data with an upfront size.

Each level lives in its own module (broadcast, track, group, frame, origin, announce) that owns the short Producer / Consumer / Info names.

Traffic counters for the levels above live in stats: build a stats::Registry and hand each session a stats::Handle via Client::with_stats / Server::with_stats. Publishing the counters as MoQ broadcasts lives in the moq-stats crate.

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. Client::connect and Server::accept return a (Session, Driver) pair: the Session is the handle, and the Driver is the future that runs all of its protocol work. Nothing is spawned behind your back: spawn the driver on your executor, await it in place, or step Driver::poll with a kio::Waiter from your own poll_* function. The driver holds no session handle, so the transport still closes when the last Session clone drops (or on Session::abort), which in turn finishes the driver.

The crate has no direct tokio dependency: every future is built on kio (plain std::task::Waker plumbing) and futures, so any executor can poll them, and the poll_xxx counterparts can be stepped synchronously with a kio::Waiter.

The one remaining runtime tie is time. Timers go through web_async::time, which is backed by tokio’s time driver on native (and wasmtimer in the browser), and those timers panic when polled outside a tokio runtime. So on native you still need a tokio runtime to poll a Driver (bandwidth sampling, the control stream timeout, and subscription linger all sleep); purely model-layer methods (tracks, groups, frames, origins) never touch a timer and run on any executor.

Re-exports

pub use bytes;

pub use web_transport_trait;

pub use kio;

Modules

announce

Subscribing to broadcast (un)announcements from an origin.

bandwidth

Bandwidth estimation, split into a Producer and Consumer handle.

broadcast

A broadcast is a named collection of tracks, split into a Producer and Consumer handle.

cache

A shared byte budget for cached groups, reclaimed with LRU eviction.

frame

Frames are the leaf of the model: a sized, timestamped payload within a group.

group

A group is a stream of frames, split into a Producer and Consumer handle.

origin

Publishing and consuming the set of broadcasts routed through an origin.

stats

Traffic counter collection for moq-net sessions.

track

A track is a collection of semi-reliable and semi-ordered streams, split into a Producer and Subscriber handle.

Structs

BoundsExceeded

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

Client

A MoQ client session builder.

ConnectionStats

A snapshot of connection statistics for a Session.

Datagram

A single unreliable payload on a track: a sequence number, a presentation timestamp, and the bytes.

Driver

The future driving a Session’s protocol state.

InvalidOrigin

Returned when a local origin id is zero or outside the 62-bit wire range.

Origin

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

OriginList

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

Path

A broadcast path that provides safe prefix matching operations.

PathPrefixes

A deduplicated list of path prefixes.

PathRelative

A relative broadcast path, used to reference one broadcast from another broadcast’s content.

Request

A paused server-side handshake.

Server

A MoQ server session builder.

Session

A MoQ transport session, wrapping a WebTransport connection.

TimeOverflow

Returned when a Timestamp operation would exceed the QUIC VarInt range (2^62 - 1), overflow during scale conversion or arithmetic, or attempt arithmetic between timestamps with mismatched scales.

Timescale

Units per second used by a track for frame timestamps.

Timestamp

A timestamp in a track’s timescale (units per second).

TooManyOrigins

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

VarInt

An integer less than 2^62

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.

Role

The session direction a client advertises in its SETUP (moq-lite-05+). The single direction a client intends to use the session for.

Version

A MoQ protocol version.

Constants

ALPNS

ALPN strings for supported versions, most-preferred first. ALPNS[0] is the newest moq-lite ALPN that both sides converge on.

Traits

AsPath

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

Consume

Derive a read view from a handle.

IntoBytes

Converts borrowed or owned byte buffers into Bytes.

Type Aliases

PathOwned

An owned version of Path with a 'static lifetime.

PathRelativeOwned

An owned version of PathRelative with a 'static lifetime.

Result

A Result with this crate’s Error.