From d4a746106f55635d2235531d614d24aa008829c2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 27 Aug 2026 10:08:35 -0700 Subject: [PATCH 1/8] refactor(net)!: make group delivery order a handle, and retire the Ordered wire field `track::Subscriber` exposed two delivery orders as two methods on one handle, with coupled cursors: `recv_datagram` bumped the sequence cursor, and `read_frame` bumped both. Interleaving them was expressible and the result was hard to reason about, so the rule lived in doc comments rather than in the type. `Subscriber::ordered(self) -> track::Ordered` makes the order a handle. Consuming `self` makes mixing unrepresentable. The plain `Subscriber` keeps the arrival cursor (`recv_group`) and datagrams (`recv_datagram`), which is what the relay forwarders use; `Ordered` owns `next_group` plus its own bounds, control, and finished. Datagrams no longer touch any group cursor: they are unordered by construction, so there is nothing for a sequence cursor to do with them. `read_frame` is removed from the track level. It was two different functions under one name (plain: one frame per group then skip; spliced: drain every frame in sequence), so it is removed rather than moved. Callers loop `next_group()` + `group.read_frame()`. The ordered cursor no longer discards. A group already cached costs nothing to deliver, and dropping it puts a hole in the sequence a decoder is reading, so a backlog is delivered as a burst, in order, however old it is. `Subscription::max_age` instead bounds how long a *handed-out* group may block, which group expiry already enforces (it only convicts a read that is Pending). This matches what moq-mux's container consumer has always done. The arrival cursor keeps writing a backlog off, which is what lets a relay shed one. `Ordered` is a `bool` on the wire and in the model, and it goes away entirely: model, `Subscription`, `Info`, aggregation, the lite priority queue, and the lite-06-wip wire. Group order within a track is now normatively newest-first, so a congested track sheds its backlog rather than its live edge; a subscriber wanting sequence order reorders locally, which costs the network nothing and does not let one subscriber's preference reach a track a relay is fanning out to many. Deployed lite-03/04/05 keep the byte in their layout (written as 0, ignored on read) so every field behind it stays put. The IETF adapter already only spoke Descending, so it maps to the fixed order unchanged. moq-ffi's `MoqTrackConsumer` cannot express a consuming conversion, so it commits on first use: whichever cursor a caller reaches for first is the one the track keeps, and the other returns `Unsupported`. `moq_track_info.ordered` and `moq_subscription.ordered` are removed from the C ABI, which is a layout break for a prebuilt consumer. `goaway_cluster`'s failover test asked for `ordered: true` to get sequence-order arrival across every hop. With the field gone the wire no longer promises that, so it now asserts what a failover actually owes: every group arrives exactly once with its frames intact, collected in arrival order and checked for completeness per phase. Regression test: `raw_track_next_group_is_repeatable` covers the FFI cursor conversion running more than once (the first draft dropped the converted handle on the second call). Drafts updated in the same PR: `draft-lcurley-moq-lite` loses `Subscriber Ordered` and `Publisher Ordered` and gains a normative Group Order section; `draft-lcurley-moq-hang`'s recording Track Object drops the field it inherited. The generated `swift/`/`kt/` bindings still need regenerating against the new moq-ffi surface; that lands with the stacked bindings PR. Co-Authored-By: Claude Opus 5 --- demo/web/src/stats.ts | 2 +- doc/lib/c/index.md | 5 - doc/lib/kt/moq.md | 3 +- doc/lib/py/moq-rs.md | 5 +- doc/lib/swift/moq.md | 3 +- drafts/draft-lcurley-moq-hang.md | 3 +- drafts/draft-lcurley-moq-lite.md | 36 +- go/wrapper/publish.go | 2 +- go/wrapper/subscribe.go | 4 +- js/json/src/snapshot/compression.test.ts | 16 +- js/json/src/snapshot/consumer.ts | 4 +- js/json/src/snapshot/snapshot.test.ts | 16 +- js/json/src/stream/codec.test.ts | 2 +- js/json/src/stream/consumer.ts | 4 +- js/json/src/stream/stream.test.ts | 2 +- js/msf/src/catalog.ts | 2 +- js/net/src/broadcast.test.ts | 25 +- js/net/src/ietf/subscriber.ts | 12 +- js/net/src/integration.test.ts | 72 +-- js/net/src/lite/priority.ts | 10 +- js/net/src/lite/publisher.test.ts | 23 +- js/net/src/lite/publisher.ts | 4 - js/net/src/lite/subscribe.test.ts | 9 +- js/net/src/lite/subscribe.ts | 38 +- js/net/src/lite/subscriber.ts | 5 - js/net/src/lite/track.test.ts | 2 - js/net/src/lite/track.ts | 25 +- js/net/src/lite/version.ts | 20 + js/net/src/track.test.ts | 69 +-- js/net/src/track.ts | 233 ++++++-- js/net/src/zod.ts | 2 +- js/publish/src/catalog.test.ts | 2 +- js/watch/src/broadcast.ts | 3 +- py/moq-rs/README.md | 7 +- py/moq-rs/moq/publish.py | 4 +- py/moq-rs/moq/subscribe.py | 4 +- rs/libmoq/src/api.rs | 12 +- rs/libmoq/src/consume.rs | 11 +- rs/libmoq/src/test.rs | 36 -- rs/moq-bench/src/connection.rs | 20 +- rs/moq-ffi/src/consumer.rs | 66 ++- rs/moq-ffi/src/producer.rs | 12 +- rs/moq-ffi/src/test.rs | 52 +- rs/moq-gst/src/sink/pad.rs | 6 +- rs/moq-json/examples/telemetry.rs | 2 +- rs/moq-json/src/snapshot/consumer.rs | 4 +- rs/moq-json/src/snapshot/mod.rs | 8 +- rs/moq-json/src/stream/consumer.rs | 4 +- rs/moq-json/src/stream/mod.rs | 5 +- rs/moq-mux/src/catalog/msf/consumer.rs | 7 +- rs/moq-mux/src/container/fmp4/muxer.rs | 4 +- rs/moq-mux/src/container/ts/export.rs | 4 +- rs/moq-net/src/lite/priority.rs | 205 +------ rs/moq-net/src/lite/publisher.rs | 32 +- rs/moq-net/src/lite/subscribe.rs | 66 ++- rs/moq-net/src/lite/subscriber.rs | 8 +- rs/moq-net/src/lite/track.rs | 11 +- rs/moq-net/src/lite/version.rs | 13 + rs/moq-net/src/model/group.rs | 5 - rs/moq-net/src/model/origin.rs | 124 ---- rs/moq-net/src/model/resume.rs | 61 +- rs/moq-net/src/model/subscription.rs | 32 -- rs/moq-net/src/model/track.rs | 704 +++++++---------------- rs/moq-relay/tests/goaway_cluster.rs | 71 ++- rs/moq-rtmp/src/dial.rs | 10 +- rs/moq-stats/src/produce.rs | 51 +- rs/moq-transcode/src/feed.rs | 2 +- rs/moq-transcode/src/lib.rs | 20 +- swift/Sources/Moq/Broadcast.swift | 4 +- swift/Sources/Moq/Dynamic.swift | 2 +- swift/Sources/Moq/Track.swift | 2 +- 71 files changed, 920 insertions(+), 1434 deletions(-) diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index d7208789eb0..11aa846a2a5 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -145,7 +145,7 @@ function subscribeNode(effect: Signals.Effect, origin: Net.Origin.Table, path: N if (!consumer) return; const sub = (trackName: string, key: K) => { - const track = consumer.subscribe(trackName); + const track = consumer.subscribe(trackName).ordered(); effect.cleanup(() => track.close()); effect.spawn(async () => { for (;;) { diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 5556df2c312..2e69cfc2ac1 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -344,14 +344,10 @@ codec metadata. ## Raw Track Options `moq_publish_track` accepts optional publisher-side track properties: -`ordered` controls prioritization only. When true, groups are prioritized in -sequence order. Groups may always arrive out-of-order (or not at all) over the -network. ```c struct moq_track_info info = {0}; info.priority = 3; -info.ordered = true; info.max_age_ms = 1000; info.max_age_present = true; info.timescale = 1000000; @@ -371,7 +367,6 @@ Fields ending in `_present` decide whether the matching optional value is set: ```c struct moq_subscription sub = {0}; sub.priority = 5; -sub.ordered = true; sub.max_age_ms = 25; sub.group_start = 10; sub.group_start_present = true; diff --git a/doc/lib/kt/moq.md b/doc/lib/kt/moq.md index cc1ec00f5b6..0f2f65a7de8 100644 --- a/doc/lib/kt/moq.md +++ b/doc/lib/kt/moq.md @@ -110,10 +110,9 @@ val track = announcement.broadcast().subscribeTrack( Subscription(priority = 10u.toUByte()), ) val info = track.info() -track.update(Subscription(priority = 20u.toUByte(), ordered = false)) +track.update(Subscription(priority = 20u.toUByte())) ``` -`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network. A catalog rendition may name a *different* broadcast: `MoqVideo.broadcast` / `MoqAudio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. `subscribeMedia`, `subscribeTrack`, `fetchGroup`, and `fetchMediaGroup` take a track name rather than a rendition, so resolve first: diff --git a/doc/lib/py/moq-rs.md b/doc/lib/py/moq-rs.md index 64ee708640d..c6b37b5e800 100644 --- a/doc/lib/py/moq-rs.md +++ b/doc/lib/py/moq-rs.md @@ -240,7 +240,7 @@ track = await broadcast_consumer.subscribe_track( subscription=moq.Subscription(priority=10), ) info = track.info() -track.update(moq.Subscription(priority=20, ordered=False)) +track.update(moq.Subscription(priority=20)) async for group in track: async for frame in group: print(frame.timestamp_us, frame.payload) @@ -248,8 +248,7 @@ async for group in track: `write_frame` on a track creates a one-frame group by default, using a microsecond raw-track timescale. Consumers receive a `Frame` from `read_frame()` or group iteration, carrying `payload` and `timestamp_us`. (Media tracks yield a `MediaFrame`, which adds the codec-derived `keyframe` flag.) Use `append_group()` for multi-frame groups (e.g., a video GOP). Use `create_group(sequence)` for sparse or replayed groups. `finish_at(final_sequence)` declares the exclusive end while still permitting lower groups to arrive, and `abort(error_code)` terminates a track or group with an application error. -`TrackConsumer.info()` returns the publisher's track properties (timescale, cache, priority, ordering priority), and `update()` changes this subscriber's delivery preferences without resubscribing. -`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network. +`TrackConsumer.info()` returns the publisher's track properties (timescale, cache, priority), and `update()` changes this subscriber's delivery preferences without resubscribing. ### Fetching raw groups diff --git a/doc/lib/swift/moq.md b/doc/lib/swift/moq.md index cf1b39fbf28..d77de219d7f 100644 --- a/doc/lib/swift/moq.md +++ b/doc/lib/swift/moq.md @@ -123,10 +123,9 @@ let track = try await announcement.broadcast.subscribeTrack( name: "events", subscription: Subscription(priority: 10)) let info = try track.info() -track.update(subscription: Subscription(priority: 20, ordered: false)) +track.update(subscription: Subscription(priority: 20)) ``` -`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network. A catalog rendition may name a *different* broadcast: `Video.broadcast` / `Audio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 13c73245acb..8f460094cff 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -654,7 +654,6 @@ For the same reason a publisher SHOULD NOT combine tracks into a single object, ~~~ Track Object { Publisher Priority (8) - Publisher Ordered (8) Timescale (i) } ~~~ @@ -780,7 +779,7 @@ TODO Security A consumer parsing a recording ({{recording}}) is parsing data at rest that it did not necessarily write. It MUST bounds-check a segment object's group `Length` and each frame's `Message Length` against the bytes actually retrieved, rather than trusting either to describe the object, and it MUST treat a malformed object as a missing segment rather than letting it invalidate the recording. -It MUST reject a track object with an invalid `Publisher Ordered` value or a zero `Timescale`. +It MUST reject a track object with a zero `Timescale`. Varint fields are subject to the same limits as moq-lite {{moql}}. A recording inherits the confidentiality and integrity properties of the storage holding it; encryption at rest is transparent to the format and out of scope. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index fb12d9836a5..d9df5538ea3 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -131,7 +131,6 @@ Both bounds may be refined to a Frame within their Group, so a subscription can The subscriber and publisher both indicate their delivery preference: - `Priority` indicates if Track A should be transmitted instead of Track B. -- `Ordered` indicates if the Groups within a Track should be transmitted in order. - `Subscriber Max Age` indicates the maximum age before a non-latest Group is dropped from live delivery; `Publisher Max Age` indicates the maximum age before a non-latest Group is dropped from the publisher's cache. The combination of these preferences enables the most important content to arrive during network degradation while still respecting encoding dependencies. @@ -450,11 +449,10 @@ moq-lite consists of multiple groups being transmitted in parallel across separa How these streams get transmitted over the network is very important, and yet has been distilled down into a few simple properties: ## Prioritization -The Publisher and Subscriber both exchange `Priority` and `Ordered` values: -- `Priority` determines which Track should be transmitted next. -- `Ordered` determines which Group within the Track should be transmitted next. +The Publisher and Subscriber both exchange a `Priority` value, which determines which Track should be transmitted next. +Group order within a Track is fixed: newest first. -A publisher SHOULD attempt to transmit streams based on these fields. +A publisher SHOULD attempt to transmit streams based on these rules. This depends on the QUIC implementation and it may not be possible to get fine-grained control. ### Priority @@ -489,16 +487,15 @@ ali/video: subscriber_priority=1 publisher_priority=1 The subscriber priority takes precedence, so the subscriber can likewise full-screen Ali's window by raising the subscriber priority of Ali's tracks above Bob's. -### Ordered -The `Subscriber Ordered` field signals if older (0x1) or newer (0x0) groups should be transmitted first within a Track. -The `Publisher Ordered` field MAY likewise be used to resolve conflicts. +### Group Order +Within a Track, a publisher SHOULD transmit the newest Group first. +Under congestion this sheds the backlog rather than the live edge, which is what a Group boundary exists to make possible. -An application SHOULD use `ordered` when it wants to provide a VOD-like experience, preferring to buffer old groups rather than skip them. -An application SHOULD NOT use `ordered` when it wants to provide a live experience, preferring to skip old groups rather than buffer them. +There is no field to invert it. +A subscriber that wants Groups in sequence order gets them by reading in sequence order: reordering is a local decision, it costs the network nothing, and encoding it on the wire only lets one subscriber's preference reach a Track that a relay is fanning out to many. +Such a subscriber SHOULD raise its `Subscriber Max Age` so the Groups it intends to read in order are still being delivered when it reaches them. -Note that [expiration](#expiration) is not affected by `ordered`. -An old group may still be cancelled/skipped if it exceeds the `Subscriber Max Age`. -An application MUST support gaps and out-of-order delivery even when `ordered` is true. +A subscriber MUST support gaps and out-of-order delivery regardless. ## Expiration @@ -950,7 +947,6 @@ SUBSCRIBE Message { Track Name (s) Epoch (i) Subscriber Priority (8) - Subscriber Ordered (8) Subscriber Max Age (i) Group Start (i) Group End (i) @@ -972,11 +968,6 @@ The priority of the subscription within the session, represented as a u8. The publisher SHOULD transmit *higher* values first during congestion. See the [Prioritization](#prioritization) section for more information. -**Subscriber Ordered**: -A single byte representing whether groups are transmitted in ascending (0x1) or descending (0x0) order. -The publisher SHOULD transmit *older* groups first during congestion if true. -See the [Prioritization](#prioritization) section for more information. - **Subscriber Max Age**: The subscriber's preference, in milliseconds, for how long a non-latest group may remain in flight before being considered stale and dropped from live delivery. The publisher SHOULD reset (at the QUIC level) Group Streams for groups whose age relative to the latest group exceeds this duration. @@ -1019,7 +1010,6 @@ The start and end group can be changed in either direction (growing or shrinking SUBSCRIBE_UPDATE Message { Message Length (i) Subscriber Priority (8) - Subscriber Ordered (8) Subscriber Max Age (i) Group Start (i) Group End (i) @@ -1063,7 +1053,6 @@ TRACK_INFO Message { Message Length (i) Epoch (i) Publisher Priority (8) - Publisher Ordered (8) Publisher Max Age (i) Timescale (i) } @@ -1081,10 +1070,6 @@ Subscribers key their TRACK_INFO cache by it, and a SUBSCRIBE or FETCH that will The publisher's priority for this Track, represented as a u8, used only to resolve ties between subscriptions of equal subscriber priority. See the [Prioritization](#prioritization) section for more information. -**Publisher Ordered**: -The publisher's group ordering preference (ascending `0x1` or descending `0x0`), used only to resolve ties. -See the [Prioritization](#prioritization) section for more information. - **Publisher Max Age**: The maximum age, in milliseconds, that the publisher caches a non-latest group past the arrival of a newer group. Applies only to non-latest groups; the latest group is always retained. @@ -1368,6 +1353,7 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. +- Removed `Subscriber Ordered` from SUBSCRIBE and SUBSCRIBE_UPDATE, and `Publisher Ordered` from TRACK_INFO and SUBSCRIBE_OK. Group order within a Track is now normatively newest-first, with no field to invert it: a subscriber that wants sequence order reads in sequence order, which costs the network nothing and does not let one subscriber's preference reach a Track a relay is fanning out to many. Note this removes a byte from the middle of each message, so a lite-06 peer cannot parse a lite-05 one's SUBSCRIBE (the earlier drafts keep the byte, and an implementation serving them SHOULD write 0 and ignore what it reads). ## moq-lite-05 - Renamed ANNOUNCE_INTEREST to ANNOUNCE_REQUEST and ANNOUNCE to ANNOUNCE_BROADCAST. diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 08ffef76612..dfc3526bc9f 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -477,7 +477,7 @@ func (t *TrackProducer) Abort(errorCode uint16) error { } // Consume reads directly from this producer's track. subscription tunes delivery -// (delivery priority, group ordering priority, group range); pass nil for defaults. +// (delivery priority, group range); pass nil for defaults. func (t *TrackProducer) Consume(subscription *Subscription) (*TrackConsumer, error) { inner, err := t.inner.Consume(subscription) if err != nil { diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index a2ff7c23160..e5a2cd90e6a 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -50,7 +50,7 @@ func (b *BroadcastConsumer) SubscribeCatalog() (*CatalogConsumer, error) { } // SubscribeTrack subscribes to a track, receiving arbitrary byte payloads. -// subscription tunes delivery priority, group ordering priority, and group range; pass nil for defaults. +// subscription tunes delivery priority, group range, and staleness; pass nil for defaults. func (b *BroadcastConsumer) SubscribeTrack(name string, subscription *Subscription) (*TrackConsumer, error) { inner, err := b.inner.SubscribeTrack(name, subscription) if err != nil { @@ -81,7 +81,7 @@ func (b *BroadcastConsumer) FetchMediaGroup(name string, sequence uint64, contai } // SubscribeMedia subscribes to a media track, decoded with the given container. -// subscription tunes delivery priority, group ordering priority, group range, and +// subscription tunes delivery priority, group range, and // the max age; pass nil for defaults. Raise Subscription.MaxAgeMs to // buffer instead of skipping a stalled group. func (b *BroadcastConsumer) SubscribeMedia(name string, container Container, subscription *Subscription) (*MediaConsumer, error) { diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index 563ad3831f6..d1c81a35e7d 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -18,7 +18,7 @@ async function drainCompressed(track: Track.Subscriber): Promise { } // The raw (stored) bytes of a track's first frame, without reconstructing JSON. -async function firstFrame(track: Track.Subscriber): Promise { +async function firstFrame(track: Track.Ordered): Promise { const group = await track.nextGroup(); if (!group) throw new Error("expected a group"); const frame = await group.readFrame(); @@ -27,7 +27,7 @@ async function firstFrame(track: Track.Subscriber): Promise { } // Count the groups a (finished) track published, draining each so the reads terminate. -async function groupCount(track: Track.Subscriber): Promise { +async function groupCount(track: Track.Ordered): Promise { let groups = 0; for (;;) { const group = await track.nextGroup(); @@ -92,7 +92,9 @@ test("a group's snapshot decodes from a fresh decoder", async () => { producer.finish(); const decoder = new Decoder(); - expect(JSON.parse(dec.decode(decoder.frame(await firstFrame(track.subscribe()))))).toEqual({ hello: "world" }); + expect(JSON.parse(dec.decode(decoder.frame(await firstFrame(track.subscribe().ordered()))))).toEqual({ + hello: "world", + }); }); test("compressed deltas reuse the window", async () => { @@ -104,7 +106,7 @@ test("compressed deltas reuse the window", async () => { producer.update({ note: phrase, echo: phrase }); producer.finish(); - const group = await track.subscribe().nextGroup(); + const group = await track.subscribe().ordered().nextGroup(); if (!group) throw new Error("expected a group"); await group.readFrame(); // snapshot const delta = await group.readFrame(); @@ -122,8 +124,8 @@ test("compression shrinks a repetitive frame", async () => { const compressed = new Track.Producer("compressed"); new Producer({ track: compressed, deltaRatio: 0, compression: true }).update(value); - const plainLen = (await firstFrame(plain.subscribe())).length; - const compressedLen = (await firstFrame(compressed.subscribe())).length; + const plainLen = (await firstFrame(plain.subscribe().ordered())).length; + const compressedLen = (await firstFrame(compressed.subscribe().ordered())).length; expect(compressedLen).toBeLessThan(plainLen); }); @@ -140,7 +142,7 @@ test("compressed deltas roll on the compressed budget", async () => { }; const layout = new Track.Producer("layout"); - const layoutSub = layout.subscribe({ maxAge: REPLAY_LATENCY }); + const layoutSub = layout.subscribe({ maxAge: REPLAY_LATENCY }).ordered(); fill(layout); expect(await groupCount(layoutSub)).toBeGreaterThan(1); diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 980bfbaa46d..32106dc18dc 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -13,14 +13,14 @@ import type { Config } from "./encoder.ts"; * directly. */ export class Consumer { - #track: Moq.Track.Subscriber; + #track: Moq.Track.Ordered; #decoder: Decoder; #group?: Moq.Group.Consumer; #framesRead = 0; constructor(track: Moq.Track.Subscriber, config: Config = {}) { - this.#track = track; + this.#track = track.ordered(); this.#decoder = new Decoder(config); } diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 6b5515c5f7b..b8ad3fa0d37 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -18,7 +18,7 @@ async function drain(track: Track.Subscriber): Promise { // 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.Subscriber): Promise { +async function structure(track: Track.Ordered): Promise { const counts: number[] = []; for (;;) { const group = await track.nextGroup(); @@ -51,7 +51,7 @@ test("deltaRatio 0 disables deltas, like off", async () => { // `0` is treated as off, not a degenerate "enabled" value that keeps the group open: each change // is its own single-frame snapshot group. - expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([1, 1]); + expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1, 1]); }); test("live consumer sees each update", async () => { @@ -72,7 +72,7 @@ test("unchanged value writes nothing", async () => { producer.update({ a: 1 }); producer.finish(); - expect(await structure(track.subscribe())).toEqual([1]); + expect(await structure(track.subscribe().ordered())).toEqual([1]); }); test("deltas share one group", async () => { @@ -84,7 +84,7 @@ test("deltas share one group", async () => { producer.finish(); // All updates fit in a single group as snapshot + two deltas. - expect(await structure(track.subscribe())).toEqual([3]); + expect(await structure(track.subscribe().ordered())).toEqual([3]); }); test("deltas reconstruct to the final value", async () => { @@ -165,7 +165,7 @@ test("tight ratio rolls snapshots", async () => { producer.update({ a: 4 }); // budget already exceeded, rolls group 1 producer.finish(); - expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([3, 1]); + expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([3, 1]); }); test("deltas stay within ratio times snapshot", async () => { @@ -179,7 +179,7 @@ test("deltas stay within ratio times snapshot", async () => { for (let n = 0; n <= 10; n++) producer.update({ n }); producer.finish(); - expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([10, 1]); + expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([10, 1]); }); test("array change is a wholesale delta", async () => { @@ -190,7 +190,7 @@ test("array change is a wholesale delta", async () => { producer.finish(); // The array is replaced wholesale in a delta, so it stays in the same group. - expect(await structure(track.subscribe())).toEqual([2]); + expect(await structure(track.subscribe().ordered())).toEqual([2]); }); test("late joiner collapses a buffered backlog to the latest value", async () => { @@ -216,5 +216,5 @@ test("frame cap rolls snapshot", async () => { } producer.finish(); - expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([256, 1]); + expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([256, 1]); }); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index fea99425706..a80ce2d0f15 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -103,7 +103,7 @@ test("a record JSON cannot represent is rejected", () => { // into it and wait there even though nothing was ever appended. test("a rejected record does not open a group", async () => { const track = new Track.Producer("test"); - const subscriber = track.subscribe(); + const subscriber = track.subscribe().ordered(); const producer = new Producer(track); expect(() => producer.append(undefined)).toThrow("not representable as JSON"); diff --git a/js/json/src/stream/consumer.ts b/js/json/src/stream/consumer.ts index dc7a57e34c7..de752805d5d 100644 --- a/js/json/src/stream/consumer.ts +++ b/js/json/src/stream/consumer.ts @@ -10,13 +10,13 @@ import { type ConsumerConfig, Decoder } from "./decoder.ts"; * {@link Decoder} directly. */ export class Consumer { - #track: Moq.Track.Subscriber; + #track: Moq.Track.Ordered; #decoder: Decoder; #group?: Moq.Group.Consumer; constructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) { - this.#track = track; + this.#track = track.ordered(); this.#decoder = new Decoder(config); } diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 8d88ba480b2..6fc309a0360 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -41,7 +41,7 @@ test("the whole log rides one group, never rolled", async () => { producer.finish(); // A single group holds everything, and the consumer reads it all in order. - const subscriber = track.subscribe(); + const subscriber = track.subscribe().ordered(); const group0 = await subscriber.nextGroup(); expect(group0?.sequence).toBe(0); const group1 = await subscriber.nextGroup(); diff --git a/js/msf/src/catalog.ts b/js/msf/src/catalog.ts index 24601e15ecc..69b2b9311ca 100644 --- a/js/msf/src/catalog.ts +++ b/js/msf/src/catalog.ts @@ -149,7 +149,7 @@ export function decode(raw: Uint8Array): Catalog { } /** Read and decode the next catalog frame from a track, or undefined if the track ended. */ -export async function fetch(track: Moq.Track.Subscriber): Promise { +export async function fetch(track: Moq.Track.Ordered): Promise { const frame = await track.readFrame(); if (!frame) return undefined; return decode(frame.payload); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 9a17c6d8ce5..dda5e52bf4d 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -26,8 +26,8 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async () const consumer = new TestConsumer(); // Two subscriptions to the same track share one upstream subscription... - const a = consumer.track("video").subscribe(); - const b = consumer.subscribe("video"); + const a = consumer.track("video").subscribe().ordered(); + const b = consumer.subscribe("video").ordered(); const request = await pendingRequest(consumer); expect(request?.name).toBe("video"); @@ -129,13 +129,12 @@ test("closing a broadcast preserves dequeued request sequences", async () => { test("a request exposes the aggregate subscription options", async () => { const consumer = new TestConsumer(); - consumer.subscribe("video", { priority: 3, ordered: true, maxAge: 100, startGroup: 10, endGroup: 20 }); - consumer.subscribe("video", { priority: 7, ordered: true, maxAge: 250, startGroup: 0, endGroup: 30 }); + consumer.subscribe("video", { priority: 3, maxAge: 100, startGroup: 10, endGroup: 20 }); + consumer.subscribe("video", { priority: 7, maxAge: 250, startGroup: 0, endGroup: 30 }); const request = await pendingRequest(consumer); expect(request?.subscription).toEqual({ priority: 7, - ordered: true, maxAge: 250, startGroup: 0, endGroup: 30, @@ -189,8 +188,8 @@ test("consumer track subscriptions fan out and close independently", async () => const consumer = new TestConsumer(); // Two subscriptions to one track dedupe onto a single upstream request... - const a = consumer.subscribe("video"); - const b = consumer.subscribe("video"); + const a = consumer.subscribe("video").ordered(); + const b = consumer.subscribe("video").ordered(); const request = await pendingRequest(consumer); if (!request) throw new Error("expected request"); @@ -215,7 +214,7 @@ test("subscribe serves a statically inserted track without a request", async () track1.appendGroup().close(); // The track already exists, so subscribe resolves immediately (no requested()). - const sub1 = broadcast.track("track1").subscribe(); + const sub1 = broadcast.track("track1").subscribe().ordered(); expect((await sub1.nextGroup())?.sequence).toBe(0); // No on-demand request was emitted for it. @@ -225,7 +224,7 @@ test("subscribe serves a statically inserted track without a request", async () const track2 = new TrackProducer("track2").accept(); broadcast.insertTrack(track2); - const sub2 = broadcast.track("track2").subscribe(); + const sub2 = broadcast.track("track2").subscribe().ordered(); track2.appendGroup().close(); expect((await sub2.nextGroup())?.sequence).toBe(0); }); @@ -234,8 +233,8 @@ test("two subscribers to one inserted track each get a full copy", async () => { const broadcast = new BroadcastProducer(); const producer = broadcast.createTrack("video"); - const a = broadcast.track("video").subscribe({ maxAge: 5000 }); - const b = broadcast.track("video").subscribe({ maxAge: 5000 }); + const a = broadcast.track("video").subscribe({ maxAge: 5000 }).ordered(); + const b = broadcast.track("video").subscribe({ maxAge: 5000 }).ordered(); producer.writeString("hello"); producer.writeString("world"); @@ -254,7 +253,7 @@ test("a late subscriber replays the cached window", async () => { // Written before anyone subscribes; retained in the cache for replay. producer.writeString("early"); - const late = broadcast.track("video").subscribe(); + const late = broadcast.track("video").subscribe().ordered(); expect(await late.readString()).toBe("early"); producer.writeString("later"); @@ -264,7 +263,7 @@ test("a late subscriber replays the cached window", async () => { test("a read throws Lagged on a gap, then resyncs to the next group", async () => { const broadcast = new BroadcastProducer(); const producer = broadcast.createTrack("video"); - const sub = broadcast.track("video").subscribe({ maxAge: 5000 }); + const sub = broadcast.track("video").subscribe({ maxAge: 5000 }).ordered(); // Group 0 overflows its frame cap without being read, evicting the front: a gap. const g0 = producer.appendGroup(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 62ea8b9a4eb..b01385115a5 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -403,12 +403,12 @@ export class Subscriber { console.debug(`subscribe start: id=${requestId} broadcast=${broadcast} track=${request.name}`); - // IETF negotiates group order in SUBSCRIBE_OK; this implementation only - // supports descending (newest-first), so commit ordered: false. (There's no - // per-frame timescale, so the rest stay at their defaults.) This - // resolves the consumer's track.info() and gives us the write side that - // incoming object streams are routed into. - const producer = request.accept({ ordered: false }); + // IETF negotiates group order in SUBSCRIBE_OK; this implementation only supports + // descending (newest-first), which is what moq-lite fixes group order to, so the + // mapping needs nothing here. (There's no per-frame timescale either, so every + // property stays at its default.) This resolves the consumer's track.info() and + // gives us the write side that incoming object streams are routed into. + const producer = request.accept({}); // Open the stream and wait for SUBSCRIBE_OK under a timeout. State // flows back via `state` so the timeout path can clean up the stream diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 4cb36f2b012..3ec80c6e0bc 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -77,7 +77,7 @@ async function runPublishSubscribeFlow(protocol: string, version?: number) { // Client consumes the broadcast and subscribes to a track const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); // Client reads data const data = await track.readString(); @@ -139,7 +139,6 @@ test("integration: lite subscription options and updates reach the publisher", a const remote = client.consume(Path.from("test")); const subscriber = remote.track("video").subscribe({ priority: 3, - ordered: true, maxAge: 250, startGroup: 0, endGroup: 9, @@ -147,17 +146,15 @@ test("integration: lite subscription options and updates reach the publisher", a const producer = await accepted; expect(producer.subscription.peek()).toEqual({ priority: 3, - ordered: true, maxAge: 250, startGroup: 0, endGroup: 9, }); const updated = producer.subscription.changed(); - subscriber.update({ priority: 8, ordered: false, maxAge: 500, startGroup: 2, endGroup: 12 }); + subscriber.update({ priority: 8, maxAge: 500, startGroup: 2, endGroup: 12 }); expect(await updated).toEqual({ priority: 8, - ordered: false, maxAge: 500, startGroup: 2, endGroup: 12, @@ -192,11 +189,14 @@ test("integration: lite applies initial and updated group bounds", async () => { for (let sequence = 0; sequence < GROUP_COUNT; sequence++) producer.appendGroup().close(); const remote = client.consume(Path.from("test")); - const subscriber = remote.track("video").subscribe({ - maxAge: REPLAY_LATENCY_MS, - startGroup: INITIAL_START_GROUP, - endGroup: INITIAL_END_GROUP, - }); + const subscriber = remote + .track("video") + .subscribe({ + maxAge: REPLAY_LATENCY_MS, + startGroup: INITIAL_START_GROUP, + endGroup: INITIAL_END_GROUP, + }) + .ordered(); try { expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_START_GROUP); expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_END_GROUP); @@ -333,7 +333,8 @@ test("integration: lite draft-05 datagrams not sent on a non-datagram transport" const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); + const datagrams = remote.track("video").subscribe(); // Keep pushing a group (to prove the connection is live) and a datagram (which must be dropped). let stop = false; @@ -350,7 +351,8 @@ test("integration: lite draft-05 datagrams not sent on a non-datagram transport" expect(grp).toBe("group"); // No datagram is ever delivered: recvDatagram stays pending until the timeout wins. - const datagram = track.recvDatagram(); + // Its own handle, since the group reads above took the ordered cursor. + const datagram = datagrams.recvDatagram(); datagram.catch(() => {}); // The track close below settles it; swallow to avoid a stray rejection. const outcome = await Promise.race([datagram, sleep(50).then(() => "timeout" as const)]); expect(outcome).toBe("timeout"); @@ -417,7 +419,7 @@ test("integration: lite draft-05 missing datagram writer does not close streams" const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); producer.appendDatagram(Timestamp.fromMillis(0), enc.encode("dgram")); producer.writeString("group"); @@ -444,7 +446,7 @@ test("integration: lite draft-05 missing datagram reader does not close streams" const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); producer.appendDatagram(Timestamp.fromMillis(0), enc.encode("dgram")); producer.writeString("group"); @@ -481,7 +483,7 @@ test("integration: a group reset carries the peer's code to the subscriber", asy const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); const group = producer.appendGroup(); group.writeString("frame"); @@ -734,7 +736,7 @@ async function runSubscriberTeardown(protocol: string, version?: number) { video.writeString("hello"); const remote = client.consume(Path.from("test")); - const sub = remote.track("video").subscribe(); + const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe("hello"); // The publisher now has a live downstream reader for the track. @@ -787,7 +789,7 @@ test("integration: ietf draft-14 subscriber teardown on last unsubscribe", async await announced.next(); const remote = client.consume(Path.from("test")); - const sub = remote.track("video").subscribe(); + const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe("hello"); await waitUntil(() => served?.used.peek() === true); @@ -858,8 +860,8 @@ test("integration: lite fan-out keeps the upstream until the last subscriber lea video.writeString("hello"); const remote = client.consume(Path.from("test")); - const a = remote.track("video").subscribe(); - const b = remote.track("video").subscribe(); + const a = remote.track("video").subscribe().ordered(); + const b = remote.track("video").subscribe().ordered(); expect(await a.readString()).toBe("hello"); expect(await b.readString()).toBe("hello"); await waitUntil(() => video.used.peek()); @@ -897,7 +899,7 @@ test("integration: lite re-subscribe re-opens the upstream after each teardown", for (let i = 0; i < 8; i++) { video.writeString(`hello-${i}`); - const sub = remote.track("video").subscribe(); + const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe(`hello-${i}`); await waitUntil(() => video.used.peek()); @@ -1006,7 +1008,7 @@ async function runSubscribeWithoutWarmup(version: number) { })(); const remote = client.consume(Path.from("test")); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); const data = await Promise.race([ track.readString(), new Promise((_, reject) => @@ -1045,7 +1047,7 @@ test("integration: subscribe to non-existent broadcast", async () => { // Client tries to consume a broadcast that nobody is publishing const remote = client.consume(Path.from("nonexistent")); - const track = remote.subscribe("video"); + const track = remote.subscribe("video").ordered(); // Reading should eventually error since the broadcast doesn't exist await expect( @@ -1096,7 +1098,7 @@ test("integration: announcedBroadcast waits for a late publisher", async () => { const active = await waitFor(watched.active, (b) => b !== undefined); if (!active) throw new Error("expected an active broadcast"); - expect(await active.subscribe("video").readString()).toBe("hello"); + expect(await active.subscribe("video").ordered().readString()).toBe("hello"); // It goes away. first.close(); @@ -1110,7 +1112,7 @@ test("integration: announcedBroadcast waits for a late publisher", async () => { const republished = await waitFor(watched.active, (b) => b !== undefined); if (!republished) throw new Error("expected a republished broadcast"); expect(republished).not.toBe(active); - expect(await republished.subscribe("video").readString()).toBe("world"); + expect(await republished.subscribe("video").ordered().readString()).toBe("world"); // Closing the handle releases the broadcast it held. watched.close(); @@ -1144,7 +1146,7 @@ test("integration: announcedBroadcast consumes blind without discovery", async ( const watched = client.announcedBroadcast(Path.from("test")); const active = await waitFor(watched.active, (b) => b !== undefined); if (!active) throw new Error("expected an active broadcast"); - expect(await active.subscribe("video").readString()).toBe("blind"); + expect(await active.subscribe("video").ordered().readString()).toBe("blind"); watched.close(); broadcast.close(); @@ -1175,7 +1177,7 @@ test("integration: a republish is not served from the previous generation's cach const watched = client.announcedBroadcast(Path.from("shared")); const active = await waitFor(watched.active, (b) => b !== undefined); if (!active) throw new Error("expected an active broadcast"); - expect(await active.subscribe("video").readString()).toBe("old"); + expect(await active.subscribe("video").ordered().readString()).toBe("old"); // A second holder of the same path, which is what makes the cache reachable: consumed // broadcasts are reference-counted, so the handle closing its own copy below does not @@ -1193,7 +1195,7 @@ test("integration: a republish is not served from the previous generation's cach const republished = await waitFor(watched.active, (b) => b !== undefined); if (!republished) throw new Error("expected a republished broadcast"); - expect(await republished.subscribe("video").readString()).toBe("new"); + expect(await republished.subscribe("video").ordered().readString()).toBe("new"); bystander.close(); watched.close(); @@ -1218,7 +1220,7 @@ test("integration: a blind handle picks up a publisher that arrives late", async // Nobody publishes the path yet, so a subscribe is how the caller finds out. That kills the // track, not the handle: a consumed broadcast is scoped to the path, not to one publisher. - await expect(blind.subscribe("video").readString()).rejects.toThrow(); + await expect(blind.subscribe("video").ordered().readString()).rejects.toThrow(); expect(watched.active.peek()).toBe(blind); // So a subscribe made after the publisher finally shows up still works, on the same handle. @@ -1231,7 +1233,7 @@ test("integration: a blind handle picks up a publisher that arrives late", async } })(); - expect(await blind.subscribe("video").readString()).toBe("late"); + expect(await blind.subscribe("video").ordered().readString()).toBe("late"); watched.close(); producer.close(); @@ -1275,7 +1277,7 @@ test("integration: ietf blind handle picks up a publisher that arrives late", as if (!blind) throw new Error("expected a blind consumer"); // Rejects with 404 rather than resetting the whole handle. - await expect(blind.subscribe("video").readString()).rejects.toThrow(); + await expect(blind.subscribe("video").ordered().readString()).rejects.toThrow(); expect(watched.active.peek()).toBe(blind); const producer = origin.publish(Path.from("later")); @@ -1287,7 +1289,7 @@ test("integration: ietf blind handle picks up a publisher that arrives late", as } })(); - expect(await blind.subscribe("video").readString()).toBe("ietf-late"); + expect(await blind.subscribe("video").ordered().readString()).toBe("ietf-late"); watched.close(); producer.close(); @@ -1341,7 +1343,7 @@ async function runOriginFlow(protocol: string, version?: number) { // Consuming through the origin reaches the wire. const remote = routed(reader, Path.from("test")); if (!remote) throw new Error("expected the origin to route the broadcast"); - const track = remote.track("video").subscribe(); + const track = remote.track("video").subscribe().ordered(); expect(await track.readString()).toBe("hello"); // Unpublishing retracts the entry over the wire and out of the origin. @@ -1478,7 +1480,7 @@ test("origin: a request resolves blind on a relay without discovery", async () = await until(() => request.active.peek() !== undefined); const front = request.active.peek(); - const track = front?.track("chat").subscribe(); + const track = front?.track("chat").subscribe().ordered(); if (!track) throw new Error("expected a track"); expect(await track.readString()).toBe("found you"); @@ -1610,7 +1612,7 @@ test("origin: overlapping sessions carrying one path fail over", async () => { const remote = routed(reader, Path.from("redundant")); if (!remote) throw new Error("route black-holed despite a live session"); - const track = remote.track("chat").subscribe(); + const track = remote.track("chat").subscribe().ordered(); expect(await track.readString()).toBe("still here"); track.close(); @@ -1663,7 +1665,7 @@ test("origin: a standby session re-answers a request when the answerer dies", as await until(() => request.active.peek() !== undefined && request.active.peek() !== before); const front = request.active.peek(); - const track = front?.track("chat").subscribe(); + const track = front?.track("chat").subscribe().ordered(); if (!track) throw new Error("expected a track from the standby"); expect(await track.readString()).toBe("from standby"); diff --git a/js/net/src/lite/priority.ts b/js/net/src/lite/priority.ts index a5e83448924..542143756d3 100644 --- a/js/net/src/lite/priority.ts +++ b/js/net/src/lite/priority.ts @@ -60,9 +60,9 @@ function clamp(value: number, max: number): number { * set changes or the subscription is updated. * * A group's rank is its position among the groups in flight, so which group goes first is - * decided here rather than by arithmetic on sequence numbers. Newest-first by default, since - * that is what live playback wants; an `ordered` subscription is playing through in sequence, - * so it gets the oldest group first instead. + * decided here rather than by arithmetic on sequence numbers. Newest first, always: under + * congestion that sheds the backlog rather than the live edge, and a subscriber wanting + * sequence order reorders locally rather than asking the wire for it. * * One listener covers the whole subscription. A listener per group would instead pile up on * it, and a track that stalls with many groups open would trip the signals leak guard. @@ -125,11 +125,9 @@ export class Priority { // Sequences are unique within a subscription, so a group already registered never counts // itself. #position(sequence: number): number { - const ordered = this.#track.subscription.peek()?.ordered ?? false; - let ahead = 0; for (const other of this.#streams.values()) { - if (ordered ? other < sequence : other > sequence) ahead++; + if (other > sequence) ahead++; } return ahead; } diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 3affef50896..912550f6d86 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -89,8 +89,8 @@ async function servingNextGroup(opened: ReadableStreamDefaultReader new GroupProducer(sequence)); const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); @@ -108,7 +108,6 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; broadcast: Path.from("test"), track: "video", priority, - ordered, }); void publisher.runSubscribe(msg, server); @@ -118,7 +117,7 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; try { for (const [index, group] of groups.entries()) { if (index === 1 && update !== undefined) { - await replayUpdate({ priority: update, ordered }).encode(client.writer, Version.DRAFT_05); + await replayUpdate({ priority: update }).encode(client.writer, Version.DRAFT_05); // Wait for the publisher to apply it, rather than assuming it beat the next group. while (track.subscription.peek()?.priority !== update) await track.subscription.changed(); } @@ -156,19 +155,6 @@ test("lite draft-05: group streams are ranked newest-first", async () => { expect(orders[2]).toBeGreaterThan(orders[1]); }); -// An ordered subscriber is playing through in sequence, so the oldest group in flight is the -// one it needs next. -test("lite draft-05: an ordered subscription is ranked oldest-first", async () => { - const orders = await groupSendOrders({ priority: 7, sequences: [0, 1, 2], ordered: true }); - expect(orders).toEqual([ - sendOrder({ priority: 7, position: 0 }), - sendOrder({ priority: 7, position: 1 }), - sendOrder({ priority: 7, position: 2 }), - ]); - - expect(orders[2]).toBeLessThan(orders[1]); -}); - // Two tracks the subscriber values equally each get their next group out, whatever their group // numbering: ranking by sequence would let the one with larger numbers starve the other. test("lite draft-05: equal priorities tie regardless of group numbering", async () => { @@ -813,12 +799,11 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", sub.serve(0); await sub.parked; - await replayUpdate({ priority: 9, ordered: true, endGroup: 5 }).encode(sub.client.writer, Version.DRAFT_06); + await replayUpdate({ priority: 9, endGroup: 5 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); expect(sub.track.subscription.peek()).toEqual({ priority: 9, - ordered: true, maxAge: DEFAULT_MAX_AGE_MS, startGroup: undefined, endGroup: 5, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 7338202891b..358f6ab7b27 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -466,7 +466,6 @@ export class Publisher { const track = broadcast.subscribe(msg.track, { priority: msg.priority, - ordered: msg.ordered, maxAge: servingMaxAge(this.version, msg.maxAge), startGroup: msg.startGroup, endGroup: msg.endGroup, @@ -500,7 +499,6 @@ export class Publisher { // Older drafts acknowledge with SUBSCRIBE_OK and stream frames verbatim. const ok = new SubscribeOk({ priority: msg.priority, - ordered: msg.ordered, maxAge: msg.maxAge, startGroup: msg.startGroup, endGroup: msg.endGroup, @@ -523,7 +521,6 @@ export class Publisher { apply: (update) => { track.update({ priority: update.priority, - ordered: update.ordered, maxAge: servingMaxAge(this.version, update.maxAge), startGroup: update.startGroup, endGroup: update.endGroup, @@ -782,7 +779,6 @@ export class Publisher { const info = await published.track(track).info(); return new TrackInfoMessage({ priority: info.priority, - ordered: info.ordered, // Publisher Max Age: the publisher's retention bound, advertised so // relays re-serve with the same window. maxAge: info.maxAge, diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 6aa2ebf165a..05243eb5419 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -64,14 +64,13 @@ async function encodeMessage( return concat(written); } -test("SubscribeOk round-trips priority/ordered/groups on draft-04", async () => { +test("SubscribeOk round-trips priority/groups on draft-04", async () => { const got = await responseRoundtrip(Version.DRAFT_04, { - ok: new SubscribeOk({ priority: 7, ordered: true, maxAge: 250, startGroup: 3 }), + ok: new SubscribeOk({ priority: 7, maxAge: 250, startGroup: 3 }), }); expect("ok" in got).toBe(true); if (!("ok" in got)) throw new Error("expected ok"); expect(got.ok.priority).toBe(7); - expect(got.ok.ordered).toBe(true); expect(got.ok.startGroup).toBe(3); }); @@ -81,7 +80,6 @@ test("Subscribe round-trips every option including startGroup 0", async () => { broadcast: Path.from("test"), track: "video", priority: 7, - ordered: true, maxAge: 250, startGroup: 0, endGroup: 9, @@ -91,7 +89,6 @@ test("Subscribe round-trips every option including startGroup 0", async () => { Version.DRAFT_05, ); expect(got.priority).toBe(7); - expect(got.ordered).toBe(true); expect(got.maxAge).toBe(250); expect(got.startGroup).toBe(0); expect(got.endGroup).toBe(9); @@ -100,7 +97,6 @@ test("Subscribe round-trips every option including startGroup 0", async () => { test("SubscribeUpdate round-trips every option including startGroup 0", async () => { const message = new SubscribeUpdate({ priority: 8, - ordered: true, maxAge: 500, startGroup: 0, endGroup: 12, @@ -110,7 +106,6 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () Version.DRAFT_05, ); expect(got.priority).toBe(8); - expect(got.ordered).toBe(true); expect(got.maxAge).toBe(500); expect(got.startGroup).toBe(0); expect(got.endGroup).toBe(12); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 4a2be25a3fe..2d224917cf0 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -1,7 +1,7 @@ import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, Version } from "./version.ts"; +import { hasFrameBounds, hasGroupOrder, Version } from "./version.ts"; /** * Encode the trailing `Frame Start` / `Frame End` pair shared by SUBSCRIBE and @@ -59,9 +59,18 @@ async function decodeFrameBounds( return { startFrame, endFrame: endFrame > 0 ? endFrame - 1 : undefined }; } +/** Step over the retired `Ordered` byte on a version whose layout still has it. */ +async function skipGroupOrder(r: Reader, version: Version) { + if (hasGroupOrder(version)) await r.bool(); +} + +/** Write the retired `Ordered` byte as 0, keeping a deployed version's field offsets. */ +async function padGroupOrder(w: Writer, version: Version) { + if (hasGroupOrder(version)) await w.bool(false); +} + export class SubscribeUpdate { priority: number; - ordered: boolean; /** Subscriber max latency in milliseconds; zero skips once a newer group is available. */ maxAge: number; startGroup?: number; @@ -73,7 +82,6 @@ export class SubscribeUpdate { constructor(props: { priority: number; - ordered?: boolean; maxAge?: number; startGroup?: number; endGroup?: number; @@ -81,7 +89,6 @@ export class SubscribeUpdate { endFrame?: number; }) { this.priority = props.priority; - this.ordered = props.ordered ?? false; this.maxAge = props.maxAge ?? 0; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -97,7 +104,7 @@ export class SubscribeUpdate { break; default: await w.u8(this.priority); - await w.bool(this.ordered); + await padGroupOrder(w, version); await w.u53(this.maxAge); await w.u53(this.startGroup !== undefined ? this.startGroup + 1 : 0); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); @@ -113,7 +120,7 @@ export class SubscribeUpdate { return new SubscribeUpdate({ priority: await r.u8() }); default: { const priority = await r.u8(); - const ordered = await r.bool(); + await skipGroupOrder(r, version); const maxAge = await r.u53(); const startGroup = (await r.u53()) || undefined; const endGroup = (await r.u53()) || undefined; @@ -125,7 +132,6 @@ export class SubscribeUpdate { ); return new SubscribeUpdate({ priority, - ordered, maxAge, startGroup: startGroup !== undefined ? startGroup - 1 : undefined, endGroup: endGroup !== undefined ? endGroup - 1 : undefined, @@ -153,7 +159,6 @@ export class Subscribe { broadcast: Path.Valid; track: string; priority: number; - ordered: boolean; /** Subscriber max latency in milliseconds; zero skips once a newer group is available. */ maxAge: number; @@ -177,7 +182,6 @@ export class Subscribe { broadcast: Path.Valid; track: string; priority: number; - ordered?: boolean; maxAge?: number; startGroup?: number; endGroup?: number; @@ -188,7 +192,6 @@ export class Subscribe { this.broadcast = props.broadcast; this.track = props.track; this.priority = props.priority; - this.ordered = props.ordered ?? false; this.maxAge = props.maxAge ?? 0; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -207,7 +210,7 @@ export class Subscribe { case Version.DRAFT_02: break; default: - await w.bool(this.ordered); + await padGroupOrder(w, version); await w.u53(this.maxAge); await w.u53(this.startGroup !== undefined ? this.startGroup + 1 : 0); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); @@ -227,7 +230,7 @@ export class Subscribe { case Version.DRAFT_02: return new Subscribe({ id, broadcast, track, priority }); default: { - const ordered = await r.bool(); + await skipGroupOrder(r, version); const maxAge = await r.u53(); const startGroup = (await r.u53()) || undefined; const endGroup = (await r.u53()) || undefined; @@ -239,7 +242,6 @@ export class Subscribe { broadcast, track, priority, - ordered, maxAge, startGroup: start, endGroup: end, @@ -266,7 +268,6 @@ export class Subscribe { */ export class SubscribeOk { priority: number; - ordered: boolean; /** Accepted subscriber max latency in milliseconds. */ maxAge: number; startGroup?: number; @@ -274,19 +275,16 @@ export class SubscribeOk { constructor({ priority = 0, - ordered = false, maxAge = 0, startGroup = undefined, endGroup = undefined, }: { priority?: number; - ordered?: boolean; maxAge?: number; startGroup?: number; endGroup?: number; }) { this.priority = priority; - this.ordered = ordered; this.maxAge = maxAge; this.startGroup = startGroup; this.endGroup = endGroup; @@ -304,7 +302,7 @@ export class SubscribeOk { // Draft-03/04 so a stray future use stays well-formed. default: await w.u8(this.priority); - await w.bool(this.ordered); + await padGroupOrder(w, version); await w.u53(this.maxAge); await w.u53(this.startGroup !== undefined ? this.startGroup + 1 : 0); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); @@ -314,7 +312,6 @@ export class SubscribeOk { static async #decode(version: Version, r: Reader): Promise { let priority: number | undefined; - let ordered: boolean | undefined; let maxAge: number | undefined; let startGroup: number | undefined; let endGroup: number | undefined; @@ -328,7 +325,7 @@ export class SubscribeOk { break; default: priority = await r.u8(); - ordered = await r.bool(); + await skipGroupOrder(r, version); maxAge = await r.u53(); startGroup = await r.u53(); endGroup = await r.u53(); @@ -337,7 +334,6 @@ export class SubscribeOk { return new SubscribeOk({ priority, - ordered, maxAge, startGroup: startGroup !== undefined && startGroup > 0 ? startGroup - 1 : undefined, endGroup: endGroup !== undefined && endGroup > 0 ? endGroup - 1 : undefined, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index b92734a64b2..239708222bc 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -460,7 +460,6 @@ export class Subscriber { broadcast, track: request.name, priority: subscription.priority ?? 0, - ordered: subscription.ordered, maxAge: subscription.maxAge, startGroup: subscription.startGroup, endGroup: subscription.endGroup, @@ -611,7 +610,6 @@ export class Subscriber { // matches what the upstream advertises (relays re-serve with the same bound). maxAge: info.maxAge, priority: info.priority, - ordered: info.ordered, }; } @@ -768,7 +766,6 @@ export class Subscriber { const stopped: Promise = Promise.race([track.closed, stream.reader.closed]).then(() => null); let lastSent: track.Subscription = { priority: msg.priority, - ordered: msg.ordered, maxAge: msg.maxAge, startGroup: msg.startGroup, endGroup: msg.endGroup, @@ -787,7 +784,6 @@ export class Subscriber { // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxAge/etc. const update = new SubscribeUpdate({ priority: current.priority ?? 0, - ordered: current.ordered, maxAge: current.maxAge, startGroup: current.startGroup, endGroup: current.endGroup, @@ -801,7 +797,6 @@ export class Subscriber { #sameSubscription(a: track.Subscription, b: track.Subscription): boolean { return ( (a.priority ?? 0) === (b.priority ?? 0) && - (a.ordered ?? false) === (b.ordered ?? false) && (a.maxAge ?? 0) === (b.maxAge ?? 0) && a.startGroup === b.startGroup && a.endGroup === b.endGroup diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index f794cf42180..a3fbad42394 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -30,14 +30,12 @@ async function bytes(f: (w: Writer) => Promise): Promise { test("TrackInfo round-trips on draft-05", async () => { const info = new TrackInfo({ priority: 7, - ordered: false, maxAge: 2000, timescale: 90000, }); const reader = new Reader(undefined, await bytes((w) => info.encode(w, Version.DRAFT_05))); const got = await TrackInfo.decode(reader, Version.DRAFT_05); expect(got.priority).toBe(7); - expect(got.ordered).toBe(false); expect(got.maxAge).toBe(2000); expect(got.timescale).toBe(90000); }); diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index 9a6d0e589b6..1d6b61078ba 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -1,7 +1,7 @@ import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import * as Message from "./message.ts"; -import { Version } from "./version.ts"; +import { hasGroupOrder, Version } from "./version.ts"; // The Track Stream (0x6) is draft-05+ only. function guardTrack(version: Version) { @@ -59,11 +59,6 @@ export class Track { export class TrackInfo { /** The publisher's tie-break priority for this track. */ priority: number; - /** - * Whether groups are prioritized in sequence order. Groups may always arrive - * out-of-order (or not at all) over the network. - */ - ordered: boolean; /** * Publisher Max Age: an upper bound (milliseconds) on how long the publisher * caches a non-latest group past the arrival of a newer one. @@ -78,37 +73,35 @@ export class TrackInfo { constructor({ priority = 0, - ordered = false, maxAge = 0, timescale = 0, }: { priority?: number; - ordered?: boolean; maxAge?: number; timescale?: number; }) { this.priority = priority; - this.ordered = ordered; this.maxAge = maxAge; this.timescale = timescale; } - async #encode(w: Writer) { + async #encode(w: Writer, version: Version) { await w.u8(this.priority); - await w.bool(this.ordered); + // The retired `Ordered` byte: lite-05 keeps it in its layout, written as 0. + if (hasGroupOrder(version)) await w.bool(false); await w.u53(this.maxAge); await w.u53(this.timescale); } - static async #decode(r: Reader): Promise { + static async #decode(r: Reader, version: Version): Promise { const priority = await r.u8(); - const ordered = await r.bool(); + if (hasGroupOrder(version)) await r.bool(); const maxAge = await r.u53(); const timescale = await r.u53(); // Mandatory on Lite05: a zero scale is invalid (mirrors Rust's Timescale::new rejection), // and would otherwise throw later when wrapped in Timescale(). if (timescale === 0) throw new Error("track timescale must be non-zero"); - return new TrackInfo({ priority, ordered, maxAge, timescale }); + return new TrackInfo({ priority, maxAge, timescale }); } async encode(w: Writer, version: Version): Promise { @@ -116,11 +109,11 @@ export class TrackInfo { // Reject a zero timescale on encode too, so an invalid TrackInfo fails fast on // the sender rather than only at the peer's decoder. if (this.timescale === 0) throw new Error("track timescale must be non-zero"); - return Message.encode(w, (w) => this.#encode(w)); + return Message.encode(w, (w) => this.#encode(w, version)); } static async decode(r: Reader, version: Version): Promise { guardTrack(version); - return Message.decode(r, (r) => TrackInfo.#decode(r)); + return Message.decode(r, (r) => TrackInfo.#decode(r, version)); } } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 037fac7dc41..cd93648cd79 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -168,6 +168,26 @@ export function hasFrameBounds(version: Version): boolean { } } +/** Whether SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, and TRACK_INFO carry the retired + * `Ordered` byte. + * + * The field is gone from the model: a publisher transmits newest-first within a track, + * always. Deployed drafts still have the byte in their layout, so it is written as 0 and + * ignored on read rather than shifting every field behind it. */ +export function hasGroupOrder(version: Version): boolean { + // Explicitly list older versions so future versions keep the lite-06+ behavior. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + return true; + default: + return false; + } +} + /// The WebTransport subprotocol identifier for moq-lite. /// Version negotiation still happens via SETUP when this is used. export const ALPN = "moql"; diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index c0c97c4a8a9..8d9d1c51d3e 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -33,7 +33,7 @@ test("used reflects subscriber demand and unused resolves when the last one leav expect(producer.used.peek()).toBe(false); const a = producer.subscribe(); - const b = producer.subscribe(); + const b = producer.subscribe().ordered(); expect(producer.used.peek()).toBe(true); // Closing one of two keeps demand, so unused() stays pending. @@ -61,7 +61,7 @@ test("a producer never self-closes on zero demand: a publisher keeps serving new // A later subscriber still works and replays the cache. producer.writeString("still here"); - const b = producer.subscribe(); + const b = producer.subscribe().ordered(); expect(await b.readString()).toBe("still here"); expect(producer.used.peek()).toBe(true); }); @@ -124,16 +124,19 @@ test("writeDatagram preserves an explicit sequence", async () => { expect(producer.appendGroup().sequence).toBe(101); }); -test("recvDatagram advances the ordered group cursor", async () => { +// Datagrams and groups are separate channels that share only a sequence namespace, so +// consuming one must not move the other's cursor. +test("recvDatagram leaves the ordered group cursor alone", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const datagrams = producer.subscribe(); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); producer.writeDatagram({ sequence: 5, timestamp: Timestamp.fromMillis(5), payload: enc.encode("x") }); - expect((await track.recvDatagram())?.sequence).toBe(5); + expect((await datagrams.recvDatagram())?.sequence).toBe(5); - // Ordered group reads treat lower sequences as late once a datagram used sequence 5. producer.writeGroup(new GroupProducer(3)); producer.writeGroup(new GroupProducer(6)); + expect((await track.nextGroup())?.sequence).toBe(3); expect((await track.nextGroup())?.sequence).toBe(6); }); @@ -149,7 +152,6 @@ test("subscriber options and updates are forwarded to the producer's aggregate", // The initial options are available before the request is accepted or put on the wire. expect(producer.subscription.peek()).toEqual({ priority: 0, - ordered: false, maxAge: 0, startGroup: 0, endGroup: undefined, @@ -157,18 +159,17 @@ test("subscriber options and updates are forwarded to the producer's aggregate", // The wire layer watches the producer's signal to emit SUBSCRIBE_UPDATE. const next = producer.subscription.changed(); - track.update({ priority: 7, ordered: true, maxAge: 250, startGroup: 2, endGroup: 9 }); - expect(await next).toEqual({ priority: 7, ordered: true, maxAge: 250, startGroup: 2, endGroup: 9 }); + track.update({ priority: 7, maxAge: 250, startGroup: 2, endGroup: 9 }); + expect(await next).toEqual({ priority: 7, maxAge: 250, startGroup: 2, endGroup: 9 }); }); test("multiple subscriber options aggregate like Rust", async () => { const producer = new TrackProducer("test"); - const bounded = producer.subscribe({ priority: 2, ordered: true, maxAge: 100, startGroup: 10, endGroup: 20 }); - const live = producer.subscribe({ priority: 7, ordered: false, maxAge: 250, startGroup: 5 }); + const bounded = producer.subscribe({ priority: 2, maxAge: 100, startGroup: 10, endGroup: 20 }); + const live = producer.subscribe({ priority: 7, maxAge: 250, startGroup: 5 }); expect(producer.subscription.peek()).toEqual({ priority: 7, - ordered: false, maxAge: 250, startGroup: 5, endGroup: undefined, @@ -178,7 +179,6 @@ test("multiple subscriber options aggregate like Rust", async () => { live.close(); expect(await narrowed).toEqual({ priority: 2, - ordered: true, maxAge: 100, startGroup: 10, endGroup: 20, @@ -202,7 +202,7 @@ test("the producer aggregate is clamped without changing subscriber options", as test("nextGroup skips late arrivals", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe().ordered(); producer.writeGroup(new GroupProducer(5)); @@ -220,7 +220,7 @@ test("nextGroup skips late arrivals", async () => { test("nextGroup returns buffered groups in sequence", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); producer.writeGroup(new GroupProducer(3)); producer.writeGroup(new GroupProducer(5)); @@ -229,19 +229,23 @@ test("nextGroup returns buffered groups in sequence", async () => { expect((await track.nextGroup())?.sequence).toBe(5); }); -test("latency budget skips a buffered timeline in every group read", async () => { +// The arrival cursor writes a backlog off; the ordered cursor does not. A group already +// buffered costs nothing to deliver, and dropping it would put a hole in the sequence a +// decoder is reading. The budget bounds how long a *blocking* group may stall instead. +test("the latency budget skips a buffered timeline only on the arrival cursor", async () => { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); const arrival = producer.subscribe(); - const ordered = producer.subscribe(); - const frames = producer.subscribe(); + const ordered = producer.subscribe().ordered(); for (const timestamp of [0, 1000, 2000]) { producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } expect((await arrival.recvGroup())?.sequence).toBe(2); + + expect((await ordered.nextGroup())?.sequence).toBe(0); + expect((await ordered.nextGroup())?.sequence).toBe(1); expect((await ordered.nextGroup())?.sequence).toBe(2); - expect((await frames.readFrameSequence())?.group).toBe(2); }); test("zero latency takes the latest group when ages are equal", async () => { @@ -657,7 +661,7 @@ test("endAt caps the live edge used by the latency budget", async () => { test("endAt does not cap frame-level reads", async () => { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); - const track = producer.subscribe({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); track.endAt(0); producer.writeFrame({ payload: enc.encode("zero"), timestamp: Timestamp.fromMillis(0) }); @@ -671,7 +675,7 @@ test("endAt does not cap frame-level reads", async () => { test("local cursor bounds can skip, pause, and release buffered groups", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); for (let sequence = 0; sequence < 5; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -842,25 +846,24 @@ test("closing the subscriber releases a recvGroup parked while the producer is l expect(await pending).toBeUndefined(); }); -test("recvGroup after nextGroup still returns late arrivals", async () => { +test("the ordered and arrival cursors are independent", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxAge: 5000 }); + const ordered = producer.subscribe({ maxAge: 5000 }).ordered(); + const arrival = producer.subscribe({ maxAge: 5000 }); producer.writeGroup(new GroupProducer(5)); + expect((await ordered.nextGroup())?.sequence).toBe(5); - // Ordered returns seq 5, advancing its cursor. - const ordered = await track.nextGroup(); - expect(ordered?.sequence).toBe(5); - - // recvGroup is independent of the ordered cursor: a late seq 3 still surfaces. + // A late seq 3 is skipped by the ordered cursor, which has already passed it, but the + // arrival cursor has both buffered and still delivers each exactly once. producer.writeGroup(new GroupProducer(3)); - const recv = await track.recvGroup(); - expect(recv?.sequence).toBe(3); + expect((await arrival.recvGroup())?.sequence).toBe(3); + expect((await arrival.recvGroup())?.sequence).toBe(5); }); test("nextGroup returns undefined when track closes", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe().ordered(); producer.close(); expect(await track.nextGroup()).toBeUndefined(); }); @@ -870,7 +873,7 @@ test("nextGroup returns undefined when track closes", async () => { // the data (mirrors the Rust subscriber). Only a drained closed track reports finished. test("a closed track still delivers a group parked above the cap once the cap is raised", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); for (let sequence = 0; sequence < 3; sequence++) { const group = new GroupProducer(sequence); @@ -928,7 +931,7 @@ test("final is 0 for an empty track and undefined after an abort", async () => { test("readFrame does not livelock when a sole group finishes before the next arrives", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe().ordered(); // A group is appended then finished empty while the track stays open. A finished group's // readable() resolves immediately, so the reader must not busy-wait on it (which would starve the diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 9d5f8a20130..3bef41a8a7e 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -62,11 +62,6 @@ export interface Info { maxAge: number; /** Tie-break priority between subscriptions of equal subscriber priority. */ priority: number; - /** - * Whether groups are prioritized in sequence order. Groups may always arrive - * out-of-order (or not at all) over the network. Defaults to `false` (newest-first). - */ - ordered: boolean; } /** Fill in any unset {@link Info} fields with their defaults. */ @@ -75,7 +70,6 @@ export function infoDefaults(info: Partial = {}): Info { timescale: info.timescale ?? Timescale.MILLI, maxAge: info.maxAge ?? DEFAULT_MAX_AGE_MS, priority: info.priority ?? 0, - ordered: info.ordered ?? false, }; } @@ -86,8 +80,6 @@ export function infoDefaults(info: Partial = {}): Info { export interface Subscription { /** Delivery priority relative to this session's other subscriptions. Defaults to `0`. */ priority?: number; - /** Whether groups are prioritized in sequence order. Defaults to `false` (newest-first). */ - ordered?: boolean; /** Maximum age (milliseconds) of a non-latest group before it is skipped. Defaults to `0`. */ maxAge?: number; /** First group the publisher should deliver, or omit to start at the latest group. */ @@ -101,7 +93,6 @@ export interface Subscription { function subscriptionDefaults(subscription: Subscription = {}): Subscription { return { priority: subscription.priority ?? 0, - ordered: subscription.ordered ?? false, maxAge: subscription.maxAge ?? 0, startGroup: subscription.startGroup, endGroup: subscription.endGroup, @@ -120,7 +111,6 @@ function combineSubscriptions(states: Iterable): Subscription | unde } combined.priority = Math.max(combined.priority ?? 0, subscription.priority ?? 0); - combined.ordered = (combined.ordered ?? false) && (subscription.ordered ?? false); combined.maxAge = Math.max(combined.maxAge ?? 0, subscription.maxAge ?? 0); if (subscription.startGroup !== undefined) { @@ -311,6 +301,19 @@ function bindProducer(name: string, producer: Producer, sequences: TrackSequence let bindProducerSequence: (producer: Producer, sequence: TrackSequence) => void; +// The sequence-order cursor lives inside `Subscriber` (it shares the group buffer and the +// drift anchor with the arrival cursor), so `Ordered` reaches it through this bridge, +// assigned in the class's static block. +let makeOrdered: (subscriber: Subscriber) => Ordered; +let ordered_: { + nextGroup(subscriber: Subscriber): Promise; + readFrame(subscriber: Subscriber): Promise; + readFrameSequence(subscriber: Subscriber): Promise<({ group: number; frame: number } & Frame) | undefined>; + readString(subscriber: Subscriber): Promise; + readJson(subscriber: Subscriber): Promise; + readBool(subscriber: Subscriber): Promise; +}; + // Constructs a Subscriber from within this module without exposing a public // constructor that would leak the unexported TrackState. Assigned in the class's // static block. @@ -691,6 +694,9 @@ export class Subscriber { #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); #enforceLatency = true; + // Set by {@link ordered}: both cursors draw from one buffer, so the handle that + // wins is the only one allowed to read from here on. + #committed = false; #drift(): { budget: number; @@ -784,6 +790,21 @@ export class Subscriber { hooks.ignoreLatency = (subscriber) => { subscriber.#enforceLatency = false; }; + // The sequence cursor lives here (it shares the buffer and the drift anchor with + // the arrival cursor); `Ordered` is the handle that reaches it. + ordered_ = { + nextGroup: (subscriber) => subscriber.#nextGroup(), + readFrame: (subscriber) => subscriber.#readFrame(), + readFrameSequence: (subscriber) => subscriber.#readFrameSequence(), + readString: (subscriber) => subscriber.#readString(), + readJson: (subscriber) => subscriber.#readJson(), + readBool: (subscriber) => subscriber.#readBool(), + }; + } + + // Refuse an arrival-order read once `ordered()` has taken the subscription. + #live() { + if (this.#committed) throw new Error("track is read in sequence order; use the Ordered handle"); } /** @@ -828,9 +849,9 @@ export class Subscriber { } /** - * Cap {@link nextGroup} and {@link recvGroup} at `sequence` inclusively, or omit it to - * remove the cap. Groups above the cap remain buffered and become readable if the cap - * is raised. This local cursor does not change the subscription's wire request. + * Cap {@link recvGroup} at `sequence` inclusively, or omit it to remove the cap. Groups + * above the cap remain buffered and become readable if the cap is raised. This local + * cursor does not change the subscription's wire request. */ endAt(sequence?: number): void { this.#cursor.update((cursor) => ({ ...cursor, end: sequence })); @@ -854,8 +875,8 @@ export class Subscriber { * Receive every group on this track exactly once, as it becomes available. * * Groups may arrive out of order or with gaps due to network conditions; unlike - * {@link nextGroup}, one that arrives after a newer group was already returned is - * still delivered. When several groups are buffered, the lowest sequence is + * {@link Ordered.nextGroup}, one that arrives after a newer group was already returned + * is still delivered. When several groups are buffered, the lowest sequence is * returned first. * * Honors the floor set by {@link startAt} and the cap set by {@link endAt}: a group @@ -867,6 +888,7 @@ export class Subscriber { * group becomes stale while newer data advances. */ async recvGroup(): Promise { + this.#live(); for (;;) { const recv = this.#tryRecvGroup(); switch (recv.kind) { @@ -928,10 +950,11 @@ export class Subscriber { * Datagrams are a separate best-effort channel from groups (see * {@link Producer.appendDatagram}); they share only the sequence namespace. A consumer * that falls too far behind silently loses the oldest datagrams. Read this alongside - * {@link recvGroup} (e.g. in a separate loop) to receive both channels concurrently. Returning - * a datagram advances {@link nextGroup} past that sequence. + * {@link recvGroup} (e.g. in a separate loop) to receive both channels concurrently. + * The two cursors are independent: a datagram never moves the group cursor. */ async recvDatagram(): Promise { + this.#live(); for (;;) { const datagrams = this.#state.datagrams.peek(); @@ -941,11 +964,7 @@ export class Subscriber { while (datagrams.length > 0 && datagrams[0].time < cutoff) datagrams.shift(); if (datagrams.length > 0) { - const datagram = datagrams.shift()?.datagram; - if (datagram) { - this.#nextSequence = Math.max(this.#nextSequence, datagram.sequence + 1); - } - return datagram; + return datagrams.shift()?.datagram; } const closed = this.#state.closed.peek(); @@ -956,30 +975,17 @@ export class Subscriber { } } - /** - * Return the next group with a strictly-greater sequence number than the last returned. - * - * Late arrivals (sequence at or below the last returned) are silently skipped. - * Use {@link recvGroup} to see every group in arrival order instead. - * The subscription's `maxAge` also skips groups that drift behind the live edge. - */ - async nextGroup(): Promise { + // The sequence cursor behind {@link Ordered}, which owns the only public door to it. + async #nextGroup(): Promise { for (;;) { const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); - const drift = this.#drift(); - - let group = groups[0]; - while (group && (cursor.end === undefined || group.sequence <= cursor.end)) { + const group = groups[0]; + if (group && (cursor.end === undefined || group.sequence <= cursor.end)) { groups.shift(); this.#nextSequence = group.sequence + 1; - if (this.#isStale(group, drift)) { - group.close(); - group = groups[0]; - continue; - } return this.#guard(group); } @@ -998,8 +1004,8 @@ export class Subscriber { * Reads the next frame across all groups, discarding older groups. * Treat the returned frame bytes as read-only; they are shared with other consumers. */ - async readFrame(): Promise { - const next = await this.readFrameSequence(); + async #readFrame(): Promise { + const next = await this.#readFrameSequence(); return next ? { payload: next.payload, timestamp: next.timestamp } : undefined; } @@ -1008,7 +1014,7 @@ export class Subscriber { * Treat the returned frame bytes as read-only; they are shared with other consumers. * Groups outside the subscription's `maxAge` budget are discarded before reading. */ - async readFrameSequence(): Promise<({ group: number; frame: number } & Frame) | undefined> { + async #readFrameSequence(): Promise<({ group: number; frame: number } & Frame) | undefined> { for (;;) { const groups = this.#state.groups.peek(); const { start } = this.#cursor.peek(); @@ -1094,28 +1100,44 @@ export class Subscriber { } /** Reads the next frame and decodes it as a UTF-8 string. */ - async readString(): Promise { - const next = await this.readFrame(); + async #readString(): Promise { + const next = await this.#readFrame(); if (!next) return undefined; return new TextDecoder().decode(next.payload); } /** Reads the next frame and parses it as JSON. */ - async readJson(): Promise { - const next = await this.readString(); + async #readJson(): Promise { + const next = await this.#readString(); if (!next) return undefined; return JSON.parse(next); } /** Reads the next frame and decodes it as a one-byte boolean, throwing on a malformed frame. */ - async readBool(): Promise { - const next = await this.readFrame(); + async #readBool(): Promise { + const next = await this.#readFrame(); if (!next) return undefined; const payload = next.payload; if (payload.byteLength !== 1 || !(payload[0] === 0 || payload[0] === 1)) throw new Error("invalid bool frame"); return payload[0] === 1; } + /** + * Read this track's groups in sequence order instead of arrival order. + * + * Both cursors draw from the same buffer, so a track is read one way or the other: this + * hands the subscription to the returned {@link Ordered} and leaves this handle inert. + * {@link recvGroup} and {@link recvDatagram} throw afterwards. + * + * Datagrams stay on this handle by construction: they are unordered, so a sequence + * cursor has nothing to do with them. + */ + ordered(): Ordered { + if (this.#committed) throw new Error("track is already read in sequence order"); + this.#committed = true; + return makeOrdered(this); + } + /** * Update this subscription's options (e.g. priority), triggering a SUBSCRIBE_UPDATE to the * publisher. Mirrors the Rust `Subscriber::update`. @@ -1124,3 +1146,118 @@ export class Subscriber { this.#state.update.set(subscriptionDefaults(options)); } } + +/** + * A {@link Subscriber} that reads groups in sequence order. + * + * Created by {@link Subscriber.ordered}, which takes the subscription over: the two + * cursors draw from one buffer, so a track is read one way or the other and never both. + * Every group this returns has a higher sequence than the last, so a late arrival is + * skipped rather than delivered out of turn. + * + * This cursor never drops a group it can already serve: a backlog is delivered as a + * burst, in order, however old it is. `maxAge` instead bounds how long a group already + * handed out may block, so a stalled group's pending frame read rejects once newer + * content has pulled that far ahead. + */ +export class Ordered { + /** The track name. */ + readonly name: string; + + #subscriber: Subscriber; + + private constructor(subscriber: Subscriber) { + this.name = subscriber.name; + this.#subscriber = subscriber; + } + + static { + makeOrdered = (subscriber) => new Ordered(subscriber); + } + + /** Resolve this track's immutable publisher properties; see {@link Subscriber.info}. */ + info(): Promise { + return this.#subscriber.info(); + } + + /** Settles once the track closes; see {@link Producer.closed}. */ + get closed(): GetPromise { + return this.#subscriber.closed; + } + + /** This subscriber's current options, including defaults and the last {@link update}. */ + get subscription(): Getter { + return this.#subscriber.subscription; + } + + /** The latest group sequence observed on this track, if any. */ + latest(): number | undefined { + return this.#subscriber.latest(); + } + + /** The track's exclusive final boundary; see {@link Subscriber.final}. */ + final(): number | undefined { + return this.#subscriber.final(); + } + + /** Start this cursor at `sequence`, without changing the subscription's wire request. */ + startAt(sequence: number): void { + this.#subscriber.startAt(sequence); + } + + /** + * Cap this cursor at `sequence` inclusively, or omit it to remove the cap. Groups above + * the cap remain buffered and become readable if the cap is raised. + */ + endAt(sequence?: number): void { + this.#subscriber.endAt(sequence); + } + + /** Update this subscription's options; see {@link Subscriber.update}. */ + update(options: Subscription) { + this.#subscriber.update(options); + } + + /** Close the track (optionally with an error), closing any pending groups. Idempotent. */ + close(abort?: Error) { + this.#subscriber.close(abort); + } + + /** + * Return the next group with a strictly-greater sequence number than the last returned. + * + * Late arrivals (sequence at or below the last returned) are silently skipped. Honors + * the bounds set by {@link startAt} and {@link endAt}. + */ + nextGroup(): Promise { + return ordered_.nextGroup(this.#subscriber); + } + + /** + * Read the next frame across groups, discarding older groups. + * Treat the returned frame bytes as read-only; they are shared with other consumers. + */ + readFrame(): Promise { + return ordered_.readFrame(this.#subscriber); + } + + /** The same, plus the group and frame sequence numbers the frame came from. */ + readFrameSequence(): Promise<({ group: number; frame: number } & Frame) | undefined> { + return ordered_.readFrameSequence(this.#subscriber); + } + + /** Read the next frame and decode it as a UTF-8 string. */ + readString(): Promise { + return ordered_.readString(this.#subscriber); + } + + /** Read the next frame and parse it as JSON. */ + readJson(): Promise { + return ordered_.readJson(this.#subscriber); + } + + /** Read the next frame and decode it as a one-byte boolean, throwing on a malformed frame. */ + readBool(): Promise { + return ordered_.readBool(this.#subscriber); + } +} diff --git a/js/net/src/zod.ts b/js/net/src/zod.ts index 9482bb075a9..4961ad448cf 100644 --- a/js/net/src/zod.ts +++ b/js/net/src/zod.ts @@ -10,7 +10,7 @@ import type * as track from "./track.ts"; /** Read the next JSON frame and validate it against the schema. Returns undefined at end of stream. */ export async function read( - source: track.Subscriber | group.Consumer, + source: track.Ordered | group.Consumer, schema: z.ZodMiniType, ): Promise { const next = await source.readJson(); diff --git a/js/publish/src/catalog.test.ts b/js/publish/src/catalog.test.ts index f423a3f8855..de5a27b92a6 100644 --- a/js/publish/src/catalog.test.ts +++ b/js/publish/src/catalog.test.ts @@ -41,7 +41,7 @@ test("catalog producer publishes every update as a snapshot group", async () => const effect = new Effect(); const track = new Track.Producer("catalog.json"); catalog.serve(track, effect); - const subscriber = track.subscribe(); + const subscriber = track.subscribe().ordered(); const first = await subscriber.nextGroup(); expect(first?.sequence).toBe(0); diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 01cc2a752e8..9f80c49d69c 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -306,8 +306,9 @@ export class Broadcast { }); fetchNext = () => consumer.next(); } else { + const ordered = track.ordered(); fetchNext = async () => { - const update = await Msf.fetch(track); + const update = await Msf.fetch(ordered); return update ? toHang(update) : undefined; }; } diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 142bf8036a7..c0da5b764d8 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -174,7 +174,7 @@ client = moq.Client( - `.read_frame() -> Frame | None` returns a timestamped raw frame. - `await .recv_datagram() -> Datagram | None` for best-effort raw track datagrams. - `.info() → TrackInfo` - - `.update(subscription)`. Change delivery priority, group ordering priority, staleness, or group range after subscribing. + - `.update(subscription)`. Change delivery priority, staleness, or group range after subscribing. - **`GroupConsumer`**. Async iterator of timestamped `Frame`s. - `.read_frame() -> Frame | None` returns a timestamped raw frame. @@ -202,12 +202,11 @@ All consumers (`CatalogConsumer`, `MediaConsumer`, `TrackConsumer`, `AudioConsum - **`Datagram`**. `.sequence: int`, `.timestamp_us: int`, `.payload: bytes`. Delivered only on datagram-capable transports and lite-05 or newer moq-lite. - **`Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.description`. - **`Video`**. `.codec`, `.coded: Dimensions`, `.display_aspect`, `.bitrate`, `.stalled`, `.framerate`, `.description`. A true `.stalled` recommends temporarily avoiding the rendition without making it unavailable. -- **`Subscription`**. Subscriber delivery preferences: priority, ordering priority, staleness, and optional group range. -- **`TrackInfo`**. Publisher track properties: priority, ordering priority, cache window, and timescale. +- **`Subscription`**. Subscriber delivery preferences: priority, staleness, and optional group range. +- **`TrackInfo`**. Publisher track properties: priority, cache window, and timescale. - **`Dimensions`**. `.width: int`, `.height: int`. - **`Container`**. The catalog container enum, carried on each `Video`/`Audio` record. -For both `Subscription` and `TrackInfo`, `ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network. ### Logging and errors diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index a212a485759..5d34c0576b6 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -262,7 +262,7 @@ def append_datagram(self, payload: bytes, timestamp_us: int = 0) -> int: def consume(self, subscription: Subscription | None = None) -> TrackConsumer: """Create a consumer that reads directly from this producer's track. - ``subscription`` tunes delivery priority, group ordering priority, and group range; omit for defaults. + ``subscription`` tunes delivery priority, group range, and staleness; omit for defaults. """ from .subscribe import TrackConsumer @@ -299,7 +299,7 @@ def name(self) -> str: def accept(self, info: TrackInfo | None = None) -> TrackProducer: """Accept the request as a raw track. - ``info`` fixes the track's timescale, priority, ordering priority, and cache; omit for defaults. + ``info`` fixes the track's timescale, priority, and cache; omit for defaults. """ return TrackProducer(self._inner.accept(info)) diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index f9c1df82b91..7f4e579bd16 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -411,7 +411,7 @@ async def subscribe_catalog(self) -> CatalogConsumer: async def subscribe_track(self, name: str, subscription: Subscription | None = None) -> TrackConsumer: """Subscribe to a track and receive arbitrary byte payloads. - ``subscription`` tunes delivery priority, group ordering priority, and group range; omit for defaults. + ``subscription`` tunes delivery priority, group range, and staleness; omit for defaults. """ return TrackConsumer(await self._inner.subscribe_track(name, subscription)) @@ -474,7 +474,7 @@ async def subscribe_media( ``catalog.video[name]``), whose ``container`` describes how to parse the bitstream, or a :class:`Container` directly. Pass a bare container for the dynamic flow, where you subscribe before the catalog exists. - ``subscription`` tunes delivery priority, group ordering priority, group + ``subscription`` tunes delivery priority, group range, and the max age; omit for defaults. Raise :attr:`Subscription.max_age_ms` to buffer instead of skipping a stalled group. diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 129962b81a7..a02ca958022 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -426,10 +426,6 @@ pub struct moq_track_info { /// Priority, used to break ties between subscriptions of equal subscriber priority. pub priority: u8, - /// Whether groups are prioritized in sequence order. - /// Groups may always arrive out-of-order (or not at all) over the network. - pub ordered: bool, - /// Maximum age of a non-latest group before the publisher evicts it, in milliseconds. /// The publisher-side half of `moq_subscription.max_age_ms`. pub max_age_ms: u64, @@ -451,8 +447,7 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { // timestamp_us units. An explicit timescale below overrides it. let mut out = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) - .with_priority(info.priority) - .with_ordered(info.ordered); + .with_priority(info.priority); if info.max_age_present { out = out.with_max_age(std::time::Duration::from_millis(info.max_age_ms)); } @@ -473,10 +468,6 @@ pub struct moq_subscription { /// Delivery priority. Higher values preempt lower ones under contention. pub priority: u8, - /// Whether groups are prioritized in sequence order. - /// Groups may always arrive out-of-order (or not at all) over the network. - pub ordered: bool, - /// Maximum age of a non-latest group before it is skipped, in milliseconds. /// Zero skips immediately. Enforced by the publisher's cache and by any local buffering. pub max_age_ms: u64, @@ -496,7 +487,6 @@ impl From<&moq_subscription> for moq_net::track::Subscription { fn from(subscription: &moq_subscription) -> Self { let mut out = moq_net::track::Subscription::default() .with_priority(subscription.priority) - .with_ordered(subscription.ordered) .with_max_age(std::time::Duration::from_millis(subscription.max_age_ms)); if subscription.group_start_present { out = out.with_start(moq_net::track::Position::group(subscription.group_start)); diff --git a/rs/libmoq/src/consume.rs b/rs/libmoq/src/consume.rs index 6b0e0aa1718..80d660c2cdb 100644 --- a/rs/libmoq/src/consume.rs +++ b/rs/libmoq/src/consume.rs @@ -603,7 +603,7 @@ impl Consume { // `subscribe` blocks on SUBSCRIBE_OK, so run it inside the task. tokio::spawn(async move { let res = async move { - let mut track = broadcast.track(&name)?.subscribe(subscription.clone()).await?; + let mut track = broadcast.track(&name)?.subscribe(subscription.clone()).await?.ordered(); Self::apply_raw_subscription(&mut track, subscription); Self::run_raw(on_frame, track, channel.1, updates).await } @@ -620,10 +620,7 @@ impl Consume { Ok(id) } - fn apply_raw_subscription( - track: &mut moq_net::track::Subscriber, - subscription: Option, - ) { + fn apply_raw_subscription(track: &mut moq_net::track::Ordered, subscription: Option) { let subscription = subscription.unwrap_or_default(); if let Some(start) = subscription.start.map(|start| start.group).or_else(|| track.latest()) { track.start_at(start); @@ -639,7 +636,7 @@ impl Consume { async fn run_raw( callback: OnStatus, - mut track: moq_net::track::Subscriber, + mut track: moq_net::track::Ordered, mut close: oneshot::Receiver<()>, mut updates: mpsc::UnboundedReceiver>, ) -> Result<(), Error> { @@ -708,7 +705,7 @@ impl Consume { fn poll_raw_control( close: &mut oneshot::Receiver<()>, updates: &mut mpsc::UnboundedReceiver>, - track: &mut moq_net::track::Subscriber, + track: &mut moq_net::track::Ordered, waiter: &moq_net::kio::Waiter, ) -> bool { let mut cx = std::task::Context::from_waker(waiter.waker()); diff --git a/rs/libmoq/src/test.rs b/rs/libmoq/src/test.rs index 40cf686c075..f8a1d55501a 100644 --- a/rs/libmoq/src/test.rs +++ b/rs/libmoq/src/test.rs @@ -1206,7 +1206,6 @@ fn publish_track_invalid_broadcast() { assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) } < 0); let info = moq_track_info { priority: 1, - ordered: true, max_age_ms: 0, max_age_present: false, timescale: 0, @@ -1221,7 +1220,6 @@ fn publish_track_invalid_broadcast() { let subscription = moq_subscription { priority: 1, - ordered: true, max_age_ms: 0, group_start: 0, group_start_present: false, @@ -1238,7 +1236,6 @@ fn publish_track_with_info_rejects_invalid_timescale() { let name = b"data"; let info = moq_track_info { priority: 0, - ordered: false, max_age_ms: 0, max_age_present: false, timescale: 0, @@ -1249,36 +1246,6 @@ fn publish_track_with_info_rejects_invalid_timescale() { assert_eq!(moq_publish_finish(broadcast), 0); } -#[test] -fn raw_track_options_preserve_ordering_priority() { - let mut info = moq_track_info { - priority: 0, - ordered: false, - max_age_ms: 0, - max_age_present: false, - timescale: 0, - timescale_present: false, - }; - - assert!(!moq_net::track::Info::try_from(&info).unwrap().ordered); - info.ordered = true; - assert!(moq_net::track::Info::try_from(&info).unwrap().ordered); - - let mut subscription = moq_subscription { - priority: 0, - ordered: false, - max_age_ms: 0, - group_start: 0, - group_start_present: false, - group_end: 0, - group_end_present: false, - }; - - assert!(!moq_net::track::Subscription::from(&subscription).ordered); - subscription.ordered = true; - assert!(moq_net::track::Subscription::from(&subscription).ordered); -} - #[test] fn raw_track_publish_consume() { let origin = id(moq_origin_create()); @@ -1303,7 +1270,6 @@ fn raw_track_publish_consume() { // finish draining if the second becomes visible while the callback runs. let subscription = moq_subscription { priority: 0, - ordered: false, max_age_ms: 1_000, group_start: 0, group_start_present: false, @@ -1485,7 +1451,6 @@ fn raw_track_subscription_options_and_update() { let track_name = b"data"; let info = moq_track_info { priority: 3, - ordered: false, max_age_ms: 1_000, max_age_present: true, timescale: 1_000_000, @@ -1507,7 +1472,6 @@ fn raw_track_subscription_options_and_update() { let frame_cb = Callback::new(); let subscription = moq_subscription { priority: 5, - ordered: true, max_age_ms: 25, group_start: 1, group_start_present: true, diff --git a/rs/moq-bench/src/connection.rs b/rs/moq-bench/src/connection.rs index cd2a84dc1dc..57426f920c0 100644 --- a/rs/moq-bench/src/connection.rs +++ b/rs/moq-bench/src/connection.rs @@ -556,7 +556,13 @@ mod tests { // Advance past one full group (keyframe + 2 payload) into the next. tokio::time::advance(Duration::from_millis(350)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap(); + let mut sub = consumer + .track(TRACK) + .unwrap() + .subscribe(replay()) + .await + .unwrap() + .ordered(); let mut group = sub.next_group().await.unwrap().expect("a group"); let keyframe = group.read_frame().await.unwrap().expect("keyframe"); @@ -591,7 +597,13 @@ mod tests { let task = tokio::spawn(produce(0, "bench/test".into(), rolled(10, 4, 0), track, stats.clone())); tokio::time::advance(Duration::from_millis(250)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap(); + let mut sub = consumer + .track(TRACK) + .unwrap() + .subscribe(replay()) + .await + .unwrap() + .ordered(); let mut group = sub.next_group().await.unwrap().expect("a group"); // Just the keyframe, then the group ends. @@ -623,7 +635,7 @@ mod tests { )); tokio::time::advance(Duration::from_millis(250)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap(); + let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap().ordered(); let mut group = sub.next_group().await.unwrap().expect("a group"); let keyframe = group.read_frame().await.unwrap().expect("keyframe").payload; @@ -650,7 +662,7 @@ mod tests { let task = tokio::spawn(produce(3, "bench/test".into(), rolled(10, 50, 0), track, stats.clone())); tokio::time::advance(Duration::from_millis(250)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap(); + let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap().ordered(); let mut group = sub.next_group().await.unwrap().expect("a group"); let keyframe = group.read_frame().await.unwrap().expect("keyframe").payload; diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 280a8baf8f4..023a9af439f 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -44,17 +44,12 @@ fn media_container(container: MoqContainer) -> Result for moq_net::track::Subscription { fn from(s: MoqSubscription) -> Self { moq_net::track::Subscription::default() .with_priority(s.priority) - .with_ordered(s.ordered) .with_max_age(std::time::Duration::from_millis(s.max_age_ms)) .with_start(s.group_start.map(moq_net::track::Position::group)) .with_end(s.group_end.and_then(moq_net::track::Position::after_group)) @@ -285,7 +279,7 @@ impl MoqBroadcastConsumer { /// Subscribe to a track by name, the same pattern as moq-boy's command/status tracks. /// /// Frames are returned as plain byte payloads with no codec or container parsing. - /// `subscription` tunes delivery priority, group ordering priority, and group range; omit for defaults. + /// `subscription` tunes delivery priority, group range, and staleness; omit for defaults. pub async fn subscribe_track( &self, name: String, @@ -337,7 +331,7 @@ impl MoqBroadcastConsumer { /// Subscribe to a track by name, delivering frames in decode order. /// /// `container` is the track container from the catalog. - /// `subscription` tunes delivery priority, group ordering priority, and group range; omit for defaults. + /// `subscription` tunes delivery priority, group range, and staleness; omit for defaults. /// /// [`MoqSubscription::max_age_ms`] bounds the local jitter buffer as well as /// the publisher's cache, so both ends skip a stalled group on the same budget. @@ -369,25 +363,65 @@ fn map_fetch_error(err: moq_net::Error) -> MoqError { // ---- Track Consumer ---- +/// A track subscription reading one way or the other. +/// +/// `moq_net` makes the choice a handle you consume the subscriber into, which a foreign +/// binding can't express in its type system, so the handle commits on first use instead: +/// whichever cursor a caller reaches for first is the one this track keeps. +enum Cursor { + Arrival(moq_net::track::Subscriber), + Ordered(moq_net::track::Ordered), + /// Transient, while the subscriber is moved out to be converted. + Converting, +} + struct TrackInner { - track: moq_net::track::Subscriber, + track: Cursor, } impl TrackInner { + /// The arrival cursor, or [`MoqError::Unsupported`] once this track committed to + /// sequence order. + fn arrival(&mut self) -> Result<&mut moq_net::track::Subscriber, MoqError> { + match &mut self.track { + Cursor::Arrival(track) => Ok(track), + _ => Err(MoqError::Unsupported), + } + } + + /// The sequence cursor, committing this track to it on first use. + fn ordered(&mut self) -> &mut moq_net::track::Ordered { + // Only move the subscriber out when there is one to convert: `ordered()` consumes + // it, and swapping unconditionally would drop an already-converted handle. + if matches!(self.track, Cursor::Arrival(_)) { + let Cursor::Arrival(track) = std::mem::replace(&mut self.track, Cursor::Converting) else { + unreachable!("just matched Arrival"); + }; + self.track = Cursor::Ordered(track.ordered()); + } + match &mut self.track { + Cursor::Ordered(track) => track, + _ => unreachable!("converted above"), + } + } + async fn recv_group(&mut self) -> Result, MoqError> { - Ok(self.track.recv_group().await?) + Ok(self.arrival()?.recv_group().await?) } async fn next_group(&mut self) -> Result, MoqError> { - Ok(self.track.next_group().await?) + Ok(self.ordered().next_group().await?) } async fn read_frame(&mut self) -> Result, MoqError> { - self.track.read_frame().await?.map(raw_frame).transpose() + let Some(mut group) = self.ordered().next_group().await? else { + return Ok(None); + }; + group.read_frame().await?.map(raw_frame).transpose() } async fn recv_datagram(&mut self) -> Result, MoqError> { - let Some(datagram) = self.track.recv_datagram().await? else { + let Some(datagram) = self.arrival()?.recv_datagram().await? else { return Ok(None); }; let timestamp_us = datagram @@ -415,7 +449,9 @@ impl MoqTrackConsumer { let control = track.control(); let info = track.info().clone(); Self { - task: Task::new(TrackInner { track }), + task: Task::new(TrackInner { + track: Cursor::Arrival(track), + }), control, info, } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 92b90184c22..a03b7badf76 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -11,16 +11,12 @@ use crate::origin::MoqRoute; /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults -/// (priority 0, unordered, the publisher's default max age, microsecond timescale). +/// (priority 0, the publisher's default max age, microsecond timescale). #[derive(Clone, uniffi::Record)] pub struct MoqTrackInfo { /// Priority, used only to break ties between subscriptions of equal subscriber priority. #[uniffi(default = 0)] pub priority: u8, - /// Whether groups are prioritized in sequence order. Groups may always arrive - /// out-of-order (or not at all) over the network. Defaults to false. - #[uniffi(default = false)] - pub ordered: bool, /// Maximum age of a non-latest group before the publisher evicts it, in /// milliseconds. Null uses the default. This is the publisher-side half of /// [`MoqSubscription::max_age_ms`](crate::consumer::MoqSubscription::max_age_ms). @@ -37,8 +33,7 @@ impl TryFrom for moq_net::track::Info { fn try_from(info: MoqTrackInfo) -> Result { let mut out = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) - .with_priority(info.priority) - .with_ordered(info.ordered); + .with_priority(info.priority); if let Some(ms) = info.max_age_ms { out = out.with_max_age(std::time::Duration::from_millis(ms)); } @@ -65,7 +60,6 @@ impl TryFrom<&moq_net::track::Info> for MoqTrackInfo { .map_err(|_| MoqError::Codec("track max_age duration overflow".into()))?; Ok(Self { priority: info.priority, - ordered: info.ordered, max_age_ms: Some(max_age_ms), timescale: Some(info.timescale.as_u64()), }) @@ -694,7 +688,7 @@ impl MoqTrackProducer { /// Create a consumer that reads from this producer's track. /// /// Useful for local pub/sub without going through an origin/broadcast. `subscription` - /// tunes delivery priority, group ordering priority, and group range; omit for defaults. + /// tunes delivery priority, group range, and staleness; omit for defaults. pub fn consume(&self, subscription: Option) -> Result, MoqError> { let _guard = crate::ffi::enter(); let guard = self.inner.lock().unwrap(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 913a5ec0b43..f3167d3cbb7 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -284,7 +284,6 @@ async fn raw_track_datagram_roundtrip() { "events".into(), Some(MoqTrackInfo { priority: 0, - ordered: true, max_age_ms: None, timescale: Some(1_000_000), }), @@ -315,7 +314,6 @@ async fn raw_track_info_reports_publisher_properties() { let broadcast = MoqBroadcastProducer::new().unwrap(); let info = MoqTrackInfo { priority: 7, - ordered: false, max_age_ms: Some(2_500), timescale: Some(90_000), }; @@ -324,20 +322,10 @@ async fn raw_track_info_reports_publisher_properties() { let got = consumer.info().unwrap(); assert_eq!(got.priority, 7); - assert!(!got.ordered); assert_eq!(got.max_age_ms, Some(2_500)); assert_eq!(got.timescale, Some(90_000)); } -#[tokio::test] -async fn raw_track_info_defaults_to_unordered() { - let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); - let consumer = track.consume(None).unwrap(); - - assert!(!consumer.info().unwrap().ordered); -} - #[tokio::test] async fn raw_track_update_does_not_wait_for_pending_read() { let broadcast = MoqBroadcastProducer::new().unwrap(); @@ -351,7 +339,6 @@ async fn raw_track_update_does_not_wait_for_pending_read() { consumer.update(MoqSubscription { priority: 10, - ordered: false, max_age_ms: 25, group_start: Some(0), group_end: None, @@ -1829,6 +1816,45 @@ async fn dynamic_broadcast_request() { served.finish().unwrap(); } +/// The sequence cursor commits on first use, so every later read has to reach the same +/// converted handle. Repeating the conversion (or dropping it on the way through) leaves +/// the track in its transient state and panics the next read. +#[tokio::test] +async fn raw_track_next_group_is_repeatable() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("commands".into(), None).unwrap(); + let consumer = broadcast + .consume() + .unwrap() + .subscribe_track("commands".into(), None) + .await + .unwrap(); + + for payload in [b"one".to_vec(), b"two".to_vec(), b"three".to_vec()] { + track + .write_frame(MoqFrame { + payload: payload.clone(), + timestamp_us: 0, + }) + .unwrap(); + + let group = tokio::time::timeout(TIMEOUT, consumer.next_group()) + .await + .expect("timed out waiting for a group") + .unwrap() + .expect("expected a group"); + let frame = tokio::time::timeout(TIMEOUT, group.read_frame()) + .await + .expect("timed out waiting for a frame") + .unwrap() + .expect("expected a frame"); + assert_eq!(frame.payload, payload); + } + + // The arrival cursor is gone once the track committed to sequence order. + assert!(matches!(consumer.recv_group().await, Err(MoqError::Unsupported))); +} + #[tokio::test] async fn dynamic_broadcast_request_can_reject() { let origin = MoqOriginProducer::new(MoqOriginOptions::default()); diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 7a54d214677..72f253598ea 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -987,7 +987,8 @@ mod tests { .expect("the opaque track is published") .subscribe(moq_net::track::Subscription::default().with_max_age(std::time::Duration::from_secs(1))) .await - .expect("subscribe to the opaque track"); + .expect("subscribe to the opaque track") + .ordered(); let mut group = subscriber.next_group().await.unwrap().expect("a first group"); let frame = group.read_frame().await.unwrap().expect("a frame in the first group"); @@ -1104,7 +1105,8 @@ mod tests { .expect("the opaque track is published") .subscribe(None) .await - .expect("subscribe to the opaque track"); + .expect("subscribe to the opaque track") + .ordered(); let mut group = subscriber.next_group().await.unwrap().expect("a group"); let frame = group.read_frame().await.unwrap().expect("a frame"); assert_eq!(frame.payload.as_ref(), b"no pts", "the unstamped buffer was published"); diff --git a/rs/moq-json/examples/telemetry.rs b/rs/moq-json/examples/telemetry.rs index bb76af5d129..7839a18c192 100644 --- a/rs/moq-json/examples/telemetry.rs +++ b/rs/moq-json/examples/telemetry.rs @@ -91,7 +91,7 @@ fn wire_bytes(config: ProducerConfig, ticks: u64) -> usize { // Drain the raw stored frames (compressed if the producer compressed them) and sum their sizes. let waiter = kio::Waiter::noop(); let mut total = 0; - let mut track = consumer; + let mut track = consumer.ordered(); while let Poll::Ready(Ok(Some(mut group))) = track.poll_next_group(&waiter) { while let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) { total += frame.payload.len(); diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 6ae3eb86030..67b23ea0091 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -13,7 +13,7 @@ use crate::Result; /// yields the reconstructed value. When something else already owns the track, use the [`Decoder`] /// directly. pub struct Consumer { - track: moq_net::track::Subscriber, + track: moq_net::track::Ordered, group: Option, decoder: Decoder, frames_read: usize, @@ -26,7 +26,7 @@ impl Consumer { /// [`ProducerConfig::compression`](super::ProducerConfig::compression) on. pub fn new(track: moq_net::track::Subscriber, config: ConsumerConfig) -> Self { Self { - track, + track: track.ordered(), group: None, decoder: Decoder::new(config), frames_read: 0, diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index dc5a3b084f0..8258446e583 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -348,7 +348,7 @@ mod test { #[test] fn a_rejected_snapshot_does_not_strand_an_empty_group() { let track = rejecting_track(); - let mut subscriber = track.subscribe(None); + let mut subscriber = track.subscribe(None).ordered(); let mut producer = Producer::::new(track, cfg(0)); assert!(matches!(producer.update(&json!({ "a": 1 })), Err(crate::Error::Net(_)))); @@ -562,7 +562,7 @@ mod test { fn compressed_deltas_reuse_window() { // The shared per-group window is the whole point: a delta that restates content already in // the snapshot compresses to far fewer bytes than the raw patch. - let (mut producer, mut track) = producer(cfg_deflate(100)); + let (mut producer, track) = producer(cfg_deflate(100)); let phrase = "Media over QUIC delivers real-time latency at massive scale"; producer.update(&json!({ "note": phrase })).unwrap(); producer.update(&json!({ "note": phrase, "echo": phrase })).unwrap(); @@ -570,6 +570,7 @@ mod test { // Both frames land in group 0; read the delta (frame 1) verbatim. let waiter = kio::Waiter::noop(); + let mut track = track.ordered(); let Poll::Ready(Ok(Some(mut group))) = track.poll_next_group(&waiter) else { panic!("expected a group"); }; @@ -632,11 +633,12 @@ mod test { /// Publish a single value and return the byte length of the resulting (frame 0) wire frame. fn wire_frame_len(config: ProducerConfig, value: &Value) -> usize { - let (mut producer, mut track) = producer(config); + let (mut producer, track) = producer(config); producer.update(value).unwrap(); producer.finish().unwrap(); let waiter = kio::Waiter::noop(); + let mut track = track.ordered(); let Poll::Ready(Ok(Some(mut group))) = track.poll_next_group(&waiter) else { panic!("expected a group"); }; diff --git a/rs/moq-json/src/stream/consumer.rs b/rs/moq-json/src/stream/consumer.rs index 51bb765c456..fcfc4caf5b4 100644 --- a/rs/moq-json/src/stream/consumer.rs +++ b/rs/moq-json/src/stream/consumer.rs @@ -15,7 +15,7 @@ use crate::Result; /// [`Encoder`](super::Encoder) desync is cleared) is read here too. When something else already owns /// the track, use the [`Decoder`] directly. pub struct Consumer { - track: moq_net::track::Subscriber, + track: moq_net::track::Ordered, group: Option, decoder: Decoder, } @@ -27,7 +27,7 @@ impl Consumer { /// [`ProducerConfig::compression`](super::ProducerConfig::compression) on. pub fn new(track: moq_net::track::Subscriber, config: ConsumerConfig) -> Self { Self { - track, + track: track.ordered(), group: None, decoder: Decoder::new(config), } diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 48d2598b93e..54d3f4eb099 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -127,13 +127,14 @@ mod test { #[test] fn shared_window_shrinks_repetitive_records() { - let (mut producer, mut track) = producer(compressed()); + let (mut producer, track) = producer(compressed()); for n in 0..8 { producer.append(&json!({ "group": n, "pts": n * 2_000 })).unwrap(); } producer.finish().unwrap(); let waiter = kio::Waiter::noop(); + let mut track = track.ordered(); let Poll::Ready(Ok(Some(mut group))) = track.poll_next_group(&waiter) else { panic!("expected a group"); }; @@ -188,7 +189,7 @@ mod test { #[test] fn a_rejected_record_does_not_strand_an_empty_group() { let track = rejecting_track(); - let mut subscriber = track.subscribe(None); + let mut subscriber = track.subscribe(None).ordered(); let mut producer = Producer::::new(track, ProducerConfig::default()); assert!(producer.append(&json!({ "n": 1 })).is_err()); diff --git a/rs/moq-mux/src/catalog/msf/consumer.rs b/rs/moq-mux/src/catalog/msf/consumer.rs index d6c033aa3b2..834bb20471b 100644 --- a/rs/moq-mux/src/catalog/msf/consumer.rs +++ b/rs/moq-mux/src/catalog/msf/consumer.rs @@ -14,7 +14,7 @@ use crate::catalog::msf::Error; /// so the rest of the pipeline only deals with hang types. pub struct Consumer { /// Access to the underlying track consumer. - pub track: moq_net::track::Subscriber, + pub track: moq_net::track::Ordered, group: Option, } @@ -23,7 +23,10 @@ impl Consumer { /// /// The track is expected to carry MSF catalog payloads (track name [`moq_msf::DEFAULT_NAME`]). pub fn new(track: moq_net::track::Subscriber) -> Self { - Self { track, group: None } + Self { + track: track.ordered(), + group: None, + } } /// Poll for the next catalog update, returned as a [`hang::Catalog`]. diff --git a/rs/moq-mux/src/container/fmp4/muxer.rs b/rs/moq-mux/src/container/fmp4/muxer.rs index 0f23576dc3a..dfffd82d69d 100644 --- a/rs/moq-mux/src/container/fmp4/muxer.rs +++ b/rs/moq-mux/src/container/fmp4/muxer.rs @@ -320,7 +320,7 @@ mod tests { .produce() .create_track("v", None) .unwrap(); - let mut subscriber = track.subscribe(None); + let mut subscriber = track.subscribe(None).ordered(); let mut producer = crate::container::Producer::new(track, HangContainer::Legacy); producer.write(frame(10_000_000, true)).unwrap(); producer.write(frame(10_033_000, false)).unwrap(); @@ -355,7 +355,7 @@ mod tests { .produce() .create_track("v", None) .unwrap(); - let mut subscriber = track.subscribe(None); + let mut subscriber = track.subscribe(None).ordered(); let mut producer = crate::container::Producer::new(track, HangContainer::Legacy); producer .write(Frame { diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index cef66ba12ef..cca6a9e2969 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -226,7 +226,7 @@ enum SiState { /// Waiting for the subscription to resolve. Subscribing(kio::Pending), /// The resolved subscription, reading snapshot groups. - Active(moq_net::track::Subscriber), + Active(moq_net::track::Ordered), /// The track ended or failed; the last complete snapshot keeps re-emitting, /// mirroring how a real mux repeats its tables between (absent) revisions. Done, @@ -290,7 +290,7 @@ impl SiTrack { } }; self.state = match resolved { - Ok(track) => SiState::Active(track), + Ok(track) => SiState::Active(track.ordered()), Err(err) => { tracing::warn!(%err, "SI subscription failed; carrying the last snapshot"); SiState::Done diff --git a/rs/moq-net/src/lite/priority.rs b/rs/moq-net/src/lite/priority.rs index 36b1579c0ca..086a6a0110f 100644 --- a/rs/moq-net/src/lite/priority.rs +++ b/rs/moq-net/src/lite/priority.rs @@ -21,45 +21,25 @@ use std::{ /// belongs to, and its group sequence. /// /// Higher `track` always wins. `group` breaks ties only *within* one `subscribe`, -/// in the direction that subscription asked for: a live subscription transmits the -/// newest group first, an `Ordered` one the oldest. +/// newest first, so a congested track sheds its backlog rather than its live edge. /// -/// Scoping the tie-break to a subscription is what keeps `Ordered` from deciding -/// between tracks. The draft gives that job to `Priority` alone, so a session -/// carrying an ordered track and a live one at equal priority must interleave them -/// by priority, not by direction. Comparing the two directions in one space cannot -/// do that: whichever encoding puts the oldest group on top also puts it above -/// every group of the other subscription. +/// Scoping the tie-break to a subscription is what keeps group sequence from deciding +/// between tracks. The draft gives that job to `Priority` alone, so a session carrying +/// two tracks at equal priority interleaves them rather than draining one first. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Priority { track: u8, subscribe: u64, group: u64, - /// The owning subscription's `Ordered` preference, which decides which way - /// `group` is read. [`PriorityState::set_ordered`] moves a whole - /// subscription's groups at once so they agree on it. - ordered: bool, } impl Priority { - /// Rank for a live (unordered) subscription: the newest group transmits first. + /// Rank a group for transmission: the newest group of a track transmits first. pub fn new(track: u8, subscribe: u64, group: u64) -> Self { Self { track, subscribe, group, - ordered: false, - } - } - - /// Rank for an `Ordered` subscription: the oldest group transmits first, so - /// back-to-back groups leave the session in sequence order. - pub fn ordered(track: u8, subscribe: u64, group: u64) -> Self { - Self { - track, - subscribe, - group, - ordered: true, } } } @@ -74,19 +54,9 @@ impl Ord for Priority { // stable and independent of either one's direction. The older (lower id) // subscription goes first. .then(self.subscribe.cmp(&other.subscribe)) - // Normally redundant, since one subscription's groups all carry its - // direction. It is here so the comparison below is reached only by two - // groups that agree on it, which makes this a total order for every - // value rather than only for well-formed ones: reversing the sense for - // one side alone is intransitive, and `sort` is documented to be free - // to panic on a comparator that does that. Nothing in the protocol - // stops a peer opening two SUBSCRIBEs with one id and disagreeing. - .then(self.ordered.cmp(&other.ordered)) - // Both sides agree on the direction, so it can be read off either. - .then_with(|| match self.ordered { - true => self.group.cmp(&other.group), - false => other.group.cmp(&self.group), - }) + // Newest group first, which is what makes a congested track shed its + // backlog rather than its live edge. + .then(other.group.cmp(&self.group)) } } @@ -132,12 +102,6 @@ impl PriorityQueue { pub fn insert(&self, priority: Priority) -> PriorityHandle { self.state.lock().unwrap().insert(priority, self.clone()) } - - /// Apply a subscription's new `Ordered` preference to the groups it has already - /// queued, so a SUBSCRIBE_UPDATE reaches the backlog and not just what follows it. - pub fn set_ordered(&self, subscribe: u64, ordered: bool) { - self.state.lock().unwrap().set_ordered(subscribe, ordered); - } } const MAX_VEC_SIZE: usize = 255; @@ -294,49 +258,12 @@ impl PriorityState { } /// Change one item's track priority, leaving the rest of its rank alone. - /// - /// Deliberately narrower than "write back a whole [`Priority`]": a handle's copy - /// of the direction goes stale the moment [`Self::set_ordered`] runs, and pushing - /// that copy back would resurrect the old direction for a single group. fn set_track(&mut self, id: usize, track: u8) { let mut item = self.extract(id); item.priority.track = track; self.place(item); } - /// Flip the group direction for every queued group of one subscription. - /// - /// Done wholesale rather than per item because [`Priority`] is only a total order - /// while every group of a subscription agrees on its direction. Re-placing them - /// one at a time would leave the queue comparing an ordered rank against a live - /// one from the same subscription, which is intransitive and would corrupt the - /// sorted vec. The flip can also move entries across the vec/overflow boundary, - /// so both containers are rebuilt from one sorted snapshot. - fn set_ordered(&mut self, subscribe: u64, ordered: bool) { - let stale = |item: &PriorityItem| item.priority.subscribe == subscribe && item.priority.ordered != ordered; - if !self.vec.iter().any(stale) && !self.overflow.iter().any(|Reverse(item)| stale(item)) { - return; - } - - let mut items = std::mem::take(&mut self.vec); - items.extend(self.overflow.drain().map(|Reverse(item)| item)); - for item in &mut items { - if item.priority.subscribe == subscribe { - item.priority.ordered = ordered; - } - } - items.sort(); - - let overflow = items.split_off(items.len().min(MAX_VEC_SIZE)); - self.vec = items; - self.update_indices_from(0); - for item in overflow { - let id = item.id; - self.overflow.push(Reverse(item)); - Self::update_location(&mut self.indexes, id, Location::Overflow); - } - } - fn remove(&mut self, id: usize) { let was_in_vec = matches!(self.indexes.get(&id), Some((Location::Vec(_), _))); self.extract(id); @@ -355,9 +282,8 @@ impl PriorityState { pub struct PriorityHandle { id: usize, - /// This item's track priority, the only part of its rank a handle owns. The - /// rest lives in the queue, which [`PriorityQueue::set_ordered`] can change - /// underneath us. + /// This item's track priority, the only part of its rank a handle owns; the + /// rest is fixed when the item is queued. track: u8, rx: kio::Consumer, /// Last value observed via [`current`](Self::current)/[`next`](Self::next), so @@ -434,11 +360,6 @@ mod tests { Priority::new(track, 0, group) } - /// The same, for a subscription that asked for `Ordered`. - fn older_first(track: u8, group: u64) -> Priority { - Priority::ordered(track, 0, group) - } - #[test] fn test_single_item() { let queue = PriorityQueue::default(); @@ -491,96 +412,12 @@ mod tests { assert_eq!(group1.current(), 2); } + /// `Ord` has to hold for every value: the queue sorts a shared vec, and a + /// comparator that says `a < b` and `b < a` is free to panic `sort`. #[test] - fn test_ordered_prefers_older_groups() { - let queue = PriorityQueue::default(); - - // Same track priority, ordered subscription: sequence order wins. - let mut group1 = queue.insert(older_first(100, 1)); - let mut group5 = queue.insert(older_first(100, 5)); - let mut group10 = queue.insert(older_first(100, 10)); - - assert_eq!(group1.current(), 0); - assert_eq!(group5.current(), 1); - assert_eq!(group10.current(), 2); - } - - /// `Ordered` chooses between a subscription's own groups, never between - /// subscriptions. One queue serves the whole session, so an ordered rank and a - /// live rank meet here constantly; if the direction were compared across them, - /// every ordered group would outrank every live one at the same priority and - /// starve a live track that shares the session. - #[test] - fn test_ordered_does_not_outrank_a_live_subscription() { - let queue = PriorityQueue::default(); - - // Same track priority: one live subscription, one that asked for Ordered. - let mut live_new = queue.insert(Priority::new(100, 0, 2)); - let mut live_old = queue.insert(Priority::new(100, 0, 1)); - let mut ordered_old = queue.insert(Priority::ordered(100, 1, 1)); - let mut ordered_new = queue.insert(Priority::ordered(100, 1, 2)); - - // The subscriptions stay whole and in id order; neither one's direction - // promotes it past the other. - assert_eq!(live_new.current(), 0); - assert_eq!(live_old.current(), 1); - assert_eq!(ordered_old.current(), 2); - assert_eq!(ordered_new.current(), 3); - } - - /// A subscription that flips to `Ordered` mid-stream means it about the groups - /// already queued for it, not just the ones that follow. Leaving the backlog on - /// the old direction would let every new group outrank exactly the groups the - /// subscriber just asked to receive first. - #[test] - fn test_set_ordered_reranks_the_backlog() { - let queue = PriorityQueue::default(); - - let mut group1 = queue.insert(live(100, 1)); - let mut group2 = queue.insert(live(100, 2)); - let mut group3 = queue.insert(live(100, 3)); - assert_eq!((group3.current(), group2.current(), group1.current()), (0, 1, 2)); - - queue.set_ordered(0, true); - assert_eq!((group1.current(), group2.current(), group3.current()), (0, 1, 2)); - - // And back: the direction is not a one-way door. - queue.set_ordered(0, false); - assert_eq!((group3.current(), group2.current(), group1.current()), (0, 1, 2)); - } - - /// The flip can move an entry across the vec/overflow boundary, so both sides - /// are rebuilt: the oldest groups start out demoted past index 254 and have to - /// come back as the top of the queue. - #[test] - fn test_set_ordered_promotes_across_the_overflow_boundary() { - let queue = PriorityQueue::default(); - - let total = MAX_VEC_SIZE + 50; - let mut handles: Vec<_> = (0..total as u64).map(|group| queue.insert(live(100, group))).collect(); - - // Live ranks newest first, so the oldest groups sit in overflow. - assert_eq!(handles[total - 1].current(), 0); - assert_eq!(handles[0].current(), u8::MAX); - - queue.set_ordered(0, true); - - // Ordered inverts it: the oldest group leads and the newest is demoted. - assert_eq!(handles[0].current(), 0); - assert_eq!(handles[1].current(), 1); - assert_eq!(handles[total - 1].current(), u8::MAX); - } - - /// `Ord` has to hold for every value, not just the ones a well-behaved peer - /// produces. Nothing stops a peer opening two SUBSCRIBEs with the same id and - /// opposite `Ordered`, which lands both directions under one subscribe id, and - /// a comparator that says `a < b` and `b < a` is free to panic `sort`. - #[test] - fn test_ord_is_total_across_mixed_directions() { + fn test_ord_is_total() { let mixed = [ - Priority::ordered(100, 7, 1), Priority::new(100, 7, 1), - Priority::ordered(100, 7, 2), Priority::new(100, 7, 2), Priority::new(100, 8, 1), Priority::new(200, 7, 1), @@ -600,22 +437,6 @@ mod tests { } } - /// A flip must not disturb a subscription that did not ask for one. - #[test] - fn test_set_ordered_leaves_other_subscriptions_alone() { - let queue = PriorityQueue::default(); - - let mut other_new = queue.insert(Priority::new(100, 7, 2)); - let mut other_old = queue.insert(Priority::new(100, 7, 1)); - let mut mine = queue.insert(Priority::new(100, 9, 1)); - - queue.set_ordered(9, true); - - assert_eq!(other_new.current(), 0, "an untouched subscription keeps newest-first"); - assert_eq!(other_old.current(), 1); - assert_eq!(mine.current(), 2); - } - #[test] fn test_track_priority_overrides_group() { let queue = PriorityQueue::default(); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index c3c588b4893..208829b048a 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1260,7 +1260,6 @@ impl TrackInfoServe { let stream = self.stream.as_mut().expect("stream present"); stream.writer.buffer(&lite::TrackInfo { priority: info.priority, - ordered: info.ordered, max_age: info.max_age, timescale: info.timescale, })?; @@ -1399,7 +1398,6 @@ impl SubscribeServe { let subscription = crate::track::Subscription { priority: msg.priority, - ordered: msg.ordered, max_age: serving_max_age(self.shared.version, msg.max_age), ..Bounds::from(&msg).positions() }; @@ -1439,7 +1437,6 @@ impl SubscribeServe { if !self.shared.version.has_track_stream() { let info = lite::SubscribeOk { priority: msg.priority, - ordered: false, max_age: Duration::ZERO, start_group: None, end_group: None, @@ -1460,7 +1457,6 @@ impl SubscribeServe { priority: self.shared.priority.clone(), track_priority: track_priority_tx.consume(), track_priority_seen: msg.priority, - ordered: msg.ordered, version: self.shared.version, timescale, }; @@ -2726,10 +2722,6 @@ struct Subscription { track_priority: kio::Consumer, /// Last track priority observed by this clone, so a change only fires once. track_priority_seen: u8, - /// The subscriber's `Ordered` preference: rank older groups first so they - /// transmit in sequence order, instead of the live default of newest first. - /// Applied to groups as they are queued; refreshed by SUBSCRIBE_UPDATE. - ordered: bool, version: Version, /// Negotiated timestamp scale for this track. `Some(_)` on lite-05+ after /// TRACK_INFO; used to validate per-frame timestamps before encoding. @@ -2881,21 +2873,11 @@ impl TrackRun { if let Ok(mut value) = self.track_priority_tx.write() { *value = upd.priority; } - // Re-rank the backlog too, not just the groups queued from here on. - // The preference is about which of the groups we are holding to send - // first, so leaving the queued ones on the old direction would let - // every new group outrank exactly the ones the subscriber just asked - // to receive first, starving them until they expire. - if self.ctx.ordered != upd.ordered { - self.ctx.ordered = upd.ordered; - self.ctx.priority.set_ordered(self.ctx.id, self.ctx.ordered); - } // Feed the full update into the model subscriber so the producer's // aggregate reflects it (and a relay re-forwards it upstream). let bounds = Bounds::from(&upd); let _ = self.track.update(crate::track::Subscription { priority: upd.priority, - ordered: upd.ordered, max_age: serving_max_age(self.ctx.version, upd.max_age), ..bounds.positions() }); @@ -2949,11 +2931,10 @@ impl TrackRun { // The subscribe id scopes the group tie-break: one queue serves every // subscription on the session, and only groups of the same one may be // ranked against each other by sequence. - let priority = match self.ctx.ordered { - true => Priority::ordered(current_priority, self.ctx.id, sequence), - false => Priority::new(current_priority, self.ctx.id, sequence), - }; - let handle = self.ctx.priority.insert(priority); + let handle = self + .ctx + .priority + .insert(Priority::new(current_priority, self.ctx.id, sequence)); self.children .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, handle, group)); } @@ -3334,7 +3315,6 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - ordered: false, version: Version::Lite06Wip, timescale: Some(crate::Timescale::default()), }; @@ -3375,7 +3355,6 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - ordered: false, version: Version::Lite06Wip, timescale: Some(crate::Timescale::default()), }; @@ -3420,7 +3399,6 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - ordered: false, version: Version::Lite06Wip, timescale: Some(crate::Timescale::default()), }; @@ -3483,7 +3461,6 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - ordered: false, version: Version::Lite06Wip, timescale: Some(crate::Timescale::default()), }; @@ -3553,7 +3530,6 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - ordered: false, version: Version::Lite06Wip, timescale: Some(crate::Timescale::default()), }; diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index c012ed14809..c36ce035bdc 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -16,7 +16,6 @@ pub struct Subscribe<'a> { pub broadcast: Path<'a>, pub track: Cow<'a, str>, pub priority: u8, - pub ordered: bool, pub max_age: std::time::Duration, pub start_group: Option, pub end_group: Option, @@ -46,14 +45,14 @@ impl Message for Subscribe<'_> { let track = Cow::::decode(r, version)?; let priority = u8::decode(r, version)?; - let (ordered, max_age, start_group, end_group) = match version { - Version::Lite01 | Version::Lite02 => (false, std::time::Duration::ZERO, None, None), + let (max_age, start_group, end_group) = match version { + Version::Lite01 | Version::Lite02 => (std::time::Duration::ZERO, None, None), _ => { - let ordered = u8::decode(r, version)? != 0; + skip_group_order(r, version)?; let max_age = std::time::Duration::decode(r, version)?; let start_group = Option::::decode(r, version)?; let end_group = Option::::decode(r, version)?; - (ordered, max_age, start_group, end_group) + (max_age, start_group, end_group) } }; @@ -64,7 +63,6 @@ impl Message for Subscribe<'_> { broadcast, track, priority, - ordered, max_age, start_group, end_group, @@ -82,7 +80,7 @@ impl Message for Subscribe<'_> { match version { Version::Lite01 | Version::Lite02 => {} _ => { - (self.ordered as u8).encode(w, version)?; + pad_group_order(w, version)?; self.max_age.encode(w, version)?; self.start_group.encode(w, version)?; self.end_group.encode(w, version)?; @@ -102,6 +100,25 @@ impl Message for Subscribe<'_> { } } +/// Step over the retired `Ordered` byte on a version whose layout still has it. +/// +/// The value is ignored: group order is fixed, so a peer that still sets it gets the +/// same newest-first delivery as one that doesn't. +pub(super) fn skip_group_order(r: &mut R, version: Version) -> Result<(), DecodeError> { + if version.has_group_order() { + u8::decode(r, version)?; + } + Ok(()) +} + +/// Write the retired `Ordered` byte as 0, keeping a deployed version's field offsets. +pub(super) fn pad_group_order(w: &mut W, version: Version) -> Result<(), EncodeError> { + if version.has_group_order() { + 0u8.encode(w, version)?; + } + Ok(()) +} + /// Decode the trailing `Frame Start` / `Frame End` pair shared by SUBSCRIBE, /// SUBSCRIBE_UPDATE, and FETCH. /// @@ -162,7 +179,6 @@ fn encode_frame_bounds( #[derive(Clone, Debug)] pub struct SubscribeOk { pub priority: u8, - pub ordered: bool, pub max_age: std::time::Duration, pub start_group: Option, pub end_group: Option, @@ -179,7 +195,7 @@ impl Message for SubscribeOk { // Lite03/04 so a stray future use stays well-formed. _ => { self.priority.encode(w, version)?; - (self.ordered as u8).encode(w, version)?; + pad_group_order(w, version)?; self.max_age.encode(w, version)?; self.start_group.encode(w, version)?; self.end_group.encode(w, version)?; @@ -193,28 +209,25 @@ impl Message for SubscribeOk { match version { Version::Lite01 => Ok(Self { priority: u8::decode(r, version)?, - ordered: false, max_age: std::time::Duration::ZERO, start_group: None, end_group: None, }), Version::Lite02 => Ok(Self { priority: 0, - ordered: false, max_age: std::time::Duration::ZERO, start_group: None, end_group: None, }), _ => { let priority = u8::decode(r, version)?; - let ordered = u8::decode(r, version)? != 0; + skip_group_order(r, version)?; let max_age = std::time::Duration::decode(r, version)?; let start_group = Option::::decode(r, version)?; let end_group = Option::::decode(r, version)?; Ok(Self { priority, - ordered, max_age, start_group, end_group, @@ -289,7 +302,6 @@ impl Message for SubscribeEnd { #[derive(Clone, Debug)] pub struct SubscribeUpdate { pub priority: u8, - pub ordered: bool, pub max_age: std::time::Duration, pub start_group: Option, pub end_group: Option, @@ -309,7 +321,7 @@ impl Message for SubscribeUpdate { } let priority = u8::decode(r, version)?; - let ordered = u8::decode(r, version)? != 0; + skip_group_order(r, version)?; let max_age = std::time::Duration::decode(r, version)?; let start_group = match u64::decode(r, version)? { 0 => None, @@ -324,7 +336,6 @@ impl Message for SubscribeUpdate { Ok(Self { priority, - ordered, max_age, start_group, end_group, @@ -342,7 +353,7 @@ impl Message for SubscribeUpdate { } self.priority.encode(w, version)?; - (self.ordered as u8).encode(w, version)?; + pad_group_order(w, version)?; self.max_age.encode(w, version)?; match self.start_group { @@ -574,7 +585,6 @@ mod test { broadcast: Path::new("room").to_owned(), track: Cow::Borrowed("video"), priority: 3, - ordered: true, max_age: std::time::Duration::from_millis(250), start_group: Some(7), end_group: Some(9), @@ -596,7 +606,7 @@ mod test { /// The whole-group defaults are what a version without the fields decodes to, so /// lite-05 stays byte-identical. #[test] - fn subscribe_without_frame_bounds_is_unchanged_on_lite05() { + fn subscribe_drops_the_retired_ordered_byte_on_lite06() { let mut msg = subscribe_sample(); msg.start_frame = 0; msg.end_frame = None; @@ -606,9 +616,20 @@ mod test { let mut lite06 = Vec::new(); msg.encode_msg(&mut lite06, Version::Lite06Wip).unwrap(); - // Lite06 appends the two defaulted varints and nothing else. - assert_eq!(&lite06[..lite05.len()], &lite05[..]); - assert_eq!(&lite06[lite05.len()..], &[0, 0]); + // The two layouts diverge in exactly one place: the retired byte lite-05 still + // reserves. A deployed peer's field offsets depend on it being there and zero. + let ordered_at = lite05 + .iter() + .zip(&lite06) + .position(|(a, b)| a != b) + .expect("the layouts must diverge at the retired byte"); + assert_eq!(lite05[ordered_at], 0, "the retired byte is written as zero"); + + // Remove it and lite-06 is the same message plus the two defaulted frame varints. + let mut spliced = lite05.clone(); + spliced.remove(ordered_at); + assert_eq!(&lite06[..spliced.len()], &spliced[..]); + assert_eq!(&lite06[spliced.len()..], &[0, 0]); let got = Subscribe::decode_msg(&mut lite05.as_slice(), Version::Lite05).unwrap(); assert_eq!((got.start_frame, got.end_frame), (0, None)); @@ -649,7 +670,6 @@ mod test { fn subscribe_ok_rejected_on_lite05() { let resp = SubscribeResponse::Ok(SubscribeOk { priority: 1, - ordered: true, max_age: std::time::Duration::ZERO, start_group: None, end_group: None, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index b9d15020710..eecef9740c5 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -2276,7 +2276,6 @@ struct SubStream { id: u64, /// Original SUBSCRIBE params, echoed in every SUBSCRIBE_UPDATE; refreshed as the /// downstream aggregate changes. - ordered: bool, max_age: Duration, start: Option, priority: u8, @@ -2445,7 +2444,6 @@ impl TrackServe { // SUBSCRIBE_UPDATE (Lite03+ only; older peers can't carry one). let start_moved = active.start != subscription.start; active.priority = subscription.priority; - active.ordered = subscription.ordered; active.max_age = subscription.max_age; active.start = subscription.start; if supports_update { @@ -2610,7 +2608,6 @@ fn buffer_update( let bounds = WireBounds::new(active.start, end); active.stream.writer.buffer(&lite::SubscribeUpdate { priority: active.priority, - ordered: active.ordered, max_age: active.max_age, start_group: bounds.start_group, end_group: bounds.end_group, @@ -2665,7 +2662,6 @@ impl Establish { broadcast: self.serve.path.as_path(), track: self.serve.name.as_str().into(), priority: self.subscription.priority, - ordered: self.subscription.ordered, max_age: self.subscription.max_age, start_group: bounds.start_group, end_group: bounds.end_group, @@ -2710,7 +2706,6 @@ impl Establish { SubStream { stream, id: self.id, - ordered: self.subscription.ordered, max_age: self.subscription.max_age, start: self.subscription.start, priority: self.subscription.priority, @@ -2885,8 +2880,7 @@ impl TrackInfoFetch { let model = track::Info::default() .with_timescale(info.timescale) .with_max_age(info.max_age) - .with_priority(info.priority) - .with_ordered(info.ordered); + .with_priority(info.priority); return Poll::Ready(Ok(model)); } } diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 9dfa62ef427..79dcd0daffd 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -49,9 +49,6 @@ impl Message for Track<'_> { pub struct TrackInfo { /// The publisher's tie-break priority for this track. pub priority: u8, - /// Whether groups are prioritized in sequence order. Groups may always arrive - /// out-of-order (or not at all) over the network. - pub ordered: bool, /// Publisher Max Age: an upper bound on how long the publisher caches a /// non-latest group past the arrival of a newer one. Encoded as milliseconds. pub max_age: Duration, @@ -67,13 +64,12 @@ impl Message for TrackInfo { } let priority = u8::decode(r, version)?; - let ordered = u8::decode(r, version)? != 0; + super::subscribe::skip_group_order(r, version)?; let max_age = Duration::decode(r, version)?; let timescale = Timescale::new(u64::decode(r, version)?).map_err(|_| DecodeError::InvalidValue)?; Ok(Self { priority, - ordered, max_age, timescale, }) @@ -85,7 +81,7 @@ impl Message for TrackInfo { } self.priority.encode(w, version)?; - (self.ordered as u8).encode(w, version)?; + super::subscribe::pad_group_order(w, version)?; self.max_age.encode(w, version)?; u64::from(self.timescale).encode(w, version)?; Ok(()) @@ -99,7 +95,6 @@ mod test { fn info_sample() -> TrackInfo { TrackInfo { priority: 7, - ordered: false, max_age: Duration::from_millis(2000), timescale: Timescale::MICRO, } @@ -116,7 +111,6 @@ mod test { fn track_info_roundtrips_on_lite05() { let got = info_roundtrip(Version::Lite05, &info_sample()); assert_eq!(got.priority, 7); - assert!(!got.ordered); assert_eq!(got.max_age, Duration::from_millis(2000)); assert_eq!(got.timescale, Timescale::MICRO); } @@ -133,7 +127,6 @@ mod test { let info = crate::track::Info::default(); let info = TrackInfo { priority: info.priority, - ordered: info.ordered, max_age: info.max_age, timescale: info.timescale, }; diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 7882ceffc95..aab7092b82b 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -138,6 +138,19 @@ impl Version { } } + /// Whether this version's SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, and TRACK_INFO + /// carry the retired `Ordered` byte. + /// + /// The field is gone from the model: a publisher transmits newest-first within a + /// track, always. Deployed drafts still have the byte in their layout, so it is + /// written as 0 and ignored on read rather than shifting every field behind it. + pub fn has_group_order(self) -> bool { + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 => true, + Self::Lite06Wip => false, + } + } + /// Whether announcements carry the route cost: the marginal cost of pulling /// the broadcast via this route, accumulated per link. Added in lite-06. /// Older versions carry nothing, so a received route stays at zero and ranks diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 49e9b8e99c6..dea8c4ba644 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -712,11 +712,6 @@ impl Producer { self.state.read().timestamp } - /// Snapshot the content a subscriber would discard by skipping this group. - pub(crate) fn content(&self) -> stats::Content { - self.state.read().content() - } - /// The group's full cached footprint (payload plus fixed overhead), used by the /// track to size this group as an eviction victim. pub(crate) fn cache_size(&self) -> u64 { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index d2ae8d0ca55..3b8b12b6f5b 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -5027,130 +5027,6 @@ mod tests { ); } - /// `Subscriber::read_frame` collapses a group to its first frame. The paths it - /// delegates to (plain and spliced) build their own *unmetered* group consumers, - /// so the wrapper is the only place that can attribute the read: exactly one - /// group, one frame, and the payload bytes, counted once each. - #[tokio::test] - async fn test_stats_read_frame_counts_once() { - use crate::Timestamp; - use crate::stats::{Config, Registry, Tier}; - use bytes::Bytes; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Origin::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - let mut announced = egress.announced(); - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - let broadcast = announced.next().await.unwrap().broadcast.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // A single-frame group, read back through the collapsing helper. - producer - .write_frame(Timestamp::ZERO, Bytes::from_static(b"hello")) - .unwrap(); - - let frame = sub.read_frame().await.unwrap().expect("frame"); - assert_eq!(frame.payload.len(), 5); - settle().await; - - let report = registry.report(); - let entry = report - .traffic - .iter() - .find(|e| e.path.as_str() == "demo") - .expect("demo tracked"); - assert_eq!(entry.publisher.groups, 1, "one group, counted once"); - assert_eq!(entry.publisher.frames, 1, "one frame, counted once"); - assert_eq!( - entry.publisher.bytes, 5, - "payload counted once, not zero and not doubled" - ); - } - - /// A spliced `read_frame` holds its group internally while a partial frame fills. - /// If that group expires, its unread content still belongs to the logical - /// subscriber's stale counters even though the helper skips to the live edge. - #[tokio::test] - async fn test_stats_spliced_read_frame_counts_internal_expiry() { - use crate::Timestamp; - use crate::frame; - use crate::stats::{Config, Registry, Tier}; - use bytes::Bytes; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Origin::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - let mut announced = egress.announced(); - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - let broadcast = announced.next().await.unwrap().broadcast.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut subscriber = subscribing.await.unwrap(); - - let mut old = producer.append_group().unwrap(); - let mut writing = old - .create_frame(frame::Info { - size: 6, - timestamp: Timestamp::ZERO, - }) - .unwrap(); - writing.write(Bytes::from_static(b"old")).unwrap(); - - let pending = tokio::spawn(async move { subscriber.read_frame().await }); - tokio::task::yield_now().await; - assert!(!pending.is_finished(), "the partial frame should still be pending"); - - tokio::time::advance(Duration::from_secs(1)).await; - let mut edge = producer.append_group().unwrap(); - edge.write_frame(Timestamp::from_millis(1000).unwrap(), Bytes::from_static(b"edge")) - .unwrap(); - edge.finish().unwrap(); - - let frame = pending.await.unwrap().unwrap().expect("live edge frame"); - assert_eq!(frame.payload, Bytes::from_static(b"edge")); - writing.abort(crate::Error::Cancel).unwrap(); - settle().await; - - let report = registry.report(); - let traffic = &report - .traffic - .iter() - .find(|entry| entry.path.as_str() == "demo") - .expect("demo tracked") - .publisher; - assert_eq!(traffic.groups, 1, "only the live edge group was delivered"); - assert_eq!(traffic.frames, 1, "only the live edge frame was delivered"); - assert_eq!(traffic.bytes, 4, "only the live edge payload was delivered"); - assert_eq!(traffic.stale.groups, 0, "the internal group was never handed out"); - assert_eq!(traffic.stale.frames, 1, "the expired partial frame was discarded"); - assert_eq!(traffic.stale.bytes, 6, "the declared partial payload was discarded"); - } - /// Datagrams bypass the group/frame handles entirely, so they're metered at the /// producer (ingress write) and the subscriber (egress read). Each one counts as /// the single-frame group it stands in for, plus the `datagrams` breakout. diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 43d2ad98d7b..40a57111359 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -469,8 +469,6 @@ impl Consumer { min_sequence: 0, end_sequence: None, drift_cap: kio::Producer::new(None), - stale_stats: Default::default(), - reading: None, } } @@ -1234,11 +1232,6 @@ pub struct Subscriber { end_sequence: Option, /// Shared copy of [`Self::end_sequence`] for groups that outlive this cursor poll. drift_cap: kio::Producer>, - /// Logical subscriber meter for groups drained internally by [`Self::poll_read_frame`]. - stale_stats: crate::stats::Meter, - - /// The group currently being drained by [`Self::read_frame`]. - reading: Option, } impl Subscriber { @@ -1249,14 +1242,6 @@ impl Subscriber { self.reap(); } - /// Attribute expiry for the group this frame helper drains internally. - pub(crate) fn set_stale_meter(&mut self, meter: crate::stats::Meter) { - if let Some(reading) = &mut self.reading { - reading.set_stale_meter(meter.clone()); - } - self.stale_stats = meter; - } - /// Reap retired cursors, then bound the live stragglers: a pruned segment's /// cursor keeps draining (groups below its cap may still arrive out of /// order, and its demand keeps the upstream serving them), but only the @@ -1695,37 +1680,10 @@ impl Subscriber { } } - /// Poll for a single full frame from the next group in sequence order, - /// skipping the rest of the group. Intended for single-frame groups. - pub fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { - loop { - if let Some(group) = &mut self.reading { - match group.poll_read_frame(waiter) { - Poll::Ready(Ok(Some(frame))) => { - self.reading = None; - return Poll::Ready(Ok(Some(frame))); - } - // An empty or broken group is skipped like a gap. - Poll::Ready(_) => self.reading = None, - Poll::Pending => return Poll::Pending, - } - continue; - } - - match ready!(self.poll_next_group(waiter))? { - Some(mut group) => { - group.set_stale_meter(self.stale_stats.clone()); - self.reading = Some(group); - } - None => return Poll::Ready(Ok(None)), - } - } - } - - /// Read a single full frame from the next group in sequence order. + /// Return the next group with a higher sequence than any previously returned. #[cfg(test)] - pub async fn read_frame(&mut self) -> Result> { - kio::wait(|waiter| self.poll_read_frame(waiter)).await + pub async fn next_group(&mut self) -> Result> { + kio::wait(|waiter| self.poll_next_group(waiter)).await } /// Poll for the next datagram, from the newest segment only (datagrams are a @@ -2260,7 +2218,7 @@ mod test { } #[tokio::test] - async fn read_frame_across_segments() { + async fn next_group_across_segments() { let (mut track_a, consumer_a) = track_pair("a"); let (mut track_b, consumer_b) = track_pair("b"); @@ -2272,10 +2230,13 @@ mod test { producer.switch(&consumer_b, Position::group(1)).unwrap(); write_group(&mut track_b, 1, "b1"); - let frame = sub.read_frame().now_or_never().unwrap().unwrap().unwrap(); - assert_eq!(&frame.payload[..], b"a0"); - let frame = sub.read_frame().now_or_never().unwrap().unwrap().unwrap(); - assert_eq!(&frame.payload[..], b"b1"); + let mut read = |expected: &[u8]| { + let mut group = sub.next_group().now_or_never().unwrap().unwrap().unwrap(); + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(&frame.payload[..], expected); + }; + read(b"a0"); + read(b"b1"); } #[tokio::test] diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 4670f089812..79a9f897c49 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -11,10 +11,6 @@ use std::{task::Poll, time::Duration}; pub struct Subscription { /// Delivery priority. Higher values preempt lower ones when bandwidth is constrained. pub priority: u8, - /// Whether groups are prioritized in sequence order. Groups may always arrive - /// out-of-order (or not at all) over the network. Defaults to `false`; the - /// aggregate is ordered only when every live subscriber asks for it. - pub ordered: bool, /// How old a group may get before this subscriber gives up on it. /// /// [`Duration::ZERO`] (the default) skips immediately: group 8 arriving means group 7 @@ -83,7 +79,6 @@ impl Default for Subscription { fn default() -> Self { Self { priority: 0, - ordered: false, max_age: Duration::ZERO, start: None, end: None, @@ -98,13 +93,6 @@ impl Subscription { self } - /// Set whether groups are prioritized in sequence order, returning `self` for - /// chaining. Groups may always arrive out-of-order (or not at all) over the network. - pub fn with_ordered(mut self, ordered: bool) -> Self { - self.ordered = ordered; - self - } - /// Set how old a group may get before it is skipped, returning `self` for chaining. pub fn with_max_age(mut self, max_age: Duration) -> Self { self.max_age = max_age; @@ -142,7 +130,6 @@ impl Subscription { let merged = Subscription { priority: self.priority.max(combined.priority), // Sequence-first prioritization is enabled only when every subscriber wants it. - ordered: self.ordered && combined.ordered, max_age: self.max_age.max(combined.max_age), // Bounds fold as whole positions. Two subscribers starting in the same group // are separated only by their frame, so folding group and frame independently @@ -260,25 +247,6 @@ mod tests { combined } - #[test] - fn combined_ordered_stays_ordered_for_multiple_ordered_viewers() { - let subscription = Subscription::default().with_ordered(true); - - let combined = combine(&[subscription.clone(), subscription.clone(), subscription]).unwrap(); - - assert!(combined.ordered); - } - - #[test] - fn combined_any_unordered_viewer_disables_ordered() { - let unordered = Subscription::default().with_ordered(false); - let ordered = Subscription::default().with_ordered(true); - - let combined = combine(&[unordered, ordered]).unwrap(); - - assert!(!combined.ordered); - } - /// The exclusive representation runs out at both extremes, and `Option` says so /// rather than saturating into a bound that contradicts the request. #[test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index a47dac1f1ab..db4c3599532 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -14,7 +14,7 @@ //! The track is closed with [Error] when all writers or readers are dropped. use crate::{Error, Result, Timescale, Timestamp, coding}; -use crate::{broadcast, cache, frame, group, stats}; +use crate::{broadcast, cache, group, stats}; use super::{Datagram, Requests}; @@ -82,10 +82,6 @@ pub struct Info { /// The publisher's priority for this track, used only to break ties between /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). pub priority: u8, - /// Whether groups are prioritized in sequence order. Groups may always arrive - /// out-of-order (or not at all) over the network. Used only to break ties, - /// reported in TRACK_INFO (Lite05+), and defaults to `false` (newest-first). - pub ordered: bool, } impl Default for Info { @@ -94,7 +90,6 @@ impl Default for Info { timescale: Timescale::default(), max_age: DEFAULT_MAX_AGE, priority: 0, - ordered: false, } } } @@ -120,14 +115,6 @@ impl Info { self.priority = priority; self } - - /// Set whether groups are prioritized in sequence order, returning `self` for - /// chaining. Groups may always arrive out-of-order (or not at all) over the - /// network. Defaults to `false`. - pub fn with_ordered(mut self, ordered: bool) -> Self { - self.ordered = ordered; - self - } } #[derive(Default)] @@ -227,20 +214,6 @@ pub(crate) struct TrackState { fetch: kio::Shared, } -/// What a frame-level scan found, including content skipped on the way to either a -/// frame or the clean end of the track. -struct FrameScan { - hit: Option, - stale: stats::Content, -} - -/// A frame found by a frame-level scan and the cursor position it came from. -struct FrameHit { - frame: frame::Frame, - index: usize, - sequence: u64, -} - /// A cached group plus its bookkeeping in the track's `lookup` map. /// /// Access times and the evictable-population sample live in the group's own @@ -368,78 +341,6 @@ impl TrackState { } } - /// Scan groups at or after `index` in arrival order, looking for the first with sequence - /// `>= next_sequence` that has a fully-buffered next frame. Returns the frame plus the - /// winning slot's absolute index and sequence so the consumer can advance past it. - fn poll_read_frame( - &self, - index: usize, - next_sequence: u64, - drift: Drift, - waiter: &kio::Waiter, - ) -> Poll> { - let start = index.saturating_sub(self.offset); - let mut pending_seen = false; - // Groups the budget gave up on below the frame this returns. Counted only on the - // winning scan, whose cursor jumps past them, so a scan that ends Pending leaves - // them to be counted exactly once by the one that eventually succeeds. - let mut stale = stats::Content::default(); - for (i, (sequence, stamp)) in self.arrival.iter().enumerate().skip(start) { - if *sequence < next_sequence { - continue; - } - let Some(slot) = self.lookup.get(sequence) else { - continue; - }; - if slot.stamp != *stamp { - // A historical entry; the sequence was re-served by a newer - // incarnation, delivered (if at all) at its own arrival position. - continue; - } - // The drift budget bounds this the same as the group-level reads: a frame - // from a group the subscription has given up on is no fresher for being - // read one frame at a time. - if self.is_stale(*sequence, None, drift.edge, drift.budget) { - stale.add(slot.group.content()); - continue; - } - - let mut consumer = slot.group.consume(); - match consumer.poll_read_frame(waiter) { - Poll::Ready(Ok(Some(frame))) => { - return Poll::Ready(Ok(FrameScan { - hit: Some(FrameHit { - frame, - index: self.offset + i, - sequence: *sequence, - }), - stale, - })); - } - Poll::Ready(Ok(None)) => continue, - // A single group failing (aborted upstream, or evicted from the - // cache) doesn't poison the track; skip it like a gap. - Poll::Ready(Err(_)) => continue, - Poll::Pending => { - pending_seen = true; - continue; - } - } - } - - // A pending group can still produce a frame even after finish(). Finish only - // blocks new groups at/above final_sequence, not frames on existing groups. - if pending_seen { - Poll::Pending - } else if self.is_complete() { - Poll::Ready(Ok(FrameScan { hit: None, stale })) - } else if let Some(err) = &self.abort { - Poll::Ready(Err(err.clone())) - } else { - Poll::Pending - } - } - /// Find the smallest-sequence cached group satisfying /// `next_sequence <= seq <= end_sequence (if set)`. Used by /// [`Subscriber::next_group`] so the range can be widened (or unset) @@ -2998,51 +2899,24 @@ impl PlainSubscriber { }; self.datagram_index = found_index + 1; - self.next_sequence = self.next_sequence.max(datagram.sequence.saturating_add(1)); Poll::Ready(Ok(Some(datagram))) } fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { - let drift = ready!(self.poll_drift(waiter))?; - - loop { - let floor = self.next_sequence.max(self.min_sequence); - let Some(group) = ready!(self.poll(waiter, |state| state.poll_next_in_range(floor, self.end_sequence))?) - else { - return Poll::Ready(Ok(None)); - }; - // Advance before the budget check: a skipped group is consumed, not retried. - self.next_sequence = group.sequence.saturating_add(1); - if ready!(self.poll_stale(&group, drift, waiter))? { - self.stale.add(group.content()); - continue; - } - return Poll::Ready(Ok(Some(self.with_expiry(group)))); - } - } - - fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { - let drift = ready!(self.poll_drift(waiter))?; - let lower = self.min_sequence.max(self.next_sequence); - let scan = ready!(self.poll(waiter, |state| { - state.poll_read_frame(self.index, lower, drift, waiter) - })?); - self.stale.add(scan.stale); - let Some(hit) = scan.hit else { + let floor = self.next_sequence.max(self.min_sequence); + let Some(group) = ready!(self.poll(waiter, |state| state.poll_next_in_range(floor, self.end_sequence))?) else { return Poll::Ready(Ok(None)); }; - - self.index = hit.index + 1; - self.next_sequence = hit.sequence.saturating_add(1); - Poll::Ready(Ok(Some(hit.frame))) + self.next_sequence = group.sequence.saturating_add(1); + Poll::Ready(Ok(Some(self.with_expiry(group)))) } } /// A cloneable handle to a subscriber's delivery preferences. /// /// This updates the same subscription as the owning [`Subscriber`] without -/// borrowing its read cursor, so callers can change delivery priority, group -/// ordering priority, or group bounds while another task is waiting for groups. +/// borrowing its read cursor, so callers can change delivery priority, the max age +/// budget, or group bounds while another task is waiting for groups. #[derive(Clone)] pub struct SubscriberControl { subscription: kio::Producer, @@ -3153,8 +3027,8 @@ impl Subscriber { /// /// Returns each group it delivers exactly once, in the order it landed on the wire, /// which may be out of sequence due to network reordering or loss. Use - /// [`Self::poll_next_group`] if you only want groups whose sequence number is higher - /// than any previously returned. + /// [`Self::ordered`] if you only want groups whose sequence number is higher than any + /// previously returned. /// /// Groups are semi-reliable, and the [`Subscription::max_age`] budget is the other /// thing (alongside eviction and a moving start) that decides which of them arrive: @@ -3190,7 +3064,7 @@ impl Subscriber { /// Receive the next group in arrival order. /// /// Every group is returned exactly once, in the order it landed on the wire, which may - /// be out of sequence due to network reordering or loss. Use [`Self::next_group`] if you + /// be out of sequence due to network reordering or loss. Use [`Self::ordered`] if you /// only want groups whose sequence number is higher than any previously returned. /// See [`Self::poll_recv_group`] for how [`Self::start_at`] and [`Self::end_at`] apply. pub async fn recv_group(&mut self) -> Result> { @@ -3200,9 +3074,9 @@ impl Subscriber { /// Poll for the next datagram in arrival order, without blocking. /// /// Datagrams are a separate best-effort channel from groups (see - /// [`Producer::append_datagram`]); they share only the sequence namespace. A consumer - /// that falls too far behind silently loses the oldest datagrams. - /// Returning a datagram advances [`Self::poll_next_group`] past that sequence. + /// [`Producer::append_datagram`]); they share only the sequence namespace, and + /// neither cursor moves the other. A consumer that falls too far behind silently + /// loses the oldest datagrams. /// /// Returns `Poll::Ready(Ok(Some(datagram)))` when one is available, /// `Poll::Ready(Ok(None))` when the track is finished, `Poll::Ready(Err(e))` when the track @@ -3224,25 +3098,15 @@ impl Subscriber { /// Receive the next datagram in arrival order. /// /// A best-effort channel parallel to [`Self::recv_group`]; the two share only the sequence - /// namespace. To receive both concurrently from one subscriber, poll [`Self::poll_next_group`] - /// (or [`Self::poll_recv_group`]) and [`Self::poll_recv_datagram`] together in a single `poll` + /// namespace. To receive both concurrently from one subscriber, poll + /// [`Self::poll_recv_group`] and [`Self::poll_recv_datagram`] together in a single `poll` /// closure (sequential `&mut` borrows), rather than awaiting the two `recv` futures at once. pub async fn recv_datagram(&mut self) -> Result> { kio::wait(|waiter| self.poll_recv_datagram(waiter)).await } - /// Poll for the next group with a higher sequence number than any previously returned. - /// - /// Late arrivals (sequence at or below the last returned) are silently skipped, so this - /// produces a monotonically increasing sequence at the cost of dropping out-of-order - /// groups. Use [`Self::poll_recv_group`] to see every group in arrival order instead. - /// - /// The [`Subscription::max_age`] budget applies here too, on the same terms; see - /// [`Self::poll_recv_group`]. - /// - /// Honors the cap set by [`Self::end_at`]: groups with sequence past the cap are left - /// in the producer's cache and become eligible again if the cap is raised or removed. - pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + /// The sequence cursor behind [`Ordered`], which owns the only public door to it. + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { let meter = self.stats.meter(); let res = match &mut self.inner { SubscriberKind::Plain(plain) => plain.poll_next_group(waiter), @@ -3252,44 +3116,17 @@ impl Subscriber { res.map(|res| res.map(|group| group.map(|group| group.with_meter(meter)))) } - /// Return the next group with a higher sequence number than any previously returned. + /// Read this track's groups in sequence order instead of arrival order. /// - /// Late arrivals (sequence at or below the last returned) are silently skipped, so this - /// produces a monotonically increasing sequence at the cost of dropping out-of-order - /// groups. Use [`Self::recv_group`] to see every group in arrival order instead. - pub async fn next_group(&mut self) -> Result> { - kio::wait(|waiter| self.poll_next_group(waiter)).await - } - - /// A helper that calls [`Self::poll_next_group`] and returns its first frame - /// (timestamp and payload), skipping the rest of the group. Intended for - /// single-frame groups (see [`Producer::write_frame`]). - pub fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { - let meter = self.stats.meter(); - let res = match &mut self.inner { - SubscriberKind::Plain(plain) => plain.poll_read_frame(waiter), - SubscriberKind::Spliced(spliced) => { - spliced.set_stale_meter(meter.clone()); - spliced.poll_read_frame(waiter) - } - }; - self.count_stale(&meter); - // This helper collapses a group to its first frame: count the group, the one - // frame, and the bytes actually read. - if let Poll::Ready(Ok(Some(frame))) = &res { - meter.group(); - meter.frames(1); - meter.bytes(frame.payload.len() as u64); - } - res - } - - /// Read a single full frame (timestamp and payload) from the next group in - /// sequence order. + /// Consumes the subscriber, so one handle carries exactly one cursor: an + /// arrival-order [`Subscriber`] or a sequence-order [`Ordered`], never both at once. + /// The two advance independently, and interleaving them produces a group stream that + /// is neither, which is why the choice is a handle rather than a method. /// - /// See [`Self::poll_read_frame`] for semantics. - pub async fn read_frame(&mut self) -> Result> { - kio::wait(|waiter| self.poll_read_frame(waiter)).await + /// Datagrams stay on [`Subscriber`]: they are unordered by construction, so there is + /// nothing for a sequence cursor to do with them. + pub fn ordered(self) -> Ordered { + Ordered { inner: self } } /// Whether `other` was cloned from this subscriber (shares the same underlying state). @@ -3314,8 +3151,8 @@ impl Subscriber { /// /// Resolves as soon as the boundary is known, which may be ahead of the live edge /// when the producer finished via [`Producer::finish_at`]. This reports the declared - /// end, not that every group has arrived: drive [`Self::recv_group`] / - /// [`Self::next_group`] until they yield `None` to observe the track fully drained. + /// end, not that every group has arrived: drive [`Self::recv_group`] (or + /// [`Ordered::next_group`]) until it yields `None` to observe the track fully drained. pub async fn finished(&mut self) -> Result { kio::wait(|waiter| self.poll_finished(waiter)).await } @@ -3341,10 +3178,10 @@ impl Subscriber { /// A local filter, not a request; [`Subscription::end`] is the wire-level /// counterpart. See [Local cursor vs wire preference](Self#local-cursor-vs-wire-preference). /// - /// Affects [`Self::next_group`] and [`Self::recv_group`]: groups beyond the cap are - /// held rather than skipped past, so a later call to [`Self::end_at`] with a higher - /// value (or `None`) makes them available again. Lowering the cap below the - /// consumer's current cursor parks the consumer until the cap is raised. + /// Groups beyond the cap are held rather than skipped past, so a later call to + /// [`Self::end_at`] with a higher value (or `None`) makes them available again. + /// Lowering the cap below the consumer's current cursor parks the consumer until the + /// cap is raised. pub fn end_at(&mut self, sequence: impl Into>) { match &mut self.inner { SubscriberKind::Plain(plain) => { @@ -3385,6 +3222,125 @@ impl Subscriber { } } +/// A [`Subscriber`] that reads groups in sequence order. +/// +/// Created by [`Subscriber::ordered`], which consumes the subscriber, so a track is read +/// one way or the other and never both. Every group it returns has a higher sequence +/// than the last, so a late arrival (network reordering, or a gap the cache filled after +/// the fact) is skipped rather than delivered out of turn. +/// +/// # Age and skipping +/// +/// This cursor never discards a group it can already serve. A backlog is delivered as a +/// burst, in order, however old it is. [`Subscription::max_age`] instead bounds how long +/// a *handed-out* group may block: once newer content has pulled that far ahead, a read +/// that is still waiting on it ends with [`Error::Old`] and the cursor moves on. A gap +/// costs nothing either way, since the cursor seeks to the lowest cached group in range +/// rather than waiting for the sequence it would have read next. +/// +/// The budget is [`Subscription::max_age`], updatable mid-stream through +/// [`Self::control`]. [`Duration::ZERO`] (the default) gives up on a blocking group as +/// soon as anything newer exists. +pub struct Ordered { + inner: Subscriber, +} + +impl Ordered { + /// The track's [`Info`], resolved when the subscription was established. + pub fn info(&self) -> &Info { + self.inner.info() + } + + /// The track's name, unique within its broadcast. + pub fn name(&self) -> &str { + self.inner.name() + } + + /// The broadcast this track belongs to, as reached through the handle it came from. + pub fn broadcast(&self) -> &broadcast::Info { + self.inner.broadcast() + } + + /// Poll for the next group with a higher sequence number than any previously + /// returned, without blocking. + /// + /// Honors the floor set by [`Self::start_at`] and the cap set by [`Self::end_at`]: + /// a group past the cap stays in the producer's cache and becomes eligible again if + /// the cap rises or is removed. + /// + /// Returns `Poll::Ready(Ok(Some(group)))` when a group is available, + /// `Poll::Ready(Ok(None))` when the track is finished, + /// `Poll::Ready(Err(e))` when the track has been aborted, or + /// `Poll::Pending` when no group is available yet. + pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + self.inner.poll_next_group(waiter) + } + + /// Return the next group with a higher sequence number than any previously returned. + pub async fn next_group(&mut self) -> Result> { + kio::wait(|waiter| self.poll_next_group(waiter)).await + } + + /// Start this cursor at the given sequence. + /// + /// A local filter, not a request: the skipped groups are still delivered and simply + /// not returned. [`Subscription::start`], set via [`Self::update`], is what asks the + /// publisher to start there instead. + pub fn start_at(&mut self, sequence: u64) { + self.inner.start_at(sequence); + } + + /// Cap this cursor at the given sequence (inclusive), or remove the cap entirely. + /// + /// Accepts a bare `u64` (cap), `Some(u64)`, or `None` (uncap). A local filter, not a + /// request; [`Subscription::end`] is the wire-level counterpart. Groups past the cap + /// are held rather than skipped, so raising it later makes them available again. + pub fn end_at(&mut self, sequence: impl Into>) { + self.inner.end_at(sequence); + } + + /// Create a handle for updating this subscriber's delivery preferences without + /// borrowing the read cursor. + pub fn control(&self) -> SubscriberControl { + self.inner.control() + } + + /// This subscriber's current preferences. + pub fn subscription(&self) -> Subscription { + self.inner.subscription() + } + + /// Replace this subscriber's delivery preferences. + /// + /// Returns [`Error::Closed`] if the track already ended. + pub fn update(&mut self, subscription: Subscription) -> Result<()> { + self.inner.update(subscription) + } + + /// Poll for the track's declared final sequence, without blocking. + pub fn poll_finished(&mut self, waiter: &kio::Waiter) -> Poll> { + self.inner.poll_finished(waiter) + } + + /// Block until the track declares its end, returning the exclusive final sequence. + /// + /// See [`Subscriber::finished`]: this reports the declared end, not that every group + /// has arrived. + pub async fn finished(&mut self) -> Result { + kio::wait(|waiter| self.poll_finished(waiter)).await + } + + /// The latest sequence number in the track. + pub fn latest(&self) -> Option { + self.inner.latest() + } + + /// Whether `other` reads the same underlying track state. + pub fn is_clone(&self, other: &Self) -> bool { + self.inner.is_clone(&other.inner) + } +} + /// A subscriber asked for a track this broadcast doesn't have yet. /// /// Yielded by [`broadcast::Dynamic::requested_track`](crate::broadcast::Dynamic::requested_track), @@ -3595,6 +3551,7 @@ impl Subscriber { #[cfg(test)] mod test { use super::*; + use crate::frame; use crate::model::test_tracing::count_drop_warnings; use std::time::Duration; @@ -3751,10 +3708,13 @@ mod test { group.abort(Error::Cancel).unwrap(); } + /// Datagrams and groups are separate channels that share only a sequence namespace, + /// so consuming one must not move the other's cursor. #[tokio::test] - async fn recv_datagram_advances_ordered_group_cursor() { + async fn recv_datagram_leaves_the_ordered_cursor_alone() { let mut producer = track_producer("test", None); - let mut subscriber = producer.subscribe(None); + let mut datagrams = producer.subscribe(None); + let mut subscriber = producer.subscribe(None).ordered(); let ts = Timestamp::from_millis(5).unwrap(); producer @@ -3764,18 +3724,22 @@ mod test { payload: bytes::Bytes::from_static(b"x"), }) .unwrap(); - assert_eq!(recv_datagram(&mut subscriber).sequence, 5); + assert_eq!(recv_datagram(&mut datagrams).sequence, 5); producer.create_group(group::Info { sequence: 3 }).unwrap(); producer.create_group(group::Info { sequence: 6 }).unwrap(); - let group = subscriber - .next_group() - .now_or_never() - .expect("group would have blocked") - .expect("would have errored") - .expect("track was closed"); - assert_eq!(group.sequence, 6); + let mut next = || { + subscriber + .next_group() + .now_or_never() + .expect("group would have blocked") + .expect("would have errored") + .expect("track was closed") + .sequence + }; + assert_eq!(next(), 3, "the datagram at sequence 5 did not consume group 3"); + assert_eq!(next(), 6); } #[tokio::test] @@ -4631,32 +4595,6 @@ mod test { writing.abort(Error::Cancel).unwrap(); } - #[tokio::test] - async fn widening_latency_wakes_a_pending_frame_read() { - let mut producer = track_producer("test", None); - let mut subscriber = producer.subscribe(None); - let control = subscriber.control(); - - append_at(&mut producer, 0); - crate::model::clock::advance(Duration::from_secs(1)); - let _edge = producer.append_group().unwrap(); - - let pending = tokio::spawn(async move { subscriber.read_frame().await }); - tokio::task::yield_now().await; - assert!(!pending.is_finished(), "the real-time budget skips the old frame"); - - control - .update(Subscription::default().with_max_age(Duration::from_secs(2))) - .unwrap(); - - let frame = pending - .await - .unwrap() - .unwrap() - .expect("the wider budget admits the frame"); - assert_eq!(frame.payload, bytes::Bytes::from_static(b"x")); - } - #[test] fn max_age_bounds_the_budget() { // The publisher only keeps a group around for 500ms, so a subscriber asking to @@ -4692,19 +4630,27 @@ mod test { assert_eq!(drain(&mut patient), vec![0, 1, 2, 3]); } + /// The arrival cursor writes a backlog off; the ordered cursor does not. A group + /// that is already cached costs nothing to deliver, and dropping it would put a + /// hole in the sequence a decoder is reading. The budget bounds how long a + /// *blocking* group may stall, which is what group expiry enforces. #[test] - fn next_group_skips_stale_groups_too() { + fn next_group_bursts_a_stale_backlog() { let mut producer = track_producer("test", None); for second in 0..4 { append_at(&mut producer, second * 1000); } - // Sequence-ordered reads run the same budget: a relay serves in arrival order, - // but a decoder reading by sequence must not be handed a backlog either. - let mut subscriber = producer.subscribe(None); - let group = subscriber.next_group().now_or_never().unwrap().unwrap().unwrap(); - assert_eq!(group.sequence, 3); - assert!(subscriber.next_group().now_or_never().is_none()); + let mut subscriber = producer.subscribe(None).ordered(); + let mut seen = Vec::new(); + while let Some(Ok(Some(group))) = subscriber.next_group().now_or_never() { + seen.push(group.sequence); + } + assert_eq!(seen, vec![0, 1, 2, 3]); + + // The arrival cursor, which the relay forwarders use, still sheds it. + let mut arrival = producer.subscribe(None); + assert_eq!(drain(&mut arrival), vec![3]); } #[tokio::test] @@ -4731,25 +4677,6 @@ mod test { assert_eq!(group.sequence, 0); } - #[tokio::test] - async fn read_frame_honors_the_budget() { - let mut producer = track_producer("test", None); - for second in 0..4 { - append_at(&mut producer, second * 1000); - } - - // The frame-level helper is the group-level read with the group thrown away, so - // it gives up on a backlog on the same terms. Reading one frame at a time makes - // nothing fresher. - let mut subscriber = producer.subscribe(None); - let frame = subscriber.read_frame().await.unwrap().expect("a frame"); - assert_eq!(frame.timestamp, Timestamp::from_millis(3000).unwrap()); - assert!( - subscriber.read_frame().now_or_never().is_none(), - "the skipped groups are gone, not queued" - ); - } - /// A one-shot fetch populates the shared cache but never the live arrival cursor, /// so it cannot make content available to a subscription look stale. #[tokio::test] @@ -4778,16 +4705,6 @@ mod test { let mut groups = producer.subscribe(None); assert_eq!(groups.assert_group().sequence, 0); groups.assert_no_group(); - - let mut frames = producer.subscribe(None); - let frame = frames - .read_frame() - .now_or_never() - .expect("live frame is ready") - .unwrap() - .expect("live frame"); - assert_eq!(frame.timestamp.as_millis(), 0); - assert!(frames.read_frame().now_or_never().is_none()); } /// The live edge is resolved once per poll and applied to every group that poll @@ -4822,45 +4739,6 @@ mod test { ); } - #[tokio::test] - async fn read_frame_counts_what_it_skips() { - let mut producer = track_producer("test", None); - for second in 0..4 { - append_at(&mut producer, second * 1000); - } - - // A silent skip is indistinguishable from loss whichever read did it, so the - // frame-level path reports its drops like the group-level ones. - let mut subscriber = producer.subscribe(None); - subscriber.read_frame().await.unwrap().expect("a frame"); - let stale = subscriber.take_stale(); - assert_eq!(stale.groups, 3); - assert_eq!(stale.frames, 3); - } - - #[tokio::test] - async fn read_frame_counts_stale_groups_at_eof() { - let mut producer = track_producer("test", None); - append_at(&mut producer, 0); - append_at(&mut producer, 1000); - - // The live edge starts past frame zero, so the frame helper cannot read it. - // The two older groups are still stale and must be reported when the scan - // reaches the clean end without returning a frame. - let mut edge = producer.append_group().unwrap(); - edge.start_at(1).unwrap(); - edge.write_frame(Timestamp::from_millis(2000).unwrap(), b"edge".to_vec()) - .unwrap(); - edge.finish().unwrap(); - producer.finish().unwrap(); - - let mut subscriber = producer.subscribe(None); - assert!(subscriber.read_frame().await.unwrap().is_none()); - let stale = subscriber.take_stale(); - assert_eq!(stale.groups, 2); - assert_eq!(stale.frames, 2); - } - #[tokio::test] async fn a_lower_sequence_is_never_the_live_edge() { let mut producer = track_producer("test", None); @@ -4928,13 +4806,10 @@ mod test { let mut recv = Box::pin(subscriber.recv_group()); assert!(recv.as_mut().now_or_never().is_none()); - control - .update(Subscription::default().with_priority(7).with_ordered(false)) - .unwrap(); + control.update(Subscription::default().with_priority(7)).unwrap(); let aggregate = producer.subscription().expect("expected an active subscription"); assert_eq!(aggregate.priority, 7); - assert!(!aggregate.ordered); } #[test] @@ -5299,7 +5174,7 @@ mod test { #[tokio::test] async fn next_group_skips_late_arrivals() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(None).ordered(); // Seq 5 arrives first. producer.create_group(group::Info { sequence: 5 }).unwrap(); @@ -5336,7 +5211,7 @@ mod test { #[tokio::test] async fn next_group_returns_arrivals_in_order() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut consumer = producer.subscribe(replay()).ordered(); // Seq 3 arrives first, then seq 5. Both should be returned in arrival order. producer.create_group(group::Info { sequence: 3 }).unwrap(); @@ -5360,17 +5235,18 @@ mod test { } #[tokio::test] - async fn next_group_and_recv_group_use_independent_cursors() { + async fn ordered_and_arrival_cursors_are_independent() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut ordered = producer.subscribe(replay()).ordered(); + let mut arrival = producer.subscribe(replay()); // Out-of-order arrivals: seq 5 first, then seq 3. producer.create_group(group::Info { sequence: 5 }).unwrap(); producer.create_group(group::Info { sequence: 3 }).unwrap(); - // next_group is sequence-ordered: it returns the smallest sequence first, - // regardless of arrival order. - let group = consumer + // The ordered handle returns the smallest sequence first, regardless of + // arrival order. + let group = ordered .next_group() .now_or_never() .expect("should not block") @@ -5378,15 +5254,14 @@ mod test { .expect("track should not be closed"); assert_eq!(group.sequence, 3); - // recv_group is arrival-ordered and uses an independent cursor, so it - // still starts at the first arrival. - assert_eq!(consumer.assert_group().sequence, 5); + // The plain handle walks arrivals, so it still starts at seq 5. + assert_eq!(arrival.assert_group().sequence, 5); } #[tokio::test] async fn end_at_caps_next_group() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..6 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -5418,7 +5293,7 @@ mod test { #[tokio::test] async fn end_at_release_drains_cached_groups() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..6 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -5463,7 +5338,7 @@ mod test { #[tokio::test] async fn end_at_lower_than_cursor_parks_consumer() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..3 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -5507,7 +5382,7 @@ mod test { #[tokio::test] async fn end_at_toggling_around_late_arrivals() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); + let mut consumer = producer.subscribe(replay()).ordered(); consumer.end_at(5); @@ -5720,31 +5595,6 @@ mod test { assert!(matches!(fut.as_mut().poll(&mut cx), Poll::Ready(Ok(None)))); } - #[tokio::test] - async fn read_frame_returns_single_frame_per_group() { - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); - - producer.write_frame(Timestamp::ZERO, b"hello".as_slice()).unwrap(); - producer.write_frame(Timestamp::ZERO, b"world".as_slice()).unwrap(); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"hello"); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"world"); - } - #[test] fn write_frame_rejects_an_oversized_frame_before_appending_its_group() { let mut producer = track_producer("test", None); @@ -5757,162 +5607,6 @@ mod test { assert_eq!(producer.latest(), None, "the rejected frame did not publish a group"); } - #[tokio::test] - async fn read_frame_preserves_timestamp() { - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); - - producer - .write_frame(Timestamp::from_micros(20_000).unwrap(), b"hello".as_slice()) - .unwrap(); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(frame.timestamp.as_micros(), 20_000); - assert_eq!(&frame.payload[..], b"hello"); - } - - #[tokio::test] - async fn read_frame_skips_stalled_group_for_newer_ready_frame() { - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); - - // Seq 3: group open, no frame yet (stalled). - let _stalled = producer.create_group(group::Info { sequence: 3 }).unwrap(); - // Seq 5: fully-written group with a frame. - let mut g5 = producer.create_group(group::Info { sequence: 5 }).unwrap(); - g5.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"later")) - .unwrap(); - g5.finish().unwrap(); - - // read_frame should not block on the stalled seq 3. It returns seq 5's frame. - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block on stalled earlier group") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"later"); - } - - #[tokio::test] - async fn read_frame_discards_rest_of_multi_frame_group() { - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(replay()); - - // Group 0 has two frames; only the first is returned. - let mut g0 = producer.create_group(group::Info { sequence: 0 }).unwrap(); - g0.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"one")) - .unwrap(); - g0.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"two")) - .unwrap(); - g0.finish().unwrap(); - - // Group 1 is a normal single-frame group. - producer.write_frame(Timestamp::ZERO, b"next".as_slice()).unwrap(); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"one"); - - // The second frame of group 0 is discarded; the next read jumps to group 1. - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"next"); - } - - #[tokio::test] - async fn read_frame_waits_for_pending_group_after_finish() { - // finish() sets final_sequence, but groups already created with lower sequences - // can still produce frames. read_frame must not return None prematurely. - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); - - let mut g0 = producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.finish().unwrap(); - - // Track is finished but group 0 has no frame yet. It must block, not return None. - assert!( - consumer.read_frame().now_or_never().is_none(), - "read_frame must block on a pending group even after finish()" - ); - - // A late frame on the pending group is still delivered. - g0.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"late")) - .unwrap(); - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block once a frame is written") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"late"); - } - - #[tokio::test] - async fn read_frame_respects_start_at() { - // start_at sets min_sequence; read_frame must skip groups below it even though - // next_sequence is still 0. - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); - consumer.start_at(5); - - // Seq 3 has a frame but is below min_sequence, so it must be skipped. - let mut g3 = producer.create_group(group::Info { sequence: 3 }).unwrap(); - g3.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"skip-me")) - .unwrap(); - g3.finish().unwrap(); - - let mut g5 = producer.create_group(group::Info { sequence: 5 }).unwrap(); - g5.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"keep")) - .unwrap(); - g5.finish().unwrap(); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"keep"); - } - - #[tokio::test] - async fn read_frame_returns_none_when_finished() { - let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); - - producer.write_frame(Timestamp::ZERO, b"only".as_slice()).unwrap(); - producer.finish().unwrap(); - - let frame = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored") - .expect("track should not be closed"); - assert_eq!(&frame.payload[..], b"only"); - - let done = consumer - .read_frame() - .now_or_never() - .expect("should not block") - .expect("would have errored"); - assert!(done.is_none()); - } - #[test] fn append_group_returns_bounds_exceeded_on_sequence_overflow() { let mut producer = track_producer("test", None); diff --git a/rs/moq-relay/tests/goaway_cluster.rs b/rs/moq-relay/tests/goaway_cluster.rs index 482929ca185..8042d74a2f1 100644 --- a/rs/moq-relay/tests/goaway_cluster.rs +++ b/rs/moq-relay/tests/goaway_cluster.rs @@ -6,6 +6,7 @@ //! hands the live subscription over at a group boundary. A downstream consumer //! of the cluster origin observes contiguous groups and no unannounce. +use std::collections::BTreeSet; use std::net::TcpListener; use std::time::Duration; @@ -449,22 +450,20 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { ) .await .expect("broadcast announced"); - // Ordered, because the verification below asserts strict sequence order. - // A live (unordered) subscription transmits the newest group first, so a - // back-to-back burst legally arrives inverted; `ordered` is the protocol's - // way to ask every hop for sequence-order transmission instead. + // The age budget is what makes the completeness check below meaningful: this test + // asserts every group arrives exactly once, which is more than the default budget + // promises. A subscriber that wants completeness across a failover has to say how + // far behind the live edge it is willing to sit (clamped to what the publisher + // retains). // - // The latency budget is the other half of that ask: this test asserts every group - // arrives exactly once, which is more than the default REAL_TIME budget promises. - // A subscriber that wants completeness across a failover has to say how far behind - // the live edge it is willing to sit (clamped to what the publisher retains). + // Arrival order, not sequence order: a publisher transmits the newest group of a + // track first, so a back-to-back burst legally arrives inverted. What the failover + // must preserve is that every group arrives, exactly once, with its frames intact. let mut sub = within( "subscribe to the video track", - bc.track("video").expect("track handle").subscribe( - moq_net::track::Subscription::default() - .with_ordered(true) - .with_max_age(Duration::from_secs(60)), - ), + bc.track("video") + .expect("track handle") + .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(60))), ) .await .expect("subscribe"); @@ -479,7 +478,9 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { } g.finish().expect("finish"); - verify_group(&mut sub, 0, FRAMES_PER_GROUP, "pre-failover (via MID-A)").await; + let mut seen = BTreeSet::new(); + collect_group(&mut sub, &mut seen, FRAMES_PER_GROUP, "pre-failover (via MID-A)").await; + assert_eq!(seen, BTreeSet::from([0]), "group 0 must arrive before the failover"); // ── continuous publishing THROUGH the failover window ──────────────── // Groups 1..=LAST_GROUP stream at a steady cadence, with multiple frames @@ -516,9 +517,14 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { // ── completeness across the swap: every group exactly once, in order, // every frame intact, exact frame count (no loss, no duplicates) ────── - for seq in 1..=LAST_GROUP { - verify_group(&mut sub, seq, FRAMES_PER_GROUP, "across the failover window").await; + for _ in 1..=LAST_GROUP { + collect_group(&mut sub, &mut seen, FRAMES_PER_GROUP, "across the failover window").await; } + assert_eq!( + seen, + (0..=LAST_GROUP).collect::>(), + "every group must cross the failover exactly once" + ); let mut track = within("publisher task finishes", publisher) .await @@ -541,9 +547,14 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { } g.finish().expect("finish"); } - for seq in (LAST_GROUP + 1)..=POST_DRAIN_LAST { - verify_group(&mut sub, seq, FRAMES_PER_GROUP, "post-drain (MID-B leg only)").await; + for _ in (LAST_GROUP + 1)..=POST_DRAIN_LAST { + collect_group(&mut sub, &mut seen, FRAMES_PER_GROUP, "post-drain (MID-B leg only)").await; } + assert_eq!( + seen, + (0..=POST_DRAIN_LAST).collect::>(), + "the new leg alone must carry the rest, exactly once each" + ); // ── no GOAWAY cascade to the downstream subscriber ─────────────────── assert!( @@ -567,16 +578,22 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { assert!(churn.is_err(), "failover must not churn announces under the subscriber"); } -/// Receive the next group and assert its sequence, every frame's payload, and -/// the exact frame count. `stage` names the failover phase for diagnostics. -async fn verify_group(sub: &mut moq_net::track::Subscriber, expected_seq: u64, frames: u64, stage: &str) { - let mut group = within(&format!("recv group {expected_seq} {stage}"), sub.recv_group()) +/// Receive the next group, assert every frame's payload and the exact frame count +/// against the sequence it carries, and record that sequence in `seen`. +/// +/// Sequence order is deliberately not asserted: a publisher transmits the newest group +/// of a track first, so a back-to-back burst legally arrives inverted. Completeness is +/// what the failover owes, and `seen` is what the caller checks it against. +/// `stage` names the failover phase for diagnostics. +async fn collect_group(sub: &mut moq_net::track::Subscriber, seen: &mut BTreeSet, frames: u64, stage: &str) { + let mut group = within(&format!("recv a group {stage}"), sub.recv_group()) .await - .unwrap_or_else(|err| panic!("subscription errored at group {expected_seq} {stage}: {err}")) - .unwrap_or_else(|| panic!("track ended early at group {expected_seq} {stage}")); - assert_eq!( - group.sequence, expected_seq, - "groups must arrive exactly once, in order ({stage})" + .unwrap_or_else(|err| panic!("subscription errored {stage}: {err}")) + .unwrap_or_else(|| panic!("track ended early {stage}")); + let expected_seq = group.sequence; + assert!( + seen.insert(expected_seq), + "group {expected_seq} arrived twice ({stage})" ); for f in 0..frames { let frame = within(&format!("read frame {f} of group {expected_seq}"), group.read_frame()) diff --git a/rs/moq-rtmp/src/dial.rs b/rs/moq-rtmp/src/dial.rs index 3f4d5bf5647..9d89d69fc2d 100644 --- a/rs/moq-rtmp/src/dial.rs +++ b/rs/moq-rtmp/src/dial.rs @@ -580,11 +580,17 @@ mod tests { .expect("catalog track") .subscribe(None) .await - .expect("subscribe catalog"); - let frame = tokio::time::timeout(Duration::from_secs(5), catalog_track.read_frame()) + .expect("subscribe catalog") + .ordered(); + let mut group = tokio::time::timeout(Duration::from_secs(5), catalog_track.next_group()) .await .expect("catalog read timed out") .expect("catalog read") + .expect("a catalog group"); + let frame = group + .read_frame() + .await + .expect("catalog read") .expect("a catalog frame"); assert!(!frame.payload.is_empty(), "pulled broadcast should carry a catalog"); diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 8d973c98a9c..57da75696d7 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -1004,7 +1004,7 @@ mod tests { /// wire format (a full JSON object per frame, no compression). async fn read_frame(broadcast: &moq_net::broadcast::Consumer, name: &str) -> BTreeMap { let mut track = subscribe(broadcast, name).await; - let frame = track.read_frame().await.expect("ok").expect("frame"); + let frame = next_frame(&mut track).await; serde_json::from_slice(&frame.payload).expect("json parse") } @@ -1012,10 +1012,9 @@ mod tests { /// immediate first (often empty) frame at time zero, so a test that records /// traffic asynchronously reads the accumulated state rather than that stale one. async fn read_last_frame(broadcast: &moq_net::broadcast::Consumer, name: &str) -> BTreeMap { - use futures::FutureExt; let mut track = subscribe(broadcast, name).await; - let mut last = track.read_frame().await.expect("ok").expect("frame"); - while let Some(Ok(Some(frame))) = track.read_frame().now_or_never() { + let mut last = next_frame(&mut track).await; + while let Some(frame) = try_next_frame(&mut track) { last = frame; } serde_json::from_slice(&last.payload).expect("json parse") @@ -1023,17 +1022,32 @@ mod tests { async fn read_session_frame(broadcast: &moq_net::broadcast::Consumer, name: &str) -> BTreeMap { let mut track = subscribe(broadcast, name).await; - let frame = track.read_frame().await.expect("ok").expect("frame"); + let frame = next_frame(&mut track).await; serde_json::from_slice(&frame.payload).expect("json parse") } - async fn subscribe(broadcast: &moq_net::broadcast::Consumer, name: &str) -> track::Subscriber { + async fn subscribe(broadcast: &moq_net::broadcast::Consumer, name: &str) -> track::Ordered { broadcast .track(name) .expect("track") .subscribe(None) .await .expect("subscribe") + .ordered() + } + + /// The next group's first frame. Stats tracks are one frame per group, so this is + /// one published sample. + async fn next_frame(track: &mut track::Ordered) -> moq_net::frame::Frame { + let mut group = track.next_group().await.expect("ok").expect("group"); + group.read_frame().await.expect("ok").expect("frame") + } + + /// The same, without blocking: `None` once nothing more is buffered. + fn try_next_frame(track: &mut track::Ordered) -> Option { + use futures::FutureExt; + let mut group = track.next_group().now_or_never()?.expect("ok")?; + group.read_frame().now_or_never()?.expect("ok") } /// The advertised path normalizes a messy node suffix and drops an @@ -1217,8 +1231,8 @@ mod tests { .expect("logical track") .subscribe(None); drive_tick().await; - let mut sub = subscribing.await.expect("an idle tier's track is held open"); - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let mut sub = subscribing.await.expect("an idle tier's track is held open").ordered(); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert!(parsed.is_empty(), "an idle tier serves zeros, got {parsed:?}"); } @@ -1293,15 +1307,15 @@ mod tests { // Nothing has recorded on the rtmp tier: the track does not exist yet. let subscribing = broadcast.track("rtmp/publisher.json").expect("track").subscribe(None); drive_tick().await; - let mut sub = subscribing.await.expect("held open, not rejected"); - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let mut sub = subscribing.await.expect("held open, not rejected").ordered(); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert!(parsed.is_empty(), "an idle tier serves zeros"); // The tier records: the same subscription carries the data. let _rtmp = feed(producer.registry(), Tier::new("rtmp"), "foo/live", true, 1, 7).await; drive_tick().await; - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert_eq!(parsed.get("foo/live").expect("entry").bytes, 7); } @@ -1333,8 +1347,8 @@ mod tests { let subscribing = broadcast.track("webrtc/sessions.json").expect("track").subscribe(None); drive_tick().await; - let mut sub = subscribing.await.expect("held open, not rejected"); - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let mut sub = subscribing.await.expect("held open, not rejected").ordered(); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert!(parsed.is_empty()); } @@ -1376,8 +1390,11 @@ mod tests { drive_tick().await; // The queued subscription resolves and carries the tier's first data. - let mut sub = subscribing.await.expect("fulfilled by the tick's own creation"); - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let mut sub = subscribing + .await + .expect("fulfilled by the tick's own creation") + .ordered(); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert_eq!(parsed.get("foo/live").expect("entry").bytes, 7); } @@ -1459,8 +1476,8 @@ mod tests { // The tier records while the request is parked: the flush adopts it. let _rt = feed(producer.registry(), Tier::new("rt"), "foo/live", true, 1, 9).await; drive_tick().await; - let mut sub = subscribing.await.expect("adopted by the flush"); - let frame = sub.read_frame().await.expect("ok").expect("frame"); + let mut sub = subscribing.await.expect("adopted by the flush").ordered(); + let frame = next_frame(&mut sub).await; let parsed: BTreeMap = serde_json::from_slice(&frame.payload).expect("json"); assert_eq!(parsed.get("foo/live").expect("entry").bytes, 9); } diff --git a/rs/moq-transcode/src/feed.rs b/rs/moq-transcode/src/feed.rs index 5cf2c071788..ecd5b2b11f5 100644 --- a/rs/moq-transcode/src/feed.rs +++ b/rs/moq-transcode/src/feed.rs @@ -176,7 +176,7 @@ async fn decode(inner: &Inner, sender: &broadcast::Sender) -> Result<(), E // The feed serves whichever rungs are active, so there is no single // downstream subscription to mirror; live-edge defaults fit every rung. - let mut subscriber = inner.source.subscribe(None).await?; + let mut subscriber = inner.source.subscribe(None).await?.ordered(); while let Some(mut group) = subscriber.next_group().await? { // Sends only fail with zero receivers, which is fine: teardown aborts diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 04dc70d9541..e989aada09c 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -411,7 +411,7 @@ mod tests { Err(err) => panic!("rung track {name}: {err}"), } }; - subscribers.push((name, track.subscribe(None).await.unwrap())); + subscribers.push((name, track.subscribe(None).await.unwrap().ordered())); } // Every rung receives a complete group with all 5 source frames. @@ -479,7 +479,7 @@ mod tests { Err(err) => panic!("rung track {name}: {err}"), } }; - subscribers.push((name, track.subscribe(None).await.unwrap())); + subscribers.push((name, track.subscribe(None).await.unwrap().ordered())); } for (name, subscriber) in &mut subscribers { @@ -625,7 +625,13 @@ mod tests { // Subscribing to the rung starts the live loop, which mirrors source // group sequences 1:1. - let mut subscriber = consumer.track("video/120p").unwrap().subscribe(None).await.unwrap(); + let mut subscriber = consumer + .track("video/120p") + .unwrap() + .subscribe(None) + .await + .unwrap() + .ordered(); let mut group = subscriber.next_group().await.unwrap().unwrap(); assert!(group.sequence <= 1, "unexpected sequence {}", group.sequence); let payload = group.read_frame().await.unwrap().unwrap(); @@ -703,7 +709,13 @@ mod tests { assert!(!update.encoding, "encoding before anyone asked"); assert_eq!(rendition.frames(), 0); - let mut subscriber = consumer.track("video/120p").unwrap().subscribe(None).await.unwrap(); + let mut subscriber = consumer + .track("video/120p") + .unwrap() + .subscribe(None) + .await + .unwrap() + .ordered(); let update = active.next().await.unwrap(); assert_eq!(update.rendition.name(), "video/120p"); assert!(update.encoding); diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index aee09cd096b..76621d8bdd5 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -27,8 +27,8 @@ public final class BroadcastConsumer: Sendable { } /// Subscribe to a track by name, delivering raw frame payloads with no codec - /// or container parsing. `subscription` tunes delivery priority, group ordering priority, - /// and group range; omit for defaults. + /// or container parsing. `subscription` tunes delivery priority, group range, and + /// staleness; omit for defaults. public func subscribeTrack(name: String, subscription: Subscription? = nil) async throws -> TrackConsumer { TrackConsumer(try await ffi.subscribeTrack(name: name, subscription: subscription)) } diff --git a/swift/Sources/Moq/Dynamic.swift b/swift/Sources/Moq/Dynamic.swift index 3f648425b62..28a3f4284a8 100644 --- a/swift/Sources/Moq/Dynamic.swift +++ b/swift/Sources/Moq/Dynamic.swift @@ -16,7 +16,7 @@ public final class TrackRequest: Sendable { } /// Accept the request as a raw track. `info` fixes the track's timescale, - /// priority, ordering priority, and cache; omit for defaults. + /// priority, and cache; omit for defaults. public func accept(info: TrackInfo? = nil) throws -> TrackProducer { TrackProducer(try ffi.accept(info: info)) } diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index 83a6b77e837..4b5cbd43039 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -123,7 +123,7 @@ public final class TrackProducer: Sendable { } /// A read handle for this track (local pub/sub, no origin needed). - /// `subscription` tunes delivery priority, group ordering priority, and group range; omit for defaults. + /// `subscription` tunes delivery priority, group range, and staleness; omit for defaults. public func consume(subscription: Subscription? = nil) throws -> TrackConsumer { TrackConsumer(try ffi.consume(subscription: subscription)) } From 50fcd3bbd72dd20e391d6e2db43725c8a8ecbe73 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 27 Aug 2026 18:50:28 -0700 Subject: [PATCH 2/8] fix(net): measure a group's age from where its content ends `is_stale` judged a group that had not yet been handed out by its *first* frame timestamp. A group covering a long span was therefore convicted the moment it opened, even while its tail sat level with the live edge and every frame in it was unread: a group spanning 0..2000ms with the edge at 2000ms was dropped under a 500ms budget, which is exactly the group being filled. Measure the candidate by its newest frame instead, against the edge group's first. The comparison then reads as "where this group's content ends, versus where newer content begins", which is the age that was always intended. A group already handed out was already correct (measured at its reader's position, per `group::Position`), so only the hand-out check moves. Single-frame groups have first == latest and are unaffected, which is why the rest of the suite is untouched. This is the normative measure both ends apply, so `draft-lcurley-moq-lite`'s Expiration section and changelog change with it. Also give `track::Ordered` the datagram channel. Datagrams are unordered by construction and live on a separate cursor, so the choice of group order says nothing about them; withholding them only forced a track using both channels to subscribe twice. Co-Authored-By: Claude Opus 5 --- drafts/draft-lcurley-moq-lite.md | 8 +- js/net/src/group.ts | 1 + js/net/src/internal.ts | 4 + js/net/src/track.test.ts | 48 +++++++++++ js/net/src/track.ts | 31 ++++++- rs/moq-net/src/model/group.rs | 12 +++ rs/moq-net/src/model/subscription.rs | 9 ++- rs/moq-net/src/model/track.rs | 117 ++++++++++++++++++++++++--- 8 files changed, 214 insertions(+), 16 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index d9df5538ea3..cd5d485aba3 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -509,9 +509,14 @@ It is RECOMMENDED that an application set conservative limits and only resort to A group is never expired until at least the next group (by sequence number) has been received or queued. Once a newer group exists, the group's age is measured two ways, and it is expired once **either** measure exceeds the relevant `Max Age`: -- **Timestamp age**: the difference between this group's first frame timestamp and the first frame timestamp of the latest group that has at least one frame. This measure is consistent across relays and unaffected by buffering or jitter. +- **Timestamp age**: the difference between this group's *newest* frame timestamp and the *first* frame timestamp of the latest group that has at least one frame. This measure is consistent across relays and unaffected by buffering or jitter. - **Wall-clock age**: the difference between when this group's first byte arrived (subscriber) or was queued (publisher) and the same instant for the latest group. +Timestamp age is measured from where a group's content *ends* because that is what is still owed. +A group covering two seconds is not two seconds late when it opened two seconds ago; its tail is level with the live edge and every frame in it is unread. +Judging it by its first frame would expire exactly the group being filled. +A receiver that has already begun reading a group MAY substitute its own read position, which is never behind the group's start and so can only keep the group longer. + The two backstop each other: a publisher cannot keep stale groups alive with fresh-looking timestamps, and a burst of groups arriving together does not reset their age. A group that contains zero frames has no timestamp, so only the wall-clock age applies; this avoids stalling expiration on empty groups sent as keep-alives or gap markers. @@ -1353,6 +1358,7 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. +- Measure a group's timestamp age from its *newest* frame rather than its first, against the latest group's first frame. A group covering a long span is not late while its tail is level with the live edge, and judging it by its first frame expired exactly the group being filled. Single-frame groups, where the two coincide, are unaffected. - Removed `Subscriber Ordered` from SUBSCRIBE and SUBSCRIBE_UPDATE, and `Publisher Ordered` from TRACK_INFO and SUBSCRIBE_OK. Group order within a Track is now normatively newest-first, with no field to invert it: a subscriber that wants sequence order reads in sequence order, which costs the network nothing and does not let one subscriber's preference reach a Track a relay is fanning out to many. Note this removes a byte from the middle of each message, so a lite-06 peer cannot parse a lite-05 one's SUBSCRIBE (the earlier drafts keep the byte, and an implementation serving them SHOULD write 0 and ignore what it reads). ## moq-lite-05 diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 8c32066ecae..aa60d44e2e1 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -360,6 +360,7 @@ export class Consumer { static { makeConsumer = (state) => new Consumer(state); hooks.groupTimestamp = (group) => group.#state.timestamp; + hooks.groupLatest = (group) => group.#state.latest; hooks.expireGroup = (group, expiry) => { group.#expiry = expiry; }; diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 2a98d17c30a..3cfc50ef92a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -81,6 +81,7 @@ export const hooks: { ignoreLatency: (subscriber: Subscriber) => void; /** Return a group's first timestamp, retained even after its first frame is read. */ groupTimestamp: (group: GroupConsumer) => Timestamp | undefined; + groupLatest: (group: GroupConsumer) => Timestamp | undefined; /** Keep applying a subscription's drift policy after it hands a group out. */ expireGroup: ( group: GroupConsumer, @@ -108,6 +109,9 @@ export const hooks: { groupTimestamp: () => { throw new Error("group.ts not loaded"); }, + groupLatest: () => { + throw new Error("group.ts not loaded"); + }, expireGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 8d9d1c51d3e..b687b0b0601 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -229,6 +229,54 @@ test("nextGroup returns buffered groups in sequence", async () => { expect((await track.nextGroup())?.sequence).toBe(5); }); +// A group's age is where its content *ends*, not where it began. A long group whose tail +// is level with the live edge still owes the reader every frame in it, so judging it by +// its first timestamp would discard exactly the group being filled. +test("a long group is not stale while its tail reaches the edge", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 5000 }); + const sub = producer.subscribe({ maxAge: 500 }); + + // Group 0 spans 0..2000ms; group 1 starts at 2000ms, where group 0 ends. + const long = producer.appendGroup(); + for (const ms of [0, 500, 1000, 1500, 2000]) { + long.writeFrame({ payload: enc.encode(`${ms}`), timestamp: Timestamp.fromMillis(ms) }); + } + long.close(); + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(2000) }); + + expect((await sub.recvGroup())?.sequence).toBe(0); + expect((await sub.recvGroup())?.sequence).toBe(1); +}); + +test("a long group is stale once its tail falls behind", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 5000 }); + const sub = producer.subscribe({ maxAge: 500 }); + + const long = producer.appendGroup(); + for (const ms of [0, 500, 1000]) { + long.writeFrame({ payload: enc.encode(`${ms}`), timestamp: Timestamp.fromMillis(ms) }); + } + long.close(); + // The edge starts 2s past where group 0 ends, well beyond the budget. + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(3000) }); + + expect((await sub.recvGroup())?.sequence).toBe(1); +}); + +// Datagrams are unordered by construction, so the sequence cursor carries them too: a +// track using both channels needs one subscription, not two. +test("the ordered handle carries datagrams", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); + + producer.writeDatagram({ sequence: 5, timestamp: Timestamp.fromMillis(5), payload: enc.encode("x") }); + producer.writeGroup(new GroupProducer(3)); + + expect((await track.recvDatagram())?.sequence).toBe(5); + // The datagram did not consume the group cursor. + expect((await track.nextGroup())?.sequence).toBe(3); +}); + // The arrival cursor writes a backlog off; the ordered cursor does not. A group already // buffered costs nothing to deliver, and dropping it would put a hole in the sequence a // decoder is reading. The budget bounds how long a *blocking* group may stall instead. diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 3bef41a8a7e..3ba5ab87cfe 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -312,6 +312,7 @@ let ordered_: { readString(subscriber: Subscriber): Promise; readJson(subscriber: Subscriber): Promise; readBool(subscriber: Subscriber): Promise; + recvDatagram(subscriber: Subscriber): Promise; }; // Constructs a Subscriber from within this module without exposing a public @@ -752,7 +753,10 @@ export class Subscriber { drift.wall.sequence > group.sequence && (drift.budget === 0 || drift.wall.time - time > drift.budget); - const timestamp = at?.presentation ?? hooks.groupTimestamp(group); + // Where the group's unread content *ends*, not where the group began: a long group + // whose tail reaches the live edge still owes the reader every frame in it. One + // already handed out is measured at its reader's position instead. + const timestamp = at?.presentation ?? hooks.groupLatest(group); const presentationStale = drift.presentation !== undefined && drift.presentation.sequence > group.sequence && @@ -799,6 +803,8 @@ export class Subscriber { readString: (subscriber) => subscriber.#readString(), readJson: (subscriber) => subscriber.#readJson(), readBool: (subscriber) => subscriber.#readBool(), + // Unordered either way, so both handles reach the same cursor. + recvDatagram: (subscriber) => subscriber.#recvDatagram(), }; } @@ -955,6 +961,12 @@ export class Subscriber { */ async recvDatagram(): Promise { this.#live(); + return this.#recvDatagram(); + } + + // The datagram cursor, reachable from either handle: unordered by construction, so the + // choice of group order says nothing about it. + async #recvDatagram(): Promise { for (;;) { const datagrams = this.#state.datagrams.peek(); @@ -1129,8 +1141,8 @@ export class Subscriber { * hands the subscription to the returned {@link Ordered} and leaves this handle inert. * {@link recvGroup} and {@link recvDatagram} throw afterwards. * - * Datagrams stay on this handle by construction: they are unordered, so a sequence - * cursor has nothing to do with them. + * Datagrams come along: they are a separate cursor either way, so the choice of group + * order says nothing about them. */ ordered(): Ordered { if (this.#committed) throw new Error("track is already read in sequence order"); @@ -1260,4 +1272,17 @@ export class Ordered { readBool(): Promise { return ordered_.readBool(this.#subscriber); } + + /** + * Receive the next datagram in arrival order. + * + * Datagrams are a separate best-effort channel from groups (see + * {@link Producer.appendDatagram}); they share only the sequence namespace, and + * neither cursor moves the other. Unordered by construction, so this behaves + * identically on either handle; it is here so a track carrying both channels needs + * one subscription rather than two. + */ + recvDatagram(): Promise { + return ordered_.recvDatagram(this.#subscriber); + } } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index dea8c4ba644..7919ac24d12 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -712,6 +712,18 @@ impl Producer { self.state.read().timestamp } + /// Where the group ends in presentation time: its newest frame's timestamp, or + /// `None` while no frame has been opened. + /// + /// This is what a drift budget measures an untouched group against. A group is not + /// late because it *started* long ago: a two-second group whose tail is level with + /// the live edge still has content nobody has read. Only once its newest frame has + /// fallen behind is there nothing left worth delivering. Grows as the group does, so + /// a group still receiving frames stays fresh and a stalled one ages in place. + pub(crate) fn latest(&self) -> Option { + self.state.read().latest + } + /// The group's full cached footprint (payload plus fixed overhead), used by the /// track to size this group as an eviction victim. pub(crate) fn cache_size(&self) -> u64 { diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 79a9f897c49..b194b6a9047 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -39,9 +39,12 @@ pub struct Subscription { /// # How age is measured /// /// By both presentation time and wall-clock arrival, with either able to expire the - /// group. Presentation time compares a group's first timestamp against the newest - /// one above it, so a backlog delivered as a burst still reads as its true age. - /// Wall-clock backstops an empty or stalled group that has supplied no timestamp. + /// group. Presentation time compares where the group's unread content *ends* against + /// where the newest group above it begins, so a backlog delivered as a burst still + /// reads as its true age while a long group whose tail reaches the live edge does not. + /// A group already handed out is measured at its reader's position, so a reader that + /// keeps up is never convicted. Wall-clock backstops an empty or stalled group that + /// has supplied no timestamp. /// /// Protocols whose wire can't carry a timestamp (pre-Lite05 moq-lite, moq-transport /// without the Timestamp property) have their frames stamped on receipt, which makes diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index db4c3599532..6ef70b3ccf2 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -486,9 +486,12 @@ impl TrackState { /// Whether the group at `sequence` has drifted further behind `edge` than `budget` /// tolerates, so a subscriber should skip it rather than hand it over. /// - /// Presentation time distinguishes a backlog delivered as a burst from live content. - /// Wall-clock arrival time backstops it, including for an empty or stalled group that - /// has no first-frame timestamp. Either age exceeding the budget makes the group stale. + /// Presentation time distinguishes a backlog delivered as a burst from live content, + /// measured from where the group's *unread* content ends rather than where the group + /// began: a long group whose tail reaches the live edge still owes the reader + /// something. Wall-clock arrival time backstops it, including for an empty or stalled + /// group that has supplied no timestamp. Either age exceeding the budget makes the + /// group stale. /// /// The edge must sit strictly above the candidate. The live edge is never late /// against itself, and backfill or the tail of a rewound timeline can carry a high @@ -501,11 +504,13 @@ impl TrackState { return false; }; - // Where the candidate sits. A group nobody has started reading sits at its own - // start; one already handed out sits wherever its reader got to, so a reader - // that has kept up is not convicted by how long ago its group opened. + // Where the candidate sits. One already handed out sits wherever its reader got + // to; one nobody has read sits at its newest frame, since that is the last of the + // content still owed. Either way the measure is what the reader has yet to take, + // not when the group opened: a long group whose tail reaches the live edge is not + // late just because its first frame is old. let at = at.unwrap_or_default(); - let presentation = at.presentation.or_else(|| slot.group.timestamp()); + let presentation = at.presentation.or_else(|| slot.group.latest()); let arrived = at.activity.unwrap_or(slot.arrived); // The anchors were resolved under an earlier lock, so confirm each still names @@ -3123,8 +3128,8 @@ impl Subscriber { /// The two advance independently, and interleaving them produces a group stream that /// is neither, which is why the choice is a handle rather than a method. /// - /// Datagrams stay on [`Subscriber`]: they are unordered by construction, so there is - /// nothing for a sequence cursor to do with them. + /// Datagrams come along: they are a separate cursor either way, so the choice of group + /// order says nothing about them. pub fn ordered(self) -> Ordered { Ordered { inner: self } } @@ -3281,6 +3286,27 @@ impl Ordered { kio::wait(|waiter| self.poll_next_group(waiter)).await } + /// Poll for the next datagram in arrival order, without blocking. + /// + /// Datagrams are a separate best-effort channel from groups (see + /// [`Producer::append_datagram`]); they share only the sequence namespace, and neither + /// cursor moves the other. Unordered by construction, so this behaves identically on + /// either handle; it is here so a track carrying both channels needs one subscription + /// rather than two. + pub fn poll_recv_datagram(&mut self, waiter: &kio::Waiter) -> Poll>> { + self.inner.poll_recv_datagram(waiter) + } + + /// Receive the next datagram in arrival order. + /// + /// To read groups and datagrams concurrently from one handle, poll + /// [`Self::poll_next_group`] and [`Self::poll_recv_datagram`] together in a single + /// `poll` closure (sequential `&mut` borrows), rather than awaiting the two `recv` + /// futures at once. + pub async fn recv_datagram(&mut self) -> Result> { + kio::wait(|waiter| self.poll_recv_datagram(waiter)).await + } + /// Start this cursor at the given sequence. /// /// A local filter, not a request: the skipped groups are still delivered and simply @@ -4634,6 +4660,79 @@ mod test { /// that is already cached costs nothing to deliver, and dropping it would put a /// hole in the sequence a decoder is reading. The budget bounds how long a /// *blocking* group may stall, which is what group expiry enforces. + /// A group's age is where its content *ends*, not where it began. A long group whose + /// tail is level with the live edge still owes the reader every frame in it, so + /// judging it by its first timestamp would discard exactly the group being filled. + #[test] + fn a_long_group_is_not_stale_while_its_tail_reaches_the_edge() { + let mut producer = track_producer("test", None); + + // Group 0 spans 0..2000ms; group 1 starts at 2000ms, where group 0 ends. + let mut long = producer.append_group().unwrap(); + for ms in [0u64, 500, 1000, 1500, 2000] { + long.write_frame(Timestamp::from_millis(ms).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + } + long.finish().unwrap(); + append_at(&mut producer, 2000); + + // A budget far shorter than the group's own span still keeps it. + let mut sub = producer.subscribe(Subscription::default().with_max_age(Duration::from_millis(500))); + assert_eq!(drain(&mut sub), vec![0, 1]); + } + + /// The same group, once its tail has fallen behind, is stale like any other. + #[test] + fn a_long_group_is_stale_once_its_tail_falls_behind() { + let mut producer = track_producer("test", None); + + let mut long = producer.append_group().unwrap(); + for ms in [0u64, 500, 1000] { + long.write_frame(Timestamp::from_millis(ms).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + } + long.finish().unwrap(); + // The edge starts 2s past where group 0 ends, well beyond the budget. + append_at(&mut producer, 3000); + + let mut sub = producer.subscribe(Subscription::default().with_max_age(Duration::from_millis(500))); + assert_eq!(drain(&mut sub), vec![1]); + } + + /// Datagrams are unordered by construction, so the sequence cursor carries them too: + /// a track using both channels needs one subscription, not two. + #[tokio::test] + async fn ordered_carries_datagrams() { + let mut producer = track_producer("test", None); + let mut sub = producer.subscribe(None).ordered(); + + producer + .write_datagram(Datagram { + sequence: 5, + timestamp: Timestamp::from_millis(5).unwrap(), + payload: bytes::Bytes::from_static(b"x"), + }) + .unwrap(); + producer.create_group(group::Info { sequence: 3 }).unwrap(); + + let datagram = sub + .recv_datagram() + .now_or_never() + .expect("datagram would have blocked") + .expect("would have errored") + .expect("track was closed"); + assert_eq!(datagram.sequence, 5); + + // The datagram did not consume the group cursor. + let group = sub + .next_group() + .now_or_never() + .expect("group would have blocked") + .expect("would have errored") + .expect("track was closed"); + assert_eq!(group.sequence, 3); + } + #[test] fn next_group_bursts_a_stale_backlog() { let mut producer = track_producer("test", None); From 4f5fde13372699685432d667fd1660e224255a2a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:27:43 -0700 Subject: [PATCH 3/8] fix(net): expire a group only once it provably cannot overlap the budget Max age judged a group by where it *started*, so a group was convicted for being behind rather than for having nothing left to give. That is the wrong axis. Priority already transmits newer groups first, so an older group consumes only leftover capacity and closes the gap faster than the live edge advances: being behind is survivable, and a receiver that is behind converges without losing content. What cannot be recovered is a group with nothing left worth delivering. Measure a group by how far it could still *reach* instead: the first frame timestamp of its successor, since a group cannot present past where the next group begins. Its own frames prove nothing, because frame durations are not on the wire and a group's last timestamp is where that frame starts, not where the group ends. A group whose successor has not arrived is therefore never expired on timestamp age; the wall-clock measure still backstops it. Reach is an exclusive bound, so the comparison is `>=`: the freshest frame a group could still hold sits strictly below its reach, and an age equal to the budget already puts every frame in it past the budget. That also makes a zero budget fall out of the general rule, so `wall_stale` loses its `budget.is_zero()` special case. This retires all three competing measures at once: the original first-frame one, the reader-position preference from #2890 (a drained-but-open group measured as level with the edge, so nothing could convict a stall), and the newest-frame one from the previous commit (which had the same defect and hung a reader outright). `Edge` carries a suffix minimum over stamped groups, built in the scan `live_edge` already did, so walking a backlog stays linear rather than rescanning per candidate. It is `Clone` rather than `Copy` now, so `is_stale` and `poll_stale` take it by reference. Once `lookup` becomes a `BTreeMap` (it already is on main, via #3088) this collapses to a `range(sequence + 1..)` walk and the table goes away. Six tests move to the new semantics. The shape they share: a two-group track can never expire the older group on timestamp age, because its reach *is* the edge. Convicting it needs a group beyond the successor, which is what each test now sets up. Co-Authored-By: Claude Opus 5 --- drafts/draft-lcurley-moq-lite.md | 20 +++- js/net/src/ietf/publisher.test.ts | 8 ++ js/net/src/track.test.ts | 19 +++- js/net/src/track.ts | 73 +++++++++--- rs/moq-net/src/model/track.rs | 181 +++++++++++++++++++++--------- 5 files changed, 225 insertions(+), 76 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index cd5d485aba3..10f58d05921 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -509,13 +509,21 @@ It is RECOMMENDED that an application set conservative limits and only resort to A group is never expired until at least the next group (by sequence number) has been received or queued. Once a newer group exists, the group's age is measured two ways, and it is expired once **either** measure exceeds the relevant `Max Age`: -- **Timestamp age**: the difference between this group's *newest* frame timestamp and the *first* frame timestamp of the latest group that has at least one frame. This measure is consistent across relays and unaffected by buffering or jitter. +- **Timestamp age**: the difference between the *newest* frame timestamp of the latest group that has at least one frame, and this group's **reach**, defined below. This measure is consistent across relays and unaffected by buffering or jitter. - **Wall-clock age**: the difference between when this group's first byte arrived (subscriber) or was queued (publisher) and the same instant for the latest group. -Timestamp age is measured from where a group's content *ends* because that is what is still owed. -A group covering two seconds is not two seconds late when it opened two seconds ago; its tail is level with the live edge and every frame in it is unread. -Judging it by its first frame would expire exactly the group being filled. -A receiver that has already begun reading a group MAY substitute its own read position, which is never behind the group's start and so can only keep the group longer. +A group is expired only once it **provably cannot overlap the Max Age window**: every frame it could still present is older than the budget allows. +Being behind is not itself a reason to expire anything. +[Prioritization](#prioritization) already transmits newer groups first, so an older group consumes only whatever capacity is left over; it therefore closes the gap faster than the live edge advances, and a receiver that is behind can converge without losing content. +What cannot be recovered is a group with nothing left worth delivering, and that is what expiration removes. + +A group's **reach** is the first frame timestamp of the next group by sequence number, or unbounded when no later group has presented a frame. +A group cannot present past where its successor begins, so this is the furthest it could still reach. +Its own frames do not bound it: frame durations are not carried on the wire, so a group's last frame timestamp is where that frame *starts* presenting, not where the group ends. +A group whose successor has not arrived is therefore never expired on timestamp age, because nothing yet proves where it stops. + +Reach is an exclusive bound, so a timestamp age **equal** to Max Age already expires the group: the freshest frame it could still hold sits strictly below its reach, and is therefore strictly older than the budget. +A Max Age of zero follows from the same rule without a special case. The two backstop each other: a publisher cannot keep stale groups alive with fresh-looking timestamps, and a burst of groups arriving together does not reset their age. A group that contains zero frames has no timestamp, so only the wall-clock age applies; this avoids stalling expiration on empty groups sent as keep-alives or gap markers. @@ -1358,7 +1366,7 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. -- Measure a group's timestamp age from its *newest* frame rather than its first, against the latest group's first frame. A group covering a long span is not late while its tail is level with the live edge, and judging it by its first frame expired exactly the group being filled. Single-frame groups, where the two coincide, are unaffected. +- Redefined timestamp age so a group is expired only once it provably cannot overlap the Max Age window. Age is now measured from a group's *reach* (the first frame timestamp of its successor, which is the furthest it could still present) to the newest frame of the latest group, and an age equal to Max Age expires it, since reach is an exclusive bound. Previously age ran from the group's own first frame, which expired a group whose later frames were still well inside the budget. A group whose successor has not yet arrived is never expired on timestamp age, because frame durations are not on the wire and nothing else proves where it ends; the wall-clock measure still applies. - Removed `Subscriber Ordered` from SUBSCRIBE and SUBSCRIBE_UPDATE, and `Publisher Ordered` from TRACK_INFO and SUBSCRIBE_OK. Group order within a Track is now normatively newest-first, with no field to invert it: a subscriber that wants sequence order reads in sequence order, which costs the network nothing and does not let one subscriber's preference reach a Track a relay is fanning out to many. Note this removes a byte from the middle of each message, so a lite-06 peer cannot parse a lite-05 one's SUBSCRIBE (the earlier drafts keep the byte, and an implementation serving them SHOULD write 0 and ignore what it reads). ## moq-lite-05 diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 54a57e625e3..0fb9b51df08 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -177,6 +177,14 @@ test("a blocked group header is reset when the group expires", async () => { edge.close(); track.writeGroup(edge); + // A group beyond the edge, so group 0's reach (10s, where group 1 begins) is + // provably past the budget. A group is bounded by where its successor starts, so + // the successor alone never convicts it: nothing yet proves group 0 ends sooner. + const later = new GroupProducer(2); + later.writeFrame({ payload: new TextEncoder().encode("later"), timestamp: Timestamp.fromMillis(20_000) }); + later.close(); + track.writeGroup(later); + const resetBeforeRelease = await Promise.race([ streamReset.then(() => true), new Promise((resolve) => setTimeout(() => resolve(false), 500)), diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index b687b0b0601..fe047ee256d 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -248,7 +248,7 @@ test("a long group is not stale while its tail reaches the edge", async () => { expect((await sub.recvGroup())?.sequence).toBe(1); }); -test("a long group is stale once its tail falls behind", async () => { +test("a long group is stale once its successor falls behind", async () => { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); const sub = producer.subscribe({ maxAge: 500 }); @@ -257,10 +257,14 @@ test("a long group is stale once its tail falls behind", async () => { long.writeFrame({ payload: enc.encode(`${ms}`), timestamp: Timestamp.fromMillis(ms) }); } long.close(); - // The edge starts 2s past where group 0 ends, well beyond the budget. + // Group 0 reaches at most 3s (where group 1 starts), a second behind the 4s edge and + // so past the budget. A frame's duration is not on the wire, so group 0's own last + // timestamp proves nothing about where it ends; only group 1's start bounds it. producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(3000) }); + producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(4000) }); expect((await sub.recvGroup())?.sequence).toBe(1); + expect((await sub.recvGroup())?.sequence).toBe(2); }); // Datagrams are unordered by construction, so the sequence cursor carries them too: a @@ -318,6 +322,8 @@ test("latency budget admits groups within its presentation-time window", async ( producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } + // Group 0 reaches 1s, only 1s behind the 2s edge, so a 1.5s budget still admits it. + expect((await track.recvGroup())?.sequence).toBe(0); expect((await track.recvGroup())?.sequence).toBe(1); expect((await track.recvGroup())?.sequence).toBe(2); }); @@ -459,6 +465,9 @@ test("committing track info wakes a group newly outside the retention window", a const waiting = group.readFrame(); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + // A group beyond the edge, so group 0's reach (1s) is provably behind it: a group is + // bounded by where its successor begins, so the successor alone never convicts it. + producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); await settle(); producer.accept({ maxAge: 100 }); @@ -504,6 +513,9 @@ test("a guarded write keeps the position of the frame removed from the buffer", const guarded = hooks.guardGroup(group, operation, read.position); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + // A group beyond the edge, so group 0's reach (1s) is provably behind it: a group is + // bounded by where its successor begins, so the successor alone never convicts it. + producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); await expect(guarded).rejects.toThrow("latency budget"); read.complete(); release(); @@ -531,6 +543,9 @@ test("clean source closure stays provisional while a frame write can expire", as const edge = producer.appendGroup(); edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + // See above: a group is bounded by where its successor begins, so convicting group 0 + // needs a group beyond that successor. + producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); await expect(guarded).rejects.toThrow("latency budget"); expect(await closed).toBeInstanceOf(Error); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 3ba5ab87cfe..64be28cc77c 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -703,20 +703,35 @@ export class Subscriber { budget: number; wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; + suffix: { sequence: number; reach: number }[]; } { const { end } = this.#cursor.peek(); let wall: { sequence: number; time: number } | undefined; let presentation: { sequence: number; timestamp: Timestamp } | undefined; + const suffix: { sequence: number; reach: number }[] = []; for (const { group, time } of this.#state.timeline.values()) { if (end !== undefined && group.sequence > end) continue; if (group.closed.peek() instanceof Error) continue; if (!wall || group.sequence > wall.sequence) wall = { sequence: group.sequence, time }; const timestamp = hooks.groupTimestamp(group); - if (timestamp !== undefined && (!presentation || group.sequence > presentation.sequence)) { - presentation = { sequence: group.sequence, timestamp }; + if (timestamp !== undefined) { + // The table bounds a candidate's reach, so it wants where each group + // begins; the edge wants the newest content that exists, so it takes the + // newest group's latest frame. + suffix.push({ sequence: group.sequence, reach: timestamp.asMillis() }); + if (!presentation || group.sequence > presentation.sequence) { + presentation = { sequence: group.sequence, timestamp: hooks.groupLatest(group) ?? timestamp }; + } } } + // Turn it into a suffix minimum: each entry carries the earliest presentation time + // any group at or after that sequence begins at, so a backlog walk stays linear. + suffix.sort((a, b) => a.sequence - b.sequence); + for (let i = suffix.length - 2; i >= 0; i--) { + suffix[i].reach = Math.min(suffix[i].reach, suffix[i + 1].reach); + } + const requested = this.#state.update.peek()?.maxAge ?? 0; const retained = this.#state.info.peek()?.maxAge; return { @@ -727,20 +742,49 @@ export class Subscriber { : Number.POSITIVE_INFINITY, wall, presentation, + suffix, }; } - // `at` is where a handed-out group's reader stands. A group nobody has started - // reading sits at its own start, which is what selection measures; one already - // handed out sits wherever its reader got to, so a reader keeping pace is not - // convicted by how long ago its group opened. Measuring from the group's first - // frame instead makes a GOP one GOP-duration behind by construction. + // The furthest presentation time the group at `sequence` could still reach: where its + // nearest successor begins, or undefined when nothing follows it yet. An upper bound, + // deliberately: a frame's duration is not on the wire, so a group's own last timestamp + // says where it starts presenting, not where it ends. Only a successor's start proves + // the predecessor cannot run past it. + static #reach(suffix: { sequence: number; reach: number }[], sequence: number): number | undefined { + let lo = 0; + let hi = suffix.length; + while (lo < hi) { + const mid = (lo + hi) >> 1; + if (suffix[mid].sequence <= sequence) lo = mid + 1; + else hi = mid; + } + return suffix[lo]?.reach; + } + + // Whether the drift budget says to give up on `group`. + // + // Presentation time measures a group by how far it could still reach, not by how far + // behind it started. Being behind is survivable: priority transmits newer groups first, + // so a backlog bursts at whatever rate is left over and closes the gap faster than the + // live edge advances. A group is abandoned only once everything it could still present + // falls outside the budget. + // + // A group's reach is bounded by its nearest successor: it cannot present past where the + // next group begins. Its own frames say nothing, since a frame's duration is not on the + // wire. The bound is exclusive, so the comparison is `>=`: the freshest frame a group + // could still hold sits just below its reach, so an age equal to the budget already puts + // every frame in it strictly past the budget. A zero budget falls out for free. + // + // `at.activity` is where a handed-out group's reader last made progress, backstopping + // an empty group that has supplied no timestamp at all. #isStale( group: GroupConsumer, drift: { budget: number; wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; + suffix: { sequence: number; reach: number }[]; }, at?: GroupPosition, ): boolean { @@ -749,19 +793,14 @@ export class Subscriber { const time = at?.activity ?? candidate.time; const wallStale = - drift.wall !== undefined && - drift.wall.sequence > group.sequence && - (drift.budget === 0 || drift.wall.time - time > drift.budget); - - // Where the group's unread content *ends*, not where the group began: a long group - // whose tail reaches the live edge still owes the reader every frame in it. One - // already handed out is measured at its reader's position instead. - const timestamp = at?.presentation ?? hooks.groupLatest(group); + drift.wall !== undefined && drift.wall.sequence > group.sequence && drift.wall.time - time >= drift.budget; + + const reach = Subscriber.#reach(drift.suffix, group.sequence); const presentationStale = drift.presentation !== undefined && drift.presentation.sequence > group.sequence && - timestamp !== undefined && - drift.presentation.timestamp.asMillis() - timestamp.asMillis() > drift.budget; + reach !== undefined && + drift.presentation.timestamp.asMillis() - reach >= drift.budget; return wallStale || presentationStale; } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 6ef70b3ccf2..c52fb6b5947 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -455,6 +455,7 @@ impl TrackState { fn live_edge(&self, cap: Option) -> Option { let mut wall: Option = None; let mut presentation: Option = None; + let mut stamped: Vec<(u64, Timestamp)> = Vec::new(); for slot in self.lookup.values() { if !slot.visible { continue; @@ -470,33 +471,62 @@ impl TrackState { arrived: slot.arrived, }); } - if let Some(timestamp) = group.timestamp() - && presentation.is_none_or(|edge| group.sequence > edge.sequence) - { - presentation = Some(PresentationEdge { - sequence: group.sequence, - stamp: slot.stamp, - timestamp, - }); + if let Some(timestamp) = group.timestamp() { + // The suffix table bounds a candidate's reach, so it wants where each group + // *begins*; the edge wants the newest content that exists, so it takes the + // newest group's latest frame. + stamped.push((group.sequence, timestamp)); + if presentation.is_none_or(|edge| group.sequence > edge.sequence) { + presentation = Some(PresentationEdge { + sequence: group.sequence, + stamp: slot.stamp, + timestamp: group.latest().unwrap_or(timestamp), + }); + } } } - wall.map(|wall| Edge { wall, presentation }) + + // Turn the stamped groups into a suffix minimum: entry `i` carries the earliest + // presentation time any group at or after that sequence begins at. One backwards + // pass, so the whole poll still costs a single scan. + stamped.sort_unstable_by_key(|(sequence, _)| *sequence); + let mut min: Option = None; + for entry in stamped.iter_mut().rev() { + min = Some(min.map_or(entry.1, |seen: Timestamp| seen.min(entry.1))); + entry.1 = min.expect("just assigned"); + } + + wall.map(|wall| Edge { + wall, + presentation, + suffix: stamped.into(), + }) } /// Whether the group at `sequence` has drifted further behind `edge` than `budget` /// tolerates, so a subscriber should skip it rather than hand it over. /// - /// Presentation time distinguishes a backlog delivered as a burst from live content, - /// measured from where the group's *unread* content ends rather than where the group - /// began: a long group whose tail reaches the live edge still owes the reader - /// something. Wall-clock arrival time backstops it, including for an empty or stalled - /// group that has supplied no timestamp. Either age exceeding the budget makes the - /// group stale. + /// Presentation time measures a group by how far it could still *reach*, not by how far + /// behind it started. Being behind is survivable: priority transmits newer groups + /// first, so a backlog bursts at whatever rate is left over and closes the gap faster + /// than the live edge advances. What is not survivable is having nothing left worth + /// delivering, so a group is abandoned only once everything it could still present + /// falls outside the budget. + /// + /// A group's reach is bounded by its nearest successor: it cannot present past where + /// the next group begins. Its own frames say nothing, since a frame's duration is not + /// on the wire and its last timestamp is where that frame *starts*. Wall-clock arrival + /// backstops the whole thing for an empty group that has supplied no timestamp at all. + /// + /// The bound is exclusive, so the comparison is `>=` rather than `>`: the freshest frame + /// a group could still hold sits just *below* its reach, so an age equal to the budget + /// already puts every frame in it strictly past the budget. That also makes a zero + /// budget fall out for free instead of needing a special case. /// /// The edge must sit strictly above the candidate. The live edge is never late /// against itself, and backfill or the tail of a rewound timeline can carry a high /// timestamp on a low sequence without being an edge at all. - fn is_stale(&self, sequence: u64, at: Option, edge: Option, budget: Duration) -> bool { + fn is_stale(&self, sequence: u64, at: Option, edge: Option<&Edge>, budget: Duration) -> bool { let Some(edge) = edge else { return false; }; @@ -504,13 +534,9 @@ impl TrackState { return false; }; - // Where the candidate sits. One already handed out sits wherever its reader got - // to; one nobody has read sits at its newest frame, since that is the last of the - // content still owed. Either way the measure is what the reader has yet to take, - // not when the group opened: a long group whose tail reaches the live edge is not - // late just because its first frame is old. + // Where the candidate can still reach, which is a property of what follows it + // rather than of the reader or of the group's own frames. let at = at.unwrap_or_default(); - let presentation = at.presentation.or_else(|| slot.group.latest()); let arrived = at.activity.unwrap_or(slot.arrived); // The anchors were resolved under an earlier lock, so confirm each still names @@ -521,21 +547,21 @@ impl TrackState { .lookup .get(&edge.wall.sequence) .is_some_and(|live| live.stamp == edge.wall.stamp && !live.group.is_aborted()) - && (budget.is_zero() - || edge - .wall - .arrived - .checked_duration_since(arrived) - .is_some_and(|age| age > budget)); - - let presentation_stale = edge.presentation.is_some_and(|edge| { - edge.sequence > sequence + && edge + .wall + .arrived + .checked_duration_since(arrived) + .is_some_and(|age| age >= budget); + + let reach = edge.reach(sequence); + let presentation_stale = edge.presentation.is_some_and(|live_edge| { + live_edge.sequence > sequence && self .lookup - .get(&edge.sequence) - .is_some_and(|live| live.stamp == edge.stamp && !live.group.is_aborted()) - && presentation.is_some_and( - |timestamp| matches!(edge.timestamp.checked_sub(timestamp), Ok(age) if Duration::from(age) > budget), + .get(&live_edge.sequence) + .is_some_and(|live| live.stamp == live_edge.stamp && !live.group.is_aborted()) + && reach.is_some_and( + |reach| matches!(live_edge.timestamp.checked_sub(reach), Ok(age) if Duration::from(age) >= budget), ) }); @@ -2597,7 +2623,7 @@ enum SubscriberKind { /// One poll's view of how far this subscription may drift: the clamped budget and the /// live edge to measure a candidate group against. Resolved once, then applied to every /// group that poll considers. -#[derive(Clone, Copy)] +#[derive(Clone)] struct Drift { budget: Duration, edge: Option, @@ -2637,7 +2663,7 @@ impl group::Expiry for GroupExpiry { let budget = clamp_max_age(max_age, state.max_age_bound()); loop { let edge = state.live_edge(cap); - expired = state.is_stale(self.sequence, Some(at), edge, budget); + expired = state.is_stale(self.sequence, Some(at), edge.as_ref(), budget); if expired { break; } @@ -2657,6 +2683,7 @@ impl group::Expiry for GroupExpiry { } } let presentation_sequence = edge + .as_ref() .and_then(|edge| edge.presentation) .map_or(self.sequence, |edge| edge.sequence.max(self.sequence)); for slot in state.lookup.values() { @@ -2688,10 +2715,33 @@ impl group::Expiry for GroupExpiry { /// The group a poll's drift is measured against, identified well enough to tell it apart /// from whatever may occupy its sequence by the time a candidate is judged. -#[derive(Clone, Copy)] +#[derive(Clone)] struct Edge { wall: WallEdge, presentation: Option, + /// Every servable stamped group by sequence, paired with the minimum first-timestamp + /// at or after it. A candidate's reach is bounded by its successors: it cannot present + /// past where the next group begins, so `reach()` reads that bound off in one lookup + /// rather than rescanning, keeping a backlog walk linear. + /// + /// Sorted by sequence, so this is a suffix minimum. Once `lookup` becomes a `BTreeMap` + /// (it already is on main) this collapses to a `range(sequence + 1..)` walk and the + /// table goes away. + suffix: Arc<[(u64, Timestamp)]>, +} + +impl Edge { + /// The furthest presentation time the group at `sequence` could still reach: where its + /// nearest successor begins, or `None` when nothing follows it yet. + /// + /// An upper bound, deliberately. A frame's duration is not on the wire, so a group's + /// own last timestamp says where it *starts* presenting, not where it ends; only a + /// successor's start proves the predecessor cannot run past it. Overestimating keeps a + /// group longer, which is the safe direction: we abort only what is provably useless. + fn reach(&self, sequence: u64) -> Option { + let index = self.suffix.partition_point(|(seq, _)| *seq <= sequence); + self.suffix.get(index).map(|(_, timestamp)| *timestamp) + } } /// The newest servable group, including an empty group with no media timestamp. @@ -2711,6 +2761,10 @@ struct PresentationEdge { /// The slot incarnation this timestamp was read from, so an eviction or a re-served /// sequence between resolving the anchor and using it is detectable. stamp: u32, + /// The newest frame this group has presented, not its first. The candidate side of the + /// comparison is an upper bound on what a group could still reach, so the edge side has + /// to be the newest content that actually exists, or the two meet and nothing is ever + /// convicted. Only ever grows as the group fills. timestamp: Timestamp, } @@ -2807,9 +2861,14 @@ impl PlainSubscriber { /// Whether the drift budget says to skip `group`, against a [`Drift`] already resolved /// for this poll. - fn poll_stale(&self, group: &group::Consumer, drift: Drift, waiter: &kio::Waiter) -> Poll> { + fn poll_stale(&self, group: &group::Consumer, drift: &Drift, waiter: &kio::Waiter) -> Poll> { self.poll(waiter, move |state| { - Poll::Ready(Ok(state.is_stale(group.sequence, None, drift.edge, drift.budget))) + Poll::Ready(Ok(state.is_stale( + group.sequence, + None, + drift.edge.as_ref(), + drift.budget, + ))) }) } @@ -2888,7 +2947,7 @@ impl PlainSubscriber { // Drop a group the drift budget has given up on and keep scanning, so one // poll walks a whole backlog off rather than handing it out group by group. - if ready!(self.poll_stale(&consumer, drift, waiter))? { + if ready!(self.poll_stale(&consumer, &drift, waiter))? { self.stale.add(consumer.content()); continue; } @@ -3011,7 +3070,7 @@ impl Subscriber { return Poll::Ready(Ok(false)); }; let drift = ready!(plain.poll_drift(waiter))?; - let stale = ready!(plain.poll_stale(group, drift, waiter))?; + let stale = ready!(plain.poll_stale(group, &drift, waiter))?; if stale { plain.note_stale(group); } @@ -4330,7 +4389,9 @@ mod test { } // Two seconds of tolerance keeps the groups presenting within 2s of the live - // edge (2s, 3s, 4s) and drops the two below it. + // edge (2s, 3s, 4s) and drops the two below it. Group 1 reaches exactly 2s behind + // the edge, and the reach bound is exclusive, so every frame it could hold is + // already past the budget. let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(2))); assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } @@ -4346,7 +4407,7 @@ mod test { } let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_millis(1500))); - assert_eq!(drain(&mut subscriber), vec![2, 3]); + assert_eq!(drain(&mut subscriber), vec![1, 2, 3]); } #[tokio::test] @@ -4387,6 +4448,10 @@ mod test { assert!(matches!(result, Ok(None)), "the held group ends: {result:?}"); } + /// A first timestamp on a *newer* group can convict a held one, so the held reader has + /// to be woken by it. The conviction needs a group beyond the held one's successor: + /// a group is bounded by where its successor begins, so the successor itself never + /// proves it stale. #[tokio::test] async fn a_handed_out_group_wakes_when_a_newer_group_gets_its_first_timestamp() { let mut producer = track_producer("test", None); @@ -4395,15 +4460,20 @@ mod test { old.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"old")) .unwrap(); + // Group 1 bounds group 0's reach at 1s. + append_at(&mut producer, 1000); + let mut held = subscriber.recv_group().await.unwrap().expect("old group"); assert!(held.read_frame().await.unwrap().is_some()); + let mut live = producer.append_group().unwrap(); let pending = tokio::spawn(async move { held.read_frame().await }); tokio::task::yield_now().await; assert!(!pending.is_finished(), "the newer group has no timestamp yet"); + // 2s edge against group 0's 1s reach: a full second past the budget. live.write_frame( - Timestamp::from_millis(1000).unwrap(), + Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"live"), ) .unwrap(); @@ -4629,9 +4699,12 @@ mod test { let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_millis(500))); append_at(&mut producer, 0); append_at(&mut producer, 1000); + append_at(&mut producer, 2000); + // Group 0 reaches 1s, a full second behind the 2s edge, so the clamped 500ms + // budget drops it. An unclamped ten seconds would have kept it. let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(10))); - assert_eq!(drain(&mut subscriber), vec![1]); + assert_eq!(drain(&mut subscriber), vec![1, 2]); } #[test] @@ -4682,8 +4755,12 @@ mod test { } /// The same group, once its tail has fallen behind, is stale like any other. + /// The same long group, once its *successor* has itself fallen behind. A frame's + /// duration is not on the wire, so group 0's own last timestamp proves nothing about + /// where it ends; only group 1's start bounds it. Group 0 is convicted once that bound + /// is further behind the edge than the budget allows. #[test] - fn a_long_group_is_stale_once_its_tail_falls_behind() { + fn a_long_group_is_stale_once_its_successor_falls_behind() { let mut producer = track_producer("test", None); let mut long = producer.append_group().unwrap(); @@ -4692,11 +4769,13 @@ mod test { .unwrap(); } long.finish().unwrap(); - // The edge starts 2s past where group 0 ends, well beyond the budget. + // Group 0 reaches at most 3s (where group 1 starts), a full second behind the 4s + // edge and so past the budget. Group 1 reaches the edge itself and is kept. append_at(&mut producer, 3000); + append_at(&mut producer, 4000); let mut sub = producer.subscribe(Subscription::default().with_max_age(Duration::from_millis(500))); - assert_eq!(drain(&mut sub), vec![1]); + assert_eq!(drain(&mut sub), vec![1, 2]); } /// Datagrams are unordered by construction, so the sequence cursor carries them too: @@ -4822,7 +4901,7 @@ mod test { edge: state.live_edge(None), }; assert!( - state.is_stale(0, None, drift.edge, drift.budget), + state.is_stale(0, None, drift.edge.as_ref(), drift.budget), "stale against a live edge" ); drop(state); @@ -4833,7 +4912,7 @@ mod test { let state = producer.state.read(); assert!( - !state.is_stale(0, None, drift.edge, drift.budget), + !state.is_stale(0, None, drift.edge.as_ref(), drift.budget), "a vanished edge is no reason to drop what is left" ); } From c535fb9bf0d1199b6f265d62673a78f377683fdc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:48:32 -0700 Subject: [PATCH 4/8] fix(net): bound a group by its immediate successor, not a later rewind `live_edge` collapsed the stamped groups into a suffix minimum, so a candidate's reach became the earliest timestamp among *all* later groups rather than where its own successor begins. Timestamps need not rise with sequence: a rewind can put a much earlier timestamp on a much later group. With starts of 10s, 1s and 2s on sequences 1, 2 and 3, group 0's reach resolved to 1s instead of its successor's 10s, so a 500ms budget discarded a group that could still hold frames through nearly 10s. A minimum shrinks the bound, which is the unsafe direction: the bound exists to prove a group has nothing left worth delivering, and only its immediate successor proves anything about where it ends. A later group starting earlier says nothing at all. The draft already specified the next group by sequence number; the code disagreed with it. Dropping the suffix pass is a simplification: sorting by sequence already puts the immediate successor one lookup away. Co-Authored-By: Claude Opus 5 --- js/net/src/track.ts | 11 ++++--- rs/moq-net/src/model/track.rs | 54 ++++++++++++++++++++++++----------- 2 files changed, 43 insertions(+), 22 deletions(-) diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 64be28cc77c..12928fcb5be 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -725,12 +725,11 @@ export class Subscriber { } } - // Turn it into a suffix minimum: each entry carries the earliest presentation time - // any group at or after that sequence begins at, so a backlog walk stays linear. + // Sequence order, so a candidate's immediate successor is one lookup away. + // Deliberately not a minimum over later groups: timestamps need not rise with + // sequence, and taking the minimum would shrink the bound, which is the unsafe + // direction. Only the immediate successor bounds a group. suffix.sort((a, b) => a.sequence - b.sequence); - for (let i = suffix.length - 2; i >= 0; i--) { - suffix[i].reach = Math.min(suffix[i].reach, suffix[i + 1].reach); - } const requested = this.#state.update.peek()?.maxAge ?? 0; const retained = this.#state.info.peek()?.maxAge; @@ -747,7 +746,7 @@ export class Subscriber { } // The furthest presentation time the group at `sequence` could still reach: where its - // nearest successor begins, or undefined when nothing follows it yet. An upper bound, + // immediate successor begins, or undefined when nothing follows it yet. An upper bound, // deliberately: a frame's duration is not on the wire, so a group's own last timestamp // says where it starts presenting, not where it ends. Only a successor's start proves // the predecessor cannot run past it. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c52fb6b5947..2a547313e02 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -486,15 +486,8 @@ impl TrackState { } } - // Turn the stamped groups into a suffix minimum: entry `i` carries the earliest - // presentation time any group at or after that sequence begins at. One backwards - // pass, so the whole poll still costs a single scan. + // Sequence order, so a candidate's immediate successor is one lookup away. stamped.sort_unstable_by_key(|(sequence, _)| *sequence); - let mut min: Option = None; - for entry in stamped.iter_mut().rev() { - min = Some(min.map_or(entry.1, |seen: Timestamp| seen.min(entry.1))); - entry.1 = min.expect("just assigned"); - } wall.map(|wall| Edge { wall, @@ -2719,20 +2712,24 @@ impl group::Expiry for GroupExpiry { struct Edge { wall: WallEdge, presentation: Option, - /// Every servable stamped group by sequence, paired with the minimum first-timestamp - /// at or after it. A candidate's reach is bounded by its successors: it cannot present - /// past where the next group begins, so `reach()` reads that bound off in one lookup - /// rather than rescanning, keeping a backlog walk linear. + /// Every servable stamped group, sorted by sequence, paired with its own first frame + /// timestamp. A candidate's reach is where its immediate successor begins, so `reach()` + /// finds that one entry rather than rescanning, keeping a backlog walk linear. + /// + /// Deliberately *not* a minimum over later groups. Timestamps need not rise with + /// sequence (a rewind reorders them), and a distant group starting earlier proves + /// nothing about where the candidate's own successor begins. Taking the minimum would + /// shrink the bound, which is the unsafe direction: it discards content that might + /// still be inside the budget. Only the immediate successor bounds a group. /// - /// Sorted by sequence, so this is a suffix minimum. Once `lookup` becomes a `BTreeMap` - /// (it already is on main) this collapses to a `range(sequence + 1..)` walk and the - /// table goes away. + /// Once `lookup` becomes a `BTreeMap` (it already is on main) this collapses to a + /// `range(sequence + 1..).next()` and the table goes away. suffix: Arc<[(u64, Timestamp)]>, } impl Edge { /// The furthest presentation time the group at `sequence` could still reach: where its - /// nearest successor begins, or `None` when nothing follows it yet. + /// immediate successor begins, or `None` when nothing follows it yet. /// /// An upper bound, deliberately. A frame's duration is not on the wire, so a group's /// own last timestamp says where it *starts* presenting, not where it ends; only a @@ -4778,6 +4775,31 @@ mod test { assert_eq!(drain(&mut sub), vec![1, 2]); } + /// Reach is the *immediate* successor's start, never a minimum across later groups. + /// Timestamps need not rise with sequence: a rewind can put a much earlier timestamp on + /// a much later group, and that group proves nothing about where the candidate's own + /// successor begins. Taking the minimum would shrink the bound and discard content that + /// is still well inside the budget. + #[test] + fn reach_follows_the_immediate_successor_not_a_later_rewind() { + let mut producer = track_producer("test", None); + + // Group 0 is bounded by group 1 at 10s. Groups 2 and 3 rewind to 1s and 2s. + append_at(&mut producer, 0); + append_at(&mut producer, 10_000); + append_at(&mut producer, 1_000); + append_at(&mut producer, 2_000); + + // Group 0 reaches 10s, so nothing here proves it is past a 500ms budget: it could + // hold frames through nearly 10s. A minimum over later groups would put its reach + // at 1s and drop it. + let mut sub = producer.subscribe(Subscription::default().with_max_age(Duration::from_millis(500))); + assert!( + drain(&mut sub).contains(&0), + "group 0 is bounded by its successor at 10s, not by a later rewind" + ); + } + /// Datagrams are unordered by construction, so the sequence cursor carries them too: /// a track using both channels needs one subscription, not two. #[tokio::test] From dae5cc6d137e7ba8ab7eefb9bc15e87e511e4d2e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 16:39:32 -0700 Subject: [PATCH 5/8] fix(net): honor the ordered burst contract on spliced tracks, and commit cursors on first read The spliced subscriber's sequence path filtered the arrival path, which prunes by max age, so the same Ordered handle burst a backlog on a plain track and discarded it across a takeover. Each segment now drives its own sequence cursor with one group staged per segment, and the lowest sequence across segments is delivered next. js/net's Subscriber never committed on an arrival read, so recvGroup() then ordered() interleaved both cursors on one buffer. The first group read now commits the track: the other order throws. moq-ffi grows the matching Uncommitted state, refuses mixing with Unsupported instead of converting after arrival reads, and dispatches datagrams through either handle without committing. moq-transcode's shared decode feed returns to arrival order so its drift budget keeps dropping what falls behind the live edge instead of bursting the backlog through the codecs. Also reconciles the dev merge: the reader-position expiry plumbing dev carried (group::Position.presentation) is deleted since the reach rule retired that measure, and the group bench's sequence arm drives track::Ordered. Co-Authored-By: Claude Fable 5 --- doc/lib/kt/moq.md | 1 - doc/lib/swift/moq.md | 1 - js/net/src/track.test.ts | 40 ++++++ js/net/src/track.ts | 25 ++-- py/moq-rs/README.md | 1 - rs/moq-ffi/src/consumer.rs | 66 +++++++--- rs/moq-ffi/src/test.rs | 61 +++++++++ rs/moq-net/benches/group.rs | 2 +- rs/moq-net/src/model/frame.rs | 3 - rs/moq-net/src/model/group.rs | 32 +---- rs/moq-net/src/model/resume.rs | 228 +++++++++++++++++++++++++++++++-- rs/moq-net/src/model/track.rs | 3 +- rs/moq-transcode/src/feed.rs | 8 +- 13 files changed, 395 insertions(+), 76 deletions(-) diff --git a/doc/lib/kt/moq.md b/doc/lib/kt/moq.md index 0f2f65a7de8..0df92144647 100644 --- a/doc/lib/kt/moq.md +++ b/doc/lib/kt/moq.md @@ -113,7 +113,6 @@ val info = track.info() track.update(Subscription(priority = 20u.toUByte())) ``` - A catalog rendition may name a *different* broadcast: `MoqVideo.broadcast` / `MoqAudio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. `subscribeMedia`, `subscribeTrack`, `fetchGroup`, and `fetchMediaGroup` take a track name rather than a rendition, so resolve first: ```kotlin diff --git a/doc/lib/swift/moq.md b/doc/lib/swift/moq.md index d77de219d7f..dc584688521 100644 --- a/doc/lib/swift/moq.md +++ b/doc/lib/swift/moq.md @@ -126,7 +126,6 @@ let info = try track.info() track.update(subscription: Subscription(priority: 20)) ``` - A catalog rendition may name a *different* broadcast: `Video.broadcast` / `Audio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index fe047ee256d..b677f0f04e6 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -924,6 +924,46 @@ test("the ordered and arrival cursors are independent", async () => { expect((await arrival.recvGroup())?.sequence).toBe(5); }); +// Both cursors draw from one buffer, so interleaving them produces a stream in neither +// order. The first group read commits the subscription; the other order is refused. +test("the first group read commits the cursor and refuses the other order", async () => { + const producer = new TrackProducer("test"); + + // An arrival read commits to arrival order; ordered() is refused afterwards. + const arrival = producer.subscribe({ maxAge: 5000 }); + producer.writeGroup(new GroupProducer(5)); + expect((await arrival.recvGroup())?.sequence).toBe(5); + expect(() => arrival.ordered()).toThrow("arrival order"); + + // The commitment refuses the other cursor without poisoning this one: a late + // lower sequence still flows in arrival order. + producer.writeGroup(new GroupProducer(3)); + expect((await arrival.recvGroup())?.sequence).toBe(3); + + // The other direction: ordered() takes the subscription and arrival reads throw. + const inert = producer.subscribe({ maxAge: 5000 }); + const ordered = inert.ordered(); + expect(inert.recvGroup()).rejects.toThrow("sequence order"); + expect(() => inert.ordered()).toThrow("sequence order"); + expect((await ordered.nextGroup())?.sequence).toBe(3); + expect((await ordered.nextGroup())?.sequence).toBe(5); +}); + +// Datagrams are a separate cursor on either handle, so reading them must not commit +// the subscription to a group order. +test("recvDatagram does not commit the group cursor", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 5000 }); + + producer.writeDatagram({ sequence: 0, timestamp: Timestamp.fromMillis(0), payload: enc.encode("x") }); + expect((await track.recvDatagram())?.sequence).toBe(0); + + // Still uncommitted: the subscription can go sequence-ordered. + const ordered = track.ordered(); + producer.writeGroup(new GroupProducer(1)); + expect((await ordered.nextGroup())?.sequence).toBe(1); +}); + test("nextGroup returns undefined when track closes", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe().ordered(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 12928fcb5be..534740ba1fb 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -695,9 +695,11 @@ export class Subscriber { #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); #enforceLatency = true; - // Set by {@link ordered}: both cursors draw from one buffer, so the handle that - // wins is the only one allowed to read from here on. - #committed = false; + // Which cursor owns this subscription. Both cursors draw from one buffer, so the + // first group read commits the track to arrival order and {@link ordered} commits + // it to sequence order; whichever wins is the only one allowed from here on. + // Datagrams are a separate cursor and never commit. + #mode?: "arrival" | "ordered"; #drift(): { budget: number; @@ -846,9 +848,9 @@ export class Subscriber { }; } - // Refuse an arrival-order read once `ordered()` has taken the subscription. + // Refuse a read on this handle once `ordered()` has taken the subscription. #live() { - if (this.#committed) throw new Error("track is read in sequence order; use the Ordered handle"); + if (this.#mode === "ordered") throw new Error("track is read in sequence order; use the Ordered handle"); } /** @@ -930,9 +932,12 @@ export class Subscriber { * than this subscriber's `maxAge` is skipped. The default of zero takes the live edge. * The budget remains attached after return, so a pending frame read rejects if a stalled * group becomes stale while newer data advances. + * + * The first call commits this track to arrival order: {@link ordered} throws afterwards. */ async recvGroup(): Promise { this.#live(); + this.#mode = "arrival"; for (;;) { const recv = this.#tryRecvGroup(); switch (recv.kind) { @@ -1177,14 +1182,16 @@ export class Subscriber { * * Both cursors draw from the same buffer, so a track is read one way or the other: this * hands the subscription to the returned {@link Ordered} and leaves this handle inert. - * {@link recvGroup} and {@link recvDatagram} throw afterwards. + * {@link recvGroup} and {@link recvDatagram} throw afterwards. Throws once a + * {@link recvGroup} call has already committed the track to arrival order. * * Datagrams come along: they are a separate cursor either way, so the choice of group - * order says nothing about them. + * order says nothing about them, and reading them commits nothing. */ ordered(): Ordered { - if (this.#committed) throw new Error("track is already read in sequence order"); - this.#committed = true; + if (this.#mode === "ordered") throw new Error("track is already read in sequence order"); + if (this.#mode === "arrival") throw new Error("track is already read in arrival order"); + this.#mode = "ordered"; return makeOrdered(this); } diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index c0da5b764d8..e8dfb9be2be 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -207,7 +207,6 @@ All consumers (`CatalogConsumer`, `MediaConsumer`, `TrackConsumer`, `AudioConsum - **`Dimensions`**. `.width: int`, `.height: int`. - **`Container`**. The catalog container enum, carried on each `Video`/`Audio` record. - ### Logging and errors - **`log_level(level="info")`**. Initialize logging for the underlying Rust layer (`"error"`, `"warn"`, `"info"`, `"debug"`, `"trace"`). Call once per process. diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 023a9af439f..02d2c1660c0 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -366,10 +366,16 @@ fn map_fetch_error(err: moq_net::Error) -> MoqError { /// A track subscription reading one way or the other. /// /// `moq_net` makes the choice a handle you consume the subscriber into, which a foreign -/// binding can't express in its type system, so the handle commits on first use instead: -/// whichever cursor a caller reaches for first is the one this track keeps. +/// binding can't express in its type system, so the handle commits on the first group +/// read instead: whichever group cursor a caller reaches for first is the one this +/// track keeps, and reaching for the other afterwards is [`MoqError::Unsupported`]. +/// Datagrams are a separate cursor on either handle, so reading them never commits. enum Cursor { + /// No group read has happened yet; the track can still commit either way. + Uncommitted(moq_net::track::Subscriber), + /// Committed to arrival order by the first `recv_group`. Arrival(moq_net::track::Subscriber), + /// Committed to sequence order by the first `next_group` or `read_frame`. Ordered(moq_net::track::Ordered), /// Transient, while the subscriber is moved out to be converted. Converting, @@ -380,28 +386,35 @@ struct TrackInner { } impl TrackInner { - /// The arrival cursor, or [`MoqError::Unsupported`] once this track committed to - /// sequence order. + /// The arrival cursor, committing this track to it, or [`MoqError::Unsupported`] + /// once it committed to sequence order. fn arrival(&mut self) -> Result<&mut moq_net::track::Subscriber, MoqError> { + if let Cursor::Uncommitted(_) = &self.track { + let Cursor::Uncommitted(track) = std::mem::replace(&mut self.track, Cursor::Converting) else { + unreachable!("just matched Uncommitted"); + }; + self.track = Cursor::Arrival(track); + } match &mut self.track { Cursor::Arrival(track) => Ok(track), _ => Err(MoqError::Unsupported), } } - /// The sequence cursor, committing this track to it on first use. - fn ordered(&mut self) -> &mut moq_net::track::Ordered { + /// The sequence cursor, committing this track to it, or [`MoqError::Unsupported`] + /// once it committed to arrival order. + fn ordered(&mut self) -> Result<&mut moq_net::track::Ordered, MoqError> { // Only move the subscriber out when there is one to convert: `ordered()` consumes // it, and swapping unconditionally would drop an already-converted handle. - if matches!(self.track, Cursor::Arrival(_)) { - let Cursor::Arrival(track) = std::mem::replace(&mut self.track, Cursor::Converting) else { - unreachable!("just matched Arrival"); + if let Cursor::Uncommitted(_) = &self.track { + let Cursor::Uncommitted(track) = std::mem::replace(&mut self.track, Cursor::Converting) else { + unreachable!("just matched Uncommitted"); }; self.track = Cursor::Ordered(track.ordered()); } match &mut self.track { - Cursor::Ordered(track) => track, - _ => unreachable!("converted above"), + Cursor::Ordered(track) => Ok(track), + _ => Err(MoqError::Unsupported), } } @@ -410,18 +423,25 @@ impl TrackInner { } async fn next_group(&mut self) -> Result, MoqError> { - Ok(self.ordered().next_group().await?) + Ok(self.ordered()?.next_group().await?) } async fn read_frame(&mut self) -> Result, MoqError> { - let Some(mut group) = self.ordered().next_group().await? else { + let Some(mut group) = self.ordered()?.next_group().await? else { return Ok(None); }; group.read_frame().await?.map(raw_frame).transpose() } async fn recv_datagram(&mut self) -> Result, MoqError> { - let Some(datagram) = self.arrival()?.recv_datagram().await? else { + // Datagrams are unordered on either handle; reading them never commits the + // group cursor. + let datagram = match &mut self.track { + Cursor::Uncommitted(track) | Cursor::Arrival(track) => track.recv_datagram().await?, + Cursor::Ordered(track) => track.recv_datagram().await?, + Cursor::Converting => return Err(MoqError::Unsupported), + }; + let Some(datagram) = datagram else { return Ok(None); }; let timestamp_us = datagram @@ -450,7 +470,7 @@ impl MoqTrackConsumer { let info = track.info().clone(); Self { task: Task::new(TrackInner { - track: Cursor::Arrival(track), + track: Cursor::Uncommitted(track), }), control, info, @@ -464,6 +484,10 @@ impl MoqTrackConsumer { /// /// Groups are returned as they arrive on the wire, which may be out of sequence /// order (e.g. if a later group lands before an earlier one on a separate stream). + /// + /// The first call commits this track to arrival order: sequence-order reads + /// ([`Self::next_group`], [`Self::read_frame`]) fail with + /// [`MoqError::Unsupported`] afterwards. pub async fn recv_group(&self) -> Result>, MoqError> { self.task .run(|mut state| async move { @@ -477,8 +501,11 @@ impl MoqTrackConsumer { .await } - /// Return the next group in sequence order, skipping forward if the reader - /// has fallen behind. Returns `None` when the track ends. + /// Return the next group with a higher sequence number than any previously + /// returned, skipping late arrivals. Returns `None` when the track ends. + /// + /// The first call commits this track to sequence order: arrival-order reads + /// ([`Self::recv_group`]) fail with [`MoqError::Unsupported`] afterwards. pub async fn next_group(&self) -> Result>, MoqError> { self.task .run(|mut state| async move { @@ -495,7 +522,8 @@ impl MoqTrackConsumer { /// Read the first frame of the next group, including its timestamp. /// /// Convenience for tracks using one-frame-per-group (like moq-boy's - /// status/command tracks). Returns `None` when the track ends. + /// status/command tracks). Returns `None` when the track ends. Reads in + /// sequence order, committing the track like [`Self::next_group`]. pub async fn read_frame(&self) -> Result, MoqError> { self.task.run(|mut state| async move { state.read_frame().await }).await } @@ -504,6 +532,8 @@ impl MoqTrackConsumer { /// /// Returns `None` when the track ends. Datagram delivery is unavailable over /// IETF moq-transport, pre-lite-05 moq-lite, and stream-only transports. + /// Datagrams are a separate cursor from groups, so this works alongside either + /// group order and never commits the track to one. pub async fn recv_datagram(&self) -> Result, MoqError> { self.task .run(|mut state| async move { state.recv_datagram().await }) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index f3167d3cbb7..0e64b83e99b 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1855,6 +1855,67 @@ async fn raw_track_next_group_is_repeatable() { assert!(matches!(consumer.recv_group().await, Err(MoqError::Unsupported))); } +/// The first group read commits the cursor either way: mixing arrival and sequence +/// reads on one track is refused rather than silently interleaving two cursors. +/// Datagrams are a separate cursor, so they flow regardless of the commitment. +#[tokio::test] +async fn raw_track_group_order_commits_on_first_read() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("commands".into(), None).unwrap(); + let consumer = broadcast + .consume() + .unwrap() + .subscribe_track("commands".into(), None) + .await + .unwrap(); + + track + .write_frame(MoqFrame { + payload: b"one".to_vec(), + timestamp_us: 0, + }) + .unwrap(); + + // An arrival read commits the track to arrival order. + let group = tokio::time::timeout(TIMEOUT, consumer.recv_group()) + .await + .expect("timed out waiting for a group") + .unwrap() + .expect("expected a group"); + assert_eq!(group.sequence(), 0); + assert!(matches!(consumer.next_group().await, Err(MoqError::Unsupported))); + assert!(matches!(consumer.read_frame().await, Err(MoqError::Unsupported))); + + // The commitment refuses the other cursor without poisoning this one. + track + .write_frame(MoqFrame { + payload: b"two".to_vec(), + timestamp_us: 0, + }) + .unwrap(); + let group = tokio::time::timeout(TIMEOUT, consumer.recv_group()) + .await + .expect("timed out waiting for a group") + .unwrap() + .expect("expected a group"); + assert_eq!(group.sequence(), 1); + + // Datagrams never commit and keep working after a commitment. + let sequence = track + .append_datagram(MoqFrame { + payload: b"beep".to_vec(), + timestamp_us: 0, + }) + .unwrap(); + let datagram = tokio::time::timeout(TIMEOUT, consumer.recv_datagram()) + .await + .expect("timed out waiting for a datagram") + .unwrap() + .expect("expected a datagram"); + assert_eq!(datagram.sequence, sequence); + assert_eq!(datagram.payload, b"beep".to_vec()); +} + #[tokio::test] async fn dynamic_broadcast_request_can_reject() { let origin = MoqOriginProducer::new(MoqOriginOptions::default()); diff --git a/rs/moq-net/benches/group.rs b/rs/moq-net/benches/group.rs index ea9bd3c2a27..125d405824d 100644 --- a/rs/moq-net/benches/group.rs +++ b/rs/moq-net/benches/group.rs @@ -244,7 +244,7 @@ fn bench_track_recv(c: &mut Criterion) { b.iter_batched( || { let ctx = filled_track(n, &payload); - let subscriber = ctx.track.subscribe(replay()); + let subscriber = ctx.track.subscribe(replay()).ordered(); (ctx, subscriber) }, |(ctx, mut subscriber)| { diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 93c52b54dd0..ca35d4f5fa9 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -603,10 +603,7 @@ impl Consumer { let Some(expiry) = &self.expiry else { return false; }; - // A half-read payload sits at its own frame's presentation time, not at the - // start of the group that carries it. let at = group::Position { - presentation: Some(self.info.timestamp), activity: self.state.read().activity, }; if !expiry.policy.is_expired(waiter, at) { diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 488d88e7d15..b1fe428b436 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -250,25 +250,14 @@ impl GroupState { } /// Record where the group starts and currently ends in presentation time, plus - /// when it last produced. `timestamp` is the first frame only; the rest track - /// every frame, so a reader that has caught up can be measured where it sits. + /// when it last produced. `timestamp` keeps the first frame only; `latest` and + /// `activity` follow every frame. fn stamp(&mut self, timestamp: Timestamp) { self.timestamp.get_or_insert(timestamp); self.latest = Some(timestamp); self.activity = Some(crate::model::clock::now()); } - /// Where a cursor at `index` sits in presentation time: the next frame it would - /// read, or the newest frame in the group once it has taken them all. - /// - /// `None` only while the group has presented nothing at all. - fn position(&self, index: usize) -> Option { - self.frames - .get(index.saturating_sub(self.offset)) - .map(|frame| frame.timestamp) - .or(self.latest) - } - /// Evict completed frames from the front until within the byte budget. fn evict(&mut self) { while self.cache > MAX_GROUP_CACHE { @@ -1224,12 +1213,8 @@ impl Consumer { self.expired } - /// Where this cursor sits, for a drift budget to measure it against the live edge. - /// - /// A group is not late because it *started* long ago. What is late is the content - /// its reader has yet to take, so a reader that has drained a group sits at the - /// group's newest frame, not its first. Measuring from the first would make every - /// group one group-duration behind by construction. + /// When this cursor's group last produced, for a drift budget to age it against + /// the live edge instead of when the group first arrived. pub(crate) fn position(&self) -> Position { match &self.inner { ConsumerKind::Plain(plain) => plain.position(), @@ -1479,24 +1464,19 @@ impl Consumer { } } -/// Where a group cursor sits in presentation and wall-clock time. +/// When a group cursor last saw producer activity. /// -/// `None` fields mean the group has presented nothing (an empty or stalled group), +/// `None` means the group has presented nothing (an empty or stalled group), /// where the track falls back to when the group arrived. #[derive(Clone, Copy, Default)] pub(crate) struct Position { - pub(crate) presentation: Option, pub(crate) activity: Option, } impl Plain { fn position(&self) -> Position { - // The prefetch batch was drained under an earlier lock, so the cursor's real - // position is past it. - let index = self.index.saturating_add(self.prefetch.buffered().0 as usize); let state = self.state.read(); Position { - presentation: state.position(index), activity: state.activity, } } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 40a57111359..36c1f5c39b1 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1132,6 +1132,12 @@ struct SegmentSub { /// the lowest is re-offered first; holding them here (rather than blocking on /// the first) keeps in-range groups that arrive behind a capped one flowing. parked: BTreeMap, + /// The next group this segment's sequence cursor would deliver, held so the + /// spliced sequence path ([`Subscriber::poll_next_group`]) can pick the lowest + /// across segments without consuming more than one group per segment ahead. + /// The cursor behind it is monotonic, so a staged group past the subscriber's + /// cap also correctly stalls everything after it in this segment. + staged: Option, } impl SegmentSub { @@ -1179,7 +1185,9 @@ impl SegmentSub { /// replaced before producing, so it holds nothing. The straggler bound in /// `reap` cuts what lingers too long, parked group and all. fn retired(&self) -> bool { - self.pruned && (self.end.is_none() || (matches!(self.sub, SubState::Done(_)) && self.parked.is_empty())) + self.pruned + && (self.end.is_none() + || (matches!(self.sub, SubState::Done(_)) && self.parked.is_empty() && self.staged.is_none())) } } @@ -1268,6 +1276,7 @@ impl Subscriber { seg.sub = SubState::Done(None); seg.terminal = None; seg.parked.clear(); + seg.staged = None; cut -= 1; } } @@ -1391,6 +1400,7 @@ impl Subscriber { terminal: None, pruned: false, parked: BTreeMap::new(), + staged: None, }); } } @@ -1521,6 +1531,55 @@ impl Subscriber { } } + /// Drive one segment's sequence cursor: resolve a pending subscription, then poll + /// for the next in-sequence group. Out-of-bounds groups (a route racing its cap) are + /// skipped. Unlike [`Self::poll_segment`], groups are never discarded for age: the + /// spliced sequence path inherits the [`track::Ordered`] contract of bursting a + /// backlog instead of skipping it. + fn poll_segment_ordered( + seg: &mut SegmentSub, + prefs: &Subscription, + min_sequence: u64, + end_sequence: Option, + waiter: &kio::Waiter, + ) -> Poll> { + loop { + match &mut seg.sub { + SubState::Pending(_) => { + ready!(Self::poll_activate(seg, prefs, min_sequence, end_sequence, waiter)); + } + SubState::Active(sub) => match sub.poll_next_group(waiter) { + Poll::Ready(Ok(Some(group))) => { + // The floor is enforced by the caller; enforce the segment + // boundary here since the inner cursor is deliberately uncapped. + if let Some(end) = seg.last_group() + && group.sequence > end + { + continue; + } + return Poll::Ready(Some(group)); + } + Poll::Ready(Ok(None)) => { + let count = match sub.poll_finished(waiter) { + Poll::Ready(count) => count.ok(), + Poll::Pending => None, + }; + seg.complete(count); + return Poll::Ready(None); + } + // A dead segment stalls the logical track rather than erroring; + // the next switch resumes it. + Poll::Ready(Err(_)) => { + seg.complete(None); + return Poll::Ready(None); + } + Poll::Pending => return Poll::Pending, + }, + SubState::Done(_) => return Poll::Ready(None), + } + } + } + /// Poll for the next group in arrival order across the segments. /// /// A group that continues one already returned (a boundary landed inside it) is @@ -1663,21 +1722,105 @@ impl Subscriber { /// Poll for the next group with a higher sequence than any previously /// returned, skipping late arrivals, across the segments. /// - /// Unlike [`track::Subscriber`], the arrival-order and sequence-order cursors - /// are shared: groups consumed here are also consumed for - /// [`Self::poll_recv_group`]. + /// Mirrors [`track::Ordered`]: each segment is driven through its own sequence + /// cursor with no age-based pruning, so a backlog bursts in order instead of + /// being discarded, and [`Subscription::max_age`] only bounds how long a + /// handed-out group's reads may block. One group per segment is staged so the + /// lowest sequence across segments is delivered first; a segment's cursor is + /// monotonic, so a staged group past the [`Self::end_at`] cap stalls only that + /// segment until the cap rises. pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { - loop { - // Snapshot the floor before receiving: `poll_recv_group` advances - // `next_sequence` for every group it returns, and a duplicate of the - // last returned sequence (a boundary splicing at the delivered edge) - // must compare against the floor as it was, or it slips through. - let floor = self.next_sequence; - match ready!(self.poll_recv_group(waiter))? { - Some(group) if group.sequence < floor => continue, - res => return Poll::Ready(Ok(res)), + self.poll_sync(waiter); + + let end_sequence = self.end_sequence; + let beyond_cap = |sequence: u64| end_sequence.is_some_and(|end| sequence > end); + let floor = self.next_sequence.max(self.min_sequence); + + // A staged group needs a waiter for the same reason a parked one does: an + // eviction aborts it without touching any cursor this subscriber polls. + let watch = |group: &group::Consumer| match group.poll_closed(waiter) { + Poll::Pending => true, + Poll::Ready(()) => !group.is_aborted(), + }; + + let mut all_done = true; + for index in 0..self.segments.len() { + // A raised `start_at` or an abort invalidates a staged group. The floor + // itself cannot overtake one: it only advances past delivered sequences, + // and delivery always takes the lowest staged. + if let Some(group) = &self.segments[index].staged + && (group.sequence < floor || !watch(group)) + { + self.segments[index].staged = None; + } + + while self.segments[index].staged.is_none() { + let polled = Self::poll_segment_ordered( + &mut self.segments[index], + &self.last_prefs, + self.min_sequence, + end_sequence, + waiter, + ); + match polled { + Poll::Ready(Some(group)) => { + let sequence = group.sequence; + // Fold a copy that continues a group already handed out + // before the floor is consulted: a boundary can land inside a + // group whose head this cursor has not surfaced yet, and such + // a copy must splice rather than pose as a fresh group. + let Some(group) = self.hand_out(index, group) else { + continue; + }; + // A late arrival the sequence contract skips. + if sequence < floor { + continue; + } + if watch(&group) { + self.segments[index].staged = Some(group); + } + } + Poll::Ready(None) => break, + Poll::Pending => break, + } + } + + let seg = &self.segments[index]; + if seg.staged.is_some() || !matches!(seg.sub, SubState::Done(_)) { + all_done = false; + } + } + + // Deliver the lowest staged group within the cap. + let candidate = self + .segments + .iter() + .enumerate() + .filter_map(|(index, seg)| seg.staged.as_ref().map(|group| (index, group.sequence))) + .filter(|(_, sequence)| !beyond_cap(*sequence)) + .min_by_key(|(_, sequence)| *sequence); + if let Some((index, sequence)) = candidate { + let group = self.segments[index].staged.take().expect("staged just observed"); + // Staging is not a delivery; this is. + group.cache_refresh(); + self.next_sequence = self.next_sequence.max(sequence.saturating_add(1)); + return Poll::Ready(Ok(Some(group))); + } + + if let Some(err) = &self.abort { + return Poll::Ready(Err(err.clone())); + } + if all_done { + if self.finished { + return Poll::Ready(Ok(None)); + } + // The producer is gone without finishing: no takeover can ever resume + // the drained segments, so report the drop like a plain track would. + if self.closed { + return Poll::Ready(Err(Error::Dropped)); } } + Poll::Pending } /// Return the next group with a higher sequence than any previously returned. @@ -2467,6 +2610,65 @@ mod test { assert_eq!(next(&mut sub), 2); } + /// The spliced sequence path inherits the [`track::Ordered`] contract: a backlog + /// the drift budget would discard on the arrival path is still delivered whole, + /// in order, exactly as a plain track's sequence cursor delivers it. + #[tokio::test] + async fn next_group_bursts_a_stale_backlog_like_a_plain_track() { + // Groups spaced 10s apart on the media timeline, so with the default (zero) + // max age budget every group behind the newest one's reach is stale. + let stamp = |sequence: u64| Duration::from_secs(10 * sequence); + + // Plain baseline: the same content through `track::Ordered`. + let (mut plain, _plain_consumer) = track_pair("plain"); + for sequence in 0..4 { + write_group_at(&mut plain, sequence, "data", stamp(sequence)); + } + let mut plain_ordered = plain.subscribe(None).ordered(); + let baseline: Vec = std::iter::from_fn(|| { + plain_ordered + .next_group() + .now_or_never()? + .expect("should not error") + .map(|group| group.sequence) + }) + .collect(); + assert_eq!(baseline, vec![0, 1, 2, 3], "a plain sequence cursor bursts the backlog"); + + // The arrival path on the same content discards the backlog instead. + let mut arrival = plain.subscribe(None); + assert_eq!( + arrival.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, + 3, + "the arrival path skips straight to the live edge" + ); + + // Spliced: the same backlog split across a takeover boundary. + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + producer.switch(&consumer_b, Position::group(2)).unwrap(); + let mut sub = producer.consume().subscribe(None); + + write_group_at(&mut track_a, 0, "a0", stamp(0)); + write_group_at(&mut track_a, 1, "a1", stamp(1)); + write_group_at(&mut track_b, 2, "b2", stamp(2)); + write_group_at(&mut track_b, 3, "b3", stamp(3)); + + let spliced: Vec = std::iter::from_fn(|| { + kio::wait(|waiter| sub.poll_next_group(waiter)) + .now_or_never()? + .expect("should not error") + .map(|group| group.sequence) + }) + .collect(); + assert_eq!( + spliced, baseline, + "spliced and plain sequence cursors deliver the same backlog" + ); + } + #[tokio::test] async fn consecutive_updates_wake() { use std::task::Context; diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index aabf652012a..d5584153866 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -3157,7 +3157,8 @@ impl Subscriber { } /// The sequence cursor behind [`Ordered`], which owns the only public door to it. - fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + /// Crate-visible so a [`super::resume::Subscriber`] segment can drive it too. + pub(crate) fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { let meter = self.stats.meter(); let res = match &mut self.inner { SubscriberKind::Plain(plain) => plain.poll_next_group(waiter), diff --git a/rs/moq-transcode/src/feed.rs b/rs/moq-transcode/src/feed.rs index ecd5b2b11f5..39118f1e658 100644 --- a/rs/moq-transcode/src/feed.rs +++ b/rs/moq-transcode/src/feed.rs @@ -176,9 +176,13 @@ async fn decode(inner: &Inner, sender: &broadcast::Sender) -> Result<(), E // The feed serves whichever rungs are active, so there is no single // downstream subscription to mirror; live-edge defaults fit every rung. - let mut subscriber = inner.source.subscribe(None).await?.ordered(); + // Arrival order on purpose: its drift budget keeps dropping whatever falls + // behind the live edge, where a sequence cursor would burst the backlog + // through the codecs. Group order doesn't matter here, since every group + // decodes independently from its own keyframe. + let mut subscriber = inner.source.subscribe(None).await?; - while let Some(mut group) = subscriber.next_group().await? { + while let Some(mut group) = subscriber.recv_group().await? { // Sends only fail with zero receivers, which is fine: teardown aborts // this task at the next await anyway. let _ = sender.send(Item::Group(group.sequence)); From 2cb60740b8bb30355f729221c50d0ce2601c2197 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 19:11:37 -0700 Subject: [PATCH 6/8] fix(net): keep spliced and frame-level cursors on the sequence contract Codex's adversarial pass found two holes in the takeover commit. The spliced sequence path left each segment's inner cursor uncapped, so a beyond-cap group arriving early advanced it past an in-range group still on the wire, losing that group for good once the cap rose; the inner cursor now carries the outer cap. js/net's frame helpers read the lowest buffered group with no floor, so a late lower-sequence group was fed to the caller backwards, and they still discarded stale groups the Ordered contract promises to deliver; they now acquire groups through the same sequence cursor as nextGroup, which also makes endAt apply to them like every other read. The JS snapshot consumer replayed every retained group where the Rust one collapses to the newest, so a late joiner decoded each superseded state; it now jumps the cursor to the latest buffered group. Co-Authored-By: Claude Fable 5 --- js/json/src/snapshot/compression.test.ts | 5 +- js/json/src/snapshot/consumer.ts | 5 + js/json/src/snapshot/snapshot.test.ts | 6 +- js/net/src/track.test.ts | 54 ++++++++++- js/net/src/track.ts | 98 ++++++-------------- rs/moq-net/src/model/resume.rs | 113 +++++++++++++++++------ 6 files changed, 180 insertions(+), 101 deletions(-) diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index d1c81a35e7d..dadd5b872fb 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -44,8 +44,9 @@ test("compressed snapshot per group round-trips", async () => { producer.update({ a: 2 }); producer.finish(); - // Deltas off: one compressed snapshot per group, reconstructed in order. - expect(await drainCompressed(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([{ a: 1 }, { a: 2 }]); + // Deltas off: one compressed snapshot per group. A consumer joining after the fact + // collapses the backlog to the newest value (mirrors the Rust consumer). + expect(await drainCompressed(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([{ a: 2 }]); }); test("compressed live consumer sees each update in order", async () => { diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 32106dc18dc..ce9abbd4a94 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -36,6 +36,11 @@ export class Consumer { async next(): Promise { for (;;) { if (!this.#group) { + // Collapse the retained backlog: every group restarts from a full snapshot, so + // older groups only hold superseded state. Jump the cursor to the newest + // buffered group instead of replaying each one (mirrors the Rust consumer). + const latest = this.#track.latest(); + if (latest !== undefined) this.#track.startAt(latest); // Advance to the next group with a higher sequence number (skipping late arrivals). this.#group = await this.#track.nextGroup(); if (!this.#group) return undefined; diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index b8ad3fa0d37..bbb2dff219d 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -38,8 +38,10 @@ test("deltas off: a snapshot group per change", async () => { producer.update({ a: 2 }); producer.finish(); - // Two changes => two single-frame snapshot groups, reconstructed in order. - expect(await drain(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([{ a: 1 }, { a: 2 }]); + // Two changes => two single-frame snapshot groups. A consumer joining after the fact + // 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({ maxAge: REPLAY_LATENCY }))).toEqual([{ a: 2 }]); }); test("deltaRatio 0 disables deltas, like off", async () => { diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index b677f0f04e6..ab33d3e0ae5 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -300,6 +300,46 @@ test("the latency budget skips a buffered timeline only on the arrival cursor", expect((await ordered.nextGroup())?.sequence).toBe(2); }); +// The ordered frame helpers share the burst contract: a buffered backlog is drained +// in full rather than discarded for age. +test("ordered frame reads drain a stale backlog", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 5000 }); + const ordered = producer.subscribe().ordered(); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + expect(await ordered.readString()).toBe("0"); + expect(await ordered.readString()).toBe("1000"); + expect(await ordered.readString()).toBe("2000"); +}); + +// The frame helpers ride the same sequence cursor as nextGroup: a lower group arriving +// after a higher one was read is skipped, never fed to the caller backwards. +test("ordered frame reads skip a late lower-sequence group", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); + + const five = new GroupProducer(5); + five.writeString("five"); + five.close(); + producer.writeGroup(five); + expect(await track.readString()).toBe("five"); + + const three = new GroupProducer(3); + three.writeString("three"); + three.close(); + producer.writeGroup(three); + + const six = new GroupProducer(6); + six.writeString("six"); + six.close(); + producer.writeGroup(six); + + expect(await track.readString()).toBe("six"); +}); + test("zero latency takes the latest group when ages are equal", async () => { const clock = mockMonotonicTime(10_000); try { @@ -722,7 +762,9 @@ test("endAt caps the live edge used by the latency budget", async () => { expect((await track.recvGroup())?.sequence).toBe(2); }); -test("endAt does not cap frame-level reads", async () => { +// The frame helpers ride the group cursor, so its bounds apply to them too: a group +// above the cap parks (surviving a clean close) until the cap admits it. +test("endAt caps frame-level reads like the group cursor", async () => { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); const track = producer.subscribe({ maxAge: 5000 }).ordered(); track.endAt(0); @@ -732,7 +774,15 @@ test("endAt does not cap frame-level reads", async () => { producer.close(); expect((await track.readFrameSequence())?.group).toBe(0); - expect((await track.readFrameSequence())?.group).toBe(1); + + // Group 1 parks above the cap; a clean close must not resolve it as finished. + const parked = track.readFrameSequence(); + const timeout = new Promise((resolve) => setTimeout(() => resolve("pending"), 10)); + expect(await Promise.race([parked, timeout])).toBe("pending"); + + // Raising the cap releases the parked group, frames intact. + track.endAt(1); + expect((await parked)?.group).toBe(1); expect(await track.readFrameSequence()).toBeUndefined(); }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 534740ba1fb..6f13e316d3a 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -700,6 +700,9 @@ export class Subscriber { // it to sequence order; whichever wins is the only one allowed from here on. // Datagrams are a separate cursor and never commit. #mode?: "arrival" | "ordered"; + // The group the frame-level helpers are currently draining, acquired through the + // sequence cursor so frame reads and {@link Ordered.nextGroup} share one floor. + #frameGroup?: GroupConsumer; #drift(): { budget: number; @@ -914,6 +917,8 @@ export class Subscriber { for (const group of groups) group.close(abort); groups.length = 0; }); + this.#frameGroup?.close(abort); + this.#frameGroup = undefined; this.#state.timeline.clear(); } @@ -1056,7 +1061,7 @@ export class Subscriber { } /** - * Reads the next frame across all groups, discarding older groups. + * Reads the next frame across groups, in sequence order. * Treat the returned frame bytes as read-only; they are shared with other consumers. */ async #readFrame(): Promise { @@ -1067,90 +1072,47 @@ export class Subscriber { /** * Reads the next frame along with its group and frame sequence numbers. * Treat the returned frame bytes as read-only; they are shared with other consumers. - * Groups outside the subscription's `maxAge` budget are discarded before reading. + * + * Groups are acquired through the same sequence cursor as {@link Ordered.nextGroup}, + * so frames never run backwards: a late lower-sequence group is skipped, and a + * buffered backlog is drained in full rather than discarded for age. A group the + * `maxAge` budget abandons mid-stall ends cleanly and the cursor resyncs from the + * next group; an eviction gap inside a group still surfaces as {@link Lagged}. */ async #readFrameSequence(): Promise<({ group: number; frame: number } & Frame) | undefined> { for (;;) { - const groups = this.#state.groups.peek(); - const { start } = this.#cursor.peek(); - while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); - const drift = this.#drift(); - for (let i = 0; i < groups.length; ) { - const group = groups[i]; - if (!this.#isStale(group, drift)) { - i++; - continue; - } - groups.splice(i, 1); - group.close(); + if (!this.#frameGroup) { + this.#frameGroup = await this.#nextGroup(); + if (!this.#frameGroup) return undefined; } - - let readable = groups.length; - - // Drain older groups first, dropping each once empty. - while (readable > 1) { - if (groups[0].skipped) { - // The reader fell behind this group's eviction window. Drop it and - // signal the gap; the next read resyncs from the following group. - groups.shift()?.close(); - throw new Lagged(); - } - const next = groups[0].tryReadFrameSequence(); - if (next) { - return { - group: groups[0].sequence, - frame: next.sequence, - payload: next.payload, - timestamp: next.timestamp, - }; - } - groups.shift()?.close(); - readable--; - } - - if (readable === 0) { + const group = this.#frameGroup; + + let next: ({ sequence: number } & Frame) | undefined; + try { + next = await group.readFrameSequence(); + } catch (err) { + // The group failed underneath us: resync from the next one, surfacing + // only what the caller can act on (a gap, or the track's own abort). + this.#frameGroup = undefined; + group.close(); + if (err instanceof Lagged) throw err; const closed = this.#state.closed.peek(); if (closed instanceof Error) throw closed; - if (closed !== undefined && groups.length === 0) return undefined; - if (closed !== undefined) { - await Signal.race(this.#cursor); - continue; - } - await Signal.race(this.#state.groups, this.#cursor, this.#state.closed); continue; } - const group = groups[0]; - if (group.skipped) { - // Fell behind this group's eviction window. Drop it and signal the gap; - // the next read resyncs from the following group. - groups.shift()?.close(); - throw new Lagged(); - } - const next = group.tryReadFrameSequence(); - if (next) + if (next) { return { group: group.sequence, frame: next.sequence, payload: next.payload, timestamp: next.timestamp, }; - - const closed = this.#state.closed.peek(); - if (closed instanceof Error) throw closed; - if (closed !== undefined) return undefined; - - // A finished (drained + closed) group has nothing left: drop it and loop, rather than - // busy-waiting on its already-resolved readable() (which would livelock and starve the - // macrotask that delivers the next group). - if (group.done) { - groups.shift()?.close(); - continue; } - // Lone open group with nothing buffered yet: wait for a frame on it, a new group, or - // the track closing. - await Promise.race([Signal.race(this.#state.groups, this.#cursor, this.#state.closed), group.readable()]); + // The group is exhausted (or the budget abandoned its stall); move on. + this.#frameGroup = undefined; + group.close(); } } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 36c1f5c39b1..adda3ea3669 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1135,9 +1135,11 @@ struct SegmentSub { /// The next group this segment's sequence cursor would deliver, held so the /// spliced sequence path ([`Subscriber::poll_next_group`]) can pick the lowest /// across segments without consuming more than one group per segment ahead. - /// The cursor behind it is monotonic, so a staged group past the subscriber's - /// cap also correctly stalls everything after it in this segment. staged: Option, + /// The outer cap last applied to the inner sequence cursor, so the ordered path + /// only rewrites it on change. `None` until first applied; the arrival path + /// leaves the inner uncapped instead (see [`Subscriber::poll_activate`]). + inner_cap: Option>, } impl SegmentSub { @@ -1401,6 +1403,7 @@ impl Subscriber { pruned: false, parked: BTreeMap::new(), staged: None, + inner_cap: None, }); } } @@ -1548,33 +1551,46 @@ impl Subscriber { SubState::Pending(_) => { ready!(Self::poll_activate(seg, prefs, min_sequence, end_sequence, waiter)); } - SubState::Active(sub) => match sub.poll_next_group(waiter) { - Poll::Ready(Ok(Some(group))) => { - // The floor is enforced by the caller; enforce the segment - // boundary here since the inner cursor is deliberately uncapped. - if let Some(end) = seg.last_group() - && group.sequence > end - { - continue; - } - return Poll::Ready(Some(group)); + SubState::Active(sub) => { + // The inner cursor must not advance past the outer cap: a beyond-cap + // group it returned would sit staged while a late in-range arrival + // slipped underneath it, and the monotonic cursor would then skip + // that arrival for good. The arrival path instead leaves the inner + // uncapped, since an inner cap would hide the segment's completion + // from it; the sequence path never needs completion before the cap + // lifts, because an uncompleted segment just reads as Pending. + if seg.inner_cap != Some(end_sequence) { + sub.end_at(end_sequence); + seg.inner_cap = Some(end_sequence); } - Poll::Ready(Ok(None)) => { - let count = match sub.poll_finished(waiter) { - Poll::Ready(count) => count.ok(), - Poll::Pending => None, - }; - seg.complete(count); - return Poll::Ready(None); - } - // A dead segment stalls the logical track rather than erroring; - // the next switch resumes it. - Poll::Ready(Err(_)) => { - seg.complete(None); - return Poll::Ready(None); + match sub.poll_next_group(waiter) { + Poll::Ready(Ok(Some(group))) => { + // The floor is enforced by the caller; enforce the segment + // boundary here since the boundary is not on the inner cursor. + if let Some(end) = seg.last_group() + && group.sequence > end + { + continue; + } + return Poll::Ready(Some(group)); + } + Poll::Ready(Ok(None)) => { + let count = match sub.poll_finished(waiter) { + Poll::Ready(count) => count.ok(), + Poll::Pending => None, + }; + seg.complete(count); + return Poll::Ready(None); + } + // A dead segment stalls the logical track rather than erroring; + // the next switch resumes it. + Poll::Ready(Err(_)) => { + seg.complete(None); + return Poll::Ready(None); + } + Poll::Pending => return Poll::Pending, } - Poll::Pending => return Poll::Pending, - }, + } SubState::Done(_) => return Poll::Ready(None), } } @@ -2610,6 +2626,49 @@ mod test { assert_eq!(next(&mut sub), 2); } + /// A beyond-cap group arriving (and being polled) before an in-range one must not + /// advance the sequence cursor past the late arrival: the inner cursor is capped, + /// so the reordered burst is delivered in order once the cap admits each group. + #[tokio::test] + async fn next_group_cap_holds_a_reordered_group_without_losing_late_arrivals() { + let (mut track_a, consumer_a) = track_pair("a"); + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(replay()); + + let next = |sub: &mut Subscriber| { + kio::wait(|waiter| sub.poll_next_group(waiter)) + .now_or_never() + .expect("should not block") + .expect("should not error") + .expect("should not be finished") + .sequence + }; + let next_pending = |sub: &mut Subscriber| { + assert!( + kio::wait(|waiter| sub.poll_next_group(waiter)).now_or_never().is_none(), + "should have blocked" + ); + }; + + sub.end_at(1); + + // The beyond-cap group arrives first and is polled: it must hold, not advance + // the cursor past the in-range groups still on their way. + write_group(&mut track_a, 2, "a2"); + next_pending(&mut sub); + + write_group(&mut track_a, 0, "a0"); + write_group(&mut track_a, 1, "a1"); + assert_eq!(next(&mut sub), 0); + assert_eq!(next(&mut sub), 1); + next_pending(&mut sub); + + // Raising the cap admits the held group. + sub.end_at(2); + assert_eq!(next(&mut sub), 2); + } + /// The spliced sequence path inherits the [`track::Ordered`] contract: a backlog /// the drift budget would discard on the arrival path is still delivered whole, /// in order, exactly as a plain track's sequence cursor delivers it. From 135d34ef9d87fa4e8b608c829a7899720ba014bc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 19:38:00 -0700 Subject: [PATCH 7/8] feat(net)!: expire groups on timestamps alone, leaving wall-clock to the cache Expiration and reclamation were two rules under one budget. Expiration is now timestamp-only: a group is stale once its reach (its successor's first frame timestamp) falls a full budget behind the newest frame of the latest group. The candidate needs no timestamp of its own, so an empty or stalled group is bounded by its stamped successor the same way, which is what the retired wall-clock arm existed for. Wall-clock reclamation of idle content belongs to the retention cache (Publisher Max Age, the pool's access-time expiry), whose symptom is a gap (Lagged), not a budget verdict. Removes the wall edge, the per-slot arrival instants, and the per-frame activity clocks from both implementations, along with the group Position plumbing that carried them into every guarded read. The draft's Expiration section drops the wall-clock measure to match. Co-Authored-By: Claude Fable 5 --- drafts/draft-lcurley-moq-lite.md | 18 ++--- js/net/src/group.ts | 60 ++++----------- js/net/src/ietf/publisher.ts | 1 - js/net/src/internal.ts | 18 +---- js/net/src/lite/publisher.ts | 6 +- js/net/src/track.test.ts | 18 +++-- js/net/src/track.ts | 46 ++++------- rs/moq-net/src/model/frame.rs | 5 +- rs/moq-net/src/model/group.rs | 58 +++----------- rs/moq-net/src/model/subscription.rs | 13 ++-- rs/moq-net/src/model/track.rs | 111 ++++++++------------------- 11 files changed, 110 insertions(+), 244 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 63bf0427db1..272d3fa2e05 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -507,11 +507,10 @@ Expiration only removes the group from live delivery; the publisher MAY still re It is not crucial to aggressively expire groups thanks to [prioritization](#prioritization), but a lower priority group still consumes RAM, bandwidth, and potentially flow control. It is RECOMMENDED that an application set conservative limits and only resort to expiration when data is absolutely no longer needed. -A group is never expired until at least the next group (by sequence number) has been received or queued. -Once a newer group exists, the group's age is measured two ways, and it is expired once **either** measure exceeds the relevant `Max Age`: - -- **Timestamp age**: the difference between the *newest* frame timestamp of the latest group that has at least one frame, and this group's **reach**, defined below. This measure is consistent across relays and unaffected by buffering or jitter. -- **Wall-clock age**: the difference between when this group's first byte arrived (subscriber) or was queued (publisher) and the same instant for the latest group. +A group is never expired until a later group (by sequence number) has presented a frame. +Once one has, the group's **timestamp age** is the difference between the *newest* frame timestamp of the latest group that has at least one frame, and this group's **reach**, defined below; the group is expired once that age meets the relevant `Max Age`. +Timestamps are the only measure: they are consistent across relays and unaffected by buffering or jitter. +Wall-clock reclamation of idle content is the retention cache's own policy (`Publisher Max Age`, or any implementation-defined bound), not part of this rule. A group is expired only once it **provably cannot overlap the Max Age window**: every frame it could still present is older than the budget allows. Being behind is not itself a reason to expire anything. @@ -521,13 +520,13 @@ What cannot be recovered is a group with nothing left worth delivering, and that A group's **reach** is the first frame timestamp of the next group by sequence number, or unbounded when no later group has presented a frame. A group cannot present past where its successor begins, so this is the furthest it could still reach. Its own frames do not bound it: frame durations are not carried on the wire, so a group's last frame timestamp is where that frame *starts* presenting, not where the group ends. -A group whose successor has not arrived is therefore never expired on timestamp age, because nothing yet proves where it stops. +A group whose successor has not presented a frame is therefore never expired, because nothing yet proves where it stops. +The group itself needs no timestamp: a zero-frame group (a keep-alive or gap marker) is bounded by its successor's first frame the same way. Reach is an exclusive bound, so a timestamp age **equal** to Max Age already expires the group: the freshest frame it could still hold sits strictly below its reach, and is therefore strictly older than the budget. A Max Age of zero follows from the same rule without a special case. -The two backstop each other: a publisher cannot keep stale groups alive with fresh-looking timestamps, and a burst of groups arriving together does not reset their age. -A group that contains zero frames has no timestamp, so only the wall-clock age applies; this avoids stalling expiration on empty groups sent as keep-alives or gap markers. +Measuring in timestamps rather than arrival means a burst of groups delivered together still reads as its true age, so catching up never resets the clock. An expired group SHOULD be reset at the QUIC level to avoid consuming flow control. @@ -1371,7 +1370,8 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. -- Redefined timestamp age so a group is expired only once it provably cannot overlap the Max Age window. Age is now measured from a group's *reach* (the first frame timestamp of its successor, which is the furthest it could still present) to the newest frame of the latest group, and an age equal to Max Age expires it, since reach is an exclusive bound. Previously age ran from the group's own first frame, which expired a group whose later frames were still well inside the budget. A group whose successor has not yet arrived is never expired on timestamp age, because frame durations are not on the wire and nothing else proves where it ends; the wall-clock measure still applies. +- Redefined timestamp age so a group is expired only once it provably cannot overlap the Max Age window. Age is now measured from a group's *reach* (the first frame timestamp of its successor, which is the furthest it could still present) to the newest frame of the latest group, and an age equal to Max Age expires it, since reach is an exclusive bound. Previously age ran from the group's own first frame, which expired a group whose later frames were still well inside the budget. A group whose successor has not yet presented a frame is never expired, because frame durations are not on the wire and nothing else proves where it ends. +- Removed the wall-clock age measure from expiration: timestamps are the only input, and wall-clock reclamation of idle content is the retention cache's own policy (`Publisher Max Age`) rather than part of the subscription rule. A zero-frame group needs no measure of its own, since its reach is bounded by its successor's first frame like any other group. - Removed `Subscriber Ordered` from SUBSCRIBE and SUBSCRIBE_UPDATE, and `Publisher Ordered` from TRACK_INFO and SUBSCRIBE_OK. Group order within a Track is now normatively newest-first, with no field to invert it: a subscriber that wants sequence order reads in sequence order, which costs the network nothing and does not let one subscriber's preference reach a Track a relay is fanning out to many. Note this removes a byte from the middle of each message, so a lite-06 peer cannot parse a lite-05 one's SUBSCRIBE (the earlier drafts keep the byte, and an implementation serving them SHOULD write 0 and ignore what it reads). - Made `Group Start` an absolute floor (the raw minimum group sequence, default 0) rather than the sequence + 1 with 0 meaning the latest group. The start resolves from `Subscriber Max Age` instead: the oldest group at or above the floor within the budget, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group, which was the only start the old encoding could ask for by default. diff --git a/js/net/src/group.ts b/js/net/src/group.ts index aa60d44e2e1..7f761d9f96b 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -4,7 +4,7 @@ * @module */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; -import { type GroupPosition, hooks, type ReadGroupFrame } from "./internal.ts"; +import { hooks, type ReadGroupFrame } from "./internal.ts"; import { Timestamp } from "./time.ts"; /** Maximum bytes of frames cached in a group before old frames are evicted from the front. */ @@ -29,12 +29,6 @@ export interface Frame { timestamp: Timestamp; } -/** A frame paired with its arrival clock for wall-clock drift measurement. */ -interface BufferedFrame { - frame: Frame; - activity: number; -} - /** Immutable group metadata. */ export interface Info { /** Sequence number of this group within its track. */ @@ -55,7 +49,7 @@ export class Lagged extends Error { /** Reactive backing state shared by the group producer and one consumer. */ class GroupState { readonly sequence: number; - frames = new Signal([]); + frames = new Signal([]); closed = new Once(); total = new Signal(0); // The total number of frames in the group thus far @@ -67,29 +61,25 @@ class GroupState { timestamp?: Timestamp; // The newest frame's timestamp: where a reader that has taken every frame sits. latest?: Timestamp; - // When the group last accepted a frame. A group is silent from here, not from - // whenever it was created. - activity?: number; constructor(sequence: number) { this.sequence = sequence; } } -function appendFrame(state: GroupState, frame: Frame, activity: number) { +function appendFrame(state: GroupState, frame: Frame) { if (state.closed.peek() !== undefined) throw new Error("group is closed"); state.timestamp ??= frame.timestamp; state.latest = frame.timestamp; - state.activity = activity; state.cacheBytes += frame.payload.byteLength; state.frames.mutate((frames) => { - frames.push({ frame, activity }); + frames.push(frame); while (frames.length > MAX_GROUP_FRAMES || state.cacheBytes > MAX_GROUP_CACHE_BYTES) { const evicted = frames.shift(); if (!evicted) break; - state.cacheBytes -= evicted.frame.payload.byteLength; + state.cacheBytes -= evicted.payload.byteLength; state.offset++; } }); @@ -144,8 +134,7 @@ export class Producer { const dst = new GroupState(this.sequence); dst.timestamp = this.#state.timestamp; dst.latest = this.#state.latest; - dst.activity = this.#state.activity; - for (const { frame, activity } of this.#state.frames.peek()) appendFrame(dst, frame, activity); + for (const frame of this.#state.frames.peek()) appendFrame(dst, frame); dst.offset = this.#state.offset; const closed = this.#state.closed.peek(); @@ -196,13 +185,12 @@ export class Producer { /** Writes a frame to the group. */ writeFrame(frame: Frame) { - const activity = performance.now(); - appendFrame(this.#state, frame, activity); + appendFrame(this.#state, frame); if (this.#mirrors) { for (const mirror of this.#mirrors) { if (mirror.closed.peek() !== undefined) this.#mirrors.delete(mirror); - else appendFrame(mirror, frame, activity); + else appendFrame(mirror, frame); } } } @@ -327,7 +315,7 @@ export class Consumer { readonly sequence: number; #state: GroupState; - #expiry?: { expired: (at: GroupPosition) => boolean; changed: readonly Getter[] }; + #expiry?: { expired: () => boolean; changed: readonly Getter[] }; // Sticky verdicts, set once. `#ended` is a drained group the budget gave up on, // which is indistinguishable from one that ended: nothing was lost, so it reads as // the end of the group. `#terminal` is a failure, including a budget that gave up @@ -364,26 +352,13 @@ export class Consumer { hooks.expireGroup = (group, expiry) => { group.#expiry = expiry; }; - hooks.guardGroup = (group, operation, at) => group.#guard(operation, at); + hooks.guardGroup = (group, operation) => group.#guard(operation); hooks.readGroupFrame = (group) => group.#readFramePosition(true); hooks.evictGroup = (group) => { group.#evict(); }; } - /// Where this cursor sits, for the budget to measure against the live edge. - // - // A group is not late because it *started* long ago; what can be late is the content - // its reader has yet to take. So a reader that has drained the group sits at the - // group's newest frame, not its first. - #position(): GroupPosition { - const next = this.#state.frames.peek()[0]; - return { - presentation: next?.frame.timestamp ?? this.#state.latest, - activity: next?.activity ?? this.#state.activity, - }; - } - // Evaluate the drift budget for a read that has nothing buffered and is about to // wait. A group with frames in hand is always drained: the budget bounds a group // that has stalled while the live edge moved on, not a reader slower than the wire. @@ -392,10 +367,10 @@ export class Consumer { // `unread` is for a caller that still holds content the reader has not seen (a // publisher part-way through writing a frame): giving up there is a truncation, so // it fails rather than ending. - #expire(unread = false, at = this.#position()): boolean { + #expire(unread = false): boolean { if (this.#terminal || this.#ended) return false; if (this.#state.closed.peek() instanceof Error) return false; - if (!this.#expiry?.expired(at)) return false; + if (!this.#expiry?.expired()) return false; if (unread) { this.#terminal = new Error("group exceeded the subscription latency budget"); @@ -406,8 +381,8 @@ export class Consumer { return true; } - #guard(operation: Promise, at = this.#position()): Promise { - if (this.#expire(true, at)) return Promise.reject(this.#terminal); + #guard(operation: Promise): Promise { + if (this.#expire(true)) return Promise.reject(this.#terminal); if (this.#terminal) return Promise.reject(this.#terminal); const expiry = this.#expiry; if (!expiry) return operation; @@ -422,7 +397,7 @@ export class Consumer { fn(); }; const check = () => { - this.#expire(true, at); + this.#expire(true); if (this.#terminal) { const error = this.#terminal; finish(() => reject(error)); @@ -468,13 +443,12 @@ export class Consumer { const buffered = frames.shift(); if (!buffered) return undefined; - this.#state.cacheBytes -= buffered.frame.payload.byteLength; + this.#state.cacheBytes -= buffered.payload.byteLength; if (pending) this.#pendingFrames++; let completed = false; return { sequence: this.#state.total.peek() - frames.length - 1, - frame: buffered.frame, - position: { presentation: buffered.frame.timestamp, activity: buffered.activity }, + frame: buffered, complete: () => { if (completed) return; completed = true; diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 865c0bf17b7..da5972657cf 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -302,7 +302,6 @@ export class Publisher { await hooks.guardGroup( group, obj.encode(stream, header.flags, timescale, this.#session.version), - read.position, ); } finally { read.complete(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 74a40231e20..4df9a7f8b9a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -26,22 +26,12 @@ export type Recv = /** The track aborted. */ | { kind: "error"; error: Error }; -/** Where a group cursor sits while measuring drift against the live edge. */ -export interface GroupPosition { - /** Presentation timestamp of the next or in-flight frame. */ - presentation?: Timestamp; - /** Monotonic arrival time of the next or in-flight frame. */ - activity?: number; -} - -/** A package-internal frame read paired with its guarded cursor position. */ +/** A package-internal frame read the wire publisher completes once written. */ export interface ReadGroupFrame { /** Frame sequence within the group. */ sequence: number; /** Frame returned to the publisher. */ frame: Frame; - /** Cursor position held while the frame is in flight. */ - position: GroupPosition; /** Mark the frame delivered or deliberately skipped by the wire publisher. */ complete(): void; } @@ -89,11 +79,11 @@ export const hooks: { /** Keep applying a subscription's drift policy after it hands a group out. */ expireGroup: ( group: GroupConsumer, - expiry: { expired: (at: GroupPosition) => boolean; changed: readonly Getter[] }, + expiry: { expired: () => boolean; changed: readonly Getter[] }, ) => void; /** Stop an in-flight group operation if the handed-out group expires. */ - guardGroup: (group: GroupConsumer, operation: Promise, at?: GroupPosition) => Promise; - /** Read a frame with the cursor position needed to guard its wire write. */ + guardGroup: (group: GroupConsumer, operation: Promise) => Promise; + /** Read a frame the wire publisher completes (or skips) once written. */ readGroupFrame: (group: GroupConsumer) => Promise; /** Make an evicted mirror terminal while its track timeline still contains it. */ evictGroup: (group: GroupConsumer) => void; diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index c7a68728fb1..714ca001356 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -955,12 +955,12 @@ export class Publisher { if (timestamps) { // Convert each frame to the track's advertised timescale. const ts = BigInt(Math.round(read.frame.timestamp.as(timescale))); - await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs)), read.position); + await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs))); prevTs = ts; } - await hooks.guardGroup(group, stream.u53(read.frame.payload.byteLength), read.position); - await hooks.guardGroup(group, stream.write(read.frame.payload), read.position); + await hooks.guardGroup(group, stream.u53(read.frame.payload.byteLength)); + await hooks.guardGroup(group, stream.write(read.frame.payload)); } finally { read.complete(); } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index b4f173877a8..e9c1574c432 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -432,7 +432,9 @@ test("the budget is clamped to the publisher's window", async () => { expect((await track.recvGroup())?.sequence).toBe(1); }); -test("wall-clock age expires a group stalled before its first frame", async () => { +// The stalled group needs no timestamp of its own: its reach is where its stamped +// successor begins, which the zero budget already puts out of range. +test("a stamped successor expires a group stalled before its first frame", async () => { const clock = mockMonotonicTime(10_000); try { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); @@ -614,7 +616,7 @@ test("a guarded write keeps the position of the frame removed from the buffer", const operation = new Promise((resolve) => { release = resolve; }); - const guarded = hooks.guardGroup(group, operation, read.position); + const guarded = hooks.guardGroup(group, operation); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); // A group beyond the edge, so group 0's reach (1s) is provably behind it: a group is @@ -643,7 +645,7 @@ test("clean source closure stays provisional while a frame write can expire", as const operation = new Promise((resolve) => { release = resolve; }); - const guarded = hooks.guardGroup(group, operation, read.position); + const guarded = hooks.guardGroup(group, operation); const edge = producer.appendGroup(); edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); @@ -672,7 +674,11 @@ test("a drained group finishes cleanly after the live edge advances", async () = expect(group.done).toBe(true); }); -test("retention eviction preserves expiry for a handed-out group", async () => { +// Retention is the wall-clock half of the split: it reclaims idle content on its own +// schedule, and a reader that loses unread frames to it sees a gap. The subscription +// budget is timestamp-only and says nothing here (the empty successor has no timestamp +// to bound the held group with). +test("retention eviction surfaces as a gap for a handed-out group", async () => { const clock = mockMonotonicTime(10_000); try { const producer = new TrackProducer("test").accept({ maxAge: 100 }); @@ -689,7 +695,7 @@ test("retention eviction preserves expiry for a handed-out group", async () => { clock.set(10_200); producer.appendGroup(); - await expect(group.readFrame()).rejects.toThrow("latency budget"); + await expect(group.readFrame()).rejects.toThrow(Lagged); } finally { clock.restore(); } @@ -742,7 +748,7 @@ test("retention pruning preserves clean EOF for a drained mirror", async () => { } }); -test("system clock changes do not affect wall-clock latency", async () => { +test("system clock changes do not affect the latency budget", async () => { const clock = mockMonotonicTime(10_000); setSystemTime(new Date(10_000)); try { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 92db4fc8d04..8120b3a6aa6 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -6,14 +6,7 @@ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import type { Datagram } from "./datagram.ts"; import { type Frame, type Consumer as GroupConsumer, Producer as GroupProducer, Lagged } from "./group.ts"; -import { - type GroupPosition, - hooks, - type Recv, - type TrackRequestOptions, - type TrackSequence, - type TrackSequences, -} from "./internal.ts"; +import { hooks, type Recv, type TrackRequestOptions, type TrackSequence, type TrackSequences } from "./internal.ts"; import { Timescale, type Timestamp } from "./time.ts"; export type { Datagram } from "./datagram.ts"; @@ -728,18 +721,15 @@ export class Subscriber { #drift(): { budget: number; - wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; suffix: { sequence: number; reach: number }[]; } { const { end } = this.#cursor.peek(); - let wall: { sequence: number; time: number } | undefined; let presentation: { sequence: number; timestamp: Timestamp } | undefined; const suffix: { sequence: number; reach: number }[] = []; - for (const { group, time } of this.#state.timeline.values()) { + for (const { group } of this.#state.timeline.values()) { if (end !== undefined && group.sequence > end) continue; if (group.closed.peek() instanceof Error) continue; - if (!wall || group.sequence > wall.sequence) wall = { sequence: group.sequence, time }; const timestamp = hooks.groupTimestamp(group); if (timestamp !== undefined) { // The table bounds a candidate's reach, so it wants where each group @@ -766,7 +756,6 @@ export class Subscriber { ? requested : Math.min(requested, retained) : Number.POSITIVE_INFINITY, - wall, presentation, suffix, }; @@ -798,43 +787,36 @@ export class Subscriber { // // A group's reach is bounded by its nearest successor: it cannot present past where the // next group begins. Its own frames say nothing, since a frame's duration is not on the - // wire. The bound is exclusive, so the comparison is `>=`: the freshest frame a group - // could still hold sits just below its reach, so an age equal to the budget already puts - // every frame in it strictly past the budget. A zero budget falls out for free. - // - // `at.activity` is where a handed-out group's reader last made progress, backstopping - // an empty group that has supplied no timestamp at all. + // wire, and the candidate needs no timestamp of its own: an empty group is bounded by + // its stamped successor the same way. The bound is exclusive, so the comparison is `>=`: + // the freshest frame a group could still hold sits just below its reach, so an age equal + // to the budget already puts every frame in it strictly past the budget. A zero budget + // falls out for free. Only timestamps drive expiry; wall-clock reclamation of idle + // content is the cache's own policy, not the budget's. #isStale( group: GroupConsumer, drift: { budget: number; - wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; suffix: { sequence: number; reach: number }[]; }, - at?: GroupPosition, ): boolean { const candidate = this.#state.timeline.get(group.sequence); if (candidate?.group !== group) return false; - const time = at?.activity ?? candidate.time; - const wallStale = - drift.wall !== undefined && drift.wall.sequence > group.sequence && drift.wall.time - time >= drift.budget; - const reach = Subscriber.#reach(drift.suffix, group.sequence); - const presentationStale = + return ( drift.presentation !== undefined && drift.presentation.sequence > group.sequence && reach !== undefined && - drift.presentation.timestamp.asMillis() - reach >= drift.budget; - - return wallStale || presentationStale; + drift.presentation.timestamp.asMillis() - reach >= drift.budget + ); } #guard(group: GroupConsumer): GroupConsumer { if (!this.#enforceLatency) return group; hooks.expireGroup(group, { - expired: (at) => this.#isStale(group, this.#drift(), at), + expired: () => this.#isStale(group, this.#drift()), changed: [ this.#state.groups, this.#state.timelineChanged, @@ -959,8 +941,8 @@ export class Subscriber { * Honors the floor set by {@link startAt} and the cap set by {@link endAt}: a group * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even * after a clean close, without blocking in-range groups that arrive behind it. - * A group whose presentation time or wall-clock arrival is further behind the live edge - * than this subscriber's `maxAge` is skipped. The default of zero takes the live edge. + * A group whose presentation time is further behind the live edge than this + * subscriber's `maxAge` is skipped. The default of zero takes the live edge. * The budget remains attached after return, so a pending frame read rejects if a stalled * group becomes stale while newer data advances. * diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index ca35d4f5fa9..144abe0d3c0 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -603,10 +603,7 @@ impl Consumer { let Some(expiry) = &self.expiry else { return false; }; - let at = group::Position { - activity: self.state.read().activity, - }; - if !expiry.policy.is_expired(waiter, at) { + if !expiry.policy.is_expired(waiter) { return false; } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index b1fe428b436..5b27be226c9 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -137,11 +137,6 @@ pub(crate) struct GroupState { // against. Kept alongside `timestamp` for the same reasons. latest: Option, - // When the group last accepted a frame. The wall-clock half of the same question: - // a group is silent from here, not from whenever it was created. `None` while it - // has produced nothing, where the track's arrival time is the only thing to go on. - pub(crate) activity: Option, - // Once finalized, the total number of frames the group will ever contain. Recorded // at finish so the count outlives an abort that clears the cache. pub(crate) fin: Option, @@ -249,13 +244,11 @@ impl GroupState { } } - /// Record where the group starts and currently ends in presentation time, plus - /// when it last produced. `timestamp` keeps the first frame only; `latest` and - /// `activity` follow every frame. + /// Record where the group starts and currently ends in presentation time. + /// `timestamp` keeps the first frame only; `latest` follows every frame. fn stamp(&mut self, timestamp: Timestamp) { self.timestamp.get_or_insert(timestamp); self.latest = Some(timestamp); - self.activity = Some(crate::model::clock::now()); } /// Evict completed frames from the front until within the byte budget. @@ -990,9 +983,9 @@ pub struct Consumer { /// Subscriber-specific policy for expiring a group after it was handed out. pub(crate) trait Expiry: Send + Sync { - /// Return whether a reader sitting at `at` is stale, registering `waiter` for - /// anything that could change the answer while the group remains live. - fn is_expired(&self, waiter: &kio::Waiter, at: Position) -> bool; + /// Return whether the group is stale, registering `waiter` for anything that + /// could change the answer while the group remains live. + fn is_expired(&self, waiter: &kio::Waiter) -> bool; } // `Plain` is the hot path and carries an inline frame prefetch, so boxing it to even the @@ -1185,15 +1178,13 @@ impl Consumer { /// Keep checking expiry while a wire publisher still owns buffered group data. pub(crate) fn poll_expired_while_pending(&mut self, waiter: &kio::Waiter, pending: bool) -> bool { - if !self.expired && (pending || self.expiry_pending()) { - // Resolved here rather than up front: the sticky flag above answers most - // calls without touching the group's state at all. - let at = self.position(); - if self.expiry.as_ref().is_some_and(|expiry| expiry.is_expired(waiter, at)) { - self.expired = true; - if !self.stale_counted.swap(true, Ordering::Relaxed) { - self.stale_stats.stale(self.unread_content()); - } + if !self.expired + && (pending || self.expiry_pending()) + && self.expiry.as_ref().is_some_and(|expiry| expiry.is_expired(waiter)) + { + self.expired = true; + if !self.stale_counted.swap(true, Ordering::Relaxed) { + self.stale_stats.stale(self.unread_content()); } } self.expired @@ -1213,16 +1204,6 @@ impl Consumer { self.expired } - /// When this cursor's group last produced, for a drift budget to age it against - /// the live edge instead of when the group first arrived. - pub(crate) fn position(&self) -> Position { - match &self.inner { - ConsumerKind::Plain(plain) => plain.position(), - // A spliced group's route-specific cursors carry their own policy. - ConsumerKind::Spliced(_) => Position::default(), - } - } - /// Whether the group has been aborted (including pool eviction); the abort /// dropped the cached frames, so a held consumer has nothing left to read. /// @@ -1464,22 +1445,7 @@ impl Consumer { } } -/// When a group cursor last saw producer activity. -/// -/// `None` means the group has presented nothing (an empty or stalled group), -/// where the track falls back to when the group arrived. -#[derive(Clone, Copy, Default)] -pub(crate) struct Position { - pub(crate) activity: Option, -} - impl Plain { - fn position(&self) -> Position { - let state = self.state.read(); - Position { - activity: state.activity, - } - } /// Whether this cursor still has unread content or may receive another frame. fn expiry_pending(&self) -> bool { diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index cc9182964cf..6a7fe4a2c71 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -38,13 +38,12 @@ pub struct Subscription { /// /// # How age is measured /// - /// By both presentation time and wall-clock arrival, with either able to expire the - /// group. Presentation time compares where the group's unread content *ends* against - /// where the newest group above it begins, so a backlog delivered as a burst still - /// reads as its true age while a long group whose tail reaches the live edge does not. - /// A group already handed out is measured at its reader's position, so a reader that - /// keeps up is never convicted. Wall-clock backstops an empty or stalled group that - /// has supplied no timestamp. + /// In presentation time only. A group is measured by its *reach*, where its immediate + /// successor begins, against the newest frame of the latest group: it cannot present + /// past its successor, so once everything it could still hold falls outside the budget + /// it is provably useless. The candidate needs no timestamp of its own, so an empty or + /// stalled group is bounded by its stamped successor the same way. Wall-clock + /// reclamation of idle content is the cache's own policy, not this budget's. /// /// Protocols whose wire can't carry a timestamp (pre-Lite05 moq-lite, moq-transport /// without the Timestamp property) have their frames stamped on receipt, which makes diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 99a6dff5dba..e63f2bfb8e4 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -224,10 +224,6 @@ pub(crate) struct TrackState { struct Slot { group: group::Producer, - // When this group entered the track at this hop. This is the wall-clock - // backstop for groups whose first frame has not supplied a timestamp yet. - arrived: crate::runtime::Instant, - // Incarnation stamp, echoed by this slot's arrival entry (if any). A re-served // sequence (an aborted group re-created by the publisher or re-fetched as // backfill) gets a fresh stamp, so a historical arrival entry can't resolve to @@ -429,11 +425,12 @@ impl TrackState { self.info.as_ref().map(|info| info.max_age) } - /// The live edges a subscription bounded at `cap` measures drift against: the - /// highest-sequence group for wall-clock age, plus the highest one that has - /// presented a frame for timestamp age. + /// The live edge a subscription bounded at `cap` measures drift against: the + /// highest-sequence group that has presented a frame, or `None` while nothing + /// stamped is servable (an unstamped track drives no expiry at all; the cache's + /// own wall-clock policy is what bounds it). /// - /// One scan answers a whole poll. Each highest-sequence anchor in range is above + /// One scan answers a whole poll. The highest-sequence anchor in range is above /// every candidate below it and above none at or past it. Recomputing per candidate /// would make walking a backlog of N groups off in one poll cost O(N^2). /// @@ -443,7 +440,6 @@ impl TrackState { /// Fetched backfill is absent from `arrival`, so it cannot age subscription content /// as though it were a live replacement. fn live_edge(&self, cap: Option) -> Option { - let mut wall: Option = None; let mut presentation: Option = None; let mut stamped: Vec<(u64, Timestamp)> = Vec::new(); for slot in self.lookup.values() { @@ -454,13 +450,6 @@ impl TrackState { if cap.is_some_and(|cap| group.sequence > cap) || group.is_aborted() { continue; } - if wall.is_none_or(|edge| group.sequence > edge.sequence) { - wall = Some(WallEdge { - sequence: group.sequence, - stamp: slot.stamp, - arrived: slot.arrived, - }); - } if let Some(timestamp) = group.timestamp() { // The suffix table bounds a candidate's reach, so it wants where each group // *begins*; the edge wants the newest content that exists, so it takes the @@ -479,8 +468,7 @@ impl TrackState { // Sequence order, so a candidate's immediate successor is one lookup away. stamped.sort_unstable_by_key(|(sequence, _)| *sequence); - wall.map(|wall| Edge { - wall, + presentation.map(|presentation| Edge { presentation, suffix: stamped.into(), }) @@ -498,8 +486,10 @@ impl TrackState { /// /// A group's reach is bounded by its nearest successor: it cannot present past where /// the next group begins. Its own frames say nothing, since a frame's duration is not - /// on the wire and its last timestamp is where that frame *starts*. Wall-clock arrival - /// backstops the whole thing for an empty group that has supplied no timestamp at all. + /// on the wire and its last timestamp is where that frame *starts*. The candidate + /// itself needs no timestamp: an empty group is bounded by its stamped successor the + /// same way. Only timestamps drive expiry; wall-clock reclamation of idle content is + /// the cache's own policy, not the budget's. /// /// The bound is exclusive, so the comparison is `>=` rather than `>`: the freshest frame /// a group could still hold sits just *below* its reach, so an age equal to the budget @@ -509,46 +499,27 @@ impl TrackState { /// The edge must sit strictly above the candidate. The live edge is never late /// against itself, and backfill or the tail of a rewound timeline can carry a high /// timestamp on a low sequence without being an edge at all. - fn is_stale(&self, sequence: u64, at: Option, edge: Option<&Edge>, budget: Duration) -> bool { + fn is_stale(&self, sequence: u64, edge: Option<&Edge>, budget: Duration) -> bool { let Some(edge) = edge else { return false; }; - let Some(slot) = self.lookup.get(&sequence) else { + if !self.lookup.contains_key(&sequence) { return false; - }; - - // Where the candidate can still reach, which is a property of what follows it - // rather than of the reader or of the group's own frames. - let at = at.unwrap_or_default(); - let arrived = at.activity.unwrap_or(slot.arrived); + } - // The anchors were resolved under an earlier lock, so confirm each still names + // The anchor was resolved under an earlier lock, so confirm it still names // the same servable incarnation before it convicts a candidate. Failing safe // (delivering) is right, since the next poll resolves fresh anchors. - let wall_stale = edge.wall.sequence > sequence + let live_edge = &edge.presentation; + let reach = edge.reach(sequence); + live_edge.sequence > sequence && self .lookup - .get(&edge.wall.sequence) - .is_some_and(|live| live.stamp == edge.wall.stamp && !live.group.is_aborted()) - && edge - .wall - .arrived - .checked_duration_since(arrived) - .is_some_and(|age| age >= budget); - - let reach = edge.reach(sequence); - let presentation_stale = edge.presentation.is_some_and(|live_edge| { - live_edge.sequence > sequence - && self - .lookup - .get(&live_edge.sequence) - .is_some_and(|live| live.stamp == live_edge.stamp && !live.group.is_aborted()) - && reach.is_some_and( - |reach| matches!(live_edge.timestamp.checked_sub(reach), Ok(age) if Duration::from(age) >= budget), - ) - }); - - wall_stale || presentation_stale + .get(&live_edge.sequence) + .is_some_and(|live| live.stamp == live_edge.stamp && !live.group.is_aborted()) + && reach.is_some_and( + |reach| matches!(live_edge.timestamp.checked_sub(reach), Ok(age) if Duration::from(age) >= budget), + ) } /// Resolve a one-shot fetch from the track side: the cached group, or an [`Error`] @@ -734,7 +705,6 @@ impl TrackState { sequence, Slot { group: group.clone(), - arrived: crate::model::clock::now(), stamp, visible, }, @@ -2657,7 +2627,7 @@ struct GroupExpiry { } impl group::Expiry for GroupExpiry { - fn is_expired(&self, waiter: &kio::Waiter, at: group::Position) -> bool { + fn is_expired(&self, waiter: &kio::Waiter) -> bool { let mut max_age = Duration::default(); let _ = self.subscription.poll(waiter, |subscription| { max_age = subscription.max_age; @@ -2676,7 +2646,7 @@ impl group::Expiry for GroupExpiry { let budget = clamp_max_age(max_age, state.max_age_bound()); loop { let edge = state.live_edge(cap); - expired = state.is_stale(self.sequence, Some(at), edge.as_ref(), budget); + expired = state.is_stale(self.sequence, edge.as_ref(), budget); if expired { break; } @@ -2697,8 +2667,7 @@ impl group::Expiry for GroupExpiry { } let presentation_sequence = edge .as_ref() - .and_then(|edge| edge.presentation) - .map_or(self.sequence, |edge| edge.sequence.max(self.sequence)); + .map_or(self.sequence, |edge| edge.presentation.sequence.max(self.sequence)); for slot in state.lookup.values() { let group = &slot.group; if slot.visible @@ -2730,8 +2699,7 @@ impl group::Expiry for GroupExpiry { /// from whatever may occupy its sequence by the time a candidate is judged. #[derive(Clone)] struct Edge { - wall: WallEdge, - presentation: Option, + presentation: PresentationEdge, /// Every servable stamped group, sorted by sequence, paired with its own first frame /// timestamp. A candidate's reach is where its immediate successor begins, so `reach()` /// finds that one entry rather than rescanning, keeping a backlog walk linear. @@ -2761,16 +2729,6 @@ impl Edge { } } -/// The newest servable group, including an empty group with no media timestamp. -#[derive(Clone, Copy)] -struct WallEdge { - sequence: u64, - /// The slot incarnation this arrival time was read from, so an eviction or a re-served - /// sequence between resolving the anchor and using it is detectable. - stamp: u32, - arrived: crate::runtime::Instant, -} - /// The newest servable group that has presented at least one frame. #[derive(Clone, Copy)] struct PresentationEdge { @@ -2880,12 +2838,7 @@ impl PlainSubscriber { /// for this poll. fn poll_stale(&self, group: &group::Consumer, drift: &Drift, waiter: &kio::Waiter) -> Poll> { self.poll(waiter, move |state| { - Poll::Ready(Ok(state.is_stale( - group.sequence, - None, - drift.edge.as_ref(), - drift.budget, - ))) + Poll::Ready(Ok(state.is_stale(group.sequence, drift.edge.as_ref(), drift.budget))) }) } @@ -4537,15 +4490,15 @@ mod test { } #[tokio::test] - async fn wall_clock_expires_an_unstamped_group() { + async fn a_stamped_successor_expires_an_unstamped_group() { let mut producer = track_producer("test", None); let mut subscriber = producer.subscribe(None); producer.append_group().unwrap(); // seq 0 stalls before its first frame - crate::model::clock::advance(Duration::from_secs(1)); append_at(&mut producer, 1000); // seq 1 proves the live feed moved on - // With the real-time budget, wall-clock age backstops the missing timestamp. + // The candidate needs no timestamp of its own: its reach is where its stamped + // successor begins, which the zero budget already puts out of range. assert_eq!(drain(&mut subscriber), vec![1]); } @@ -5052,7 +5005,7 @@ mod test { edge: state.live_edge(None), }; assert!( - state.is_stale(0, None, drift.edge.as_ref(), drift.budget), + state.is_stale(0, drift.edge.as_ref(), drift.budget), "stale against a live edge" ); drop(state); @@ -5063,7 +5016,7 @@ mod test { let state = producer.state.read(); assert!( - !state.is_stale(0, None, drift.edge.as_ref(), drift.budget), + !state.is_stale(0, drift.edge.as_ref(), drift.budget), "a vanished edge is no reason to drop what is left" ); } From 4a147f5a8fcd2f724b7b7ce13bc1fac02a6150d5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 20:04:35 -0700 Subject: [PATCH 8/8] fix(net): seek segments instead of staging, and keep one frame cursor in js Codex's re-review caught the staging design's flaw: staging a group advances a segment's inner cursor before the outer cursor commits, so a cap lowered after a lookahead stranded a late in-range arrival the inner cursor had stepped past. The spliced sequence path now seeks each segment's cache for the lowest group at the outer floor without consuming anything, delivers the winner, and advances only its own floor; the staged slot and inner cap tracking are gone. js/net's nextGroup now abandons the group the frame helpers were draining when it moves past it, so interleaving the two read styles on one Ordered handle can no longer replay older frames behind the cursor. Co-Authored-By: Claude Fable 5 --- js/net/src/track.test.ts | 33 ++++ js/net/src/track.ts | 6 + rs/moq-net/src/model/group.rs | 1 - rs/moq-net/src/model/resume.rs | 307 +++++++++++++++++---------------- rs/moq-net/src/model/track.rs | 41 ++++- 5 files changed, 234 insertions(+), 154 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index e9c1574c432..dd99d51e23a 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -315,6 +315,39 @@ test("ordered frame reads drain a stale backlog", async () => { expect(await ordered.readString()).toBe("2000"); }); +// Interleaving nextGroup with the frame helpers is still one cursor: a nextGroup that +// moves past the group the frame helpers were draining abandons it, so a later frame +// read never runs backwards. +test("nextGroup abandons the frame helpers' group when it passes it", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 5000 }).ordered(); + + const zero = new GroupProducer(0); + zero.writeString("0.0"); + zero.writeString("0.1"); + zero.close(); + producer.writeGroup(zero); + + const one = new GroupProducer(1); + one.writeString("1.0"); + one.close(); + producer.writeGroup(one); + + const two = new GroupProducer(2); + two.writeString("2.0"); + two.close(); + producer.writeGroup(two); + + // The frame path enters group 0; a direct nextGroup then takes group 1. + expect((await track.readFrameSequence())?.group).toBe(0); + expect((await track.nextGroup())?.sequence).toBe(1); + + // The frame path must not resume group 0 behind the cursor: it continues at 2. + const next = await track.readFrameSequence(); + expect(next?.group).toBe(2); + expect(dec.decode(next?.payload)).toBe("2.0"); +}); + // The frame helpers ride the same sequence cursor as nextGroup: a lower group arriving // after a higher one was read is skipped, never fed to the caller backwards. test("ordered frame reads skip a late lower-sequence group", async () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 8120b3a6aa6..ccc4488bb17 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1054,6 +1054,12 @@ export class Subscriber { if (group && (cursor.end === undefined || group.sequence <= cursor.end)) { groups.shift(); this.#nextSequence = group.sequence + 1; + // One cursor: the frame helpers must not keep draining a group this + // read just moved past, or interleaved reads would run backwards. + if (this.#frameGroup && this.#frameGroup.sequence < group.sequence) { + this.#frameGroup.close(); + this.#frameGroup = undefined; + } return this.#guard(group); } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 5b27be226c9..0df6d2f8171 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1446,7 +1446,6 @@ impl Consumer { } impl Plain { - /// Whether this cursor still has unread content or may receive another frame. fn expiry_pending(&self) -> bool { if self.capped() { diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 33c63928afa..1e42e91c88a 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1132,14 +1132,6 @@ struct SegmentSub { /// the lowest is re-offered first; holding them here (rather than blocking on /// the first) keeps in-range groups that arrive behind a capped one flowing. parked: BTreeMap, - /// The next group this segment's sequence cursor would deliver, held so the - /// spliced sequence path ([`Subscriber::poll_next_group`]) can pick the lowest - /// across segments without consuming more than one group per segment ahead. - staged: Option, - /// The outer cap last applied to the inner sequence cursor, so the ordered path - /// only rewrites it on change. `None` until first applied; the arrival path - /// leaves the inner uncapped instead (see [`Subscriber::poll_activate`]). - inner_cap: Option>, } impl SegmentSub { @@ -1187,9 +1179,7 @@ impl SegmentSub { /// replaced before producing, so it holds nothing. The straggler bound in /// `reap` cuts what lingers too long, parked group and all. fn retired(&self) -> bool { - self.pruned - && (self.end.is_none() - || (matches!(self.sub, SubState::Done(_)) && self.parked.is_empty() && self.staged.is_none())) + self.pruned && (self.end.is_none() || (matches!(self.sub, SubState::Done(_)) && self.parked.is_empty())) } } @@ -1278,7 +1268,6 @@ impl Subscriber { seg.sub = SubState::Done(None); seg.terminal = None; seg.parked.clear(); - seg.staged = None; cut -= 1; } } @@ -1402,8 +1391,6 @@ impl Subscriber { terminal: None, pruned: false, parked: BTreeMap::new(), - staged: None, - inner_cap: None, }); } } @@ -1536,65 +1523,113 @@ impl Subscriber { } } - /// Drive one segment's sequence cursor: resolve a pending subscription, then poll - /// for the next in-sequence group. Out-of-bounds groups (a route racing its cap) are - /// skipped. Unlike [`Self::poll_segment`], groups are never discarded for age: the - /// spliced sequence path inherits the [`track::Ordered`] contract of bursting a - /// backlog instead of skipping it. - fn poll_segment_ordered( - seg: &mut SegmentSub, - prefs: &Subscription, - min_sequence: u64, - end_sequence: Option, + /// Seek this subscriber's lowest servable group at or above `floor` (bounded by + /// `end`, inclusive), without advancing any cursor. The shared engine behind + /// [`Self::poll_next_group`] and [`Self::poll_seek_group`]. + /// + /// Unlike [`Self::poll_segment`], nothing is discarded for age: the spliced + /// sequence path inherits the [`track::Ordered`] contract of bursting a backlog + /// instead of skipping it. Nothing is consumed either: each segment is *seeked* + /// rather than read, so a candidate a poll does not deliver stays where it was, + /// and a cap lowered between polls never strands a group behind a segment cursor + /// that had already stepped past it. + fn poll_seek( + &mut self, + floor: u64, + end: Option, waiter: &kio::Waiter, - ) -> Poll> { - loop { - match &mut seg.sub { - SubState::Pending(_) => { - ready!(Self::poll_activate(seg, prefs, min_sequence, end_sequence, waiter)); + ) -> Poll>> { + self.poll_sync(waiter); + + let mut floor = floor; + 'retry: loop { + let mut all_done = true; + let mut best: Option<(usize, group::Consumer)> = None; + + for index in 0..self.segments.len() { + if matches!(self.segments[index].sub, SubState::Pending(_)) + && Self::poll_activate( + &mut self.segments[index], + &self.last_prefs, + self.min_sequence, + end, + waiter, + ) + .is_pending() + { + all_done = false; + continue; } - SubState::Active(sub) => { - // The inner cursor must not advance past the outer cap: a beyond-cap - // group it returned would sit staged while a late in-range arrival - // slipped underneath it, and the monotonic cursor would then skip - // that arrival for good. The arrival path instead leaves the inner - // uncapped, since an inner cap would hide the segment's completion - // from it; the sequence path never needs completion before the cap - // lifts, because an uncompleted segment just reads as Pending. - if seg.inner_cap != Some(end_sequence) { - sub.end_at(end_sequence); - seg.inner_cap = Some(end_sequence); - } - match sub.poll_next_group(waiter) { + + let seg = &mut self.segments[index]; + // A boundary behind the floor can never serve this cursor again; + // release its inner subscription rather than holding demand open. + if seg.last_group().is_some_and(|last| last < floor) + && let SubState::Active(sub) = &mut seg.sub + { + let count = match sub.poll_finished(waiter) { + Poll::Ready(count) => count.ok(), + Poll::Pending => None, + }; + seg.complete(count); + } + + let cap = min_some(end, seg.last_group()); + match &mut seg.sub { + SubState::Active(sub) => match sub.poll_seek_group(floor, cap, waiter) { Poll::Ready(Ok(Some(group))) => { - // The floor is enforced by the caller; enforce the segment - // boundary here since the boundary is not on the inner cursor. - if let Some(end) = seg.last_group() - && group.sequence > end - { - continue; + all_done = false; + // Strict, so the earlier segment wins a boundary tie: it + // holds the head copy, the one `hand_out` can surface. + if best.as_ref().is_none_or(|(_, best)| group.sequence < best.sequence) { + best = Some((index, group)); } - return Poll::Ready(Some(group)); } + // The track ran out at or below the floor: the segment drained. Poll::Ready(Ok(None)) => { let count = match sub.poll_finished(waiter) { Poll::Ready(count) => count.ok(), Poll::Pending => None, }; seg.complete(count); - return Poll::Ready(None); } // A dead segment stalls the logical track rather than erroring; // the next switch resumes it. - Poll::Ready(Err(_)) => { - seg.complete(None); - return Poll::Ready(None); - } - Poll::Pending => return Poll::Pending, + Poll::Ready(Err(_)) => seg.complete(None), + Poll::Pending => all_done = false, + }, + SubState::Pending(_) => all_done = false, + SubState::Done(_) => {} + } + } + + if let Some((index, group)) = best { + let sequence = group.sequence; + // A copy continuing a group already handed out splices into it rather + // than surfacing again; step past it and look for the next sequence. + match self.hand_out(index, group) { + Some(group) => return Poll::Ready(Ok(Some(group))), + None => { + floor = sequence.saturating_add(1); + continue 'retry; } } - SubState::Done(_) => return Poll::Ready(None), } + + if let Some(err) = &self.abort { + return Poll::Ready(Err(err.clone())); + } + if all_done { + if self.finished { + return Poll::Ready(Ok(None)); + } + // The producer is gone without finishing: no takeover can ever resume + // the drained segments, so report the drop like a plain track would. + if self.closed { + return Poll::Ready(Err(Error::Dropped)); + } + } + return Poll::Pending; } } @@ -1740,105 +1775,30 @@ impl Subscriber { /// Poll for the next group with a higher sequence than any previously /// returned, skipping late arrivals, across the segments. /// - /// Mirrors [`track::Ordered`]: each segment is driven through its own sequence - /// cursor with no age-based pruning, so a backlog bursts in order instead of - /// being discarded, and [`Subscription::max_age`] only bounds how long a - /// handed-out group's reads may block. One group per segment is staged so the - /// lowest sequence across segments is delivered first; a segment's cursor is - /// monotonic, so a staged group past the [`Self::end_at`] cap stalls only that - /// segment until the cap rises. + /// Mirrors [`track::Ordered`]: segments are seeked rather than read, no group is + /// discarded for age, and [`Subscription::max_age`] only bounds how long a + /// handed-out group's reads may block. See [`Self::poll_seek`]. pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { - self.poll_sync(waiter); - - let end_sequence = self.end_sequence; - let beyond_cap = |sequence: u64| end_sequence.is_some_and(|end| sequence > end); let floor = self.next_sequence.max(self.min_sequence); - - // A staged group needs a waiter for the same reason a parked one does: an - // eviction aborts it without touching any cursor this subscriber polls. - let watch = |group: &group::Consumer| match group.poll_closed(waiter) { - Poll::Pending => true, - Poll::Ready(()) => !group.is_aborted(), + let Some(group) = ready!(self.poll_seek(floor, self.end_sequence, waiter))? else { + return Poll::Ready(Ok(None)); }; + self.next_sequence = self.next_sequence.max(group.sequence.saturating_add(1)); + Poll::Ready(Ok(Some(group))) + } - let mut all_done = true; - for index in 0..self.segments.len() { - // A raised `start_at` or an abort invalidates a staged group. The floor - // itself cannot overtake one: it only advances past delivered sequences, - // and delivery always takes the lowest staged. - if let Some(group) = &self.segments[index].staged - && (group.sequence < floor || !watch(group)) - { - self.segments[index].staged = None; - } - - while self.segments[index].staged.is_none() { - let polled = Self::poll_segment_ordered( - &mut self.segments[index], - &self.last_prefs, - self.min_sequence, - end_sequence, - waiter, - ); - match polled { - Poll::Ready(Some(group)) => { - let sequence = group.sequence; - // Fold a copy that continues a group already handed out - // before the floor is consulted: a boundary can land inside a - // group whose head this cursor has not surfaced yet, and such - // a copy must splice rather than pose as a fresh group. - let Some(group) = self.hand_out(index, group) else { - continue; - }; - // A late arrival the sequence contract skips. - if sequence < floor { - continue; - } - if watch(&group) { - self.segments[index].staged = Some(group); - } - } - Poll::Ready(None) => break, - Poll::Pending => break, - } - } - - let seg = &self.segments[index]; - if seg.staged.is_some() || !matches!(seg.sub, SubState::Done(_)) { - all_done = false; - } - } - - // Deliver the lowest staged group within the cap. - let candidate = self - .segments - .iter() - .enumerate() - .filter_map(|(index, seg)| seg.staged.as_ref().map(|group| (index, group.sequence))) - .filter(|(_, sequence)| !beyond_cap(*sequence)) - .min_by_key(|(_, sequence)| *sequence); - if let Some((index, sequence)) = candidate { - let group = self.segments[index].staged.take().expect("staged just observed"); - // Staging is not a delivery; this is. - group.cache_refresh(); - self.next_sequence = self.next_sequence.max(sequence.saturating_add(1)); - return Poll::Ready(Ok(Some(group))); - } - - if let Some(err) = &self.abort { - return Poll::Ready(Err(err.clone())); - } - if all_done { - if self.finished { - return Poll::Ready(Ok(None)); - } - // The producer is gone without finishing: no takeover can ever resume - // the drained segments, so report the drop like a plain track would. - if self.closed { - return Poll::Ready(Err(Error::Dropped)); - } - } - Poll::Pending + /// Seek the lowest servable group at or above `floor` (bounded by `end`) without + /// advancing this subscriber's own cursor: the nested-splice counterpart of + /// [`track::Subscriber::poll_seek_group`]. + pub(crate) fn poll_seek_group( + &mut self, + floor: u64, + end: Option, + waiter: &kio::Waiter, + ) -> Poll>> { + let floor = floor.max(self.min_sequence); + let end = min_some(end, self.end_sequence); + self.poll_seek(floor, end, waiter) } /// Return the next group with a higher sequence than any previously returned. @@ -2683,6 +2643,51 @@ mod test { assert_eq!(next(&mut sub), 2); } + /// Lowering the cap after the cursor already considered (but did not deliver) a + /// higher group must not strand a late in-range arrival: seeking consumes + /// nothing, so no segment cursor ever steps past an undelivered sequence. + #[tokio::test] + async fn next_group_cap_lowering_after_a_lookahead_keeps_late_arrivals() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + producer.switch(&consumer_b, Position::group(1)).unwrap(); + let mut sub = producer.consume().subscribe(replay()); + + let next = |sub: &mut Subscriber| { + kio::wait(|waiter| sub.poll_next_group(waiter)) + .now_or_never() + .expect("should not block") + .expect("should not error") + .expect("should not be finished") + .sequence + }; + let next_pending = |sub: &mut Subscriber| { + assert!( + kio::wait(|waiter| sub.poll_next_group(waiter)).now_or_never().is_none(), + "should have blocked" + ); + }; + + // The new segment's group 2 arrives early, and the old segment delivers 0. + write_group(&mut track_b, 2, "b2"); + write_group(&mut track_a, 0, "a0"); + assert_eq!(next(&mut sub), 0); + + // Cap below the group the cursor could already see. It must hold, not have + // committed the segment past the still-missing group 1. + sub.end_at(1); + next_pending(&mut sub); + + write_group(&mut track_b, 1, "b1"); + assert_eq!(next(&mut sub), 1); + next_pending(&mut sub); + + sub.end_at(None); + assert_eq!(next(&mut sub), 2); + } + /// The spliced sequence path inherits the [`track::Ordered`] contract: a backlog /// the drift budget would discard on the arrival path is still delivered whole, /// in order, exactly as a plain track's sequence cursor delivers it. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index e63f2bfb8e4..36b1e7dcab9 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2944,6 +2944,25 @@ impl PlainSubscriber { self.next_sequence = group.sequence.saturating_add(1); Poll::Ready(Ok(Some(self.with_expiry(group)))) } + + /// Seek the lowest cached group in `floor..=end` without advancing any cursor. + /// + /// Repeated polls return the same group until the caller's own floor passes it, + /// which is the point: the spliced sequence path picks the lowest candidate across + /// segments and must not commit a segment past a group it has not delivered. + fn poll_seek_group( + &mut self, + floor: u64, + end: Option, + waiter: &kio::Waiter, + ) -> Poll>> { + let floor = floor.max(self.min_sequence); + let end = super::subscription::min_some(end, self.end_sequence); + let Some(group) = ready!(self.poll(waiter, |state| state.poll_next_in_range(floor, end))?) else { + return Poll::Ready(Ok(None)); + }; + Poll::Ready(Ok(Some(self.with_expiry(group)))) + } } /// A cloneable handle to a subscriber's delivery preferences. @@ -3140,8 +3159,7 @@ impl Subscriber { } /// The sequence cursor behind [`Ordered`], which owns the only public door to it. - /// Crate-visible so a [`super::resume::Subscriber`] segment can drive it too. - pub(crate) fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { let meter = self.stats.meter(); let res = match &mut self.inner { SubscriberKind::Plain(plain) => plain.poll_next_group(waiter), @@ -3151,6 +3169,25 @@ impl Subscriber { res.map(|res| res.map(|group| group.map(|group| group.with_meter(meter)))) } + /// Seek the lowest cached group in `floor..=end` without advancing any cursor. + /// Crate-visible for [`super::resume::Subscriber`], whose sequence path picks the + /// lowest candidate across its segments and advances only its own floor; see + /// [`PlainSubscriber::poll_seek_group`]. + pub(crate) fn poll_seek_group( + &mut self, + floor: u64, + end: Option, + waiter: &kio::Waiter, + ) -> Poll>> { + let meter = self.stats.meter(); + let res = match &mut self.inner { + SubscriberKind::Plain(plain) => plain.poll_seek_group(floor, end, waiter), + SubscriberKind::Spliced(spliced) => spliced.poll_seek_group(floor, end, waiter), + }; + self.count_stale(&meter); + res.map(|res| res.map(|group| group.map(|group| group.with_meter(meter)))) + } + /// Read this track's groups in sequence order instead of arrival order. /// /// Consumes the subscriber, so one handle carries exactly one cursor: an