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::Session 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.

Driving and time

This library never spawns tasks or reads the clock. Client::connect and Server::accept take an initial time::Instant and return (Session, Driver). Poll the Driver with the current instant and a kio::Waiter, then wake on external activity or at the deadline it returns; time::run does exactly that on tokio or the browser. The last Session drop requests closure; dropping the driver cancels it.

origin::Producer::new also returns a producer and driver. Its driver runs route changes, serving, linger, teardown, and the origin’s cache expiration. Standalone caches expose cache::Pool::gc. Frame read/write methods clear their expiration timestamp for the next cleanup pass. Datagrams use a bounded FIFO; model read/write APIs take no wall-clock time.

Both drivers implement time::Driver. moq-uring drives thread-local transports on its own timer heap. Tests advance time by supplying a later instant.

Re-exports

pub use path::AsPath;

pub use path::Path;

pub use path::PathOwned;

pub use server::Server;

pub use session::Session;

pub use bytes;

pub use web_transport_trait;

pub use kio;

Modules

announce

Subscribing to route (un)announcements from an origin.

bandwidth

Rate 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, repaid by write-time eviction.

frame

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

goaway

GOAWAY, the graceful drain signal, split into a Producer and Consumer handle.

group

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

origin

Publishing broadcasts, announcing routes, and consuming both through an origin.

path

Broadcast paths and the patterns that match them.

server

Accepting a MoQ session, including the paused handshake that inspects the peer’s SETUP before granting origins.

session

A MoQ session handle and a snapshot of its connection statistics.

stats

Traffic counter collection for moq-net sessions.

time

Caller-supplied time for protocol and model drivers.

track

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

transport

The transport interface a MoQ session runs over.

Structs

BoundsExceeded

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

Client

A MoQ client session builder.

Datagram

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

Driver

Drives a session with caller-supplied time.

Hop

One relay’s identity in a broadcast’s hop chain: a 62-bit varint on the wire.

Hops

Bounded, loop-free list of Hop entries: the hop chain of a broadcast.

Pattern

A pattern over broadcast paths: literal segments, * for one segment, prefix*suffix for one segment with a known start and end, and at most one ** for any run of segments. Every segment kind matches whole segments, and a pattern is exact: foo matches only foo, and a subtree is foo/**.

Patterns

A union of patterns, reduced so no member is contained by another.

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).

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

Failures in this crate, both local conditions and codes received off the wire.

InvalidHop

Why a Hop is not usable, on its own or as part of a Hops chain.

InvalidPattern

Why a string or a segment list is not a valid Pattern.

Role

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

SessionError

A code sent when terminating the session.

StreamError

A code sent when resetting a stream, or refusing to receive one.

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

Consume

Derive a read view from a handle.

IntoBytes

Converts borrowed or owned byte buffers into Bytes.

Type Aliases

Result

A Result with this crate’s Error.