[Frando]

This PR ports iroh-live to moq main and gives it a new public API in every library crate. The node now takes any path, and the live/ layout, calls and rooms sit on top of it as optional parts. Generic media and access code moves into moq-ext-* crates without an iroh dependency, so it can potentially be upstreamed. #75 was closed in favor of this PR, so its redesign is part of this diff.

Why

moq main now does much of what iroh-live built by hand. Its origin picks routes and fails over between them. moq-mux has rendition helpers and encoder rate control, moq-audio has an adaptive jitter buffer, and moq-room is a room layer over announcements. Main also dropped moq-tokio's iroh backend (moq-dev/moq#7345), so iroh-live is now the only place where moq runs over iroh.

That splits the work in two. What is specific to iroh stays here: the transport, the node with its route table and per-peer access, tickets, gossip rooms and the relay. Everything generic moves into moq-ext-* crates that know nothing about iroh.

On main, the API was built around one convention. Live decided the path layout, the grants, the endpoint and the router, and calls and rooms were methods on it. An application with its own path scheme, its own access rules or its own router had to work around the facade. This PR turns that around:

• The node is the application's handle, and it knows only paths. iroh_live::Node publishes and subscribes at any path. Nothing in the node mentions live/.
• Conventions are values you opt into. layout::LiveLayout is the <root>/<peer>/<name> scheme, and every use of it names it. An application with another scheme calls the node with its own paths.
• Services hold a node. Calls::new(&node, &layout) and Rooms::new(&node) stand side by side. Neither knows the other, and the node knows neither.
• Least privilege, and viewing a ticket still works. NodeConfig::default() lets peers read and publish nothing. Subscribing to a ticket grants exactly that ticket's path, to exactly its publisher, for as long as the subscription lives.

moq main is not released, so the workspace depends on it by git rev (moq-dev/moq@5ac2db31d, 2026-11-08). The README says so up front and gives the git dependency line, since iroh-live is not on crates.io either.

How it fits together

 apps        irl (cli) · Android demo · pi-zero demo · iroh-live-relay
 facade      iroh-live: layout::LiveLayout · calls · EndpointOptions · media glue
 services    iroh-live-rooms        moq-ext-player · moq-ext-publisher · moq-ext-sources
 node        iroh-live-node: Node, BroadcastTicket, grants and claims, relay links
 transport   moq-transport-iroh     moq-ext-access (grants, audiences, token convention)
 upstream    iroh · iroh-gossip · moq-net · moq-video · moq-audio · moq-json

Crate	On main	What it holds
iroh-live	same	The facade: layout::LiveLayout, calls, EndpointOptions, media::remote_broadcast, and re-exports of the rest
iroh-live-node	iroh-moq	Node: one route table fed by direct sessions and relay links, publications, grants and ticket claims, admission, BroadcastTicket
moq-transport-iroh	part of iroh-moq	moq-net's poll transport on iroh connections, dial, accept, ALPNs, MoqPreset, link statistics
iroh-live-rooms	iroh-rooms	Gossip membership and members-only broadcasts. No media and no chat
iroh-live-relay	same	Relay for browsers. Pulls broadcasts from iroh publishers into moq-relay's cluster
iroh-live-cli	same	The irl binary
moq-ext-access	new	Grant, SessionRequest, Audience<P>, visible_paths and the token wire convention, generic over the peer id
moq-ext-adaptive	part of moq-media	Rendition choice and decoder handover as I/O-free state machines, tested on a fake clock
moq-ext-player	part of moq-media	RemoteBroadcast and Player: rendition switches, adaptation, A/V sync, stats, recording
moq-ext-publisher	part of moq-media	LocalBroadcast: one source encoded into a rendition ladder
moq-ext-sources	part of moq-media	Test pattern, audio files, capture, rpicam and push senders
moq-ext-media-core	new	The error, slot state and stats helpers the player and the publisher share
moq-ext-egui	moq-media-egui	egui video views and the debug overlay

The Android EGL renderer and JNI helpers moved into demos/android/rust, their only user. The thin wrappers in moq-media are gone: the crates use moq_audio::playback::Engine, moq_audio::encode::Control, hang's Catalog, moq_net::bandwidth::Rate and moq_video::FrameRate directly.

Using it

Publish and play

On main, Live::publish returned a broadcast with one video and one audio slot, and a subscriber got one decoder per track:

// main
let live = Live::from_env().await?.with_router().spawn();
let broadcast = live.publish("hello")?;
broadcast.video().set(video::capture::Config::default())?;

