diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index a7fe99980a3..b11ea2ef100 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -16,7 +16,7 @@ The hand-written crate never published as moq-c: a libmoq 0.6 user applies these ### Paths with an empty segment are refused ([#6648](https://github.com/moq-dev/moq/pull/6648)) -`moq_origin_create_broadcast`, `moq_origin_requests`, `moq_origin_announced_broadcast`, and `moq_origin_request` return an error for a path with a leading, trailing, or doubled `/` instead of collapsing it. Pass the canonical path, such as `room/cam`. The generated API refuses the same paths. +`moq_origin_create_broadcast`, `moq_origin_requests`, `moq_origin_follow`, and `moq_origin_request` return an error for a path with a leading, trailing, or doubled `/` instead of collapsing it. Pass the canonical path, such as `room/cam`. The generated API refuses the same paths. ### Session allocator ([#6751](https://github.com/moq-dev/moq/pull/6751)) @@ -59,11 +59,16 @@ With deltas on, the track carries a refresh ratio of 8 and the producer restates Higher is first and 0 is the unset midpoint, so a zeroed `moq_track_info` now uses the default priority rather than the least urgent one. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `moq_origin_follow` replaces `moq_origin_announced_broadcast`, and both resolutions take an instance ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +Rename `moq_origin_announced_broadcast` and `moq_origin_announced_broadcast_cancel` to `moq_origin_follow` and `moq_origin_follow_cancel`. +`moq_origin_request` and `moq_origin_follow` take `instance, instance_len` after `path_len`: pass `NULL, 0` to accept whichever publisher instance serves the path, or an instance to refuse every other. +`moq_origin_request` resolves one publisher instance: it retries as the routes covering the path change, and fails as unroutable only once discovery has synced with no covering route. `moq_origin_follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `moq_origin_announced` or `moq_origin_announced_broadcast`, instead of under its whole scope at connect. -`moq_origin_request` watches nothing, so on a client it fails with a negative code for a path nothing watches, even when the relay announces it. -Resolve the path with `moq_origin_announced_broadcast`, or hold `moq_origin_announced` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `moq_origin_announced`, `moq_origin_request`, or `moq_origin_follow`, instead of under its whole scope at connect. +`moq_origin_request` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `MOQ_CONTAINER_FORMAT_FMP4` unwraps to Legacy (#6250) @@ -151,7 +156,7 @@ if (consumer > 0) { } ``` -### `moq_origin_announced_broadcast` delivers every publisher instance (#5700) +### `moq_origin_follow` delivers every publisher instance (#5700) Its callback gets a new broadcast handle each time another instance takes over the path or the broadcast returns, and its terminal `0` only on cancel. Free each handle with `moq_consume_close` once its successor arrives. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index f4a5f95ab7e..6a1d48f36b9 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -113,11 +113,16 @@ Publish the track with a `refresh` ratio so a joiner gets the value restated in `TrackInfo.priority` defaulted to 127 and now defaults to 0. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `request` and `follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +Rename `requestBroadcast` to `request`, `announcedBroadcast` to `follow`, and `AnnouncedBroadcast` to `Following`. +On `Moq` both take a positional path and a named `instance:`; on `OriginConsumer` they take `path:` and `instance:`. Pass an instance to refuse every other publisher instance. +`request` resolves one publisher instance: it retries as the routes covering the path change, and fails with an unroutable error only once discovery has synced with no covering route. `follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. -`requestBroadcast()` watches nothing, so on a client it fails with an unroutable error for a path nothing watches, even when the relay announces it. -Resolve the path with `announcedBroadcast()`, or hold `announced()` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()`, `request()`, or `follow()`, instead of under its whole scope at connect. +`request()` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `ContainerFormat.fmp4` unwraps to Legacy (#6250) @@ -197,7 +202,7 @@ The connection stats no longer carry a receive estimate. Hold the consumer `Session.recvBandwidth` returns to request PROBE, read it with `rate()` or wait with `rateChanged()`, and `cancel()` it to stop. Replace `stats().estimatedRecvRateBps` with `recvBandwidth()?.rate()`. -### `AnnouncedBroadcast.available()` waits for the next publisher instance (#5700) +### `Following.available()` waits for the next publisher instance (#5700) The first call returns the broadcast serving the path, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index ab7c8e208af..8e41a69fc87 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -107,11 +107,16 @@ Publish the track with a `Refresh` ratio so a joiner gets the value restated in Higher is first and the zero value is the unset midpoint, so a `TrackInfo` that leaves `Priority` zero now gets the default rather than the least urgent priority; drop any `Priority: 127` that asked for the midpoint. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `Request` and `Follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +On `OriginConsumer` and `Client`, `RequestBroadcast(ctx, path)` is `Request(ctx, path, nil)`, `AnnouncedBroadcast(path)` is `Follow(path, nil)`, and `*moq.AnnouncedBroadcast` is `*moq.Following`. +Pass `&instance` instead of `nil` to refuse every other publisher instance. +`Request` resolves one publisher instance: it retries as the routes covering the path change, and fails with an unroutable error only once discovery has synced with no covering route. `Follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `Announced()` or `AnnouncedBroadcast()`, instead of under its whole scope at connect. -`OriginConsumer.RequestBroadcast()` watches nothing, so on a client it fails with an unroutable error for a path nothing watches, even when the relay announces it. -Resolve the path with `AnnouncedBroadcast()`, or hold `Announced()` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `Announced()`, `Request()`, or `Follow()`, instead of under its whole scope at connect. +`OriginConsumer.Request()` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `media.ContainerFormatFmp4` unwraps to Legacy (#6250) @@ -196,7 +201,7 @@ The connection stats no longer carry a receive estimate. Hold the consumer `Session.RecvBandwidth` returns to request PROBE, read it with `Rate()` or wait with `RateChanged(ctx)`, and `Close()` it to stop. It returns `nil` when the version has no PROBE. -### `AnnouncedBroadcast.Available` waits for the next publisher instance (#5700) +### `Following.Available` waits for the next publisher instance (#5700) The first call returns the broadcast serving the path, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now. diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 8dbad0d2958..b06f8a1c1b0 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -204,10 +204,12 @@ const sub = track.subscribe({ maxDelay: Milli(1000) }); `Time.Nano`, `Time.Micro`, `Time.Milli`, and `Time.Second` are gone. Import them from `@moq/clock`, which throws on negative or non-finite values. -### Announced requests follow restarts, and `broadcasts()` is gone +### `follow(path)` replaces `request(path, { announced: true })`, and `broadcasts()` is gone ([#7173](https://github.com/moq-dev/moq/pull/7173), [#7476](https://github.com/moq-dev/moq/pull/7476)) -An unpinned `request(path, { announced: true })` stays open across publisher instances: its `active` moves to each new instance's broadcast and clears between them, instead of ending with `Unroutable`. -Read `active` reactively and close the request when done, or pass `instance` to keep the old single-instance behavior. +`RequestOptions.announced` is removed: replace `request(path, { announced: true })` with `follow(path)`, which returns an `Origin.Following`. +An unpinned `follow(path)` stays open across publisher instances: its `active` moves to each new instance's broadcast and clears between them, instead of ending with `Unroutable`. +Read `active` reactively and close the follower when done, or use `request(path)` to stay on one instance. +A follower needs discovery: a session without it never serves one. `Origin.Producer` and `Origin.Consumer` drop `broadcasts(scope)`; iterate `announced(scope)` instead. ```ts @@ -218,8 +220,9 @@ for await (const event of origin.announced(scope)) { ### Discovery follows what something watches, and `discovery` is gone -A `consume` origin stays empty until a reader watches it with `announced(scope)` or `request(path, { announced: true })`; the session then asks the relay about those prefixes only. -Code that called `request(path)` expecting a route without watching should hold an `announced(scope)` stream. +A `consume` origin stays empty until a reader watches it with `announced(scope)`, `request(path)`, or `follow(path)`; the session then asks the relay about those prefixes only. +`request(path)` owns the discovery of its path until closed, so it finds a broadcast the relay serves with nothing else watching first, and retries as the routes covering the path change. +It fails `Unroutable` once at least one session is attached and every session's discovery has synced without a route for it; with no session attached, such as between reconnects, it waits. Drop any `announced(scope)` stream held only so a request could resolve. The `discovery` option on `connect`, `accept`, and `Connection`, and `Established.discovery`, are removed; passing the option throws a `TypeError`. Drop the option. @@ -234,7 +237,7 @@ A `"restart"` means another publisher instance now serves the prefix: request th Every route carries an `Instance`: non-empty text naming one continuous run of group numbers at its path. Every broadcast mints a random one and keeps it across re-announcing, so most publishers set nothing. A publisher that continues its group sequences across restarts may name a stable one with `announce({ instance, epoch })`, raising `epoch` on each run. -Read `Route.instance` and `Broadcast.Consumer.instance`; pin a request or follow to one with `request(path, { instance })`. +Read `Route.instance` and `Broadcast.Consumer.instance`; pin a request or follower to one with `request(path, { instance })` or `follow(path, { instance })`. ### Publishing never invents a timestamp (#5070) diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index a31250c8ff7..3a0c23d6444 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -2520,6 +2520,38 @@ for (const alpn of [Lite.ALPN_06, Lite.ALPN_07_WIP]) { } } +// As Rust's lazy discovery tests: a request owns its discovery, so nothing watches first. +test.each([Lite.ALPN_05, Lite.ALPN_06, Lite.ALPN_07_WIP])( + "%s: a request on an unwatched path resolves it, or fails Unroutable once the peer syncs", + async (alpn) => { + const pair = createMockTransportPair(alpn); + const serverOrigin = new OriginProducer(); + const clientOrigin = new OriginProducer(); + const [client, server] = await Promise.all([ + connect(url, { transport: pair.client, consume: clientOrigin }), + accept(pair.server, url, { publish: serverOrigin.consume() }), + ]); + const broadcast = publish(serverOrigin, Path.from("room/cam")); + + const reader = clientOrigin.consume(); + const found = reader.request(Path.from("room/cam")); + const missing = reader.request(Path.from("room/missing")); + await until(() => found.active.peek() !== undefined && missing.closed.peek() !== undefined); + expect(found.closed.peek()).toBeUndefined(); + const err = missing.closed.peek(); + expect(err).toBeInstanceOf(StreamError); + expect((err as StreamError).code).toBe(StreamCode.Unroutable); + + found.close(); + missing.close(); + broadcast.close(); + client.abort(); + server.abort(); + serverOrigin.close(); + clientOrigin.close(); + }, +); + test.each([Ietf.ALPN.DRAFT_18])( "%s: closing an announce consumer before the namespace answer ends the peer's stream", async (alpn) => { diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index 9f490a0622d..ebdae50cba2 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -699,6 +699,32 @@ test("a pending request fails Unroutable once its discovery syncs without a rout origin.close(); }); +// Unlike a Rust origin, which answers for its own table at once, a JS origin usually fronts a +// reconnecting connection: no session yet means nothing has synced. +test("a pending request waits for a session before concluding absence", async () => { + const origin = new Producer(); + const wire = wireOf(origin); + const request = origin.request(Path.from("room/missing")); + await settle(); + expect(request.closed.peek()).toBeUndefined(); + + let synced: (() => void) | undefined; + const stop = wire.interests((prefix, wanted) => { + if (wanted) synced = wire.snapshot(prefix); + }); + const detach = wire.attach(true); + await settle(); + expect(request.closed.peek()).toBeUndefined(); + synced?.(); + await settle(); + expect((request.closed.peek() as StreamError).code).toBe(StreamCode.Unroutable); + + request.close(); + stop(); + detach(); + origin.close(); +}); + test("a follower retains a selected handler's explicit unroutable refusal", async () => { const origin = new Producer(); const path = Path.from("room/audio"); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index ce31ad0afba..bd89d1a046b 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -1943,8 +1943,9 @@ export class Consumer implements Reader { * Resolve one publisher instance serving `path`, pinned to `instance` when given. * * The request owns discovery of its path until closed and retries route churn while - * pending. It fails `Unroutable` once every session's discovery has synced without a - * route for it, and can use a session without discovery instead. Once resolved it keeps + * pending. It fails `Unroutable` once at least one session is attached and every + * session's discovery has synced without a route for it, and can use a session without + * discovery instead. With no session attached, such as between reconnects, it waits. Once resolved it keeps * that instance, ending when the instance stops serving. Use {@link follow} to move on * to the next one. */ diff --git a/js/watch/MIGRATE.md b/js/watch/MIGRATE.md index b07cd1e408d..2131df329e4 100644 --- a/js/watch/MIGRATE.md +++ b/js/watch/MIGRATE.md @@ -9,7 +9,7 @@ How to update your code for each breaking change, newest first. Property and built-in UI changes now reflect into attributes. Invalid rendering/catalog modes, URLs, numbers, durations, and version lists throw instead of selecting defaults; remove an attribute to use its default. Catch those property setter errors. A browser reports malformed markup through its normal `error` event, and the element suspends media until those invalid attributes are corrected or removed. A valid property assignment also corrects that attribute. An empty, duplicate, or unsupported `versions` list now throws from the setter instead of failing on `el.connection.error`; check a list up front with `Net.Connection.checkVersions`. `broadcast`, `video`, `audio`, `renderer`, and `sync` are TypeScript `readonly` fields. Configure the existing components through their inputs and `controls` instead of replacing them; use a headless `Player` for a different pipeline. -`announced=false` reflects as `announced="false"`; `captions` and `catalog-format` now reflect too. +`follow=false` reflects as `follow="false"`; `captions` and `catalog-format` now reflect too. ### Muting preserves the selected volume @@ -44,7 +44,7 @@ Read `Sync.out.delay` instead of `Sync.out.jitter`, and the element's `sync.out. Stop passing `probe` to `new Sync(...)`; it was never read. `Sync.now()` returns `Milli | undefined`. `received`, `wait`, and `register` are internal to the built-in decoders, and `epoch` and `skipped` are gone: `wait` now resolves `true` to present the frame or `false` to drop it. -`` no longer observes `reload`, `latency`, `latency-min`, or `jitter`, nor has the `latency`, `latencyMin`, `latencyMax`, or `reload` properties; use `announced`, `delay`, and `buffer` (see 0.5 -> 0.6). +`` no longer observes `reload`, `latency`, `latency-min`, or `jitter`, nor has the `latency`, `latencyMin`, `latencyMax`, or `reload` properties; use `follow`, `delay`, and `buffer` (see 0.5 -> 0.6, where `follow` is still `announced`). ### `Video.Source.out.error` is an `Error` @@ -98,10 +98,12 @@ Rename `Sync.out.maxAge` to `Sync.out.maxDelay`. A rendition the catalog marks `enabled: false` is skipped, even when named. With no video rendition selectable, the picture clears to black. -### `announced` off stays on one publisher +### `announced` is `follow`, and off stays on one publisher ([#7189](https://github.com/moq-dev/moq/pull/7189)) -With `announced` off, the player no longer moves to a later publisher at the same path. -Turn `announced` on to follow restarts. +Rename `announced` to `follow` on `new Watch.Broadcast({...})`, `new Watch.Player({...})`, `broadcast.in`, `player.in`, and `` (``, `el.follow = false`); its default is unchanged. +Passing `announced` throws, and an `announced` attribute suspends the element until it is removed. +With `follow` off, the player no longer moves to a later publisher at the same path. +Turn `follow` on to follow restarts. ## 0.5 -> 0.6 diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 98257b6dad4..192a1d2b2d0 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -104,11 +104,16 @@ Publish the track with a `refresh` ratio so a joiner gets the value restated in `TrackInfo.priority` defaulted to 127 and now defaults to 0. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `request` and `follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +On `OriginConsumer` and `Moq`, rename `requestBroadcast(path)` to `request(path)` and `announcedBroadcast(path)` to `follow(path)`; the `AnnouncedBroadcast` typealias is `Following`. +Both take an optional `instance` to refuse every other publisher instance. +`request` resolves one publisher instance: it retries as the routes covering the path change, and fails with an unroutable error only once discovery has synced with no covering route. `follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. -`requestBroadcast()` watches nothing, so on a client it fails with an unroutable error for a path nothing watches, even when the relay announces it. -Resolve the path with `announcedBroadcast()`, or hold `announced()` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()`, `request()`, or `follow()`, instead of under its whole scope at connect. +`request()` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `ContainerFormat.FMP4` unwraps to Legacy (#6250) @@ -188,7 +193,7 @@ The connection stats no longer carry a receive estimate. Hold the consumer `Session.recvBandwidth` returns to request PROBE, read it with `rate()` or wait with `rateChanged()`, and `cancel()` it to stop. Replace `stats().estimatedRecvRateBps` with `recvBandwidth()?.rate()`. -### `AnnouncedBroadcast.available()` waits for the next publisher instance (#5700) +### `Following.available()` waits for the next publisher instance (#5700) The first call returns the broadcast serving the path, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index aad98da3ea3..44e86fec16f 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -101,11 +101,16 @@ Publish the track with a `refresh` ratio so a joiner gets the value restated in `TrackInfo.priority` defaulted to 127 and now defaults to 0. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `request` and `follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +On `OriginConsumer` and `Client`, rename `request_broadcast(path)` to `request(path)` and `announced_broadcast(path)` to `follow(path)`; `moq.AnnouncedBroadcast` is `moq.Following`. +Both take a keyword-only `instance=` to refuse every other publisher instance. +`request` resolves one publisher instance: it retries as the routes covering the path change, and fails with an unroutable error only once discovery has synced with no covering route. `follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announced_broadcast()`, instead of under its whole scope at connect. -`OriginConsumer.request_broadcast()` watches nothing, so on a client it fails with an unroutable error for a path nothing watches, even when the relay announces it. -Resolve the path with `announced_broadcast()`, or hold `announced()` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()`, `request()`, or `follow()`, instead of under its whole scope at connect. +`OriginConsumer.request()` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `ContainerFormat.FMP4` unwraps to Legacy (#6250) @@ -188,7 +193,7 @@ bandwidth = session.recv_bandwidth() rate = bandwidth.rate() if bandwidth else None ``` -### `AnnouncedBroadcast.available()` waits for the next publisher instance (#5700) +### `Following.available()` waits for the next publisher instance (#5700) The first call returns the broadcast serving the path, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now. diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index ae4f269d71d..c02205b885e 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -73,7 +73,6 @@ 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 `instance`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` ## Related diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md deleted file mode 100644 index 14d21088e4b..00000000000 --- a/quest/m1/api-audit/resolve/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# [M] Two broadcast resolutions - -## Goal - -An application resolves a broadcast in one of two ways, named the same in -Rust, JS, and every binding: - -- `request(path, epoch)` resolves one publisher instance. It owns the - discovery interest it needs, so on a watch-driven lite client it finds a - broadcast the peer serves without the caller watching the path first, and - it retries across route churn. It answers `Unroutable` only once discovery - has synced with no covering route. -- `follow(path, epoch)` follows the path across publisher instances (today's - `announced_broadcast`), pinned to `epoch` when given. - -[Instance and epoch](https://github.com/moq-dev/moq/pull/7489) later changes the -pin from `epoch` to an `instance` 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". - -## Plan - -Decided 2026-10-22 (API audit, maintainer approved the recommendation). - -The behavioral checkpoint makes the Rust request own scoped discovery and -retry route churn. It reports table absence only after sync; a selected handler's -explicit refusal stays terminal, including a dropped Prepared answer. The front -records that refusal privately at its existing standing-route decision, rather -than guessing from unrelated mutations of the table. The old immediate lookup -is private to sessions. `Requesting::is_queued` and the public `Routing` task are -gone; `Requesting` is the owned task. The stats reader uses it instead of its -own retry on `is_queued`. Rust and JS have same-epoch follow-return coverage, -and every JS request owns its discovery watch from creation. A pending plain JS -request fails `Unroutable` once that discovery syncs with no route for it, -matching Rust. JS announcement-following no longer silently uses a blind peer. - -Decided 2026-10-28 (maintainer, /quest-plan): the rollout splits into a child -per language and one for the callers, so each reviews on its own. Rust has -landed: `request(path, epoch)` and `follow(path, epoch)` (returning -`origin::Following`), with `routed`, `routed_broadcast`, and the route-level -`announce::Follow` gone, and its in-tree callers following the path where they -used to wait for a route. JS has landed `follow(path, {epoch})`. The bindings -have landed too: moq-ffi, the C ABI, and every wrapper name them `request` and -`follow` with an optional epoch, `follow` returning `Following`. The callers -follow both. - -This README's own work, once every child lands: the lifecycle and churn checks -across languages, the required Nix gate, and all-language interop -(`just test interop --all`). - -Public API: breaking task shape in moq-net; behavior changes in `@moq/net` and -the bindings. The method and epoch renames broke every wrapper. -Wire: none. - -## Related - -- [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index e09b312af74..3cdb71422cd 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -101,11 +101,16 @@ With deltas on, the track carries a refresh ratio of 8 and the producer restates Higher is first and 0 is the unset midpoint, so a zeroed `moq_track_info` now uses the default priority rather than the least urgent one. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `moq_origin_follow` replaces `moq_origin_announced_broadcast`, and both resolutions take an instance ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +Rename `moq_origin_announced_broadcast` and `moq_origin_announced_broadcast_cancel` to `moq_origin_follow` and `moq_origin_follow_cancel`. +`moq_origin_request` and `moq_origin_follow` take `instance, instance_len` after `path_len`: pass `NULL, 0` to accept whichever publisher instance serves the path, or an instance to refuse every other. +`moq_origin_request` resolves one publisher instance: it retries as the routes covering the path change, and fails as unroutable only once discovery has synced with no covering route. `moq_origin_follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `moq_origin_announced` or `moq_origin_announced_broadcast`, instead of under its whole scope at connect. -`moq_origin_request` watches nothing, so on a client it fails with a negative code for a path nothing watches, even when the relay announces it. -Resolve the path with `moq_origin_announced_broadcast`, or hold `moq_origin_announced` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `moq_origin_announced`, `moq_origin_request`, or `moq_origin_follow`, instead of under its whole scope at connect. +`moq_origin_request` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `MOQ_CONTAINER_FORMAT_FMP4` unwraps to Legacy (#6250) @@ -193,7 +198,7 @@ if (consumer > 0) { } ``` -### `moq_origin_announced_broadcast` delivers every publisher instance (#5700) +### `moq_origin_follow` delivers every publisher instance (#5700) Its callback gets a new broadcast handle each time another instance takes over the path or the broadcast returns, and its terminal `0` only on cancel. Free each handle with `moq_consume_close` once its successor arrives. diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 4edfd584bbc..45bcd972382 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -52,38 +52,10 @@ fn publish_broadcast(origin: u32, path: &[u8]) -> u32 { } /// Request a published broadcast via `moq_origin_request` and return its handle. -/// -/// A broadcast created with `moq_origin_create_broadcast` becomes reachable -/// asynchronously, so an early request can race the attach and fail as unroutable; -/// retry until the deadline. fn request_broadcast(origin: u32, path: &[u8]) -> u32 { - let deadline = kio::clock::now() + TIMEOUT; - loop { - let cb = Callback::new(); - let _task = id(unsafe { - moq_origin_request( - origin, - path.as_ptr() as *const c_char, - path.len(), - std::ptr::null(), - 0, - Some(channel_callback), - cb.ptr, - ) - }); - let code = cb.recv(); - if code > 0 { - cb.recv_terminal(); - return code as u32; - } - // A failed request already delivered its terminal code; back off and retry. - assert!(kio::clock::now() < deadline, "timed out requesting broadcast: {code}"); - #[expect( - clippy::disallowed_methods, - reason = "the test thread has no runtime; it polls the C API's runtime between real retries" - )] - std::thread::sleep(Duration::from_millis(10)); - } + let code = request_once(origin, path); + assert!(code > 0, "requesting the broadcast failed: {code}"); + code as u32 } /// Request `path` once and return the first callback code: a broadcast handle, or diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 247823c3be5..b4b12376d6a 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -35,7 +35,7 @@ The `MoqFlate*` producers and `MoqFlateConfig` are deleted: publish opaque bytes ### Paths with an empty segment are refused ([#6648](https://github.com/moq-dev/moq/pull/6648)) -Every method taking a path, such as `MoqOriginProducer::create_broadcast` and `MoqOriginConsumer::request_broadcast`, returns an error for a path with a leading, trailing, or doubled `/` instead of collapsing it. Pass the canonical path, such as `room/cam`. +Every method taking a path, such as `MoqOriginProducer::create_broadcast` and `MoqOriginConsumer::request`, returns an error for a path with a leading, trailing, or doubled `/` instead of collapsing it. Pass the canonical path, such as `room/cam`. ### Request handlers are `requests()` ([#6752](https://github.com/moq-dev/moq/pull/6752)) @@ -127,11 +127,16 @@ Snapshot groups roll on joiner demand, which the producer answers on its own: pu `MoqTrackInfo.priority` defaulted to 127 and now defaults to 0. To keep a value's moq-lite byte, subtract 128 from it: 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `request` and `follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +Rename `MoqOriginConsumer::request_broadcast(path)` to `request(path, instance)`, `announced_broadcast(path)` to `follow(path, instance)`, and `MoqAnnouncedBroadcast` to `MoqFollowing`. +`instance` defaults to null in every generated binding, accepting whichever publisher instance serves the path; pass one to refuse every other. +`request` resolves one publisher instance: it retries as the routes covering the path change, and fails with `MoqError::Unroutable` only once discovery has synced with no covering route. `follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced` or `announced_broadcast`, instead of under its whole scope at connect. -`MoqOriginConsumer::request_broadcast` watches nothing, so on a client it fails with `MoqError::Unroutable` for a path nothing watches, even when the relay announces it. -Resolve the path with `announced_broadcast`, or hold `announced` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced`, `request`, or `follow`, instead of under its whole scope at connect. +`MoqOriginConsumer::request` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `MoqContainerFormat::Fmp4` unwraps to Legacy (#6250) @@ -220,7 +225,7 @@ let rate = bandwidth.as_ref().and_then(|b| b.rate()); ### `available()` waits for the next publisher instance (#5700) -`MoqAnnouncedBroadcast::available` returns the broadcast serving the path on its first call, as before. +`MoqFollowing::available` returns the broadcast serving the path on its first call, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now. ### A timed track refuses a group that rewinds (#5803) diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index d1522c7f1f0..2dcbaeffd3a 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -193,7 +193,7 @@ Its `Hang`, `Msf`, and `Closed` variants and `catalog::msf::Consumer::track` are Every later request for a path, siblings included, stays on the broadcast first held there and fails once it ends, so build a new `Source` to follow a new instance. ```rust -let broadcast = origin.request_broadcast(path, None).await?; +let broadcast = origin.request(path, None).await?; let source = Source::new(origin, broadcast); ``` diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 2c39bcddc6d..4711d76a8d5 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -90,7 +90,7 @@ There is one owned `Path` type: a short path is stored inline and a long one sha - `Path::{to_owned, into_owned, borrow}` and the `Relative` equivalents are gone: drop the call, or `clone()` a `&Path` you need to keep. - `Path::new`, `Relative::new`, `Path::join`, and `Path::resolve` return `Result<_, path::Error>`, failing on a path longer than `Path::MAX_BYTES`. `Path::new` copies its argument; use `Path::from_static("room")` for a literal, which borrows it and panics if it is too long. - `From<&str>`, `From<&String>`, and `From` for `Path` and `Relative` are `TryFrom`, with `path::Error` as the error. -- `AsPath` is gone. Origin entry points such as `publish`, `create_broadcast`, `scope`, `mount`, and `routed` take `impl TryInto>`, so `&str`, `String`, `Path`, and `&Path` still work and a too-long string fails with `Error::BoundsExceeded`. Other functions that took `impl AsPath`, such as `stats::Tier::new`, take `impl Into`: pass a `Path` or `&Path`. +- `AsPath` is gone. Origin entry points such as `publish`, `create_broadcast`, `scope`, `mount`, and `request` take `impl TryInto>`, so `&str`, `String`, `Path`, and `&Path` still work and a too-long string fails with `Error::BoundsExceeded`. Other functions that took `impl AsPath`, such as `stats::Tier::new`, take `impl Into`: pass a `Path` or `&Path`. - `origin::{Producer, Consumer}::absolute` and `announce::Consumer::absolute` return `Result`. - `Path::{has_prefix, strip_prefix, join, relative}` take `&Path`: write `path.has_prefix(&Path::from_static("room"))`. - Decoding a path longer than `Path::MAX_BYTES` fails with `BoundsExceeded`, like one deeper than `Path::MAX_PARTS`. @@ -275,9 +275,8 @@ On the wire, moq-lite carries `priority + 128` and moq-transport `127 - priority ### A client session asks only about what its readers watch (#6165) On moq-lite, a client session no longer asks its peer for announcements under its whole subscribe scope at connect. -It asks only under the prefixes its subscribe origin's readers watch, with `announced()`, `follow`, `routed`, `routed_broadcast`, or `announced_broadcast`, and stops asking 2s after nothing at or beneath a prefix is watched. -`request_broadcast` watches nothing, so on a client it fails with `Error::Unroutable` for a path no reader watches, even when the peer announces it. -Resolve a path with `routed_broadcast` or `announced_broadcast`, or hold an `announced()` stream over its prefix while requesting, the way `routed` already did after connecting. +It asks only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, and stops asking 2s after nothing at or beneath a prefix is watched. +`request(path, instance)` watches its own path while it resolves, so it finds a broadcast the peer serves with nothing else watching first; no `announced()` stream is needed beside it. A broadcast resolved through a discovered route keeps its path watched until dropped. A server session, and a client fed into a `Producer::peer` or `Producer::upstream` handle, still asks for everything it may, so a relay discovers as before. Serving another session's request is not a watch, so a client that relays what it discovers to its own sessions should feed its client session `origin.upstream()` (or `peer()`) instead of a plain handle. @@ -517,9 +516,22 @@ A publisher that continues its group sequences across restarts may name a stable Read `Route::instance` and `broadcast::Info::instance`; the epoch is never readable. A session of moq-lite 06 or older, or moq-transport, mints an instance starting with `~` for each announcement (`Instance::is_minted`). -### `request` and `follow` take an instance +### A path resolves with `request` or `follow` ([#6445](https://github.com/moq-dev/moq/pull/6445), [#7172](https://github.com/moq-dev/moq/pull/7172)) -Pass `None` to accept whichever instance wins the path, or an `Instance` to refuse every other one. +| Before | After | +|---|---| +| `origin::Consumer::request_broadcast(path)` | `request(path, None)` | +| `origin::Consumer::routed_broadcast(path)` | `request(path, None)` to resolve one instance, or `follow(path, None)?` to follow the path across instances | +| `origin::Consumer::routed(path)`, then `request_broadcast(path)` | `follow(path, None)?.available().await` | +| `origin::Consumer::routed(path)` to read the `Route` | `announced()` on a consumer `scope`d to the path with `Pattern::literal` | + +`request(path, instance)` resolves one publisher instance. It owns the discovery of its path and retries as the routes covering the path change, so it no longer fails at once when no route covers the path yet: it fails with `Error::Unroutable` only once discovery has synced with no covering route. +Drop a `routed` wait or an `announced()` stream held only so a request could resolve. +A selected handler's explicit refusal, including a dropped `Prepared`, is final; a request no longer waits for the routes to move after one. +`follow(path, instance)` returns an `origin::Following`, whose `available()` yields the broadcast each instance serving the path in turn. +`Requesting` is the owned task `request` returns; `Requesting::is_queued` is gone. + +Pass `None` to either to accept whichever instance wins the path, or an `Instance` to refuse every other one. A route updated to another instance refuses the requests its handler still holds with `Unroutable`. ### Demand is read through `demand()` diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index cc7bd5e5c43..2b395bce2ad 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -96,11 +96,16 @@ Publish the track with a `refresh` ratio so a joiner gets the value restated in `TrackInfo.priority` defaulted to 127 and now defaults to 0. To keep a value's moq-lite byte, subtract 128 from it, widening first so it doesn't trap (`Int8(Int16(old) - 128)`): 255 becomes 127, 128 becomes 0, and 0 becomes -128. +### `request` and `follow` name the two resolutions ([#7193](https://github.com/moq-dev/moq/pull/7193), [#7489](https://github.com/moq-dev/moq/pull/7489)) + +Rename `OriginConsumer.requestBroadcast(path:)` to `request(path:)`, `announcedBroadcast(path:)` to `follow(path:)`, and `AnnouncedBroadcast` to `Following`. +Both take an optional `instance:` to refuse every other publisher instance. +`request` resolves one publisher instance: it retries as the routes covering the path change, and fails with an unroutable error only once discovery has synced with no covering route. `follow` hands out each instance that serves the path in turn. + ### A client asks only about what it watches (#6165) -On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. -`OriginConsumer.requestBroadcast()` watches nothing, so on a client it fails with an unroutable error for a path nothing watches, even when the relay announces it. -Resolve the path with `announcedBroadcast()`, or hold `announced()` over its prefix while requesting. +On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()`, `request(path:)`, or `follow(path:)`, instead of under its whole scope at connect. +`OriginConsumer.request(path:)` owns the discovery of its path, so it finds a broadcast the relay serves with nothing else watching first; no announcement stream is needed beside it. moq-transport and moq-lite-03/04 sessions are unchanged. ### `ContainerFormat.fmp4` unwraps to Legacy (#6250) @@ -181,7 +186,7 @@ The connection stats no longer carry a receive estimate. Hold the consumer `Session.recvBandwidth` returns to request PROBE, read it with `rate()` or wait with `rateChanged()`, and drop it to stop. It returns `nil` when the version has no PROBE. -### `AnnouncedBroadcast.available()` waits for the next publisher instance (#5700) +### `Following.available()` waits for the next publisher instance (#5700) The first call returns the broadcast serving the path, as before. Each later call waits for the next instance to take over the path, instead of returning whatever serves it now.