Skip to content

feat(transport): mark send group streams incremental (needs noq#859) - #97

Draft
Frando wants to merge 2 commits into
mainfrom
Frando/send-groups-incremental
Draft

Frando wants to merge 2 commits into
mainfrom
Frando/send-groups-incremental

Conversation

@Frando

@Frando Frando commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Stacked on #94. Draft, and not for merge until n0-computer/noq#859 is released.

What it adds

#94 maps moq-net's send groups onto noq stream priorities. The heads of equal-priority groups share one priority, and noq sends streams of one priority round robin, but only while the connection's send fairness is on. That is noq's default, so #94 works on stock noq 1.4. An endpoint whose QuicTransportConfig sets send_fairness(false) would get streams of one priority in the order they were written to, and the older of two equal-priority subscriptions would starve the newer one again.

This PR sets RFC 9218's per-stream incremental flag (SendStream::set_incremental(true), added in noq#859) on every stream moq-transport-iroh opens or accepts, so the sharing no longer depends on the send fairness setting. The tests for the urgency mapping now also assert that each stream is incremental, and the SendGroup docs and docs/architecture/transport.md describe the flag.

The noq#859 dependency

The first commit patches noq, noq-proto and noq-udp to the PR head (danielpetri1/noq fb242c47, version 1.5.0), marked "NOT FOR MERGE: pending n0-computer/noq#859". iroh 1.4's noq = "1.4" accepts 1.5.0, and cargo tree -i noq-proto shows a single copy. Once noq#859 is released, the patch should be dropped in favor of a version bump.

Tests

  • cargo make check-all (5 check configs, clippy -D warnings in 3 configs, fmt) and cargo fmt --check pass.
  • cargo nextest run -p moq-transport-iroh --all-features: 21 of 21 pass, including equal_priority_groups_progress_together.
  • a_switch_lands_while_the_link_stays_capped: 3 of 3 runs pass (6 to 9 s each).
  • scripts/check-links.py: 364 links, none broken.

🤖 Generated with Claude Code

@Frando
Frando force-pushed the Frando/send-groups branch from 59369d6 to cf14b6d Compare November 16, 2026 11:12
@Frando
Frando force-pushed the Frando/send-groups-incremental branch from 6825b22 to 667b0de Compare November 16, 2026 11:12
@Frando
Frando changed the base branch from Frando/send-groups to Frando/cleanup-auth November 16, 2026 13:35
@Frando
Frando force-pushed the Frando/send-groups-incremental branch from 667b0de to b52f424 Compare November 16, 2026 13:35
Frando added a commit that referenced this pull request Nov 16, 2026
…s (merge of #94)

Rebuild iroh-live on moq's `main` branch and iroh 1.4, split the code
into crates by whether they need iroh, and add an access model so a
node decides which peers may connect and what each may read and
publish. Every library crate changes its public API, and nothing stays
wire-compatible with `main`. The book in `docs/` is rewritten to match.
This replaces #87 and contains all of it.

## Why

On `main`, iroh-live builds on the crates.io releases of moq, which
leaves three problems:

- No access control. `Moq::publish` announces every broadcast to every
  peer that connects, so a call or a room cannot keep its broadcasts
  to its members.
- Two transport adapters. MoQ runs over WebTransport on HTTP/3 on iroh,
  at an allocation per operation and a copy per write, and a node
  cannot attach to a MoQ relay.
- Duplication. moq `main` now has route selection and failover,
  rendition selection, A/V sync, capture, codecs and audio output, much
  of which `moq-media` and `iroh-moq` reimplement.

The goal is to use upstream moq for everything it does, keep in
iroh-live only what needs iroh, and put the rest in `moq-ext-*` crates
with no iroh dependency so each can move upstream on its own. The
facade imposes no path layout, endpoint setup or router.

## Crates

- `moq-transport-iroh`: a moq-net session over an iroh connection,
  implementing moq-net's poll transport directly on iroh streams.
- `moq-ext-access`: grants, policies, audiences, layouts, and the
  optional JWT and rcan verifiers. No iroh.
- `moq-ext-adaptive`: rendition choice, decoder backoff and handover as
  pure state machines with no I/O.
- `iroh-live-node`: the `Node` with its route table, publications,
  sessions, relay links, admission, tickets, link stats, `MoqPreset`,
  `EndpointConfig` and `LiveLayout`.
- `iroh-live-rooms`: gossip membership and members-only broadcasts.
- `moq-ext-sources`, `moq-ext-publisher`, `moq-ext-player`,
  `moq-ext-egui`: capture, the encoding `LocalBroadcast`, the decoding
  `RemoteBroadcast` and `Player`, and egui views. No iroh.
- `iroh-live`: the facade, with `Calls`, `SubscriptionExt`, one `Error`
  and re-exports.
- `iroh-live-relay` and `iroh-live-cli` (`irl`): the applications.

The media crates know nothing of the network, so one player runs over
a direct session, a relay link or another MoQ transport.

## How a broadcast flows

A publisher binds an endpoint with `EndpointConfig`, creates a `Node`
with a policy, mounts it on its own router, publishes a
`LocalBroadcast` at a path, and shares a `BroadcastTicket`. A viewer
calls `Node::subscribe_ticket` and plays the result through
`SubscriptionExt::remote_broadcast`, which attaches the serving link's
measurements so the `Player` adapts with nothing more to wire.

`Node::publish` creates the broadcast inside the route table, and
sessions read it from there without a copy. Encoders run only while
someone reads a rendition. Every session and relay link feeds the
viewer's route table, a path resolves to its cheapest route, and moq
moves a subscription to another route of the same publisher when its
route dies. A node serves only its own publications and never forwards
a route it learned from another link.

## Access

A policy decides each session: `Policy::decide` returns a `Grant`, two
sets of path patterns for subscribe and publish, with an optional
expiry, or a rejection. The node decides again on expiry and on
`Node::reauthorize`. Policies compose (`Open`, `Closed`, `from_fn`,
`filter`, `Queue` for asking the user, `Verify` with `JwtVerifier` or
`RcanVerifier`).

A layout is the path convention. `LiveLayout` puts broadcasts at
`live/<endpoint id>/<name>` and lets each peer publish only under its
own id, and `RoomsLayout` does the same under `rooms/<topic>/`. A
publication's `Audience` narrows the grant per broadcast: `Granted`
reaches every session whose grant covers the path, `Peers(set)` only
the named peers. `docs/concepts/access.md` describes the model.

## Calls and rooms

A call is a broadcast with `Audience::Peers` over a set that ringing
adds to and hanging up removes from. A room is an iroh-gossip topic
whose members announce their broadcasts. `Room::state()` returns a
watched `RoomState`, and `RoomMember::connection` reports when the last
direct session to a member closes. Chat moved out of the library into
`irl`.

## Relays

The iroh-live relay runs one `moq_relay::Cluster` that browsers reach
over WebTransport and iroh nodes over `moq-transport-iroh`. It gets a
broadcast by push, when a publisher attaches a relay link, or by pull,
when a session names a ticket and the relay dials the publisher. Pulls
require a token that grants the ticket's path (or `--open-pulls`), are
capped and rate-limited per client, and only work for paths the
ticket's publisher owns under a layout. With `--auth-key`, JWTs grant
more to iroh clients and browsers alike, and the key reloads on change.

A relay link (`Node::attach_relay`) runs moq-net's `Reconnect` with
backoff and GOAWAY migration over `https://` or `iroh://`, with tokens
that can be replaced on a live link.

## Transport

Raw QUIC has no request URI, so the path and token travel in the MoQ
SETUP. `export_keying_material` forwards iroh's TLS exporter for
moq-lite-07 route key proofs.

moq-net opens one send group per subscription, while iroh has one
`i32` urgency per stream. `Transport::send_group` returns a `SendGroup`
that packs the group's priority and each stream's rank into that
urgency, so a group's newest stream goes first and equal-priority
groups share bytes round robin. A replacement rendition therefore does
not wait behind the old one's backlog, and a switch lands on a link
held at its cap. `docs/architecture/transport.md` has the details.

After a simultaneous dial, only the oldest session with a peer
announces, since moq-lite-06 carries no publisher instance.

## Notable decisions

- moq is pinned to `main` at rev `e8075629a` by git, with no `[patch]`
  block. It includes moq-dev/moq#8561, #8562, #8636, #8639 and #8640.
  iroh-live cannot publish to crates.io until moq releases from `main`.
- Authorization is per session, not per peer, so a decision stays tied
  to what the peer presented on that session. A dial also asks the
  policy.
- Layouts are conventions, not a fixed scheme: `Node::publish` takes
  any path, and `BroadcastTicket` holds a full path.
- The player samples the link every 200 ms, caps bitrate at the
  publisher's PROBE delivery estimate, steps down on 10% loss and to
  the lowest rung on 20%, and holds 500 ms before a downgrade and 4 s
  before an upgrade. Upgrades decode in parallel and swap once caught
  up. `MoqPreset` uses BBR3.
- With `pipewire`, Linux defaults to the shareable PipeWire camera and
  the portal screen picker. `irl` enables every backend by default,
  while `iroh-live` has no default features and a `full` feature.
- Config structs are `#[non_exhaustive]` with `Default` and `with_*`
  builders, so fields can be added without a breaking release.

## Breaking changes

Nothing is wire-compatible with `main`; upgrade every node, the relay
and the Android app together.

- `iroh-moq` becomes `iroh-live-node` and `moq-transport-iroh`,
  `iroh-rooms` becomes `iroh-live-rooms`, and `moq-media` splits into
  the `moq-ext-*` crates.
- `Live` and `LiveBuilder` are gone in favour of `EndpointConfig`,
  `Node` and an application-owned router.
- Broadcasts move to `live/<endpoint id>/<name>`. `LiveTicket` becomes
  `BroadcastTicket` (`ilv1:`), room tickets use kind `room2`, and old
  tickets do not parse.
- `VideoTrack`, `AudioTrack` and `MediaTracks` become one `Player`.
- `RoomEvent` becomes the watched `RoomState`, `RoomPeer` becomes
  `RoomMember`, and chat leaves the library.
- The relay pulls tickets only for authorized sessions or with
  `--open-pulls`, and `irl record --latency` is now `--max-age`.

docs/migration.md lists every rename and removal with before and after
code.

## Testing

Beyond what `main` covered, CI now checks the Android JNI crate with
cargo-ndk, builds the relay and the facade without media on their own,
runs doctests and `cargo doc` with warnings denied, compiles the guide
programs in `docs/` as doctests, and checks the book's links. New
integration tests cover grants, re-authorization, tokens, relay pull
limits and calls, and the patchbay scenario for a switch on a capped
link, ignored on `main`, now runs.

## Known limitations

- noq 1.4 applies a raised stream priority to queued data only at the
  stream's next turn. New streams are unaffected, so switches are too.
- Sharing between equal-priority groups relies on noq's send fairness,
  its default. #97 removes that dependency once n0-computer/noq#859 is
  released.
- The relay decides an iroh client once and closes the session on
  expiry; the client redials with a fresh token.
- No transit: a node never forwards another node's broadcast.
- Changing a rendition's codec under the same name breaks decoding for
  viewers.
- `rpicam_h264` publishes one hardware-encoded rendition that does not
  adapt.
- The oldest-session rule can go once moq speaks a lite version that
  carries the publisher instance.
@Frando
Frando changed the base branch from Frando/cleanup-auth to main November 16, 2026 14:04
@Frando
Frando force-pushed the Frando/send-groups-incremental branch from b52f424 to 437eac9 Compare November 16, 2026 15:25
Frando and others added 2 commits November 18, 2026 11:15
Patches noq, noq-proto and noq-udp to the head of n0-computer/noq#859,
which adds a per-stream incremental flag with RFC 9218 semantics
(`SendStream::set_incremental`). The send groups in moq-transport-iroh
set it on every stream. The branch is noq 1.5.0, which iroh 1.4's
`noq = "1.4"` accepts, and one copy of each crate is in the tree.

NOT FOR MERGE until noq#859 lands in a release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sets RFC 9218's incremental flag on every stream moq-transport-iroh
opens or accepts, through `SendStream::set_incremental` from
n0-computer/noq#859. The heads of equal-priority send groups then share
the bytes round robin even when the connection's transport config turns
send fairness off, instead of relying on noq's default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Frando
Frando force-pushed the Frando/send-groups-incremental branch from 437eac9 to eac02eb Compare November 18, 2026 10:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant