Skip to main content

Module moq_stream

Module moq_stream 

Source
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§

MoqReachConnection
A live moq subscriber connection resolved from a producer’s reach (#356).
MoqStreamHandle
moq stream consumer handle for MCP tool calls and other async consumers.
MoqStreamOrigin
Shared moq origin for the streaming plane, plus the in-process publish gate.
MoqStreamOriginBuilder
Builder for MoqStreamOrigin — set the prefix and publish gate before the shared Arc is constructed (avoids clone-on-write of the origin tree).
MoqStreamPublisher
In-process moq publisher with the §7.5 chained-HMAC tokenstream.
NodeStreamReach
Bound QUIC reach for one service’s MoQ producer.
ProducerReachConfig
A node/server’s moq reach inputs (#384) — the per-server context that builds a producer’s StreamInfo.reach.
RelayTarget
One independently resolver-verified relay selection for a stream.

Enums§

RelayChoice
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::TransportConfig to a wire-publishable crate::stream_info::TransportConfig union 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::Destination into the local crate::transport::TransportConfig crate::dial::dial_stream dials (#274).
relay_reach_from_decoded
Build the producer-chosen relay’s wire-reach crate::stream_info::TransportConfig from a DID-document transport entry decoded by crate::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 reach list by the QoS-preferred topology (#358), returning a new list the caller hands to connect_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 by StreamVerifier::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::TransportConfig union arm to the local dialable crate::transport::TransportConfig. Returns None for 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§

AnyStreamPublisher
Publisher for the moq-lite streaming plane.
MoqStreamOriginHandle
Mutable per-service MoQ origin source. None preserves the process-global origin for services that do not need relay isolation.
ProducerReachConfigHandle
Mutable per-service reach source. The service spawner fills it with the actual QUIC and iroh bind results before the service accepts requests.