diff --git a/quest/m1/1059-init-tracks-for-cmaf.md b/quest/m1/1059-init-tracks-for-cmaf.md deleted file mode 100644 index 9f7d21cab93..00000000000 --- a/quest/m1/1059-init-tracks-for-cmaf.md +++ /dev/null @@ -1,20 +0,0 @@ -# [M] Init tracks for CMAF - -## Goal - -Implement and verify the behavior tracked in [#1059](https://github.com/moq-dev/moq/issues/1059) -within the issue's stated scope and boundaries. - -## Plan - -Still real: the CMAF init segment is base64-embedded in the catalog on both -branches. This is a catalog-format change across rs/hang, js/hang, moq-mux, -moq-hls, and draft-lcurley-moq-hang; land it on dev. - -### Issue context - -I was trying to be smart and put everything in the catalog, but there's a lot of issues with this approach. We should go back to a track per init segment. - -## Closes - -- [#1059](https://github.com/moq-dev/moq/issues/1059) - close this issue when the quest finishes diff --git a/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md b/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md index 2faa4e54a2c..d822523a612 100644 --- a/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md +++ b/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md @@ -9,8 +9,11 @@ within the issue's stated scope and boundaries. Rescoped during the 2026-08 grooming: subscription options, track info, abort codes, and client TLS roots landed in dev's rs/libmoq. Remaining gaps: -fetch_group, dynamic track/broadcast serving, server-side accept, and -datagrams, tracked against the dev FFI surface. +fetch_group, dynamic track serving within a broadcast, server-side accept, and +datagrams, tracked against the dev FFI surface. Broadcast serving is not in +this quest: the announce handle that advertises a prefix and yields its +requests reaches C through the bindings quest linked below, so do not add a +separate `requested_broadcast` path here. ### Issue context @@ -36,3 +39,7 @@ knob. `moq play` is the worked example of what the shape should be. ## Closes - [#2152](https://github.com/moq-dev/moq/issues/2152) - close this issue when the quest finishes + +## Related + +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - brings the announce handle and broadcast request serving to C diff --git a/quest/m1/2708-origin-open-the-announce-interest-lazily-on-first-consumer.md b/quest/m1/2708-origin-open-the-announce-interest-lazily-on-first-consumer.md deleted file mode 100644 index e3b9328ddf4..00000000000 --- a/quest/m1/2708-origin-open-the-announce-interest-lazily-on-first-consumer.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] origin: open the announce interest lazily, on first consumer - -## Goal - -Implement and verify the behavior tracked in [#2708](https://github.com/moq-dev/moq/issues/2708) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -A session wired to feed an origin (JS: the `subscribe` option in #2705; Rust: `Client::with_subscriber`) opens an announce-interest stream with an empty prefix as soon as it attaches, whether or not anything ever reads an announcement. On a large relay that is announce traffic and per-session announce state for every broadcast the session may see, paid even by an app that only publishes or only consumes known paths via requests. - -The origin knows whether anyone is interested: an open `announced()` stream, an announcement-gated watch handle, or (narrower) which prefixes they cover. The forwarder could open the wire announce stream only while interest exists, and scope it to the union of requested prefixes rather than the root. - -Applies to both implementations; neither is lazy today. The JS forwarder lives in `js/net/src/connection/forward.ts`; the Rust equivalent is the subscriber wiring in `rs/moq-net` session setup. - -## Closes - -- [#2708](https://github.com/moq-dev/moq/issues/2708) - close this issue when the quest finishes diff --git a/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md b/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md index eab63afe262..ceac56e0dc4 100644 --- a/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md +++ b/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md @@ -1,24 +1,63 @@ -# [S] per-broadcast bandwidth estimates and reservation +# [L] js/net: mirror the send-side bandwidth allocator ## Goal -Implement and verify the behavior tracked in [#2709](https://github.com/moq-dev/moq/issues/2709) -within the issue's stated scope and boundaries. +On a connection shared by several components (#2705), each JS publisher's +encoder targets its own share of the send-rate estimate instead of the +whole-session number, and audio reserves its bitrate so video's share is +honest. The split follows the Rust allocator exactly: strict priority tiers by +track priority, max-min fair within a tier, surplus left unclaimed. -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -The congestion controller's `estimatedSendRate` (and the PROBE receive estimate) are per-session. With #2705 sharing one session across every component on a page, that aggregate is the wrong number for any individual publisher: two publish components each cap their encoder at the full-session estimate and jointly overshoot, and a watcher's ABR reads a budget it shares with everything else on the connection. +Boundaries: the receive side is untouched. Watch ABR keeps reading the +whole-connection PROBE estimate until Rust has a receive-side split to mirror. -This is not a regression in kind (separate sessions just let congestion control arbitrate blindly), but sharing makes it structural. What is missing is a mechanism to split the session estimate across broadcasts: per-broadcast accounting at minimum, and ideally a way to reserve or prioritize bitrate so a publisher's encoder cap and a watcher's rendition selection each work against their own share rather than the whole pipe. +## Plan -Related: #2283 fed the session estimate into the encoder; catalog::Estimator (#2530) measures per-rendition receive rates. Neither divides the send budget. +The Rust side landed on `dev` in `rs/moq-net/src/model/bandwidth.rs` +(#2854): `Allocator::new(estimate)` / `unlimited()`, `reserve(&track::Demand, +max) -> Reservation`, `Reservation::{peek, consumer, update}` with `Drop` +removing the entry, and a pure `allocate(estimate, wants, id) -> Option` +where `None` means "not registered, hold your rate" and is distinct from a +zero grant. Only tracks whose demand is active claim anything. That module is +the spec; JS has no equivalent today. + +What JS does today: `js/publish/src/element.ts` polls `connection.stats()` +every 100 ms into one signal and hands it to the video encoder only, which +caps at `estimate * 0.9`; audio is invisible to it. `js/net` exposes +`Stats.estimatedSendRate` and the PROBE `estimatedRecvRate` but nothing +divides either. + +Steps: + +- Add a `bandwidth` module to `js/net` porting `Allocator`, `Reservation`, + and `allocate()` one to one, including the Rust unit tests. Rates are bits + per second as plain numbers. A reservation exposes its grant as a + `Getter` so encoders react through the signal model. +- Move the send-estimate sampler from `js/publish` into `js/net`: the + established connection owns one 100 ms `getStats()` loop and one + `Allocator`, shared across reloads, so every component on the connection + reserves against the same registry. +- Demand comes from the `js/net` track producer (active vs idle) and priority + from the track info the publisher set (`js/hang` `PRIORITY`: catalog 100, + audio 80, video 60), the same tiers Rust allocates on. +- `js/publish` video takes its reservation's grant instead of `estimate * + 0.9`; audio reserves at its configured bitrate and ignores the grant, which + matches Rust's audio today. Following the grant for Opus is the JS twin of + [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) + and stays out of scope. + +Tests: the ported `allocate()` cases verbatim; an integration test with two +publish components on one connection whose grants sum to at most the estimate +and rank by priority; a test that an idle track claims nothing. + +Branch from `dev`, where the shared connection and `forward.ts` live. ## Closes - [#2709](https://github.com/moq-dev/moq/issues/2709) - close this issue when the quest finishes + +## Related + +- [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - audio following its grant, the Rust half +- [#2859](/quest/m1/2859-passthrough-imports-reserve-no-bandwidth-so-a-co-resident.md) - passthrough imports reserving nothing +- [#2857](/quest/m1/2857-bindings-cant-reach-encoder-rate-control-so-every-non.md) - the same gap for the native bindings diff --git a/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md b/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md index f155908ee11..5795bb7ca25 100644 --- a/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md +++ b/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md @@ -1,39 +1,50 @@ -# [S] moq-tokio does not compile with --no-default-features, and workspace feature unification hides it +# [M] moq-tokio: compile with any subset of transport features ## Goal -Implement and verify the behavior tracked in [#2979](https://github.com/moq-dev/moq/issues/2979) -within the issue's stated scope and boundaries. +`cargo check -p moq-tokio --no-default-features` and every single-feature +build compile. A crate with no transport at all builds into something that +cannot connect; a `tcp` / `uds`-only build serves qmux. `moq-relay`, +`moq-cli`, `moq-bench`, and `moq-boy` compile with their own +`--no-default-features`. Nightly proves all of it per crate, so workspace +feature unification can never hide a break again. ## Plan -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -`cargo check -p moq-tokio --no-default-features` fails on `dev`. Found while reviewing #2977; the breakage predates #2921. - -#### Errors - -At `ca2fd504f` (before #2921 merged), 4 errors: - -- 2x `E0004: non-exhaustive patterns: type &RequestKind is non-empty` (all variants cfg'd out by the missing backend features, so the remaining matches don't compile) -- 2x `E0282: type annotations needed` - -`#2921` added a 5th: `E0433: cannot find util in crate` from `worker.rs`, which calls `crate::util::resolve` while `mod util` is gated on `any(noq, quinn, quiche)`. `worker::Workers::bind` now also references the equally-gated `crate::server::DEFAULT_BIND` (#2977), deepening the same dependency rather than introducing it. - -#### Why CI never sees it - -Nightly `just rs features` runs `--no-default-features` across the workspace, and cargo unifies features per crate: `moq-relay` (and everything else) depends on `moq-tokio` with a backend enabled, so `moq-tokio` never actually compiles with zero features in a workspace build. Only a `-p moq-tokio --no-default-features` invocation, or an external consumer with `default-features = false` and no backend feature, hits it. - -#### Options - -- Decide the backend-less configuration is unsupported and enforce it: `compile_error!` when no QUIC backend feature is enabled (a tcp/uds-only build would need its own thought), which turns 5 confusing errors into 1 honest one. -- Or make it compile: ungate `util`/`DEFAULT_BIND` (both are dependency-free), gate `worker`/`steer` on a backend, and fix the pre-existing `RequestKind` matches. - -The first is less work and matches reality: `worker`, `steer`, and `server` all assume a backend exists. +Decided: make it compile rather than `compile_error!`. `dev` already gates +`server`, `worker`, and `util` on a transport, hands `QuicBackend` an empty +choice list without a QUIC feature, and treats tcp-only as a real +configuration, so refusing the backend-less build would contradict the gates +the crate ships. The existing `compile_error!` for a rustls backend without a +crypto provider stays. + +What breaks today, measured on the pre-rename crate: + +- Zero features: four errors, all from `RequestKind` in `src/server.rs`. + Every variant is feature-gated, so the `request_ref!` / `request_into!` / + `request_map!` matches become non-exhaustive over an empty, still-inhabited + enum. Fix the macros to expand to an uninhabited match (`match *self {}`) + when no variant exists, or give the enum a gated never-variant. +- `tcp`-only relay and cli: `tls::Server::server_config` is gated on a QUIC + backend but called unconditionally. Split the gate so only the QUIC-specific + parts of `tls::Server` need a backend. +- The `steer` module the issue names no longer exists; `worker` and `util` + already share one gate on `dev`. + +Why nightly is green: `just rs features` runs `--workspace +--no-default-features`, and `moq-rtmp`'s dev-dependency enables +`moq-tokio/quinn` (so its RTMPS test can borrow the self-signed cert helper, +which needs `tls::Server`). Unification hands every crate a backend. Once +`tls` compiles without one, drop that pin, keeping `aws-lc-rs`. + +Even then relay and cli unify `tcp` and `aws-lc-rs` into `moq-tokio`, so add +per-crate coverage to `just rs features`: `cargo hack check -p moq-tokio +--each-feature --no-dev-deps --locked`, plus `cargo check -p +--no-default-features` for `moq-relay`, `moq-cli`, `moq-bench`, and +`moq-boy`. Add `cargo-hack` to the Nix dev shell next to `cargo-deny`; if it +must be installed in CI, pin the version, since `--locked` alone does not. + +Branch from `dev`: the crate exists only there. ## Closes diff --git a/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md b/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md index 010478f968f..2c8742b7349 100644 --- a/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md +++ b/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md @@ -1,64 +1,58 @@ -# [L] Align origin broadcast creation naming across language bindings +# [M] Bindings: create_broadcast, set_announce, and announce mean the same thing everywhere ## Goal -Implement and verify the behavior tracked in [#3190](https://github.com/moq-dev/moq/issues/3190) -within the issue's stated scope and boundaries. +Every native binding exposes the announce surface the Rust model settled on, +with one meaning per name: -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### After prefix routes - -This is now a semantics divergence, not only a naming one. -[moq#3225](https://github.com/moq-dev/moq/pull/3225) made Rust's -`origin::Producer::create_broadcast` stop announcing, while the FFI's -`create_broadcast` still announces the exact path on the caller's behalf (it -calls `announce(path, Default::default())` and hands back the guard), so -wrappers keep announcing by convention. Two surfaces now share one name and do -different things. - -Settle that before the rename: either the FFI's auto-announce becomes explicit -in the wrappers too, or the fused operation keeps a distinct name of its own. -Renaming both to `create_broadcast` without deciding hides the difference behind -matching spelling, which is worse than the inconsistency it fixes. - -### Issue context - -#### Problem - -The operation that allocates and owns a new broadcast has different names across public surfaces: - -- Rust FFI uses [`create_broadcast`](https://github.com/moq-dev/moq/blob/7494084aaf7e2fa6abe553ac83101ac4ef19f33a/rs/moq-ffi/src/origin.rs#L251-L267) -- Python, Swift, and Go expose `create_broadcast` or `CreateBroadcast`, for example [Go](https://github.com/moq-dev/moq/blob/7494084aaf7e2fa6abe553ac83101ac4ef19f33a/go/wrapper/origin.go#L38-L51) -- TypeScript uses [`publish(path)`](https://github.com/moq-dev/moq/blob/7494084aaf7e2fa6abe553ac83101ac4ef19f33a/js/net/src/origin.ts#L106-L107) -- C uses [`moq_origin_publish`](https://github.com/moq-dev/moq/blob/7494084aaf7e2fa6abe553ac83101ac4ef19f33a/rs/libmoq/src/api.rs#L1102-L1123) +- `create_broadcast` (Python, Rust) / `createBroadcast` (Swift, Kotlin) / + `CreateBroadcast` (Go) / `moq_origin_create_broadcast` (C) creates an + unadvertised broadcast. +- `set_announce(bool)` on the broadcast producer flips its exact-path advert. +- `announce(prefix, route)` returns the handle that advertises and serves + requests beneath the prefix. -`publish` suggests announcement or transmission. The operation actually creates a broadcast, while announcement visibility is controlled separately through `setAnnounce` or its equivalent. +No binding announces on the caller's behalf any more. -Issue #1073 changes Origin lifecycle but explicitly leaves naming outside its scope. - -#### Proposed direction - -Use the role-accurate creation verb consistently: - -- Rust and Python: `create_broadcast` -- TypeScript, Swift, and Kotlin: `createBroadcast` -- Go: `CreateBroadcast` -- C: `moq_origin_create_broadcast` - -If compatibility aliases are retained, keep deprecated names hidden from user-facing documentation according to the repository deprecation policy. - -#### Acceptance criteria +## Plan -- Every language uses its idiomatic spelling of the same `create broadcast` operation. -- Announcement APIs retain separate announce terminology. -- Examples and generated documentation use only the canonical name. -- Breaking renames target `dev`. +Today `rs/moq-ffi`'s `create_broadcast` calls `announce(path, ..)` internally +and stores the guard, so Python, Swift, Kotlin, Go, and C all inherit an +auto-announce that Rust does not have, while `MoqOriginDynamic` is a separate +type from `MoqAnnounce`. Two surfaces share a name and differ; that is what +the rename must not paper over. + +- moq-ffi: `MoqOriginProducer::create_broadcast(path)` stops announcing. + `MoqBroadcastProducer::set_announce(bool)` stays as the flip, now defaulting + to `false`. `MoqAnnounce` gains the request queue (`requested()` yielding + `MoqBroadcastRequest` with accept and reject) and `MoqOriginDynamic` is + deleted. +- libmoq: hard rename `moq_origin_publish` to `moq_origin_create_broadcast` + with no alias, `moq_publish_set_announce` kept, and announce/request + accessors mirroring the FFI. Regenerate `moq.h`; update `cpp/obs/src` and + the `cpp/obs/test` stub that declares the old symbol. +- Wrappers: `py/moq-rs`, `swift`, `kt`, and `go/wrapper` (flat on `dev`) + adopt the three verbs and drop any create-and-announce convenience. + `dart/` exists only on `main`, so it has its own quest gated on the merge. +- Docs: `doc/lib/{py,swift,kt,go,c}`, including the `doc/lib/py/moq-rs.md` + sentence that says `create_broadcast` creates an announced broadcast. + +Tests: each wrapper covers create, populate, `set_announce(true)`, visible in +`announced`; and `announce(prefix)` serving a request. Run `just test +smoke-full` since the FFI surface changed. + +Branch from `dev`: every rename is breaking. + +## Required + +- [Announce handle](/quest/m1/announce-handle.md) - the Rust surface these bindings mirror ## Closes - [#3190](https://github.com/moq-dev/moq/issues/3190) - close this issue when the quest finishes + +## Related + +- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the rest of the C ABI catch-up +- [JS announce](/quest/m1/js-announce.md) - the same alignment for js/net +- [Dart announce](/quest/m1/dart-announce.md) - the Dart wrapper, once `dev` merges diff --git a/quest/m1/816-expose-transportconfig.md b/quest/m1/816-expose-transportconfig.md index 7829b627437..35ef971a03d 100644 --- a/quest/m1/816-expose-transportconfig.md +++ b/quest/m1/816-expose-transportconfig.md @@ -1,25 +1,64 @@ -# [M] Expose TransportConfig +# [M] Expose QUIC flow-control windows on quic::Client and quic::Server ## Goal -Implement and verify the behavior tracked in [#816](https://github.com/moq-dev/moq/issues/816) -within the issue's stated scope and boundaries. +A Rust consumer of `moq-tokio` sets the QUIC flow-control windows through the +public `quic::Client` / `quic::Server` config, without patching the crate, and +every backend either applies the value or refuses it. The same fields reach +`moq-relay` TOML, CLI flags, and environment variables the way the existing +knobs do. + +Boundaries: no raw `quinn::TransportConfig` / quiche `Settings` escape hatch, +since that leaks a third-party type into the signature. Congestion control +stays the `CongestionControl { Loss, Delay }` family; no algorithm-level +names. No moq-ffi, libmoq, or js/net surface in this quest. ## Plan -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. +Everything else #816 asks for already exists on `quic::Client` and +`quic::Server` (`rs/moq-tokio/src/quic.rs`): `idle_timeout`, `keep_alive`, +`max_streams`, `gso`, `mtu_discovery`, `congestion_control`, `qlog`, each +wired to quinn, quiche, noq, and iroh, with clap long names, env vars, and +relay TOML. Flow-control windows are the one knob nobody can set. + +Add three `Option` byte fields to `quic::Client`, `quic::Server`, and +`quic::Resolved`, `None` meaning the backend default: + +- `receive_window`: the connection-wide receive window. +- `stream_receive_window`: the per-stream receive window. +- `send_window`: the cap on unacknowledged outgoing data. + +Follow the existing field conventions: `--client-quic-receive-window` / +`--server-quic-receive-window` long names, `MOQ_CLIENT_QUIC_RECEIVE_WINDOW` +env vars, serde for `[client.quic]` / `[server.quic]`, and validation next to +`validate_idle_timeout` (a window must fit a QUIC varint and must not be zero). -### Issue context +Backend wiring, in each backend's private apply function: -hello, +- quinn (and noq, which shares the shape): `TransportConfig::receive_window`, + `stream_receive_window`, `send_window`. +- quiche: `initial_max_data` for the connection window and + `initial_max_stream_data_bidi_local`, `_bidi_remote`, and `_uni` all from + the stream window. quiche has no local send cap, so a `send_window` on the + quiche backend is refused at resolve time with a config error, never + silently dropped. +- iroh: apply through its transport config where quinn's fields are + reachable; refuse anything it cannot apply, the way `gso = false` is refused + today. -It would be nice to be able to adjust transport window sizes, idle timeout, keep alive etc and also congestion controller used by quinn without needing to patch moq-native +Docs: `doc/bin/relay/config.md` documents the new fields and, while there, +the existing `[server.quic]` / `[client.quic]` fields it omits today +(`max_streams`, `idle_timeout`, `keep_alive`, `gso`, `mtu_discovery`, `qlog`, +`preferred_v4`, `preferred_v6`, `quic_lb_id`, `quic_lb_nonce`), since +`congestion_control` is the only one on the page. `doc/lib/rs/env/tokio.md` +shows the library form. -would that be possible? +Tests: a resolve test per field; a `moq-relay` config-merge test guarding the +windows against the CLI re-parse clobbering TOML, like the existing +`congestion_control` guard; a refusal test for `send_window` on quiche; and one +backend test per backend where the built transport config is inspectable. -thanks +Branch from `dev`: the crate is `moq-tokio` there. The change is additive. ## Closes diff --git a/quest/m1/README.md b/quest/m1/README.md index 8aa4f2407e6..0e51adba618 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -23,7 +23,7 @@ with the current dev tree before starting. - [#3092](/quest/m1/3092-moq-sock-make-the-reuseport-groups-invariants.md) - moq-sock: make the reuseport group's invariants unrepresentable, not documented - [#2924](/quest/m1/2924-moq-relay-tls-rotation-is-not-atomic-across-thread-per.md) - moq-relay: TLS rotation is not atomic across thread-per-core QUIC workers - [#2964](/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md) - QUIC workers: dropping one split() Server resizes the reuseport group -- [#2979](/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md) - moq-tokio does not compile with --no-default-features, and workspace feature unification hides it +- [#2979](/quest/m1/2979-moq-tokio-does-not-compile-with-no-default-features-and.md) - moq-tokio compiles with any subset of transport features, and nightly checks it per crate - [#2980](/quest/m1/2980-moq-relay-nothing-guards-the-socket-capturing-acceptor.md) - moq-relay: nothing guards the socket-capturing acceptor being installed on a listener - [#2853](/quest/m1/2853-quiche-with-a-pinned-source-port-can-dial-only-a-broken.md) - quiche with a pinned source port can dial only a broken IPv4 address - [#2624](/quest/m1/2624-moq-native-goaway-redirect-guard-classifies-hosts-by-name.md) - moq-native: GOAWAY redirect guard classifies hosts by name, not by resolved address @@ -33,14 +33,17 @@ with the current dev tree before starting. - [#2895](/quest/m1/2895-add-an-atomic-readiness-gate-for-origin-broadcasts.md) - Add an atomic readiness gate for Origin broadcasts - [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - js/net: path-keyed publisher state goes stale when a broadcast is replaced - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - net: coalesce dynamic tracks and preserve sequences across replacements -- [#2708](/quest/m1/2708-origin-open-the-announce-interest-lazily-on-first-consumer.md) - origin: open the announce interest lazily, on first consumer +- [Announce handle](/quest/m1/announce-handle.md) - announce(prefix, route) advertises and serves requests; create_broadcast plus set_announce publishes +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding exposes create_broadcast, set_announce, and announce with one meaning +- [JS announce](/quest/m1/js-announce.md) - js/net gets createBroadcast, an announce flag, and the announce handle +- [Dart announce](/quest/m1/dart-announce.md) - the Dart wrapper mirrors the same three operations once dev merges - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; gates the dev merge - [Playable](/quest/m1/hls-playable.md) - a 24/7 broadcast never becomes permanently unplayable over HLS - [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - Follow the bandwidth grant in moq-audio instead of holding a fixed reservation - [#2859](/quest/m1/2859-passthrough-imports-reserve-no-bandwidth-so-a-co-resident.md) - Passthrough imports reserve no bandwidth, so a co-resident encoder over-targets - [Ladder](/quest/m1/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling - [#2857](/quest/m1/2857-bindings-cant-reach-encoder-rate-control-so-every-non.md) - Bindings can't reach encoder rate control, so every non-Rust publisher ignores congestion -- [#2709](/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md) - per-broadcast bandwidth estimates and reservation +- [#2709](/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md) - js/net mirrors the send-side bandwidth allocator so each publisher encodes against its own share - [#3000](/quest/m1/3000-track-teardown-on-poll-unused-is-not-atomic-against-a.md) - Track teardown on poll_unused is not atomic against a consumer reattaching - [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - IETF stream resets send moq-lite error codes, so routine events read as INTERNAL_ERROR - [#3002](/quest/m1/3002-no-test-drives-a-late-group-through-the-ietf-dispatch-loop.md) - No test drives a late group through the IETF dispatch loop @@ -56,12 +59,10 @@ with the current dev tree before starting. - [#3051](/quest/m1/3051-config-merge-empty-lists-lose-to-the-environment-and-the.md) - Config merge: empty lists lose to the environment, and the file outranks it - [#3046](/quest/m1/3046-fold-moq-token-into-moq-token-via-a-usage-executable-view.md) - Fold moq-token into moq token via a Usage executable view - [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - moq-bench: every README example fails to parse, and cumulative latency percentiles cannot be windowed to steady state -- [#816](/quest/m1/816-expose-transportconfig.md) - Expose TransportConfig -- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - Align origin broadcast creation naming across language bindings +- [#816](/quest/m1/816-expose-transportconfig.md) - QUIC flow-control windows on quic::Client and quic::Server, applied or refused per backend - [#3188](/quest/m1/3188-make-every-blocking-go-operation-cancellable-with-context.md) - Make every blocking Go operation cancellable with context.Context - [#3208](/quest/m1/3208-make-2-5-ms-opus-frame-durations-work-across-bindings.md) - Make 2.5 ms Opus frame durations work across bindings - [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq: C ABI catch-up with the moq-ffi surface - [#2933](/quest/m1/2933-moq-ffi-moqroute-round-trip-erases-a-routes-cold-cost.md) - moq-ffi: MoqRoute round-trip erases a route's cold cost - [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - moq-net: ban Hop ID 0 from hop chains -- [#1059](/quest/m1/1059-init-tracks-for-cmaf.md) - Init tracks for CMAF - [#2248](/quest/m1/2248-moq-mux-rebase-fmp4-export-timestamps-for-late-subscribers.md) - moq-mux: rebase fMP4 export timestamps for late subscribers diff --git a/quest/m1/announce-handle.md b/quest/m1/announce-handle.md new file mode 100644 index 00000000000..47c042785e1 --- /dev/null +++ b/quest/m1/announce-handle.md @@ -0,0 +1,73 @@ +# [L] Fold on-demand serving into the announce handle + +## Goal + +`origin::Producer` has one way to advertise and serve a prefix and one way to +publish a broadcast: + +- `announce(prefix, route)` returns a handle that both advertises the route + and queues the requests beneath it that the broadcast tree cannot resolve; + the app accepts or rejects them. `dynamic()` is gone. +- `create_broadcast(path)` creates an unadvertised broadcast inside the + origin, and `broadcast::Producer::set_announce(bool)` flips its exact-path + advertisement once it is populated. + +Every in-tree caller compiles against that surface and the Rust docs describe +only it. Bindings and js/net follow in their own quests. + +## Plan + +Why the broadcast is born inside the origin rather than attached later: a +track binds to the origin's cache pool when it is created +(`cache::Track::new(broadcast.origin.pool, ..)` in +`rs/moq-net/src/model/track.rs`), so a standalone broadcast populated before +attach would keep the unbounded default pool. Create, populate, then announce +is the order, and the boolean is what makes the last step one call. + +Model changes in `rs/moq-net/src/model/origin.rs` on `dev`: + +- `announce(prefix, route) -> Announce` is today's crate-private + `announce_served` made public: the advert guard plus the `RouteServer` + request queue, merged into one handle. `Announce::update(route)` stays; + `poll_requested(waiter)` and an async `requested()` yield `Request` + (`path`, `accept`, `reject`). The queue is unbounded and drains only when + the handle drops, which retracts the advert and rejects what is queued. + Sessions use the same handle for the routes a peer announces to them. +- `dynamic()` and `origin::Dynamic` are deleted. A caller that served a root + fallback announces `""` instead; on `dev` the relay already announces + routes and only moq-mux tests still use `dynamic()`. +- A request resolves against the tree first, then the covering announce + chosen by the route ranking #3225 defined (hops, cost); its handle gets the + request. +- `create_broadcast(path)` keeps its signature and stays unadvertised. + `broadcast::Producer::set_announce(bool)` (default `false`) creates or drops + an exact-path advert that the origin owns alongside the tree entry, so the + advert retracts with the broadcast on finish or drop. +- `broadcast::Producer::dynamic()` (tracks on demand within a broadcast) is + untouched; the catalog is a track's announcement. + +In-tree migration in the same PR, since the change is breaking: the +create-then-announce pairs in `moq-cli`, `moq-bench`, `moq-boy`, `moq-hls`, +`moq-rtc`, `moq-transcode`, `moq-gst`, and `hang/examples` become +`create_broadcast` + `set_announce(true)`; `moq-relay` keeps +`announce(prefix, route)` for cluster and node routes; moq-mux tests move +from `dynamic()` to an announce handle. `moq-ffi` and `libmoq` get the minimal +internal change to keep compiling (their `MoqOriginDynamic` reads the announce +handle's queue); their public surface changes in the bindings quest. + +Docs: `doc/lib/rs/env/tokio.md`, `doc/lib/rs/crate/moq-net.md`, and the +`doc/concept` pages that mention dynamic serving describe only the new shape. + +Tests: an announce handle serves a request under its prefix; dropping an +unpolled handle rejects its queued requests; `set_announce` toggles what +`announced()` reports and retracts on finish; a consumer that subscribes on +the first announcement finds the populated tracks; two handles covering one +path rank by route. + +Branch from `dev`. + +## Related + +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - the bindings adopt this surface +- [JS announce](/quest/m1/js-announce.md) - js/net mirrors it +- [#2895](/quest/m1/2895-add-an-atomic-readiness-gate-for-origin-broadcasts.md) - readiness gating on the same producer diff --git a/quest/m1/dart-announce.md b/quest/m1/dart-announce.md new file mode 100644 index 00000000000..4340fe111b1 --- /dev/null +++ b/quest/m1/dart-announce.md @@ -0,0 +1,26 @@ +# [S] Dart: createBroadcast, setAnnounce, and announce + +## Goal + +The Dart wrapper, its generated `moq_ffi` bindings, tests, and +`doc/lib/dart` expose the same three announce operations as every other +binding: `createBroadcast` creates an unadvertised broadcast, `setAnnounce` +flips its exact-path advert, and `announce(prefix, route)` returns the handle +that advertises and serves requests. Nothing in Dart announces on the caller's +behalf. + +## Plan + +`dart/` exists only on `main`, while the FFI surface it must mirror lands on +`dev` in the bindings quest, so this cannot start until the two share a tree. +Today `dart/moq/lib/moq.dart` documents `createBroadcast` as create-and-announce +and `dart/moq/test/moq_test.dart` asserts the immediate announcement; both +change with the semantics. Regenerate `dart/moq_ffi` from `rs/moq-ffi`, adapt +the hand-written `dart/moq` wrapper, update the test to create, populate, then +`setAnnounce(true)`, add a test for `announce(prefix)` serving a request, and +update `doc/lib/dart/moq.md`. + +## Required + +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - the FFI surface this wrapper mirrors +- `dev` has merged into `main`, so `dart/` and the new FFI surface are in one tree diff --git a/quest/m1/js-announce.md b/quest/m1/js-announce.md new file mode 100644 index 00000000000..65a5b2b55f2 --- /dev/null +++ b/quest/m1/js-announce.md @@ -0,0 +1,42 @@ +# [M] js/net: createBroadcast, an announce flag, and an announce handle + +## Goal + +`Origin.Producer` in js/net has the same three operations as the Rust model: +`createBroadcast(path)` creates an unadvertised broadcast, the producer's +announce flag advertises its exact path once it is populated, and +`announce(prefix, route)` returns a handle that advertises the prefix and +yields the requests beneath it for the app to accept or reject. + +## Plan + +On `dev`, `Origin.Producer.publish(path)` creates and announces in one step +through the local table, and `announce(prefix, provider)` takes a +`RouteProvider` that serves requests through an interface the caller +implements. Both fuse two decisions and the second is callback-shaped. + +- Rename `publish(path)` to `createBroadcast(path)`, unadvertised. The + broadcast producer carries a settable announce flag in the signals idiom + (see `js/CLAUDE.md`), default off, retracted when the producer closes. +- `announce(prefix, route)` returns an `Announce` handle: `update(route)`, + `close()` to retract and reject, and `requested()` as an async iterator of + requests with `accept(broadcast)` and `reject(error)`. `RouteProvider` is + removed; `forward.ts` and the session code drive the handle instead. +- Consumers: `js/publish`, `js/watch`, `js/boy`, `demo/web`, and the + `doc/lib/js/@moq` pages that show `publish(path)`. + +Tests: `origin.test.ts` and `integration.test.ts` cover create then flag, +a handle serving a request under its prefix, and close rejecting queued +requests; `reload.test.ts` keeps the announce state across a reload. + +Branch from `dev`, where the origin table lives; the rename is breaking. + +## Required + +- [Announce handle](/quest/m1/announce-handle.md) - the shape is proven in Rust first + +## Related + +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - the native bindings half +- [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - publisher state on the same origin table +- [#2318](/quest/m1/2318-js-net-remaining-capability-gaps-vs-rs-moq-net-setup-role.md) - other js/net gaps vs rs/moq-net