let sub = live.subscribe(ticket.endpoint, &ticket.broadcast_name).await?;
if let Some(video) = sub.media().await.video {
    while let Some(frame) = video.recv().await { /* render */ }
}

Now the application binds the endpoint, owns the router, and names the layout it publishes under:

// this PR
let layout = LiveLayout::default();                          // "live/<peer>/<name>"
let endpoint = EndpointOptions::from_env()?.bind().await?;
let node = Node::new(endpoint.clone(), layout.config(&[]));  // peers publish only under their own id
let router = node.mount(Router::builder(endpoint)).spawn(); // add your own protocols here

let cam: LocalBroadcast = layout.publish(&node, "hello")?;
cam.set_video(camera, VideoEncoding::ladder([VideoRendition::p360(), VideoRendition::p720()]))?;
println!("{}", layout.ticket(node.id(), "hello")?);

let subscription = node.subscribe_ticket(&ticket).await?;
let player = remote_broadcast(&subscription).play(PlayerConfig::default())?;
let mut frames = player.video();
while let Some(frame) = frames.next().await { /* render */ }

router.shutdown().await?; // shuts down the node and every mounted service, then closes the endpoint

The broadcast is created in the node's route table, and peers read it without a copy. layout.publish_with(&node, name, audience, fill) runs fill before the announcement, so a reader never finds the broadcast without its catalog, and returns the Publication with what fill built.

On main, the adaptation state machine, the playout clock and reopen_decoder were public, and the caller had to coordinate them. Now PlayerConfig sets each behaviour with one value: RenditionMode (auto, pinned or off), Latency, the decoder kind and an optional AudioTarget. Player::status() reports the rendition on screen, a pending switch and errors. A switch opens a second decoder that takes over once it catches up, so the picture does not go blank.

An application with a path scheme of its own skips the layout and gives the node a grant:

let node = Node::new(endpoint, NodeConfig { grant: Some(Arc::new(my_grant)), ..Default::default() });
let (publication, cam) = node.publish_with("fleet/robot-7/cam", Audience::peers([edge]), fill)?;
let subscription = node.subscribe("fleet/robot-7/cam", Reach::Direct(robot)).await?;

iroh-live/examples/moq_only.rs does exactly this.

Tickets

A BroadcastTicket is a publisher's endpoint id and the full path of one of its broadcasts. It says nothing about layouts, so it works with any scheme. Publication::ticket() and LiveLayout::ticket(peer, name) build one.

The string form is ilv1:<peer>/<path>. The peer is the endpoint id in lowercase base32. A path segment equal to the peer's own id is written ~, and other bytes outside [A-Za-z0-9._-] are percent-encoded:

ilv1:xq2zp5bk3o4rbi5kx7ncymbkjrmdlbm3lqkv3wuiixu3vo5mbfqq/live/~/studio

That is about 72 characters, short enough for a QR code on a small screen. A ticket holds no socket addresses: the subscriber finds the publisher by its id over pkarr, DNS and mDNS.

Ticket grants

Node::subscribe_ticket works on a node with the default config, which lets no peer publish anything. It does that by claiming the ticket's path for the ticket's publisher:

1. If the node's grant already lets the publisher publish the path, it claims nothing.
2. Otherwise it calls Node::claim_path(peer, path). The claim widens what that peer may publish into this node by that one path, on every session with the peer, including ones that start later.
3. It resolves the path like subscribe(path, Reach::Both(peer)).
4. The subscription holds the claim. When the last subscription of the path drops, the grant narrows again, and moq ends what local readers read there.

A claim is only allowed if the peer owns the path. By default that means exactly one segment of the path is the peer's endpoint id in its canonical spelling, and no other segment parses as an endpoint id. So a claimed path names its publisher and no one else, and it can never overlap another peer's paths. NodeConfig::owner replaces the rule for a node that knows better, as the relay does. Claims are capped at 64 paths and 16 KiB per peer.

Each session's grant is now two layers: a base set by NodeConfig::grant, manual admission, ConnectOptions::grant or Session::set_grant, and the peer's claimed paths on top. Session::grant() returns the effective grant, Session::base_grant() the base. A set_grant cannot remove a claimed path, and a claim cannot undo a narrowing of any other path.

Calls

On main, each side published at calls/<own id>, which every session of the node could see, and Call::close closed the whole session. iroh_live::calls is now a service over a layout's call path:

