From d1f2644135d51dcf58b34b3776c9e9772ea3ad13 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 20:16:43 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/unpublish.md Quest-Claim: 36c04cdc4bcb3864 From f692d9bfc59c67c1046609d4df66f08bd364acd7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 21:01:37 -0700 Subject: [PATCH 2/3] refactor: stop shipping unused API surface Apply the approved publication and feature boundaries, preserve real workspace consumers, and validate ICE sockets at construction. Co-Authored-By: GPT-6 --- bun.lock | 2 ++ demo/web/package.json | 4 ++- demo/web/src/meet.ts | 5 +++- doc/bin/relay/config.md | 5 ++-- doc/bin/rtc.md | 4 +-- doc/concept/transport.md | 6 +++-- doc/lib/rs/index.md | 6 ++--- doc/lib/rs/moq-room.md | 42 ++++-------------------------- js/p2p/MIGRATE.md | 4 +++ js/p2p/README.md | 2 ++ js/p2p/package.json | 6 ++--- js/room/MIGRATE.md | 5 ++++ js/room/src/index.ts | 11 -------- quest/m1/api-audit/README.md | 1 - quest/m1/api-audit/unpublish.md | 38 ---------------------------- quest/m2/e2ee/cli.md | 3 +++ quest/m2/p2p/udp-demux.md | 2 ++ quest/m2/p2p/watch.md | 4 +++ quest/m2/wire-stats/README.md | 3 +++ rs/moq-boy/Cargo.toml | 7 ++++- rs/moq-boy/MIGRATE.md | 2 +- rs/moq-boy/README.md | 2 +- rs/moq-boy/src/main.rs | 4 --- rs/moq-cli/Cargo.toml | 2 +- rs/moq-cli/MIGRATE.md | 6 +++++ rs/moq-e2ee/Cargo.toml | 1 + rs/moq-e2ee/MIGRATE.md | 4 +++ rs/moq-e2ee/README.md | 8 ++---- rs/moq-ice/MIGRATE.md | 7 +++++ rs/moq-ice/README.md | 2 +- rs/moq-ice/src/agent.rs | 20 +++------------ rs/moq-ice/src/lib.rs | 2 ++ rs/moq-ice/src/wire.rs | 45 ++++++++++++++++++++++++++++++--- rs/moq-relay/Cargo.toml | 5 +++- rs/moq-relay/MIGRATE.md | 6 +++++ rs/moq-relay/src/config.rs | 22 +++++++++++++++- rs/moq-relay/src/internal.rs | 8 ++++++ rs/moq-relay/src/lib.rs | 1 + rs/moq-relay/src/relay.rs | 9 +++++++ rs/moq-relay/src/settings.rs | 2 ++ rs/moq-relay/src/stun.rs | 2 +- rs/moq-room/Cargo.toml | 1 + rs/moq-room/MIGRATE.md | 4 +++ rs/moq-room/README.md | 2 ++ rs/moq-rtc/MIGRATE.md | 7 ++--- rs/moq-rtc/src/client/mod.rs | 12 +++------ rs/moq-rtc/src/client/whep.rs | 11 +++----- rs/moq-rtc/src/client/whip.rs | 7 +++-- rs/moq-rtc/src/lib.rs | 39 +++++----------------------- rs/moq-rtc/src/server/mod.rs | 2 -- rs/moq-rtc/src/server/whep.rs | 7 +---- rs/moq-rtc/src/server/whip.rs | 7 +---- rs/moq-rtc/src/session.rs | 10 +------- rs/moq-rtc/src/wire.rs | 19 -------------- rs/moq-tokio/MIGRATE.md | 5 ++++ rs/moq-tokio/src/lib.rs | 1 + rs/moq-tokio/src/webrtc.rs | 10 +++----- rs/qmux/README.md | 20 +++++++++++++++ 58 files changed, 239 insertions(+), 245 deletions(-) delete mode 100644 quest/m1/api-audit/unpublish.md delete mode 100644 rs/moq-rtc/src/wire.rs create mode 100644 rs/qmux/README.md diff --git a/bun.lock b/bun.lock index 847bffa72d3..a65db3ef54f 100644 --- a/bun.lock +++ b/bun.lock @@ -73,8 +73,10 @@ "@moq/clock": "workspace:*", "@moq/hang": "workspace:^", "@moq/json": "workspace:^", + "@moq/net": "workspace:^", "@moq/publish": "workspace:^", "@moq/room": "workspace:^", + "@moq/signals": "workspace:^", "@moq/watch": "workspace:^", }, "devDependencies": { diff --git a/demo/web/package.json b/demo/web/package.json index d31151a4134..d39a20449eb 100644 --- a/demo/web/package.json +++ b/demo/web/package.json @@ -17,7 +17,9 @@ "@moq/json": "workspace:^", "@moq/publish": "workspace:^", "@moq/room": "workspace:^", - "@moq/watch": "workspace:^" + "@moq/watch": "workspace:^", + "@moq/net": "workspace:^", + "@moq/signals": "workspace:^" }, "//devDependencies": "These are only needed for local development with workspace packages. They are NOT needed when using the published npm packages.", "devDependencies": { diff --git a/demo/web/src/meet.ts b/demo/web/src/meet.ts index 74465269f3d..e8643df2a3b 100644 --- a/demo/web/src/meet.ts +++ b/demo/web/src/meet.ts @@ -5,7 +5,10 @@ import "@moq/publish/support/element"; import "@moq/watch/support/element"; -import { Local, type Member, Net, Publish, Room, Signals } from "@moq/room"; +import * as Net from "@moq/net"; +import * as Publish from "@moq/publish"; +import { Local, type Member, Room } from "@moq/room"; +import * as Signals from "@moq/signals"; const RELAY_URL = import.meta.env.VITE_RELAY_URL ?? "http://localhost:4443"; diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index b76ef9e601c..6bc1d377ba4 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -231,8 +231,9 @@ renewal keeps the current certificate serving and retries. ## \[stun] -Applications can use the relay as an explicitly selected STUN server for WebRTC -ICE. The listener has its own UDP port and is disabled unless configured: +Build with `cargo install moq-relay --features stun` to use the relay as an +explicitly selected STUN server for WebRTC ICE. This feature is off by default. +The listener has its own UDP port and is disabled unless configured: ```toml [stun] diff --git a/doc/bin/rtc.md b/doc/bin/rtc.md index 18164216d24..d024188c442 100644 --- a/doc/bin/rtc.md +++ b/doc/bin/rtc.md @@ -38,6 +38,4 @@ under a fresh [epoch](/concept/moq-lite#publisher-epochs), so a publisher that reconnects while its stale session lingers replaces it at once. Built on [str0m](https://crates.io/crates/str0m); the library is -[`moq-rtc`](https://docs.rs/moq-rtc). Embedders can sample each peer's -[wire source](https://github.com/moq-dev/moq/blob/main/rs/moq-ice/src/wire.rs) for UDP -payload bytes, including media, control traffic, and retransmissions. +[`moq-rtc`](https://docs.rs/moq-rtc). diff --git a/doc/concept/transport.md b/doc/concept/transport.md index 9e55121898f..5c52b567907 100644 --- a/doc/concept/transport.md +++ b/doc/concept/transport.md @@ -65,14 +65,16 @@ See [stream listeners](/bin/relay/auth#stream-listeners). ## WebRTC data channels (experimental) -Applications that already negotiate a browser `RTCPeerConnection` can pass an +The private workspace P2P transport is exercised by `test/p2p`; it is not a +published package. Applications in this checkout that negotiate a browser +`RTCPeerConnection` can pass an [`@moq/p2p` transport](https://github.com/moq-dev/moq/tree/main/js/p2p) to `@moq/net`'s connect or accept. One reliable ordered data channel carries qmux records, with no datagrams. The application supplies signaling and ICE and keeps ownership of the peer connection; closing the transport closes only its channel. SCTP ordering means one lost packet can hold back every stream. -Native peers use `moq-tokio`'s `webrtc` feature, which runs its own ICE agent: +Native peers can opt into `moq-tokio`'s internal `webrtc` feature, which runs its own ICE agent: host candidates on every interface, server-reflexive candidates from the STUN servers it is given, and mDNS resolution of a browser's `.local` candidates. The application still carries the offer, answer, and candidates; the offering diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index 7d8d0f2424b..9e67f860511 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -23,7 +23,7 @@ see [Applications](/bin/). [Examples](/setup/examples) links runnable consumers; | [moq-tokio](https://docs.rs/moq-tokio) | Connects and listens over QUIC, WebSocket, or iroh, from config or CLI flags. Its `driver` feature alone is a tokio QUIC stack without MoQ. | | [qmux](https://docs.rs/qmux) | QUIC streams, datagrams, and flow control over TCP, TLS, WebSocket, and Unix sockets, on moq-quic's state machine. | | [moq-sock](https://docs.rs/moq-sock) | Socket binding and CPU pinning for thread-per-core listeners. | -| [moq-ice](https://github.com/moq-dev/moq/tree/main/rs/moq-ice) | The ICE agent behind native WebRTC: drives a str0m connection over UDP, with a STUN client. | +| [moq-ice](https://github.com/moq-dev/moq/tree/main/rs/moq-ice) | Internal infrastructure with no stability promise; the ICE agent behind native WebRTC: drives a str0m connection over UDP, with a STUN client. | | [moq-uring](https://docs.rs/moq-uring) | Experimental Linux io\_uring server for moq-lite. | | [hang](/lib/rs/hang) | The media layer: catalog, containers, ordered frame delivery. | | [moq-mux](/lib/rs/moq-mux) | Import and export fMP4/CMAF, MPEG-TS, Matroska, FLV, and Annex-B. | @@ -33,10 +33,10 @@ see [Applications](/bin/). [Examples](/setup/examples) links runnable consumers; | [moq-audio](/lib/rs/moq-audio) | Microphone and speaker, Opus/PCM/AAC codecs, echo cancellation. | | [moq-transcode](https://docs.rs/moq-transcode) | Just-in-time rendition ladders, GPU-resident on NVIDIA. | | [moq-auth](/lib/rs/moq-auth) | Relay authorization: JWT signing and verification, and the auth server contract. | -| [moq-room](/lib/rs/moq-room) | Headless rooms: announce-derived roster, token claims, and a chat track. | +| [moq-room](/lib/rs/moq-room) | Workspace-only native rooms; use the published JS room API for applications. | | [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | | [moq-flate](/lib/rs/moq-flate) | Opaque payloads over tracks, optionally compressed with group-scoped DEFLATE: snapshots or append logs. | -| [moq-e2ee](https://docs.rs/moq-e2ee) | End-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. | +| [moq-e2ee](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee) | Workspace-only end-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. | | [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. | | [moq-stats](https://docs.rs/moq-stats) | Publish and consume relay traffic counters as tracks. | | [moq-clock](/lib/rs/moq-clock) | One clock for time and timers on tokio, the browser, and a deterministic test simulator. | diff --git a/doc/lib/rs/moq-room.md b/doc/lib/rs/moq-room.md index 18f0bbc46be..0cee2f40f22 100644 --- a/doc/lib/rs/moq-room.md +++ b/doc/lib/rs/moq-room.md @@ -1,43 +1,11 @@ --- title: moq-room -description: Headless multi-participant rooms over MoQ +description: Native room implementation in the workspace --- # moq-room -[![crates.io](https://img.shields.io/crates/v/moq-room)](https://crates.io/crates/moq-room) -[![docs.rs](https://docs.rs/moq-room/badge.svg)](https://docs.rs/moq-room) - -The native twin of [`@moq/room`](/lib/js/room). A room is a path prefix. There -is no service and no storage: joining is minting a moq-auth token rooted at that -prefix and dialing the relay. Participants are discovered from the announce -stream. Identity is the path before `camera.hang` / `screen.hang`. - -Each participant publishes `{identity}/camera.hang` (camera + mic) and -`{identity}/screen.hang` (screenshare; its announce/unannounce is the share -lifecycle). Capture and encode stay in [`moq-video`](/lib/rs/moq-video) and -[`moq-audio`](/lib/rs/moq-audio). - -```bash -cargo add moq-room -``` - -```rust -use moq_net::Path; -use moq_room::{Kind, Room, claims}; - -let token = key.sign(&claims("meet/demo", "alice")?)?; -let origin = moq_tokio::origin::spawn(); -let mut room = Room::new(&origin.consume(), Some(Path::new("alice").to_owned())); -while let Some(event) = room.next().await { - if event.kind == Kind::Camera { - // event.broadcast is the live broadcast, or None once it goes offline. - } -} -``` - -Chat is `moq_room::chat`: a JSON window track named `chat` that keeps ten -seconds of messages. It is not hang.live's `hang/chat.json` catalog extension. - -Gossip, tickets, and 1:1 calls stay in iroh-live. API: -[docs.rs/moq-room](https://docs.rs/moq-room). +The native room implementation is workspace-only and is not published. +Use [`@moq/room`](/lib/js/room) for the published room API. +The [Rust source](https://github.com/moq-dev/moq/tree/main/rs/moq-room) +contains the native implementation and its tests. diff --git a/js/p2p/MIGRATE.md b/js/p2p/MIGRATE.md index 1dd9e38670a..146d905ad5b 100644 --- a/js/p2p/MIGRATE.md +++ b/js/p2p/MIGRATE.md @@ -3,3 +3,7 @@ How to update your code for each breaking change, newest first. ## Unreleased + +### Workspace-only package + +This package is private and has no release script. Use the workspace source for the `test/p2p` harness. diff --git a/js/p2p/README.md b/js/p2p/README.md index 36d258cd4e1..360ce9fe4ba 100644 --- a/js/p2p/README.md +++ b/js/p2p/README.md @@ -1,5 +1,7 @@ # @moq/p2p +Private workspace package, exercised by `test/p2p`; it is not published. + A WebTransport-shaped MoQ transport over one reliable ordered WebRTC data channel. Applications own signaling, ICE configuration, admission, and the `RTCPeerConnection`. The transport owns its data channel. Closing it leaves the peer connection open. diff --git a/js/p2p/package.json b/js/p2p/package.json index 053ee25fe96..c1b17b8ee5f 100644 --- a/js/p2p/package.json +++ b/js/p2p/package.json @@ -16,8 +16,7 @@ "scripts": { "build": "rimraf dist && tsc -b tsconfig.build.json && bun ../common/package.ts", "check": "tsc --noEmit && tsc --noEmit --project bench/tsconfig.json", - "test": "bun test --only-failures", - "release": "bun ../common/release.ts" + "test": "bun test --only-failures" }, "dependencies": { "@moq/qmux": "workspace:^" @@ -27,5 +26,6 @@ "@typescript/lib-dom": "npm:@types/web@^0.0.358", "rimraf": "^6.1.3", "typescript": "7.0.2" - } + }, + "private": true } diff --git a/js/room/MIGRATE.md b/js/room/MIGRATE.md index 323ee407a1f..0606da2203e 100644 --- a/js/room/MIGRATE.md +++ b/js/room/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Import dependencies directly + +The `Hang`, `Net`, `Publish`, `Signals`, and `Watch` namespace re-exports are removed. +Import from `@moq/hang`, `@moq/net`, `@moq/publish`, `@moq/signals`, and `@moq/watch` directly, and declare those packages in your application's dependencies. + ### Chat events carry their send time `Chat.Subscriber.recv()` returns `{ value, at }`: `value` is the event `recv()` used to return, and `at` is its frame's timestamp. diff --git a/js/room/src/index.ts b/js/room/src/index.ts index f9b2c4d89f9..960d67b0782 100644 --- a/js/room/src/index.ts +++ b/js/room/src/index.ts @@ -11,17 +11,6 @@ * @module */ -/** Re-export of {@link https://jsr.io/@moq/hang | @moq/hang}, the media layer. */ -export * as Hang from "@moq/hang"; -/** Re-export of {@link https://jsr.io/@moq/net | @moq/net}, the transport. */ -export * as Net from "@moq/net"; -/** Re-export of `@moq/publish`, which publishes each participant's media. */ -export * as Publish from "@moq/publish"; -/** Re-export of {@link https://jsr.io/@moq/signals | @moq/signals}, the reactive primitives used throughout this package. */ -export * as Signals from "@moq/signals"; -/** Re-export of `@moq/watch`, which plays each participant's media. */ -export * as Watch from "@moq/watch"; - /** Chat messages exchanged in the room. */ export * as Chat from "./chat.ts"; export { Local, type LocalProps } from "./local.ts"; diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index a223e5ad187..23c36519a73 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -74,7 +74,6 @@ Rejected in planning: - [The origin announces](/quest/m1/api-audit/announce-owner.md) - a broadcast producer cannot announce; the origin hands out the announcement, so `Prepared` and standalone broadcasts lose methods that always fail - [Sync.wait says what happened](/quest/m1/api-audit/sync-wait.md) - the decoder-facing `Sync` calls are internal and report present or skip; `jitter`, `probe`, and the `` compat shims are gone - [Auth access is patterns](/quest/m1/api-audit/auth-access.md) - token claims and grants carry path patterns only until a rate quest enforces caps, and `Key::decode` is gone -- [Unpublish what nothing uses](/quest/m1/api-audit/unpublish.md) - packages, features, and listeners with no consumer stop shipping or stop being on by default - [Container formats name inputs](/quest/m1/api-audit/container-format.md) - `ContainerFormat` names what is parsed, never how it is packaged; `ContainerStream` and TS passthrough internals are gone - [Binding connection state](/quest/m1/api-audit/binding-state.md) - one `state()` snapshot and `state_changed()` replace `status`, `connects`, and both `failure` polls - [moq-net exports with a consumer](/quest/m1/api-audit/net-exports.md) - Rust and JS model exports without a consumer go private, wrong ones are deleted, and JS names mirror Rust diff --git a/quest/m1/api-audit/unpublish.md b/quest/m1/api-audit/unpublish.md deleted file mode 100644 index fed775391ed..00000000000 --- a/quest/m1/api-audit/unpublish.md +++ /dev/null @@ -1,38 +0,0 @@ -# [S] Unpublish what nothing uses - -## Goal - -Packages, crates, features, and listeners with no consumer stop shipping in -this release or stop being on by default, so the release promises nothing -it does not use. - -## Plan - -Decided 2026-10-22 (API audit): - -- `@moq/p2p` (`js/p2p/package.json`, first publish at 0.1.0, only `test/p2p` - consumes it): `"private": true` until [P2P watch](/quest/m2/p2p/watch.md). -- `moq-e2ee`: `publish = false` until [E2EE CLI](/quest/m2/e2ee/cli.md); - `@moq/e2ee` is already private. -- Rust `moq-room`: `publish = false`; no consumer here or in moq.pro (the JS - package has `demo/web`). `@moq/room` stops re-exporting the whole Hang, - Net, Publish, Signals, and Watch namespaces. -- `moq-boy`: `[[bin]] required-features = ["openh264"]`, so `cargo install` - fails at build time instead of building a binary that refuses to start. -- moq-cli: drop `webrtc` from default features - (`rs/moq-cli/Cargo.toml`); the CLI never calls it, yet every build pulls - str0m, moq-ice, mdns-sd, and if-addrs. moq-tokio's `webrtc` module stays - behind its feature, `#[doc(hidden)]` until [P2P CLI](/quest/m2/p2p/cli.md). -- moq-relay's STUN server (`pub mod stun`, `Config.stun`, 537 lines): gate - behind a non-default `stun` feature until - [UDP demux](/quest/m2/p2p/udp-demux.md); nothing sets `stun.bind` and it - forces `stun-types` onto default-features-off embedders. -- moq-rtc: revert `Client::publish`/`subscribe` to `Result<()>` and drop - `pub mod wire` and `Response.wire` until - [wire stats](/quest/m2/wire-stats/README.md) lands its consumer. -- moq-ice stays published (moq-tokio and moq-rtc depend on it); document it - as internal with no stability promise and give `Socket` a constructor that - enforces non-empty `locals`. -- `qmux` 0.7.0 publishes without a README; add one. - -Public API: removes unconsumed surface. Wire: none. diff --git a/quest/m2/e2ee/cli.md b/quest/m2/e2ee/cli.md index 569277a17c8..becf9316b9f 100644 --- a/quest/m2/e2ee/cli.md +++ b/quest/m2/e2ee/cli.md @@ -8,6 +8,9 @@ Existing plaintext commands remain the default; an explicit application credenti ## Plan +Make `moq-e2ee` publishable with this CLI consumer; the crate currently sets +`publish = false` while it is workspace-only. + - Hand the [trait-generic CLI paths](/quest/m2/net-wrap/cli.md) an encrypted broadcast for publication and playback. Keep codec, capture, playback, and synchronization logic outside the crypto layer. - Accept the credential through a dedicated file descriptor, otherwise-unused stdin, or a permission-checked file (`0600` on Unix), never a command argument or environment variable. Redact errors and tracing, zeroize owned secret bytes, and document shell-safe invocation. - Follow the approved protected naming contract for mux, video, audio, diff --git a/quest/m2/p2p/udp-demux.md b/quest/m2/p2p/udp-demux.md index 5e9d115286d..b12cb04a508 100644 --- a/quest/m2/p2p/udp-demux.md +++ b/quest/m2/p2p/udp-demux.md @@ -39,6 +39,8 @@ Binding request without USERNAME is a public query; drop and count it. Decided 2026-10-08: the public STUN responder is left to the P2P line, so `moq-sock` takes no STUN codec dependency (str0m included). Decided 2026-10-13: it binds its own port ([relay STUN](/doc/bin/relay/config.md#stun)). +That listener and its settings are behind the relay's non-default `stun` +feature; consuming it must enable that feature explicitly. WebRTC: DTLS, RTP, and USERNAME-carrying STUN go to a `webrtc` hook that `moq-relay` leaves unconsumed and an embedder takes: the datagrams, a send diff --git a/quest/m2/p2p/watch.md b/quest/m2/p2p/watch.md index 43655535d32..a87e4f79244 100644 --- a/quest/m2/p2p/watch.md +++ b/quest/m2/p2p/watch.md @@ -9,6 +9,10 @@ the peer goes away, with no visible interruption. ## Plan +Publish `@moq/p2p` with its first application consumer in this quest. It is +currently private and has no release script; the `test/p2p` harness uses its +workspace source. + `moq-watch` and `moq-publish` gain a `p2p` attribute that constructs `Peers` on the shared connection's origin and its relay auth handle (see [Signaling and policy](/quest/m2/p2p/signal.md)), with the demo's ICE servers diff --git a/quest/m2/wire-stats/README.md b/quest/m2/wire-stats/README.md index f79e706149c..28362bcf87b 100644 --- a/quest/m2/wire-stats/README.md +++ b/quest/m2/wire-stats/README.md @@ -50,6 +50,9 @@ the stats producer samples and preserves their final values. Native tokio and io_uring QUIC sources and their relay integration tests are already on `main`. Reuse that registry and accounting; do not create another one. +The unused public RTC wire source was removed. Reintroduce one only with an +adapter that registers it on the shared stats handle for a real consumer. + Remaining here: finish the qmux and SRT adapter children, then verify their wire counters appear in the existing per-root presence and per-tier totals alongside native sessions, with final counts retained when a source closes. diff --git a/rs/moq-boy/Cargo.toml b/rs/moq-boy/Cargo.toml index 18a5ca44508..0b292f015c1 100644 --- a/rs/moq-boy/Cargo.toml +++ b/rs/moq-boy/Cargo.toml @@ -11,12 +11,17 @@ version = "0.5.12" edition = "2024" rust-version.workspace = true +[[bin]] +name = "moq-boy" +path = "src/main.rs" +required-features = ["openh264"] + [features] default = ["quic", "websocket"] jemalloc = ["moq-tokio/jemalloc"] # The software H.264 encoder. moq-boy needs it at runtime (a 160x144 frame is # below every hardware encoder's minimum), but it is vendored C++, so it stays -# off for development builds and refused at startup when missing. Defaulting it +# off for development builds; the binary requires it at build time. Defaulting it # on would turn it on for every workspace build through feature unification. # The nix package turns it on. openh264 = ["moq-video/openh264"] diff --git a/rs/moq-boy/MIGRATE.md b/rs/moq-boy/MIGRATE.md index b2f353dab50..129e32115ba 100644 --- a/rs/moq-boy/MIGRATE.md +++ b/rs/moq-boy/MIGRATE.md @@ -11,5 +11,5 @@ Add `--quic-keylog` (`MOQ_QUIC_KEYLOG`) to capture them; without `SSLKEYLOGFILE` ### Build with `--features openh264` (#5771) -moq-boy encodes with OpenH264, which is now opt-in, and refuses to start without it. +moq-boy encodes with OpenH264, which is now opt-in, and Cargo refuses to build or install its binary without it. Install with `cargo install moq-boy --features openh264`. The Nix package already enables it. diff --git a/rs/moq-boy/README.md b/rs/moq-boy/README.md index b9eb5f0d26c..2dcccd4ed8b 100644 --- a/rs/moq-boy/README.md +++ b/rs/moq-boy/README.md @@ -20,4 +20,4 @@ See the [demo](https://github.com/moq-dev/moq/tree/main/demo/boy) for the orches cargo install moq-boy --features openh264 ``` -The `openh264` feature is required: a Game Boy frame is below every hardware encoder's minimum size, so moq-boy refuses to start without the software encoder. +The `openh264` feature is required: a Game Boy frame is below every hardware encoder's minimum size, so Cargo refuses to build or install the binary without the software encoder. diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index bf19324aa5e..a3ac5a90d34 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -480,10 +480,6 @@ async fn main() -> Result<()> { let config = Config::parse(); config.log.init()?; config.check_deprecated()?; - // A 160x144 frame is below every hardware encoder's minimum, so OpenH264 is the only one. - if !cfg!(feature = "openh264") { - anyhow::bail!("built without the `openh264` feature: cargo install moq-boy --features openh264"); - } #[cfg(feature = "jemalloc")] let jemalloc = moq_tokio::jemalloc::run(); diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 19159747620..3eafda61367 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -26,7 +26,7 @@ path = "src/main.rs" doc = false [features] -default = ["cluster-lan", "quic", "websocket", "webrtc", "nvidia", "s3", "gcs", "azure"] +default = ["cluster-lan", "quic", "websocket", "nvidia", "s3", "gcs", "azure"] # Experimental transport with a heavy dependency tree, enabled only on request. iroh = ["moq-relay/iroh", "moq-tokio/iroh"] # LAN discovery and meshing (`--cluster-lan`). diff --git a/rs/moq-cli/MIGRATE.md b/rs/moq-cli/MIGRATE.md index 215b3a099ff..075b785aa8d 100644 --- a/rs/moq-cli/MIGRATE.md +++ b/rs/moq-cli/MIGRATE.md @@ -4,6 +4,12 @@ How to update your invocation and config for each breaking change, newest first. ## Unreleased +### Native WebRTC data channels are opt-in + +The default features no longer enable `moq_tokio::webrtc` data channels. +Enable `webrtc` explicitly in a source build that integrates that transport. +`moq import rtc` and `moq export rtc` still include the WHIP/WHEP gateway and its ICE dependencies. + ### `import fmp4` and `import hls` unwrap to Legacy (#6250) Both now publish one `legacy` frame per sample instead of one `cmaf` frame per fragment. diff --git a/rs/moq-e2ee/Cargo.toml b/rs/moq-e2ee/Cargo.toml index 7a33cb7d5d2..77a0a314ad6 100644 --- a/rs/moq-e2ee/Cargo.toml +++ b/rs/moq-e2ee/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "moq-e2ee" description = "End-to-end encryption for MoQ groups, datagrams, and track names." authors = ["Luke Curley "] diff --git a/rs/moq-e2ee/MIGRATE.md b/rs/moq-e2ee/MIGRATE.md index d73c02a1e3d..b6c141c1dec 100644 --- a/rs/moq-e2ee/MIGRATE.md +++ b/rs/moq-e2ee/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Workspace-only package + +This crate sets `publish = false`. Use the workspace source while no shipping application consumes it. + ### Tracks are named semantically through `broadcast` wrappers (#5876) `generation::Producer::produce` and `generation::Consumer::consume` are private. diff --git a/rs/moq-e2ee/README.md b/rs/moq-e2ee/README.md index a97f08c9c56..d15c2aabc01 100644 --- a/rs/moq-e2ee/README.md +++ b/rs/moq-e2ee/README.md @@ -1,19 +1,15 @@ -[![Documentation](https://docs.rs/moq-e2ee/badge.svg)](https://docs.rs/moq-e2ee/) -[![Crates.io](https://img.shields.io/crates/v/moq-e2ee.svg)](https://crates.io/crates/moq-e2ee) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/moq-dev/moq/blob/main/LICENSE-MIT) # moq-e2ee +Workspace-only implementation; this crate is not published. + End-to-end encryption for [Media over QUIC](https://moq.dev) groups, datagrams, and track names. Profile `moq-e2ee-00` from [draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/). Relays forward ciphertext. Content keys never enter `moq-net`. -```bash -cargo add moq-e2ee -``` - ## Shape The application distributes a `Credential { context, kid, secret }` over its own diff --git a/rs/moq-ice/MIGRATE.md b/rs/moq-ice/MIGRATE.md index 4be91a0b380..c609cff7a55 100644 --- a/rs/moq-ice/MIGRATE.md +++ b/rs/moq-ice/MIGRATE.md @@ -3,3 +3,10 @@ How to update your code for each breaking change, newest first. ## Unreleased + +### Construct `Socket` with advertised candidates + +Replace struct literals with `Socket::new(udp, locals, inbound)?`. +It refuses empty `locals` immediately with `std::io::ErrorKind::InvalidInput`; its fields are private so candidates cannot be emptied later. +Read candidates through `socket.locals()`. +This crate remains published for `moq-tokio` and `moq-rtc`, as internal infrastructure with no API stability promise. diff --git a/rs/moq-ice/README.md b/rs/moq-ice/README.md index 23d9f8b6a60..5c840fc8a02 100644 --- a/rs/moq-ice/README.md +++ b/rs/moq-ice/README.md @@ -8,5 +8,5 @@ str0m is sans-IO and requires every mutation to be followed by draining its output. `Agent::rtc_mut` hands out a guard that drains when dropped, so callers can't forget. -This is infrastructure, not an entry point: `moq-tokio`'s `webrtc` feature +This is internal infrastructure with no API stability promise: `moq-tokio`'s `webrtc` feature builds MoQ data channels on it, and `moq-rtc` builds its WHIP/WHEP gateway. diff --git a/rs/moq-ice/src/agent.rs b/rs/moq-ice/src/agent.rs index e94730a0626..88f1bedb7ce 100644 --- a/rs/moq-ice/src/agent.rs +++ b/rs/moq-ice/src/agent.rs @@ -115,19 +115,13 @@ pub struct Agent { } impl Agent { - /// Drive `rtc` over `socket`, which must have a host candidate. + /// Drive `rtc` over `socket`. pub fn new(rtc: Rtc, socket: Socket) -> std::io::Result { let Socket { udp: socket, locals, inbound, } = socket; - if locals.is_empty() { - return Err(std::io::Error::new( - std::io::ErrorKind::InvalidInput, - "no host candidate to receive on", - )); - } let socket_v6 = socket.local_addr()?.is_ipv6(); let now = Instant::now(); let mut agent = Self { @@ -479,11 +473,7 @@ mod tests { let local = socket.local_addr().unwrap(); let inbound = crate::reader(socket.clone()); let wire = inbound.wire.clone(); - let socket = Socket { - udp: socket, - locals: vec![local], - inbound, - }; + let socket = Socket::new(socket, vec![local], inbound).unwrap(); let mut agent = Agent::new(Rtc::builder().build(Instant::now().into_std()), socket).unwrap(); // Until tokio has seen the socket writable, a send waits in the outbox. @@ -507,11 +497,7 @@ mod tests { socket.set_nonblocking(true).unwrap(); let socket = Arc::new(UdpSocket::from_std(socket).unwrap()); let local = socket.local_addr().unwrap(); - let socket = Socket { - inbound: crate::reader(socket.clone()), - udp: socket, - locals: vec![local], - }; + let socket = Socket::new(socket.clone(), vec![local], crate::reader(socket)).unwrap(); Agent::new(Rtc::builder().build(Instant::now().into_std()), socket).unwrap() } diff --git a/rs/moq-ice/src/lib.rs b/rs/moq-ice/src/lib.rs index af782457c8e..2f8ff9a9e0b 100644 --- a/rs/moq-ice/src/lib.rs +++ b/rs/moq-ice/src/lib.rs @@ -1,6 +1,8 @@ //! The ICE side of a str0m peer connection: one UDP socket, its candidates, and //! the loop that drives an [`str0m::Rtc`] over it. //! +//! This crate is internal infrastructure with no API stability promise. +//! //! str0m is sans-IO, so [`Agent::next`] alternates between feeding it datagrams //! and timeouts and draining what it produces (transmits, events, the next //! timeout), and runs a STUN Binding client on the same socket so the agent can diff --git a/rs/moq-ice/src/wire.rs b/rs/moq-ice/src/wire.rs index 53c022371fd..638bcf6c6b5 100644 --- a/rs/moq-ice/src/wire.rs +++ b/rs/moq-ice/src/wire.rs @@ -19,12 +19,30 @@ pub const INBOX: usize = 256; /// and the host candidates it is reachable at. pub struct Socket { /// Sends datagrams, possibly shared by several agents (a demuxed server socket). - pub udp: Arc, + pub(crate) udp: Arc, /// The host candidates advertised to the peer, not the socket's bind address. /// Must not be empty. - pub locals: Vec, + pub(crate) locals: Vec, /// The datagrams routed to this agent. - pub inbound: Inbound, + pub(crate) inbound: Inbound, +} + +impl Socket { + /// Build a socket with at least one advertised host candidate. + pub fn new(udp: Arc, locals: Vec, inbound: Inbound) -> std::io::Result { + if locals.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "no host candidate to receive on", + )); + } + Ok(Self { udp, locals, inbound }) + } + + /// The advertised host candidates, which are never empty. + pub fn locals(&self) -> &[SocketAddr] { + &self.locals + } } /// The datagrams routed to one [`crate::Agent`], and the counters they are tallied in. @@ -76,7 +94,7 @@ impl Wire { } /// Pump every datagram from a socket the caller owns 1:1 into a queue for -/// [`Socket::inbound`], until the queue's receiver is dropped. +/// an agent, until the queue's receiver is dropped. pub fn reader(socket: Arc) -> Inbound { let (tx, rx) = mpsc::channel(INBOX); let wire = Wire::default(); @@ -104,3 +122,22 @@ pub fn reader(socket: Arc) -> Inbound { }); Inbound { packets: rx, wire } } + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn construction_refuses_a_socket_without_advertised_candidates() { + let udp = Arc::new(UdpSocket::bind("127.0.0.1:0").await.unwrap()); + let (_, packets) = mpsc::channel(INBOX); + let inbound = Inbound { + packets, + wire: Wire::default(), + }; + let Err(err) = Socket::new(udp, Vec::new(), inbound) else { + panic!("an unusable socket escaped construction"); + }; + assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput); + } +} diff --git a/rs/moq-relay/Cargo.toml b/rs/moq-relay/Cargo.toml index f672b08bdda..c9fcb333964 100644 --- a/rs/moq-relay/Cargo.toml +++ b/rs/moq-relay/Cargo.toml @@ -25,6 +25,8 @@ doc = false [features] # A programmatic relay fixture with generated TLS and ephemeral ports. test-support = [] +# The optional public STUN Binding listener (`--stun-bind`). +stun = ["dep:stun-types"] default = ["cluster-lan", "quic", "websocket", "uds"] iroh = ["moq-tokio/iroh"] # Discover cluster peers on the LAN with mDNS (`--cluster-lan`). @@ -81,7 +83,7 @@ rustls-acme = { version = "0.15.4", default-features = false, features = ["aws-l serde = { workspace = true } serde_json = { workspace = true } serde_with = { workspace = true, features = ["json", "base64"] } -stun-types = { workspace = true } +stun-types = { workspace = true, optional = true } sysinfo = { version = "0.39", default-features = false, features = ["system"] } thiserror = { workspace = true } tokio = { workspace = true, features = ["full"] } @@ -110,6 +112,7 @@ moq-shaper = { path = "../moq-shaper", features = ["test"] } qmux = { workspace = true, features = ["tcp"] } rand = { workspace = true } rcgen = { workspace = true, features = ["pem", "ring", "x509-parser"] } +stun-types = { workspace = true } tempfile = { workspace = true } time = { workspace = true } tokio = { workspace = true, features = ["test-util"] } diff --git a/rs/moq-relay/MIGRATE.md b/rs/moq-relay/MIGRATE.md index 866a7e1d2d0..e51e6440d56 100644 --- a/rs/moq-relay/MIGRATE.md +++ b/rs/moq-relay/MIGRATE.md @@ -5,6 +5,12 @@ Rolling a cluster across a release also follows the [upgrade guide](https://moq. ## Unreleased +### STUN requires an opt-in feature + +Enable the `stun` Cargo feature to use `moq_relay::stun`, `Config::stun`, or `--stun-bind` / `MOQ_STUN_BIND` / `[stun]`. +For example, install with `cargo install moq-relay --features stun`. +Default builds have no STUN listener or settings and refuse a STUN CLI flag, environment variable, or TOML table. + ### `receive_window` has a floor (#5878) The `[quic]` and `[peer.quic]` `receive_window` must be at least 67108880 bytes (64 MiB plus 16), or the relay refuses to start; the `[quic]` default is now 128 MiB. diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index 5e6a1370668..40149c52fc2 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -86,7 +86,8 @@ pub struct Config { #[serde(default)] pub acme: crate::acme::Config, - /// Optional public STUN Binding listener for application-selected ICE servers. + /// Optional public STUN Binding listener, available with the `stun` feature. + #[cfg(feature = "stun")] #[usage(flatten)] #[serde(default)] pub stun: crate::stun::Config, @@ -160,6 +161,7 @@ impl Default for Config { auth: Default::default(), web: Default::default(), acme: Default::default(), + #[cfg(feature = "stun")] stun: Default::default(), stats: Default::default(), cache: Default::default(), @@ -300,6 +302,12 @@ impl Config { env: &usage_rs::config::EnvLayer, file: Option>, ) -> anyhow::Result<()> { + #[cfg(not(feature = "stun"))] + anyhow::ensure!( + env.get("MOQ_STUN_BIND").is_none(), + "MOQ_STUN_BIND requires a moq-relay build with the stun feature" + ); + #[cfg(not(feature = "iroh"))] for name in [ "MOQ_IROH_ENABLED", @@ -387,6 +395,7 @@ mod tests { use super::*; use crate::test_env::EnvGuard; + #[cfg(feature = "stun")] #[test] fn stun_binding_merges_file_environment_and_cli() { let _env = EnvGuard::clear(&["MOQ_STUN_BIND"]); @@ -411,6 +420,17 @@ mod tests { assert!(toml::from_str::("[stun]\nrate = 10").is_err()); } + #[cfg(not(feature = "stun"))] + #[test] + fn a_stun_listener_requires_the_feature() { + assert!(toml::from_str::("[stun]\nbind = \"127.0.0.1:3478\"").is_err()); + assert!(Config::parse_and_merge(["moq-relay", "--stun-bind=127.0.0.1:3478"]).is_err()); + let cli = usage_rs::config::CliLayer::new(std::iter::empty::<(String, String)>()); + let env = usage_rs::config::EnvLayer::new([("MOQ_STUN_BIND".to_string(), "127.0.0.1:3478".to_string())]); + let error = Config::default().merge_into(&cli, &env, None).unwrap_err(); + assert!(error.to_string().contains("MOQ_STUN_BIND requires"), "{error}"); + } + #[test] fn session_limits_merge_without_crossing_peer_policy() { let _env = EnvGuard::clear(&[ diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index 873ef2aee5f..475b9b78f58 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -91,6 +91,7 @@ pub struct Internal { health: moq_tokio::accept::Health, listeners: Vec, uring: Vec, + #[cfg(any(feature = "stun", test))] stun: Option, shutdown: Option, listener: Option, @@ -105,6 +106,7 @@ struct InternalState { sessions: crate::session::Registry, listeners: Vec, uring: Vec, + #[cfg(any(feature = "stun", test))] stun: Option, shutdown: Option, } @@ -133,6 +135,7 @@ impl Internal { health, listeners, uring: Vec::new(), + #[cfg(any(feature = "stun", test))] stun: None, shutdown: None, listener: None, @@ -140,6 +143,7 @@ impl Internal { } } + #[cfg(feature = "stun")] pub(crate) fn with_stun(mut self, counters: Option) -> Self { self.stun = counters; self @@ -259,6 +263,7 @@ impl Internal { sessions: self.sessions.clone(), listeners: self.listeners.clone(), uring: self.uring.clone(), + #[cfg(any(feature = "stun", test))] stun: self.stun.clone(), shutdown: self.shutdown.clone(), }) @@ -334,6 +339,7 @@ async fn serve_health() -> Response { /// counts (`open - closed`). async fn serve_metrics(State(state): State) -> Response { let mut body = render_metrics(&state.stats.snapshot(), &state.listeners, &state.uring); + #[cfg(any(feature = "stun", test))] if let Some(stun) = &state.stun { stun.render(&mut body); } @@ -1102,6 +1108,7 @@ mod tests { sessions: crate::session::Registry::new(), listeners: Vec::new(), uring: Vec::new(), + #[cfg(any(feature = "stun", test))] stun: None, shutdown: None, }; @@ -1121,6 +1128,7 @@ mod tests { sessions: crate::session::Registry::new(), listeners: Vec::new(), uring: Vec::new(), + #[cfg(any(feature = "stun", test))] stun: None, shutdown: None, }; diff --git a/rs/moq-relay/src/lib.rs b/rs/moq-relay/src/lib.rs index b3ed94f3000..e3bf403fb35 100644 --- a/rs/moq-relay/src/lib.rs +++ b/rs/moq-relay/src/lib.rs @@ -35,6 +35,7 @@ pub mod session; mod settings; pub mod shutdown; pub mod stats; +#[cfg(any(feature = "stun", test))] pub mod stun; #[cfg(test)] mod test_env; diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index 41f0ca1af36..1e66018a97a 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -82,6 +82,7 @@ pub struct Relay { web: web::Web, /// The ACME client, issuing before [`Self::run`] serves and renewing after. acme: Option, + #[cfg(feature = "stun")] stun: Option, addr: Option, shutdown: shutdown::Observer, @@ -320,6 +321,7 @@ impl Relay { // starts them on its first accept. let server = server.bind().await.context("failed to bind listeners")?; + #[cfg(feature = "stun")] let stun = crate::stun::Server::bind(config.stun).await?; // Internal (ops) listener (plain HTTP, opt-in via `--internal-listen`) for @@ -335,6 +337,7 @@ impl Relay { .with_listeners(web.accept_health()) .with_listeners(server.accept_health()) .bind()?; + #[cfg(feature = "stun")] let internal = internal.with_stun(stun.as_ref().map(|stun| stun.counters.clone())); // Bound but not yet serving: registering here (rather than after the // threads start) is what gives every worker a series from the first @@ -363,6 +366,7 @@ impl Relay { internal, web, acme, + #[cfg(feature = "stun")] stun, addr, shutdown, @@ -539,6 +543,7 @@ impl Relay { internal, web, acme, + #[cfg(feature = "stun")] stun, shutdown, shutdown_trigger, @@ -725,10 +730,13 @@ impl Relay { }; let stun = async move { + #[cfg(feature = "stun")] match stun { Some(stun) => stun.run().await, None => std::future::pending().await, } + #[cfg(not(feature = "stun"))] + std::future::pending::>().await }; let result = tokio::select! { Err(err) = started.run() => Err(err).context("cluster failed"), @@ -842,6 +850,7 @@ async fn serve_listening( #[cfg(test)] #[allow(clippy::disallowed_methods, clippy::disallowed_types)] mod tests { + #[cfg(feature = "stun")] #[tokio::test] async fn stun_listener_runs_with_the_relay_and_stops_with_it() { use stun_types::message::{BINDING, Message, MessageWriteVec}; diff --git a/rs/moq-relay/src/settings.rs b/rs/moq-relay/src/settings.rs index 25ad57508b0..4e05245f342 100644 --- a/rs/moq-relay/src/settings.rs +++ b/rs/moq-relay/src/settings.rs @@ -43,6 +43,7 @@ pub struct Settings { #[usage(flatten)] stats: Stats, + #[cfg(feature = "stun")] #[usage(flatten)] stun: Stun, @@ -275,6 +276,7 @@ struct PeerQuic { send_window: Option, } +#[cfg(feature = "stun")] #[derive(usage_rs::Config)] #[usage(prefix = "stun")] struct Stun { diff --git a/rs/moq-relay/src/stun.rs b/rs/moq-relay/src/stun.rs index b5bd971935a..0c2cc7099bb 100644 --- a/rs/moq-relay/src/stun.rs +++ b/rs/moq-relay/src/stun.rs @@ -218,7 +218,7 @@ pub(crate) struct Server { } impl Server { - #[cfg(test)] + #[cfg(all(test, feature = "stun"))] pub(crate) fn addr(&self) -> SocketAddr { self.socket.local_addr().unwrap() } diff --git a/rs/moq-room/Cargo.toml b/rs/moq-room/Cargo.toml index 96f1f8bec74..baad70e1394 100644 --- a/rs/moq-room/Cargo.toml +++ b/rs/moq-room/Cargo.toml @@ -1,4 +1,5 @@ [package] +publish = false name = "moq-room" description = "Headless multi-participant rooms over MoQ: announce-derived roster, token claims, and a chat track." authors = ["Luke Curley "] diff --git a/rs/moq-room/MIGRATE.md b/rs/moq-room/MIGRATE.md index 1149a75e95a..cabeab6362f 100644 --- a/rs/moq-room/MIGRATE.md +++ b/rs/moq-room/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Workspace-only package + +This crate sets `publish = false`. Use the workspace source; the published room implementation is `@moq/room`. + ### `chat::PRIORITY` is signed (#6142) `chat::PRIORITY` is an `i8`, still 10. diff --git a/rs/moq-room/README.md b/rs/moq-room/README.md index 6b25df11ec2..b6b1b19bf85 100644 --- a/rs/moq-room/README.md +++ b/rs/moq-room/README.md @@ -1,5 +1,7 @@ # moq-room +Workspace-only implementation; this crate is not published. + Headless multi-participant rooms over [Media over QUIC](https://moq.dev/). A room is a path prefix. There is no service and no storage: joining is minting a moq-auth token rooted at that prefix. Participants are discovered from the announce stream. Identity is the path before `camera.hang` / `screen.hang`. Each participant publishes `{identity}/camera.hang` and `{identity}/screen.hang`. diff --git a/rs/moq-rtc/MIGRATE.md b/rs/moq-rtc/MIGRATE.md index 37b2b252a61..fa791368b5b 100644 --- a/rs/moq-rtc/MIGRATE.md +++ b/rs/moq-rtc/MIGRATE.md @@ -9,7 +9,8 @@ How to update your code for each breaking change, newest first. After a `DELETE`, a WHIP server session's `Response::run` finishes the ingest and resolves only once the finished broadcast goes stale. Drop the future to close the broadcast early. A peer that disconnects without one still closes it at once. -### Sessions return their UDP wire source (#5632) +### Client dials return `Result<()>` -`Client::publish` and `Client::subscribe` return `Result` instead of `Result<()>`. -Read per-peer byte counts with `source.stats()`, or discard it. +`Client::publish` and `Client::subscribe` return `Result<()>` again: successful negotiation starts the background media session. +Remove reads of their returned wire source, `Response::wire`, and `moq_rtc::wire`; this unused stats surface is removed. +`Response::run` still drives an accepted server session until it ends. diff --git a/rs/moq-rtc/src/client/mod.rs b/rs/moq-rtc/src/client/mod.rs index 00790466e99..69d8f67ed44 100644 --- a/rs/moq-rtc/src/client/mod.rs +++ b/rs/moq-rtc/src/client/mod.rs @@ -67,17 +67,13 @@ impl Client { /// `client subscribe`: pull a remote WHEP feed and publish it as /// `broadcast` on the local origin. Returns once the session is - /// running in the background, returning its cumulative UDP payload source. - pub async fn subscribe( - &self, - url: Url, - broadcast: moq_net::broadcast::Producer, - ) -> crate::Result { + /// running in the background. + pub async fn subscribe(&self, url: Url, broadcast: moq_net::broadcast::Producer) -> crate::Result<()> { whep::dial(self, url, broadcast).await } /// `client publish`: pull the broadcast at `path` from `origin` and push it to a - /// remote WHIP endpoint, returning its cumulative UDP payload source. + /// remote WHIP endpoint. /// /// Taking the origin plus path (rather than a resolved [`moq_net::broadcast::Consumer`]) /// lets the egress resolve a rendition whose catalog `broadcast` field references a @@ -87,7 +83,7 @@ impl Client { url: Url, origin: moq_net::origin::Consumer, path: impl moq_net::AsPath, - ) -> crate::Result { + ) -> crate::Result<()> { whip::dial(self, url, origin, path).await } } diff --git a/rs/moq-rtc/src/client/whep.rs b/rs/moq-rtc/src/client/whep.rs index 8f945c1aac0..26b448eb783 100644 --- a/rs/moq-rtc/src/client/whep.rs +++ b/rs/moq-rtc/src/client/whep.rs @@ -15,11 +15,7 @@ use url::Url; use crate::{Error, Result, client::Client, ingest::IngestSink, session}; -pub(crate) async fn dial( - client: &Client, - url: Url, - broadcast: moq_net::broadcast::Producer, -) -> Result { +pub(crate) async fn dial(client: &Client, url: Url, broadcast: moq_net::broadcast::Producer) -> Result<()> { let config = moq_mux::catalog::Config::default() .with_max_age(client.config().max_age) .with_bandwidth(client.config().bandwidth.clone()); @@ -27,7 +23,7 @@ pub(crate) async fn dial( let socket = session::bind_udp(&client.config().ice_candidates).await?; let mut rtc = Rtc::new(moq_clock::now().into_std()); - for addr in &socket.locals { + for addr in socket.locals() { let cand = Candidate::host(*addr, "udp").map_err(Error::rtc)?; rtc.add_local_candidate(cand); } @@ -65,11 +61,10 @@ pub(crate) async fn dial( for mid in mids { session.open_media(mid)?; } - let wire = session.wire(); tokio::spawn(async move { let result = session.run().await; session::log_session_end("whep client", &result); }); - Ok(wire) + Ok(()) } diff --git a/rs/moq-rtc/src/client/whip.rs b/rs/moq-rtc/src/client/whip.rs index 3727953664b..703dd817ee6 100644 --- a/rs/moq-rtc/src/client/whip.rs +++ b/rs/moq-rtc/src/client/whip.rs @@ -22,7 +22,7 @@ pub(crate) async fn dial( url: Url, origin: moq_net::origin::Consumer, path: impl moq_net::AsPath, -) -> Result { +) -> Result<()> { let broadcast = origin.request_broadcast(path, None).await?; let source = EgressSource::new(moq_mux::Source::new(origin, broadcast)).await?; let codecs = source.catalog_codecs(); @@ -34,7 +34,7 @@ pub(crate) async fn dial( // Restrict to codecs the catalog can actually source so the remote // answer doesn't pick a codec we have no rendition for. let mut rtc = session::rtc_with_codecs(&codecs); - for addr in &socket.locals { + for addr in socket.locals() { let cand = Candidate::host(*addr, "udp").map_err(Error::rtc)?; rtc.add_local_candidate(cand); } @@ -79,11 +79,10 @@ pub(crate) async fn dial( for mid in mids { session.open_media(mid)?; } - let wire = session.wire(); tokio::spawn(async move { let result = session.run().await; session::log_session_end("whip client", &result); }); - Ok(wire) + Ok(()) } diff --git a/rs/moq-rtc/src/lib.rs b/rs/moq-rtc/src/lib.rs index ae1087ccd33..77bafb9078b 100644 --- a/rs/moq-rtc/src/lib.rs +++ b/rs/moq-rtc/src/lib.rs @@ -25,12 +25,7 @@ //! (resolving the broadcast name from a verified token), skip the routers and //! call [`whip::accept`] (ingest) / [`whep::accept`] (egress) from your own //! handler. Return the [`Response::answer`] in your HTTP response, then run -//! [`Response::run`] to drive the media session for its lifetime. Clone -//! [`Response::wire`] before running it to sample the peer's cumulative UDP -//! payload bytes, including ICE, DTLS, RTP, RTCP, and retransmissions. Client -//! dials return the same [`wire::Source`]; its counters remain readable after -//! the session ends. [`wire::Source::stats`] can back an embedder's wire-source -//! registry without retaining the session or its socket. The routers and +//! [`Response::run`] to drive the media session for its lifetime. The routers and //! the `axum` re-export sit behind the default `server` feature, so such an //! embedder can drop them with `default-features = false`. //! @@ -45,7 +40,6 @@ pub mod client; pub mod server; -pub mod wire; // Implementation detail modules: these carry the WebRTC/str0m plumbing (str0m // `Rtc`, `Mid`/`Pt`, tokio channels, raw packet buffers) and are deliberately @@ -152,9 +146,8 @@ mod tests { .unwrap(); let answer = response.answer.clone(); let id = response.resource_id.clone(); - let wire = response.wire.clone(); let task = tokio::spawn(response.run()); - sources.send((id, wire, task)).await.unwrap(); + sources.send((id, task)).await.unwrap(); answer } }), @@ -171,9 +164,8 @@ mod tests { .unwrap(); let answer = response.answer.clone(); let id = response.resource_id.clone(); - let wire = response.wire.clone(); let task = tokio::spawn(response.run()); - sources.send((id, wire, task)).await.unwrap(); + sources.send((id, task)).await.unwrap(); answer } }), @@ -189,7 +181,7 @@ mod tests { let whip = format!("http://user:pass@{address}/whip/ingested?jwt=secret") .parse() .expect("WHIP URL"); - let whip_wire = tokio::time::timeout(TIMEOUT, client.publish(whip, source_consumer, "source")) + tokio::time::timeout(TIMEOUT, client.publish(whip, source_consumer, "source")) .await .expect("WHIP negotiation timed out") .expect("WHIP negotiation failed"); @@ -202,7 +194,7 @@ mod tests { let whep = format!("http://user:pass@{address}/whep/ingested?jwt=secret") .parse() .expect("WHEP URL"); - let whep_wire = tokio::time::timeout(TIMEOUT, client.subscribe(whep, output)) + tokio::time::timeout(TIMEOUT, client.subscribe(whep, output)) .await .expect("WHEP negotiation timed out") .expect("WHEP negotiation failed"); @@ -239,21 +231,8 @@ mod tests { .expect("read output Opus packet") .expect("output Opus track ended"); assert_eq!(frame.payload.as_ref(), OPUS_PACKET); - let (whip_id, whip_server_wire, whip_task) = sources_rx.recv().await.unwrap(); - let (whep_id, whep_server_wire, whep_task) = sources_rx.recv().await.unwrap(); - for source in [&whip_wire, &whep_wire, &whip_server_wire, &whep_server_wire] { - let stats = source.stats(); - assert!( - stats.tx > OPUS_PACKET.len() as u64, - "includes outgoing ICE/DTLS/RTP/RTCP: {stats:?}" - ); - assert!( - stats.rx > OPUS_PACKET.len() as u64, - "includes incoming ICE/DTLS/RTP/RTCP: {stats:?}" - ); - assert!(source.stats().tx >= stats.tx); - assert!(source.stats().rx >= stats.rx); - } + let (whip_id, whip_task) = sources_rx.recv().await.unwrap(); + let (whep_id, whep_task) = sources_rx.recv().await.unwrap(); assert!(server.terminate(&whep_id)); assert!(server.terminate(&whip_id)); tokio::time::timeout(TIMEOUT, whep_task) @@ -280,12 +259,8 @@ mod tests { .unwrap() .unwrap() .unwrap(); - let final_whip = whip_server_wire.stats(); - let final_whep = whep_server_wire.stats(); assert!(!server.terminate(&whip_id)); assert!(!server.terminate(&whep_id)); - assert_eq!(whip_server_wire.stats(), final_whip); - assert_eq!(whep_server_wire.stats(), final_whep); http.abort(); http.await.unwrap_err(); } diff --git a/rs/moq-rtc/src/server/mod.rs b/rs/moq-rtc/src/server/mod.rs index 1adc598316d..470b436a52c 100644 --- a/rs/moq-rtc/src/server/mod.rs +++ b/rs/moq-rtc/src/server/mod.rs @@ -33,8 +33,6 @@ pub struct Response { pub resource_id: String, /// The SDP answer body (`Content-Type: application/sdp`). pub answer: String, - /// This peer's cumulative UDP payload bytes, retained after the session ends. - pub wire: crate::wire::Source, session: AcceptedSession, } diff --git a/rs/moq-rtc/src/server/whep.rs b/rs/moq-rtc/src/server/whep.rs index 46006d4cf5a..5b546fbc580 100644 --- a/rs/moq-rtc/src/server/whep.rs +++ b/rs/moq-rtc/src/server/whep.rs @@ -159,11 +159,7 @@ pub async fn accept( let answer = rtc.sdp_api().accept_offer(offer).map_err(Error::rtc)?; let resource_id = sdp::new_resource_id(); - let socket = moq_ice::Socket { - udp: mux.socket(), - locals: mux.candidates().to_vec(), - inbound, - }; + let socket = moq_ice::Socket::new(mux.socket(), mux.candidates().to_vec(), inbound)?; let session = session::Session::egress(rtc, socket, source)?; // Register before returning so a DELETE that races startup still finds the @@ -173,7 +169,6 @@ pub async fn accept( Ok(Response { resource_id: resource_id.clone(), answer: sdp::render_answer(&answer), - wire: session.wire(), session: crate::server::AcceptedSession { server: server.clone(), resource_id, diff --git a/rs/moq-rtc/src/server/whip.rs b/rs/moq-rtc/src/server/whip.rs index b8c73285d7a..57a548c8f9f 100644 --- a/rs/moq-rtc/src/server/whip.rs +++ b/rs/moq-rtc/src/server/whip.rs @@ -153,11 +153,7 @@ pub async fn accept( handle.announce(moq_net::origin::Route::default().with_epoch(epoch.clone()))?; let resource_id = sdp::new_resource_id(); - let socket = moq_ice::Socket { - udp: mux.socket(), - locals: mux.candidates().to_vec(), - inbound, - }; + let socket = moq_ice::Socket::new(mux.socket(), mux.candidates().to_vec(), inbound)?; let session = session::Session::ingest(rtc, socket, sink)?; // Register before returning so a DELETE that races the first packet still @@ -168,7 +164,6 @@ pub async fn accept( Ok(Response { resource_id: resource_id.clone(), answer: sdp::render_answer(&answer), - wire: session.wire(), session: crate::server::AcceptedSession { server: server.clone(), resource_id, diff --git a/rs/moq-rtc/src/session.rs b/rs/moq-rtc/src/session.rs index 930e454d00f..0ae6883465c 100644 --- a/rs/moq-rtc/src/session.rs +++ b/rs/moq-rtc/src/session.rs @@ -129,10 +129,6 @@ impl Session { }) } - pub(crate) fn wire(&self) -> crate::wire::Source { - crate::wire::Source::new(self.agent.wire().clone()) - } - /// Open a locally offered media line after its answer has been applied. pub(crate) fn open_media(&mut self, mid: str0m::media::Mid) -> Result<()> { self.handle_media(mid) @@ -544,11 +540,7 @@ pub fn rtc_with_codecs(codecs: &[str0m::format::Codec]) -> Rtc { pub async fn bind_udp(advertise: &[SocketAddr]) -> Result { let udp = Arc::new(UdpSocket::bind(("0.0.0.0", 0)).await?); let locals = advertised_candidates(advertise, udp.local_addr()?)?; - Ok(moq_ice::Socket { - inbound: moq_ice::reader(udp.clone()), - udp, - locals, - }) + Ok(moq_ice::Socket::new(udp.clone(), locals, moq_ice::reader(udp))?) } /// Pair configured ICE candidates with the bound UDP port and validate them. diff --git a/rs/moq-rtc/src/wire.rs b/rs/moq-rtc/src/wire.rs deleted file mode 100644 index 2580970d852..00000000000 --- a/rs/moq-rtc/src/wire.rs +++ /dev/null @@ -1,19 +0,0 @@ -//! Cumulative UDP payload bytes for one WebRTC peer. - -/// A peer's cumulative datagram bytes, excluding IP and UDP headers. -pub use moq_ice::Stats; - -/// A read-only source whose counters survive the WebRTC session ending. -#[derive(Clone, Debug)] -pub struct Source(moq_ice::Wire); - -impl Source { - pub(crate) fn new(wire: moq_ice::Wire) -> Self { - Self(wire) - } - - /// Read cumulative sent and received UDP payload bytes; neither read consumes them. - pub fn stats(&self) -> Stats { - self.0.stats() - } -} diff --git a/rs/moq-tokio/MIGRATE.md b/rs/moq-tokio/MIGRATE.md index 4f4a034a986..308f731490c 100644 --- a/rs/moq-tokio/MIGRATE.md +++ b/rs/moq-tokio/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### WebRTC data channels are internal + +The feature-gated `webrtc` module is hidden from public API documentation while it has no application consumer. +Existing source integrations still enable the `webrtc` feature explicitly. + ### The connection receive window is 128 MiB, and has a floor (#5878) `quic::DEFAULT_RECEIVE_WINDOW` is 128 MiB instead of 64 MiB, since incomplete messages now hold connection credit until complete. diff --git a/rs/moq-tokio/src/lib.rs b/rs/moq-tokio/src/lib.rs index e85c43c01b5..f927e7111c9 100644 --- a/rs/moq-tokio/src/lib.rs +++ b/rs/moq-tokio/src/lib.rs @@ -76,6 +76,7 @@ mod util; #[cfg(feature = "watch")] pub mod watch; #[cfg(feature = "webrtc")] +#[doc(hidden)] pub mod webrtc; #[cfg(feature = "websocket")] pub mod websocket; diff --git a/rs/moq-tokio/src/webrtc.rs b/rs/moq-tokio/src/webrtc.rs index 01c86875102..11475199044 100644 --- a/rs/moq-tokio/src/webrtc.rs +++ b/rs/moq-tokio/src/webrtc.rs @@ -272,7 +272,7 @@ impl Offerer { async fn with_hosts(config: &Config, protocol: &str, hosts: Vec) -> Result<(Self, Offer), Error> { let protocol = negotiated(protocol)?; let socket = bind(&hosts)?; - let mut rtc = rtc(&socket.locals)?; + let mut rtc = rtc(socket.locals())?; let mut api = rtc.sdp_api(); let id = api.add_channel_with_config(ChannelConfig { @@ -362,7 +362,7 @@ impl Answerer { let parsed = SdpOffer::from_sdp_string(&sdp).map_err(|err| Error::Sdp(err.to_string()))?; let socket = bind(&hosts)?; - let mut rtc = rtc(&socket.locals)?; + let mut rtc = rtc(socket.locals())?; let answer = rtc .sdp_api() .accept_offer(parsed) @@ -853,11 +853,7 @@ fn bind(hosts: &[IpAddr]) -> Result { return Err(Error::NoHost); } let udp = Arc::new(socket); - Ok(moq_ice::Socket { - inbound: moq_ice::reader(udp.clone()), - udp, - locals, - }) + Ok(moq_ice::Socket::new(udp.clone(), locals, moq_ice::reader(udp))?) } /// Look up each STUN server. One that does not resolve is skipped, since a missing diff --git a/rs/qmux/README.md b/rs/qmux/README.md new file mode 100644 index 00000000000..9d22c57ae96 --- /dev/null +++ b/rs/qmux/README.md @@ -0,0 +1,20 @@ +# qmux + +[QMux](https://datatracker.ietf.org/doc/draft-ietf-quic-qmux/) carries QUIC streams, +datagrams, and flow control over reliable transports. This crate uses +`moq-quic`'s stream state machine and speaks draft-02 by default, negotiating +with draft-01 and draft-00 peers. + +Use `Session::connect` or `Session::accept` with a transport. The `tcp`, `tls`, +`uds`, and `ws` modules provide TCP, TLS, Unix socket, and WebSocket transports; +`transport::Stream` wraps another Tokio byte stream. Sessions implement +`moq_net::transport::poll` for MoQ's protocol layer. + +The default features are `tls` and `wss`. Opt into `tcp`, `uds`, or `ws` for the +corresponding unencrypted transport, or disable defaults when supplying your own. +Unix sockets require a Unix host. + +See the [API reference](https://docs.rs/qmux) and the +[client and server examples](https://github.com/moq-dev/moq/tree/main/rs/qmux/examples). +`just rs test --manifest-path rs/qmux/Cargo.toml --features tcp,ws` runs its +protocol tests and compatibility checks with qmux 0.6.3. From 3722c02a6c7a64acc893da70e2054b03f93c0c0b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 24 Oct 2026 07:59:30 -0700 Subject: [PATCH 3/3] fix(relay): gate main's STUN environment test behind the stun feature Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/config.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index 04fdf4bd7f2..20c3d203142 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -553,6 +553,7 @@ mod tests { assert!(error.to_string().contains("MOQ_STUN_BIND requires"), "{error}"); } + #[cfg(feature = "stun")] #[test] fn stun_binding_merges_the_environment() { if !test_env::Env::default().set("MOQ_STUN_BIND", "[::1]:3478").isolate() {