diff --git a/bun.lock b/bun.lock index e3e32420308..13f7cab5316 100644 --- a/bun.lock +++ b/bun.lock @@ -197,11 +197,11 @@ "name": "@moq/json", "version": "0.4.2", "dependencies": { + "@moq/clock": "workspace:^", "@moq/net": "workspace:^", "@moq/signals": "workspace:^", }, "devDependencies": { - "@moq/clock": "workspace:^", "@types/bun": "^1.4.4", "fast-check": "^4.10.2", "typescript": "7.0.2", diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index b68b7bc6375..bde762ab762 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -16,6 +16,10 @@ Use `BroadcastProducer.createDatagrams(name: ..., info: ...)` and `BroadcastCons A null `TrackInfo.maxAge`, the default, and a null info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited: true`, which ignores `maxAge`, where you relied on null meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`SnapshotConsumer(broadcast: ..., name: ..., priority: ...)` takes the `BroadcastConsumer` and the track name instead of `track:`, and subscribes to the track itself at a zero `delay.max` and `priority` (default 0). Drop the `subscribeTrack` call; a refused subscription now throws from the first read. `next()` skips every group a newer one supersedes, and `latest()` no longer waits for a lower group the track still owes. Publish a stream track when every state must survive, or a window track for a bounded recent history. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. @@ -56,7 +60,7 @@ A fixed audio playout delay `d` is `delay: Delay(min: d, max: ...)` with `estima `package:moq/flate.dart` is removed: publish opaque bytes on a `TrackProducer`. `SnapshotConfig` and `WindowConfig` lose `compression`, and `StreamConfig` is removed. Publish the track with `MoqTrackInfo(compress: true)` instead. -`StreamProducer` drops its `config`, and `SnapshotConsumer`, `StreamConsumer`, and `WindowConsumer` take only the track. +`StreamProducer` drops its `config`, and `StreamConsumer` and `WindowConsumer` take only the track. `SnapshotConsumer` takes the broadcast and track name; see the entry above. ### Paths with an empty segment are refused ([#6648](https://github.com/moq-dev/moq/pull/6648)) diff --git a/dart/moq/lib/json.dart b/dart/moq/lib/json.dart index 2ede41f88b8..cda9004ac77 100644 --- a/dart/moq/lib/json.dart +++ b/dart/moq/lib/json.dart @@ -34,8 +34,8 @@ import 'package:moq_ffi/moq_ffi.dart'; /// Publishes lossy latest-value JSON snapshots on a track it takes over. typedef SnapshotProducer = MoqJsonSnapshotProducer; -/// Consumes each JSON snapshot state from a track it takes over, or skips to -/// the newest with `latest()`. +/// Consumes each JSON snapshot state from a track it subscribes to itself, or +/// skips to the newest with `latest()`. typedef SnapshotConsumer = MoqJsonSnapshotConsumer; /// Configures a lossy latest-value JSON producer. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 574aae34b8a..14749e44102 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -641,11 +641,10 @@ void main() { ), config: moq_json.SnapshotConfig(), ); - final track = await broadcast - .consume() - .subscribeTrack(name: 'status', subscription: null) - .timeout(timeout); - final consumer = moq_json.SnapshotConsumer(track: track); + final consumer = moq_json.SnapshotConsumer( + broadcast: broadcast.consume(), + name: 'status', + ); for (var n = 1; n <= 4; n++) { producer.update( diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 793b24161e0..ef6628b69ac 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -11596,14 +11596,19 @@ class MoqJsonSnapshotConsumer implements MoqJsonSnapshotConsumerInterface { MoqJsonSnapshotConsumer._(this._ptr) { _MoqJsonSnapshotConsumerFinalizer.attach(this, _ptr, detach: this); } - MoqJsonSnapshotConsumer({required MoqTrackConsumer track}) - : _ptr = rustCall( - (status) => uniffi_moq_ffi_fn_constructor_moqjsonsnapshotconsumer_new( - FfiConverterMoqTrackConsumer.lower(track), - status, - ), - moqExceptionErrorHandler, - ) { + MoqJsonSnapshotConsumer({ + required MoqBroadcastConsumer broadcast, + required String name, + int priority = 0, + }) : _ptr = rustCall( + (status) => uniffi_moq_ffi_fn_constructor_moqjsonsnapshotconsumer_new( + FfiConverterMoqBroadcastConsumer.lower(broadcast), + FfiConverterString.lower(name), + FfiConverterInt8.lower(priority), + status, + ), + moqExceptionErrorHandler, + ) { _MoqJsonSnapshotConsumerFinalizer.attach(this, _ptr, detach: this); } factory MoqJsonSnapshotConsumer.lift(Pointer ptr) { @@ -20129,12 +20134,19 @@ external void uniffi_moq_ffi_fn_free_moqjsonsnapshotconsumer( Pointer uniffiStatus, ); -@Native Function(Pointer, Pointer)>( - assetId: _uniffiAssetId, -) +@Native< + Pointer Function( + Pointer, + RustBuffer, + Int8, + Pointer, + ) +>(assetId: _uniffiAssetId) external Pointer uniffi_moq_ffi_fn_constructor_moqjsonsnapshotconsumer_new( - Pointer track, + Pointer broadcast, + RustBuffer name, + int priority, Pointer uniffiStatus, ); @@ -23586,7 +23598,7 @@ void _checkApiChecksums() { 60932) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotconsumer_next() != 5806) { + if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotconsumer_next() != 15547) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_demand() != @@ -24092,7 +24104,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonsnapshotconsumer_new() != - 11929) { + 47962) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonsnapshotproducer_new() != diff --git a/demo/carla/web/src/truck.test.ts b/demo/carla/web/src/truck.test.ts index 165a354c117..84e89a503e4 100644 --- a/demo/carla/web/src/truck.test.ts +++ b/demo/carla/web/src/truck.test.ts @@ -328,10 +328,10 @@ describe("Truck safety controls", () => { timestamps: [], }); const front = new Json.Snapshot.Consumer>({ - track: safety.broadcast.track("control").subscribe(), + track: safety.broadcast.track("control"), }); const rear = new Json.Snapshot.Consumer>({ - track: safety.broadcast.track("control").subscribe(), + track: safety.broadcast.track("control"), }); try { diff --git a/demo/carla/web/src/truck.ts b/demo/carla/web/src/truck.ts index 442757ac2ba..e16c27b7eeb 100644 --- a/demo/carla/web/src/truck.ts +++ b/demo/carla/web/src/truck.ts @@ -365,13 +365,12 @@ export class Truck { this.#sawStatusSource = true; this.statusState.set("pending"); - const statusTrack = active.track("status").subscribe({ priority: 10 }); - effect.cleanup(() => statusTrack.close()); - const consumer = new Json.Snapshot.Consumer({ - track: statusTrack, + track: active.track("status"), schema: TruckStatusSchema, + priority: 10, }); + effect.cleanup(() => consumer.close()); effect.spawn(async () => { for (;;) { diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index 55958c73391..e7342608394 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -440,9 +440,11 @@ ui.run((effect) => { return; } - const track = broadcast.track(trackName).subscribe({ priority: Hang.Catalog.PRIORITY.catalog }); - effect.cleanup(() => track.close()); - const consumer = new Json.Snapshot.Consumer({ track }); + const consumer = new Json.Snapshot.Consumer({ + track: broadcast.track(trackName), + priority: Hang.Catalog.PRIORITY.catalog, + }); + effect.cleanup(() => consumer.close()); effect.spawn(async () => { try { diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index c5c161a3825..3b689cd2c32 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -200,9 +200,8 @@ function subscribeNode(effect: Signals.Effect, origin: Net.Origin.Reader, path: const consumer = request.active.peek(); if (!consumer) return; - const track = consumer.track("group.json").subscribe(); - effect.cleanup(() => track.close()); - const group = new Json.Snapshot.Consumer({ track }); + const group = new Json.Snapshot.Consumer({ track: consumer.track("group.json") }); + effect.cleanup(() => group.close()); effect.spawn(async () => { for (;;) { const state = await effect.race(group.latest()); diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 1fd5044a997..2c105c612f8 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -13,7 +13,7 @@ are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is a third framing for a raw track: both ends opt into it, and a generic catalog reader will not pick it up. -- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest. Deltas ride one group until a joiner wants a fresh one: give the track a `refresh` ratio (8 is typical) and the producer restates the value in a new group. Without a ratio a group rolls only at its caps. +- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields each state in order, skipping every group a newer one supersedes; `latest()` skips to the newest. Deltas ride one group until a joiner wants a fresh one: give the track a `refresh` ratio (8 is typical) and the producer restates the value in a new group. Without a ratio a group rolls only at its caps. - **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. - **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Its ops roll on the track's `refresh` ratio the same way. @@ -27,18 +27,18 @@ an untimed track (no `timescale`) takes none and reads back without one. ```ts import { Snapshot } from "@moq/json"; -// Hold each state back until the video playhead reaches it. +// Schedule each state at its capture time. const consumer = new Snapshot.Consumer({ track }); for await (const { value, at } of consumer) { schedule(value, at); } ``` -`next()` buffers every state it has not yielded and skips a group once the -subscription's `delay.max` proves it stale. The budget counts media time and -wall time, or wall time alone for an untimed track. The default subscription's -zero keeps only the newest group, so subscribe with a `delay.max` covering how -far the playhead trails the live edge. Use `latest()` to skip straight to the head. +`next()` yields every buffered state of the group it is reading and skips a +group once a newer one supersedes it: the consumer takes the track, a +`Track.Consumer` such as `broadcast.track(name)`, and subscribes to it itself at +a zero `delay.max`, so nothing can raise its budget. Use `latest()` to skip +straight to the head, and `close()` to end the subscription. A stream rides one group with no record-count or cumulative byte limit. The group retains a 32 MiB tail; a reader that falls behind gets `Evicted` rather diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index 4bfd2702924..12b7250b591 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -145,13 +145,11 @@ const dispose = el.signals.run((effect) => { const name = metadata?.[0]; if (!active || !name) return; - const track = active.track(name).subscribe({ - ...Moq.Track.Subscription.default(), + const consumer = new Json.Snapshot.Consumer({ + track: active.track(name), priority: Hang.Catalog.PRIORITY.catalog, }); - effect.cleanup(() => track.close()); - - const consumer = new Json.Snapshot.Consumer({ track }); + effect.cleanup(() => consumer.close()); effect.spawn(async () => { for (;;) { const state = await effect.race(consumer.latest()); diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index dfb51393929..84e0611a307 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -26,10 +26,11 @@ same optional capture time when opened, including when they publish on drop. Consumers return `Timed`: read `.value` for the decoded value and `.at` for its optional frame timestamp, with the track's exact scale preserved. Snapshot -`next()` yields states in order inside the subscription's `delay.max` budget; -set that budget when following a playhead behind live. Use `latest()` to skip -to the newest buffered state. Skipped states are gone, and a later `next()` -continues after them. +`next()` yields states in order, skipping every group a newer one supersedes: +`snapshot::Consumer::new` takes the track and subscribes to it itself at a zero +`delay.max`, so nothing can raise its budget. Use `latest()` to skip to the +newest buffered state. Skipped states +are gone, and a later `next()` continues after them. Upgrading from an older release: see moq-json's [MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md). diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index cfeddfb2b16..bea18463d46 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -16,6 +16,10 @@ Replace stream-track `AppendDatagram` / `InsertDatagram` / `RecvDatagram` with ` `TrackInfo.MaxAge` is a `time.Duration` instead of a `*time.Duration`, like `Delay.Max`: the zero value, and a nil `*TrackInfo`, now advertise a zero max age, serving only the live edge, instead of no publisher limit. Assign the duration directly, and set the new `MaxAgeUnlimited`, which ignores `MaxAge`, where you relied on nil meaning no limit. A received track's `Info()` sets it when its publisher advertised no limit. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`json.NewSnapshotConsumer(broadcast, name, options)` takes the `*BroadcastConsumer`, the track name, and `SnapshotConsumerOptions` instead of a `*TrackConsumer`, and subscribes to the track itself at a zero `Delay.Max` and the options' `Priority`. Drop the `SubscribeTrack` call; a refused subscription now fails the first read. `Next` skips every group a newer one supersedes, and `Latest` no longer waits for a lower group the track still owes. Publish a stream track when every state must survive, or a window track for a bounded recent history. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `ErrOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.Watch` returns `(*Viewer, error)`, and `Viewers.SetTarget` and `Viewer.Update` return an `error`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. @@ -195,7 +199,7 @@ Application calls are unchanged. ### JSON consumers return `*json.Timed` (#5677) `SnapshotConsumer.Next`, `StreamConsumer.Next`, and `All` return `*Timed{Value, Timestamp}` instead of the raw message; `Timestamp` is a `*time.Duration`, nil when untimed. -A snapshot consumer's `Next` now yields every state in order; call `Latest(ctx)` for the newest. +A snapshot consumer's `Next` now yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); call `Latest(ctx)` for the newest. Timestamps are rounded down to a whole microsecond. ### Ranges filter reads (#5929) diff --git a/go/wrapper/README.md b/go/wrapper/README.md index b14d4b13156..c459b043a99 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -117,8 +117,9 @@ so the media importer selects the timescale. JSON tracks live in the `moq.dev/moq/json` subpackage, mirroring the `moq-json` crate. Import it under an alias next to `encoding/json`. Each type wraps a track: `NewSnapshotProducer` / `NewStreamProducer` take over a `TrackProducer` and advertise it -in the broadcast's catalog, and `NewSnapshotConsumer` / `NewStreamConsumer` take over a -`TrackConsumer` that has not read a group yet. Snapshots carry lossy latest state; streams +in the broadcast's catalog, `NewStreamConsumer` takes over a `TrackConsumer` that has not +read a group yet, and `NewSnapshotConsumer` takes the `BroadcastConsumer` and track name and +subscribes itself at a zero `Delay.Max` and `SnapshotConsumerOptions.Priority`. Snapshots carry lossy latest state; streams carry every record in order. `NewWindowProducer` / `NewWindowConsumer` carry a sliding window of records a reader can join at any point; the catalog has no window mode, so the producer takes only the track. Producers accept any `encoding/json` value; consumers return @@ -148,7 +149,8 @@ _ = publication.Announce(moq.AnnounceRoute{}) ``` Snapshot and window producers take `SnapshotOptions` or `WindowOptions`; the stream producer and -every consumer take only the track, and a consumer reads a compressed track like a plain one. +the stream and window consumers take only the track. Every consumer reads a compressed track like a +plain one. ## Errors diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 7866ac4d059..1af07d5f31f 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -155,19 +155,26 @@ type SnapshotConsumer struct { inner *ffi.MoqJsonSnapshotConsumer } -// NewSnapshotConsumer reads track as a lossy latest-value JSON track. It takes over -// track, whose handle is closed afterward, and fails if track has already read a group. -func NewSnapshotConsumer(track *moq.TrackConsumer) (*SnapshotConsumer, error) { - inner, err := ffi.NewMoqJsonSnapshotConsumer(bridge.TrackConsumer(track)) +// SnapshotConsumerOptions configures a snapshot consumer's subscription. +type SnapshotConsumerOptions struct { + // Priority is the subscription's delivery priority, higher first, as + // moq.Subscription.Priority. + Priority int8 +} + +// NewSnapshotConsumer subscribes to the track named name on broadcast and reads it as a +// lossy latest-value JSON track. The consumer owns its subscription, at a zero Delay.Max +// and the options' priority; a read waits for it to resolve and fails if it cannot. +func NewSnapshotConsumer(broadcast *moq.BroadcastConsumer, name string, options SnapshotConsumerOptions) (*SnapshotConsumer, error) { + inner, err := ffi.NewMoqJsonSnapshotConsumer(bridge.BroadcastConsumer(broadcast), name, options.Priority) if err != nil { return nil, err } return &SnapshotConsumer{inner: inner}, nil } -// Next returns the next state in order, or nil when the track ends. Groups older -// than the subscription's Delay.Max are skipped, so a playhead reader sets that -// budget to its distance behind live. +// Next returns the next state in order, or nil when the track ends. It skips +// every group a newer one supersedes. func (c *SnapshotConsumer) Next(ctx context.Context) (*Timed, error) { value, err := bridge.Call(ctx, c.inner.Cancel, c.inner.Next) return timed(value), err diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index df60fb57ee6..d05c34f82ea 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -65,7 +65,7 @@ func TestTracks(t *testing.T) { if err != nil { t.Fatal(err) } - snapshotConsumer, err := moqjson.NewSnapshotConsumer(subscribeTrack(ctx, t, consumer, "status")) + snapshotConsumer, err := moqjson.NewSnapshotConsumer(consumer, "status", moqjson.SnapshotConsumerOptions{}) if err != nil { t.Fatal(err) } @@ -246,7 +246,7 @@ func TestDemand(t *testing.T) { t.Fatalf("Wanted = %d before any subscriber", *wanted) } - snapshotConsumer, err := moqjson.NewSnapshotConsumer(subscribeTrack(ctx, t, consumer, "status")) + snapshotConsumer, err := moqjson.NewSnapshotConsumer(consumer, "status", moqjson.SnapshotConsumerOptions{}) if err != nil { t.Fatal(err) } diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 7827f1ab84a..b5c4a9fe29a 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -1,6 +1,6 @@ import * as Json from "@moq/json"; import type * as Moq from "@moq/net"; -import { Path, Track } from "@moq/net"; +import { Path } from "@moq/net"; import * as z from "zod/mini"; import { AudioSchema } from "./audio"; import { BinarySchema } from "./binary"; @@ -191,15 +191,18 @@ export function checkResolvable(root: Root, base: Moq.Path.Valid): Root { * yielded unresolved. */ export async function* watch(broadcast: Moq.Broadcast.Consumer): AsyncIterable { - const track = broadcast.track(TRACK).subscribe({ ...Track.Subscription.default(), priority: PRIORITY.catalog }); + const consumer = new Json.Snapshot.Consumer({ + track: broadcast.track(TRACK), + schema: RootSchema, + priority: PRIORITY.catalog, + }); try { - const consumer = new Json.Snapshot.Consumer({ track, schema: RootSchema }); for (;;) { const root = await consumer.latest(); if (!root) return; yield checkResolvable(checkRenditions(root.value), broadcast.path); } } finally { - track.close(); + consumer.close(); } } diff --git a/js/json/MIGRATE.md b/js/json/MIGRATE.md index d32c2324c0a..c18dd854690 100644 --- a/js/json/MIGRATE.md +++ b/js/json/MIGRATE.md @@ -4,6 +4,15 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`Snapshot.Consumer`'s `track` option is the track itself, a `Track.Consumer` (`broadcast.track(name)`) or an in-process `Track.Producer`, instead of a `Track.Subscriber`. The consumer subscribes to it at a zero `delay.max` and default options otherwise; the new `priority` option sets the subscription's priority. +Call the consumer's new `close()` to end that subscription, where you closed your subscriber before. +No handle to the subscription leaves the consumer, so ranges, order, and `delay.max` can no longer be set on a snapshot reader. + +`next()` skips every group a newer one supersedes, and `latest()` no longer waits for a lower group a received track still owes, whatever another reader of the track asks for. +A reader that set `delay.max` to replay a snapshot track's history or trail a playhead gets only the newest group: read the track's groups yourself and feed them to a `Snapshot.Decoder`, or publish a `Stream` track when every state must survive, or a `Window` track for a bounded recent history. + ### Compression moves to the track The `Compression` type, every `compression` option, `Desync`, `Stream.Decoder.reset`, and `Window.DecoderConfig` are gone, along with the `@moq/flate` dependency. @@ -30,7 +39,7 @@ Fix any publisher that writes a repeated key. The snapshot, stream, and window consumers' `next()` and async iterator yield `{ value, at }`, where `at` is the frame's timestamp and absent on an untimed track. A window event's `value` is the `Event` that `next()` used to return; a record restated by a group header carries the header frame's time. -A snapshot consumer's `next()` yields every state in order; call `latest()` to skip to the newest, as `next()` used to. +A snapshot consumer's `next()` yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); call `latest()` to skip to the newest, as `next()` used to. Where you awaited `next()` for the newest value, read `(await consumer.latest())?.value`. A caller that passes the result on as `any` or `unknown` still compiles, so search for every `next()` and `for await` rather than relying on type errors. diff --git a/js/json/README.md b/js/json/README.md index 52130324737..b15aa79ac80 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -32,8 +32,9 @@ import { Time } from "@moq/net"; const producer = new Snapshot.Producer({ track }); producer.update({ value: { hello: "world" }, at: Time.Timestamp.now() }); -// Consume: each state in order, with the timestamp of the frame that produced it. -const consumer = new Snapshot.Consumer({ track: track.subscribe() }); +// Consume: each state in order, with the timestamp of the frame that produced it. The consumer +// subscribes to the track itself; pass `broadcast.track(name)` for a remote one. +const consumer = new Snapshot.Consumer({ track }); for await (const { value, at } of consumer) { console.log(value, at); } diff --git a/js/json/api/index.api.md b/js/json/api/index.api.md index 771fe2414ae..31d28825535 100644 --- a/js/json/api/index.api.md +++ b/js/json/api/index.api.md @@ -28,12 +28,14 @@ export namespace Snapshot { } export namespace Consumer { export type Config = Pick, "schema"> & { - track: Track.Subscriber; + priority?: number; + track: Pick; }; } export class Consumer { constructor(config: Snapshot.Consumer.Config); [Symbol.asyncIterator](): AsyncIterator>; + close(): void; latest(): Promise | undefined>; next(): Promise | undefined>; } diff --git a/js/json/package.json b/js/json/package.json index 1a27c1a37d9..b7596dd7cae 100644 --- a/js/json/package.json +++ b/js/json/package.json @@ -20,6 +20,7 @@ "release": "bun ../common/release.ts" }, "dependencies": { + "@moq/clock": "workspace:^", "@moq/net": "workspace:^", "@moq/signals": "workspace:^" }, @@ -27,7 +28,6 @@ "zod": "^4.5.0" }, "devDependencies": { - "@moq/clock": "workspace:^", "@types/bun": "^1.4.4", "fast-check": "^4.10.2", "typescript": "7.0.2" diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 6914da66761..492c2f5339a 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -1,3 +1,4 @@ +import { Milli } from "@moq/clock"; import type { Timed } from "@moq/net"; import * as Moq from "@moq/net"; @@ -16,10 +17,16 @@ const GAPS: Moq.StreamCode[] = [ * * A {@link Decoder} that owns its track: it reads groups, routes each frame by its position, and * yields each reconstructed value with the timestamp of the frame that produced it. Two reads: - * {@link next} yields every state in order, for a caller that picks the state matching a playhead, + * {@link next} yields each state in order, skipping every group a newer one supersedes, * and {@link latest} skips to the newest state, for a caller that only wants the current value. - * What {@link latest} skips is gone, so a later {@link next} resumes after it. + * What {@link latest} skips is gone, so a later {@link next} resumes after it. Overlapping reads + * take turns in call order. * When something else already owns the track, use the {@link Decoder} directly. + * + * A snapshot is superseded the moment a newer one exists, so the consumer subscribes itself at a + * zero `delay.max` and keeps that subscription to itself: a group is skipped once a newer one + * arrives, and a lower group the subscription still owes never holds up a newer one. + * {@link close} ends the subscription. */ export class Consumer { #track: Moq.Track.Ordered; @@ -27,24 +34,38 @@ export class Consumer { #group?: Moq.Group.Consumer; #framesRead = 0; + #closed = false; + // The read in flight: reads share the group and decoder, so each starts once the last settles. + #reading: Promise = Promise.resolve(); constructor(config: Consumer.Config) { - this.#track = config.track.ordered(); + this.#track = config.track + .subscribe({ + ...Moq.Track.Subscription.default(), + priority: config.priority ?? 0, + delay: { max: Milli.zero }, + }) + .ordered(); this.#decoder = new Decoder(config); } + /** End the consumer's subscription; a pending or later read returns `undefined`. Idempotent. */ + close(): void { + if (this.#closed) return; + this.#closed = true; + this.#group?.close(); + this.#track.close(); + } + /** * Get the next state in order, or `undefined` once the track ends. * - * Yields one state per frame and finishes a group before starting the next, buffering every - * state the reader has not reached yet. A group the subscription's `delay.max` proves too old - * is skipped, counting media time and wall time, or wall time alone for an untimed track. The - * default subscription's zero keeps only the newest group, so a playhead reader sets `delay.max` - * to how far it trails the live edge. Use {@link latest} to skip straight to the head. A group lost to a - * gap resyncs from the next one. + * Yields one state per frame from the group it is reading, and skips every group a newer one + * supersedes. Use {@link latest} to skip straight to the head. A group lost to a gap resyncs + * from the next one. */ next(): Promise | undefined> { - return this.#read(false); + return this.#queue(false); } /** @@ -57,15 +78,23 @@ export class Consumer { * when nothing newer than the last yield has arrived. */ latest(): Promise | undefined> { - return this.#read(true); + return this.#queue(true); + } + + #queue(skip: boolean): Promise | undefined> { + const read = this.#reading.then(() => this.#read(skip)); + this.#reading = read.catch(() => undefined); + return read; } async #read(skip: boolean): Promise | undefined> { for (;;) { + // Checked again after every wait: a read that resumes after close ends, not reads on. + if (this.#closed) return undefined; if (skip) { // Jump to the newest group the reader already has; a newer one supersedes the rest. // Taking groups, not the track's largest position, ignores datagrams (which share - // the sequence space) and stays inside any range the caller set on the reader. + // the sequence space). // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses // nothing but stale state. for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { @@ -77,22 +106,30 @@ export class Consumer { if (!this.#group) { // Advance to the next group with a higher sequence number (skipping late arrivals). - this.#group = await this.#track.nextGroup(); - if (!this.#group) return undefined; + const next = await this.#track.nextGroup(); + if (this.#closed) { + next?.close(); + return undefined; + } + if (!next) return undefined; + this.#group = next; // The next frame is the new group's snapshot, which also restarts the decoder's window. this.#framesRead = 0; } + const group = this.#group; let frame: Moq.Group.Frame | undefined; try { - frame = await this.#group.readFrame(); + frame = await group.readFrame(); } catch (err) { + if (this.#closed) return undefined; if (!(err instanceof Moq.Error.Stream && GAPS.includes(err.code))) throw err; // The group was reset or we fell behind its eviction window. Resync from the next // group, which begins with a fresh snapshot (frame 0), so no partial state is presented. this.#group = undefined; continue; } + if (this.#closed) return undefined; if (!frame) { // The group is exhausted; advance to the next one. @@ -103,7 +140,7 @@ export class Consumer { this.#apply(frame.payload); if (skip) { // Apply the rest of the backlog but yield only the head. - for (let more = this.#group.tryReadFrame(); more; more = this.#group.tryReadFrame()) { + for (let more = group.tryReadFrame(); more; more = group.tryReadFrame()) { this.#apply(more.payload); frame = more; } @@ -138,6 +175,13 @@ export class Consumer { export namespace Consumer { /** Snapshot consumer options, including the source track. */ export type Config = Pick, "schema"> & { - track: Moq.Track.Subscriber; + /** + * The track to read: a {@link Moq.Track.Consumer}, or a {@link Moq.Track.Producer} to read + * in-process. The consumer subscribes to it at a zero `delay.max`, with default options + * otherwise. + */ + track: Pick; + /** Delivery priority of the consumer's subscription, higher first; defaults to 0. */ + priority?: number; }; } diff --git a/js/json/src/snapshot/index.ts b/js/json/src/snapshot/index.ts index 3bb074e92f8..311ecbfdd2d 100644 --- a/js/json/src/snapshot/index.ts +++ b/js/json/src/snapshot/index.ts @@ -3,8 +3,8 @@ * * One JSON value updated over time, for consumers that care about the state rather than every * record (a catalog, a status document). This mode is **lossy** by design: a new group supersedes - * the older ones, which are dropped. {@link Consumer.next} yields every state it still receives, - * in order, each with its frame's timestamp, for a caller that picks the state at a playhead. + * the older ones, which are dropped. {@link Consumer.next} yields each state in order, each with + * its frame's timestamp, skipping every group a newer one supersedes. * {@link Consumer.latest} jumps straight to the newest group and collapses any buffered backlog * into a single yield, for a caller that only wants the current value. For an ordered log where * every record is preserved, use the `Stream` module instead. diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 128fd19419d..2d037330da0 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -1,31 +1,36 @@ import { expect, test } from "bun:test"; -import { Milli } from "@moq/clock"; +import { Milli, Nano, sleep } from "@moq/clock"; import { Error as NetError, StreamCode, Time, Track } from "@moq/net"; +import { hooks } from "../../../net/src/internal.ts"; import { Consumer } from "./consumer.ts"; import { Encoder } from "./encoder.ts"; import { Producer } from "./producer.ts"; type Value = Record; -// These tests inspect complete finished timelines, so request a replay window -// instead of the transport's live-edge default. +// These tests inspect complete finished timelines through raw ordered reads, so request a +// replay window instead of the transport's live-edge default. A snapshot consumer ignores it. const REPLAY_LATENCY = Milli(30_000); -// Reconstruct every state a consumer yields from `next()`, in order. -async function drain(track: Track.Subscriber): Promise { +// Reconstruct every state a consumer reading `track` yields from `next()`, in order. +async function drain(track: Track.Producer | Consumer): Promise { const out: Value[] = []; - for await (const { value } of new Consumer({ track })) out.push(value); + for await (const { value } of reader(track)) out.push(value); return out; } -// Reconstruct every state a consumer yields from `latest()`, in order. -async function drainLatest(track: Track.Subscriber): Promise { - const consumer = new Consumer({ track }); +// Reconstruct every state a consumer reading `track` yields from `latest()`, in order. +async function drainLatest(track: Track.Producer | Consumer): Promise { + const consumer = reader(track); const out: Value[] = []; for (let state = await consumer.latest(); state; state = await consumer.latest()) out.push(state.value); return out; } +function reader(track: Track.Producer | Consumer): Consumer { + return track instanceof Consumer ? track : new Consumer({ track }); +} + // Inspect the published layout via the public API: the frame count of each group, in order. // The track must be finished first so group/frame reads terminate. async function structure(track: Track.Ordered): Promise { @@ -53,7 +58,7 @@ test("a cut makes the next update a snapshot group", async () => { // The ratio would have kept every update in one group; the cut rolled it anyway. The replacement // opens with a full snapshot, so it is one frame rather than a delta appended to the first group. expect(await structure(track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered())).toEqual([2, 1]); - expect((await drain(track.subscribe({ delay: { max: REPLAY_LATENCY } }))).at(-1)).toEqual({ a: 1, b: 3 }); + expect(await drain(track)).toEqual([{ a: 1, b: 3 }]); }); test("a cut republishes an unchanged value", async () => { @@ -115,15 +120,18 @@ test("a cut is inert without deltas", async () => { test("deltas off: a snapshot group per change", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltas: false }); + const consumer = new Consumer({ track }); producer.update({ value: { a: 1 } }); + expect((await consumer.next())?.value).toEqual({ a: 1 }); producer.update({ value: { a: 2 } }); + expect((await consumer.next())?.value).toEqual({ a: 2 }); producer.finish(); - // Two changes => two single-frame snapshot groups. `next()` reads both in order, while `latest()` - // collapses the backlog to the newest value: older groups only hold superseded state (mirrors the - // Rust consumer). The layout itself is asserted via structure() below. - expect(await drain(track.subscribe({ delay: { max: REPLAY_LATENCY } }))).toEqual([{ a: 1 }, { a: 2 }]); - expect(await drainLatest(track.subscribe({ delay: { max: REPLAY_LATENCY } }))).toEqual([{ a: 2 }]); + // Two changes => two single-frame snapshot groups. A reader arriving after both reads only the + // newest: the older group holds superseded state (mirrors the Rust consumer). + expect(await structure(track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered())).toEqual([1, 1]); + expect(await drain(track)).toEqual([{ a: 2 }]); + expect(await drainLatest(track)).toEqual([{ a: 2 }]); }); // `latest()` holding a group must jump when a newer snapshot group rolls: the @@ -133,7 +141,7 @@ test("deltas off: a snapshot group per change", async () => { test("latest abandons a held group when a newer snapshot group rolls", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - const consumer = new Consumer({ track: track.subscribe({ delay: { max: REPLAY_LATENCY } }) }); + const consumer = new Consumer({ track }); producer.update({ value: { a: 1 } }); expect((await consumer.latest())?.value).toEqual({ a: 1 }); @@ -148,25 +156,24 @@ test("latest abandons a held group when a newer snapshot group rolls", async () expect(await consumer.latest()).toBeUndefined(); }); -// Skipping to the head never widens the reader's range: a capped reader reads the newest state -// below its cap, and a datagram past every group does not strand it. -test("latest stays inside the reader's range", async () => { +// Skipping to the head takes groups, not the track's largest position, so a datagram past every +// group does not strand it. +test("latest ignores a datagram past every group", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltas: false }); - const subscriber = track.subscribe({ delay: { max: REPLAY_LATENCY } }).withRange({ end: { excluded: 2n } }); - const consumer = new Consumer({ track: subscriber }); + const consumer = new Consumer({ track }); for (let n = 0; n < 4; n++) producer.update({ value: { a: n } }); track.appendDatagram(Time.Timestamp.now(), new Uint8Array([0])); - expect((await consumer.latest())?.value).toEqual({ a: 1 }); + expect((await consumer.latest())?.value).toEqual({ a: 3 }); producer.finish(); }); -// `next()` finishes the held group before the newer one, so a playhead sees every state. +// `next()` reads the held group's buffered frames before the newer one. test("next reads a held group out before a newer snapshot group", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - const consumer = new Consumer({ track: track.subscribe({ delay: { max: REPLAY_LATENCY } }) }); + const consumer = new Consumer({ track }); producer.update({ value: { a: 1 } }); expect((await consumer.next())?.value).toEqual({ a: 1 }); @@ -181,24 +188,98 @@ test("next reads a held group out before a newer snapshot group", async () => { expect(await consumer.next()).toBeUndefined(); }); -// Reading in order is still bounded: a group the subscription's max delay proves stale is skipped, -// as on any ordered track, so a reader that falls behind jumps ahead instead of replaying it. -test("next skips the groups the max delay abandons", async () => { +// A snapshot is superseded the moment a newer one exists, so the consumer subscribes at a zero +// budget whatever another reader of the track asks for: a reader that falls behind jumps to the +// newest group. +test("next skips every superseded group, whatever budget another reader asks for", async () => { const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: null }); const producer = new Producer({ track, deltas: false }); for (let n = 1; n <= 3; n++) producer.update({ value: { n }, at: Time.Timestamp.fromMillis(n * 1_000) }); producer.finish(); - expect(await drain(track.subscribe({ delay: { max: REPLAY_LATENCY } }))).toEqual([{ n: 1 }, { n: 2 }, { n: 3 }]); - expect(await drain(track.subscribe({ delay: { max: Milli(500) } }))).toEqual([{ n: 2 }, { n: 3 }]); - // The default of zero keeps only the newest group. - expect(await drain(track.subscribe())).toEqual([{ n: 3 }]); + for (const max of [Milli.zero, Milli(500), REPLAY_LATENCY, null]) { + const other = track.subscribe({ delay: { max } }); + expect(await drain(track)).toEqual([{ n: 3 }]); + other.close(); + } +}); + +// A session-fed track owes the groups between its arrivals. A snapshot reader never waits on one: +// group 2 arriving while group 1 is still owed supersedes it at once, whatever budget another +// reader of the track, such as the caller's own, asks for. +test("reads skip a group the subscription still owes", async () => { + for (const max of [Milli.zero, Milli(1_000), null]) { + const track = new Track.Producer("test").accept({}); + hooks.receiveTrack(track); + const other = track.subscribe({ delay: { max } }); + const latest = new Consumer({ track }); + const next = new Consumer({ track }); + const put = (sequence: bigint) => { + const group = track.createGroup(sequence); + group.writeFrame({ payload: new TextEncoder().encode(`{"n":${sequence}}`) }); + group.finish(); + }; + + put(0n); + expect((await latest.latest())?.value).toEqual({ n: 0 }); + expect((await next.next())?.value).toEqual({ n: 0 }); + const reads = [latest.latest(), next.next()]; + await sleep(Nano.fromMilli(Milli(1))); + put(2n); + expect((await Promise.all(reads)).map((state) => state?.value)).toEqual([{ n: 2 }, { n: 2 }]); + + // The owed group landing late is superseded, not delivered. + put(1n); + const ends = [latest.latest(), next.next()]; + track.finish(); + expect(await Promise.all(ends)).toEqual([undefined, undefined]); + other.close(); + track.close(); + } +}); + +// Closing the consumer ends a read already waiting, and every later one, without touching the +// group it was reading. +test("close ends a pending read", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + const consumer = new Consumer({ track }); + producer.update({ value: { a: 1 } }); + expect((await consumer.latest())?.value).toEqual({ a: 1 }); + + const pending = [consumer.latest(), consumer.next()]; + producer.update({ value: { a: 2 } }); + consumer.close(); + expect(await Promise.all(pending)).toEqual([undefined, undefined]); + // The subscription the consumer owned is gone. + expect(track.demand().wanted.peek()).toBeUndefined(); + expect(await consumer.latest()).toBeUndefined(); + producer.finish(); +}); + +// Reads share the consumer's group and decoder, so a read waiting on a group must finish before a +// later read moves on: otherwise the old group's delta lands on the newer group's snapshot. +test("overlapping reads take turns", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + const consumer = new Consumer({ track }); + producer.update({ value: { a: 1, keep: true } }); + expect((await consumer.next())?.value).toEqual({ a: 1, keep: true }); + + const next = consumer.next(); + producer.update({ value: { a: 2, keep: true } }); + producer.cut(); + producer.update({ value: { b: 3 } }); + const latest = consumer.latest(); + expect((await next)?.value).toEqual({ a: 2, keep: true }); + expect((await latest)?.value).toEqual({ b: 3 }); + producer.finish(); }); test("live consumer sees each update", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); for (let n = 1; n <= 3; n++) { producer.update({ value: { a: n } }); @@ -236,7 +317,7 @@ test("deltas reconstruct to the final value", async () => { producer.update({ value: { a: 5, b: 2 } }); producer.finish(); - expect((await drain(track.subscribe())).at(-1)).toEqual({ a: 5, b: 2 }); + expect((await drain(track)).at(-1)).toEqual({ a: 5, b: 2 }); }); // `mutate()` edits the shared document: multiple owners edit one producer, each touching its own @@ -245,7 +326,7 @@ test("deltas reconstruct to the final value", async () => { test("mutate composes independent owners", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, initial: {} }); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); producer.mutate((v) => { v.video = "v1"; @@ -262,7 +343,7 @@ test("mutate composes independent owners", async () => { test("mutate starts from the configured initial value", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, initial: {} }); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); producer.mutate((v) => { v.a = 1; @@ -291,7 +372,7 @@ test("a rejected mutate leaves the value at the last one written", async () => { v.scte35 = 42; }); producer.finish(); - expect(await drainLatest(track.subscribe())).toEqual([{ video: "v1", scte35: 42 }]); + expect(await drainLatest(track)).toEqual([{ video: "v1", scte35: 42 }]); }); test("mutate without a prior value or initial throws", () => { @@ -304,7 +385,7 @@ test("mutate without a prior value or initial throws", () => { test("mutate removes a section", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltas: true, initial: {} }); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); producer.mutate((v) => { v.a = 1; @@ -354,7 +435,7 @@ test("a joiner over the ratio gets a fresh snapshot", async () => { joiner.close(); expect(await structure(track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered())).toEqual([...layout]); - expect(await drainLatest(track.subscribe())).toEqual([{ n: 3 }]); + expect(await drainLatest(track)).toEqual([{ n: 3 }]); } }); @@ -424,14 +505,7 @@ test("a refresh after a rejected update restates the last written value", async joiner.close(); expect(await structure(track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered())).toEqual([4, 2]); - expect(await drain(track.subscribe({ delay: { max: REPLAY_LATENCY } }))).toEqual([ - { n: 0 }, - { n: 1 }, - { n: 2 }, - { n: 3 }, - { n: 3 }, - { n: 4 }, - ]); + expect(await drain(track)).toEqual([{ n: 3 }, { n: 4 }]); }); test("no ratio never refreshes", async () => { @@ -461,7 +535,7 @@ test("a compressed refresh opens a fresh group", async () => { joiner.close(); expect(await structure(track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered())).toEqual([2, 2]); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); const values: Value[] = []; for await (const { value } of consumer) values.push(value); expect(values).toEqual([ @@ -484,8 +558,8 @@ test("array change is a wholesale delta", async () => { test("a late joiner reads a buffered backlog state by state, or collapses it to the latest", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltas: true }); - const subscriber = track.subscribe(); - const collapsed = track.subscribe(); + const subscriber = new Consumer({ track }); + const collapsed = new Consumer({ track }); for (let n = 0; n <= 20; n++) { producer.update({ value: { n } }); } @@ -523,7 +597,7 @@ test("a rejected update leaves the previous value readable", async () => { producer.finish(); // A reader arriving now still finds the last good value, not an empty superseding group. - expect(await drain(track.subscribe())).toEqual([{ keep: true }]); + expect(await drain(track)).toEqual([{ keep: true }]); }); test("a delta that would overflow the snapshot rolls a new one instead", async () => { @@ -548,8 +622,7 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( expect(await subscriber.nextGroup()).toBeUndefined(); // The newest value is readable with no earlier frame to apply it to. - const values = await drain(track.subscribe({ delay: { max: REPLAY_LATENCY } })); - expect(values[values.length - 1]).toEqual({ v: "y".repeat(size) }); + expect(await drain(track)).toEqual([{ v: "y".repeat(size) }]); }); test("a delta that would push the snapshot out of the group's tail rolls a new group", () => { @@ -576,7 +649,7 @@ test("a snapshot past the budget is refused", () => { // moq-lite version reports as OLD. The reader skips to the newer snapshot instead of failing. test("snapshot consumer skips a group the publisher dropped mid-read", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); const first = track.appendGroup(); first.writeFrame({ payload: new TextEncoder().encode('{"v":0}'), timestamp: Time.Timestamp.now() }); expect((await consumer.latest())?.value).toEqual({ v: 0 }); @@ -591,7 +664,7 @@ test("snapshot consumer skips a group the publisher dropped mid-read", async () // A malformed or failed group must reach the caller; only an explicit retention gap is resumable. test("snapshot consumer propagates a non-gap frame failure", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); const group = track.appendGroup(); group.writeFrame({ payload: new TextEncoder().encode('{"ok":true}'), timestamp: Time.Timestamp.now() }); expect((await consumer.next())?.value).toEqual({ ok: true }); @@ -632,7 +705,7 @@ test("an untimed state reads back untimed", async () => { producer.update({ value: { a: 2, b: "x".repeat(64) } }); producer.finish(); - const consumer = new Consumer({ track: track.subscribe() }); + const consumer = new Consumer({ track }); expect(await consumer.next()).toEqual({ value: { a: 1, b: "x".repeat(64) }, at: undefined }); expect(await consumer.next()).toEqual({ value: { a: 2, b: "x".repeat(64) }, at: undefined }); }); @@ -647,8 +720,7 @@ test("each state reads back with its frame's timestamp", async () => { } producer.finish(); - const subscription = { delay: { max: REPLAY_LATENCY } }; - const consumer = new Consumer({ track: track.subscribe(subscription) }); + const consumer = new Consumer({ track }); const states: [unknown, number | undefined][] = []; for await (const { value, at } of consumer) states.push([value.n, at?.as(Time.Timescale.MILLI)]); expect(states).toEqual([ @@ -657,7 +729,7 @@ test("each state reads back with its frame's timestamp", async () => { [3, 3_000], ]); - const latest = new Consumer({ track: track.subscribe(subscription) }); + const latest = new Consumer({ track }); const head = await latest.latest(); expect(head?.value.n).toBe(3); expect(head?.at?.as(Time.Timescale.MILLI)).toBe(3_000); diff --git a/js/json/src/types.test.ts b/js/json/src/types.test.ts index 1da9d1c861d..68b72b0ae1f 100644 --- a/js/json/src/types.test.ts +++ b/js/json/src/types.test.ts @@ -23,7 +23,7 @@ test("track-owning wrappers take one options object", () => { expect(arities).toEqual([1, 1, 1, 1, 1, 1]); const producerTrack: SnapshotProducerInit["track"] = new Track.Producer("test"); - const consumerTrack: SnapshotConsumerInit["track"] = producerTrack.subscribe(); + const consumerTrack: SnapshotConsumerInit["track"] = producerTrack; expect(producerTrack).toBeDefined(); expect(consumerTrack).toBeDefined(); }); @@ -51,16 +51,17 @@ test("consumer options omit producer-only knobs", () => { }); test("object literals reject producer knobs and positional tracks", () => { - const track = new Track.Producer("test").subscribe(); + const source = new Track.Producer("test"); + const track = source.subscribe(); const reject = () => { // @ts-expect-error deltas is producer-only - new Snapshot.Consumer({ track, deltas: true }); + new Snapshot.Consumer({ track: source, deltas: true }); // @ts-expect-error initial is producer-only - new Snapshot.Consumer({ track, initial: {} }); + new Snapshot.Consumer({ track: source, initial: {} }); // @ts-expect-error a positional track is not an options object - new Snapshot.Consumer(track); - // @ts-expect-error a producer track is not a subscriber - new Snapshot.Consumer({ track: new Track.Producer("test") }); + new Snapshot.Consumer(source); + // @ts-expect-error a snapshot consumer subscribes itself, so it takes the track, not a subscriber + new Snapshot.Consumer({ track }); // @ts-expect-error ops is producer-only new Window.Consumer({ track, ops: true }); // @ts-expect-error checkpointRecords is producer-only diff --git a/js/json/tsconfig.build.json b/js/json/tsconfig.build.json index b0d79fdc2cb..b58733f6162 100644 --- a/js/json/tsconfig.build.json +++ b/js/json/tsconfig.build.json @@ -3,5 +3,8 @@ // are neither published nor discovered by `bun test` at the package root. // `tsc --noEmit` still uses tsconfig.json, so tests stay type-checked. "extends": "./tsconfig.json", + "compilerOptions": { + "rootDir": "./src" + }, "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"] } diff --git a/js/json/tsconfig.json b/js/json/tsconfig.json index bb55d7c43fc..a1bf54c031e 100644 --- a/js/json/tsconfig.json +++ b/js/json/tsconfig.json @@ -2,7 +2,9 @@ "extends": "../tsconfig.json", "compilerOptions": { "outDir": "dist", - "rootDir": "./src", + // The snapshot test borrows `@moq/net`'s internal hooks by relative path, so the + // type-check spans the workspace. The build pins `rootDir` to src and skips tests. + "rootDir": "..", "types": ["bun"] }, "include": ["src"] diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index 0a043641b3a..bbfff3d1d06 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -269,13 +269,15 @@ export class Game { const active = effect.get(this.broadcast.out.active); if (!active) return; - const statusTrack = active.track("status").subscribe({ ...Moq.Track.Subscription.default(), priority: 10 }); - effect.cleanup(() => statusTrack.close()); - // Reconstruct each status from snapshots and deltas, validated against the schema. - const consumer = new Json.Snapshot.Consumer({ track: statusTrack, schema: GameStatusSchema }); + const consumer = new Json.Snapshot.Consumer({ + track: active.track("status"), + schema: GameStatusSchema, + priority: 10, + }); + effect.cleanup(() => consumer.close()); - // Closing the track on cleanup unblocks a pending latest() (it returns undefined), so the loop + // Closing the consumer on cleanup unblocks a pending latest() (it returns undefined), so the loop // ends without racing the teardown. effect.spawn(async () => { for (;;) { diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 1245dfcd199..5481f530ab5 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1187,6 +1187,29 @@ test("an ordered reader takes a replaced copy's buffered group before the new co b.close(); }); +test("a routed read right after an update picks its group under the new preferences", async () => { + const front = new Front(); + const a = new BroadcastProducer(); + const ta = copy(a); + front.serve(a.consume()); + const ordered = front.consumer + .track("seq") + .subscribe({ delay: { max: null } }) + .ordered(); + try { + ta.write(0n); + ta.write(1n); + await settle(); + // The copy learns of the update a microtask later; the read must not pick under its old budget. + ordered.update({ delay: { max: Milli.zero } }); + expect(ordered.tryNextGroup()?.sequence).toBe(1n); + } finally { + ordered.close(); + front.consumer.close(); + a.close(); + } +}); + for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { test(`an ordered resumed reader keeps an older copy's owed hole until ${resolution}`, async () => { const clock = new Manual(); diff --git a/js/publish/bench/catalog.ts b/js/publish/bench/catalog.ts index a3b47134380..d05f37d7c05 100644 --- a/js/publish/bench/catalog.ts +++ b/js/publish/bench/catalog.ts @@ -27,10 +27,8 @@ async function measure(tracks: number, viewers: number, clock: Manual) { const output = new Track.Producer("catalog.json"); catalog.serve(output, scope); const subscribers = Array.from({ length: viewers }, () => { - const subscriber = output.subscribe(); return { - subscriber, - catalog: new Json.Snapshot.Consumer({ track: subscriber }), + catalog: new Json.Snapshot.Consumer({ track: output }), media: media.map((track) => track.subscribe()), }; }); @@ -81,7 +79,7 @@ async function measure(tracks: number, viewers: number, clock: Manual) { publishing.close(); output.close(); for (const viewer of subscribers) { - viewer.subscriber.close(); + viewer.catalog.close(); for (const track of viewer.media) track.close(); } for (const track of media) track.close(); diff --git a/js/publish/src/announce.test.ts b/js/publish/src/announce.test.ts index d943d4c0187..e27e66923be 100644 --- a/js/publish/src/announce.test.ts +++ b/js/publish/src/announce.test.ts @@ -176,8 +176,7 @@ test("capture gaps keep the broadcast instance and its track sequences", async ( const active: boolean[] = []; const stop = request.active.subscribe((value) => active.push(value !== undefined)); const media = net.track("audio").subscribe(); - const catalogTrack = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: catalogTrack }); + const catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); try { await catalog.latest(); await settle(); @@ -212,7 +211,7 @@ test("capture gaps keep the broadcast instance and its track sequences", async ( stop(); request.close(); media.close(); - catalogTrack.close(); + catalog.close(); } }); diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 782483b1afd..f31e1f2ffe5 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -882,7 +882,7 @@ test("audio failure stays local through demand changes and capture format re-arm const encoder = new Encoder("audio", { broadcast, capture: capture as never, bandwidth, enabled }); let subscriber: Moq.Track.Subscriber | undefined; let siblingSubscriber: Moq.Track.Subscriber | undefined; - let catalogSubscriber: Moq.Track.Subscriber | undefined; + let catalog: Json.Snapshot.Consumer | undefined; let recovered: Moq.Track.Subscriber | undefined; const push = async (first: number, channels: number) => { for (let i = 0; i < 3; i++) { @@ -912,8 +912,7 @@ test("audio failure stays local through demand changes and capture format re-arm expect(siblingTrack.appendGroup().sequence).toBe(0n); await push(0, 1); expect((await subscriber.largest())?.group).toBe(0n); - catalogSubscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: catalogSubscriber }); + catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); expect((await catalog.latest())?.value.audio?.renditions.audio?.enabled).not.toBe(false); const live = LaggingAudioEncoder.instances.at(-1); if (!live) throw new Error("expected live audio encoder"); @@ -963,7 +962,7 @@ test("audio failure stays local through demand changes and capture format re-arm } finally { subscriber?.close(); siblingSubscriber?.close(); - catalogSubscriber?.close(); + catalog?.close(); recovered?.close(); encoder.close(); bandwidth.close(); @@ -978,7 +977,7 @@ test("an audio failure without demand still recovers under a fresh track name", const broadcast = new Broadcast({ origin: new Moq.Origin.Producer(), name: Moq.Path.from("idle.hang") }); const configuring = configured(); const encoder = new Encoder("audio", { broadcast, capture: fakeCapture(new Feed()) as never }); - let catalogSubscriber: Moq.Track.Subscriber | undefined; + let catalog: Json.Snapshot.Consumer | undefined; try { await configuring; await settle(); @@ -998,15 +997,14 @@ test("an audio failure without demand still recovers under a fresh track name", encoder.codec.set({ mime: "opus", bitrate: 64_000 }); await reconfiguring; await settle(); - catalogSubscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: catalogSubscriber }); + catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); const config = (await catalog.latest())?.value.audio?.renditions.audio; expect(config?.track).toBeDefined(); expect(config?.track).not.toBe("audio"); expect(encoder.out.error.peek()).toBeUndefined(); expect(broadcast.net.peek()).toBe(net); } finally { - catalogSubscriber?.close(); + catalog?.close(); encoder.close(); broadcast.close(); } @@ -1024,7 +1022,7 @@ test.each(["failure first", "config first"])( }); const configuring = configured(); const encoder = new Encoder("audio", { broadcast, capture: fakeCapture(new Feed()) as never }); - let catalogSubscriber: Moq.Track.Subscriber | undefined; + let catalog: Json.Snapshot.Consumer | undefined; try { await configuring; await settle(); @@ -1038,8 +1036,7 @@ test.each(["failure first", "config first"])( if (order === "failure first") encoder.codec.set({ mime: "opus", bitrate: 64_000 }); await reconfiguring; await settle(); - catalogSubscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: catalogSubscriber }); + catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); const config = (await catalog.latest())?.value.audio?.renditions.audio; expect(config?.track).toBeDefined(); expect(config?.track).not.toBe("audio"); @@ -1048,7 +1045,7 @@ test.each(["failure first", "config first"])( expect(encoder.out.active.peek()).toBe(true); expect(broadcast.net.peek()).toBe(net); } finally { - catalogSubscriber?.close(); + catalog?.close(); encoder.close(); broadcast.close(); } @@ -1126,7 +1123,7 @@ test("an audio-only broadcast declares its group spacing as the join interval", const configuring = configured(); // 20 ms Opus frames start a group every two frames for a 30 ms duration. const encoder = new Encoder("audio", { broadcast, capture: fakeCapture(feed) as never, groupDuration: Milli(30) }); - let catalog: Moq.Track.Subscriber | undefined; + let catalog: Json.Snapshot.Consumer | undefined; try { await configuring; await settle(); @@ -1134,8 +1131,8 @@ test("an audio-only broadcast declares its group spacing as the join interval", if (!net) throw new Error("expected network broadcast"); expect(encoder.out.active.peek()).toBe(false); - catalog = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const root = (await new Json.Snapshot.Consumer({ track: catalog }).latest())?.value; + catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); + const root = (await catalog.latest())?.value; expect(root?.media?.join).toEqual({ interval: Catalog.u53(40) }); expect(root?.audio?.renditions.audio).toBeDefined(); expect(root?.audio?.renditions.audio).not.toHaveProperty("hls"); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 9b77f2a5388..958711b2a03 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -20,7 +20,7 @@ async function readCatalog(broadcast: Broadcast): Promise({ track: track.subscribe() }).latest())?.value; + const catalog = (await new Json.Snapshot.Consumer({ track }).latest())?.value; effect.close(); return catalog; } @@ -117,19 +117,18 @@ test("shared Rust stats names survive the publisher's report builder", async () await settle(); const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer"); - const subscriber = net.track(Broadcast.STATS_TRACK).subscribe(); + const consumer = new Json.Snapshot.Consumer({ + track: net.track(Broadcast.STATS_TRACK), + schema: Stats.SnapshotSchema, + }); try { - const consumer = new Json.Snapshot.Consumer({ - track: subscriber, - schema: Stats.SnapshotSchema, - }); await settle(); await clock.advance(Nano.fromMilli(Milli(1000))); const reported = (await consumer.latest())?.value.renditions ?? {}; expect(Object.keys(reported).sort()).toEqual(Object.keys(fixture.renditions ?? {}).sort()); expect(reported).toEqual(fixture.renditions ?? {}); } finally { - subscriber.close(); + consumer.close(); } } finally { broadcast.close(); @@ -319,12 +318,12 @@ test("serves the catalog through a shared static track", async () => { const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); - const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = (await new Json.Snapshot.Consumer({ track: subscriber }).latest())?.value; + const reader = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); + const catalog = (await reader.latest())?.value; expect(catalog?.video?.renditions.video?.codec).toBe("avc1.640028"); // Dropping the subscriber closes the served track; the broadcast keeps running for the next viewer. - subscriber.close(); + reader.close(); await settle(); expect(broadcast.net.peek()).toBe(net); @@ -560,15 +559,15 @@ test("keeps the current catalog snapshot for a reconnecting viewer", async () => const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); - const first = net.track(Broadcast.CATALOG_TRACK).subscribe(); - expect((await new Json.Snapshot.Consumer({ track: first }).latest())?.value.video).toBeDefined(); + const first = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); + expect((await first.latest())?.value.video).toBeDefined(); first.close(); // A reconnect past the idle cache window must still receive the live track's newest // snapshot instead of waiting forever for an edit that may never come. await clock.advance(Nano.fromMilli(Milli(60_000))); - const second = net.track(Broadcast.CATALOG_TRACK).subscribe(); - expect((await new Json.Snapshot.Consumer({ track: second }).latest())?.value.video).toBeDefined(); + const second = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); + expect((await second.latest())?.value.video).toBeDefined(); second.close(); broadcast.close(); @@ -621,7 +620,7 @@ test("a served decoder identity change moves the rendition to a fresh track name const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const instance = announced?.active.peek()?.instance; const catalog = new Json.Snapshot.Consumer({ - track: net.track(Broadcast.CATALOG_TRACK).subscribe(), + track: net.track(Broadcast.CATALOG_TRACK), }); const first = net.track("video").subscribe(); try { @@ -870,7 +869,7 @@ test("identity changes before the first announce take a fresh track name", async const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); const catalog = new Json.Snapshot.Consumer({ - track: net.track(Broadcast.CATALOG_TRACK).subscribe(), + track: net.track(Broadcast.CATALOG_TRACK), }); const config = (await catalog.latest())?.value.video?.renditions.video; expect(config?.codec).toBe("vp8"); @@ -912,9 +911,8 @@ test("stats names a track in the catalog and reports each listed rendition while const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); - const subscriber = net.track(Broadcast.STATS_TRACK).subscribe(); const consumer = new Json.Snapshot.Consumer({ - track: subscriber, + track: net.track(Broadcast.STATS_TRACK), schema: Stats.SnapshotSchema, }); await settle(); @@ -924,7 +922,7 @@ test("stats names a track in the catalog and reports each listed rendition while transport: { rtt: 12 }, renditions: { video: { frames: 3, bytes: 300, keyframes: 1, skipped: 2, bitrate: 1_000_000 } }, }); - subscriber.close(); + consumer.close(); stats.set(false); await settle(); diff --git a/js/publish/src/catalog.test.ts b/js/publish/src/catalog.test.ts index 786eda35991..4d0fa97043c 100644 --- a/js/publish/src/catalog.test.ts +++ b/js/publish/src/catalog.test.ts @@ -17,7 +17,7 @@ test("catalog producer seeds subscribers and fans out edits", async () => { const effect = new Effect(); const track = new Track.Producer("catalog.json"); catalog.serve(track, effect); - const consumer = new Json.Snapshot.Consumer({ track: track.subscribe() }); + const consumer = new Json.Snapshot.Consumer({ track }); // A new subscriber is seeded with the current catalog. expect((await consumer.latest())?.value.video).toEqual({ renditions: {} }); @@ -57,7 +57,7 @@ test("catalog producer computes the version from the fields it uses", async () = const effect = new Effect(); const track = new Track.Producer("catalog.json"); catalog.serve(track, effect); - const consumer = new Json.Snapshot.Consumer({ track: track.subscribe() }); + const consumer = new Json.Snapshot.Consumer({ track }); const video = { codec: "avc1.64001f", container: { kind: "legacy" as const } }; // A caller's own version is replaced by the computed one. @@ -116,7 +116,7 @@ test("catalog producer advertises the page clock from the first snapshot", async const effect = new Effect(); const track = new Track.Producer("catalog.json"); catalog.serve(track, effect); - const consumer = new Json.Snapshot.Consumer({ track: track.subscribe() }); + const consumer = new Json.Snapshot.Consumer({ track }); // Before any rendition: a live-only publisher exposes its clock. const first = Catalog.RootSchema.parse((await consumer.latest())?.value); @@ -180,7 +180,7 @@ test("a reconnecting subscriber is seeded with the full current catalog", async const effect = new Effect(); const track = new Track.Producer("catalog.json"); catalog.serve(track, effect); - const seeded = (await new Json.Snapshot.Consumer({ track: track.subscribe() }).latest())?.value; + const seeded = (await new Json.Snapshot.Consumer({ track }).latest())?.value; expect(seeded?.video).toEqual({ renditions: {} }); expect(seeded?.scte35).toEqual({ splices: [] }); @@ -352,7 +352,7 @@ describe("estimate publication window", () => { scopes.push(effect); const track = new Track.Producer("catalog.json"); producer.serve(track, effect); - const consumer = new Json.Snapshot.Consumer({ track: track.subscribe() }); + const consumer = new Json.Snapshot.Consumer({ track }); const estimate = (jitter: number) => producer.mutate((catalog) => { if (!catalog.video) throw new Error("video missing"); @@ -441,7 +441,7 @@ describe("estimate publication window", () => { scopes.push(again); const track = new Track.Producer("catalog.json"); producer.serve(track, again); - const reader = new Json.Snapshot.Consumer({ track: track.subscribe() }); + const reader = new Json.Snapshot.Consumer({ track }); await reader.latest(); estimate(3); expect((await reader.latest())?.value.video?.renditions.v.jitter).toBe(Catalog.u53(3)); diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index a30af1dfd90..5196eafd431 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -325,7 +325,7 @@ async function readCatalog(broadcast: Broadcast): Promise({ track: track.subscribe() }).latest())?.value; + return (await new Json.Snapshot.Consumer({ track }).latest())?.value; } finally { effect.close(); } @@ -1337,16 +1337,15 @@ test("an on-demand rendition declares its keyframe interval, and a media subscri capture: recording.capture as never, config, }); - const subscribers: Moq.Track.Subscriber[] = []; + const subscribers: { close(): void }[] = []; try { await settle(); const net = broadcast.net.peek(); if (!net) throw new Error("expected network broadcast"); expect(encoder.out.active.peek()).toBe(false); - const catalogSubscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - subscribers.push(catalogSubscriber); - const catalog = new Json.Snapshot.Consumer({ track: catalogSubscriber }); + const catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); + subscribers.push(catalog); const first = (await catalog.latest())?.value; expect(first?.media?.join).toEqual({ interval: Catalog.u53(3000) }); expect(first?.video?.renditions.video).not.toHaveProperty("hls"); @@ -1467,7 +1466,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh const encoder = new Encoder("video/hd", { broadcast, capture: capture as never, bandwidth, enabled, config: {} }); let subscriber: Moq.Track.Subscriber | undefined; let siblingSubscriber: Moq.Track.Subscriber | undefined; - let catalogSubscriber: Moq.Track.Subscriber | undefined; + let catalog: Json.Snapshot.Consumer | undefined; let recovered: Moq.Track.Subscriber | undefined; let announced: Moq.Origin.Following | undefined; try { @@ -1487,8 +1486,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh const siblingTrack = sibling.track.peek(); if (!siblingTrack) throw new Error("expected demanded sibling track"); expect(siblingTrack.appendGroup().sequence).toBe(0n); - catalogSubscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: catalogSubscriber }); + catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); expect((await catalog.latest())?.value.video?.renditions["video/hd"]?.enabled).not.toBe(false); const live = FakeVideoEncoder.instances.find((instance) => instance.state === "configured"); if (!live) throw new Error("expected live video encoder"); @@ -1550,7 +1548,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh } finally { subscriber?.close(); siblingSubscriber?.close(); - catalogSubscriber?.close(); + catalog?.close(); recovered?.close(); encoder.close(); bandwidth.close(); @@ -2043,8 +2041,7 @@ test("ceiling growth updates the served track in place", async () => { const encoder = new Encoder("video", { broadcast, capture: capture as never, config: { frameRate: 60 } }); const net = broadcast.net.peek() ?? (await broadcast.net.changed()); if (!net) throw new Error("expected a network broadcast"); - const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe(); - const catalog = new Json.Snapshot.Consumer({ track: subscriber }); + const catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK) }); const next = async (done: (config: Catalog.VideoConfig) => boolean) => { for (;;) { const config = (await catalog.latest())?.value.video?.renditions.video; @@ -2068,7 +2065,7 @@ test("ceiling growth updates the served track in place", async () => { expect(grown.track).toBeUndefined(); expect(broadcast.net.peek()).toBe(net); } finally { - subscriber.close(); + catalog.close(); encoder.close(); broadcast.close(); } diff --git a/js/room/src/metadata.test.ts b/js/room/src/metadata.test.ts index 040db2017bd..6fbf32ef956 100644 --- a/js/room/src/metadata.test.ts +++ b/js/room/src/metadata.test.ts @@ -30,13 +30,12 @@ test("metadata updates keep the same track and reach an existing subscriber", as try { serve(broadcast, user, new Signal({}), effect); await flush(); - const track = net.consume().track(TRACK.user).subscribe(); - const consumer = new Json.Snapshot.Consumer<{ name: string }>({ track }); + const consumer = new Json.Snapshot.Consumer<{ name: string }>({ track: net.consume().track(TRACK.user) }); expect((await consumer.latest())?.value.name).toBe("Alice"); user.name.set("Bob"); await flush(); expect((await consumer.latest())?.value.name).toBe("Bob"); - track.close(); + consumer.close(); } finally { effect.close(); net.close(); diff --git a/js/room/src/metadata.ts b/js/room/src/metadata.ts index 9ad2a3a4c42..d688abfd547 100644 --- a/js/room/src/metadata.ts +++ b/js/room/src/metadata.ts @@ -267,10 +267,9 @@ function subscribeJson( effect: Effect, update: (value: T) => void, ): void { - const track = broadcast.track(name).subscribe({ ...Moq.Track.Subscription.default(), priority: PRIORITY }); - effect.cleanup(() => track.close()); + const consumer = new Json.Snapshot.Consumer({ track: broadcast.track(name), schema, priority: PRIORITY }); + effect.cleanup(() => consumer.close()); - const consumer = new Json.Snapshot.Consumer({ track, schema }); effect.spawn(async () => { for (;;) { let state: Moq.Timed | undefined; diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 7afc89bd87e..986e4de0626 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -383,20 +383,23 @@ export class Broadcast { this.#out.status.set("loading"); - const trackName = format === "hang" ? Catalog.TRACK : "catalog"; - const track = broadcast.track(trackName).subscribe({ - ...Track.Subscription.default(), - priority: Catalog.PRIORITY.catalog, - }); - effect.cleanup(() => track.close()); - // The hang catalog is reconstructed from snapshots (and future deltas) via @moq/json, which reads - // it compressed or not; MSF stays on its own one-blob-per-group fetch. + // it compressed or not and subscribes itself; MSF stays on its own one-blob-per-group fetch. let fetchNext: () => Promise; if (format === "hang") { - const consumer = new Json.Snapshot.Consumer({ track, schema: Catalog.RootSchema }); + const consumer = new Json.Snapshot.Consumer({ + track: broadcast.track(Catalog.TRACK), + schema: Catalog.RootSchema, + priority: Catalog.PRIORITY.catalog, + }); + effect.cleanup(() => consumer.close()); fetchNext = async () => (await consumer.latest())?.value; } else { + const track = broadcast.track("catalog").subscribe({ + ...Track.Subscription.default(), + priority: Catalog.PRIORITY.catalog, + }); + effect.cleanup(() => track.close()); const ordered = track.ordered(); fetchNext = async () => { const update = await Msf.fetch(ordered); diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index 9a8b4df402b..3eea05958dd 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -44,12 +44,14 @@ async function read(origin: Origin.Producer, path: string, clock: Manual): Promi await flush(); const broadcast = request.active.peek(); if (!broadcast) throw new Error(`no feedback at ${path}`); - const track = broadcast.track(Schema.TRACK).subscribe(); - const consumer = new Json.Snapshot.Consumer({ track, schema: Schema.SnapshotSchema }); + const consumer = new Json.Snapshot.Consumer({ + track: broadcast.track(Schema.TRACK), + schema: Schema.SnapshotSchema, + }); await flush(); await clock.advance(Nano.fromMilli(Milli(1000))); const value = (await consumer.latest())?.value; - track.close(); + consumer.close(); request.close(); return value; } diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index b89c3445109..92423abd12b 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -16,6 +16,10 @@ Replace stream-track `appendDatagram` / `insertDatagram` / `recvDatagram` with ` A null `TrackInfo.maxAge`, the default, and a null info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited = true`, which ignores `maxAge`, where you relied on null meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`SnapshotConsumer(broadcast, name, priority)` takes the `BroadcastConsumer` and the track name instead of a `TrackConsumer`, and subscribes to the track itself at a zero `delay.max` and `priority` (default 0). Drop the `subscribeTrack` call; a refused subscription now throws from the first read. `values()` skips every group a newer one supersedes, and `latest()` no longer waits for a lower group the track still owes. Publish a stream track when every state must survive, or a window track for a bounded recent history. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. @@ -52,7 +56,7 @@ A fixed audio playout delay `d` is `delay = Delay(min = d, max = ...)` with `est `dev.moq.flate` is removed: publish opaque bytes on a `TrackProducer`. `SnapshotConfig` and `WindowConfig` lose `compression`, and `StreamConfig` is removed. Publish the track with `TrackInfo(compress = true)` instead. -`StreamProducer` drops its config argument, and `SnapshotConsumer`, `StreamConsumer`, and `WindowConsumer` take only the track. +`StreamProducer` drops its config argument, and `StreamConsumer` and `WindowConsumer` take only the track. `SnapshotConsumer` takes the broadcast and track name; see the entry above. ### Paths with an empty segment are refused ([#6648](https://github.com/moq-dev/moq/pull/6648)) @@ -187,7 +191,7 @@ Application calls are unchanged. ### JSON consumers emit timestamps (#5677) `values()` emits `json.Value` (`value`, plus `timestamp` as a `Duration?`) instead of a string, and `valuesAs()` emits `Timed(value, timestamp)`. -A snapshot consumer's `next()` now yields every state in order; call `latest()` for the newest. +A snapshot consumer's `next()` now yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); call `latest()` for the newest. Timestamps are rounded down to a whole microsecond. ### Ranges filter reads (#5929) diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt index 2d938cb8b76..8804be16c2c 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -12,7 +12,7 @@ package dev.moq.json // val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL, compress = true)) // val status = SnapshotProducer(broadcast, track, SnapshotConfig()) // status.update(Status(state = "live"), CatalogProducer(broadcast).now()) -// val reader = SnapshotConsumer(consumer.subscribeTrack("status", null)) +// val reader = SnapshotConsumer(consumer, "status") import dev.moq.MoqJson import dev.moq.Timestamp @@ -24,7 +24,7 @@ import kotlinx.serialization.serializer /** Publishes lossy latest-value JSON snapshots on a track it takes over. */ typealias SnapshotProducer = uniffi.moq.MoqJsonSnapshotProducer -/** Consumes reconstructed latest-value JSON snapshots from a track it takes over. */ +/** Consumes reconstructed latest-value JSON snapshots from a track it subscribes to itself. */ typealias SnapshotConsumer = uniffi.moq.MoqJsonSnapshotConsumer /** Publishes a lossless stream of JSON records on a track it takes over. */ @@ -100,8 +100,8 @@ inline fun WindowEventPush.decode(): T = /** * Stream of each JSON state from a snapshot track, in order. * - * Groups older than the subscription's `delay.max` are skipped, so a playhead reader sets that - * budget to its distance behind live. Call [SnapshotConsumer.latest] to skip to the newest state. + * Skips every group a newer one supersedes, at the zero `delay.max` the consumer subscribes with. + * Call [SnapshotConsumer.latest] to skip to the newest state. */ fun SnapshotConsumer.values(): Flow = pull({ cancel() }) { next() } diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index cf7bb7aacb4..013cfaf18ff 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -559,7 +559,7 @@ class SmokeTest { val config = SnapshotConfig(deltas = true) val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000_000uL)) SnapshotProducer(broadcast, track, config).use { producer -> - val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) + val consumer = SnapshotConsumer(broadcast.consume(), "status") for (n in 1..4) producer.update( Status(state = "live$n"), timestamp = n.milliseconds.toTimestamp(), @@ -629,7 +629,7 @@ class SmokeTest { assertEquals("status", demand.name()) assertEquals(null, demand.wanted()) - val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) + val consumer = SnapshotConsumer(broadcast.consume(), "status") while (demand.wantedChanged() == null) {} consumer.cancel() while (demand.wantedChanged() != null) {} @@ -647,7 +647,7 @@ class SmokeTest { val demand: TrackDemand = producer.demand() producer.update(Status(state = "live"), Timestamp(1uL, 1_000uL)) - val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) + val consumer = SnapshotConsumer(broadcast.consume(), "status") while (demand.wantedChanged() == null) {} // `first` cancels the collection, which must release the subscription without an // explicit cancel. @@ -669,7 +669,7 @@ class SmokeTest { SnapshotProducer(broadcast, track, config).use { producer -> producer.update("""{"state":"raw"}""", Timestamp(1uL, 1_000uL)) - val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) + val consumer = SnapshotConsumer(broadcast.consume(), "status") assertEquals( Timed(Status(state = "raw"), Timestamp(1uL, 1_000uL)), consumer.valuesAs().first(), diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 848cb645a9f..9fdbbcff993 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -16,6 +16,10 @@ Replace stream-track `append_datagram` / `insert_datagram` / `recv_datagram` wit `TrackInfo.max_age` defaults to `timedelta(0)`, like `Delay.max`, so a bare `TrackInfo()` and an omitted one now advertise a zero max age, serving only the live edge, instead of no publisher limit. `None` still means no limit: pass `max_age=None` where you relied on the default. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`moq.json.SnapshotConsumer(broadcast, name, *, priority=0)` takes the `BroadcastConsumer` and the track name instead of a `TrackConsumer`, and subscribes to the track itself at a zero `delay.max` and `priority`. Drop the `subscribe_track` call; a refused subscription now raises from the first read. Iteration skips every group a newer one supersedes, and `latest()` no longer waits for a lower group the track still owes. Publish a stream track when every state must survive, or a window track for a bounded recent history. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `moq.Error.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `set_target` and `Viewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. @@ -183,7 +187,7 @@ and native library together; application calls are unchanged. ### JSON consumers yield `json.Timed` (#5677) `json.SnapshotConsumer` and `json.StreamConsumer` yield `Timed(value, timestamp)` instead of the bare value; `timestamp` is a `timedelta`, or `None` when untimed. -Iterating a snapshot consumer now yields every state in order; `await consumer.latest()` returns the newest. +Iterating a snapshot consumer now yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); `await consumer.latest()` returns the newest. Timestamps are rounded down to a whole microsecond. ### Ranges filter reads (#5929) diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index 062ecf3a98f..eab20bfbca4 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -134,13 +134,15 @@ def finish(self) -> None: class SnapshotConsumer(_Stream[Timed]): """Async iterator over a JSON snapshot track, yielding each state in order (lossy). - Each item is a :class:`Timed`. Groups older than the subscription's ``delay.max`` are skipped, - so a playhead reader sets that budget to its distance behind live; :meth:`latest` skips to the - newest state instead. Usable as an async context manager that cancels on exit. + Each item is a :class:`Timed`. Every group a newer one supersedes is skipped; :meth:`latest` + skips to the newest state instead. The consumer subscribes to the track ``name`` on + ``broadcast`` itself, at a zero ``delay.max`` and ``priority`` (higher first); a read waits for + that subscription and raises if it fails. Usable as an async context manager that cancels on + exit. """ - def __init__(self, track: subscribe.TrackConsumer) -> None: - self._inner = MoqJsonSnapshotConsumer(track._inner) + def __init__(self, broadcast: subscribe.BroadcastConsumer, name: str, *, priority: int = 0) -> None: + self._inner = MoqJsonSnapshotConsumer(broadcast._inner, name, priority) async def _next(self) -> Timed | None: return Timed._from_ffi(await self._inner.next()) diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 4fb0d3010af..0e8a01b560f 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -559,7 +559,7 @@ async def test_json_snapshot_roundtrip(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000, compress=True)) producer = moq.json.SnapshotProducer(broadcast, track) - consumer = moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("status")) + consumer = moq.json.SnapshotConsumer(broadcast.consume(), "status") for viewers in range(1, 5): producer.update({"viewers": viewers}, moq.Timestamp(viewers, 1_000)) @@ -686,7 +686,7 @@ async def test_json_producers_report_demand(): assert snapshot_demand.wanted() is None consumer = broadcast.consume() - snapshot_consumer = moq.json.SnapshotConsumer(await consumer.subscribe_track("status")) + snapshot_consumer = moq.json.SnapshotConsumer(consumer, "status") stream_consumer = moq.json.StreamConsumer(await consumer.subscribe_track("events")) await asyncio.wait_for(until_wanted(snapshot_demand), timeout=5.0) await asyncio.wait_for(until_wanted(stream_demand), timeout=5.0) @@ -1805,7 +1805,7 @@ async def assert_cancelled(awaitable) -> None: await assert_cancelled(track_dynamic.requested_fill()) snapshot = moq.json.SnapshotProducer(broadcast, broadcast.publish_track("state", moq.TrackInfo(timescale=1_000))) - async with moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("state")) as snapshot_consumer: + async with moq.json.SnapshotConsumer(broadcast.consume(), "state") as snapshot_consumer: pass await assert_cancelled(anext(snapshot_consumer)) diff --git a/quest/m1/README.md b/quest/m1/README.md index 23dc7549706..a2fbd3826a4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -177,7 +177,6 @@ their end report, so an embedder's drain alert pages on real cuts. - [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh - [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them - [Poll-first async](/quest/m1/poll-first/README.md) - library crates compile no coroutines by default: async wrappers are generated from `poll_*` and gated behind an `async` feature -- [Ordered reads can skip owed holes, and snapshot latest() does](/quest/m1/ordered-owed-holes.md) - moq-net's `Ordered` gains a read that skips past an owed hole to the newest buffered group, while keeping the reader's bounds - [The relay reports native sessions it force-closes at the drain deadline](/quest/m1/relay-drain-cuts.md) - the drain's public outcome and live tally separate sessions cut while open from sessions only finishing their end report, so an embedder's drain alert pages on real cuts - [A Rust relay never replays from group 0 to a lite-03/04 subscriber](/quest/m1/relay-inflight-replay.md) - A Rust relay or publisher serving a lite-03 or lite-04 SUBSCRIBE from a track copy that is still resolving starts at the newest group once the copy resolves - [Rename moq-rtc to moq-webrtc](/quest/m1/webrtc-rename.md) - one published `moq-webrtc` crate holds the gateway, the ICE driver, and the data-channel transport diff --git a/quest/m1/ordered-owed-holes.md b/quest/m1/ordered-owed-holes.md deleted file mode 100644 index 994c6a7139d..00000000000 --- a/quest/m1/ordered-owed-holes.md +++ /dev/null @@ -1,42 +0,0 @@ -# [M] Ordered reads can skip owed holes, and snapshot latest() does - -## Goal - -moq-net's `Ordered` gains a read that skips past an owed hole to the newest -buffered group, while keeping the reader's bounds (range, budget, delivered -set). `moq_json::snapshot::Consumer::latest()` moves onto it, so on a -received track with a nonzero or unlimited `max_delay` it returns the newest -buffered snapshot at once instead of waiting for an owed lower group. The -`poll_latest` caveat goes. `@moq/net`'s `Ordered` and `@moq/json`'s -`latest()` do the same. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 -/quest-complete run), from -[moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403). - -Milestone: ✅ m1 (moved from m2). Not chosen: m2. - -- [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403) decision 7, taken overnight on the maintainer's standing - authorization (2026-10-31): ✅ land with the documented caveat (the - `poll_latest` rustdoc, commit - [1aad05c565](https://github.com/moq-dev/moq/commit/1aad05c565)) and plan - this follow-up. Not chosen: fix it in [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403), threading new public API - through `Cursor::poll_next_with`, `Subscriber::poll_group`, and the resume - layer's multi-copy peek (`rs/moq-net/src/model/resume.rs`). -- Today `latest()` drains `Ordered::poll_next_group`, which since [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403) parks - above an owed hole until it lands, the track says it won't, or the budget - gives up. Every in-repo snapshot reader uses the zero default and is - unaffected; a reader with a budget is not. -- The new read is that threading: skip owed holes but not the reader's range - or budget, and never hand out a group twice. The caveat sits at - `rs/moq-json/src/snapshot/consumer.rs:84` at be39188000. -- [moq-dev/moq#7609](https://github.com/moq-dev/moq/pull/7609) (merged) made - JS ordered reads wait on owed groups too, so `@moq/json`'s `latest()` - (`js/json/src/snapshot/consumer.ts:59`, draining `Ordered.tryNextGroup`) - now parks the same way. Mirror the new read in `@moq/net`'s `Ordered` - (`js/net/src/track.ts:3111`) and move `latest()` onto it. - -Public API: adds an `Ordered` read (Rust and JS); `snapshot::Consumer::latest()` -and `@moq/json`'s `latest()` stop waiting at owed holes. Wire: none. diff --git a/quest/m2/net-wrap/json.md b/quest/m2/net-wrap/json.md index b0190226c9b..1381100d68a 100644 --- a/quest/m2/net-wrap/json.md +++ b/quest/m2/net-wrap/json.md @@ -12,9 +12,10 @@ types, so each publishes into and reads from a wrapped track unchanged. - moq-json takes the trait, not a wrapper role (decided 2026-10-20, maintainer): its `Encoder`/`Decoder` codec layer stays as it is, and only - `Producer::new(track::Producer)` and `Consumer::new(track::Subscriber)` in - `snapshot`, `stream`, and `window` become generic. -- hang: `catalog::Consumer::new(track::Subscriber)`, + `Producer::new(track::Producer)` in `snapshot`, `stream`, and `window`, + `snapshot::Consumer::new(track::Consumer)`, which subscribes itself, and + `Consumer::new(track::Subscriber)` in `stream` and `window` become generic. +- hang: `catalog::Consumer::new(track::Consumer)`, `Root::subscribe(&broadcast::Consumer)`, and `container::Frame::write_to(&mut group::Producer)` are the entry points. - moq-stats: the produce and consume paths that hold moq-net broadcasts and diff --git a/rs/hang/MIGRATE.md b/rs/hang/MIGRATE.md index 1eb2d5aaca1..2000b63d707 100644 --- a/rs/hang/MIGRATE.md +++ b/rs/hang/MIGRATE.md @@ -9,6 +9,12 @@ How to update your code for each breaking change, newest first. `Catalog::default_track_info` takes moq-net's new zero default, so the catalog track advertises the live edge only where it advertised no limit. A late joiner still reads the newest snapshot, which never goes stale. `container::track_info` still declares `container::MAX_AGE` (30 s) on media tracks. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`catalog::Consumer::new` takes the catalog track, a `moq_net::track::Consumer`, instead of a `track::Subscriber`, and subscribes to it itself at `Catalog::default_subscription()`'s priority and a zero `delay.max`, so `latest` never waits on a catalog group the track still owes. +Pass `broadcast.track(Catalog::DEFAULT_NAME)?` rather than subscribing first; `Catalog::subscribe` is unchanged. +A refused subscription now surfaces from the first read. + ### Compression moves to the track `catalog::Compression`, the `compression` field on `JsonConfig` and `BinaryConfig`, `Catalog::COMPRESSED_NAME`, and `catalog::Consumer::compressed` are gone. diff --git a/rs/hang/examples/subscribe.rs b/rs/hang/examples/subscribe.rs index 9718326d08f..5445d1863b2 100644 --- a/rs/hang/examples/subscribe.rs +++ b/rs/hang/examples/subscribe.rs @@ -80,11 +80,7 @@ async fn play(consumer: moq_net::origin::Consumer, announce: moq_net::announce:: let broadcast = consumer.request(&announce.prefix, announce.route.instance).await?; // Read the catalog to discover available tracks. - let catalog_track = broadcast - .track(hang::Catalog::DEFAULT_NAME)? - .subscribe(hang::Catalog::default_subscription()) - .await?; - let mut catalog = moq_mux::catalog::hang::Consumer::<()>::new(catalog_track); + let mut catalog = moq_mux::catalog::hang::Consumer::<()>::new(broadcast.track(hang::Catalog::DEFAULT_NAME)?); let info = catalog.next().await?.ok_or_else(|| anyhow::anyhow!("no catalog"))?; diff --git a/rs/hang/src/catalog/consumer.rs b/rs/hang/src/catalog/consumer.rs index 67c9c722cc5..eebd5b48726 100644 --- a/rs/hang/src/catalog/consumer.rs +++ b/rs/hang/src/catalog/consumer.rs @@ -8,7 +8,7 @@ use serde::de::DeserializeOwned; use super::Catalog; use crate::Result; -/// Reads typed catalog roots from an already subscribed catalog track. +/// Reads typed catalog roots from a catalog track, subscribing to it at catalog priority. pub struct Consumer { // Decoded in two steps, so a catalog needing a newer reader fails with a typed error. inner: moq_json::snapshot::Consumer, @@ -17,11 +17,16 @@ pub struct Consumer { } impl Consumer { - /// Wrap a catalog track subscription, compressed or not. - pub fn new(track: moq_net::track::Subscriber) -> Self { + /// Read a catalog track, compressed or not. + /// + /// Subscribes to it at [`Catalog::default_subscription`]'s priority, reading only the newest + /// catalog; see [`moq_json::snapshot::Consumer::new`]. + pub fn new(track: moq_net::track::Consumer) -> Self { + let mut config = moq_json::snapshot::consumer::Config::default(); + config.priority = Catalog::default_subscription().priority; Self { base: track.broadcast().path.clone(), - inner: moq_json::snapshot::Consumer::new(track, Default::default()), + inner: moq_json::snapshot::Consumer::new(track, config), _ext: std::marker::PhantomData, } } diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index bfb92b0caa7..73b752b1819 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -345,11 +345,7 @@ impl FromStr for Catalog { impl Catalog { /// Subscribe to catalog updates on a broadcast. pub async fn subscribe(broadcast: &moq_net::broadcast::Consumer) -> Result> { - let track = broadcast - .track(Catalog::DEFAULT_NAME)? - .subscribe(Catalog::default_subscription()) - .await?; - Ok(super::Consumer::new(track)) + Ok(super::Consumer::new(broadcast.track(Catalog::DEFAULT_NAME)?)) } /// Parse a catalog from a slice of bytes. diff --git a/rs/moq-boy/src/input.rs b/rs/moq-boy/src/input.rs index b7c954e7acc..606a2359174 100644 --- a/rs/moq-boy/src/input.rs +++ b/rs/moq-boy/src/input.rs @@ -127,7 +127,7 @@ async fn handle_viewer_commands( broadcast: moq_net::broadcast::Consumer, cmd_tx: &tokio::sync::mpsc::Sender, ) -> anyhow::Result<()> { - let track = broadcast.track("command")?.subscribe(None).await?; + let track = broadcast.track("command")?; let mut commands = moq_json::snapshot::Consumer::::new(track, moq_json::snapshot::consumer::Config::default()); diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 7aa54de22b9..e43df123482 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -283,20 +283,17 @@ impl Consume { let driver = origin.as_ref().map(|origin| origin.driver.clone()).unwrap_or_default(); - // `subscribe` blocks on SUBSCRIBE_OK, so run it inside the task - // to keep this entrypoint non-blocking. + // Reads wait on SUBSCRIBE_OK, so run them inside the task to keep this entrypoint + // non-blocking. self.catalog_task.spawn( on_catalog, |state| &mut state.consume.catalog_task, - |mut close| async move { + |close| async move { driver .watch(async move { - let subscription = hang::catalog::Catalog::default_subscription(); - let subscribe = Self::subscribe(&broadcast, hang::catalog::Catalog::DEFAULT_NAME, subscription); - let Some(catalog) = Self::until_closed(&mut close, subscribe).await? else { - return Ok(()); - }; - Self::run_catalog(on_catalog, broadcast.clone(), origin, catalog.into(), close).await + // The consumer subscribes itself at catalog priority. + let catalog = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?.into(); + Self::run_catalog(on_catalog, broadcast.clone(), origin, catalog, close).await }) .await }, @@ -964,20 +961,19 @@ impl Consume { let broadcast = context.broadcast.clone(); let name = name.to_string(); - // `subscribe` blocks on SUBSCRIBE_OK, so run it inside the task. + // Reads wait on SUBSCRIBE_OK, so run them inside the task. self.json_task.spawn( on_value, |state| &mut state.consume.json_task, - |mut close| async move { + |close| async move { driver .watch(async move { - let Some(track) = - Self::until_closed(&mut close, Self::subscribe(&broadcast, &name, None)).await? - else { - return Ok(()); - }; - let consumer = - moq_json::snapshot::Consumer::::new(track, Default::default()); + // The consumer subscribes itself; `run_json_snapshot` keeps a close ahead of + // a SUBSCRIBE_OK that never comes. + let consumer = moq_json::snapshot::Consumer::::new( + broadcast.track(&name)?, + Default::default(), + ); Self::run_json_snapshot(on_value, consumer, close).await }) .await diff --git a/rs/moq-cli/src/report.rs b/rs/moq-cli/src/report.rs index f9ff59ff663..310d3ee519c 100644 --- a/rs/moq-cli/src/report.rs +++ b/rs/moq-cli/src/report.rs @@ -393,10 +393,10 @@ async fn next(catalog: &mut Option) -> moq_mux::Result moq_json::snapshot::Consumer { +fn reader(track: moq_net::track::Consumer) -> moq_json::snapshot::Consumer { let mut config = moq_json::snapshot::consumer::Config::default(); config.max_size = Some(MAX_REPORT); - moq_json::snapshot::Consumer::new(subscriber, config) + moq_json::snapshot::Consumer::new(track, config) } /// The next snapshot of a report track, or never while there is none. @@ -437,10 +437,7 @@ pub async fn print_report(origin: moq_net::origin::Consumer, path: String) -> an let stats = update.stats.map(|stats| stats.track); if stats != named { track = match &stats { - Some(name) => { - let subscriber = broadcast.track(name)?.subscribe(None).await?; - Some(reader(subscriber)) - } + Some(name) => Some(reader(broadcast.track(name)?)), None => None, }; named = stats; @@ -567,8 +564,7 @@ impl Readers { async fn read_echo(origin: moq_net::origin::Consumer, path: moq_net::Path, lines: tokio::sync::mpsc::Sender) { let read = async { let broadcast = origin.request(&path, None).await?; - let subscriber = broadcast.track(hang::echo::TRACK)?.subscribe(None).await?; - let mut track = reader(subscriber); + let mut track = reader(broadcast.track(hang::echo::TRACK)?); while let Some(moq_net::Timed { value: feedback, .. }) = track.latest().await? { let line = EchoLine { broadcast: path.as_str(), @@ -601,7 +597,7 @@ mod tests { .produce() .create_track(STATS_TRACK, None) .unwrap(); - let mut read = reader(track.subscribe(None)); + let mut read = reader(track.consume()); let mut report = moq_json::snapshot::Producer::::new(track, Default::default()); report .update(&serde_json::json!({ "pad": "x".repeat(MAX_REPORT) })) diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index d72968d6a2c..d5927e2007d 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -19,6 +19,10 @@ The field defaults to null, so only code that builds these records exhaustively, A null `MoqTrackInfo.max_age`, and a null `MoqTrackInfo`, now advertise a zero max age, serving only the live edge, instead of no publisher limit. Set the new `max_age_unlimited`, which ignores `max_age`, where you relied on null meaning no limit. A received track's `info()` sets `max_age_unlimited` when its publisher advertised no limit, so the record republishes unchanged. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`MoqJsonSnapshotConsumer::new(broadcast, name, priority)` takes a `MoqBroadcastConsumer`, the track name, and the subscription's priority (default 0) instead of a `MoqTrackConsumer`, and subscribes to the track itself at a zero `delay.max`. Drop the `subscribe_track` call; a refused subscription now fails the first read. `next()` skips every group a newer one supersedes, and `latest()` no longer waits for a lower group the track still owes. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqError::OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers::watch` and `set_target` and `MoqViewer::update` return a `Result`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 943e6481f42..9bbe24a2319 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -12,7 +12,7 @@ use std::task::{Poll, ready}; use serde_json::Value; -use crate::consumer::MoqTrackConsumer; +use crate::consumer::{MoqBroadcastConsumer, MoqTrackConsumer}; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Polled; @@ -228,24 +228,26 @@ pub struct MoqJsonSnapshotConsumer { #[uniffi::export] impl MoqJsonSnapshotConsumer { - /// Read `track` as a JSON snapshot track (lossy latest-value). + /// Subscribe to the track `name` on `broadcast` and read it as a JSON snapshot track (lossy + /// latest-value). /// - /// Reads a compressed track the same as a plain one. Takes over `track`, whose handle is - /// closed afterward; errors if it has already read a group. - #[uniffi::constructor] - pub fn new(track: &MoqTrackConsumer) -> Result, MoqError> { + /// The consumer owns its subscription, at a zero `delay.max` and `priority` (higher first, as + /// [`MoqSubscription::priority`](crate::consumer::MoqSubscription::priority)): a read waits for + /// it to resolve and fails if it cannot. Reads a compressed track the same as a plain one. + #[uniffi::constructor(default(priority = 0))] + pub fn new(broadcast: &MoqBroadcastConsumer, name: String, priority: i8) -> Result, MoqError> { let _guard = crate::ffi::enter(); - let (track, driver) = track.take()?; - let consumer = moq_json::snapshot::Consumer::::new(track, Default::default()); + let mut config = moq_json::snapshot::consumer::Config::default(); + config.priority = priority; + let consumer = moq_json::snapshot::Consumer::::new(broadcast.inner.track(&name)?, config); Ok(Arc::new(Self { - reads: Polled::new(consumer).supervised(driver), + reads: Polled::new(consumer).supervised(broadcast.driver.clone()), })) } /// Get the next state in order. Returns `None` once the track ends. /// - /// Groups older than the subscription's `delay.max` are skipped, so a playhead - /// reader sets that budget to its distance behind live. + /// Skips every group a newer one supersedes. pub async fn next(&self) -> Result, MoqError> { let value = self .reads diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 97988a90167..242e2e776b0 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -1834,17 +1834,8 @@ impl MoqMediaCatalogConsumer { /// Subscribe to this broadcast's catalog snapshots. #[uniffi::constructor] pub async fn subscribe(broadcast: &MoqBroadcastConsumer) -> Result, MoqError> { - let track = broadcast - .driver - .watch(async { - Ok(broadcast - .inner - .track(hang::catalog::Catalog::DEFAULT_NAME)? - .subscribe(hang::catalog::Catalog::default_subscription()) - .await?) - }) - .await?; - let consumer = moq_mux::catalog::hang::Consumer::from(track); + let consumer = + moq_mux::catalog::hang::Consumer::new(broadcast.inner.track(hang::catalog::Catalog::DEFAULT_NAME)?); Ok(Arc::new(MoqMediaCatalogConsumer { reads: Polled::new(consumer).supervised(broadcast.driver.clone()), })) @@ -2193,9 +2184,6 @@ mod timebase_tests { .consume_inner() .unwrap() .track(hang::catalog::Catalog::DEFAULT_NAME) - .unwrap() - .subscribe(moq_net::track::Subscription::default()) - .await .unwrap(); let mut catalog = moq_mux::catalog::hang::Consumer::::new(track); assert!(catalog.poll_next(&kio::Waiter::noop()).is_pending()); @@ -2221,9 +2209,6 @@ mod timebase_tests { .consume_inner() .unwrap() .track(hang::catalog::Catalog::DEFAULT_NAME) - .unwrap() - .subscribe(moq_net::track::Subscription::default()) - .await .unwrap(); let mut reader = moq_mux::catalog::hang::Consumer::::new(track); let catalog = MoqMediaCatalogProducer::new(owner.clone()).unwrap(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 48a5bc1f66d..6bc3be5e637 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1473,7 +1473,7 @@ async fn json_snapshot_roundtrip() { matches!(track.demand(), Err(MoqError::Closed)), "the producer takes over the track" ); - let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await).unwrap(); + let consumer = MoqJsonSnapshotConsumer::new(&broadcast.consume().unwrap(), "meta".into(), 0).unwrap(); for n in 1..=4 { producer.update(format!(r#"{{"a":{n}}}"#), us(n * 1000)).unwrap(); @@ -1563,7 +1563,7 @@ async fn json_snapshot_refreshes_for_a_joiner() { .await .expect("timed out waiting for the refresh"); assert_eq!(refreshed.sequence(), 1); - let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await).unwrap(); + let consumer = MoqJsonSnapshotConsumer::new(&broadcast.consume().unwrap(), "meta".into(), 0).unwrap(); let value = kio::clock::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for the restated value") @@ -1592,7 +1592,7 @@ async fn json_demand() { assert_eq!(stream_demand.name(), "events"); assert!(!snapshot_demand.wanted().is_some()); - let snapshot_consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "status").await).unwrap(); + let snapshot_consumer = MoqJsonSnapshotConsumer::new(&broadcast.consume().unwrap(), "status".into(), 0).unwrap(); let stream_consumer = MoqJsonStreamConsumer::new(&*subscribe(&broadcast, "events").await).unwrap(); kio::clock::timeout(TIMEOUT, snapshot_demand.until_wanted()) diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 5fbdba79c27..c42c9782852 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -914,20 +914,10 @@ impl Session { /// with the session, except those of renditions the catalog retired. async fn follow_catalog(&self, source: moq_mux::Source, cancel: &mut watch::Receiver) -> Result<()> { let broadcast = source.broadcast(); - let catalog_track = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?; - // A publisher that never answers would otherwise hold the run until it is cancelled. - let catalog_track = tokio::select! { - track = catalog_track.subscribe(hang::catalog::Catalog::default_subscription()) => match track { - Ok(track) => track, - Err(err) if source_lost(&err) => { - tracing::warn!(%err, "catalog unavailable, holding pads"); - return Ok(()); - } - Err(err) => return Err(anyhow::Error::from(err).context("catalog refused")), - }, - _ = cancel.changed() => return Ok(()), - }; - let mut catalog_consumer = moq_mux::catalog::hang::Consumer::new(catalog_track); + // The consumer subscribes itself: a refused or lost subscription surfaces from its first read + // below, and a publisher that never answers holds the run only until it is cancelled. + let mut catalog_consumer = + moq_mux::catalog::hang::Consumer::new(broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?); // Follow the catalog for the whole run and reconcile against every update, rather than // building the renditions once from the first frame. This covers reactive publishers (the @@ -5269,8 +5259,12 @@ mod session_tests { .expect("the refusal held the session") .unwrap() .expect_err("the refusal did not fail the session"); + // The catalog consumer subscribes itself, so the refusal surfaces from its first read. assert!( - matches!(err.downcast_ref::(), Some(moq_net::Error::NotFound)), + matches!( + err.downcast_ref::(), + Some(moq_mux::Error::Moq(moq_net::Error::NotFound)) + ), "{err:?}" ); } diff --git a/rs/moq-json/MIGRATE.md b/rs/moq-json/MIGRATE.md index fd6250edbb9..9a3c7527ec2 100644 --- a/rs/moq-json/MIGRATE.md +++ b/rs/moq-json/MIGRATE.md @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`snapshot::Consumer::new` takes the track, a `moq_net::track::Consumer`, instead of a `track::Subscriber`, and subscribes to it itself at a zero `delay.max` and default preferences otherwise; the new `Config::priority` sets the subscription's priority. +Pass `broadcast.track(name)?` rather than `broadcast.track(name)?.subscribe(..).await?`, or `producer.consume()` for an in-process `track::Producer`. +A refused or failed subscription now surfaces from the first read instead of before construction. +No handle to that subscription leaves the consumer, so ranges, order, and `delay.max` can no longer be set on a snapshot reader. + +`next()` skips every group a newer one supersedes, and `latest()` no longer waits for a lower group a received track still owes, whatever another reader of the track asks for. +A reader that set `delay.max` to replay a snapshot track's history or trail a playhead gets only the newest group: read the track's groups yourself and feed them to a `snapshot::Decoder`, or publish a `stream` track when every state must survive, or a `window` track for a bounded recent history. + ### Compression moves to the track `Compression`, every `Config::compression` field, the `with_compression` setters, `Error::Flate`, `Error::Desync`, and `stream::Decoder::reset` are gone, along with the moq-flate dependency. @@ -26,7 +36,7 @@ An `Encoder` user restates with `Encoder::snapshot()` once `Demand::wanted` pass Snapshot, stream, and window `next` / `poll_next` return `moq_net::Timed`: read `.value` for the value and `.at` for the frame's exact timestamp, `None` when untimed. A window event's `.value` is the `Event` that `next` used to return; a record restated by a group header carries the header frame's time. -Snapshot `next` now yields every state in order inside the subscription's `max_delay`; call `latest` / `poll_latest` for the old collapse-to-newest read. +Snapshot `next` now yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); call `latest` / `poll_latest` for the old collapse-to-newest read. ### Duplicate keys are refused diff --git a/rs/moq-json/examples/telemetry.rs b/rs/moq-json/examples/telemetry.rs index 3c2aded71a6..d319456742e 100644 --- a/rs/moq-json/examples/telemetry.rs +++ b/rs/moq-json/examples/telemetry.rs @@ -115,9 +115,8 @@ fn frame_bytes(config: snapshot::Config, ticks: u64) -> usize { /// exact input value after delta application (not just the final one). fn verify(producer_config: snapshot::Config, compress: bool, ticks: u64) { let track = track(compress); - let consumer = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), Default::default()); let mut producer = Producer::::new(track, producer_config); - let mut consumer = Consumer::::new(consumer, Default::default()); let waiter = kio::Waiter::noop(); for tick in 0..ticks { @@ -149,7 +148,7 @@ fn verify(producer_config: snapshot::Config, compress: bool, ticks: u64) { /// is far below `ticks`, since stale intermediate reconstructions are applied internally but skipped. fn verify_late_joiner(producer_config: snapshot::Config, compress: bool, ticks: u64) -> usize { let track = track(compress); - let consumer = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), Default::default()); let mut producer = Producer::::new(track, producer_config); for tick in 0..ticks { producer @@ -158,7 +157,6 @@ fn verify_late_joiner(producer_config: snapshot::Config, compress: bool, ticks: } producer.finish().unwrap(); - let mut consumer = Consumer::::new(consumer, Default::default()); let waiter = kio::Waiter::noop(); let mut last = None; let mut yielded = 0; diff --git a/rs/moq-json/examples/teleop.rs b/rs/moq-json/examples/teleop.rs index 0d9499a0bc0..6f2e8f4b8a1 100644 --- a/rs/moq-json/examples/teleop.rs +++ b/rs/moq-json/examples/teleop.rs @@ -26,7 +26,7 @@ fn main() -> Result<(), Box> { let info = track::Info::default().with_timescale(Timescale::MILLI); let state = broadcast.create_track("control.json", info.clone())?; let commands = broadcast.create_track("commands.json", info)?; - let mut state_reader = snapshot::Consumer::::new(state.subscribe(None), Default::default()); + let mut state_reader = snapshot::Consumer::::new(state.consume(), Default::default()); let mut command_reader = stream::Consumer::::new(commands.subscribe(None), Default::default()); let mut state = snapshot::Producer::new(state, Default::default()); let mut commands = stream::Producer::new(commands, Default::default()); diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 8839c132c44..64dcbd4de26 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -1,7 +1,7 @@ //! JSON publishing over [`moq-net`](moq_net) tracks, in three modes: //! -//! - [`snapshot`]: **lossy**. One JSON value updated over time; `next` yields states inside the -//! drift budget, while `latest` skips to the newest state. Superseded groups may be lost. +//! - [`snapshot`]: **lossy**. One JSON value updated over time; `next` yields states in order, +//! while `latest` skips to the newest state. Superseded groups are lost. //! - [`stream`]: **lossless**. An ordered append-log of self-contained records; every record is //! preserved and delivered in order, nothing is ever superseded. //! - [`window`]: **bounded**. An ordered run of records appended to the back and dropped from the diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 0c01471c93d..909ba7e9408 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -21,6 +21,10 @@ pub struct Config { /// reconstructed value costs no more than that. Set it to hold a smaller document, at the cost /// of re-measuring the value after every delta. pub max_size: Option, + + /// Delivery priority of the consumer's subscription, higher first, as + /// [`Subscription::priority`](moq_net::track::Subscription::priority). + pub priority: i8, } /// Consumes a JSON value from a track, reconstructing it from snapshots and deltas. @@ -29,20 +33,39 @@ pub struct Config { /// yields each reconstructed state and its frame timestamp, or skips to the newest with `latest`. /// When something else already owns the track, use the [`Decoder`] /// directly. +/// +/// A snapshot is superseded the moment a newer one exists, so the consumer subscribes itself at a +/// zero [`max`](moq_net::track::Delay::max) delay and keeps that subscription to itself: a group +/// is skipped once a newer one arrives, and a lower group the subscription still owes never holds +/// up a newer one. pub struct Consumer { - track: moq_net::track::Ordered, + track: Track, + name: String, group: Option, decoder: Decoder, frames_read: usize, } impl Consumer { - /// Create a consumer reading from the given track subscriber. + /// Create a consumer reading from the given track. /// - /// A [`compress`](moq_net::track::Info::compress)ed track reads the same: moq-net inflates it. - pub fn new(track: moq_net::track::Subscriber, config: Config) -> Self { + /// Subscribes right away at [`Config::priority`] and a zero + /// [`max`](moq_net::track::Delay::max) delay, with default preferences otherwise; no handle to that subscription leaves the + /// consumer, so nothing can change its budget. A read waits until the subscription resolves, + /// and fails if it cannot. A [`compress`](moq_net::track::Info::compress)ed track reads the + /// same: moq-net inflates it. + pub fn new(track: moq_net::track::Consumer, config: Config) -> Self { + let subscription = moq_net::track::Subscription::default() + .with_priority(config.priority) + .with_delay(moq_net::track::Delay::default().with_max(std::time::Duration::ZERO)); + let name = track.name().to_string(); + let mut track = Track::Subscribing(track.subscribe(subscription).into_inner()); + // Join now when the track already resolves, as an in-process one does, so the publisher + // sees the reader before its first read; otherwise the first read resolves it. + track.resolve(&kio::Waiter::noop()); Self { - track: track.ordered(), + name, + track, group: None, decoder: Decoder::new(config), frames_read: 0, @@ -57,18 +80,15 @@ impl Consumer { kio::wait(|waiter| self.poll_next(waiter)).await } - /// Poll for each state in order, retaining the subscription's drift budget. + /// Poll for each state in order, skipping every group a newer one has superseded. /// - /// Finish the current group before taking the next. Lost groups resynchronize from a - /// later snapshot. A timed playhead reader sets its subscription's `max_delay` to its - /// distance behind live; the default zero budget keeps only groups not yet superseded. + /// Finish the current group's buffered frames before taking the next. Lost groups + /// resynchronize from a later snapshot. pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll>>> { self.poll_read(waiter, false) } /// Skip to the newest buffered state and its timestamp, or wait for a new one. - /// - /// See [`Self::poll_latest`] for how a nonzero `max_delay` delays it. pub async fn latest(&mut self) -> Result>> where T: Unpin, @@ -80,11 +100,6 @@ impl Consumer { /// /// Frames inside the newest group are still decoded in order. What this skips is gone; /// a subsequent `next` resumes after it. An untimed frame keeps `at: None`. - /// - /// It reads groups in order, so on a received track with a nonzero `max_delay` it first - /// waits for a lower group the subscription still owes, up to that budget, and with no - /// limit until the gap resolves, even when a newer group is buffered. A reader that only - /// wants the newest state keeps the default zero budget. pub fn poll_latest(&mut self, waiter: &kio::Waiter) -> Poll>>> { self.poll_read(waiter, true) } @@ -92,8 +107,6 @@ impl Consumer { fn poll_read(&mut self, waiter: &kio::Waiter, skip: bool) -> Poll>>> { if skip { // Jump to the newest group the reader already has; a newer one supersedes the rest. - // Taking groups, not the track's largest position, stays inside any cap the caller - // set on the reader. while let Poll::Ready(Some(group)) = self.track.poll_next_group(waiter)? { self.group = Some(group); self.frames_read = 0; @@ -142,7 +155,7 @@ impl Consumer { ) => { // A later group starts a fresh snapshot. - tracing::warn!(track = self.track.name(), group = group.sequence, error = ?err, + tracing::warn!(track = self.name, group = group.sequence, error = ?err, "snapshot group lost; waiting for a newer one"); self.group = None; } @@ -170,6 +183,55 @@ impl Consumer { } } +/// The consumer's own subscription, resolved by the first read. +enum Track { + Subscribing(moq_net::track::Subscribing), + // Boxed: the reader dwarfs the pending subscription. + Ordered(Box), +} + +impl Track { + /// Resolve the subscription once it is ready; an error stays for the next read to report. + fn resolve(&mut self, waiter: &kio::Waiter) { + if let Self::Subscribing(pending) = self + && let Poll::Ready(Ok(subscriber)) = pending.poll_ok(waiter) + { + *self = Self::Ordered(Box::new(subscriber.ordered())); + } + } + + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + if let Self::Subscribing(pending) = self { + *self = Self::Ordered(Box::new(std::task::ready!(pending.poll_ok(waiter))?.ordered())); + } + match self { + Self::Ordered(track) => track.poll_next_group(waiter), + Self::Subscribing(_) => unreachable!("resolved above"), + } + } +} + +#[cfg(test)] +mod subscription { + use super::*; + + #[test] + fn subscribes_at_the_configured_priority_and_zero_delay() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("data", moq_net::track::Info::default()) + .unwrap(); + let config = Config { + priority: 5, + ..Default::default() + }; + let _consumer = Consumer::::new(track.consume(), config); + let subscription = track.subscription().expect("the consumer subscribed"); + assert_eq!(subscription.priority, 5); + assert_eq!(subscription.delay.max, Some(std::time::Duration::ZERO)); + } +} + #[cfg(test)] mod timestamps { use super::*; @@ -187,13 +249,9 @@ mod timestamps { .produce() .create_track("data", info) .unwrap(); - let mut subscriber = track.subscribe(None); - let mut subscription = subscriber.subscription(); - subscription.delay.max = None; - subscriber.update(subscription).unwrap(); + let mut consumer = Consumer::::new(track.consume(), Default::default()); + let mut newest = Consumer::::new(track.consume(), Default::default()); let mut producer = crate::snapshot::Producer::new(track, crate::snapshot::Config::default()); - let mut consumer = Consumer::::new(subscriber, Default::default()); - let mut newest = Consumer::::new(producer.consume(), Default::default()); let times = [0, 810_001, 990_007]; for (n, ticks) in times.into_iter().enumerate() { let at = moq_net::Timestamp::new(ticks, scale).unwrap(); @@ -206,9 +264,6 @@ mod timestamps { if n == 1 { producer.cut().unwrap(); } - } - producer.finish().unwrap(); - for (n, ticks) in times.into_iter().enumerate() { let Poll::Ready(Ok(Some(value))) = consumer.poll_next(&kio::Waiter::noop()) else { panic!("missing state {n}") }; @@ -217,6 +272,7 @@ mod timestamps { assert_eq!(at.value(), ticks); assert_eq!(at.scale(), scale); } + producer.finish().unwrap(); assert!(matches!( consumer.poll_next(&kio::Waiter::noop()), Poll::Ready(Ok(None)) @@ -236,9 +292,8 @@ mod timestamps { .produce() .create_track("data", moq_net::track::Info::default().with_compress(true)) .unwrap(); - let subscriber = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), Default::default()); let mut producer = crate::snapshot::Producer::new(track, crate::snapshot::Config::default()); - let mut consumer = Consumer::::new(subscriber, Default::default()); let waiter = kio::Waiter::noop(); for n in 0..3 { producer @@ -269,36 +324,4 @@ mod timestamps { producer.finish().unwrap(); assert!(matches!(consumer.poll_latest(&waiter), Poll::Ready(Ok(None)))); } - - #[test] - fn latest_keeps_a_cap_set_before_the_consumer() { - let track = moq_net::broadcast::Info::new() - .produce() - .create_track("data", moq_net::track::Info::default()) - .unwrap(); - let mut subscriber = track.subscribe(None); - subscriber = subscriber.with_range(..5); - let mut producer = crate::snapshot::Producer::new(track, crate::snapshot::Config::default()); - let mut consumer = Consumer::::new(subscriber, Default::default()); - let waiter = kio::Waiter::noop(); - let mut write = |n: u64| { - producer.update(&serde_json::json!({ "n": n })).unwrap(); - producer.cut().unwrap(); - }; - for n in 0..4 { - write(n); - } - let Poll::Ready(Ok(Some(value))) = consumer.poll_latest(&waiter) else { - panic!("missing latest state") - }; - assert_eq!(value.value["n"], 3); - for n in 4..7 { - write(n); - } - let Poll::Ready(Ok(Some(value))) = consumer.poll_latest(&waiter) else { - panic!("missing capped state") - }; - assert_eq!(value.value["n"], 4, "latest crossed the cap"); - assert!(consumer.poll_next(&waiter).is_pending()); - } } diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 625d2dfc96b..b0943dbebb0 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -1,9 +1,9 @@ //! Lossy latest-value JSON publishing over [`moq-net`](moq_net) tracks. //! //! One value updated over time. `Consumer::next` yields each state with its frame timestamp, -//! in order within the subscription's drift budget; `Consumer::latest` skips to the newest -//! state. Superseded groups may be lost, so use [`stream`](crate::stream) when every record -//! must survive. A playhead reader sets `max_delay` to its distance behind the live edge. +//! in order, skipping every group a newer one supersedes; `Consumer::latest` skips to the +//! newest state. Superseded groups are lost, so use [`stream`](crate::stream) when every +//! record must survive, or [`window`](crate::window) for a bounded recent history. //! //! On the wire the value is published as a series of groups, where each group is //! self-contained: its first frame is a full snapshot and any following frames are @@ -181,27 +181,24 @@ mod test { moq_net::track::Info::default().with_compress(true) } - fn producer(config: Config) -> (Producer, moq_net::track::Subscriber) { + fn producer(config: Config) -> (Producer, moq_net::track::Consumer) { producer_on(config, moq_net::track::Info::default()) } - fn producer_on(config: Config, info: moq_net::track::Info) -> (Producer, moq_net::track::Subscriber) { + fn producer_on(config: Config, info: moq_net::track::Info) -> (Producer, moq_net::track::Consumer) { let track = moq_net::broadcast::Info::new() .produce() .create_track("test", info) .unwrap(); - let consumer = track.subscribe(None); + let consumer = track.consume(); (Producer::new(track, config), consumer) } /// Demand follows the track's subscribers, so a producer can idle while nobody is watching. #[test] fn demand_follows_subscribers() { - let (producer, consumer) = producer(Config::default()); + let (producer, _track) = producer(Config::default()); let demand = producer.demand(); - assert_eq!(demand.wanted(), Some(0)); - - drop(consumer); assert_eq!(demand.wanted(), None); let _consumer = producer.consume(); @@ -209,7 +206,7 @@ mod test { } /// Drain newest states currently available from a plaintext consumer without blocking. - fn drain(track: moq_net::track::Subscriber) -> Vec { + fn drain(track: moq_net::track::Consumer) -> Vec { drain_with(Consumer::::new(track, consumer::Config::default())) } @@ -225,10 +222,7 @@ mod test { #[test] fn next_preserves_intermediate_states() { - let (mut producer, mut track) = producer(cfg(true)); - let mut subscription = track.subscription(); - subscription.delay.max = None; - track.update(subscription).unwrap(); + let (mut producer, track) = producer(cfg(true)); for n in [1, 2, 3] { producer .update(&json!({ "padding": "same-long-value-so-deltas-stay-in-one-group", "n": n })) @@ -257,7 +251,7 @@ mod test { .produce() .create_track("test", timed()) .unwrap(); - let mut consumer = Consumer::::new(track.subscribe(None), consumer::Config::default()); + let mut consumer = Consumer::::new(track.consume(), consumer::Config::default()); let waiter = kio::Waiter::noop(); // Group 0 delivers a value, then stays open with the reader parked on its next frame. @@ -292,7 +286,7 @@ mod test { .produce() .create_track("test", timed()) .unwrap(); - let mut consumer = Consumer::::new(track.subscribe(None), consumer::Config::default()); + let mut consumer = Consumer::::new(track.consume(), consumer::Config::default()); let waiter = kio::Waiter::noop(); let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -720,7 +714,7 @@ mod test { .produce() .create_track("test", moq_net::track::Info::default()) .unwrap(); - let consumer = track.subscribe(None); + let consumer = Consumer::::new(track.consume(), consumer::Config::default()); let mut producer = Producer::::new(track, Config::default()); producer.update(&Doc { count: 1 }).unwrap(); @@ -728,7 +722,7 @@ mod test { // The refused edit published nothing after the original value. producer.finish().unwrap(); - assert_eq!(drain(consumer), vec![json!({ "count": "1", "other": 1 })]); + assert_eq!(drain_with(consumer), vec![json!({ "count": "1", "other": 1 })]); } /// An end declared ahead of the live edge still admits the edit below it, and refuses the one @@ -765,7 +759,7 @@ mod test { .produce() .create_track("test", moq_net::track::Info::default()) .unwrap(); - let consumer = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), consumer::Config::default()); let mut producer = Producer::::new(track, Config::default()); // First owner sets its field. @@ -779,7 +773,6 @@ mod test { producer.finish().unwrap(); - let mut consumer = Consumer::::new(consumer, consumer::Config::default()); let waiter = kio::Waiter::noop(); let mut last = None; while let Poll::Ready(Ok(Some(value))) = consumer.poll_latest(&waiter) { @@ -809,7 +802,8 @@ mod test { .produce() .create_track("test", moq_net::track::Info::default()) .unwrap(); - let mut consumer = track.subscribe(None); + let mut raw = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), consumer::Config::default()); let mut producer = Producer::::new(track, cfg(false)); producer.mutate(|doc| doc.video = Some("v1".to_string()), None).unwrap(); @@ -821,17 +815,12 @@ mod test { // otherwise open a group of its own. producer.mutate(|_| {}, None).unwrap(); assert_eq!( - consumer - .largest() - .now_or_never() - .flatten() - .map(|position| position.group), + raw.largest().now_or_never().flatten().map(|position| position.group), Some(1) ); producer.finish().unwrap(); - let mut consumer = Consumer::::new(consumer, consumer::Config::default()); let waiter = kio::Waiter::noop(); let mut last = None; while let Poll::Ready(Ok(Some(value))) = consumer.poll_latest(&waiter) { @@ -896,7 +885,7 @@ mod test { fn a_dropped_failed_edit_aborts_the_track() { let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "keep": true })).unwrap(); - let mut subscriber = track.ordered(); + let mut subscriber = track.subscribe(None).now_or_never().unwrap().unwrap().ordered(); *producer.modify(None).unwrap() = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); @@ -1115,10 +1104,8 @@ mod test { .create_track("test", timed()) .unwrap(); let mut group = track.append_group().unwrap(); - let consumer_track = track.subscribe(None); + let mut consumer = Consumer::::new(track.consume(), consumer::Config::default()); track.finish().unwrap(); - - let mut consumer = Consumer::::new(consumer_track, consumer::Config::default()); let waiter = kio::Waiter::noop(); // Track is finished but the open group is empty: pending, not end-of-stream. @@ -1206,7 +1193,7 @@ mod test { for n in 0..=40 { producer.update(&json!({ "n": n })).unwrap(); } - let late = producer.consume(); + let late = Consumer::::new(track.clone(), consumer::Config::default()); assert!(matches!( producer.poll_refresh(&kio::Waiter::noop()), Poll::Ready(Ok(())) @@ -1218,7 +1205,7 @@ mod test { track.largest().now_or_never().flatten().map(|position| position.group), Some(1) ); - assert_eq!(drain(late).last().unwrap(), &json!({ "n": 41 })); + assert_eq!(drain_with(late).last().unwrap(), &json!({ "n": 41 })); } #[test] diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index d9d14bff8b7..922ddcf04fa 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -38,6 +38,12 @@ if let Some(max_age) = override_or_none { The catalog and HLS record tracks take moq-net's new zero default instead of no limit; their newest group restates them. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`catalog::hang::Consumer::new` and its `From` impl take the catalog track, a `moq_net::track::Consumer`, instead of a `track::Subscriber`; the consumer subscribes itself, as `hang::catalog::Consumer::new` does. Pass `broadcast.track(hang::Catalog::DEFAULT_NAME)?` rather than subscribing first. +`json::Consumer::from_track` takes a `moq_net::track::Consumer` and is now `async`: a snapshot track's reader subscribes itself, and a stream track's subscription resolves before it returns. +A refused catalog or snapshot subscription now surfaces from the first read. + ### Shared playout timing Native players can use `timeline::Producer` and its read-only `Consumer` instead diff --git a/rs/moq-mux/src/catalog/consumer.rs b/rs/moq-mux/src/catalog/consumer.rs index 5ed2bc00d14..e31c4288384 100644 --- a/rs/moq-mux/src/catalog/consumer.rs +++ b/rs/moq-mux/src/catalog/consumer.rs @@ -52,11 +52,12 @@ impl Consumer { Ok(Self { inner: match format { CatalogFormat::Hang => { - let track = broadcast - .track(hang::Catalog::DEFAULT_NAME)? - .subscribe(hang::Catalog::default_subscription()) - .await?; - State::Hang(super::hang::Consumer::new(track)) + let track = broadcast.track(hang::Catalog::DEFAULT_NAME)?; + let consumer = super::hang::Consumer::new(track.clone()); + // The consumer subscribes itself; resolving the info rides on that subscription, + // so a refused catalog fails here as it does for MSF. + track.info().await?; + State::Hang(consumer) } CatalogFormat::Msf => { let track = broadcast.track(moq_msf::DEFAULT_NAME)?.subscribe(None).await?; diff --git a/rs/moq-mux/src/catalog/hang/consumer.rs b/rs/moq-mux/src/catalog/hang/consumer.rs index ceaf6e69f0b..b1a5233c109 100644 --- a/rs/moq-mux/src/catalog/hang/consumer.rs +++ b/rs/moq-mux/src/catalog/hang/consumer.rs @@ -20,8 +20,10 @@ pub struct Consumer { } impl Consumer { - /// Create a new catalog consumer from a `catalog.json` track subscriber, compressed or not. - pub fn new(track: moq_net::track::Subscriber) -> Self { + /// Create a new catalog consumer reading a `catalog.json` track, compressed or not. + /// + /// Subscribes to the track itself; see [`hang::catalog::Consumer::new`]. + pub fn new(track: moq_net::track::Consumer) -> Self { Self { inner: hang::catalog::Consumer::new(track), } @@ -54,8 +56,8 @@ impl Consumer { } } -impl From for Consumer { - fn from(inner: moq_net::track::Subscriber) -> Self { +impl From for Consumer { + fn from(inner: moq_net::track::Consumer) -> Self { Self::new(inner) } } @@ -117,7 +119,7 @@ mod test { let track = broadcast .create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()) .expect("catalog track should create"); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let mut group = track.append_group().expect("catalog group should append"); let payload = serde_json::to_string(&published).expect("catalog should serialize"); @@ -167,14 +169,11 @@ mod test { let resolved = requesting.await; let (_dynamic, _broadcast, track) = handler.await.expect("handler task"); - let subscriber = resolved + let catalog_track = resolved .expect("the handler served it") .track(hang::Catalog::DEFAULT_NAME) - .expect("catalog track should resolve") - .subscribe(None) - .await - .expect("catalog track should subscribe"); - let mut consumer = Consumer::new(subscriber); + .expect("catalog track should resolve"); + let mut consumer = Consumer::new(catalog_track); let mut group = track.append_group().expect("catalog group should append"); let payload = serde_json::to_string(&published).expect("catalog should serialize"); @@ -354,7 +353,7 @@ mod test { #[test] fn waits_for_pending_catalog_group_payload() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let mut group = track.append_group().expect("catalog group should append"); let waiter = kio::Waiter::noop(); @@ -372,7 +371,7 @@ mod test { #[test] fn a_newer_version_is_a_typed_refusal() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer: Consumer = Consumer::new(track.subscribe(None)); + let mut consumer: Consumer = Consumer::new(track.consume()); let mut group = track.append_group().expect("catalog group should append"); group .write_frame(moq_net::Timestamp::ZERO, r#"{"version":5}"#) @@ -388,7 +387,7 @@ mod test { #[test] fn waits_for_pending_catalog_group_payload_after_track_finish() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let mut group = track.append_group().expect("catalog group should append"); track.finish().expect("catalog track should finish"); @@ -408,7 +407,7 @@ mod test { #[test] fn returns_latest_complete_catalog_group() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let waiter = kio::Waiter::noop(); let (_old, old_payload) = catalog_payload("old"); @@ -434,7 +433,7 @@ mod test { #[test] fn waits_for_newer_pending_group_instead_of_returning_older_ready_group() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let waiter = kio::Waiter::noop(); let (_old, old_payload) = catalog_payload("old"); @@ -461,7 +460,7 @@ mod test { #[test] fn retained_pending_group_is_superseded_by_newer_group() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer = Consumer::new(track.subscribe(None)); + let mut consumer = Consumer::new(track.consume()); let waiter = kio::Waiter::noop(); let (_old, old_payload) = catalog_payload("old"); @@ -493,7 +492,7 @@ mod test { #[test] fn a_lost_track_is_a_transport_error() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer: Consumer = Consumer::new(track.subscribe(None)); + let mut consumer: Consumer = Consumer::new(track.consume()); track.abort(moq_net::Error::Cancel).expect("catalog track should abort"); assert!(matches!( @@ -505,7 +504,7 @@ mod test { #[test] fn returns_none_when_empty_track_finishes() { let track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); - let mut consumer: Consumer = Consumer::new(track.subscribe(None)); + let mut consumer: Consumer = Consumer::new(track.consume()); let waiter = kio::Waiter::noop(); track.finish().expect("catalog track should finish"); diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index be235d269cd..8a289303fd0 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -1043,7 +1043,7 @@ impl Producer { /// Create a consumer for this catalog, receiving updates as they're published. pub fn consume(&self) -> Result, moq_net::Error> { - Ok(Consumer::new(self.outputs.hang.consume())) + Ok(Consumer::new(self.outputs.hang_track.consume())) } /// Abort every catalog track with `err`, preventing further edits. @@ -1756,7 +1756,7 @@ mod test { let mut broadcast = moq_net::broadcast::Info::new().produce(); let mut catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let track = catalog.outputs.hang.consume(); + let track = catalog.outputs.hang_track.consume(); assert!(catalog.outputs.hang_track.info().compress, "catalog.json is compressed"); assert!(!catalog.outputs.msf_track.info().compress, "the MSF catalog is not"); let mut consumer = Consumer::new(track); @@ -1782,7 +1782,7 @@ mod test { fn mutate_composes_independent_owners() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let mut catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut plain = Consumer::new(catalog.outputs.hang.consume()); + let mut plain = Consumer::new(catalog.outputs.hang_track.consume()); catalog .mutate(|c| { @@ -2635,7 +2635,7 @@ mod test { fn reservation_gates_until_all_renditions_resolve() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let reserved = catalog.reserve(); @@ -2668,7 +2668,7 @@ mod test { fn live_rendition_owns_its_name_without_gating_the_catalog() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let _unresolved = catalog.rendition::("video0").unwrap(); @@ -2692,7 +2692,7 @@ mod test { let mut broadcast = moq_net::broadcast::Info::new().produce(); let config = Config::default().with_catalog(Catalog::::default()); let mut catalog = Producer::new(&mut broadcast, config).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let reserved = catalog.reserve(); @@ -2730,7 +2730,7 @@ mod test { fn m2ts_counts_as_a_servable_track() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let mut catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let reserved = catalog.reserve(); @@ -2752,7 +2752,7 @@ mod test { let mut broadcast = moq_net::broadcast::Info::new().produce(); let config = Config::default().with_catalog(Catalog::::default()); let mut catalog = Producer::new(&mut broadcast, config).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let reserved = catalog.reserve(); @@ -2791,7 +2791,7 @@ mod test { let mut broadcast = moq_net::broadcast::Info::new().produce(); let config = Config::default().with_catalog(Catalog::::default()); let mut catalog = Producer::new(&mut broadcast, config).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let net = broadcast @@ -2830,7 +2830,7 @@ mod test { let mut broadcast = moq_net::broadcast::Info::new().produce(); let config = Config::default().with_catalog(Catalog::::default()); let catalog = Producer::new(&mut broadcast, config).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let net = broadcast @@ -2868,7 +2868,7 @@ mod test { fn reservation_gate_opens_when_unresolved_reservation_is_dropped() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); let reserved = catalog.reserve(); @@ -2896,7 +2896,7 @@ mod test { fn staged_change_waits_for_a_held_reservation() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); let waiter = kio::Waiter::noop(); // A deferred importer grabs a reservation up front and holds it until it can resolve. @@ -3242,7 +3242,7 @@ mod test { /// The catalog a viewer joining now receives. fn wire(catalog: &Producer) -> Catalog<()> { - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang.consume()); + let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); match consumer.poll_next(&kio::Waiter::noop()) { Poll::Ready(Ok(Some(catalog))) => catalog, _ => panic!("a published catalog"), diff --git a/rs/moq-mux/src/container/test_util.rs b/rs/moq-mux/src/container/test_util.rs index 8050c7b791c..701bba5d5db 100644 --- a/rs/moq-mux/src/container/test_util.rs +++ b/rs/moq-mux/src/container/test_util.rs @@ -276,12 +276,7 @@ pub(crate) struct Clocks(crate::catalog::hang::Consumer); impl Clocks { /// Subscribe before importing, so the first snapshot is not missed. pub(crate) async fn subscribe(consumer: &moq_net::broadcast::Consumer) -> Self { - let track = consumer - .track(hang::Catalog::DEFAULT_NAME) - .unwrap() - .subscribe(None) - .await - .unwrap(); + let track = consumer.track(hang::Catalog::DEFAULT_NAME).unwrap(); Self(crate::catalog::hang::Consumer::new(track)) } diff --git a/rs/moq-mux/src/fuzz.rs b/rs/moq-mux/src/fuzz.rs index e4e4cd38786..00d6e8c3bee 100644 --- a/rs/moq-mux/src/fuzz.rs +++ b/rs/moq-mux/src/fuzz.rs @@ -198,12 +198,11 @@ pub fn catalog(data: &[u8]) -> bool { let track = broadcast .create_track(name, info) .expect("a fresh broadcast has no catalog"); - let subscriber = track.subscribe(None); let mut next: Box Poll> = if selector & 1 == 0 { - let mut consumer = crate::catalog::hang::Consumer::<()>::new(subscriber); + let mut consumer = crate::catalog::hang::Consumer::<()>::new(track.consume()); Box::new(move || consumer.poll_next(&waiter)) } else { - let mut consumer = crate::catalog::msf::Consumer::<()>::new(subscriber); + let mut consumer = crate::catalog::msf::Consumer::<()>::new(track.subscribe(None)); Box::new(move || consumer.poll_next(&waiter)) }; diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 80972a49fd9..fe4711723ab 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -352,23 +352,29 @@ pub struct Consumer { /// Which moq-json consumer is doing the reading. Private: the caller sees one `Consumer`. enum Inner { - Snapshot(moq_json::snapshot::Consumer), - Stream(moq_json::stream::Consumer), + // Boxed: the two readers differ in size by hundreds of bytes. + Snapshot(Box>), + Stream(Box>), } impl Consumer { - /// Read an already-subscribed track as its catalog entry declares. + /// Subscribe to a track and read it as its catalog entry declares. /// - /// The escape hatch for a caller that resolved the subscription itself. Prefer + /// The escape hatch for a caller that resolved the track itself. Prefer /// [`Entry::subscribe`](crate::catalog::Entry::subscribe), which resolves the track (including a /// cross-broadcast [`broadcast`](JsonConfig::broadcast) reference) from the catalog for you. + /// A snapshot reader subscribes itself (see [`moq_json::snapshot::Consumer::new`]); a stream + /// waits for its subscription here. /// /// Errors if the entry declares a mode this build doesn't implement, which is a track a consumer /// must skip rather than guess at. - pub fn from_track(track: moq_net::track::Subscriber, config: &JsonConfig) -> crate::Result { + pub async fn from_track(track: moq_net::track::Consumer, config: &JsonConfig) -> crate::Result { let inner = match &config.mode { - Mode::Snapshot => Inner::Snapshot(moq_json::snapshot::Consumer::new(track, Default::default())), - Mode::Stream => Inner::Stream(moq_json::stream::Consumer::new(track, Default::default())), + Mode::Snapshot => Inner::Snapshot(Box::new(moq_json::snapshot::Consumer::new(track, Default::default()))), + Mode::Stream => Inner::Stream(Box::new(moq_json::stream::Consumer::new( + track.subscribe(None).await?, + Default::default(), + ))), other => return Err(crate::Error::UnsupportedMode(other.to_string())), }; @@ -380,8 +386,7 @@ impl Consumer { /// The mode the publisher chose. /// - /// [`Mode::Snapshot`] is lossy: groups may be skipped once superseded beyond the subscription - /// drift budget. [`Mode::Stream`] preserves every record a reader keeps up with; one that falls + /// [`Mode::Snapshot`] is lossy: a group is skipped once a newer one supersedes it. [`Mode::Stream`] preserves every record a reader keeps up with; one that falls /// behind a group's retained tail sees `Evicted`. Check this when the application can only /// work with one of them. pub fn mode(&self) -> &Mode { @@ -428,14 +433,11 @@ impl crate::catalog::Entry<'_, JsonConfig> { /// /// Errors if the entry declares a mode this build doesn't implement. pub async fn subscribe(&self, source: &crate::Source) -> crate::Result> { - let track = source - .subscribe_track( - self.config().broadcast.as_ref(), - self.config().instance.as_ref(), - self.config().track(self.name()), - ) + let broadcast = source + .bind(self.config().broadcast.as_ref(), self.config().instance.as_ref())? + .broadcast() .await?; - Consumer::from_track(track, self.config()) + Consumer::from_track(broadcast.track(self.config().track(self.name()))?, self.config()).await } } @@ -443,6 +445,7 @@ impl crate::catalog::Entry<'_, JsonConfig> { mod test { use std::task::Poll; + use futures::FutureExt; use serde_json::{Value, json}; use super::*; @@ -476,6 +479,13 @@ mod test { /// Drain every value a consumer currently has, without blocking. /// /// One loop whichever mode the publisher chose, which is the point of the single `Consumer`. + /// [`Consumer::from_track`] on an in-process track, whose subscription resolves at once. + fn read(track: moq_net::track::Consumer, config: &JsonConfig) -> crate::Result> { + Consumer::from_track(track, config) + .now_or_never() + .expect("in-process subscription") + } + fn drain(mut consumer: Consumer) -> Vec { let waiter = kio::Waiter::noop(); let mut out = Vec::new(); @@ -496,17 +506,16 @@ mod test { .json_stream::(track(&mut broadcast, "chat"), Config::default()) .unwrap(); - let track = chat.consume(); + // The catalog is the only thing the reader is told; the mode comes from it. + let entry = entry(&catalog, "chat"); + let track = broadcast.consume().track("chat").unwrap(); + let consumer = read(track, &entry).unwrap(); let expected: Vec = (0..3).map(|n| json!({ "n": n })).collect(); for value in &expected { chat.append(value, catalog.clock().now()).unwrap(); } - // `finish` retires the entry, so read both off the live track first. - let entry = entry(&catalog, "chat"); chat.finish().unwrap(); - // The catalog is the only thing the reader is told; the mode comes from it. - let consumer = Consumer::from_track(track, &entry).unwrap(); assert_eq!(consumer.mode(), &Mode::Stream); assert_eq!(drain(consumer), expected); } @@ -518,14 +527,14 @@ mod test { .json_snapshot::(track(&mut broadcast, "status"), Config::default(), Options::default()) .unwrap(); - let track = status.consume(); + let entry = entry(&catalog, "status"); + let track = broadcast.consume().track("status").unwrap(); + let consumer = read(track, &entry).unwrap(); status.update(&json!({ "live": false }), catalog.clock().now()).unwrap(); status.update(&json!({ "live": true }), catalog.clock().now()).unwrap(); - let entry = entry(&catalog, "status"); status.finish().unwrap(); - // A late reader only sees the newest value, which is the point of snapshot mode. - let consumer = Consumer::from_track(track, &entry).unwrap(); + // The reader only sees the newest value, which is the point of snapshot mode. assert_eq!(consumer.mode(), &Mode::Snapshot); assert_eq!(drain(consumer), vec![json!({ "live": true })]); } @@ -848,7 +857,8 @@ mod test { let mut chat = catalog .json_stream::(track(&mut broadcast, "chat"), Config::default()) .unwrap(); - let track = chat.consume(); + let entry = entry(&catalog, "chat"); + let consumer = read(broadcast.consume().track("chat").unwrap(), &entry).unwrap(); let oversized = Value::String("x".repeat(moq_net::group::MAX_CACHE_BYTES as usize)); assert!(matches!( @@ -858,12 +868,8 @@ mod test { assert!(catalog.snapshot().json.tracks.contains_key("chat")); chat.append(&json!({ "n": 1 }), catalog.clock().now()).unwrap(); - let entry = entry(&catalog, "chat"); chat.finish().unwrap(); - assert_eq!( - drain(Consumer::from_track(track, &entry).unwrap()), - vec![json!({ "n": 1 })] - ); + assert_eq!(drain(consumer), vec![json!({ "n": 1 })]); } /// Every write is stamped, so a track without a timescale, which refuses a timestamp, is refused @@ -897,7 +903,7 @@ mod test { let config = JsonConfig::new(Mode::Unknown("windowed".to_string())); assert!(matches!( - Consumer::::from_track(track.subscribe(None), &config), + read(track.consume(), &config), Err(crate::Error::UnsupportedMode(_)) )); } diff --git a/rs/moq-net-tests/tests/integration/main.rs b/rs/moq-net-tests/tests/integration/main.rs index ea8f634857e..55e1a59234b 100644 --- a/rs/moq-net-tests/tests/integration/main.rs +++ b/rs/moq-net-tests/tests/integration/main.rs @@ -1,9 +1,10 @@ -//! Session tests that need JSON consumers or the hidden peer-claim hooks. +//! Tests that need JSON consumers or moq-net's hidden fuzz hooks. mod ietf_conformance; mod refresh; mod restart; mod serve; +mod snapshot; #[path = "../../../moq-net/tests/integration/support/mod.rs"] mod support; diff --git a/rs/moq-net-tests/tests/integration/refresh.rs b/rs/moq-net-tests/tests/integration/refresh.rs index 5b5df917977..45659e063d7 100644 --- a/rs/moq-net-tests/tests/integration/refresh.rs +++ b/rs/moq-net-tests/tests/integration/refresh.rs @@ -75,8 +75,7 @@ async fn json_snapshot_refresh_crosses_a_two_relay_cluster() { json!({ "n": n }) ); if n == 1 || n == 2 * u64::from(ratio) { - let mut join = - snapshot::Consumer::::new(remote.subscribe(None).await.unwrap(), Default::default()); + let mut join = snapshot::Consumer::::new(remote.clone(), Default::default()); let received = join.latest().await.unwrap().unwrap(); assert_eq!((received.value, received.at), (value(n), Some(at(n)))); assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); @@ -138,7 +137,7 @@ async fn json_snapshot_refresh_crosses_a_two_relay_cluster() { serde_json::from_slice::(&delta.payload).unwrap(), json!({ "n": n + 1 }) ); - let mut current = snapshot::Consumer::::new(remote.subscribe(None).await.unwrap(), Default::default()); + let mut current = snapshot::Consumer::::new(remote.clone(), Default::default()); let received = current.latest().await.unwrap().unwrap(); assert_eq!((received.value, received.at), (value(n + 1), Some(at(n + 1)))); assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); diff --git a/rs/moq-net-tests/tests/integration/snapshot.rs b/rs/moq-net-tests/tests/integration/snapshot.rs new file mode 100644 index 00000000000..85177a91ce1 --- /dev/null +++ b/rs/moq-net-tests/tests/integration/snapshot.rs @@ -0,0 +1,56 @@ +//! A snapshot reader on a received track never waits on a hole the subscription still owes. +use moq_json::snapshot; +use moq_net::{fuzz, group, kio, track}; +use serde_json::{Value, json}; +use std::{task::Poll, time::Duration}; + +/// Group 2 arrives while group 1 is still owed: `latest()` and `next()` return it at once, +/// whatever budget another reader of the track asks for, since a snapshot consumer subscribes +/// itself at a zero max delay. +#[test] +fn reads_skip_an_owed_hole() { + for max in [Some(Duration::ZERO), Some(Duration::from_secs(1)), None] { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("state", track::Info::default()) + .unwrap(); + fuzz::received(&track); + // The caller's own reader of the track, at the budget it might have wanted. + let _other = track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(max))); + let mut latest = snapshot::Consumer::::new(track.consume(), Default::default()); + let mut next = snapshot::Consumer::::new(track.consume(), Default::default()); + let waiter = kio::Waiter::noop(); + let put = |sequence: u64| { + let mut group = track.create_group(group::Info { sequence }).unwrap(); + group + .write_frame(None, serde_json::to_vec(&json!({ "n": sequence })).unwrap()) + .unwrap(); + group.finish().unwrap(); + }; + + put(0); + let Poll::Ready(Ok(Some(state))) = latest.poll_latest(&waiter) else { + panic!("latest missed group 0 with max {max:?}") + }; + assert_eq!(state.value, json!({ "n": 0 })); + let Poll::Ready(Ok(Some(state))) = next.poll_next(&waiter) else { + panic!("next missed group 0 with max {max:?}") + }; + assert_eq!(state.value, json!({ "n": 0 })); + + put(2); + let Poll::Ready(Ok(Some(state))) = latest.poll_latest(&waiter) else { + panic!("latest waited on owed group 1 with max {max:?}") + }; + assert_eq!(state.value, json!({ "n": 2 })); + let Poll::Ready(Ok(Some(state))) = next.poll_next(&waiter) else { + panic!("next waited on owed group 1 with max {max:?}") + }; + assert_eq!(state.value, json!({ "n": 2 })); + + // The owed group landing late is superseded, not delivered. + put(1); + assert!(latest.poll_latest(&waiter).is_pending(), "max {max:?}"); + assert!(next.poll_next(&waiter).is_pending(), "max {max:?}"); + } +} diff --git a/rs/moq-rtc/src/lib.rs b/rs/moq-rtc/src/lib.rs index 19895f301d6..6b305030fd4 100644 --- a/rs/moq-rtc/src/lib.rs +++ b/rs/moq-rtc/src/lib.rs @@ -110,10 +110,7 @@ mod tests { async fn opus_output(broadcast: &moq_net::broadcast::Consumer) -> Track { let catalog_track = broadcast .track(hang::Catalog::DEFAULT_NAME) - .expect("output catalog track") - .subscribe(hang::Catalog::default_subscription()) - .await - .expect("subscribe to output catalog"); + .expect("output catalog track"); let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog_track); let catalog = kio::clock::timeout(TIMEOUT, catalogs.next()) .await diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index faa4d6c9dcf..b33b1396df7 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -14,7 +14,7 @@ use std::time::Duration; use kio::clock::Instant; use moq_net::kio::{self, Pending, Waiter}; use moq_net::stats::{Presence, Traffic}; -use moq_net::track::Subscribing; +use moq_net::track::Resolving; use moq_net::{Instance, Path, broadcast, origin}; use crate::{ @@ -696,8 +696,9 @@ enum Reader { Resolving(Box>), /// Waiting for the node's listing to offer the track. Waiting, - /// Awaiting the subscription handshake. - Subscribing(Pending), + /// Awaiting the subscription handshake: the reader has subscribed, and the + /// track's info resolving shows whether the track exists. + Subscribing(Box>, Pending), /// Reading frames. Boxed: the snapshot consumer dwarfs the other variants, /// and one lives per node in a map. Active(Box>), @@ -1000,7 +1001,7 @@ fn advance( } }, Poll::Ready(Ok(broadcast)) => match broadcast.track(name) { - Ok(track) => node.reader = Reader::Subscribing(track.subscribe(None)), + Ok(track) => node.reader = subscribing(track, config), Err(err) => { tracing::debug!(?err, name, "stats: node missing track"); return changed | node.depart(); @@ -1029,17 +1030,19 @@ fn advance( } node.offered = false; match listing.broadcast().track(name) { - Ok(track) => node.reader = Reader::Subscribing(track.subscribe(None)), + Ok(track) => node.reader = subscribing(track, config), Err(err) => { tracing::debug!(?err, name, "stats: node missing track"); return changed | node.depart(); } } } - Reader::Subscribing(pending) => match pending.poll_ok(waiter) { - Poll::Ready(Ok(subscriber)) => { - node.reader = - Reader::Active(Box::new(moq_json::snapshot::Consumer::new(subscriber, config.clone()))); + Reader::Subscribing(_, pending) => match pending.poll_ok(waiter) { + Poll::Ready(Ok(_)) => { + let Reader::Subscribing(reader, _) = std::mem::replace(&mut node.reader, Reader::Waiting) else { + unreachable!("matched above"); + }; + node.reader = Reader::Active(reader); } // The listed instance ended before the subscription landed: wait for // the next one. @@ -1099,6 +1102,16 @@ fn resolve(origin: &origin::Consumer, path: &Path, instance: Instance) -> Rea Reader::Resolving(Box::new(pending)) } +/// Subscribe a node's reader to `track`, awaiting the handshake. +fn subscribing( + track: moq_net::track::Consumer, + config: &moq_json::snapshot::consumer::Config, +) -> Reader { + // The reader subscribes first, so resolving the info rides on its subscription. + let reader = Box::new(moq_json::snapshot::Consumer::new(track.clone(), config.clone())); + Reader::Subscribing(reader, track.info()) +} + #[cfg(test)] mod tests { /// A millisecond track: the frames written here carry timestamps. diff --git a/rs/moq-stats/src/consume.rs b/rs/moq-stats/src/consume.rs index 4b22bb8f1fc..28bda8fa857 100644 --- a/rs/moq-stats/src/consume.rs +++ b/rs/moq-stats/src/consume.rs @@ -71,15 +71,17 @@ impl Consumer { /// Fails with [`NotFound`](moq_net::Error::NotFound) unless the group is /// listed. pub async fn group(&self, group: impl Into) -> Result { - let track = self.broadcast.track(&group_track(group))?.subscribe(None).await?; Ok(GroupConsumer { - inner: moq_json::snapshot::Consumer::new(track, Default::default()), + inner: self.subscribe(&group_track(group)).await?, }) } async fn subscribe(&self, name: &str) -> Result> { - let track = self.broadcast.track(name)?.subscribe(None).await?; - Ok(moq_json::snapshot::Consumer::new(track, Default::default())) + let track = self.broadcast.track(name)?; + // The reader subscribes itself; resolving the info rides on that subscription. + let reader = moq_json::snapshot::Consumer::new(track.clone(), Default::default()); + track.info().await?; + Ok(reader) } } diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 7f5538c7ad2..f61d5a6f7d4 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -1485,9 +1485,9 @@ mod tests { let mut previous = None; for (reading, delta) in [(40, 11), (1_000, 7)] { store(reading); - let subscriber = pumping(&mut drain, broadcast.track(&name).unwrap().subscribe(None)) - .await - .unwrap(); + let track = broadcast.track(&name).unwrap(); + let mut reader = moq_json::snapshot::Consumer::::new(track.clone(), Default::default()); + pumping(&mut drain, track.info()).await.unwrap(); let mut cursor = pumping(&mut drain, broadcast.track(&name).unwrap().subscribe(None)) .await .unwrap(); @@ -1497,7 +1497,6 @@ mod tests { } drop(group); drop(cursor); - let mut reader = moq_json::snapshot::Consumer::::new(subscriber, Default::default()); let initial = pumping(&mut drain, reader.next()).await.unwrap().unwrap().value; assert_eq!( (initial[""].wire_tx, initial[""].wire_rx), @@ -1575,13 +1574,7 @@ mod tests { }; publish(vec![Path::from_static("small")], 1); - let track = consumer - .track("t.json") - .unwrap() - .subscribe(None) - .now_or_never() - .unwrap() - .unwrap(); + let track = consumer.track("t.json").unwrap(); let mut reader = moq_json::snapshot::Consumer::::new(track, Default::default()); let mut next = || { reader @@ -1745,10 +1738,7 @@ mod tests { async fn read_group(broadcast: &moq_net::broadcast::Consumer, group: &str) -> crate::GroupFrame { let track = broadcast .track(&crate::group_track(moq_net::Path::new(group).unwrap())) - .expect("track") - .subscribe(None) - .await - .expect("subscribe"); + .expect("track"); let mut reader = moq_json::snapshot::Consumer::::new(track, Default::default()); reader.latest().await.expect("read").expect("frame").value } @@ -1768,7 +1758,7 @@ mod tests { struct Reader(moq_json::snapshot::Consumer); impl Reader { - fn new(track: track::Subscriber) -> Self { + fn new(track: track::Consumer) -> Self { Self(moq_json::snapshot::Consumer::new(track, Default::default())) } @@ -1795,24 +1785,15 @@ mod tests { broadcast: &moq_net::broadcast::Consumer, name: &str, ) -> Reader { - Reader::new( - broadcast - .track(name) - .expect("track") - .subscribe(None) - .await - .expect("subscribe"), - ) + let track = broadcast.track(name).expect("track"); + let reader = Reader::new(track.clone()); + track.info().await.expect("subscribe"); + reader } /// The latest buffered totals frame. async fn read_totals(broadcast: &moq_net::broadcast::Consumer) -> TotalsFrame { - let track = broadcast - .track(crate::TOTALS) - .expect("track") - .subscribe(None) - .await - .expect("subscribe"); + let track = broadcast.track(crate::TOTALS).expect("track"); let mut reader = moq_json::snapshot::Consumer::::new(track, Default::default()); reader.latest().await.expect("read").expect("frame").value } @@ -2281,13 +2262,11 @@ mod tests { .request(moq_net::Path::from_static("acme")); drive_tick().await; let (_, broadcast) = announced(&origin).await; - let track = broadcast + let handle = broadcast .track(&crate::group_track(moq_net::Path::from_static(""))) - .expect("track") - .subscribe(None) - .await - .expect("subscribe"); - let mut track = moq_json::snapshot::Consumer::::new(track, Default::default()); + .expect("track"); + let mut track = moq_json::snapshot::Consumer::::new(handle.clone(), Default::default()); + handle.info().await.expect("subscribe"); let drain = |track: &mut moq_json::snapshot::Consumer| { use futures::FutureExt; let mut frames = Vec::new(); @@ -2358,12 +2337,13 @@ mod tests { /// Subscribe to `label`'s presence track on `broadcast`, driving a tick so /// the producer adopts the request. async fn hold_presence(broadcast: &moq_net::broadcast::Consumer, label: &str) -> Reader { - let subscribing = broadcast - .track(&presence_track(moq_net::Path::new(label).unwrap())) - .expect("track") - .subscribe(None); + let reader = Reader::new( + broadcast + .track(&presence_track(moq_net::Path::new(label).unwrap())) + .expect("track"), + ); drive_tick().await; - Reader::new(subscribing.await.expect("held")) + reader } /// A held presence track is cumulative from when it was first held: it @@ -2442,15 +2422,15 @@ mod tests { let broadcast = origin.consume().request(".stats/node", None).await.expect("resolve"); // Let the request reach the stats broadcast's queue before the drain. - let subscribing = broadcast + let handle = broadcast .track(&presence_track(moq_net::Path::from_static(""))) - .expect("track") - .subscribe(None); + .expect("track"); + let mut track = Reader::new(handle.clone()); for _ in 0..8 { tokio::task::yield_now().await; } assert_eq!(tick(), 1, "held"); - let mut track = Reader::new(subscribing.await.expect("held")); + handle.info().await.expect("held"); assert_eq!(try_presence(&mut track), Some(PresenceFrame::new()), "held at zero"); // The label records while held: the same subscription carries it. @@ -2498,12 +2478,13 @@ mod tests { /// Subscribe to `path`'s prefix track on `broadcast`, driving a tick so the /// producer adopts the request. async fn hold_prefix(broadcast: &moq_net::broadcast::Consumer, path: &str) -> Reader { - let subscribing = broadcast - .track(&prefix_track(moq_net::Path::new(path).unwrap())) - .expect("track") - .subscribe(None); + let reader = Reader::new( + broadcast + .track(&prefix_track(moq_net::Path::new(path).unwrap())) + .expect("track"), + ); drive_tick().await; - Reader::new(subscribing.await.expect("held")) + reader } /// The latest buffered prefix frame, `None` when nothing is buffered. @@ -2696,15 +2677,15 @@ mod tests { }; let broadcast = origin.consume().request(".stats/node", None).await.expect("resolve"); - let subscribing = broadcast + let handle = broadcast .track(&prefix_track(moq_net::Path::from_static("acme"))) - .expect("track") - .subscribe(None); + .expect("track"); + let mut track = Reader::new(handle.clone()); for _ in 0..8 { tokio::task::yield_now().await; } assert_eq!(tick(), 1, "held"); - let mut track = Reader::new(subscribing.await.expect("held")); + handle.info().await.expect("held"); assert_eq!(last_prefix(&mut track), Some(PrefixFrame::new()), "held at zero"); let _feed = feed(®istry, Tier::default(), "acme/live", true, 1, 7).await; diff --git a/rs/moq-transcode/benches/ladder.rs b/rs/moq-transcode/benches/ladder.rs index 73ae3973e55..0075767710e 100644 --- a/rs/moq-transcode/benches/ladder.rs +++ b/rs/moq-transcode/benches/ladder.rs @@ -223,7 +223,7 @@ fn flapping(c: &mut Criterion) { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); let current = loop { let snapshot = catalogs.next().await.unwrap().unwrap(); if !snapshot.video.renditions.is_empty() { diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 95a8e9fea32..7f19085f8a5 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -126,11 +126,7 @@ impl Transcoder { // The source catalog drives everything; wait for a snapshot with a usable // video rendition (the first may precede the source publishing its video). - let track = source - .track(hang::Catalog::DEFAULT_NAME)? - .subscribe(hang::Catalog::default_subscription()) - .await?; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(source.track(hang::Catalog::DEFAULT_NAME)?); let mut decoders = catalog::Decoders::new(config.feed_decoder()); let (source_name, source_config, snapshot) = loop { let Some(snapshot) = catalogs.next().await? else { @@ -743,7 +739,6 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let track = track.subscribe(None).await.unwrap(); let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); // The catalog track exists from the start but may open empty; the rung // appears once the transcoder has read the source catalog. @@ -850,7 +845,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -972,7 +967,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); let derived = await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") @@ -1050,7 +1045,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); let derived = await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/360p") @@ -1151,7 +1146,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1218,7 +1213,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1290,7 +1285,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1375,7 +1370,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1486,7 +1481,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1580,7 +1575,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1666,7 +1661,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1716,7 +1711,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) @@ -1835,7 +1830,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); let derived = await_catalog(&mut catalogs, |snapshot| !snapshot.video.renditions.is_empty()).await; // Sized against the 640x360 H.264 rendition: no room for 720p, and 120p is @@ -1909,7 +1904,7 @@ mod tests { Err(err) => panic!("catalog track: {err}"), } }; - let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track); catalogs.next().await.unwrap().unwrap(); // Drop the source: the catalog track ends and the broadcast closes, so diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 9cb46a7d1bd..a0d98402281 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -16,6 +16,10 @@ Replace stream-track `appendDatagram` / `insertDatagram` / `recvDatagram` with ` A `nil` `TrackInfo.maxAge`, the default, and a `nil` info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited: true`, which ignores `maxAge`, where you relied on `nil` meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. +### Snapshot consumers subscribe themselves at a zero delay ([#7736](https://github.com/moq-dev/moq/pull/7736)) + +`Json.SnapshotConsumer(broadcast:name:priority:)` takes the `BroadcastConsumer` and the track name instead of `track:`, and subscribes to the track itself at a zero `delay.max` and `priority` (default 0). Drop the `subscribeTrack` call; a refused subscription now throws from the first read. Iteration skips every group a newer one supersedes, and `latest()` no longer waits for a lower group the track still owes. Publish a stream track when every state must survive, or a window track for a bounded recent history. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch(maxBps:)` and `setTarget(targetBps:)` and `Viewer.update(maxBps:)` throw it, so call them with `try`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. @@ -179,7 +183,7 @@ Application calls are unchanged. ### JSON consumers yield `Json.Timed` (#5677) `Json.SnapshotConsumer` and `Json.StreamConsumer` yield `Json.Timed` (`value`, `timestampUs`) instead of the bare value; `timestampUs` is `nil` when untimed. -A snapshot consumer's `next()` now yields every state in order; call `latest()` for the newest. +A snapshot consumer's `next()` now yields each state in order, skipping every group a newer one supersedes (see the zero-delay entry above); call `latest()` for the newest. Timestamps are rounded down to a whole microsecond. ### Ranges filter reads (#5929) diff --git a/swift/README.md b/swift/README.md index e7a0d9f1373..ce520f854d4 100644 --- a/swift/README.md +++ b/swift/README.md @@ -94,7 +94,8 @@ not found. lite-07 uses independent requests. JSON tracks live under the `Json` namespace, mirroring the `moq-json` crate, and carry your own `Codable` types with the framing handled for you. Each type wraps a track: a producer takes over a `TrackProducer` and advertises it in the broadcast's catalog, and a consumer takes over a -`TrackConsumer`. You opt into one of three distinct modes: `Json.SnapshotProducer`/`Json.SnapshotConsumer` +`TrackConsumer`, except `Json.SnapshotConsumer(broadcast:name:priority:)`, which subscribes itself at a +zero `delay.max`. You opt into one of three distinct modes: `Json.SnapshotProducer`/`Json.SnapshotConsumer` (lossy latest-value, a subscriber only sees the newest value), `Json.StreamProducer`/`Json.StreamConsumer` (lossless append-log, every record preserved in order), or `Json.WindowProducer`/`Json.WindowConsumer` (a sliding window of records a reader can join at any point, not advertised in the catalog). Values encode/decode at the boundary with diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index aa4e095fec1..c9e8eb3bcab 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -82,18 +82,19 @@ extension Json { } /// Read side of a JSON snapshot track (lossy latest-value). Iterating yields each state in - /// order with its timestamp: `for try await state in json { ... }`. Groups older than the - /// subscription's `delay.max` are skipped; `latest()` skips to the newest state instead. + /// order with its timestamp: `for try await state in json { ... }`. Every group a newer one + /// supersedes is skipped; `latest()` skips to the newest state instead. public final class SnapshotConsumer: AsyncSequence, Sendable { /// The decoded snapshot state emitted by this sequence. public typealias Element = Timed let ffi: MoqJsonSnapshotConsumer - /// Read `track` as a JSON snapshot track. Takes over `track`, whose handle is closed - /// afterward; throws if it has already read a group. - public init(track: TrackConsumer) throws { - ffi = try MoqJsonSnapshotConsumer(track: track.ffi) + /// Subscribe to the track `name` on `broadcast` and read it as a JSON snapshot track. + /// The consumer owns its subscription, at a zero `delay.max` and `priority` (higher + /// first); a read waits for it to resolve and throws if it cannot. + public init(broadcast: BroadcastConsumer, name: String, priority: Int8 = 0) throws { + ffi = try MoqJsonSnapshotConsumer(broadcast: broadcast.ffi, name: name, priority: priority) } /// The next state in order, or `nil` once the track ends or is closed. diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 5afbf0253fe..92686f12e50 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -464,7 +464,7 @@ final class SmokeTests: XCTestCase { broadcast: broadcast, track: try broadcast.publishTrack(name: "status", info: TrackInfo(timescale: 1_000_000, compress: true))) let consumer = try Json.SnapshotConsumer( - track: try await broadcast.consume().subscribeTrack(name: "status")) + broadcast: try broadcast.consume(), name: "status") for viewers in 1...4 { try producer.update(Status(state: "live", viewers: viewers), timestamp: micros(UInt64(viewers) * 1000)) @@ -557,7 +557,7 @@ final class SmokeTests: XCTestCase { let consumer = try broadcast.consume() let snapshotConsumer = try Json.SnapshotConsumer<[String: Int]>( - track: try await consumer.subscribeTrack(name: "status")) + broadcast: consumer, name: "status") let streamConsumer = try Json.StreamConsumer<[String: Int]>( track: try await consumer.subscribeTrack(name: "events")) while try await snapshotDemand.wantedChanged() == nil {} diff --git a/test/interop/clients/js-native/catalog.ts b/test/interop/clients/js-native/catalog.ts index 23a09ba5105..b5185b88f7c 100644 --- a/test/interop/clients/js-native/catalog.ts +++ b/test/interop/clients/js-native/catalog.ts @@ -34,18 +34,22 @@ try { await request.active.changed(); broadcast = request.active.peek(); } - const track = broadcast.track(Catalog.TRACK).subscribe({ priority: Catalog.PRIORITY.catalog }); + const track = broadcast.track(Catalog.TRACK); + const consumer = new Json.Snapshot.Consumer({ + track, + schema: Catalog.RootSchema, + priority: Catalog.PRIORITY.catalog, + }); try { const { compress } = await track.info(); assert.equal(compress, version === "moq-lite-07-wip", "wrong compression metadata"); - const consumer = new Json.Snapshot.Consumer({ track, schema: Catalog.RootSchema }); const root = (await consumer.latest())?.value; assert(root, "catalog ended before a snapshot"); const video = Object.keys(root.video?.renditions ?? {}).sort(); const audio = Object.keys(root.audio?.renditions ?? {}).sort(); console.error(`catalog compress=${compress} video=${video.join(",")} audio=${audio.join(",")}`); } finally { - track.close(); + consumer.close(); } } finally { request.close(); diff --git a/test/interop/clients/js-native/subscribe.ts b/test/interop/clients/js-native/subscribe.ts index 58b385c1f62..c8d23fb92f8 100644 --- a/test/interop/clients/js-native/subscribe.ts +++ b/test/interop/clients/js-native/subscribe.ts @@ -93,8 +93,11 @@ if ( async function catalog( bc: Moq.Broadcast.Consumer, ): Promise<{ video: [string, Catalog.VideoConfig]; audio: [string, Catalog.AudioConfig][] }> { - const track = bc.track("catalog.json").subscribe({ priority: Catalog.PRIORITY.catalog }); - const catalog = new Json.Snapshot.Consumer({ track, schema: Catalog.RootSchema }); + const catalog = new Json.Snapshot.Consumer({ + track: bc.track("catalog.json"), + schema: Catalog.RootSchema, + priority: Catalog.PRIORITY.catalog, + }); for (;;) { const root = (await catalog.latest())?.value; if (!root) throw new Error("catalog ended without a video and an audio track");