let (calls, side): (Calls, LocalBroadcast) = Calls::new(&node, &layout)?;  // "live/<me>/call", offered to nobody
side.set_video(camera, VideoEncoding::single(VideoRendition::p360()))?;

// Place a call: ring the peer, wait for it to answer, subscribe to its side.
let call = tokio::time::timeout(Duration::from_secs(30), calls.call(peer)).await??;

// Take calls.
let mut events = calls.events();
while let Some(event) = events.next().await {
    if let CallEvent::Ringing(peer) = event {
        let call = calls.answer(peer).await?;
        let player = remote_broadcast(call.subscription()).play(PlayerConfig::default())?;
    }
}

Ringing a peer adds it to the audience of this node's side, so the side appears in that peer's route table, and that is the ring. Answering rings back and subscribes. Two peers that call each other at once end up in one call. Dropping a Call hangs up: the peer loses the side, and the session stays. calls.ringing() is the level-triggered set of peers that ring now. events() reports the edges, best-effort, and replays the current ringing set first. One side serves every call in turn, so a camera and a preview keep running between calls. The wire protocol is the one irl call and the Android demo already speak.

Rooms

On main, a room subscribed to every broadcast of every member and sent events, chat included. Now the membership is a watched RoomState, and the application subscribes to the broadcasts it wants:

let node = Node::new(endpoint.clone(), layout.config(&[Arc::new(rooms::publish_scope)]));
let rooms = Rooms::new(&node);
let router = rooms.mount(node.mount(Router::builder(endpoint))).spawn(); // moq ALPNs and gossip
let room = rooms.join(&ticket, Some("ada".into())).await?;
let cam: LocalBroadcast = room.publish("cam")?;
let members = room.state().get();
let subscription = room.subscribe(peer, "cam").await?;

Room broadcasts live at rooms/<topic>/<member>/<name>, and only members see them. Chat is not part of the library: irl room sends it on moq-room's chat track, which @moq/room also reads.

The node: routing and access control

On main, iroh-moq had no shared route table: each session had its own origin, and a broadcast came only from the session with its publisher. That prevented forgery, but a broadcast could not come through a relay. The node now follows moq main's model and keeps no routing logic of its own:

• One route table. Direct sessions announce into it as Link::Peer with the peer's hop. Relay links announce as Link::Upstream with a higher cost. moq moves a subscription between a direct and a relay route of one stream without ending it, and RemoteBroadcast follows a publisher that restarts as a new stream.
• No transit. Every link serves the table's local view, which hides routes learned from peers and relays. A node serves only its own publications.
• Per-peer visibility through per-session authorization. Each session and relay link is authorized for the publications whose audience admits the peer, before its handshake and again whenever a publication, an audience, a grant or a claim changes. A peer taken out of an audience loses the path, and its reads there end with Unauthorized.
• Grants decide what peers may put into the table. The default lets peers publish nothing. LiveLayout::config lets each peer publish only under <root>/<its id>/, so no peer can publish in the name of another, and pinned subscribes can tell peers apart by the routes' hops. Admission::Manual hands incoming sessions to Node::accept, for example after a token check.
• Relays. attach_relay takes an iroh:// or https:// URL and redials with backoff. Everyone publications go to the relay, Peers publications never do. A relay is trusted with every path it forwards.

The relay

iroh-live-relay serves browsers through moq-relay and pulls broadcasts from iroh publishers into its cluster without copying them. Its pull node uses the cluster origin as its route table (NodeConfig::table) and a base grant of nothing. Each pull holds a claim_path guard for the ticket's path, so the publisher's session announces exactly that path into the cluster and nothing else. The pull node's NodeConfig::owner accepts only a peer's canonical live/<peer>/<name> or rooms/<topic>/<peer>/<name> path, so a ticket that names another peer's path is refused before anything is dialed. A browser reads the pull under the ticket string it asked for, which the relay parses from the raw URL path before percent-decoding.

Transport

moq main owns the transport interface (moq_net::transport::poll), and moq-tokio implements it on its own QUIC stack. moq-transport-iroh does the same over iroh's Connection and streams, with no web-transport crates. Priorities, datagrams, close and reset codes, metrics and wire counters are backed. send_group, probe and receive_window return None, since iroh has nothing to back them with. A send stream dropped before finish is reset, so the peer never takes a truncated stream for a complete one.

