Expand description
moq-lite streaming plane (M2a of epic #134).
Point-to-point / per-recipient streaming only (request/response, token
streams, and per-recipient unique topics such as NotificationService’s
blind broadcast — each recipient gets its own topic, not a shared fan-out
track). Broadcast fan-out (N subscribers learning about one event from one
source) is consolidated on the sibling crate::moq_event origin instead —
see its module doc for the two-origins split.
This is the moq-native replacement for the ZMQ PULL→XPUB queuing proxy in
[crate::service::streaming]. Instead of a forwarding proxy with a custom
per-topic queue + late-join rejoin buffer, in-process publishers append
directly to a shared moq_net::Origin, and external subscribers consume the
same origin over the moql ALPN via
crate::transport::iroh_moq::IrohMoqProtocolHandler.
§Topic → Track mapping
The existing call-site contract is a topic string (64-hex DH-derived, or a
notify-* / control topic) plus opaque payload bytes. We map:
topic-string -> moq Broadcast path {tenant}/{service}/{topic}/{instance}
StreamBlock -> one moq Group (sequence = block index)
containing one Frame = capnp_bytes || mac[16]For the in-process / direct path (M2a), the broadcast path is built from a
caller-supplied {tenant}/{service}/.../{instance} prefix joined with the
opaque topic. The topic itself stays opaque (and, for the relay’d path in
M2b, DH-derived/unguessable). A single track name (STREAM_TRACK) carries
the block sequence.
§§7.5 chained-HMAC tokenstream
The chained-HMAC envelope is preserved 1:1: each Group’s Frame payload is
the same [capnp StreamBlock || 16-byte truncated MAC] that the ZMQ wire
format carried in frames 1+2 (frame 0, the topic, is now the Track/Broadcast
path and is therefore dropped from the payload). StreamHmacState /
StreamVerifier are reused unchanged, so the MAC chain — which binds each
block to its predecessor — is byte-identical to the ZMQ path.
Late-join is now moq’s job: a subscriber that joins late is served the
latest Group natively by the moq Track cache (respecting upstream Group
cache consts), so the custom StreamResume / rejoin-buffer code is gone.
Structs§
- MoqReach
Connection - A live moq subscriber connection resolved from a producer’s reach (#356).
- MoqStream
Handle - moq stream consumer handle for MCP tool calls and other async consumers.
- MoqStream
Origin - Shared moq origin for the streaming plane, plus the in-process publish gate.
- MoqStream
Origin Builder - Builder for
MoqStreamOrigin— set the prefix and publish gate before the sharedArcis constructed (avoids clone-on-write of the origin tree). - MoqStream
Publisher - In-process moq publisher with the §7.5 chained-HMAC tokenstream.
- Node
Stream Reach - Bound QUIC reach for one service’s MoQ producer.
- Producer
Reach Config - A node/server’s moq reach inputs (#384) — the per-server context that builds
a producer’s
StreamInfo.reach. - Relay
Target - One independently resolver-verified relay selection for a stream.
Enums§
- Relay
Choice - Per-stream relay selection for
ProducerReachConfig::reach_with_relay(#384).
Constants§
- BROADCAST_
ANNOUNCE_ TIMEOUT - Timeout waiting for the moq origin to announce a broadcast at startup.
- DEFAULT_
PREFIX - Default
{tenant}/{service}broadcast-path prefix for the in-process plane. - FRAME_
READ_ TIMEOUT - Timeout reading a single Frame from an already-opened Group.
- GROUP_
IDLE_ TIMEOUT - Timeout between consecutive moq Groups on a subscribed track. A timeout here signals the publisher is gone; the subscriber breaks out.
- STREAM_
TRACK - The single track name that carries StreamBlock groups for a broadcast.
Functions§
- connect_
moq_ reach - Resolve a producer’s reach into a live moq subscriber connection (#356).
- connect_
moq_ reach_ for_ profile - Explicit policy seam. Required mode admits only Iroh destinations.
- connect_
moq_ reach_ for_ qos - Resolve a service-advertised reach into a live moq connection, honouring the QoS-preferred topology (#358).
- connect_
moq_ reach_ with_ server_ identity - Resolve a stream reach with the server accepted-state witness authenticated by the enclosing streaming RPC response. Iroh is fail-closed without it.
- dial_
transport_ to_ wire - The single dial→wire reach codec (#320): map a local dialable
crate::transport::TransportConfigto a wire-publishablecrate::stream_info::TransportConfigunion arm. - global_
moq_ admission_ proof - Borrow the process proof for other authenticated native MoQ planes.
- global_
moq_ origin - Borrow the process-global moq streaming origin, if initialized.
- global_
moq_ uds_ path - Path of the UDS socket that serves the moq streaming plane to local clients.
- init_
global_ moq_ admission_ proof - Install this process’s accepted-state-bound Iroh admission proof.
- init_
global_ moq_ origin - Register the process-global moq streaming origin.
- native_
iroh_ required - reach_
to_ transport_ config - Convert a wire-published
crate::stream_info::Destinationinto the localcrate::transport::TransportConfigcrate::dial::dial_streamdials (#274). - relay_
reach_ from_ decoded - Build the producer-chosen relay’s wire-reach
crate::stream_info::TransportConfigfrom a DID-document transport entry decoded bycrate::service_entry(#358). - require_
native_ iroh - Require native Iroh; later compatibility callers cannot reopen fallbacks.
- run_
relay_ announce_ link - One connect-and-hold cycle of the producer→relay announce link (#358).
- select_
reach - Reorder the service-advertised
reachlist by the QoS-preferred topology (#358), returning a new list the caller hands toconnect_moq_reach. - serve_
moq_ uds_ background - Start a UDS moq server in the background, serving the moq origin’s consumer
to local cross-process subscribers (e.g.
hyprstream tui attach). - serve_
origin_ to_ relay_ background - Announce this node’s streaming origin UP to the producer-chosen relay (#358).
- verify_
moq_ frame - Consumer-side helper: split a moq Frame payload back into the ZMQ-style
[topic, capnp, mac]frames expected byStreamVerifier::verify, then verify and parse it. - verify_
moq_ frame_ with_ provenance - Mesh consumer entry point (#321): verify a moq frame’s chained HMAC + AEAD
(via the
verifier) AND its per-host provenance signature against a roster. - wire_
transport_ to_ dial - The single wire→dial reach codec (#274/#320): map one wire
crate::stream_info::TransportConfigunion arm to the local dialablecrate::transport::TransportConfig. ReturnsNonefor an un-routable arm (e.g. an iroh reach with no relay). Shared by the streaming plane (reach_to_transport_config) and the RPC inference router (#320), so there is exactly ONE iroh/quic reach decoding.
Type Aliases§
- AnyStream
Publisher - Publisher for the moq-lite streaming plane.
- MoqStream
Origin Handle - Mutable per-service MoQ origin source.
Nonepreserves the process-global origin for services that do not need relay isolation. - Producer
Reach Config Handle - Mutable per-service reach source. The service spawner fills it with the actual QUIC and iroh bind results before the service accepts requests.