From 3fb93887d5d79c5a7b22d5c1efbf80e01dd1955c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 16:44:03 -0700 Subject: [PATCH 01/11] quest(m3): plan Common Access Token support (#3689) Co-authored-by: Claude Opus 5 --- quest/m1/auth/package.md | 15 ++++--- quest/m3/README.md | 1 + quest/m3/cat/README.md | 68 ++++++++++++++++++++++++++++ quest/m3/cat/present.md | 42 +++++++++++++++++ quest/m3/cat/setup-token.md | 72 ++++++++++++++++++++++++++++++ quest/m3/cat/verify.md | 89 +++++++++++++++++++++++++++++++++++++ 6 files changed, 281 insertions(+), 6 deletions(-) create mode 100644 quest/m3/cat/README.md create mode 100644 quest/m3/cat/present.md create mode 100644 quest/m3/cat/setup-token.md create mode 100644 quest/m3/cat/verify.md diff --git a/quest/m1/auth/package.md b/quest/m1/auth/package.md index 3c915b398f2..3361a687bfd 100644 --- a/quest/m1/auth/package.md +++ b/quest/m1/auth/package.md @@ -45,12 +45,15 @@ lands the types and the move, and keeps the relay compiling until meter passes `Counters::default()`. `http://` is refused for a non-loopback host at construction, `https://` presents the given client identity, and `unix://` speaks HTTP over the socket. -- Move `rs/moq-token` in: `Claims { root, publish: Patterns, subscribe: - Patterns, expires, issued }` serialized as `root`, `publish`, `subscribe`, - `exp`, `iat`; the old `put` and `get` names are unknown fields and fail - verification. `Key`, `Jwk`, `KeyId`, `Algorithm`, the key set, and - `authorize` come over with their names, returning pattern residuals through - `moq_pattern`. `js/token` becomes `js/auth` with the same zod shapes plus +- Move `rs/moq-token` in under `moq_auth::jwt`, so a second token format + (a [Common Access Token](/quest/m3/cat/README.md)) gets a sibling module + instead of prefixed names while the contract types stay at the root: + `jwt::Claims { root, publish: Patterns, subscribe: Patterns, expires, + issued }` serialized as `root`, `publish`, `subscribe`, `exp`, `iat`; the + old `put` and `get` names are unknown fields and fail verification. + `Key`, `Jwk`, `KeyId`, `Algorithm`, the key set, and `authorize` come over + with their names under `jwt`, returning pattern residuals through + `moq_pattern`. `@moq/auth` stays flat; nothing else lands in JS. `js/token` becomes `js/auth` with the same zod shapes plus the request and grant schemas, so a Worker or a Node server validates a request and builds a grant with one import. The cross-language vectors in `js/token/src/interop.test.ts` move and gain a request and a grant. diff --git a/quest/m3/README.md b/quest/m3/README.md index 0d88cca6a0b..e0fae0d0042 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -29,3 +29,4 @@ its verdict lands and the follow-on work becomes concrete. - [Carrier voice](/quest/m3/carrier-voice/README.md) - determine whether MoQ should be the call fabric for programmable carrier voice - [LiveKit WebRTC bridge](/quest/m3/livekit-webrtc-bridge.md) - a go/no-go verdict, backed by a spike, on per-track LiveKit-to-MoQ bridging - [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract +- [Common Access Tokens](/quest/m3/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names diff --git a/quest/m3/cat/README.md b/quest/m3/cat/README.md new file mode 100644 index 00000000000..2b521adf9e9 --- /dev/null +++ b/quest/m3/cat/README.md @@ -0,0 +1,68 @@ +# Common Access Tokens + +## Goal + +A moq-transport client presents a Common Access Token +([draft-ietf-moq-c4m](https://datatracker.ietf.org/doc/draft-ietf-moq-c4m/)) +in the SETUP `AUTHORIZATION TOKEN` option and the relay admits it with the +scope the token's `moqt` claim names, through the same +[auth server](/quest/m1/auth/README.md) contract every other credential +uses. Our own clients can present one; `moq auth serve` verifies one; the +relay stays crypto-free and forwards the bytes. This is moq-transport only: +a CAT scopes itself by moq-transport message (`SUBSCRIBE`, `FETCH`, +`PUBLISH_NAMESPACE`, ...), which moq-lite has no equivalent for, so it rides +the SETUP option and nothing else. Nothing changes on the moq-lite wire or in +the URL, and the JWT stays the URL credential. + +Boundaries decided while planning: + +- SETUP only. A token on SUBSCRIBE, PUBLISH, FETCH, or any other request is + refused; per-operation authorization is not planned. The relay authorizes + per session through origin scopes, and a token that arrives after SETUP is + the [in-band auth](/quest/m2/auth/README.md) line's problem. +- A token whose `moqt` scope restricts the track name is refused naming the + token. Grants are broadcast-path patterns and tracks are not scoped. +- Core CWT claims plus `moqt` and `moqt-reval` are enforced; any other CAT + claim present (`catu`, `catm`, `catnip`, `catreplay`, `catdpop`, `cnf`, + geo, composite `or`/`and`/`nor`) refuses the token naming the claim, so a + restriction we do not evaluate never widens silently. DPoP (c4m section 3) + is out of scope. +- Wire codes follow c4m-01: Token Type `0x01` is the value the draft + registers for CAT. The `moqt` and `moqt-reval` claim keys are still + `TBD_MOQT`, so they are hard-coded constants with a doc comment saying so. + We do not expect to interop on these until the draft registers them. +- Rust only. `@moq/auth` gains nothing; `js/net` only carries bytes it was + handed into SETUP. +- [draft-ietf-moq-privacy-pass-auth](https://datatracker.ietf.org/doc/draft-ietf-moq-privacy-pass-auth/) + was considered and dropped. A Privacy Pass token carries only the digest of + its `TokenChallenge`, the draft never says how a relay hands a client the + challenge whose `origin_info` scopes the token, VOPRF tokens need the + issuer's secret at the verifier, and nobody is asking. Do not re-plan it + until the draft has a challenge exchange and a registered token type. + +## Plan + +Order: the wire first so a token reaches the auth server; verification; +then our clients present one. Everything requires the m1 auth line, which +owns the `Request` this rides, the server that answers it, and the +`moq_auth::jwt` module `cat` sits beside. + +## Quests + +- [Setup token](/quest/m3/cat/setup-token.md) - the SETUP `AUTHORIZATION + TOKEN` option is decoded on both IETF stacks, reaches `moq_auth::Request` + as `token`, and is refused on every other message +- [Verify](/quest/m3/cat/verify.md) - `moq_auth::cat` turns a CAT into a + grant and `moq auth serve` admits one; `moq auth sign|verify` mint and + check the format +- [Present](/quest/m3/cat/present.md) - a CAT is one kind of configured + token, riding the SETUP option the in-band token quest already writes + +## Related + +- [Auth server](/quest/m1/auth/README.md) - the contract, the lease, and the + server every quest here builds on +- [In-band auth](/quest/m2/auth/README.md) - credentials presented after + SETUP, which this line refuses on the IETF wire; its [Token in + band](/quest/m2/auth/token-in-band.md) quest owns the client token + configuration a CAT joins diff --git a/quest/m3/cat/present.md b/quest/m3/cat/present.md new file mode 100644 index 00000000000..f66617d8935 --- /dev/null +++ b/quest/m3/cat/present.md @@ -0,0 +1,42 @@ +# [S] A CAT is one kind of configured token + +## Goal + +`moq_tokio::connect::Config.tokens` and `js/net`'s connect `tokens` accept a +Common Access Token beside the JWTs they already hold, and a moq-transport +session carries it in the SETUP `AUTHORIZATION TOKEN` option with Token Type +`0x01`. The library does not read the bytes. A CAT never rides the URL or an +AUTH stream, so a client that configures one while offering a version without +the option fails loud instead of dropping the credential. + +## Plan + +- [Token in band](/quest/m2/auth/token-in-band.md) defines the client token + configuration and writes the first configured token into the setup option + as type 0. This quest makes the kind explicit: each configured token is a + `moq_net::setup::Token { kind, value }`, a JWT keeps kind `0x0` and its + URL and AUTH stream behavior, and a CAT is kind `0x01`. `--connect-token` + keeps taking a JWT; `--connect-cat ` (and `MOQ_CONNECT_CAT`) + adds a CAT. One CAT per connection: it is the connection credential, so a + configured CAT takes the setup option and the JWT that would have gone + there rides its AUTH stream instead. +- A CAT with any offered version that lacks the setup option (every lite + version) fails `init` with `Unsupported` naming the token; `js/net` + rejects the same way before dialing. +- `moq` CLI publish and subscribe get the flag through the shared connect + config; `doc/bin/cli.md` and `doc/lib/rs/moq-net.md` gain it. +- Tests: the server request sees kind `0x01` and the bytes on every draft + in Rust, JS, and across; a JWT still goes to the URL or AUTH stream when + a CAT holds the option; a lite offer with a CAT refuses at init; end to + end against `moq auth serve` with a CAT from `moq auth sign --format cat`. + +Public API: additive on `moq-tokio` and `js/net`. Wire: none. + +## Required + +- [Setup token](/quest/m3/cat/setup-token.md) - the server-side exposure + and the shared `setup::Token` +- [Verify](/quest/m3/cat/verify.md) - the server that admits the token the + end-to-end test presents +- [Token in band](/quest/m2/auth/token-in-band.md) - the token + configuration and setup-option writer this adds a kind to diff --git a/quest/m3/cat/setup-token.md b/quest/m3/cat/setup-token.md new file mode 100644 index 00000000000..2f34ae2b036 --- /dev/null +++ b/quest/m3/cat/setup-token.md @@ -0,0 +1,72 @@ +# [M] The SETUP AUTHORIZATION TOKEN option reaches the auth server + +## Goal + +A moq-transport peer's SETUP `AUTHORIZATION TOKEN` option (type `0x03`, +draft-14 through the newest supported draft) is decoded by `rs/moq-net` and +`js/net` into a token type and value, exposed on the accepted request, and +forwarded by the relay in `moq_auth::Request` as `token`, so an auth server +can verify it. The same parameter on any other message is refused. Today the +option is stored as opaque bytes and ignored, and the message parameter fails +decode as an unknown key. + +## Plan + +- `moq_net::setup::Token { kind: u64, value: Vec }`, `kind` being the + wire Token Type: `Token::OUT_OF_BAND` is `0x0` and `Token::CAT` is the + `0x01` c4m-01 registers. This is the type [Token in + band](/quest/m2/auth/token-in-band.md) writes for a configured JWT + (`USE_VALUE`, type 0), so the two quests share one struct and one encoder; + whichever lands first adds them. Decode the draft-21 section 8.9 + structure: Alias Type `USE_VALUE` yields the token; `REGISTER` is treated + as `USE_VALUE` because we advertise no `MAX_AUTH_TOKEN_CACHE_SIZE` (the + default of 0 makes that the draft's own rule), so no alias state exists; + `DELETE` or `USE_ALIAS` in SETUP closes with `PROTOCOL_VIOLATION`; an + undecodable structure closes with `KEY_VALUE_FORMATTING_ERROR`. More than + one token in SETUP is refused: one credential per connection is the shape + the contract has. +- Encode side: `Parameters` learns to write a `USE_VALUE` token so + [Present](/quest/m3/cat/present.md) has nothing to add on the wire. +- Message parameter `0x03` on SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, + PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, TRACK_STATUS, and every other + message whose decoder reads parameters decodes and is refused with the + request's error path (`Unsupported`, mapped through `to_code` for the + draft) naming the parameter, so the session survives and the log says why. + Both decoder families change: the strict `decode_params!` path on newer + drafts, which rejects the key today, and the generic KVP path the legacy + drafts use, which keeps an odd key and lets the caller ignore it. +- `moq_net::Request::token() -> Option<&setup::Token>` on the accepted + request, carried through the `Legacy` (draft-14 to 16) and `PeerSetup` + (draft-17+) paths; `moq_tokio::server::Request` forwards it; lite sessions + return `None`. +- `moq_auth::Request.token: Option`, + serialized with `serde_with` base64 like the rest of the request. The relay + fills it where it builds the request, beside the URL query it already + forwards. `moq auth serve` treats kind `0x0` as the JWT the deployment + negotiated out of band, verified exactly like `?jwt=`, refuses a kind it + does not know naming the code, and hands `0x01` to + [Verify](/quest/m3/cat/verify.md). A request carrying both a SETUP token + and a `jwt` query is refused naming both. +- `js/net/src/ietf/parameters.ts` mirrors the decode and encode, and the + `SetupOption.AuthorizationToken` handling in `handshake.ts`; the JS accept + side exposes the token on its request the same way. +- Docs: `doc/concept` on the IETF binding gains the option and the refusal; + `doc/lib/rs/moq-auth.md` gains the request field. +- Tests: decode and encode round trips for every alias type on every draft + in Rust and JS; `DELETE`/`USE_ALIAS` in SETUP close the session; + `REGISTER` is accepted as a value; a token on SUBSCRIBE is refused and the + session continues, on one legacy draft and one strict draft; the relay forwards the bytes to a wiremock auth server + byte for byte; a lite session reports none. + +Public API: additive on `moq-net`, `moq-tokio`, `moq-auth`, and `js/net`. +Wire: none new; the option already exists in every supported draft. + +## Required + +- [Relay](/quest/m1/auth/relay.md) - the relay builds `moq_auth::Request` + there; this quest adds one field to it + +## Related + +- [Token in band](/quest/m2/auth/token-in-band.md) - writes the same option + from the client side with the shared `setup::Token` diff --git a/quest/m3/cat/verify.md b/quest/m3/cat/verify.md new file mode 100644 index 00000000000..2bb2a44ae8e --- /dev/null +++ b/quest/m3/cat/verify.md @@ -0,0 +1,89 @@ +# [M] moq auth serve admits a Common Access Token + +## Goal + +`moq_auth::cat` verifies a CAT (CTA-5007-B, a CWT under COSE_Mac0 or +COSE_Sign1) and turns its `moqt` and `moqt-reval` claims into a `Grant`, and +`moq auth serve` admits a connection whose SETUP token is one, with keys the +operator hands it. `moq auth sign --format cat` mints one and `moq auth +verify --format cat` checks one, so tests and operators have a way to make +tokens. Every claim we do not evaluate refuses the token naming the claim. + +## Plan + +- Crates: `coset` for COSE and CWT claims, `ciborium` for CBOR; HMAC through + the `aws-lc-rs` the crate already links, ES256 through `p256`. Keys reuse + `moq_auth::jwt::Key` files: a JWK with `alg` maps to the COSE algorithm + (`HS256` to HMAC 256/256, `ES256` to -7, `EdDSA` to -8, `RS256` to -257); + a JWK whose algorithm has no COSE mapping is refused at load naming it. +- `cat::Claims { issuer, audience, subject, expires, not_before, issued, + id, scopes: Vec, revalidate: Option }` where + `cat::Scope { actions: Vec, namespace: Option>, + exact_depth: bool, track: Option }` follows the c4m-01 CDDL: + `cat::Match` is `Exact(bytes)`, `Prefix(bytes)`, or `Suffix(bytes)`, one + per namespace field in order, the trailing `nil` becomes `exact_depth`, + and `nil` anywhere else refuses the token. `cat::Action` is the c4m-01 + table 1 enum (`ClientSetup`, `ServerSetup`, `PublishNamespace`, + `SubscribeNamespace`, `Subscribe`, `RequestUpdate`, `Publish`, `Fetch`, + `TrackStatus`). Claim keys `moqt` and `moqt-reval` are provisional + constants in the CWT private-use range with a doc comment; they change + when the draft registers them. +- `Claims::verify(token, keys)` checks the signature or MAC against the key + set by `kid`, then `exp`, `nbf`, and `iat` against now, then walks the + claim set: anything outside `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, + `cti`, `moqt`, and `moqt-reval` refuses the token naming the label. +- `Claims::grant(&self, root) -> Result`: for every scope, + `Publish` adds the namespace pattern to `publish` and `Subscribe` adds it + to `subscribe`. The grant has no narrower verbs, so `PublishNamespace` is + accepted only beside `Publish`, and `SubscribeNamespace`, `RequestUpdate`, + `Fetch`, and `TrackStatus` only beside `Subscribe`; a scope whose actions + are narrower than either verb refuses the token naming the scope rather + than widening a fetch-only token into a live subscription. `ClientSetup` + and `ServerSetup` add nothing. The namespace fields become one `moq_pattern::Pattern` segment + each, the mapping `rs/moq-pattern` documents under "CAT / C4M", relative + to the dialed path exactly as `jwt::Claims::root` is: `Exact(f)` is the + literal segment, `Prefix(f)` is `f*`, `Suffix(f)` is `*f`, a named + namespace without `exact_depth` appends `/**`, and an absent namespace is + bare `**` with nothing appended. A field value containing `/` or `*` + cannot be a segment and refuses the token naming the scope. `f*` and `*f` + are patterns the relay only admits once [Origin + scopes](/quest/m2/path-patterns/origin.md) lifts its prefix-shaped + adapter, which is why that quest is required here. A scope with a track match is refused naming the scope. + `exp` is `expires`, `moqt-reval` is + `revalidate`, and `Grant::validate` keeps refusing a cadence without an + expiry, so the serve default `--expires` applies to a token without `exp` + the way it does for a JWT. A token that grants nothing is refused. +- `moq auth serve`: `--cat-key ` and `--cat-key-dir ` beside + `--key`, `--cat-issuer ` and `--cat-audience ` required to + match `iss` and `aud` when set. Policy order: a SETUP `token` is decided + first and never falls through; then the existing `jwt` query, mTLS, + public. +- `moq auth sign --format cat` and `verify --format cat` in `rs/moq-cli`, + sharing `--publish`/`--subscribe` patterns with the JWT form and emitting + one `moqt` scope per pattern through the inverse of the mapping above (a + literal segment is `Exact`, `f*` is `Prefix`, `*f` is `Suffix`, a trailing + `**` drops `nil`, a pattern with `**` elsewhere or `a*b` is refused naming + it) with the actions each verb implies; `--revalidate ` sets + `moqt-reval`. Output is the raw CWT bytes, or base64url with `--base64`. +- Docs: `doc/lib/rs/moq-auth.md` gains the module, `doc/bin/cli.md` the + flags, `doc/bin/relay/auth.md` a CAT section with the provisional codes + and the refused-claims list. +- Tests: sign and verify under each mapped algorithm; each refused claim; + each match kind mapped or refused, `nil` placement, and the moq-pattern + vectors round-tripped both ways; expiry and not-before; the grant + produced from every c4m-01 example; serve admitting a CAT over a real + moq-transport session on every supported draft and refusing an unknown + token kind, a bad MAC, and a token plus `jwt`; the CLI round trip. + +Public API: `moq_auth::cat` new, `moq auth serve` and `moq auth sign|verify` +gain flags. Wire: none. + +## Required + +- [Package](/quest/m1/auth/package.md) - supplies `moq_auth::jwt`, which + `cat` sits beside +- [Origin scopes](/quest/m2/path-patterns/origin.md) - the relay admits + `f*` and `*f` grants only after it +- [Setup token](/quest/m3/cat/setup-token.md) - the token reaches the + server's request +- [Serve](/quest/m1/auth/serve.md) - the server this extends From c362e0d33679a4bbb2dcc4b2ee44614948e230a7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 18:22:03 -0700 Subject: [PATCH 02/11] quest(m1): libmoq track demand and dynamic track requests (#3692) Co-authored-by: Claude Opus 5 --- ...c-abi-catch-up-with-the-moq-ffi-surface.md | 7 +- quest/m1/README.md | 1 + quest/m1/libmoq-track-demand.md | 99 +++++++++++++++++++ 3 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 quest/m1/libmoq-track-demand.md 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 594686bafe8..f159ffd168e 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,10 @@ 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 serving within a broadcast, server-side accept, and -datagrams, tracked against the dev FFI surface. Broadcast serving is not in +fetch_group, server-side accept, and datagrams, tracked against the dev FFI +surface. Dynamic track serving, dynamic group serving, and demand split into +the track demand quest linked below; `fetch_group` on the consume side stays +here. 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. @@ -42,4 +44,5 @@ feature over `moq-video` (NVIDIA and VAAPI on), but `libmoq`'s ## Related +- [Track demand](/quest/m1/libmoq-track-demand.md) - track requests and used/unused on the C ABI - [#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/README.md b/quest/m1/README.md index 255b6f0f80d..c59886cd489 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -83,6 +83,7 @@ with the current dev tree before starting. - [#3188](/quest/m1/3188-make-every-blocking-go-operation-cancellable-with-context.md) - Make every blocking Go operation cancellable with context.Context - [Native Go context](/quest/m1/go-native-context.md) - the Go generator emits context.Context itself, retiring the hand-rolled cancellation token - [#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 +- [Track demand](/quest/m1/libmoq-track-demand.md) - a C publisher sees used/unused per track and serves dynamic track and group requests, so an encoder runs only while someone watches - [#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 - [Route cold cost](/quest/m1/route-cold-cost.md) - MoqRoute carries warm and cold, so an observed route re-announces intact - [Anonymous rank](/quest/m1/anonymous-route-rank.md) - moq-net: a route through an anonymous hop ranks below every identified route at any cost, and hop 0 travels the chain to say so diff --git a/quest/m1/libmoq-track-demand.md b/quest/m1/libmoq-track-demand.md new file mode 100644 index 00000000000..17f51c39abc --- /dev/null +++ b/quest/m1/libmoq-track-demand.md @@ -0,0 +1,99 @@ +# [L] libmoq: track demand and dynamic track requests + +## Goal + +A C publisher learns when a published track gains its first subscriber and +when it loses its last, and can serve track requests it did not declare up +front, so an encoder on a battery-powered device runs only while someone is +watching. The C ABI mirrors what moq-ffi already has: `used`/`unused` on +`MoqTrackProducer` and single-track `MoqMediaProducer`, and +`MoqBroadcastDynamic::requested_track` with `MoqTrackRequest::accept`/`abort`, +`publish_media_on_track` for accepting a request as media, and the group +request path (`MoqTrackDynamic::requested_group`, `MoqGroupRequest`) that +keeps a FETCH-driven request serviceable across acceptance. + +Non-goals: no wire or public Rust API change; the OBS plugin does not adopt +the signal (OBS owns its encoders and cannot pause them from an output); +a multi-track container handle has no single demand and errors, as in moq-ffi; +broadcast-level request serving stays with the announce handle quests. + +## Plan + +Branch from dev, where libmoq already serves broadcast requests through +`moq_origin_dynamic` and `moq_broadcast_request_*`; follow that callback +convention exactly (a positive handle per event, then exactly one terminal +`<= 0` call, after which `user_data` is never touched). + +Demand, one level-triggered watcher per handle: + +- `moq_publish_track_demand(track, on_demand, user_data)`, + `moq_publish_media_demand(media, on_demand, user_data)`, and the same on + the built-in encoder handles, `moq_publish_video_raw_demand` and + `moq_publish_audio_raw_demand` (moq-ffi's `MoqVideoProducer` and + `MoqAudioProducer` carry `used`/`unused` too), return a watcher handle; + `moq_publish_demand_close(watcher)` stops it. +- `on_demand(user_data, int32_t status)` fires immediately with the current + state, again on every observed change, then once with a terminal `<= 0`. Positive + values come from a `moq_demand` enum (`MOQ_DEMAND_USED`, + `MOQ_DEMAND_UNUSED`). Seeding with the current state is what closes the + race the issue calls out: a track that went unused before registration + still reports it. +- Neither `Producer` nor `Demand` exposes the current state, only the + level-triggered waits `used()` and `unused()`, and exactly one of them is + ready at any instant. The watcher task races the two to learn the initial + state, reports it, then loops waiting on the opposite wait. A flip between + reporting and arming resolves the next wait immediately, so no edge is + lost; a double flip collapses into no report, which is correct for a level + signal. Do not add an `is_used` getter to moq-net for this. +- The media watcher refuses a container handle with the same error moq-ffi + uses. + +Requests, mirroring the broadcast path one level down: + +- `moq_publish_dynamic(broadcast, on_request, user_data)` registers the + handler and returns a handle; `moq_publish_dynamic_close` drops it. Without + a live handler an unknown track name is refused, as today. +- `moq_track_request_name(request, dst)`, `moq_track_request_accept(request, + info)` returning a `moq_publish_track` handle (the demand watcher attaches + to it like any other), `moq_track_request_abort(request, error_code)`, and + `moq_track_request_free(request)`. `info` is the existing `moq_track_info`, + NULL for the microsecond default. +- `moq_track_request_video(request, init)` and + `moq_track_request_audio(request, init)` mirror `publish_media_on_track`, + split by kind the way `moq_publish_video`/`_audio` are: the importer + accepts the request, sets the timescale, and returns the same media handle + those return, so the demand watcher and frame writes work unchanged. + Single-track formats only, as in moq-ffi. + +Group requests, so a track requested by FETCH is served rather than resolving +`NotFound` once accepted: + +- `moq_track_request_dynamic(request, on_group, user_data)` mirrors + `MoqTrackRequest::dynamic`: obtain it before accepting when the track was + requested by a fetch, so the pending group request survives the transition. + `moq_publish_track_dynamic(track, on_group, user_data)` is the same handler + on an already-published track (`MoqTrackProducer::dynamic`). Both return a + handle closed by `moq_publish_dynamic_close`, and `on_group` follows the + request callback convention. +- `moq_group_request_sequence`, `moq_group_request_priority`, + `moq_group_request_accept(request)` returning a `moq_publish_group` handle, + `moq_group_request_abort(request, error_code)`, and + `moq_group_request_free`. Cached groups never reach the handler. + +Landing: regenerate `moq.h` (build.rs does not regenerate it on src-only +changes), document every new symbol in `doc/lib/c`, and add tests in +`rs/libmoq/src/test.rs`: a consumer subscribing then closing drives +used -> unused; a watcher registered after the last consumer left is told +unused first; one dynamic request is accepted and the returned track +carries frames, a second is aborted and its subscriber sees the code. +Remove the dynamic-track bullet from #2152 when this lands. + +## Closes + +- [#3678](https://github.com/moq-dev/moq/issues/3678) - close this issue when the quest finishes + +## Related + +- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the wider C ABI catch-up this splits out of +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - broadcast-level request serving on the C ABI +- [#3000](/quest/m1/3000-track-teardown-on-poll-unused-is-not-atomic-against-a.md) - an unused edge is not terminal; the watcher must keep reporting after it From 0407b5bfd824a2a67435c3c16c28e2b99a890b28 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 18:33:46 -0700 Subject: [PATCH 03/11] humans --- CLAUDE.md | 2 ++ CONTRIBUTING.md | 5 +++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b52c2513e83..56f2cf66956 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -67,6 +67,8 @@ The API is the most important thing to get right. A bad shape costs a breaking c - No em dashes. - Match the existing conventions, patterns, and naming when possible. - Fix any outdated docs and comments inline; don't add a separate PR for it. +- Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. +- Any AI comments may be challenged, and not confused with human maintainers. # Guidelines diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a481094ba1..a46fc6e0111 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,9 +25,10 @@ Fix any merge conflicts and failing CI checks. # AI AI-assisted issues, pull requests, reviews, and comments are welcome. -GitHub issues are the public front door for brainstorming. Prefer a quest for work needing durable scope or coordination. +Especially bug reports; dive deep into the root issue before proposing a solution. -Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. +GitHub issues are the public front door for brainstorming. +Prefer a quest for work needing durable scope or coordination. # Reviews From 4cc3348d38af3423cb3f7097f35717ee2c6b02a3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 19:42:05 -0700 Subject: [PATCH 04/11] fix(moq-net): a remote source never displaces a local publisher (#3694) Co-authored-by: Claude Opus 5 --- rs/moq-net/src/model/origin.rs | 141 ++++++++++++++++++++++++++++++--- 1 file changed, 130 insertions(+), 11 deletions(-) diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index f6bf485ccfd..f4bb34778c2 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1531,6 +1531,18 @@ impl FrontState { route.hops.iter().any(|hop| self.excluded.contains_key(hop)) } + /// Whether the front is a broadcast published in this process and still + /// announced. Only a remote source calls this (a local one shares the empty + /// chain and splices instead), and it can never win: the process publishing a + /// path is that path's origin, so a remote copy is our own content reflected by + /// a peer that carries no hop ids, which `excluded` cannot recognize when the + /// peer is anonymous, or an unrelated publisher that must not reach our + /// subscribers in place of what we are producing. An unannounced local source + /// (cached content reachable by exact path) is not a claim on the path. + fn holds_local_publisher(&self) -> bool { + self.publisher.is_none() && self.routes.iter().any(|r| r.route.announce) + } + /// Narrow `candidates` to the routes clean for every peer currently reading the /// shared front, unless that would leave nothing. /// @@ -1781,16 +1793,28 @@ async fn run_source( broadcast = %full, "path already live with a different publisher; parking this source until it ends", ); - // Wait for the incumbent front to close, or for our own route to - // change: a new route observation earns another takeover attempt, and - // our source closing means giving up. + // Snapshot the local-publisher hold: a remote parked by it must retry + // when the hold releases (the local route unannounces or its last + // source detaches into linger), not just when the front closes, or + // the path stays dark despite an announced remote waiting. + let held = incumbent.read().holds_local_publisher(); + // Wait for the incumbent front to close or release its hold, or for + // our own route to change: a new route observation earns another + // takeover attempt, and our source closing means giving up. let update = kio::wait(|waiter| { if let Poll::Ready(update) = source.poll_route_changed(waiter) { return Poll::Ready(Some(update)); } - // Ready on either the closed flag or the channel itself dying; - // both mean the incumbent is gone. - match incumbent.poll(waiter, |s| if s.closed { Poll::Ready(()) } else { Poll::Pending }) { + // Ready on the closed flag, the channel itself dying (both mean + // the incumbent is gone), or the local-publisher hold changing + // shape so a parked remote gets another attempt. + match incumbent.poll(waiter, |s| { + if s.closed || s.holds_local_publisher() != held { + Poll::Ready(()) + } else { + Poll::Pending + } + }) { Poll::Ready(_) => Poll::Ready(None), Poll::Pending => Poll::Pending, } @@ -1899,9 +1923,10 @@ enum Attach { /// The path's live front belongs to a different original publisher and this /// source may not take it: either the source is offline (so it would rank below /// every route the front holds), it already spent its takeover attempt on this - /// route and lost, or its chain leads back through a peer the front is already - /// exposed to, making it a reflection rather than rival content. The caller - /// parks on the returned table until the front closes. + /// route and lost, its chain leads back through a peer the front is already + /// exposed to, making it a reflection rather than rival content, or the front + /// is held by a local publisher. The caller parks on the returned table until + /// the front closes or the local-publisher hold releases. Parked(kio::Producer), } @@ -1950,7 +1975,10 @@ fn same_publisher(a: Option, b: Option) -> bool { /// chain that does not lead back through a peer this front is already exposed to /// (see [`FrontState::taints_a_reader`]): such a source is our own broadcast /// reflected by a peer that cannot detect the loop itself, and letting it evict the -/// front is how a publish direction ends up withdrawing its own announce. +/// front is how a publish direction ends up withdrawing its own announce. A front +/// held by a local publisher is never taken over at all (see +/// [`FrontState::holds_local_publisher`]): the exposure check needs the reflecting +/// peer to have an identity, and an anonymous peer's echo has none. /// /// `may_take_over` is the caller's third gate: [`run_source`] clears it once this /// source has been displaced, so a route that already lost the path stands by @@ -1984,7 +2012,7 @@ fn attach_source( }); s.reselect(carrying); joined = Some(id); - } else if !may_take_over || !route.announce || s.taints_a_reader(&route) { + } else if !may_take_over || !route.announce || s.taints_a_reader(&route) || s.holds_local_publisher() { return Attach::Parked(existing.state.clone()); } else { // New content at a live path: the newest publisher wins it. Closing @@ -5478,6 +5506,97 @@ mod tests { source_a2.finish(); } + /// A locally published broadcast holds its path against any remote source. A + /// client that shares one origin between its publish and subscribe halves sees + /// its own announce echoed back by a relay that does no loop detection, and an + /// anonymous relay's echo carries an UNKNOWN first hop, so the exposure-based + /// reflection check (`excluded`) cannot recognize it. Without this rule the echo + /// evicts the local publisher and the client ends up subscribing to the relay + /// for its own broadcast. + #[tokio::test] + async fn test_remote_source_cannot_displace_a_local_publisher() { + tokio::time::pause(); + + let origin = Origin::random().produce(); + let consumer = origin.consume(); + let mut announced = consumer.announced(); + + // Published in this process: no hop chain. + let mut local = origin.create_broadcast("test", announce()).unwrap(); + settle().await; + let face = announced.assert_next_some("test"); + + // The echo, as an anonymous relay reflects it. + let echo = OriginList::try_from(vec![Origin::UNKNOWN]).unwrap(); + let mut remote = origin.create_broadcast("test", announce().with_hops(echo)).unwrap(); + settle().await; + settle().await; + announced.assert_next_wait(); + assert!( + consumer.get_broadcast("test").unwrap().is_clone(&face), + "the local publisher must keep the path" + ); + assert!(consumer.get_broadcast("test").unwrap().route().hops.is_empty()); + + // The parked remote leaving changes nothing. + remote.finish(); + settle().await; + settle().await; + announced.assert_next_wait(); + + // Once the local publisher ends, the path is free for a remote source again. + local.finish(); + settle().await; + settle().await; + announced.assert_next_none("test"); + let echo = OriginList::try_from(vec![Origin::UNKNOWN]).unwrap(); + let _remote = origin + .create_broadcast("test", announce().with_hops(echo.clone())) + .unwrap(); + settle().await; + settle().await; + announced.assert_next_some("test"); + assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, echo); + } + + /// A parked remote retries when the local-publisher hold releases without the + /// front closing. If the local route unannounces while its source stays open, + /// the hold is gone and the waiting announced remote must take the path, + /// otherwise the path stays dark despite an available source. + #[tokio::test] + async fn test_parked_remote_retries_when_local_unannounces() { + tokio::time::pause(); + + let origin = Origin::random().produce(); + let consumer = origin.consume(); + let mut announced = consumer.announced(); + + let mut local = origin.create_broadcast("test", announce()).unwrap(); + settle().await; + announced.assert_next_some("test"); + + // Parked by the local hold: the echo of our own announce. + let echo = OriginList::try_from(vec![Origin::UNKNOWN]).unwrap(); + let _remote = origin + .create_broadcast("test", announce().with_hops(echo.clone())) + .unwrap(); + settle().await; + settle().await; + announced.assert_next_wait(); + + // The local source stays open but stops announcing: cached content + // reachable by exact path is not a claim on the path. + local.set_route(broadcast::Route::new()).unwrap(); + settle().await; + settle().await; + + // The parked remote takes over: unannounce of the local front, then an + // announce for the remote one. + announced.assert_next_none("test"); + announced.assert_next_some("test"); + assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, echo); + } + /// A repricing is not new content: a standby source must not use a cost-only /// route update to evict the live front it already lost to. #[tokio::test] From b65e28a2dbed313336b5cf7f842ab203c21766e7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 21:10:51 -0700 Subject: [PATCH 05/11] docs(cluster): revise the cluster draft to -01 and plan its implementation (#3702) Co-authored-by: Claude Fable 5.1 --- drafts/draft-lcurley-moq-cluster.md | 63 +++++++++++++++++++++-------- quest/m1/README.md | 1 + quest/m1/cluster-01/README.md | 38 +++++++++++++++++ quest/m1/cluster-01/cost-update.md | 56 +++++++++++++++++++++++++ quest/m1/cluster-01/hop-id.md | 29 +++++++++++++ 5 files changed, 170 insertions(+), 17 deletions(-) create mode 100644 quest/m1/cluster-01/README.md create mode 100644 quest/m1/cluster-01/cost-update.md create mode 100644 quest/m1/cluster-01/hop-id.md diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index a62114763d7..fd18fceeb6b 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -45,6 +45,7 @@ Relays that gossip namespaces with PUBLISH_NAMESPACE quickly break down: adverti This extension adds the HOP_PATH parameter to PUBLISH_NAMESPACE and NAMESPACE. It lists every node an advertisement has passed through, starting with the original publisher, which is enough to break loops and to compare paths. Each connection also declares its own Hop ID at SETUP, so loops are avoided even across multiple connections between the same pair of relays. +A namespace is routed to one publisher: the mesh carries the best path to it, not one path per publisher ({{single}}). Not every route is equal: one crossing a metered backbone costs more than one inside a datacenter. The RELAY_COST Setup Option prices what subscribing from an endpoint costs, defaulting to 1 so an unpriced mesh simply ranks by hop count. @@ -53,19 +54,18 @@ The ROUTE_COST parameter carries the accumulated price per namespace, and a rela # Setup Negotiation -## Relay Hops +## Hop ID {#hop-id} The extension is negotiated during the SETUP exchange ({{moqt}} Section 10.3). An endpoint indicates support with the following Setup Option, whose value is its own Hop ID: ~~~ -RELAY_HOPS Setup Option { - Option Key (vi64) = 0x40B55 - Option Value Length (vi64) +HOP_ID Setup Option { + Option Key (vi64) = 0x40B54 Hop ID (vi64) } ~~~ -Negotiation is per session; a relay MUST NOT assume that because one of its sessions negotiated Relay Hops, another did. +Negotiation is per session; a relay MUST NOT assume that because one of its sessions negotiated the extension, another did. It also enables the extended NAMESPACE message ({{namespace}}), which is what lets a NAMESPACE carry these parameters at all. On a session that negotiated the extension, an endpoint MUST include HOP_PATH on every PUBLISH_NAMESPACE and NAMESPACE it sends, and a receiver MUST close the session with a PROTOCOL_VIOLATION if one arrives without it. @@ -80,13 +80,17 @@ RELAY_COST Setup Option { } ~~~ -The option prices one direction, the sender's own egress, so each endpoint declares its own and the two need not match. +The option prices one direction, the sender's own egress, so each endpoint declares its own and the two need not match, as OSPF prices each router's own output interfaces ({{?RFC2328, Section 9}}). A receiver adds the value the sender declared to the ROUTE_COST of every advertisement that sender forwards. An absent option means 1, under which the accumulated cost equals the hop count. 0 is meaningful and distinct from absent: it makes that direction free, which is how a deployment describes two relays in the same datacenter. A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value instead, so a peer cannot reprice its neighbours by declaring itself cheap. +The cost is one dimensionless integer, as in every widely deployed routing metric: RIP's hop count ({{?RFC2453, Section 3.5}}), OSPF's interface cost, and IS-IS's default metric, whose companion delay, expense, and error metrics went unimplemented ({{?RFC5305, Section 3}}) just as OSPF's per-type-of-service metrics were deleted for lack of use ({{?RFC2178, Appendix G.10}}). +A deployment that weighs several factors, such as latency, hop count, and price, folds them into the one value it declares. +Like BGP's MULTI_EXIT_DISC ({{?RFC4271, Section 5.1.4}}), the value is comparable only within the deployment that chose its units, which is why a trust boundary clamps or replaces it ({{security}}). + # Hop IDs A **Hop ID** is a variable-length integer identifying one endpoint within an advertisement's path. @@ -132,10 +136,10 @@ An assigned ID is indistinguishable on the wire from a declared one, so it ident This extension carries HOP_PATH and ROUTE_COST as Key-Value-Pair parameters ({{moqt}} Section 2.5). PUBLISH_NAMESPACE ({{moqt}} Section 10.15) already has a Parameters field. -NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE messages, so this extension defines an extended form used only on a session that negotiated Relay Hops: +NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE messages, so this extension defines an extended form used only on a session that negotiated the extension: ~~~ -NAMESPACE Message (Relay Hops) { +NAMESPACE Message (Cluster) { Type (vi64) = 0x8, Length (16), Track Namespace Suffix (..), @@ -202,7 +206,11 @@ Equal Hop IDs (including two relays that both declared 0) cannot be ordered, and Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted immediately. ## Updating an Advertisement {#updating} -An endpoint updates an advertisement by re-sending it with new parameters **on the stream that already carries it**: the original PUBLISH_NAMESPACE request stream, or the SUBSCRIBE_NAMESPACE response stream the NAMESPACE arrived on. +An endpoint updates a PUBLISH_NAMESPACE with REQUEST_UPDATE ({{moqt}} Section 9.5) on its request stream, carrying the HOP_PATH or ROUTE_COST that changed. +A parameter omitted from REQUEST_UPDATE keeps its value, so a relay that starts carrying a namespace sends ROUTE_COST as an explicit 0 rather than omitting it. +The receiver answers REQUEST_OK, or REQUEST_ERROR and closes the stream, which withdraws the advertisement. + +NAMESPACE is a response and has no REQUEST_UPDATE, so an endpoint updates one by re-sending it with new parameters on the SUBSCRIBE_NAMESPACE response stream that carries it. A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. In {{moqt}} an advertisement lives for the lifetime of its stream, so an update on a *new* stream would leave two streams claiming one namespace and let the superseded one retract its replacement. @@ -234,7 +242,20 @@ If only excluded sources remain the subscription is unroutable, since serving it Applying one rule to both advertisement and dispatch keeps advertised paths truthful and prevents subscription cycles of any length. -# Security Considerations +# One Publisher per Namespace {#single} +{{moqt}} allows several publishers to advertise one namespace and expects a relay to forward a matching SUBSCRIBE to each. +This extension does not: a session advertises a namespace at most once, a relay advertises only the best path it knows ({{selection}}), and a subscription is served from one source. + +A relay holding paths to two publishers of one namespace has no good move. +SUBSCRIBE names a track, not a publisher, so a relay could only forward it along every path and deliver both publishers' Objects to every subscriber below it, or pick one path silently. +Two publishers also share no history, so nothing fetched from one is valid against the other. +Advertising a namespace once per publisher would only push the same choice one hop downstream. + +A second publisher of a namespace therefore replaces the first rather than joining it ({{selection}}). +Redundant ingest of one content is a deployment concern outside this document. + + +# Security Considerations {#security} A Hop ID reveals nothing beyond what its operator encodes in it, and a deployment that considers its identifiers sensitive can use random values or declare 0 ({{zero}}). Declaring 0 hides an identity from the mesh but not from the peer itself, which MAY assign one and forward it onward ({{assigned}}); an endpoint that needs to stay unlinkable past its first hop cannot get that from this extension. A HOP_PATH does expose how many hops an advertisement crossed, which hints at the size of a deployment; a relay MAY coalesce its internal hops into one entry, or strip HOP_PATH, before forwarding across a trust boundary. @@ -257,24 +278,32 @@ This document requests two registrations in the "MOQT Setup Options" registry ({ | Value | Name | Reference | |:--------|:-----------|:--------------| -| 0x40B55 | RELAY_HOPS | This Document | +| 0x40B54 | HOP_ID | This Document | | 0x40B56 | RELAY_COST | This Document | ## MOQT Message Parameters This document requests two registrations in the "MOQT Message Parameters" registry ({{moqt}} Section 15.7). -Both are carried in PUBLISH_NAMESPACE and in the extended NAMESPACE message ({{namespace}}). +Both are carried in PUBLISH_NAMESPACE, in REQUEST_UPDATE of a PUBLISH_NAMESPACE ({{updating}}), and in the extended NAMESPACE message ({{namespace}}). -| Value | Name | Carried In | Reference | -|:--------|:------------|:-----------------------------|:--------------| -| 0x40B57 | HOP_PATH | PUBLISH_NAMESPACE, NAMESPACE | This Document | -| 0x40B58 | ROUTE_COST | PUBLISH_NAMESPACE, NAMESPACE | This Document | +| Value | Name | Carried In | Reference | +|:--------|:------------|:---------------------------------------------|:--------------| +| 0x40B57 | HOP_PATH | PUBLISH_NAMESPACE, REQUEST_UPDATE, NAMESPACE | This Document | +| 0x40B58 | ROUTE_COST | PUBLISH_NAMESPACE, REQUEST_UPDATE, NAMESPACE | This Document | -The Key-Value-Pair parity is load-bearing: HOP_PATH and RELAY_HOPS are odd, so their values are length-prefixed byte strings, while ROUTE_COST and RELAY_COST are even, so their values are bare varints. +The Key-Value-Pair parity is load-bearing: HOP_PATH is odd, so its value is a length-prefixed byte string, while HOP_ID, RELAY_COST, and ROUTE_COST are even, so their values are bare varints. --- back +# Appendix A: Changelog + +## moq-cluster-01 +- Renamed the RELAY_HOPS Setup Option to HOP_ID and moved it to the even key 0x40B54, so its value is a bare varint rather than a length-prefixed one. +- A PUBLISH_NAMESPACE is updated with REQUEST_UPDATE on its request stream instead of a repeated PUBLISH_NAMESPACE; HOP_PATH and ROUTE_COST are registered for REQUEST_UPDATE. A NAMESPACE is still re-sent on its stream. +- Stated that a namespace is routed to one publisher: a session advertises it at most once and a second publisher replaces the first. +- Named the routing protocols whose single per-direction metric RELAY_COST follows. + # Acknowledgments {:numbered="false"} diff --git a/quest/m1/README.md b/quest/m1/README.md index c59886cd489..2142c8f1ede 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -77,6 +77,7 @@ with the current dev tree before starting. - [Plan: A/V clock](/quest/m1/plan-av-clock.md) - settle how the audio playhead drives Sync.reference while audio plays, then build it - [Config provenance](/quest/m1/config-provenance.md) - the merge records which source set a value, so TOML survives CLI defaults and empty lists, and env outranks the file - [Cluster construction](/quest/m1/cluster-construction.md) - construct one stable origin after its cache settings are known, deleting the rebuilding builder +- [Cluster -01](/quest/m1/cluster-01/README.md) - rs/moq-net and js/net speak the revised cluster extension (HOP_ID, REQUEST_UPDATE repricing) and -01 is published - [Abort on drop](/quest/m1/abort-on-drop.md) - one abort-on-drop task guard per crate, replacing five copies of the same Drop - [#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) - QUIC flow-control windows on quic::Client and quic::Server, applied or refused per backend diff --git a/quest/m1/cluster-01/README.md b/quest/m1/cluster-01/README.md new file mode 100644 index 00000000000..ae8f78d2926 --- /dev/null +++ b/quest/m1/cluster-01/README.md @@ -0,0 +1,38 @@ +# Cluster extension -01 + +## Goal + +`rs/moq-net` and `js/net` speak draft-lcurley-moq-cluster-01 as +`drafts/draft-lcurley-moq-cluster.md` now reads: the HOP_ID Setup Option +replaces RELAY_HOPS on an even key, and a PUBLISH_NAMESPACE reprices with +REQUEST_UPDATE instead of a repeated PUBLISH_NAMESPACE. Once both land the +revision is published to the datatracker, answering afrind's review of -00 +([#3693](https://github.com/moq-dev/moq/issues/3693), +[#3695](https://github.com/moq-dev/moq/issues/3695), +[#3697](https://github.com/moq-dev/moq/issues/3697), +[#3698](https://github.com/moq-dev/moq/issues/3698)). + +## Plan + +The draft moved first, on main. The text-only halves of that review, one +publisher per namespace and the single per-direction cost metric, needed no +code and are already answered there. What remains is the two wire changes. + +Nothing deployed speaks -00: cluster sessions run moq-lite-06 (see +[PoP skipping](/quest/m2/pop-skipping/README.md)), and a -00 peer meeting a +-01 peer sees an unknown Setup Option on each side, so neither negotiates and +the session runs as plain moq-transport. + +The draft on dev carries pattern-extension and selection changes main does +not. The merge keeps dev's text and this revision's wire changes together; +neither quest touches the draft again except the changelog. + +## Quests + +- [HOP_ID option](/quest/m1/cluster-01/hop-id.md) - both implementations negotiate with HOP_ID at 0x40B54, a bare varint +- [Cost update](/quest/m1/cluster-01/cost-update.md) - a PUBLISH_NAMESPACE reprices with REQUEST_UPDATE, and -01 is published + +## Related + +- [Anonymous rank](/quest/m1/anonymous-route-rank.md) - edits the same draft's identity sections +- [Warm advertise](/quest/m2/pop-skipping/warm-advertise.md) - the repricing this update path carries diff --git a/quest/m1/cluster-01/cost-update.md b/quest/m1/cluster-01/cost-update.md new file mode 100644 index 00000000000..abf447add5d --- /dev/null +++ b/quest/m1/cluster-01/cost-update.md @@ -0,0 +1,56 @@ +# [M] Cost update + +## Goal + +A relay that starts or stops carrying a namespace it advertised with +PUBLISH_NAMESPACE reprices it with REQUEST_UPDATE on that request stream, +carrying ROUTE_COST and, when the route changed, HOP_PATH. The receiver +answers REQUEST_OK, or REQUEST_ERROR and closes the stream, which withdraws +the advertisement. A repeated PUBLISH_NAMESPACE on a live stream is the base +draft's duplicate again. A NAMESPACE on a SUBSCRIBE_NAMESPACE stream is still +re-sent to update it. With both wire changes in, +draft-lcurley-moq-cluster-01 is on the datatracker. + +## Plan + +Today `sync_namespace` in `rs/moq-net/src/ietf/publisher.rs` re-sends +PUBLISH_NAMESPACE on the stream that carries it, and +`run_publish_namespace_updates` in `rs/moq-net/src/ietf/subscriber.rs` +decodes the repeat as an update. + +- Sender: a repricing writes REQUEST_UPDATE (type 0x2, Request ID plus + parameters) with the changed parameters. REQUEST_UPDATE keeps an omitted + parameter, so a change to 0 sends ROUTE_COST as an explicit 0, unlike the + initial advertisement where absent means 0. Reuse the REQUEST_UPDATE codec + the subscribe path has in `rs/moq-net/src/ietf/subscribe.rs`, extended to + carry HOP_PATH and ROUTE_COST. MAX_REQUEST_UPDATES bounds the outstanding + updates per stream, so wait for REQUEST_OK before the next one or coalesce + to the latest value. +- Receiver: `run_publish_namespace_updates` accepts REQUEST_UPDATE, merges + the parameters onto the held advertisement, and replies REQUEST_OK. A + repeated PUBLISH_NAMESPACE on the stream is a duplicate. An update it + cannot apply gets REQUEST_ERROR and a closed stream, per moq-transport + Section 9.5.1, which withdraws the advertisement. +- Draft-17 through draft-21 all allow REQUEST_UPDATE on PUBLISH_NAMESPACE, + which is every version the extension negotiates on, so no per-version + branch. +- js/net is a leaf that seeds cost 0 and never reprices, so it needs no + sender. Where it reads a repeated PUBLISH_NAMESPACE as an update today, it + reads REQUEST_UPDATE instead and treats the repeat as the duplicate. +- Branch from dev: the announce loops in `publisher.rs` and `subscriber.rs` + were rewritten there and m1 is the dev line. Main keeps the repeat until + the merge. +- Tests: a repricing round trip over REQUEST_UPDATE, including an explicit + 0; a repeated PUBLISH_NAMESPACE on its own stream is refused; a failed + update withdraws the advertisement; a NAMESPACE re-send still updates. +- Publish: `just drafts publish draft-lcurley-moq-cluster 01 `, then + the maintainer clicks the confirmation link. Reply on the four issues with + the -01 link. + +## Required + +- [HOP_ID option](/quest/m1/cluster-01/hop-id.md) - -01 publishes with both wire changes in + +## Closes + +- [#3698](https://github.com/moq-dev/moq/issues/3698) - close this issue when the quest finishes diff --git a/quest/m1/cluster-01/hop-id.md b/quest/m1/cluster-01/hop-id.md new file mode 100644 index 00000000000..c090597c53a --- /dev/null +++ b/quest/m1/cluster-01/hop-id.md @@ -0,0 +1,29 @@ +# [S] HOP_ID option + +## Goal + +A session negotiates the cluster extension with the HOP_ID Setup Option: key +0x40B54, even, so its value is the sender's Hop ID as a bare varint. Neither +implementation recognizes RELAY_HOPS (0x40B55) any more. rs/moq-net and +js/net agree byte for byte, and a peer that sends only the old option is not +negotiated with rather than misread. + +## Plan + +- `rs/moq-net/src/ietf/cluster.rs`: `RELAY_HOPS` becomes `HOP_ID = 0x40B54`. + `peer_from_setup` reads it with `get_varint` and `peer_into_setup` writes it + with `set_varint`, deleting the byte-string round trip and its + `TrailingBytes` check. `rs/moq-net/src/ietf/parameters.rs` moves the key + from `ParameterBytes::RelayHops` to `ParameterVarInt::HopId`. The parity + test asserts even. +- `js/net/src/ietf/parameters.ts` and `cluster.ts`: `SetupOption.RelayHops` + becomes `HopId = 0x40b54n`, decoded as a varint; the byte fixtures in + `cluster.test.ts` follow. +- Module docs in both name HOP_ID as the option. No comment records the old + name. +- Branch from main: the constants and setup codecs are identical on dev, so + the merge carries it. A wire change, so run `just test smoke-full`. + +## Closes + +- [#3693](https://github.com/moq-dev/moq/issues/3693) - close this issue when the quest finishes From 52ffad98cd6cb506a0f43e1a40cab0f30ef04b51 Mon Sep 17 00:00:00 2001 From: Rishi Desai Date: Wed, 16 Sep 2026 23:33:40 -0500 Subject: [PATCH 06/11] fix: bump h264-parser to 0.4.2 (#3707) --- Cargo.lock | 8 ++++---- rs/moq-mux/Cargo.toml | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 5e8f68f0201..d6fae708cda 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1908,7 +1908,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c54e03a951783e8b327515db3f2a2fd0e3bed362a96b066f341ce66ed49b4ead" dependencies = [ "data-encoding", - "syn 1.0.109", + "syn 3.0.5", ] [[package]] @@ -3192,9 +3192,9 @@ dependencies = [ [[package]] name = "h264-parser" -version = "0.4.1" +version = "0.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "253b313319f7109de64e480ffb606f89475cd758bae82e096e00c5d95341d30e" +checksum = "c16ee729d5d4a75be0f5181682a17cf0fce29497d0fa5273d57fe477409f02e6" [[package]] name = "h264-reader" @@ -9226,7 +9226,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" dependencies = [ "fastrand", - "getrandom 0.3.4", + "getrandom 0.4.3", "once_cell", "rustix 1.1.4", "windows-sys 0.61.2", diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 9f1b169056e..0bd57edfaab 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -16,7 +16,7 @@ categories = ["multimedia", "network-programming", "web-programming"] anyhow = { workspace = true } base64 = { workspace = true } bytes = { workspace = true } -h264-parser = { version = "0.4.0" } +h264-parser = { version = "0.4.2" } hang = { workspace = true } kio = { workspace = true } memchr = "2" From 3864364aef93f24fe8ceaa02a75fafaf9fb0ce6d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 10:24:43 +0200 Subject: [PATCH 07/11] Contributing --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a46fc6e0111..c2946bce3cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,13 @@ PRs are squash-merged, so the PR title becomes the commit subject and the PR des # PRs Keep the body short and structured, not narrated. +Have at least these sections: - **Problem**: a summary of the problem and why this PR is needed. - **Approach**: a summary of the approach taken to solve the problem. - **Impact**: a bullet point for every public API/wire change made. - **Alternatives**: any alternative approaches considered. +- **Follow-ups**: any issues encountered or quests created. When pushing additional commits to an existing PR, update the title and description if needed. When taking over someone else's PR, push commits on top of theirs so they keep credit. From 270b95d45f1e2315d758cc132a3667e8d441cfa6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 10:28:18 +0200 Subject: [PATCH 08/11] docs: serve llms.txt and markdown twins of every page (#3708) Co-authored-by: Claude Opus 5 --- README.md | 2 +- bun.lock | 71 ++++++++++++++++++++++++++++++-- doc/.vitepress/config.ts | 13 ++++++ doc/.vitepress/drafts.ts | 7 ++++ doc/index.md | 2 +- doc/package.json | 1 + doc/public/setup/agent/prompt.md | 2 +- doc/setup/agent.md | 8 +++- skills/moq/SKILL.md | 68 +++++++----------------------- 9 files changed, 113 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 2fda451b49b..1aac42ab3a7 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The core networking is delegated to a QUIC library but the rest is in applicatio Full documentation lives at **[doc.moq.dev](https://doc.moq.dev)**. - **[Run the demo](https://doc.moq.dev/setup/)** - try MoQ locally with a relay, demo media, and the web UI. -- **[Agent setup](https://doc.moq.dev/setup/agent)** - teach your AI coding agent (Claude Code, Cursor, etc.) how to build with MoQ. +- **[Agent setup](https://doc.moq.dev/setup/agent)** - teach your AI coding agent (Claude Code, Cursor, etc.) how to build with MoQ. The docs are also served as markdown via [llms.txt](https://doc.moq.dev/llms.txt). - **[Linux packages](https://doc.moq.dev/setup/install)** - install the relay and GStreamer plugin from `apt.moq.dev` / `rpm.moq.dev`. - **[Production setup](https://doc.moq.dev/setup/prod)** - deploy a relay with a real domain and TLS. diff --git a/bun.lock b/bun.lock index 9dd681544e5..cd953888275 100644 --- a/bun.lock +++ b/bun.lock @@ -67,6 +67,7 @@ "@types/node": "^26.4.1", "typescript": "7.0.2", "vitepress": "^1.6.4", + "vitepress-plugin-llms": "^1.14.0", "wrangler": "^4.129.0", "yaml": "^2.9.0", }, @@ -358,6 +359,8 @@ "@fails-components/webtransport-transport-http3-quiche", ], "packages": { + "@11ty/gray-matter": ["@11ty/gray-matter@2.1.0", "", { "dependencies": { "js-yaml": "^4.2.0", "section-matter": "^1.0.0" } }, "sha512-fNdBOb3MgDz/1UCIoeY4wDuGbp+/3s5y6UrsyfMabECbh/CVycj7Er33JXqSxRwxrRKXcGE1Jipuq/1mODInsQ=="], + "@algolia/abtesting": ["@algolia/abtesting@1.21.1", "", { "dependencies": { "@algolia/client-common": "5.55.1", "@algolia/requester-browser-xhr": "5.55.1", "@algolia/requester-fetch": "5.55.1", "@algolia/requester-node-http": "5.55.1" } }, "sha512-Wia5/mNTfiU0PIUN25UMfAGGdASkkwuCS9nBAdmhqrNPY/ff7U/6MgBVdwFDPsa3sA1msutPtO50gvOzx6MOXA=="], "@algolia/autocomplete-core": ["@algolia/autocomplete-core@1.17.7", "", { "dependencies": { "@algolia/autocomplete-plugin-algolia-insights": "1.17.7", "@algolia/autocomplete-shared": "1.17.7" } }, "sha512-BjiPOW6ks90UKl7TwMv7oNQMnzU+t/wk9mgIDi6b1tXpUek7MW0lbNOUHpvam9pe3lVCf4xPFT+lK7s+e+fs7Q=="], @@ -974,6 +977,8 @@ "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="], + "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="], + "async": ["async@3.2.6", "", {}, "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA=="], "async-mutex": ["async-mutex@0.5.0", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-1A94B18jkJ3DYq284ohPxoXbfTA5HsQ7/Mf4DEhcyLx3Bz27Rh59iScbB6EPiP+B+joue6YCxcMXSbFC1tZKwA=="], @@ -1004,7 +1009,7 @@ "bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="], - "brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="], + "brace-expansion": ["brace-expansion@5.0.12", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ=="], "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="], @@ -1132,7 +1137,7 @@ "enhanced-resolve": ["enhanced-resolve@5.24.2", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.3" } }, "sha512-rpsZEGT1jFuve6QlpyRp9ckQ+kN61hvF9BzCPyMdaKTm8UJce96KBn3sorXOFXlzjPrs3Vc4T1NsSroZ3PxlFw=="], - "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="], + "entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="], "err-code": ["err-code@2.0.3", "", {}, "sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA=="], @@ -1152,6 +1157,8 @@ "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="], + "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="], + "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="], "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="], @@ -1236,6 +1243,8 @@ "is-empty": ["is-empty@1.2.0", "", {}, "sha512-F2FnH/otLNJv0J6wc73A5Xo7oHLNnqplYqZhUu01tD54DIPvxIRSTSLkrUB/M0nHO4vo1O9PDfN4KoTxCzLh/w=="], + "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="], + "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="], "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="], @@ -1268,6 +1277,8 @@ "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="], + "js-yaml": ["js-yaml@4.3.2", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA=="], + "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="], "json-parse-even-better-errors": ["json-parse-even-better-errors@3.0.2", "", {}, "sha512-fi0NG4bPjCHunUJffmLd0gxssIgkNmArMvis4iNah6Owg1MCJjWhEcDLmsK6iGkJq3tHwbDkTlce70/tmXN4cQ=="], @@ -1276,6 +1287,8 @@ "jsonfile": ["jsonfile@6.2.1", "", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="], + "kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="], + "kleur": ["kleur@4.1.5", "", {}, "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ=="], "lightningcss": ["lightningcss@1.33.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.33.0", "lightningcss-darwin-arm64": "1.33.0", "lightningcss-darwin-x64": "1.33.0", "lightningcss-freebsd-x64": "1.33.0", "lightningcss-linux-arm-gnueabihf": "1.33.0", "lightningcss-linux-arm64-gnu": "1.33.0", "lightningcss-linux-arm64-musl": "1.33.0", "lightningcss-linux-x64-gnu": "1.33.0", "lightningcss-linux-x64-musl": "1.33.0", "lightningcss-win32-arm64-msvc": "1.33.0", "lightningcss-win32-x64-msvc": "1.33.0" } }, "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA=="], @@ -1304,6 +1317,8 @@ "lines-and-columns": ["lines-and-columns@2.0.4", "", {}, "sha512-wM1+Z03eypVAVUCE7QdSqpVIvelbOakn1M0bPDoA4SGWPx3sNDVUiMo3L6To6WWGClB7VyXnhQ4Sn7gxiJbE6A=="], + "linkify-it": ["linkify-it@5.0.2", "", { "dependencies": { "uc.micro": "^2.0.0" } }, "sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q=="], + "load-plugin": ["load-plugin@6.0.3", "", { "dependencies": { "@npmcli/config": "^8.0.0", "import-meta-resolve": "^4.0.0" } }, "sha512-kc0X2FEUZr145odl68frm+lMJuQ23+rTXYmR6TImqPtbpmXC4vVXbWKDQ9IzndA0HfyQamWfKLhzsqGSTxE63w=="], "longest-streak": ["longest-streak@3.1.0", "", {}, "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g=="], @@ -1318,6 +1333,10 @@ "markdown-extensions": ["markdown-extensions@2.0.0", "", {}, "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q=="], + "markdown-it": ["markdown-it@14.3.2", "", { "dependencies": { "argparse": "^2.0.1", "entities": "^4.5.0", "linkify-it": "^5.0.2", "mdurl": "^2.0.0", "punycode.js": "^2.3.1", "uc.micro": "^2.1.0" }, "bin": { "markdown-it": "bin/markdown-it.mjs" } }, "sha512-sHHjZ5fJKlgrG4qns2YwVcdNep35h5fERrfkD2YNsb9UFk0UIHarbiTaHKVMlPuWAoiilyK8Fv/jAm11slsY7Q=="], + + "markdown-title": ["markdown-title@1.0.2", "", {}, "sha512-MqIQVVkz+uGEHi3TsHx/czcxxCbRIL7sv5K5DnYw/tI+apY54IbPefV/cmgxp6LoJSEx/TqcHdLs/298afG5QQ=="], + "mdast-comment-marker": ["mdast-comment-marker@3.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-mdx-expression": "^2.0.0" } }, "sha512-bt08sLmTNg00/UtVDiqZKocxqvQqqyQZAg1uaRuO/4ysXV5motg7RolF5o5yy/sY1rG0v2XgZEqFWho1+2UquA=="], "mdast-util-directive": ["mdast-util-directive@3.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "devlop": "^1.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0", "parse-entities": "^4.0.0", "stringify-entities": "^4.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-I3fNFt+DHmpWCYAT7quoM6lHf9wuqtI+oCOfvILnoicNIqjh5E3dEJWiXuYME2gNe8vl1iMQwyUHa7bgFmak6Q=="], @@ -1344,6 +1363,8 @@ "mdast-util-to-string": ["mdast-util-to-string@4.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0" } }, "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg=="], + "mdurl": ["mdurl@2.1.0", "", {}, "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg=="], + "merge-anything": ["merge-anything@5.1.7", "", { "dependencies": { "is-what": "^4.1.8" } }, "sha512-eRtbOb1N5iyH0tkQDAoQ4Ipsp/5qSR79Dzrz8hEPxRX10RWWR/iQXdoKmBSRCThY1Fh5EhISDtpSc93fpxUniQ=="], "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="], @@ -1394,11 +1415,13 @@ "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="], + "millify": ["millify@6.1.0", "", { "dependencies": { "yargs": "^17.0.1" }, "bin": { "millify": "bin/millify" } }, "sha512-H/E3J6t+DQs/F2YgfDhxUVZz/dF8JXPPKTLHL/yHCcLZLtCXJDUaqvhJXQwqOVBvbyNn4T0WjLpIHd7PAw7fBA=="], + "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="], "miniflare": ["miniflare@5.20260903.0-alpha", "", { "dependencies": { "@cspotcode/source-map-support": "0.8.1", "sharp": "0.35.2", "undici": "7.29.0", "workerd": "1.20260903.1", "ws": "8.21.0", "youch": "4.1.0-beta.10" } }, "sha512-VCZIFxOqFXeibRBJWwTlppqbv2lkeO10IX3QBRGK9j1QiMAfH/OSsCvbjp1MslBMhVZmy2VTRlVaVnsKnbDp6A=="], - "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="], + "minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="], "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="], @@ -1502,6 +1525,8 @@ "prebuild-install": ["prebuild-install@7.1.3", "", { "dependencies": { "detect-libc": "^2.0.0", "expand-template": "^2.0.3", "github-from-package": "0.0.0", "minimist": "^1.2.3", "mkdirp-classic": "^0.5.3", "napi-build-utils": "^2.0.0", "node-abi": "^3.3.0", "pump": "^3.0.0", "rc": "^1.2.7", "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" }, "bin": { "prebuild-install": "bin.js" } }, "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug=="], + "pretty-bytes": ["pretty-bytes@7.1.3", "", {}, "sha512-U2KZ675nqba6XSBppSjU2pRgc9Ffx9+uUtd/RTWYmOawVkZuUbBYuwdtFZQmLv+yMgQ2TQxWWuOpyNje67J9tg=="], + "proc-log": ["proc-log@4.2.0", "", {}, "sha512-g8+OnU/L2v+wyiVK+D5fA34J7EH8jZ8DDlvwhRCMxmMj7UCBvxiO1mGeN+36JXIKF4zevU4kRBd8lVgG9vLelA=="], "promise-inflight": ["promise-inflight@1.0.1", "", {}, "sha512-6zWPyEOFaQBJYcGMHBKTKJ3u6TBsnMFOIZSa6ce1e/ZrrsOlnHRHbabMjLiBYKp+n44X9eUI6VUPaukCXHuG4g=="], @@ -1514,6 +1539,8 @@ "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="], + "punycode.js": ["punycode.js@2.3.1", "", {}, "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA=="], + "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="], "rc": ["rc@1.2.8", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="], @@ -1632,6 +1659,8 @@ "search-insights": ["search-insights@2.17.3", "", {}, "sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ=="], + "section-matter": ["section-matter@1.0.0", "", { "dependencies": { "extend-shallow": "^2.0.1", "kind-of": "^6.0.0" } }, "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA=="], + "semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="], "seroval": ["seroval@1.5.4", "", {}, "sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw=="], @@ -1718,6 +1747,8 @@ "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="], + "tokenx": ["tokenx@1.6.0", "", {}, "sha512-CKTjk345ajvBAUp5xUI9a5KKN0zU0lBueVHQbCskH1Hp6WkUKsPW2qGCYNs0pxNyfzxfo+IIjdt2W4sMbw/qBw=="], + "tree-kill": ["tree-kill@1.2.2", "", { "bin": { "tree-kill": "cli.js" } }, "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A=="], "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="], @@ -1736,6 +1767,8 @@ "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="], + "uc.micro": ["uc.micro@2.1.0", "", {}, "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A=="], + "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="], "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="], @@ -1758,6 +1791,8 @@ "unist-util-position": ["unist-util-position@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA=="], + "unist-util-remove": ["unist-util-remove@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg=="], + "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="], "unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="], @@ -1798,6 +1833,8 @@ "vitepress": ["vitepress@1.6.4", "", { "dependencies": { "@docsearch/css": "3.8.2", "@docsearch/js": "3.8.2", "@iconify-json/simple-icons": "^1.2.21", "@shikijs/core": "^2.1.0", "@shikijs/transformers": "^2.1.0", "@shikijs/types": "^2.1.0", "@types/markdown-it": "^14.1.2", "@vitejs/plugin-vue": "^5.2.1", "@vue/devtools-api": "^7.7.0", "@vue/shared": "^3.5.13", "@vueuse/core": "^12.4.0", "@vueuse/integrations": "^12.4.0", "focus-trap": "^7.6.4", "mark.js": "8.11.1", "minisearch": "^7.1.1", "shiki": "^2.1.0", "vite": "^5.4.14", "vue": "^3.5.13" }, "peerDependencies": { "markdown-it-mathjax3": "^4", "postcss": "^8" }, "optionalPeers": ["markdown-it-mathjax3", "postcss"], "bin": { "vitepress": "bin/vitepress.js" } }, "sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg=="], + "vitepress-plugin-llms": ["vitepress-plugin-llms@1.14.0", "", { "dependencies": { "@11ty/gray-matter": "^2.1.0", "markdown-it": "^14.1.0", "markdown-title": "^1.0.2", "mdast-util-from-markdown": "^2.0.3", "millify": "^6.1.0", "minimatch": "^10.2.6", "path-to-regexp": "^6.3.0", "picocolors": "^1.1.1", "pretty-bytes": "^7.1.1", "remark": "^15.0.1", "remark-frontmatter": "^5.0.0", "tokenx": "^1.6.0", "unist-util-remove": "^4.0.0", "unist-util-visit": "^5.1.0" } }, "sha512-Qb42p9pYoRlMRbv+Yvh3reS4GInyr+ToU3G1tEC1Euz+gyBNywXkZIQPV/AoltizaakAeuI89Bkhkd7Y0jaM/w=="], + "vue": ["vue@3.5.39", "", { "dependencies": { "@vue/compiler-dom": "3.5.39", "@vue/compiler-sfc": "3.5.39", "@vue/runtime-dom": "3.5.39", "@vue/server-renderer": "3.5.39", "@vue/shared": "3.5.39" }, "peerDependencies": { "typescript": "*" }, "optionalPeers": ["typescript"] }, "sha512-xmZCYabFGcirU8r0fTuvl/LICc1OU620rnqepaJDL/a141ZigkG7AyaxQLdqJ02ZRYzWe6YPaDHeQx7MfknQfA=="], "walk-up-path": ["walk-up-path@3.0.1", "", {}, "sha512-9YlCL/ynK3CTlrSRrDxZvUauLzAswPCrsaCgilqFevUYpeEW0/3ScEjaa3kbW/T0ghhkEr7mv+fpjqn1Y1YuTA=="], @@ -1948,12 +1985,16 @@ "filelist/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="], + "glob/minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="], + "hosted-git-info/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="], "html-minifier-terser/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="], "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="], + "millify/yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="], + "node-abi/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], "normalize-package-data/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], @@ -1966,6 +2007,8 @@ "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="], + "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="], + "readdirp/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="], "sharp/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], @@ -2104,6 +2147,14 @@ "filelist/minimatch/brace-expansion": ["brace-expansion@2.1.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA=="], + "glob/minimatch/brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="], + + "millify/yargs/cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="], + + "millify/yargs/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="], + + "millify/yargs/yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="], + "solid-refresh/@babel/types/@babel/helper-string-parser": ["@babel/helper-string-parser@7.29.7", "", {}, "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw=="], "solid-refresh/@babel/types/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.29.7", "", {}, "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg=="], @@ -2202,6 +2253,14 @@ "filelist/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="], + "millify/yargs/cliui/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="], + + "millify/yargs/cliui/wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="], + + "millify/yargs/string-width/emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="], + + "millify/yargs/string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="], + "unified-engine/glob/minimatch/brace-expansion": ["brace-expansion@2.1.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA=="], "unified-engine/glob/path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="], @@ -2262,6 +2321,12 @@ "cmake-js/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + "millify/yargs/cliui/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + + "millify/yargs/cliui/wrap-ansi/ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="], + + "millify/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + "unified-engine/glob/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="], } } diff --git a/doc/.vitepress/config.ts b/doc/.vitepress/config.ts index 775556145ba..e816e25ebbf 100644 --- a/doc/.vitepress/config.ts +++ b/doc/.vitepress/config.ts @@ -1,4 +1,5 @@ import { defineConfig } from "vitepress"; +import llmstxt from "vitepress-plugin-llms"; import { syncDrafts } from "./drafts"; // Generated before VitePress enumerates routes, so the pages and this sidebar @@ -232,6 +233,18 @@ export default defineConfig({ lineNumbers: true, }, + // Serves /llms.txt (an index), /llms-full.txt (every page inline), and a + // .md twin of every page so agents can read the docs without the HTML. + vite: { + plugins: [ + llmstxt({ + domain: "https://doc.moq.dev", + // Static files are already served verbatim. + ignoreFiles: ["public/**"], + }), + ], + }, + ignoreDeadLinks: [ // Localhost URLs are intentional for development examples and aren't // reachable at build time (e.g. the relay on :4443, the dev server on :5173). diff --git a/doc/.vitepress/drafts.ts b/doc/.vitepress/drafts.ts index 87d61520ee5..01e8f5293e5 100644 --- a/doc/.vitepress/drafts.ts +++ b/doc/.vitepress/drafts.ts @@ -383,9 +383,16 @@ function render(source: string, routes: Map): { meta: Metadata; return out; }; + // The abstract's first line doubles as the page description for llms.txt + // and the meta tag, with citations reduced to their labels. + const description = cite(abstract.find((line) => line.trim() !== "") ?? "") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + const page = [ "---", `title: ${JSON.stringify(meta.title)}`, + `description: ${JSON.stringify(description)}`, "outline: deep", "---", "", diff --git a/doc/index.md b/doc/index.md index e217716fcf2..99cad74bd59 100644 --- a/doc/index.md +++ b/doc/index.md @@ -101,7 +101,7 @@ If everything works, a browser window will pop up demoing how to both publish an - Keep reading the [development guide](/setup/dev) to run more advanced demos. - Skip ahead to the [production guide](/setup/prod) to see what it takes to deploy this bad boy. -- Using an AI coding agent? [Teach it MoQ](/setup/agent) with a one-line prompt. +- Using an AI coding agent? [Teach it MoQ](/setup/agent) with a one-line prompt, or point it at [llms.txt](/llms.txt). ## Applications diff --git a/doc/package.json b/doc/package.json index 508a639a492..53dc554a2bc 100644 --- a/doc/package.json +++ b/doc/package.json @@ -16,6 +16,7 @@ "@types/node": "^26.4.1", "typescript": "7.0.2", "vitepress": "^1.6.4", + "vitepress-plugin-llms": "^1.14.0", "wrangler": "^4.129.0", "yaml": "^2.9.0" } diff --git a/doc/public/setup/agent/prompt.md b/doc/public/setup/agent/prompt.md index 825f0fc41f5..fdce4b16055 100644 --- a/doc/public/setup/agent/prompt.md +++ b/doc/public/setup/agent/prompt.md @@ -15,7 +15,7 @@ Notes: - Add `--global` to install user-level instead of project-level. - Add `-a ` (e.g. `-a claude-code`) to target a specific agent instead of auto-detection. -The skill teaches the agent the MoQ architecture, the `@moq/*` npm packages and `moq-*` Rust crates, the web components, relay setup, and common pitfalls. +The skill tells the agent what MoQ is and how to read the documentation as markdown (https://doc.moq.dev/llms.txt) instead of guessing APIs. ## Verify diff --git a/doc/setup/agent.md b/doc/setup/agent.md index 6f2a10fa8b5..46e05f6d55b 100644 --- a/doc/setup/agent.md +++ b/doc/setup/agent.md @@ -11,7 +11,7 @@ Using an AI coding agent like Claude Code, Cursor, or Codex? Teach it MoQ by pas Follow the instructions at https://doc.moq.dev/setup/agent/prompt.md ``` -The agent will fetch the instructions and install the [MoQ skill](https://github.com/moq-dev/moq/tree/main/skills/moq) into your project. The skill is an index of the MoQ ecosystem: what you can build (live streaming, conferencing, voice AI, real-time data, and more) and which [`@moq/*`](/lib/js/) packages, [`moq-*`](/lib/rs/) crates, gateways, and plugins to reach for, so the agent starts from the right layer instead of hallucinating an API. +The agent will fetch the instructions and install the [MoQ skill](https://github.com/moq-dev/moq/tree/main/skills/moq) into your project. The skill tells the agent what MoQ is and to read this site as markdown (see below) instead of hallucinating an API. ## Manual Installation @@ -25,6 +25,10 @@ Add `--global` for a user-level install, or `-a ` to target a specific ag ## What's in the Skill? -The skill is a single markdown file, [`skills/moq/SKILL.md`](https://github.com/moq-dev/moq/blob/main/skills/moq/SKILL.md), that your agent loads when a task involves MoQ. It's a map rather than a manual: use cases matched to the libraries, binaries, and gateways that implement them, plus links back to [doc.moq.dev](https://doc.moq.dev) for the details. +The skill is a single markdown file, [`skills/moq/SKILL.md`](https://github.com/moq-dev/moq/blob/main/skills/moq/SKILL.md), that your agent loads when a task involves MoQ. It's deliberately short: what MoQ is, a pointer to this site, and the few facts that don't change, so it never goes stale as the packages evolve. Contributions welcome; it's just markdown. + +## Reading the Docs + +Every page on this site is also served as plain markdown: drop any trailing `/` and append `.md`, so `/bin/relay/` becomes `/bin/relay.md` and `/lib/js/watch` becomes `/lib/js/watch.md`. [`/llms.txt`](/llms.txt) indexes every page with a one-line description, and [`/llms-full.txt`](/llms-full.txt) bundles them all into one file, following the [llms.txt](https://llmstxt.org) convention. diff --git a/skills/moq/SKILL.md b/skills/moq/SKILL.md index be2e78d244c..d77a8e4b42f 100644 --- a/skills/moq/SKILL.md +++ b/skills/moq/SKILL.md @@ -1,64 +1,26 @@ --- name: moq -description: Build live video, audio, and real-time data apps with Media over QUIC (MoQ). Use when adding live streaming, conferencing, voice AI, or real-time pub/sub to an app; when integrating the @moq/* npm packages, moq-* Rust crates, or the Python/Kotlin/Swift/Go/C bindings; or when running a moq-relay server or a gateway (RTMP, SRT, WebRTC, HLS, OBS, GStreamer, ffmpeg). +description: Build live video, audio, and real-time data apps with Media over QUIC (MoQ). Use when adding live streaming, conferencing, voice AI, or real-time pub/sub to an app; when integrating the @moq/* npm packages, moq-* Rust crates, or the Python/Kotlin/Swift/Go/C/Dart bindings; or when running a moq-relay server or a gateway (RTMP, SRT, WebRTC, HLS, OBS, GStreamer, ffmpeg). --- # Media over QUIC (MoQ) -MoQ is a live media protocol delivering real-time (sub-second) latency at CDN scale. -It is generic pub/sub over QUIC: video and audio are the flagship use case, but any live data rides the same relays (chat, game input, JSON state, AI output). +MoQ is generic real-time pub/sub over QUIC: relays fan out named tracks of groups of frames without understanding the payload. +Video and audio are the flagship use case, but chat, game input, JSON state, and AI output ride the same relays. -This skill is an index of the moq-dev monorepo (https://github.com/moq-dev/moq): what you can build and which pieces to reach for. Fetch the linked docs for details instead of guessing APIs. +## Read the live docs -## Layering +The project moves quickly and your training data is stale: it describes the IETF `moq-transport` draft and crates that no longer exist. +Do not guess APIs, package names, or flags. Read https://doc.moq.dev as part of the task. -The stack from the wire up. Reach for the highest layer that fits and drop down only when you need control: +1. Fetch https://doc.moq.dev/llms.txt, an index of every page with a one-line description. +2. Fetch the pages you need as markdown: drop any trailing `/` and append `.md`, e.g. https://doc.moq.dev/lib/js/watch.md. +3. For an API, read that package's page before writing code. For a design question, start at https://doc.moq.dev/concept.md. -1. **QUIC**: does all the networking. Provided by the browser or a QUIC library (`moq-native` configures one for you in Rust). -2. **WebTransport**: a thin layer over QUIC/HTTP3 so browsers can speak it. Provided by the browser or the `web-transport` crates. -3. **moq-lite** (Rust `moq-net`, TypeScript `@moq/net`): generic real-time pub/sub. A *broadcast* contains named *tracks*; tracks carry *groups* of *frames*. Relays cache, deduplicate, and fan out without understanding the payload, so anything can be end-to-end encrypted. This is the layer CDNs implement. -4. **hang** (Rust `hang`, TypeScript `@moq/hang`): media on top. A catalog track describes codecs/renditions; containers carry timestamped codec bitstream. Think of hang as HLS/DASH and moq-lite as HTTP. -5. **Your application**: business logic, auth, custom tracks. Extend hang with your own tracks or replace it entirely. +## Durable facts -Everything below builds on these layers. - -## What you can build - -**Live streaming (Twitch-style)**. Ingest via the OBS plugin (`cpp/obs`), RTMP (`rs/moq-rtmp`), SRT (`rs/moq-srt`), GStreamer (`rs/moq-gst`), or pipe ffmpeg into the `moq` CLI (`rs/moq-cli`, a media router bridging fMP4/CMAF, MPEG-TS, FLV, HLS, RTMP, SRT, WebRTC). Distribute through `moq-relay` and watch in the browser with `` (`@moq/watch`). Serve legacy players via the HLS/LL-HLS gateway (`rs/moq-hls`) and build a rendition ladder with just-in-time transcoding (`rs/moq-transcode`). Docs: https://doc.moq.dev/bin/ - -**Conferencing (Zoom-style)**. Browser capture and playback with `@moq/publish` + `@moq/watch`; each participant is a broadcast, discovered via announcements. Bridge existing WebRTC clients with the WHIP/WHEP gateway (`rs/moq-rtc`). Why MoQ over WebRTC: https://doc.moq.dev/concept/use-case/conferencing - -**Voice/video AI agents**. Server-side media without a browser, straight from Rust: `moq-mux` publishes and decodes media containers (fMP4/CMAF, MPEG-TS, FLV), while `rs/moq-video` and `rs/moq-audio` capture/encode and decode/render with hardware codecs (VideoToolbox, D3D11, NVENC, VAAPI). Python bindings fit ML stacks, and the Pipecat voice-agent framework ships MoQ transport support (https://github.com/pipecat-ai/pipecat). TTS output written faster than real-time plays smoothly via `@moq/watch` buffered playback (`latency-max`). Background: https://moq.dev/blog/webrtc-is-the-problem and https://doc.moq.dev/concept/use-case/ai - -**Real-time data, no media at all**. Chat, multiplayer game state, telemetry, collaborative apps: publish raw tracks with `@moq/net` or `moq-net`. Helpers: `moq-json` / `@moq/json` (JSON snapshots, merge-patch deltas, append logs) and `moq-flate` / `@moq/flate` (compression). A synchronized-clock example lives in `js/clock`. Same relays, same auth as media. Rule of thumb: anything that can be delta encoded or dropped when stale is a good fit for MoQ. - -**Interactive streams and teleoperation**. Combine both directions: media down, input tracks up. MoQ Boy (`rs/moq-boy`, `demo/boy`) is a crowd-controlled Game Boy doing exactly this: https://moq.dev/blog/moq-boy. The same shape covers flying drones, controlling robots, and remote vehicle operation; some companies start from MoQ Boy and replace the emulator with a robot. - -**Cloud gaming / remote desktop**. Screen capture and low-latency hardware encoding via `rs/moq-video` (camera and display sources on macOS/Windows/Linux, plus window capture), sub-100ms playback in the browser. - -**Native and mobile apps**. One Rust core (`rs/moq-ffi`) with idiomatic bindings: Python (asyncio), Kotlin (coroutines/Flow, Android), Swift (async sequences, iOS/macOS), Go, and C (`rs/libmoq` for C/C++ build systems). Index: https://doc.moq.dev/lib/ - -**Global delivery, hosted or self-hosted**. Don't want to run infrastructure? https://moq.pro offers most of these libraries behind an API and a global CDN, with more CDN providers to come; moq-lite is also forwards-compatible with IETF moq-transport, so it runs over third-party CDNs like Cloudflare (https://moq.dev/blog/first-cdn). To self-host: `moq-relay` clusters across regions (https://doc.moq.dev/bin/relay/cluster), authenticates with path-scoped JWTs (`moq-token`, https://doc.moq.dev/bin/relay/auth), and exposes live traffic stats as MoQ tracks (`rs/moq-stats`). Load-test with `rs/moq-bench`. Native apps can also connect P2P via Iroh. - -**Web playback/capture on any site**. `` and `` are plain web components with optional UI overlays; embeddable with no build step. Docs: https://doc.moq.dev/lib/js/watch and https://doc.moq.dev/lib/js/publish - -## Repo map - -- `rs/` Rust: `moq-net` (pub/sub), `hang` (media), `moq-relay`, `moq-cli` (installs a `moq` binary), `moq-native` (QUIC/TLS setup), `moq-mux` (container muxing), `moq-token[-cli]` (auth), gateways (`moq-rtmp`, `moq-srt`, `moq-rtc`, `moq-hls`), native codecs (`moq-video`, `moq-audio`, `moq-nvenc`), `moq-ffi`/`libmoq` (bindings core). -- `js/` TypeScript, published as `@moq/*`: `net`, `hang`, `watch`, `publish`, `token`, `json`, `signals`. -- `py/`, `swift/`, `kt/`, `go/` bindings; `cpp/obs` OBS plugin; `demo/` runnable demos. - -## Getting started - -- Every client connects to a relay URL; the path scopes auth and broadcast names append to it. Public dev relay: `https://cdn.moq.dev/anon` (unauthenticated, testing only, pick a unique name). Hosted production relays: https://moq.pro. Local: `cargo install moq-relay`, or clone the repo and `nix develop -c just` to run a relay, demo media, and web UI together. -- Media broadcast names end in `.hang` (selects the hang catalog; `.msf` selects the IETF MSF format). -- Browsers need WebTransport (Chrome/Edge; Firefox/Safari experimental) and, outside localhost, a real TLS certificate. -- Auth is a JWT in the `?jwt=` query parameter, signed by `moq-token`. - -## Reference - -- Documentation: https://doc.moq.dev (concepts, apps, libraries, relay ops) -- Rust API docs: https://docs.rs/moq-net and https://docs.rs/hang -- Runnable examples: https://github.com/moq-dev/moq/tree/main/js/net/examples and https://github.com/moq-dev/moq/tree/main/rs/hang/examples -- Protocol drafts: https://moq-dev.github.io/drafts/draft-lcurley-moq-lite.html -- Inspiration: https://moq.dev/blog/ +- Two layers: `moq-lite` (`moq-net` / `@moq/net`) is the generic pub/sub the relays implement; `hang` (`hang` / `@moq/hang`) is the media catalog and container on top. Use the highest layer that fits: web components, then `@moq/*` / `moq-*` packages, then the wire protocol. +- Every client connects to a relay URL. The path scopes authorization, and broadcast names append to it. +- Media broadcast names end in `.hang`. +- Browsers need WebTransport and, outside localhost, a real TLS certificate. +- Source, examples, and issues: https://github.com/moq-dev/moq From 059263282989ded078870e2c17b436cdb6d2c110 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 11:02:07 +0200 Subject: [PATCH 09/11] docs(cluster): let a receiver choose among publishers and simplify the draft (#3722) Co-authored-by: Claude Opus 5 --- drafts/draft-lcurley-moq-cluster.md | 225 +++++++++++++--------------- 1 file changed, 107 insertions(+), 118 deletions(-) diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index fd18fceeb6b..65cd222e491 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -24,12 +24,17 @@ informative: --- abstract This document defines a clustering extension for MoQ Transport {{moqt}}, used to build a mesh of relays. -Each namespace advertisement carries the ordered list of Hop IDs it has traversed, starting with the original publisher, plus the accumulated cost of that path. -A receiver uses the list to detect routing loops and to identify which advertisements come from the same publisher, and the cost to choose between paths. -Each endpoint declares its own Hop ID during setup, and the peer uses it to avoid advertising or serving a path that already passed through that endpoint. +Each namespace advertisement carries the list of Hop IDs it has passed through, starting with the original publisher, and the accumulated cost of that path. +A receiver uses the list to detect loops and to tell which advertisements come from the same publisher, and the cost to choose between paths. +Each endpoint declares its own Hop ID at setup, so a peer never advertises or serves it a path that already passed through it. --- middle +# Note to Readers +This document was written with the assistance of Claude, an AI model by Anthropic. +The author reviewed every revision and is responsible for its content. + + # Conventions and Definitions {::boilerplate bcp14-tagged} @@ -38,25 +43,23 @@ The same pair of relays can be upstream of each other for different namespaces. # Introduction -{{moqt}} is designed to deliver content through a mesh of relays, but is deliberately vague about how that mesh is built, and the base transport does not carry enough information to build one. - -Relays that gossip namespaces with PUBLISH_NAMESPACE quickly break down: advertisements loop between relays forever, and when two connections advertise the same namespace, a relay has no basis for deciding which one to route a SUBSCRIBE toward. +{{moqt}} is designed to deliver content through a mesh of relays but does not say how to build one, and the base protocol does not carry enough information to do so. +Relays that simply forward PUBLISH_NAMESPACE to each other break down: advertisements loop forever, and a relay that hears one namespace from two peers has no basis for choosing where to send a SUBSCRIBE. -This extension adds the HOP_PATH parameter to PUBLISH_NAMESPACE and NAMESPACE. -It lists every node an advertisement has passed through, starting with the original publisher, which is enough to break loops and to compare paths. -Each connection also declares its own Hop ID at SETUP, so loops are avoided even across multiple connections between the same pair of relays. -A namespace is routed to one publisher: the mesh carries the best path to it, not one path per publisher ({{single}}). +This extension adds two parameters to PUBLISH_NAMESPACE and NAMESPACE. +HOP_PATH lists every endpoint an advertisement has passed through, starting with the original publisher, which breaks loops and lets paths be compared. +ROUTE_COST is the accumulated price of the path: the publisher seeds it, and each hop adds the RELAY_COST its upstream declared at setup, so an unpriced mesh ranks by hop count. +A relay that already carries a namespace advertises a lower cost, steering subscribers toward its warm copy. -Not every route is equal: one crossing a metered backbone costs more than one inside a datacenter. -The RELAY_COST Setup Option prices what subscribing from an endpoint costs, defaulting to 1 so an unpriced mesh simply ranks by hop count. -The ROUTE_COST parameter carries the accumulated price per namespace, and a relay may lower it to advertise that it already has the content cached, steering subscribers toward a warm copy. +Each endpoint also declares its own Hop ID at setup, so a peer can leave it out of every path it advertises or serves to it, even across several connections between the same two relays. +An advertisement is one path, so a relay forwards only the best path it knows per namespace and serves a subscription from one source at a time ({{publishers}}). # Setup Negotiation ## Hop ID {#hop-id} -The extension is negotiated during the SETUP exchange ({{moqt}} Section 10.3). -An endpoint indicates support with the following Setup Option, whose value is its own Hop ID: +The extension is negotiated during SETUP ({{moqt}} Section 10.3). +An endpoint offers it by declaring its own Hop ID: ~~~ HOP_ID Setup Option { @@ -65,13 +68,11 @@ HOP_ID Setup Option { } ~~~ -Negotiation is per session; a relay MUST NOT assume that because one of its sessions negotiated the extension, another did. -It also enables the extended NAMESPACE message ({{namespace}}), which is what lets a NAMESPACE carry these parameters at all. +Negotiation is per session; a relay MUST NOT assume that because one session negotiated the extension, another did. +On a session that did, every PUBLISH_NAMESPACE and NAMESPACE MUST carry HOP_PATH, NAMESPACE takes the extended form in {{namespace}}, and a receiver MUST close the session with a PROTOCOL_VIOLATION if either arrives without HOP_PATH. -On a session that negotiated the extension, an endpoint MUST include HOP_PATH on every PUBLISH_NAMESPACE and NAMESPACE it sends, and a receiver MUST close the session with a PROTOCOL_VIOLATION if one arrives without it. - -## Relay Cost -An endpoint MAY declare what subscribing from it costs: +## Relay Cost {#relay-cost} +An endpoint MAY declare what it charges for sending content: ~~~ RELAY_COST Setup Option { @@ -80,63 +81,61 @@ RELAY_COST Setup Option { } ~~~ -The option prices one direction, the sender's own egress, so each endpoint declares its own and the two need not match, as OSPF prices each router's own output interfaces ({{?RFC2328, Section 9}}). -A receiver adds the value the sender declared to the ROUTE_COST of every advertisement that sender forwards. -An absent option means 1, under which the accumulated cost equals the hop count. -0 is meaningful and distinct from absent: it makes that direction free, which is how a deployment describes two relays in the same datacenter. +The value prices the sender's own egress, so each endpoint declares its own and the two need not match, as OSPF prices each router's own output interfaces ({{?RFC2328, Section 9}}). +A receiver adds it to the ROUTE_COST of every advertisement that peer forwards ({{accumulating}}). +Absent means 1, so an unpriced mesh ranks by hop count. +0 is distinct from absent: it makes the link free, which is how to describe two relays in the same datacenter. -A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value instead, so a peer cannot reprice its neighbours by declaring itself cheap. +A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value instead, so a peer cannot make itself cheap by saying so. -The cost is one dimensionless integer, as in every widely deployed routing metric: RIP's hop count ({{?RFC2453, Section 3.5}}), OSPF's interface cost, and IS-IS's default metric, whose companion delay, expense, and error metrics went unimplemented ({{?RFC5305, Section 3}}) just as OSPF's per-type-of-service metrics were deleted for lack of use ({{?RFC2178, Appendix G.10}}). -A deployment that weighs several factors, such as latency, hop count, and price, folds them into the one value it declares. -Like BGP's MULTI_EXIT_DISC ({{?RFC4271, Section 5.1.4}}), the value is comparable only within the deployment that chose its units, which is why a trust boundary clamps or replaces it ({{security}}). +The cost is one dimensionless integer, as in every deployed routing metric: RIP's hop count ({{?RFC2453, Section 3.5}}), OSPF's interface cost, and IS-IS's default metric, whose delay, expense, and error metrics went unimplemented ({{?RFC5305, Section 3}}), as did OSPF's per-type-of-service metrics ({{?RFC2178, Appendix G.10}}). +A deployment that weighs latency, hop count, and price folds them into the one value. +Like BGP's MULTI_EXIT_DISC ({{?RFC4271, Section 5.1.4}}), the value only means something within the deployment that chose its units, so a trust boundary clamps or replaces it ({{security}}). -# Hop IDs -A **Hop ID** is a variable-length integer identifying one endpoint within an advertisement's path. +# Hop IDs {#hop-ids} +A **Hop ID** is a variable-length integer naming one endpoint in a path. Hop IDs SHOULD be unique among the endpoints an advertisement can traverse. -An endpoint MAY generate one randomly, since collisions across a 64-bit space are unlikely, or use a stable configured identifier that survives restarts. +An endpoint MAY pick one at random, since collisions in a 64-bit space are unlikely, or use a configured identifier that survives restarts. -Loop detection and origin identification compare Hop IDs for equality, so two endpoints sharing a Hop ID are indistinguishable. -Redundant publishers producing interchangeable content MAY share one deliberately, so a receiver treats their paths as failover options for the same content ({{selection}}). +Loops and origins are detected by comparing Hop IDs for equality, so two endpoints sharing one are indistinguishable. +Redundant publishers of interchangeable content MAY share one deliberately, so the mesh treats their paths as failover options for the same content ({{selection}}). ## The Reserved Hop ID 0 {#zero} **0 means "no identity"** and is reserved. -It is used for an endpoint that did not negotiate this extension, and an endpoint MAY also declare 0 to withhold its identity. +It stands for an endpoint that did not negotiate this extension, and an endpoint MAY declare it to withhold its identity. -Because any number of endpoints can be 0, it identifies nothing, which constrains all three uses: +Since any number of endpoints can be 0, it identifies nothing: -- **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself, and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown origin. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). Updating one advertisement is not two ({{updating}}). -- **Filtering**: a peer that declared 0 declared no identity, so there is nothing on the wire to filter that session on. A receiver MAY assign one ({{assigned}}), which covers what it attributes to that session itself but not an advertisement that arrived carrying its own HOP_PATH. +- **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself and MUST NOT discard an advertisement merely because the path contains 0. +- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). +- **Filtering**: a peer that declared 0 gave the receiver nothing to filter that session on. The receiver MAY assign an ID of its own ({{assigned}}). Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. -Declaring 0 therefore trades loop detection and failover for anonymity, except against a receiver that assigns an identity of its own. +Declaring 0 trades loop detection and failover for anonymity, except against a receiver that assigns an identity of its own. ## Assigned Identities {#assigned} -A receiver MAY assign a Hop ID of its own to a peer that declared none, whether by declaring 0 or by not negotiating this extension at all. -It uses that ID wherever it would otherwise have nothing to name the peer with: as the entry it creates for an upstream that sent no HOP_PATH, and as what it filters that session on. +A receiver MAY assign a Hop ID to a peer that declared none, whether by declaring 0 or by not negotiating the extension. +It uses that ID wherever it has nothing else to name the peer with: as the first entry of a HOP_PATH it creates for an upstream that sent none, and as what it filters that session on. -The ID is the receiver's own, not the peer's. -An advertisement that arrives carrying its own HOP_PATH names the sender there, as 0 if the sender withheld it, and this document does not define rewriting that entry. -So an assigned ID governs the advertisements a receiver attributed itself, and a peer that both declares 0 and sends its own HOP_PATH keeps the consequences in {{zero}}. +The ID is the receiver's own. +An advertisement that arrives with its own HOP_PATH already names the sender there, as 0 if withheld, and this document does not define rewriting that entry. +So an assigned ID covers what the receiver itself attributes to the session; a peer that declares 0 and sends its own HOP_PATH keeps the consequences in {{zero}}. An assigned ID MUST NOT be shared between peers not known to be the same endpoint. -Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be spliced into one and starve each other of routes. +Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be merged into one and starve each other of routes. -How an endpoint scopes the ID follows from what it can establish about the peer. -One it authenticated, or one it dialed and therefore chose, SHOULD get a single stable ID, which additionally lets reconnects and redundant sessions be recognized as the same content ({{selection}}); assigning per connection there would make one peer look like several. -An endpoint accepting an anonymous session can establish nothing and cannot correlate it with any other, so it SHOULD assign a distinct ID per session: less than an identity, but enough to keep routes it attributed to that session from being advertised back to it, which is the loop 0 cannot prevent. +A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are recognized as the same content; a fresh ID per connection would make one peer look like several. +An anonymous accepted session cannot be correlated with anything, so it SHOULD get a distinct ID per session: not an identity, but enough to keep routes learned from it from being advertised back to it, which is the loop 0 cannot prevent. -An assigned ID is indistinguishable on the wire from a declared one, so it identifies the peer to everyone the receiver forwards to; a peer that declared 0 for anonymity did not ask for that. +An assigned ID looks like a declared one on the wire, so it identifies the peer to everyone downstream; a peer that declared 0 for anonymity did not ask for that. # Namespace Advertisements {#namespace} -This extension carries HOP_PATH and ROUTE_COST as Key-Value-Pair parameters ({{moqt}} Section 2.5). -PUBLISH_NAMESPACE ({{moqt}} Section 10.15) already has a Parameters field. - -NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE messages, so this extension defines an extended form used only on a session that negotiated the extension: +HOP_PATH and ROUTE_COST are Key-Value-Pair parameters ({{moqt}} Section 2.5). +PUBLISH_NAMESPACE ({{moqt}} Section 10.15) already carries parameters. +NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE, so on a session that negotiated this extension it takes an extended form: ~~~ NAMESPACE Message (Cluster) { @@ -148,13 +147,12 @@ NAMESPACE Message (Cluster) { } ~~~ -The appended fields are encoded exactly as in PUBLISH_NAMESPACE. +The added fields are encoded exactly as in PUBLISH_NAMESPACE. An endpoint MUST NOT append them on a session that did not negotiate the extension. - -NAMESPACE_DONE ({{moqt}} Section 10.17) carries no state from this extension and is not extended. +NAMESPACE_DONE ({{moqt}} Section 10.17) is not extended. ## HOP_PATH Parameter {#hop-path} -HOP_PATH is the ordered list of Hop IDs an advertisement has traversed, from the original publisher to the relay immediately upstream of the receiver: +HOP_PATH is the ordered list of Hop IDs an advertisement has passed through, from the original publisher to the peer sending it: ~~~ HOP_PATH Parameter { @@ -164,11 +162,11 @@ HOP_PATH Parameter { } ~~~ -The list always has at least one entry, the original publisher, which is 0 if that publisher is unknown ({{zero}}). -A receiver MUST close the session with a PROTOCOL_VIOLATION if the entries do not exactly fill `Length`, if the list is empty, or if a non-zero Hop ID appears twice. +The list always has at least one entry, the original publisher, 0 if unknown ({{zero}}). +A receiver MUST close the session with a PROTOCOL_VIOLATION if the list is empty, if the entries do not exactly fill `Length`, or if a non-zero Hop ID appears twice. -## ROUTE_COST Parameter -ROUTE_COST is the marginal cost of subscribing via this advertisement: the price of the transfers a new subscription would actually cause. +## ROUTE_COST Parameter {#route-cost} +ROUTE_COST is the marginal cost of subscribing through this advertisement: the price of the transfers a new subscription would cause. ~~~ ROUTE_COST Parameter { @@ -177,91 +175,87 @@ ROUTE_COST Parameter { } ~~~ -It is OPTIONAL and absent means 0, so an endpoint that prices nothing sends nothing. -Costs still accumulate across such a mesh, because each receiver adds the price for the direction it received over ({{relay-cost}}) regardless. +It is OPTIONAL and absent means 0. +Costs still accumulate across a mesh that sends none, because each receiver adds the RELAY_COST of the link it received over ({{accumulating}}). -The original publisher seeds the value with its production cost: 0 for content it is already producing, higher for content it would have to spin up on demand, such as a standby transcoder advertising everything it *could* serve. +The original publisher seeds the value with its production cost: 0 for content it already produces, higher for content it would have to start on demand, such as a standby transcoder advertising everything it could serve. # Relay Behavior -When forwarding an advertisement downstream, a relay MUST append its own Hop ID to the HOP_PATH it received, so its own ID is always the last entry. -An advertisement arriving from an upstream that did not negotiate the extension has no HOP_PATH; the relay creates one containing a single entry for that upstream, 0 ({{zero}}) or an ID it assigned ({{assigned}}), then appends its own. +A relay forwarding an advertisement MUST append its own Hop ID to the HOP_PATH it received, so its ID is always the last entry. +An upstream that did not negotiate the extension sends no HOP_PATH; the relay creates one with a single entry for that upstream, 0 ({{zero}}) or an assigned ID ({{assigned}}), then appends its own. -On receipt, a relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. -This receiver-side check catches loops of any length and is the only loop defense required. -A conforming sender never sends one ({{selection}}), so a receiver MAY instead close the session with a PROTOCOL_VIOLATION; discarding is what keeps a mesh working when one member does not conform. +A relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. +This check catches loops of any length and is the only loop defense required. +A conforming sender never sends one ({{selection}}), so a receiver MAY close the session with a PROTOCOL_VIOLATION instead; discarding is what keeps the mesh working when one member does not conform. -## Accumulating Cost -A relay MUST add the cost the sending endpoint declared ({{relay-cost}}) to the ROUTE_COST it received before forwarding or acting on an advertisement. -The addition MUST saturate rather than wrap, so an absurd upstream value ranks last instead of overflowing to best. +## Accumulating Cost {#accumulating} +Before forwarding or acting on an advertisement, a relay MUST add the RELAY_COST the sender declared ({{relay-cost}}) to the ROUTE_COST it received. +The addition MUST saturate rather than wrap, so an absurd value ranks last instead of overflowing to best. -A relay actively carrying the namespace (a live subscription exists for at least one of its tracks) SHOULD advertise 0 instead of the accumulated value: its ingress is already paid for, so one more subscriber costs only the links below it. -This is what lets a cluster deduplicate onto a warm copy. -The discount applies only to the advertisement for the path it actually serves from; a standby path keeps its accumulated value, since serving from it means opening a fresh ingest. +A relay actively carrying the namespace (a live subscription exists for at least one of its tracks) SHOULD advertise 0 instead: its ingress is already paid for, so another subscriber costs only the links below it. +This is what lets a cluster converge on a warm copy. +The discount applies only to the path it actually serves from; a standby path keeps its accumulated value, since serving from it means opening a fresh ingest. When it stops carrying the namespace it SHOULD restore the accumulated value, optionally after a grace period so brief churn does not flap routing. -Two relays that independently begin carrying the same namespace would each see the other's 0 as cheaper than its own source, and both switching at once would leave the namespace with no source. +Two relays that each begin carrying the same namespace would each see the other's 0 as cheaper than its own source, and if both switched at once the namespace would have no source. Before re-parenting onto a 0-cost advertisement from another actively-carrying relay (one whose HOP_PATH has two or more entries), a relay SHOULD apply a deterministic tie-break, such as comparing a hash of the namespace and each Hop ID, so exactly one side moves. -Equal Hop IDs (including two relays that both declared 0) cannot be ordered, and neither side SHOULD move. -Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted immediately. +Equal Hop IDs, including two relays that both declared 0, cannot be ordered, and neither side SHOULD move. +Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted at once. ## Updating an Advertisement {#updating} An endpoint updates a PUBLISH_NAMESPACE with REQUEST_UPDATE ({{moqt}} Section 9.5) on its request stream, carrying the HOP_PATH or ROUTE_COST that changed. -A parameter omitted from REQUEST_UPDATE keeps its value, so a relay that starts carrying a namespace sends ROUTE_COST as an explicit 0 rather than omitting it. +An omitted parameter keeps its value, so a relay that starts carrying a namespace sends an explicit ROUTE_COST of 0. The receiver answers REQUEST_OK, or REQUEST_ERROR and closes the stream, which withdraws the advertisement. -NAMESPACE is a response and has no REQUEST_UPDATE, so an endpoint updates one by re-sending it with new parameters on the SUBSCRIBE_NAMESPACE response stream that carries it. +NAMESPACE has no REQUEST_UPDATE, so an endpoint updates one by re-sending it with new parameters on the same SUBSCRIBE_NAMESPACE response stream. A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. -In {{moqt}} an advertisement lives for the lifetime of its stream, so an update on a *new* stream would leave two streams claiming one namespace and let the superseded one retract its replacement. -An endpoint MUST NOT open a second stream for a namespace it already advertises on this session. - -Replacement is atomic, so a receiver MUST NOT tear down subscriptions or drop cached state merely because an update arrived. -What it means for existing subscriptions follows the first HOP_PATH entry ({{selection}}): unchanged, the content is continuous and subscriptions MAY resume on the new route at a group boundary; changed, a different publisher has taken over and they do not carry over. +An advertisement lives as long as its stream, so an update on a new stream would leave two streams claiming one namespace. +An endpoint MUST NOT open a second stream for a namespace it already advertises on the session. -This is the one comparison 0 ({{zero}}) does not decide: it identifies nothing, but there is one advertisement here and the stream carrying it is the continuity. -An endpoint whose publisher did change MUST withdraw the advertisement (NAMESPACE_DONE or PUBLISH_NAMESPACE_DONE) and advertise again rather than update in place. +An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. +If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. +If the publisher did change, the endpoint MUST withdraw the advertisement (PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE) and advertise again rather than update in place. -The expected case is a ROUTE_COST-only change, which is how a relay signals that it started or stopped carrying the namespace. +The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. # Path Selection {#selection} -A receiver holding advertisements for the same namespace over several sessions SHOULD prefer the lowest ROUTE_COST, breaking ties toward the shorter HOP_PATH and then toward the most recently received. -This is advisory: a receiver MAY apply local policy such as measured RTT instead. +A receiver holding advertisements for one namespace over several sessions SHOULD prefer the lowest ROUTE_COST, breaking ties toward the shorter HOP_PATH and then toward the most recently received. +This is advisory: a receiver MAY apply local policy, such as measured RTT, instead. -Two advertisements whose HOP_PATH begins with the same non-zero Hop ID share a publisher and carry interchangeable content, so a receiver MAY hold them as redundant paths and fail an active subscription over to the survivor. -If the first entries differ, or either is 0, they are distinct publishers reusing a namespace: a receiver MUST NOT treat them as interchangeable and SHOULD treat the later as replacing the earlier. +Two advertisements whose HOP_PATH begins with the same non-zero Hop ID come from the same publisher and carry interchangeable content: a receiver MAY hold them as redundant paths and fail an active subscription over to the survivor at a group boundary. +If the first entries differ, or either is 0, they are distinct publishers reusing a namespace ({{publishers}}). -A publisher MUST NOT advertise a path whose HOP_PATH contains the Hop ID that peer declared. -The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. -Of the paths that remain a publisher SHOULD advertise the best, and advertises nothing when every known path contains that Hop ID. -Because selection is per session, a peer that the serving path flows through still receives the best standby, which is what lets it fail over if its own copy dies. +An endpoint MUST NOT advertise a path whose HOP_PATH contains the Hop ID the peer declared: the peer could only discard it, and acting on it would form a loop. +Of the paths that remain it SHOULD advertise the best, and advertises nothing when every path contains that Hop ID. +Because selection is per session, a peer that the serving path runs through still receives the best standby, which is what lets it fail over if its own copy dies. -When serving a subscription, a publisher MUST select the source by that same rule. +An endpoint MUST select the source for a subscription by the same rule. If only excluded sources remain the subscription is unroutable, since serving it would hand the subscriber data that already flowed through itself. -Applying one rule to both advertisement and dispatch keeps advertised paths truthful and prevents subscription cycles of any length. +One rule for advertisement and dispatch keeps advertised paths truthful and prevents subscription cycles of any length. -# One Publisher per Namespace {#single} -{{moqt}} allows several publishers to advertise one namespace and expects a relay to forward a matching SUBSCRIBE to each. -This extension does not: a session advertises a namespace at most once, a relay advertises only the best path it knows ({{selection}}), and a subscription is served from one source. +# Several Publishers of One Namespace {#publishers} +{{moqt}} lets several publishers advertise one namespace and leaves to the relay how it serves a SUBSCRIBE among them. +Under this extension an advertisement is a path, so a session advertises a namespace at most once, a relay forwards only the best path it knows ({{selection}}), and a subscription is served from one source at a time. -A relay holding paths to two publishers of one namespace has no good move. -SUBSCRIBE names a track, not a publisher, so a relay could only forward it along every path and deliver both publishers' Objects to every subscriber below it, or pick one path silently. -Two publishers also share no history, so nothing fetched from one is valid against the other. -Advertising a namespace once per publisher would only push the same choice one hop downstream. +A receiver MAY still hold paths to several publishers of one namespace and choose between them as it sees fit: serve from the cheapest and move to the next when it fails or refuses the request, or try each in cost order until one accepts. +The advertised path and the served source stay the same publisher: a relay that moves to another MUST withdraw its advertisement and advertise the new path ({{updating}}), so the first Hop ID downstream always names the publisher whose Objects flow. +Moving between distinct publishers is a discontinuity: their groups are not one sequence, so a subscriber sees an unrelated Location, and a FETCH that succeeds against one may fail against the other. -A second publisher of a namespace therefore replaces the first rather than joining it ({{selection}}). -Redundant ingest of one content is a deployment concern outside this document. +Redundant publishers of the same content avoid this by sharing a Hop ID ({{hop-ids}}), which makes their paths interchangeable and lets a subscription fail over at a group boundary. +Publishers that do not share one are treated as reusing a name. # Security Considerations {#security} -A Hop ID reveals nothing beyond what its operator encodes in it, and a deployment that considers its identifiers sensitive can use random values or declare 0 ({{zero}}). -Declaring 0 hides an identity from the mesh but not from the peer itself, which MAY assign one and forward it onward ({{assigned}}); an endpoint that needs to stay unlinkable past its first hop cannot get that from this extension. -A HOP_PATH does expose how many hops an advertisement crossed, which hints at the size of a deployment; a relay MAY coalesce its internal hops into one entry, or strip HOP_PATH, before forwarding across a trust boundary. +A Hop ID reveals nothing beyond what its operator encodes in it; a deployment that considers its identifiers sensitive can use random values or declare 0 ({{zero}}). +Declaring 0 hides an identity from the mesh but not from the peer, which MAY assign one and forward it onward ({{assigned}}); an endpoint that must stay unlinkable past its first hop cannot get that from this extension. +A HOP_PATH does reveal how many hops an advertisement crossed, which hints at the size of a deployment; a relay MAY collapse its internal hops into one entry, or strip HOP_PATH, before forwarding across a trust boundary. Because a relay only appends to HOP_PATH, it cannot make a competing path look shorter than it is; the worst it can do is under-report its own upstream portion to win an advisory tie-break. -ROUTE_COST has no such structural protection: it is a single value the sender chooses, so a relay can advertise 0 for content it is not carrying and attract subscriptions it then has to fetch. +ROUTE_COST has no such protection: it is a single value the sender chooses, so a relay can advertise 0 for content it is not carrying and attract subscriptions it then has to fetch. Both cost only a suboptimal path choice, and the latter is self-limiting, since the traffic won this way must then be served. A receiver MUST NOT make security decisions based on Hop IDs, and a deployment spanning a trust boundary SHOULD treat a peer's ROUTE_COST as a hint to clamp or ignore rather than an accounting figure. @@ -301,10 +295,5 @@ The Key-Value-Pair parity is load-bearing: HOP_PATH is odd, so its value is a le ## moq-cluster-01 - Renamed the RELAY_HOPS Setup Option to HOP_ID and moved it to the even key 0x40B54, so its value is a bare varint rather than a length-prefixed one. - A PUBLISH_NAMESPACE is updated with REQUEST_UPDATE on its request stream instead of a repeated PUBLISH_NAMESPACE; HOP_PATH and ROUTE_COST are registered for REQUEST_UPDATE. A NAMESPACE is still re-sent on its stream. -- Stated that a namespace is routed to one publisher: a session advertises it at most once and a second publisher replaces the first. +- A session advertises a namespace at most once and a subscription is served from one source at a time. A receiver chooses among several publishers of one namespace; moving between them is a discontinuity unless they share a Hop ID. - Named the routing protocols whose single per-direction metric RELAY_COST follows. - -# Acknowledgments -{:numbered="false"} - -This document was drafted with the assistance of Claude, an AI assistant by Anthropic. From 1266779dd62040fb33b26bb89a3f87a1f3e0ee80 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 11:02:31 +0200 Subject: [PATCH 10/11] feat(watch): explain why video is paused while the tab is hidden or off-screen (#3721) Co-authored-by: Claude Opus 5 --- .../src/ui/components/hidden-indicator.ts | 39 +++++++++++++++++++ .../ui/components/unsupported-indicator.ts | 4 +- js/watch/src/ui/element.ts | 4 +- js/watch/src/ui/styles/index.css | 2 +- .../{unsupported-indicator.css => notice.css} | 9 +++-- 5 files changed, 50 insertions(+), 8 deletions(-) create mode 100644 js/watch/src/ui/components/hidden-indicator.ts rename js/watch/src/ui/styles/{unsupported-indicator.css => notice.css} (77%) diff --git a/js/watch/src/ui/components/hidden-indicator.ts b/js/watch/src/ui/components/hidden-indicator.ts new file mode 100644 index 00000000000..1cc2a475ce7 --- /dev/null +++ b/js/watch/src/ui/components/hidden-indicator.ts @@ -0,0 +1,39 @@ +import { type Effect, Signal } from "@moq/signals"; +import type MoqWatch from "../../element"; + +/** Explains why video isn't downloading when the `visible` gate holds it back. */ +export function hiddenIndicator(parent: Effect, watch: MoqWatch): HTMLElement { + const container = document.createElement("div"); + container.className = "watch-ui__notice watch-ui__hidden-indicator"; + container.setAttribute("role", "status"); + container.setAttribute("aria-live", "polite"); + + const text = document.createElement("span"); + text.className = "watch-ui__notice-text"; + container.appendChild(text); + + // The renderer folds tab visibility into one boolean, so track it separately to name the cause. + const hidden = new Signal(document.hidden); + parent.event(document, "visibilitychange", () => hidden.set(document.hidden)); + + parent.run((effect) => { + const gated = !effect.get(watch.renderer.out.visible); + const playing = !effect.get(watch.controls.paused); + const video = effect.get(watch.video.source.out.catalog) !== undefined; + const online = effect.get(watch.broadcast.out.status) !== "offline"; + const supported = effect.get(watch.video.source.out.error) !== "unsupported"; + // `never` is a deliberate choice, not a surprise worth explaining. + const chosen = effect.get(watch.controls.visible) === "never"; + const show = gated && playing && video && online && supported && !chosen; + container.style.display = show ? "" : "none"; + if (!show) return; + + if (effect.get(hidden)) { + text.textContent = 'Video paused while the tab is hidden. Set visible="always" to keep downloading.'; + } else { + text.textContent = 'Video paused while off-screen. Set visible="always" to keep downloading.'; + } + }); + + return container; +} diff --git a/js/watch/src/ui/components/unsupported-indicator.ts b/js/watch/src/ui/components/unsupported-indicator.ts index 755acc95741..f90442678db 100644 --- a/js/watch/src/ui/components/unsupported-indicator.ts +++ b/js/watch/src/ui/components/unsupported-indicator.ts @@ -4,12 +4,12 @@ import type MoqWatch from "../../element"; /** Shows why video cannot start when every catalog rendition is unsupported. */ export function unsupportedIndicator(parent: Effect, watch: MoqWatch): HTMLElement { const container = document.createElement("div"); - container.className = "watch-ui__unsupported-indicator"; + container.className = "watch-ui__notice watch-ui__unsupported-indicator"; container.setAttribute("role", "status"); container.setAttribute("aria-live", "polite"); const text = document.createElement("span"); - text.className = "watch-ui__unsupported-text"; + text.className = "watch-ui__notice-text"; container.appendChild(text); parent.run((effect) => { diff --git a/js/watch/src/ui/element.ts b/js/watch/src/ui/element.ts index 4be21c35cf9..ade4148bbe3 100644 --- a/js/watch/src/ui/element.ts +++ b/js/watch/src/ui/element.ts @@ -11,6 +11,7 @@ import type MoqWatch from "../element"; import { bufferingIndicator } from "./components/buffering-indicator"; import { centerPlay } from "./components/center-play"; import { controlBar } from "./components/control-bar"; +import { hiddenIndicator } from "./components/hidden-indicator"; import { offlineIndicator } from "./components/offline-indicator"; import { settingsPanel } from "./components/settings-panel"; import { unsupportedIndicator } from "./components/unsupported-indicator"; @@ -86,13 +87,14 @@ export default class MoqWatchUi extends HTMLElement { // The slotted (canvas/video) sits at the base of the stack. player.appendChild(DOM.create("slot")); - // Center affordances: play prompt + buffering spinner + offline / unsupported-codec notice. + // Center affordances: play prompt + buffering spinner + offline / unsupported-codec / hidden notices. const center = DOM.create("div", { className: "center" }); center.append( centerPlay(effect, watch), bufferingIndicator(effect, watch), offlineIndicator(effect, watch), unsupportedIndicator(effect, watch), + hiddenIndicator(effect, watch), ); // Top scrim keeps the bottom bar legible and hosts ambient gradient. diff --git a/js/watch/src/ui/styles/index.css b/js/watch/src/ui/styles/index.css index c40dd84c5d9..402a9e75a5a 100644 --- a/js/watch/src/ui/styles/index.css +++ b/js/watch/src/ui/styles/index.css @@ -5,4 +5,4 @@ @import "./buffer-control.css"; @import "./buffering-indicator.css"; @import "./offline-indicator.css"; -@import "./unsupported-indicator.css"; +@import "./notice.css"; diff --git a/js/watch/src/ui/styles/unsupported-indicator.css b/js/watch/src/ui/styles/notice.css similarity index 77% rename from js/watch/src/ui/styles/unsupported-indicator.css rename to js/watch/src/ui/styles/notice.css index 7e98bb3d807..4e7887871b2 100644 --- a/js/watch/src/ui/styles/unsupported-indicator.css +++ b/js/watch/src/ui/styles/notice.css @@ -1,4 +1,5 @@ -.watch-ui__unsupported-indicator { +/* A centered text notice explaining why video isn't playing. */ +.watch-ui__notice { position: absolute; top: 50%; left: 50%; @@ -15,7 +16,7 @@ pointer-events: auto; } -.watch-ui__unsupported-text { +.watch-ui__notice-text { font-size: 0.875rem; font-weight: 600; line-height: 1.4; @@ -23,12 +24,12 @@ } @media (max-width: 480px) { - .watch-ui__unsupported-indicator { + .watch-ui__notice { max-width: 90%; padding: 0.625rem 0.875rem; } - .watch-ui__unsupported-text { + .watch-ui__notice-text { font-size: 0.75rem; } } From 523fd01843576c149193f30160e5717944a5fa9c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 11:47:57 +0200 Subject: [PATCH 11/11] docs(quest): point track demand at the m2 #2152 quest and the shipped issues Co-Authored-By: Claude Opus 5 --- quest/m1/libmoq-track-demand.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/m1/libmoq-track-demand.md b/quest/m1/libmoq-track-demand.md index 17f51c39abc..70a90074f93 100644 --- a/quest/m1/libmoq-track-demand.md +++ b/quest/m1/libmoq-track-demand.md @@ -94,6 +94,6 @@ Remove the dynamic-track bullet from #2152 when this lands. ## Related -- [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the wider C ABI catch-up this splits out of -- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - broadcast-level request serving on the C ABI -- [#3000](/quest/m1/3000-track-teardown-on-poll-unused-is-not-atomic-against-a.md) - an unused edge is not terminal; the watcher must keep reporting after it +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the wider C ABI catch-up this splits out of +- [#3190](https://github.com/moq-dev/moq/issues/3190) - broadcast-level request serving on the C ABI, shipped on dev in #3577 +- [#3000](https://github.com/moq-dev/moq/issues/3000) - an unused edge is not terminal; the watcher must keep reporting after it (fixed on dev in #3455)