diff --git a/quest/m1/README.md b/quest/m1/README.md index 2b69a4c812a..068a621d6b0 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -15,7 +15,7 @@ before the cut, not only breaking work, so ready non-breaking quests stay here instead of moving out; the cut is what ships them. - Preserve epoch correctness, routing recovery, outbound federation, and - announcement takeover on both lite and IETF. Catalogs, long-lived readers, + claim continuity on lite-07. Catalogs, long-lived readers, and late joiners obey the same identity contract. - Keep IETF passthrough, the API audit, the broad clock conversion, archive replay/DVR correctness, and the TS fidelity @@ -133,7 +133,7 @@ removed). - [Lite-05/06 timestamps pass through](/quest/m1/lite-timestamps-through.md) - a timed track received over lite-05/06 stays timed and is forwarded with its timestamps over every version - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [A broadcast stamps everything from one clock](/quest/m1/broadcast-clock.md) - catalog, MSF, and HLS record groups are stamped from the broadcast's clock, never the ambient one -- [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire +- [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, replacing the ANNOUNCE_TAKEOVER predecessor design - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [A tightened SUBSCRIBE keeps the start's budget honest](/quest/m1/start-budget-update.md) - a relay copy records the delay its start was resolved under, so a SUBSCRIBE_UPDATE tightening cannot make later readers skip fillable history diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index e7833db3104..fcee6f58a0c 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -1,61 +1,132 @@ -# [M] Announcements take over a claim's existing instances +# [XL] A job's exact route continues its claim's readers ## Goal -A worker advertises an epochless prefix to accept lazy work, then announces -an independent, more-specific route with a unique job epoch without resetting -readers already served by that same job. A different worker or replacement -job never inherits those readers. Rust and JS expose the transition as -`Takeover`, distinct from `Restart`. +A worker advertises a prefix route to accept lazy work. When a request +starts a job, the job's exact route carries the prefix route's identity, so +a reader first served through the claim continues on the exact route with +no cold-start reset, across relays, on lite-07. A different worker, or a +restarted job, never continues those readers: each is another identity. +Readers holding `follow` or `request` simply continue, and see a new +broadcast only when the identity changes. Rust and JS players keep playing +through a claim. + +The ANNOUNCE_TAKEOVER work that landed in +[moq-dev/moq#6994](https://github.com/moq-dev/moq/pull/6994) is removed: the +lite-07 ANNOUNCE_TAKEOVER message (0x5), the origin, front and relay +handling of predecessors, the `Takeover { announce, predecessor }` event, the +predecessor fields in moq-ffi and the C ABI, and the takeover text in the +lite draft and the concept docs. No wire message or public event replaces it. + +Non-goals: moq-transport, which keeps the cold-start reset +([moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md), and an +edge mints a new identity for each announcement, +[Identity and epoch](/quest/m1/api-audit/route/identity.md)). ## Plan -Rust, the lite-07 wire (ANNOUNCE_TAKEOVER, 0x5), the lite draft, the concept -docs, and the FFI bindings landed in -[moq-dev/moq#6994](https://github.com/moq-dev/moq/pull/6994): the origin -records which incarnation a route continues at install, fronts and session -selections follow each takeover as it lands (so a chain of them too), -cursors deliver `Takeover` only where every route they saw at the -predecessor's prefix serves that incarnation, and relays forward it on that -same condition, falling back to Start or Restart. The identity guide -describes it. -Keep the rest in m1 as a prerequisite of the lite-07 cut. moq-transport gets -no counterpart, since [moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md) -(decided 2026-10-28), so a moq-transport hop uses Start/Restart. - -Decided 2026-10-29 (maintainer, settling #6994): the event stays -`Takeover { announce, predecessor }`, with `predecessor == announce.prefix` -in place; the C ABI's `moq_announce_event` carries the predecessor fields -rather than gaining an accessor; and a reader whose cursor saw a takeover -withdrawn before delivery gets the claim's later answers as Start/Restart. -A chain of in-place takeovers landing before a reader looks again is fixed -in that PR, without keeping history of retired routes. -JS continuity and epoch-bound requests through an adopted source moved here. - -What remains: - -- JS continuity. `js/net` decodes ANNOUNCE_TAKEOVER and keeps the Announce - IDs in step, but surfaces it as a `start` (or a `restart` at the - predecessor's own prefix), as an older wire would. Add a `takeover` kind - carrying the predecessor's prefix to `announced.Event`, and make the lite - subscriber's `BroadcastCache` re-key a consumer resolved through the - predecessor's current advertisement, beneath the new prefix, under the new - route instead of invalidating it. Handle the kind in - `connection/forward.ts` and any player that follows announcements, so a +Re-planned 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)): +continuity is the identity promise, not an `ANNOUNCE_TAKEOVER` predecessor +ID. An identity is one continuous sequence space at a path, so the exact +route and the claim's answer are the same consumer route, +origin → route(path, identity) → broadcast. The 2026-10-10 plan (TAKEOVER as +START plus a predecessor Announce ID, with per-stream ID translation in +relays) is dropped. Its safety requirements carry over, as follows. + +Decided 2026-10-31 (maintainer, merging main into +[moq-dev/moq#7420](https://github.com/moq-dev/moq/pull/7420)): identity +wins over the predecessor design that landed in +[moq-dev/moq#6994](https://github.com/moq-dev/moq/pull/6994) meanwhile. +Keeping both would give two continuity rules, one by identity and one by +predecessor prefix, that every origin, relay and binding must agree on. The +identity rule already covers the claim case and needs no wire message, so +this quest removes the predecessor machinery and grows to [XL]. + +- **Removing ANNOUNCE_TAKEOVER.** Delete the 0x5 message and its codec in + `rs/moq-net/src/lite/announce.rs`, `compress.rs`, `publisher.rs`, + `subscriber.rs` and `replay.rs`; the predecessor tracking in + `rs/moq-net/src/model/origin.rs` and `front.rs` (the `seen` stamps in + `OriginConsumerState` and `PendingFront::via`); relay forwarding in + `rs/moq-relay`; and `rs/moq-net/tests/integration/announce_takeover.rs`. + Remove the `Takeover` event from Rust (unless + [Listing and follow](/quest/m1/api-audit/route/events.md) has already + removed the event kinds), `TAKEOVER` and the predecessor fields from + `MoqAnnounceEvent` in `rs/moq-ffi/src/origin.rs` and from + `moq_announce_event` in `rs/moq-c/src/api.rs`, and their wrapper and + binding-doc mentions. In `js/net`, drop the ANNOUNCE_TAKEOVER decoding in + `lite/announce.ts` and `lite/subscriber.ts`. Remove the takeover sections + from `drafts/draft-lcurley-moq-lite.md`, `doc/concept/identity.md` and + `doc/concept/moq-lite.md`. +- **Inheriting the identity.** `request.route(options)` from + [One Route handle](/quest/m1/api-audit/route/handle.md) creates the + path's exact route under the prefix route's identity by default, and the + answer it gives the waiting request is that route's broadcast. A job + that serves a held broadcast through [serve](/quest/m1/api-audit/route/serve.md) + never announces an exact route, so it needs none of this. +- **One stream per path and identity.** A claim may answer a path under + its identity only while that stream is live. Once the job's route ends, + the next request for that path gets a fresh identity, because its + sequences restart. A request pinned to the old identity is refused as + ended, never answered with new bytes. This is the old rule "a worker + restarting a job under an unchanged claim cannot relabel the previous + job's cached content", now enforced in the origin. Prove it in the + model, including retained generations and pending answers, before + relying on it. +- **Relays.** An aggregated prefix can be served by several workers, but + each worker has its own identity. A relay can therefore only continue a + reader on routes carrying the identity it resolved, and readers of A + never move to B. A relay that cannot keep the identity, such as an + older-lite hop, mints a new one, so its readers see a new broadcast + rather than a splice. +- **What a continued reader keeps.** Handles, group positions, metadata, + object and negative caches, catalog pins, and outstanding + TRACK/SUBSCRIBE/FETCH requests. Unrelated sibling paths are unchanged. A + continued stream does not renew a composed catalog. +- **JS players.** `js/net`'s lite subscriber continues a consumer resolved + through the claim on the exact route with the same identity instead of + invalidating it, in `BroadcastCache` and `connection/forward.ts`, so a `@moq/watch` reader through a claim keeps playing. -- Epoch-bound requests through an adopted source. A Rust front or selection - that adopts a takeover keeps the epochless upstream SUBSCRIBE it already - sent; a later request naming the new epoch joins it without restamping. - This is accepted for now, since the answering worker is the instance by - construction. Decide whether that join needs the upstream's answer to - confirm the epoch. -- Tests not yet written, with controlled time: a SUBSCRIBE or FETCH pending - at the front between its resolve and the takeover (`PendingFront::via`), - a takeover naming a predecessor already restarted (the `seen` stamps in - `OriginConsumerState`), conflicting epochs, a diamond of - relays, a claim ending before or after its child, and held catalog pins - through a real player rather than route-table checks. +- **Epoch-bound requests through a continued route.** A front or selection + that continues on the exact route keeps the upstream SUBSCRIBE it already + sent under the claim's route; a later request naming the exact route's + epoch joins it without restamping. This is accepted while the answering + worker is the same identity by construction. Decide whether that join + needs the upstream's answer to confirm the epoch. +- **Docs.** Update the lazy-job lifecycle in `doc/concept/identity.md`: + the cold-start step no longer resets on lite-07. Also update the lite + draft's announce section where it mentions claims. + +Tests with controlled time cover: +- the first reader before and after the exact route lands, with no reader + at all, and with two workers at one prefix; +- a job restarting on one worker, and a request pinned to an ended stream; +- pending TRACK/SUBSCRIBE/FETCH at the front between its resolve and the + exact route landing, and late groups across the transition; +- conflicting epochs within one identity; +- independently ending prefix and exact routes (a claim ending before or + after its child), and late snapshots; +- multi-hop and diamond relays, and mixed versions with an older-lite hop; +- held catalog and media pins through a real player rather than route-table + checks, and the composer. + +Remove the cold-start warm-up reads (`claimed` in +`rs/moq-net-tests/tests/integration/restart.rs` and the +`rs/moq-net/tests/integration/drained_claim.rs` helper) for lite-07 and +assert that the first subscription succeeds. Keep them for moq-transport. +Run `just check`, `just test interop --all` and `just drafts check`. + +Public API: breaking; removes `Takeover` and the predecessor fields in every +language. Wire: removes lite-07's ANNOUNCE_TAKEOVER (0x5), adding nothing +beyond [Identity and epoch](/quest/m1/api-audit/route/identity.md)'s fields. + +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity a job's exact route inherits +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.route` creates the exact route under the claim's identity ## Related -- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route layer whose ANNOUNCE_START layout overlaps this one's +- [Listing and follow](/quest/m1/api-audit/route/events.md) - continuity shows up inside `follow`, not as an event +- [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - why a restarted job must never be stitched to its predecessor +- [Retired requests](https://github.com/moq-dev/moq/pull/5294) - replacements never substitute content into held handles +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route layer whose ANNOUNCE_START layout carries the identity diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index bcd70f2f4c8..e09056d35b3 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -74,6 +74,7 @@ Rejected in planning: ## Required - [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone +- [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle that owns its broadcast and carries an `identity`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` - [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - `Rendition`, `Lister`, `Arrivals`, and e2ee's generations get private constructors, and a lint rule stops new ones - [moq-congestion's first-publish names](/quest/m1/api-audit/congestion-names.md) - `bbr3::Config`, `cubic::Config`, `Metrics`, `Factory`, and no `into_any` diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 3b254e2f2a3..87d53d5d5e1 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -13,6 +13,10 @@ Rust, JS, and every binding: - `follow(path, epoch)` follows the path across publisher instances (today's `announced_broadcast`), pinned to `epoch` when given. +[Identity and epoch](/quest/m1/api-audit/route/identity.md) later changes the +pin from `epoch` to an `identity` in both; the two +resolutions stay as they are. + No caller can assemble a racy two-step resolve, and no crate hand-rolls "resolve once discovery synced". @@ -53,6 +57,8 @@ Wire: none. ## Required - [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - `@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` as well as a `Table` +- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - `follow` and `request` get their own JS types, matching Rust and the bindings +- [JS follow takes FollowOptions](/quest/m1/api-audit/resolve/follow-options.md) - `follow` and `request` get their own JS options types ## Related diff --git a/quest/m1/api-audit/resolve/follow-options.md b/quest/m1/api-audit/resolve/follow-options.md new file mode 100644 index 00000000000..6ef60260c0d --- /dev/null +++ b/quest/m1/api-audit/resolve/follow-options.md @@ -0,0 +1,26 @@ +# [S] JS follow takes FollowOptions + +## Goal + +In `@moq/net`, `Origin.Consumer.follow` (and the `Producer` and `Table` +passthroughs) takes its own `FollowOptions`, and `request` keeps +`RequestOptions`. Each options type documents only what its method does. +Every caller in `js/` compiles against the split, and the API report is +regenerated. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up from +[JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md), +which split the return types but kept one `RequestOptions` for both +methods. Keep the shared fields' names. Drop a field from `FollowOptions` +only if `follow` ignores it today, and say which in the PR. If the two +types still end up identical, a shared base with two aliases is fine; the +point is that each method's docs describe one behavior. + +Public API: breaking for TypeScript type annotations that name +`RequestOptions` for a `follow` call. Wire: none. + +## Required + +- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - the `Following` return type this finishes diff --git a/quest/m1/api-audit/resolve/js-following.md b/quest/m1/api-audit/resolve/js-following.md new file mode 100644 index 00000000000..4b02b3cefbc --- /dev/null +++ b/quest/m1/api-audit/resolve/js-following.md @@ -0,0 +1,23 @@ +# [S] JS follow returns a Following + +## Goal + +In `@moq/net`, `Origin.Consumer.follow(path, ...)` returns its own +`Following` type, matching Rust and every binding, and `request` keeps +`Requesting`. Each type documents one meaning. js/watch's annotation +(`js/watch/src/broadcast.ts:284`) and the other callers compile against it. js/watch's cache +entry (`js/watch/src/broadcast.ts:172`) and the local at `:285` hold either +result, so they take a shared read-side type (the common `active`/`closed` +shape) or `Requesting | Following`. + +## Plan + +Found by the 2026-10-30 origin API audit +([route epic](/quest/m1/api-audit/route/README.md)). Today both methods +return `Requesting`, whose docs (`js/net/src/origin.ts:1624-1650`) describe +both behaviors. Keep the `active`/`closed` shape, and rename only where a +member means something different for `follow`. A local helper in +`js/net/src/connection/forward.ts:121` is also named `follow` but +re-receives a route; rename it so it stops reading as `Consumer.follow`. + +Public API: breaking for TypeScript type annotations only. Wire: none. diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md new file mode 100644 index 00000000000..926c5b7d9a1 --- /dev/null +++ b/quest/m1/api-audit/route/README.md @@ -0,0 +1,164 @@ +# Routes are the origin API + +## Goal + +An application talks to the origin only in routes, as the wire does. On the +publishing side, ownership runs origin → route → broadcast → track → group → +frame: a `Route` handle, for an exact path or a prefix, creates and owns +its broadcast. Every route carries an `identity` naming one continuous +stream, and an `epoch` that is private and only orders a single identity's +incarnations. On the read side the chain is origin → route(path, identity) +→ broadcast, and consumers see only the identity. A prefix route answers +each request by serving a broadcast it already holds, or by creating the +path's exact route under its identity. Readers see a listing of paths, plus +`follow` and `request` for identity changes, instead of four announce event +kinds. Rust, JS, moq-ffi, moq-c and the wrappers +mirror it. + +Non-goals: the route layer's wire messages and federation +([Routes and announces](/quest/m1/cluster-routing/routes.md)), lite-07 +takeover ([announce takeover](/quest/m1/announce-takeover.md)), and any +moq-transport identity ([moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md)). + +## Plan + +Planned 2026-10-30 (`/quest-plan`, maintainer). It started from an external +relay operator's question about [moq-dev/moq#6496](https://github.com/moq-dev/moq/pull/6496). +Their relay claims `requests("")`, a separate task publishes the pulled +broadcast at the exact path, and the client's first SUBSCRIBE fails with +Unroutable. A probe over `transport::memory` reproduced this on +moq-transport-18/22, moq-lite-06 and moq-lite-07-wip, whatever the handler +does: prepare and publish, drop, reject, or the crate-private `accept`. It +is the cold-start reset. The downstream's claim-prefix selection is replaced +once the exact route lands (`Selected::change`, +`rs/moq-net/src/model/origin.rs:4255-4299`). The one answer that never +resets is serving a held broadcast with no separate exact route. +The user's "it worked before #6496" did not reproduce on any older tree, +including one before [moq-dev/moq#5678](https://github.com/moq-dev/moq/pull/5678). +Their proposed `accept_published(&Publication)` would not avoid the reset, +so it was dropped. Their relay instead gets [serve](/quest/m1/api-audit/route/serve.md). + +The maintainer then asked for an audit of the origin, claim and epoch API. +Four read-only audits covered the Rust surface, JS and the bindings, the +epoch concept and its history, and moq.pro's usage. Findings that shaped +the decisions: + +- Every production publisher calls `Epoch::mint()` once per publication; + apps choose only when. The CLI already refuses a shared epoch. +- `Route` mixes what an app sets (epoch, cost, auth) with what relays fill + in (hops, via, source). `Route::default()` is epochless, so forgetting + `with_epoch`, or re-pricing with `Route::default().with_cost(..)`, + silently gives up resume. +- `Publication`, `Prepared`, `Announcer` and `Requests` describe one + lifecycle: unannounced, then announced. Claims and prepared answers + cannot carry cost or auth. +- Almost every caller merges `Start`/`Update`/`Restart`. Only moq-boy's + input handles `Restart` alone, and no JS consumer does. +- The worst internals exist for epochless routes, not because of epochs: + `Instance::Route(generation)`, `renew`, the held restart, and Selection + retirement. +- moq.pro needs prefix routes answered on demand. Its `.dash` dashboard + (`rs/dash/src/dashboard.rs`) answers with prepare and publish and works + around the reset in three places. Its sync-ingest mirror + (`rs/edge/src/sync/ingest.rs`) answers with `request.accept(broadcast)` + under a forwarded route. On `main` both calls are crate-private, so the + mirror breaks at its next moq bump. +- The selection order is documented three ways: `doc/concept/identity.md`, + the `Consumer::request` rustdoc, and the `Route.cost` doc. None of them + says that a more specific prefix outranks the epoch. + +Decision prompts (options separated by semicolons; the chosen one is marked ✅, +and every option after it was rejected): + +- Goal for the user's question: add a same-origin resolve; keep the reset; + fold it into takeover. The maintainer instead asked for the API audit. +- Mint the epoch in the library: ✅ yes, per announce; optional only; + leave as is. +- Claims: the maintainer asked what moq.pro needs. ✅ Keep prefix routes + with requests answered dynamically, since moq.pro's `.dash` and mirror + need them. +- Request answers: ✅ announce and serve; serve only; announce only. +- Lifecycle: ✅ one `Route` type for exact and prefix routes; two typed + route kinds. This came from "broadcasts don't actually exist on the + wire; only routes do". +- Where the epoch lives: ✅ on the route, minted at each announce; per + broadcast. A re-announce after js/publish's toggle is a restart, never a + splice. +- Announce events: ✅ shrink them, with continuity in `follow`; keep four + plus `Takeover`; keep four without it. +- Prefix routes get an instance like any route: ✅ yes, so a crashed + `.dash` that comes back up wins with its newer epoch. +- Explicit instance override for forwarders (mirror, archive resume, FFI): + ✅ yes; crate-private only. +- Pool tie-break: ✅ keep the per-path hash; newest first; out of scope. + The maintainer then reframed pools and restarts as identity. Routes with + one identity are runs of one publisher; different identities are + interchangeable and spread by hash. +- Naming: ✅ `identity` (a string, possibly a public key later) and `epoch` + (start time), paired as ✅ `Instance`. "group" is taken, and the UUIDv7 + epoch is retired. +- Wire: ✅ two explicit fields; packed into the UUIDv7. +- Epochless off the wire: ✅ the receiving hop mints one; keep it + wire-only. +- Run uniqueness: ✅ start time only. Pool hosts each use their own + identity, such as a hostname, so no two hosts share one. +- Ranking: ✅ newest-wins only within an identity, cost before the hash; + hash before cost. +- Default identity: ✅ random per process; hostname (it would leak machine + names across a CDN). +- Identity an edge mints: ✅ the session ID; auth subject, else session. +- Epochless machinery: ✅ [identity](/quest/m1/api-audit/route/identity.md) + deletes it; leave it to routes.md. +- Milestone: ✅ m1 under the API audit; m1 standalone; m2. +- The external user's PR offer: ✅ we do all of it; offer them serve. + +Second round, the same day. The maintainer asked whether broadcasts should +hang off routes (origin → route → broadcast → track → group → frame). An +audit found the producer side inverted today: the broadcast holds its own +announcer (`rs/moq-net/src/model/broadcast.rs:252-292`). A standalone +broadcast cannot be announced in Rust. A consumer's broadcast, by contrast, +moves between the routes that reach it (`origin.rs:6730`). These decisions +supersede the epoch-minting, pairing and run-uniqueness answers above: + +- Producer ownership: ✅ the route creates and owns its broadcast; pass a + broadcast in. +- Mint point: ✅ per Route, which keeps its identity across withdraw and + re-announce, so js/publish's toggle continues; per announce. +- Read side: ✅ origin → route(path, identity) → broadcast, with only the + identity public; the instance on the consumer; a consumer route handle. + The maintainer added: "we can never stitch broadcasts over two different + identities, only different epochs". The epoch is only a restart + tie-break, relative to its identity, and need not be a clock. moq.pro + records start times itself. +- Epoch change under a reader: the maintainer answered "that would be a + new identity?". So identity is one continuous sequence space, and a + publisher whose sequences restart is a new identity. ✅ Confirmed: the + default is a fresh identity per stream, and a stable identity promises + continued sequences and an increasing epoch. `Instance` and the + hostname advice for pools are dropped. +- Edge minting: ✅ per announcement (the session ID plus the announcement's + ID); per session, which would splice a job restarted on one session. +- Takeover: ✅ re-plan it around identity, where a job's exact route + inherits its claim's identity and ANNOUNCE_TAKEOVER is dropped; keep the + predecessor-ID plan. + The predecessor design then landed on main in + [moq-dev/moq#6994](https://github.com/moq-dev/moq/pull/6994). On + 2026-10-31 the maintainer kept identity: [announce takeover](/quest/m1/announce-takeover.md) + now also removes that work, so only one continuity rule remains. + +The epic owns no work of its own: each child updates the docs it makes +stale, including `doc/concept/identity.md`. + +## Required + +- [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - a prefix route's request can be answered with a broadcast the app already holds, and the first subscribe succeeds on every wire +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - every route carries an `identity` (one continuous stream) and a private per-identity epoch, ranked newest within an identity and hashed across identities, with no epochless routes left in the origin +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route` that owns its broadcast, with app options separate from transit facts +- [Identities are percent-encoded in paths](/quest/m1/api-audit/route/identity-encoding.md) - HLS URLs and archive keys round-trip any stable identity +- [Listing and follow](/quest/m1/api-audit/route/events.md) - apps read a path listing plus `follow`/`request`, and route metadata moves to a relay-level stream + +## Related + +- [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, so lite-07 readers keep the first subscribe +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the wire route layer; identity takes over its epochless deletion +- [Grant subject](/quest/m1/cluster-routing/grant-subject.md) - key identities that a future public-key `identity` could reuse diff --git a/quest/m1/api-audit/route/events.md b/quest/m1/api-audit/route/events.md new file mode 100644 index 00000000000..98374c6d62a --- /dev/null +++ b/quest/m1/api-audit/route/events.md @@ -0,0 +1,54 @@ +# [M] Listing and follow + +## Goal + +Applications read announcements as a listing: each path is present or +absent. Instance changes, whether a restart or a takeover, are handled +inside `follow` and `request`, not seen as announce events. The `Start`, +`Update`, `End`, `Restart` and `Takeover` variants leave the app API in +Rust, JS, moq-ffi, moq-c and the wrappers. Route metadata changes (cost, hops, +preference) move to a relay-level `routes()` stream that moq-relay and +stats use. + +Non-goals: the wire's ANNOUNCE and ANNOUNCE_RESTART messages, which stay as +they are, and the route handle ([One Route handle](/quest/m1/api-audit/route/handle.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +The audit found that almost every production caller merges the variants, +for example `rs/moq-relay/src/internal.rs:933`, `rs/moq-rtc/src/lib.rs:81` +and `rs/moq-cli/src/archive.rs:85`. Every JS consumer branches only on +`end`. Only `rs/moq-boy/src/input.rs:79` handles `Restart` alone, and it +moves to `follow`. + +- The listing yields present and absent per path, with the announcement's + read-only facts. A path that changes identity stays present. To see an + identity change, hold a `follow`. +- `follow` yields a new broadcast when the path's identity changes, as the + read side of [Identity and epoch](/quest/m1/api-audit/route/identity.md) + defines (an epoch change within one identity is invisible). It also needs an `End` + signal for when the path goes absent, so that `moq_mux::follow::Instances` + can fold into it: delete the wrapper's duplicate epoch filter and keep + its one-shot fixed mode only if a caller needs it. +- `routes()` lives on the origin consumer for relays and stats, and is + hidden from the app-level docs. +- Format the go and python interop clients while touching them (two lines + were already unformatted on 2026-10-30). +- `Takeover` (landed in [moq-dev/moq#6994](https://github.com/moq-dev/moq/pull/6994)) + goes with the rest, along with its predecessor fields in + `MoqAnnounceEvent` and `moq_announce_event`, unless + [announce takeover](/quest/m1/announce-takeover.md) has already removed it. +- Bindings: replace `MoqAnnounceEvent`'s variants, and the go and python + interop clients' and carla `publish.py:303-340`'s Restart handling, with + the listing plus `follow`. +- Update `doc/concept/identity.md`'s follower section and the binding docs. + +Run `just check` and `just test interop --all`. + +Public API: breaking across the announce stream in every language. Wire: +none. + +## Related + +- [Announce takeover](/quest/m1/announce-takeover.md) - a job's exact route continues its claim's readers inside `follow`, with no public event diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md new file mode 100644 index 00000000000..8f3fc272d48 --- /dev/null +++ b/quest/m1/api-audit/route/handle.md @@ -0,0 +1,117 @@ +# [XL] One Route handle + +## Goal + +On the publishing side, ownership runs origin → route → broadcast → track → +group → frame. An application creates a `Route` on the origin, and the +route creates and owns its broadcast. `Publication`, `Prepared`, +`Announcer`, `Requests` and `Producer::publish` are gone, in Rust, JS, +moq-ffi, moq-c and the wrappers: + +```rust +// An exact route owns one broadcast; dropping the route withdraws it. +let route = origin.route("live/alice", Options::hidden())?; +route.broadcast().create_track("catalog", info)?; +route.announce(); // visible now, same identity +route.set_cost(5); // re-prices in place +route.withdraw(); // hidden; announce() again continues the same stream + +// A prefix route serves requests. +let claim = origin.route_prefix("transcode", Options::default())?; +while let Some(request) = claim.requested().await { + // Either serve a broadcast already held, under the claim's identity... + // request.serve(held); + // ...or create the path's own exact route. + let job = request.route(Options::default())?; + spawn(run(job)); +} +``` + +A `Route` mints its identity when it is created and keeps it for its +lifetime, across withdraw, re-announce and reconnects, because it owns the +same broadcast and its sequences continue. A new run is a new `Route`. Apps +pass only options: visibility at creation, `cost`, `auth`, and a stable +`identity` for a publisher that keeps its sequence space across restarts +(see [Identity and epoch](/quest/m1/api-audit/route/identity.md)). Setting +an identity grants no more than a minted one does: publishing still +requires the path's grant. A route exposes its own identity (`route.identity()`), so the OBS dock can +show it again. Hops, via, source and the anonymous mark become +read-only facts on a received announcement, and `Hop`, `Hops` and +`HopLimit` leave the public API. + +Non-goals: the identity model ([Identity and epoch](/quest/m1/api-audit/route/identity.md)), +announce events ([Listing and follow](/quest/m1/api-audit/route/events.md)), +the read side, which identity owns, and the route layer's wire metric +([Routes and announces](/quest/m1/cluster-routing/routes.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +The names above are a sketch. Settle the final ones in the PR, keeping Rust, +JS and the bindings identical. + +- **The route owns the broadcast.** `route.broadcast()` returns the + `broadcast::Producer` that the 18 library entry points already take + (`moq-mux` catalog and importers, `moq-hls` import, the `moq-rtc` codecs, + `moq-room` chat, `moq-boy` status). Today the broadcast holds its own + announcer (`rs/moq-net/src/model/broadcast.rs:252-292`, and + `js/net/src/broadcast.ts:391`). That inversion goes: the broadcast knows + nothing of routes, and `broadcast::Producer::announce`/`unannounce`/ + `route` are removed. A standalone `broadcast::Producer` stays for + in-process pipelines and tests. It can only be published through a + prefix route's `serve`, as today, where a standalone broadcast cannot be + announced. +- **Prefix routes.** A prefix route yields requests, and each one is + answered by `serve(consumer)` (from [serve](/quest/m1/api-audit/route/serve.md)), + by `route(options)`, or by `reject`. `route(options)` creates the path's + exact `Route`, which inherits the prefix route's identity by default so + that the reader continues (see [announce takeover](/quest/m1/announce-takeover.md)). + A prefix route takes cost and auth as an exact one does, so claims can + be priced. Today `Requests::route()` is always the default and + `update_route` is crate-private. +- **Visibility, not unannounced broadcasts.** Callers that fill the catalog + first (`moq-cli` hls, rtsp and publish; moq-studio; moq-mux + `ts/programs.rs`) or announce after SDP (`moq-rtc/server/whip.rs`) create + the route hidden and announce it when ready. js/publish's on/off toggle + becomes withdraw and announce on one route, so viewers continue rather + than restart. +- **Sessions.** Relay forwarding keeps a crate-private construction with + forwarded identity, epoch, hops and cost, which the deleted + `requests_route` and `dynamic_route` did. `moq_net::fuzz`'s hatches + shrink to what tests still need. +- **JS leaks.** Removing `Requests`/`requestsRoute`/`updateRoute` also + removes their `@internal`-but-public exposure on `Table`. Stop exporting + `Epoch.toBytes`/`fromBytes`, `RequestSlot` and `RouteEntry`, and delete + the orphaned `@internal` doc blocks (`js/net/src/origin.ts:2160-2176`). +- **Bindings.** These all move to the route handle: + - moq-ffi's `MoqRoute`, `MoqPublication`, `MoqBroadcastRequest` and + `MoqBroadcastPrepared`. + - moq-c's `moq_origin_requests`, `moq_broadcast_request_*`, + `moq_broadcast_prepared_*`, `moq_publication_*` and `moq_mint_epoch`. + - The py, kt, swift, dart and go wrappers. + + [moq-c's API gaps](/quest/m1/c/api-gaps.md) error-code fix applies to + whichever functions remain. +- **Callers.** Migrate every caller: about 25 crates use `create_broadcast` + or `publish`, about 19 set an epoch, plus `@moq/publish`, moq-boy, carla + and the e2ee generations. The rs/moq-net and js/net `MIGRATE.md` entries + and the PR's Impact section give the mapping, including moq.pro's + `.dash` claim and sync-ingest mirror. +- **Docs.** Update `doc/concept/identity.md`'s publishing and lazy-job + examples, `doc/lib/rs`, `doc/lib/js`, `doc/lib/c`, and each binding's + README. + +Run `just check` and `just test interop --all`. + +Public API: breaking across moq-net, @moq/net, moq-ffi, moq-c and the +wrappers. Wire: none. + +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity a route mints and keeps +- [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - the served answer this handle carries over + +## Related + +- [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - also retypes JS `Table` +- [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - the same JS hygiene rule diff --git a/quest/m1/api-audit/route/identity-encoding.md b/quest/m1/api-audit/route/identity-encoding.md new file mode 100644 index 00000000000..966c58e44cb --- /dev/null +++ b/quest/m1/api-audit/route/identity-encoding.md @@ -0,0 +1,27 @@ +# [XS] Identities are percent-encoded in paths + +## Goal + +Wherever an identity becomes a URL or storage path segment (moq-hls's HLS +URLs and the archive's recording keys, `/@`), it is +percent-encoded as one segment and decoded on the way back. A stable +identity containing `/`, `?`, `%` or `#` round-trips, and one test per +surface proves it. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up reported by the +[Identity and epoch](/quest/m1/api-audit/route/identity.md) implementation. +Minted identities (`~` plus random bits) are URL-safe, so only a stable +identity set by a publisher can break these paths today. Reuse the +percent-encoding the archive already applies to track names (see +[archives](/quest/m1/archive/README.md)) rather than adding a second +scheme. List any other surface that embeds an identity, found with +`git grep`, in the PR. + +Public API: none. Wire: none. Existing keys stay readable, since minted +identities encode to themselves. + +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity these paths embed diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md new file mode 100644 index 00000000000..4563cd9974b --- /dev/null +++ b/quest/m1/api-audit/route/identity.md @@ -0,0 +1,122 @@ +# [XL] Identity and epoch + +## Goal + +Every route in an origin carries an `identity`, a string naming one +continuous stream at its path. Within an identity, group sequences never +restart and never name two different groups, so readers can stitch across +any routes and incarnations that share it. Different identities are +independent streams that are never stitched together. Each route also +carries an `epoch`: an opaque counter that increases within its identity +and is never compared across identities. It only picks the live +incarnation when stale routes linger. The UUIDv7 `Epoch` is retired, and +the origin holds no route without an identity. + +A route resolving a path is chosen like this: + +1. The most specific prefix wins. +2. Within one identity, only its highest epoch is eligible, even over a + cheaper route. Readers continue across an epoch change without a seam, + because the sequence space continues. +3. Among different identities, the order is link preference, then cost, + then a broadcast published on this origin, then hop length, then a hash + of the identity and the full requested path. Relays agree on the result, + and paths spread over a pool's hosts. + +On the read side, the chain is origin → route(path, identity) → broadcast. +`request(path)` resolves one identity and returns its broadcast. Moving to +another identity, such as a pool failover or a redundant-ingest switch, +ends that broadcast, and `follow` yields the next one. Consumers, pins and +catalog references see only the identity; the epoch is never public. + +Non-goals: carrying identity over moq-transport (it carries none, +[decided 2026-10-28](/quest/m1/ietf-epoch-cut.md)), public-key identities +(a later option), and the route-handle API shape +([One Route handle](/quest/m1/api-audit/route/handle.md)). + +## Plan + +Decided 2026-10-30 (maintainer); every prompt is in the +[epic](/quest/m1/api-audit/route/README.md). + +- **Types.** In `rs/moq-net`, add `Identity` (a string) and keep `epoch` as + a crate-private `u64` on routes. Replace `broadcast::Info.epoch` and JS + `Broadcast.Consumer.epoch` with `identity()`. `request(path, identity)`, + `follow(path, identity)`, catalog references and archive keys pin an + identity. Rename the internal `Instance`/`Resolution` types if they + confuse. Mirror this in `js/net`, moq-ffi, moq-c and the wrappers. + Rename tests and variables that still say `epoch` where they mean the + identity. +- **Default identity.** Random, minted for each new stream, so a publisher + that restarts its sequences can never be stitched to its old run. A + [Route](/quest/m1/api-audit/route/handle.md) mints it when created and + keeps it, with epoch 0, while it is withdrawn and re-announced or + reconnects, since its sequences continue. +- **Stable identity.** A publisher may set its own identity (`--identity` + on the CLI, an option on the route) only if it continues the sequence + space across restarts and announces a higher epoch each time, for + example a counter persisted on disk. Nothing assumes the epoch is a + clock. Document the promise and the cost of breaking it (spliced groups) + wherever the option is documented. This publisher identity is not + [Routes and announces](/quest/m1/cluster-routing/routes.md)'s origin-node + identity, whose seqno and revision are route-layer state. A restarted + relay node still takes a fresh node identity there. +- **Pools.** Several hosts on one prefix, such as transcoders or moq.pro's + three `.dash` control nodes, each have their own identities, and step 3 + spreads paths over them. A host that is full withdraws its route (a + leaky bucket); a crashed host's route goes when its session closes or + drains. Document this in `doc/concept/identity.md`, replacing the + epochless-claim lifecycle. +- **Wire, lite-07-wip.** Announcements carry `identity` and `epoch` as two + explicit fields in place of the UUIDv7 epoch, and requests that pin carry + the identity. Update `drafts/` (the lite draft's announce and epoch + sections) and `doc/concept/moq-lite.md`. Released versions keep their + framing. Account for the change wherever lite-07 epochs flow today: + announce IDs, compression bases, snapshots and route filtering. +- **Minting off the wire.** A session mints an identity for each route it + receives without one: the session ID plus that announcement's ID, with + epoch 0. This covers moq-transport, older lite and third-party peers, and + the origin then holds no route without an identity. A re-announcement is + a new identity, so a job restarting on the same session is never spliced + to its predecessor ([moq-dev/moq#5678](https://github.com/moq-dev/moq/pull/5678)'s + bug). moq-transport keeps the cold-start reset. A pool reached through an + older-lite relay hop can pick different winners per relay + ([moq-dev/moq#6948](https://github.com/moq-dev/moq/pull/6948)'s + objection), which is accepted because m1 prefers lite-07 between relays. + Elsewhere the objection is gone: epochs are compared only within one + identity, so mint order never outranks cost or preference. +- **Delete the epochless machinery.** That is `Instance::Route(generation)` + and its renewals, `restarted_since`, the held-restart Release for + epochless routes, Selection retirement, and the epochless refusal from + [moq-dev/moq#6816](https://github.com/moq-dev/moq/pull/6816). This + replaces that part of [Routes and announces](/quest/m1/cluster-routing/routes.md) + (decided there 2026-10-27). +- **Docs.** Rewrite `doc/concept/identity.md`'s identity, selection-order + and lazy-job sections to the rule above, so the guide, the + `Consumer::request` rustdoc and the route docs give one order, with + specificity first. Update `doc/setup/redundancy.md` (a redundant pair is + two identities), `doc/bin/cli.md` ("Publisher runs", and `--epoch`, which + becomes `--identity`) and `doc/bin/relay/config.md`. +- **moq.pro.** Recording resume compares `routeEpoch` + (`api/src/recording.ts`). Recordings are currently keyed + `/@/...`; the target key is `(path, identity)`, since an + epoch only orders one identity's runs. The Impact section says to key on + identity and record the start time on moq.pro's side, for moq.pro's bump. +- **Tests.** Cover a higher epoch superseding a cheaper stale route of the + same identity; a reader continuing across an epoch change; two identities + hashing per path; a failover to another identity ending the broadcast and + `follow` yielding the next; a host withdrawing when full; per-announcement + minting at a moq-transport and a lite-06 ingest, including a job + re-announced on one session; and archive and catalog pins. Update every + epoch fixture. Run `just check`, `just test interop --all` and + `just drafts check`. Any compat cell that asserted UUID epochs gets a + planned break in `test/interop/compat/planned-breaks.json`. + +Public API: breaking. `Epoch` leaves the public API and `Identity` takes its +place in pins and on consumers. Wire: lite-07-wip announce and request +fields change; released versions are unchanged. + +## Related + +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - its ANNOUNCE_START layout overlaps; whichever lands second rebases +- [Grant subject](/quest/m1/cluster-routing/grant-subject.md) - a later public-key `identity` could reuse its key identities diff --git a/quest/m1/api-audit/route/serve.md b/quest/m1/api-audit/route/serve.md new file mode 100644 index 00000000000..2f00e95cce1 --- /dev/null +++ b/quest/m1/api-audit/route/serve.md @@ -0,0 +1,54 @@ +# [M] Serve a held broadcast + +## Goal + +An application answering a prefix route's request can hand over a broadcast +it already holds: `request.serve(consumer)` in Rust and +`request.serve(broadcast)` in JS, mirrored in moq-ffi, moq-c and the +wrappers. The answer is served under the prefix route's own identity and +announces no exact route. A client's first subscribe through it succeeds +over moq-transport-18, moq-transport-22, moq-lite-06 and moq-lite-07-wip. + +Non-goals: the route handle rename ([One Route handle](/quest/m1/api-audit/route/handle.md) +carries `serve` over), and removing the reset for answers that announce a +per-path route ([announce takeover](/quest/m1/announce-takeover.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +This lands first, on today's `origin::Requests`/`Request`, so moq.pro's +sync-ingest mirror (`rs/edge/src/sync/ingest.rs`, which calls +`request.accept`) and the external relay operator have a supported answer +before the larger rework. + +- Make the crate-private `Request::accept` (`rs/moq-net/src/model/origin.rs`) + public as `serve`, for application claims as well as sessions. Replace the + `compile_fail,E0624` doctest with usage docs. In JS, expose `#accept` as + `serve` and drop `hooks.acceptRequest` if nothing else needs it. +- Contract, in rustdoc and `doc/concept/identity.md`: a served answer is + part of the prefix route's stream at that path. Today that means its + instance; after [Identity and epoch](/quest/m1/api-audit/route/identity.md), + its identity, which promises one continuous sequence space per path. To + serve different bytes at a path that was already served, start a new + prefix route rather than serving new bytes under the old one. A job that + may restart per path answers with `prepare`/`publish`, and takes the + cold-start reset until [announce takeover](/quest/m1/announce-takeover.md). +- Served-answer cache: an answer that `prepare`/`publish` stored in the + prefix route's served cache must not serve a later request once its + exact route is withdrawn. Check `ServeState`'s cache on withdrawal, fix + it if the answer survives, and test it. +- Tests: turn the reproduction from planning into an integration test in + `rs/moq-net-tests/tests/integration/`. A server origin `requests("")` + linked over `transport::memory`; the handler serves a held broadcast; the + client's first `request` plus `subscribe` reads a frame on every version + above. Keep the prepare/publish case asserting today's reset, so + takeover's change to it is visible. Mirror it in `js/net`. +- `MIGRATE.md` (rs/moq-net, js/net): mention `serve` beside the existing + #6496 entry. It is additive. + +Public API: additive `Request::serve` in Rust, JS and the bindings. Wire: +none. + +## Related + +- [moq-dev/moq#6496](https://github.com/moq-dev/moq/pull/6496) - made `accept` crate-private; this reopens it under a stated contract diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 5d1fe8e82aa..5dfbec234d1 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -35,7 +35,8 @@ The handoff contract below, decided 2026-10-16, settles claim freshness: permission to stitch. A concrete serving-route change without an epoch remains Restart even when the origin node is unchanged; only a matching explicit epoch or the separately proven Takeover operation preserves an - instance. Test a same-origin next-hop change with no epoch. + instance (superseded 2026-10-30: a shared `identity` preserves it, per + [Identity and epoch](/quest/m1/api-audit/route/identity.md)). Test a same-origin next-hop change with no epoch. ANNOUNCE_UPDATE re-prices it and ANNOUNCE_END withdraws this origin's claim while the route stays up. A wildcard claim is capability, not an inventory of broadcasts; another origin may still serve the same epoch. An announce @@ -239,8 +240,9 @@ The handoff contract below, decided 2026-10-16, settles claim freshness: - Claim freshness follows the handoff contract below, independently of the requested path's forwarding choice. - Only the first hop selects the origin. It keeps `route_order`'s shape over - the origin nodes announcing the path: longest prefix, newest epoch, the - link's priority (`origin::Producer::with_preference`), seed plus route + the origin nodes announcing the path: longest prefix, newest epoch (within + one identity only, per [Identity and epoch](/quest/m1/api-audit/route/identity.md), + decided 2026-10-30), the link's priority (`origin::Producer::with_preference`), seed plus route metric, then a rendezvous hash of the path and the identity, and the newest connection only for an otherwise identical route. The hash drops the hop chain, which differs per node, so every node agrees on a pool member @@ -669,6 +671,18 @@ mints at its own time, so mint order outranks cost, preference, and the local-broadcast tie and relays disagree on a pool path's winner, while ranking a minted epoch last keeps the renewal it was meant to delete. +Moved 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)): +[Identity and epoch](/quest/m1/api-audit/route/identity.md) now deletes that +epochless machinery, so this quest no longer does. A session mints +an `identity` (the session ID plus the announcement's ID) for any route that +arrives without one, and newest-wins compares epochs only within one +identity, so mint order no longer outranks cost or preference. The rest of +the 2026-10-27 decision stands. The broadcast epoch fields here become that +publisher identity and its per-identity epoch, in place of the UUIDv7 +epoch. The route layer's own origin-node identity, with its seqno and +revision, stays separate ("keep administrative identity and broadcast epoch +separate", above). + Decided 2026-10-27 (maintainer), from [grant subject](https://github.com/moq-dev/moq/pull/6992): decide what key identities are filed under for sessions allowed to publish part of the tree diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index fc38dc57e9f..0605a128f7e 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -113,7 +113,7 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) - lite FETCH is gone from lite-07, in Rust and JS - [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m1/time-addressing/js.md) - JS speaks the same lite-07 wire -- [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route +- [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - the job's route inherits the claim's identity, with no new wire message - [Lite-07 padding datagram](/quest/m1/lite07-padding-datagram.md) - lite-07 defines a padding datagram that receivers discard, for the browser padding probes ## Related diff --git a/quest/m2/README.md b/quest/m2/README.md index 8fe46b3e7f8..42d30ad2bc9 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -92,6 +92,7 @@ lite-07; bitrate enforcement is not part of this release. - [Front parking](/quest/m2/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [Route wakes](/quest/m2/route-wakes.md) - a route change wakes only the fronts it can move, so pool churn stops scaling with served paths - [Fewer allocations in announce fan-out](/quest/m2/announce-fanout-allocs.md) - a deep path costs no more allocations per subscriber than a shallow one +- [moq-room scales to large rooms](/quest/m2/room-bench.md) - a benchmark measures `Room` with large participant counts, and polling narrows only if it shows a slope - [Route health](/quest/m2/route-health/README.md) - epoch-only active/passive track recovery over metadata-only subscriptions - [Wrapper traits over moq-net](/quest/m2/net-wrap/README.md) - moq-net exports producer and consumer traits, and every writer and reader above it takes them, so a wrapper such as e2ee passes through unchanged - [E2EE](/quest/m2/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt diff --git a/quest/m2/room-bench.md b/quest/m2/room-bench.md new file mode 100644 index 00000000000..13e7f1f87cd --- /dev/null +++ b/quest/m2/room-bench.md @@ -0,0 +1,27 @@ +# [S] moq-room scales to large rooms + +## Goal + +A benchmark measures `moq-room`'s `Room` with large participant counts +(for example 10, 100 and 1,000 followed paths), covering the cost of one +participant's change and of steady-state wakes. If the cost grows with room +size per wake, the room polls only the followers a wake concerns, and the +benchmark shows the change. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up to the +required [Listing and follow](/quest/m1/api-audit/route/events.md) +implementation, after which `Room` will hold a follower per listed path and +poll every follower on each wake. That should be fine at room sizes seen +today. Benchmark first, as +[moq-dev/moq#7340](https://github.com/moq-dev/moq/pull/7340) did for the +lite subscriber's prefixes, and fix +only if it shows a slope. Wire the benchmark into the existing bench lanes +([Benchmark sources](/quest/m2/bench-sources.md)). + +Public API: none. Wire: none. + +## Required + +- [Listing and follow](/quest/m1/api-audit/route/events.md) - the follower-per-path room this measures