WebTransport over HTTP/3 on iroh is gone. Its only job was carrying the relay token in the URL. The token now travels in the MoQ SETUP, and for moq-lite-06, whose SETUP has no token field, also as ?jwt= in the setup path; moq_ext_access::token writes both and SessionRequest::token() reads them. A dial offers only the newest moq ALPN, because iroh's router sorts its ALPNs and TLS would otherwise settle on the oldest version.

Breaking changes

• No compatibility with main's wire formats, room format or path layout, nor with peers that dial WebTransport over HTTP/3 on iroh. Broadcasts move from bare names to live/<id>/<name>, and calls from calls/<id> to live/<id>/call.
• Tickets are BroadcastTicket { peer, path } in the node, written ilv1:.... LiveTicket, the iroh-live: form and the older EndpointAddr form no longer parse, so printed QR codes need re-issuing.
• Removed: Live, LiveBuilder, CallOffer, Call, the facade's free config functions, Subscription::media and the per-track VideoTrack (use Player), MoqSession and IncomingSessionStream (use Session and Node::accept), RoomEvent and room chat, the Android Camera2 bridge (use VideoSource::push), and the moq-ext-media-android crate.
• Renamed: Moq to Node, Live::remote_broadcast to media::remote_broadcast, and the relay's RelayConfig to iroh_live_relay::Config. The node's RelayConfig for attach_relay keeps its name.
• Lifecycle: nothing owns the endpoint for you. Router::shutdown shuts down the node and every service mounted on the router, then closes the endpoint.
• SessionRequest lost its HTTP/3 headers; SessionRequest::token() returns the SETUP token.
• Config types are struct literals with Default; #[non_exhaustive] and the builders it forced are gone.
• Features: iroh-live has no default features (main had capture, render and sound-server). full turns on media, capture, render, sound-server and record. media, rooms, file and record are new.
• irl record --latency is now --max-age.
• LICENSE-MIT held the Apache text since the first commit; it now holds the MIT license.

Known limits

• One ALPN on dial. A future build that offers only a newer moq version will not connect to this one. The accepting side still takes every version.
• A widened grant lands a moment later. A live session applies a claim asynchronously, so a read that starts right after claim_path on an existing session can still be refused. subscribe_ticket on a fresh session is not affected.
• Calls. moq's announcements are a listing now, so a peer that publishes its side again without withdrawing it first does not ring anew, and a withdrawal and a new offer in quick succession can merge into no change. ringing() stays correct.
• Pinned subscribes depend on the grants. A peer can declare another peer's hop on the wire, so Session::subscribe attributes a route correctly only while grants do not overlap. The layout's grants and the claim ownership rule make sure of that.
• Grant size. A grant lists every visible publication, and moq refuses an AUTH_OK over 64 KiB, which a few hundred room paths reach.
• HTTPS relay links are authorized just after moq-tokio's connect spawns its dial loop. Closing that gap needs a moq-tokio API change.
• A microphone that fails no longer reopens on its own with moq main's shared audio capture. The audio slot stays Failed until the next set_audio.
• The Android crate only builds for Android, so CI on Linux and macOS does not compile it. It needs cargo ndk -t arm64-v8a check -p iroh-live-android.
• moq main is not released. A release cut from main will be one large breaking version, and we will move the git rev to it.

Testing

CI runs cargo check with default, all and no default features, plus the relay alone and the facade without media. It runs clippy with -D warnings, nextest and cargo fmt --check on Linux and macOS, the Playwright suite (browser to iroh, iroh to browser through a relay link, pull mode), and release builds for Android, Windows and aarch64.

At the head of this branch, every crate's test suite passes locally with all features, including the patchbay tests for adaptation on impaired links (cargo make test-patchbay). New tests cover ticket grants and claims (forged paths, narrowing on drop, set_grant precedence, limits, concurrent claims), the ticket format, the relay's pull ownership, and calls, including interop with a peer that speaks the raw path protocol as today's irl call does.

Suggested reading order

1. moq-ext-access: the grant, audience and token types.
2. moq-transport-iroh/src/transport.rs and stream.rs: the poll transport on iroh.
3. iroh-live-node: node.rs, publish.rs, state.rs (authorization and the two grant layers), claim.rs, ticket.rs, session.rs, route.rs, then relay.rs.
4. iroh-live/src/layout.rs and calls.rs.
5. iroh-live-relay/src/pull.rs.
6. iroh-live-rooms/src/room.rs.
7. Media: moq-ext-adaptive, then moq-ext-player and moq-ext-publisher.

You can skim iroh-live-cli, the demos and docs/. Using iroh-live has complete programs for every case above.

🤖 Generated with Claude Code