From 6c0caa357e69c175a94d0febb0279860ff430b4d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:14:44 -0800 Subject: [PATCH 01/26] chore(quest): claim quest/m2/time-addressing/lite07.md Quest-Claim: 1406d5e5325fc163 From 19879a22e2c239783b5f13e6d798a22e2416bdda Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:29:43 -0800 Subject: [PATCH 02/26] docs(drafts)!: lite-07 addresses groups by start The lite draft names every group by its start: GROUP carries the start and the previous group's start, GROUP_END ends a whole group, drops and skips name spans of starts, and OLD drops are final. Folds in the pre-cut audit's fixes: Subscriber Max Age plus one, one Time anchor, no Padding, a listing kind, Largest Ended, and no RTCDataChannel binding. Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 17 +- drafts/draft-lcurley-moq-e2ee.md | 9 +- drafts/draft-lcurley-moq-lite.md | 400 ++++++++++++++++--------------- 3 files changed, 220 insertions(+), 206 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index f270c250a90..49b48c89f3b 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -325,6 +325,14 @@ upstream as that ID, where a start selects the first group at or after it rather than the one containing it. moq-lite 01 and 02 carry no start, so every subscription there starts at the live group. +A group ends one of three ways: finished at the time it ends, so it is whole; +closed, so every frame written arrives but it may have held more, as when a +relay stops sending a group that went stale; or aborted with an error. A +finished group's end also bounds how long it stays fresh, so the last group of +a paused track still ages out. Over the work-in-progress moq-lite 07 each group +also names the start of the group before it, so a reader sees a gap at once; +older versions and moq-transport carry neither the end nor the previous start. + Order only decides what goes first, never what is skipped, so catching up oldest first needs a max delay that covers the backlog. When a relay serves subscribers of both orders from one upstream subscription, it asks upstream for newest first, and @@ -347,7 +355,7 @@ track is judged by the wall clock alone. Tracks from moq-lite before 05, or from moq-transport without a `TIMESCALE`, arrive untimed. moq-lite 05 and 06 cannot declare an untimed track, so there its frames go out stamped with their send time; the work-in-progress 07 carries it -untimed. +without a timescale, each frame stamped with its group's start. A publisher refuses a group that starts before a lower one, and so does a moq-lite 07 receiver. A receiver passes on the timestamps it gets over moq-lite @@ -446,9 +454,10 @@ suits real-time audio and sensor data. There is no stream fallback, so a datagram that doesn't fit isn't delivered. Datagram tracks have a namespace apart from stream tracks, so `audio` as -datagrams and `audio` as streams are two independent tracks. Nothing on the -wire says which kind a name is: the application knows from its catalog or by -convention, so a broadcast's track listing never includes a datagram track. In +datagrams and `audio` as streams are two independent tracks. A broadcast's +track listing says which kind each track is, and lists datagram tracks only +over the work-in-progress moq-lite 07; elsewhere the application knows the kind +from its catalog or by convention. In Rust, `broadcast.create_datagrams(name, info)` publishes one and `broadcast.datagrams(name)` reads it. In JavaScript use `broadcast.createDatagrams(name, info)` and `broadcast.datagrams(name)`. diff --git a/drafts/draft-lcurley-moq-e2ee.md b/drafts/draft-lcurley-moq-e2ee.md index 94d5edf991e..c0f52878e23 100644 --- a/drafts/draft-lcurley-moq-e2ee.md +++ b/drafts/draft-lcurley-moq-e2ee.md @@ -151,7 +151,7 @@ Neither can cause a nonce to repeat, because only the publisher instance chooses A restart or replacement of a publisher is a new instance and mints a new epoch. So is a cloned process image, such as a `fork` without `exec`, a restored VM snapshot or process checkpoint, or a producing generation prepared once and copied to two processes: each copy MUST mint its own generation before it encrypts. A clone copies the epoch and the per-track counters verbatim, so two copies that both encrypt would protect different plaintext under the same key and nonce, and nothing on the wire lets a receiver or relay detect it. -Transport sequence numbers therefore restart freely without any coordination between instances. +Group starts and datagram sequences therefore restart freely without any coordination between instances. An ended instance stays readable only for as long as relays or archives retain it under its epoch; once another instance wins the shared path, subscribers resolve that one. @@ -234,7 +234,8 @@ A subscriber derives both from the semantic name it wants; a publisher derives t A protected object is the tuple `(generation, physical_name, domain, group, frame)`. ## Grouped Frames -A grouped frame uses `domain = 0x00`, the group's sequence as `group`, and the frame index within that group as `frame`. +A grouped frame uses `domain = 0x00`, the group's start as `group`, and the frame index within that group as `frame`. +The start is the Group Start of a moq-lite-07 GROUP, the Group Sequence of an earlier moq-lite version, and the Group ID on MoQ Transport, which carry the same value ({{moql}} Section "Group"). moq-lite numbers frames from 0 in write order ({{moql}}). On MoQ Transport, `frame` is the explicit Object ID, never its arrival ordinal. Publishers supporting both transports MUST assign contiguous Object IDs from zero so that each matches its moq-lite write-order index; relays MUST NOT renumber protected objects. @@ -265,7 +266,7 @@ AES-128-GCM encrypts the application bytes with `key`, `nonce`, and empty AAD. The bytes placed in the MoQ frame or datagram payload are ciphertext concatenated with the 16-byte tag, in the {{RFC5116}} convention. There is no inner header. -Within a generation a publisher MUST allocate each semantic name's group sequences, and separately its datagram sequences, monotonically, and frame indices in write order, so an identity is encrypted at most once. +Within a generation a publisher MUST give each semantic name's groups strictly increasing starts, allocate its datagram sequences monotonically, and frame indices in write order, so an identity is encrypted at most once. Encrypting at an identity the same instance already used is `reuse` and MUST be refused. Relays and caches forward ciphertext unchanged, so replay from a cache never re-encrypts. @@ -290,7 +291,7 @@ Encrypting then compressing is forbidden: ciphertext does not compress. # Bounds {#bounds} Implementations MUST refuse non-integer identities (including NaN and infinities) and identities outside these bounds before encoding or AEAD: -- `group` (grouped sequence or datagram sequence) and `kid`: `0..=2^53-1`. Above that is `identity`. +- `group` (group start or datagram sequence) and `kid`: `0..=2^53-1`. Above that is `identity`. - `frame`: `0..=2^32-1`. `2^32` and above is `identity`. - AEAD operations with one key: at most `2^24` invocations and at most `2^36` plaintext bytes (`2^32` 16-byte blocks). Exceeding either is `exhausted`. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 48a1e21e76f..fd16607ec4e 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -32,7 +32,6 @@ normative: RFC6455: RFC8032: RFC8446: - RFC8831: RFC9000: RFC9002: @@ -136,10 +135,10 @@ This corresponds to a MoqTransport's "track namespace". A path is a sequence of non-empty segments joined by `/` (0x2F), so it never starts or ends with `/` or contains two in a row; the empty path has no segments and prefixes every path. A `\` (0x5C) escapes the `\` or `/` that follows it, as a MoqTransport namespace field holding either is spelled; a path with any other `\` is a PROTOCOL_VIOLATION, or in a claim refused (see [Refused Content](#refused-content)). A continuous stream is named by an Instance, carried on its claims (see [ANNOUNCE_START](#announce-start)): a path and an Instance name one Broadcast, and a publisher MUST NOT serve different content under the same pair. -Within one Instance, group sequences never restart and never name two different groups, so claims sharing it serve the same bytes; two Instances are independent streams, never stitched together. -A publisher that starts its group sequences over, such as a restarted process, uses a new Instance, while replicas of the same content share one. -A publisher MAY keep an Instance across restarts only if it continues the sequence space and announces a higher Epoch each time. -A Track recreated within one Instance likewise continues past every Group Sequence its predecessor published. +Within one Instance, a Group start never names two different Groups, so claims sharing it serve the same bytes; two Instances are independent streams, never stitched together. +A publisher whose Group starts could go back, such as a restarted process with a new clock, uses a new Instance, while replicas of the same content share one. +A publisher MAY keep an Instance across restarts only if its Group starts keep moving forward and it announces a higher Epoch each time. +A Track recreated within one Instance likewise starts past every Group its predecessor published. A receiver does not detect a publisher that breaks this, which corrupts only that Broadcast for its subscribers. The Epoch is a counter within one Instance that picks its live incarnation while a stale claim lingers; it is never compared across Instances. @@ -171,18 +170,26 @@ The subscriber and publisher both indicate their delivery preference: The combination of these preferences enables the most important content to arrive during network degradation while still respecting encoding dependencies. A Track is instead a datagram Track when its publisher creates it as one: a series of unreliable QUIC datagrams with no Groups (see [Datagrams](#datagrams)). -Which kind a Track is never changes, and the wire does not say; the application knows it from its catalog or by convention. +Which kind a Track is never changes; a [Tracks Stream](#tracks-stream) listing says it, and otherwise the application knows it from its catalog or by convention. Datagram Tracks have a namespace apart from other Tracks, so a datagram Track and a Track of Groups may share a name and are independent. ## Group A Group is an ordered stream of Frames within a Track. Each group consists of an append-only list of Frames. -A Group's sequence is its start: its frame 0's timestamp on a timed Track, and on an untimed Track a number that grows with each Group, in no unit. -Sequences therefore order Groups by start without a counter, and a gap between two says nothing on its own. -A receiver addresses a Group by the sequence it carries whatever its frames hold, so a publisher that numbers its Groups 0, 1, 2 is still served, with time Anchors compared against those numbers. -A publisher never creates a Group with sequence 2^64-1, so every range of Groups ends within 64 bits; a receiver treats a Group Stream naming it as a malformed Track. -A Group is normally served by a dedicated QUIC stream which is closed on completion, reset by the publisher, or cancelled by the subscriber. +A Group is addressed by its start, a timestamp in the Track's `Timescale`: its frame 0's timestamp, or a bare number on a Track with a `Timescale` of 0. +No two Groups of a Track share a start, so starts order Groups without a counter, and moq-lite carries no Group sequence number. +A gap between two starts says nothing on its own: the [GROUP](#group-message) message names the start of the Group before it when the publisher knows it, and [SUBSCRIBE_SKIP](#subscribe-skip) names the starts it declared it will never produce. +A receiver addresses a Group by the start it carries whatever its frames hold, so a publisher that numbers its Groups 0, 1, 2 is still served, with time Anchors compared against those numbers. +A publisher never creates a Group with start 2^64-1, so every span of starts ends within 64 bits; a receiver treats a Group Stream naming it as a malformed Track. + +A Group ends in one of three ways: + +- Finished: a [GROUP_END](#group-end) names where it ends, so it is whole. +- Closed: its stream ends (FIN) without a GROUP_END, so every Frame sent on it arrived, but the Group may have held more. +- Aborted: its stream is reset. + +A Group is normally served by a dedicated QUIC stream which is finished or closed on completion, reset by the publisher, or cancelled by the subscriber. This ensures that all Frames within a Group arrive reliably and in order. In contrast, Groups may arrive out of order due to network congestion and prioritization. @@ -195,29 +202,30 @@ A frame is used to represent a chunk of data with an upfront size. The contents are opaque to the moq-lite layer. Frames within a Group are numbered from 0 in the order they were produced. -This index is not transmitted per frame; it is implied by position within the Group, anchored by the [GROUP](#group) message's `Frame Start`. +This index is not transmitted per frame; it is implied by position within the Group, anchored by the [GROUP](#group-message) message's `Frame Start`. A Group Stream normally starts at frame 0. -Each frame of a timed Track carries a presentation timestamp expressed in the Track's `Timescale` (see [TRACK_INFO](#track-info)), used by the moq-lite layer for [expiration](#expiration) decisions. -A Track without a `Timescale` is untimed: its frames carry no timestamp. +Each frame carries a presentation timestamp expressed in the Track's `Timescale` (see [TRACK_INFO](#track-info)), used by the moq-lite layer for [expiration](#expiration) decisions. +A Track with a `Timescale` of 0 is scale-less: its timestamps and Group starts are bare numbers in no known unit, and each frame's timestamp is its Group's start. A timestamp MUST be less than 2^61, so every version can carry it; a receiver treats a larger one as a malformed Track. -Unless a negotiated extension specifies otherwise, a publisher MUST NOT start a timed Group's frame 0 at or before that of any lower-sequence Group it publishes. +Unless a negotiated extension specifies otherwise, a publisher MUST NOT start a Group's frame 0 at or before that of any Group with a lower start it publishes, and MUST NOT give a frame of a scale-less Track any timestamp but its Group's start. A receiver MAY check a received Group against this rule, refusing a violating Group's stream (STOP_SENDING) with TIMESTAMP_MISMATCH. A relay serves a Track's timestamps on as it received them, including ones it did not check, unless a negotiated extension specifies otherwise. ## Positions {#positions} -A Position is a (Group Sequence, Frame Index) pair identifying one frame within a Track. +A Position is a (Group Start, Frame Index) pair identifying one frame within a Track. Positions order lexicographically: by group first, then by frame within the group. -SUBSCRIBE reads whole Groups: a Range's Absolute Anchors name Groups (see [SUBSCRIBE](#subscribe)), so a subscription never starts or stops partway through one. +SUBSCRIBE reads whole Groups: a Range's Anchors name Groups (see [SUBSCRIBE](#subscribe)), so a subscription never starts or stops partway through one. FETCH reads one Group, or a slice of one: its `Frame Start` and `Frame End` bound the returned frames, and a frame index of 0 at the start, or an absent end frame, is the whole Group. -A subscriber that has received frames 0 through `N-1` of group `G` and wants the rest FETCHes `G` from frame `N` and subscribes from Group `G+1`, so the two requests cover the Track with no gap and no overlap. +A subscriber that has received frames 0 through `N-1` of the Group starting at `G` and wants the rest FETCHes `G` from frame `N`, and subscribes for the Groups after it. This is what lets a subscriber move a Track to a different publisher partway through a Group instead of waiting for the next Group to start, which matters for Tracks whose current Group may stay open indefinitely. A Group can therefore be assembled from more than one publisher: each contributes a disjoint run of frames, and the subscriber concatenates them in index order. A partial Group is only ever delivered to a subscriber that asked for one with FETCH, or as the [continuation](#yield) of a paused Group. -A publisher that holds only part of a Group a subscription covers names it in a [SUBSCRIBE_DROP](#subscribe-drop) rather than deliver the part it holds. +A publisher that holds only the later frames of a Group a subscription covers names it in a [SUBSCRIBE_DROP](#subscribe-drop) rather than deliver the part it holds. +One that holds its earlier frames, such as a relay whose upstream closed the Group or a Group expiring as it is sent, delivers them and closes the Group Stream without a GROUP_END. A Group is the unit of decodability: its earlier Frames may carry a keyframe or compression state the later Frames need. # Flow @@ -234,8 +242,8 @@ A subscriber that holds an Auth Stream and an Announce Stream needs credit for a AUTH and ANNOUNCE occupy two streams for the session lifetime, and TRACK is briefly held alongside SUBSCRIBE, requiring two more. ## Transports {#transports} -moq-lite defines five transport bindings. -All five carry the same control and data streams defined elsewhere in this document; they differ only in how QUIC streams are multiplexed onto the underlying connection. +moq-lite defines four transport bindings. +All four carry the same control and data streams defined elsewhere in this document; they differ only in how QUIC streams are multiplexed onto the underlying connection. |----|---------------------|------------------|----------------------| | | Transport | ALPN / Identifier | Record framing | @@ -244,23 +252,15 @@ All five carry the same control and data streams defined elsewhere in this docum | 2 | WebTransport / H3 | `moq-lite-xx` (CONNECT header) | Native WebTransport streams | | 3 | Qmux over TCP/TLS | `moq-lite-xx` (ALPN over TLS) | Qmux Record [qmux] | | 4 | Qmux over WebSocket | `moq-lite-xx` (Sec-WebSocket-Protocol) | WebSocket message [qmuxws] | -| 5 | Qmux over RTCDataChannel | `moq-lite-xx` (signaling and DataChannel protocol) | DataChannel message | For bindings 1 and 2, moq-lite uses the underlying QUIC/WebTransport stream APIs directly. -QUIC datagrams (see [Datagrams](#datagrams)) are supported by bindings 1 and 2 only; a publisher MUST NOT emit datagrams on bindings 3, 4, and 5, and a subscriber SHOULD NOT open a [Datagrams Stream](#datagrams-stream) there. +QUIC datagrams (see [Datagrams](#datagrams)) are supported by bindings 1 and 2 only; a publisher MUST NOT emit datagrams on bindings 3 and 4, and a subscriber SHOULD NOT open a [Datagrams Stream](#datagrams-stream) there. For binding 3, a client opens a TCP connection, performs a TLS handshake, and negotiates the moq-lite version as the ALPN token. Each direction of the TLS byte stream then carries Qmux Records as defined in [qmux]. For binding 4, a client opens a WebSocket connection [RFC6455] offering the moq-lite version as the subprotocol, per [qmuxws]: each WebSocket binary message carries one Qmux Record's `Frames` payload, with the message boundary replacing the Record `Size` field. -For binding 5, WebRTC Data Channels [RFC8831] carry Qmux. Signaling agrees the moq-lite version before establishing the peer connection. -The client creates one reliable, ordered RTCDataChannel with that version as its protocol; the server MUST refuse a channel whose protocol differs or whose delivery is unordered or partially reliable. -The binding uses Qmux draft-01: each binary DataChannel message carries one Record's `Frames` payload, with the message boundary replacing the Record `Size` field. -The record limit defaults to 16 KiB and MUST NOT exceed the negotiated SCTP `maxMessageSize`; an endpoint MUST refuse a message limit below Qmux's minimum record size. -A sender splits stream payloads at frame boundaries to fit this limit, never within a frame. -Signaling, peer admission, and ICE server selection are application concerns. - All other moq-lite semantics (stream types, message encoding, flow control, etc.) are identical across bindings. ## Termination @@ -344,9 +344,9 @@ Sent when resetting a stream (RESET_STREAM), or when refusing to receive one (ST | ------- | ------------- | ----------- | | 0x32 | GROUP_TOO_LARGE | The group grew past the publisher's cache budget and was aborted. | | ------- | ------------- | ----------- | -| 0x33 | NOT_FOUND | The requested group, track, or broadcast is not here. A sequence its publisher declared it will never produce is named by SUBSCRIBE_SKIP instead; any other sequence a publisher never had, including a gap it never declared, is named with NOT_FOUND unless it is past the subscriber's budget (see [SUBSCRIBE_DROP](#subscribe-drop)). | +| 0x33 | NOT_FOUND | The requested group, track, or broadcast is not here. A start its publisher declared it will never produce is named by SUBSCRIBE_SKIP instead; any other start a publisher never had, including a gap it never declared, is named with NOT_FOUND unless it is past the subscriber's budget (see [SUBSCRIBE_DROP](#subscribe-drop)). | | ------- | ------------- | ----------- | -| 0x34 | OLD | The group was superseded by a newer group and dropped. In SUBSCRIBE_DROP, the next SUBSCRIBE_UPDATE reopens it: the publisher re-offers the group or drops it again. | +| 0x34 | OLD | The group was superseded by a newer group and dropped. | | ------- | ------------- | ----------- | | 0x35 | EVICTED | The group was dropped under memory pressure. Unlike OLD it was still current, so it can be re-fetched. | | ------- | ------------- | ----------- | @@ -356,7 +356,7 @@ Sent when resetting a stream (RESET_STREAM), or when refusing to receive one (ST | ------- | ------------- | ----------- | | 0x38 | FRAME_TOO_LARGE | A frame declared a payload larger than the receiver accepts. | | ------- | ------------- | ----------- | -| 0x39 | TIMESTAMP_MISMATCH | A frame's timestamp does not fit its track: it is present on an untimed track, absent on a timed one, or starts a Group before a lower-sequence one. | +| 0x39 | TIMESTAMP_MISMATCH | A frame's timestamp does not fit its track: it starts a Group at or before one with a lower start, or differs from its Group's start on a scale-less track. | | ------- | ------------- | ----------- | | 0x3B | UNAUTHORIZED | The endpoint does not authorize this request, or no longer does, such as when the [scope](#auth-stream) does not cover it. The session stays up. | | ------- | ------------- | ----------- | @@ -627,31 +627,31 @@ A claim asserts capability rather than inventory, so a subscription for a covere The track's immutable publisher properties are not carried here; they are fetched once via a [Track Stream](#track-stream). The subscriber needs the track's TRACK_INFO (notably its timescale) to interpret FRAME messages, and MAY open the Track and Subscribe streams concurrently, buffering frames until it arrives. -The publisher sends SUBSCRIBE_OK once the start is resolved, and SUBSCRIBE_FINISH as soon as the exclusive final group is known (see [SUBSCRIBE_OK](#subscribe-ok) and [SUBSCRIBE_FINISH](#subscribe-finish)). +The publisher sends SUBSCRIBE_OK once the start is resolved, and SUBSCRIBE_FINISH as soon as the Track's end is known (see [SUBSCRIBE_OK](#subscribe-ok) and [SUBSCRIBE_FINISH](#subscribe-finish)). Neither closes the stream: the publisher keeps reading SUBSCRIBE_UPDATE messages, so an update can still widen the Ranges, including into an ended Track's history, and the publisher serves or drops what it newly covers. -The subscriber judges a Range complete from what it observed: the Groups it received, the SUBSCRIBE_SKIP and SUBSCRIBE_DROP messages, the Range Starts in SUBSCRIBE_OK and SUBSCRIBE_STARTED, and SUBSCRIBE_FINISH. -Drops and Groups name absolute sequences, so the subscriber judges them against its latest Ranges, and an update still in flight changes nothing it has counted. +The subscriber judges a Range complete from what it observed: the Groups it received and the starts their `Previous Start` passed over, the SUBSCRIBE_SKIP and SUBSCRIBE_DROP messages, the Range Starts in SUBSCRIBE_OK and SUBSCRIBE_STARTED, and SUBSCRIBE_FINISH. +Drops and Groups name starts, so the subscriber judges them against its latest Ranges, and an update still in flight changes nothing it has counted. The publisher never closes its side first: a subscription whose every Range has an `End` other than None and whose every Group has been delivered, skipped, or dropped stays open for an update to widen it. A subscriber fills Groups it misses by asking for them as Ranges, adding them to an open subscription with SUBSCRIBE_UPDATE or opening a bounded SUBSCRIBE when none is open, rather than with a FETCH of each Group; FETCH remains for one Group, or a slice of one. -A publisher never sends a Group twice on one subscription, except to re-offer one whose stream it reset, so a Group the subscription already delivered or named in a final SUBSCRIBE_DROP is asked for with a SUBSCRIBE of its own. -A Group dropped with OLD that the subscriber still wants needs no new SUBSCRIBE: a SUBSCRIBE_UPDATE with a `Subscriber Max Age` its age does not reach reopens it on the same subscription (see [SUBSCRIBE_UPDATE](#subscribe-update)). +A publisher never sends a Group twice on one subscription, except to [continue](#yield) one, so a Group the subscription already delivered or named in a SUBSCRIBE_DROP is asked for with a SUBSCRIBE of its own. +That includes a Group dropped with OLD that the subscriber still wants, such as a relay reader whose `Subscriber Max Age` is wider than the one the drop was judged under: no SUBSCRIBE_UPDATE reopens a drop. The subscriber closes its side (FIN) once it wants nothing more from the subscription, and the publisher then closes its side (FIN), cancelling any Group Stream still open. -After SUBSCRIBE_FINISH, the subscriber SHOULD close its side once its tail accounting has settled: every received Group Stream has been read to its FIN, reset, or dropped, and every sequence in range has arrived, been named by SUBSCRIBE_SKIP or SUBSCRIBE_DROP, or exhausted the subscriber's grace period. +After SUBSCRIBE_FINISH, the subscriber SHOULD close its side once its tail accounting has settled: every received Group Stream has been read to its FIN, reset, or dropped, and every start in range has arrived, been passed over by a [GROUP](#group-message)'s `Previous Start`, been named by SUBSCRIBE_SKIP or SUBSCRIBE_DROP, or exhausted the subscriber's grace period. A publisher closing its session gracefully MUST wait for the subscriber's FIN or reset on every Subscribe Stream before closing the connection; a transport acknowledgement alone does not confirm the subscriber read the tail. Either endpoint MAY reset the stream at any time. ### Fetch A subscriber opens a Fetch Stream (0x3) to request a single Group from a Track. -The subscriber sends a FETCH message containing the broadcast path, track name, priority, group sequence, and the frame range within that group. +The subscriber sends a FETCH message containing the broadcast path, track name, priority, group start, and the frame range within that group. Unlike SUBSCRIBE, FETCH works on both live and ended broadcasts; it is the only way to read an ended one. The publisher responds with FRAME messages directly on the same bidirectional stream - there is no response header. -The Group Sequence and index of the first returned frame are implicit, taken from the original FETCH request. +The Group Start and index of the first returned frame are implicit, taken from the original FETCH request. Because there is no response header, a publisher that cannot serve the requested frame range in full MUST reset the stream rather than return a shorter run; the subscriber has no way to learn where a truncated response actually started. As with a subscription, the subscriber MUST already have the track's [TRACK_INFO](#track-info) to parse the returned frames; because the properties are immutable, a single Track Stream lookup is reused across every FETCH of that track (group-by-group fetches do not re-fetch it). -The publisher FINs the stream after the last frame, or resets the stream on error. +The publisher ends the stream as a [Group Stream](#group-stream) ends: with a [GROUP_END](#group-end) and a FIN once the response reaches the end of a finished Group, with a FIN alone after the last frame requested or the last frame of a closed Group, or with a reset on error. Fetch behaves like HTTP: a single request/response per stream. @@ -672,12 +672,13 @@ A listing is discovery, not delivery: the subscriber SUBSCRIBEs to each Track it The subscriber sends a [TRACKS](#tracks) message naming the broadcast path and Instance. The publisher replies with listing events, then FINs the stream once the Broadcast ends, or resets it on error: -- [TRACKS_ADD](#tracks-add): a Track is listed, with its TRACK_INFO. +- [TRACKS_ADD](#tracks-add): a Track is listed, with its kind and its TRACK_INFO or DATAGRAMS_INFO. - [TRACKS_REMOVE](#tracks-remove): a listed Track no longer is, without having finished. - [TRACKS_FINISH](#tracks-finish): a listed Track no longer is because it finished. - [SYNCED](#synced): every Track this hop listed when the stream opened, and still lists, has been sent. -A Broadcast lists the Tracks its publisher produces, except datagram Tracks, which are never listed: TRACK_INFO does not say which kind a Track is, so a subscriber could not tell whether to SUBSCRIBE or send DATAGRAMS. +A Broadcast lists the Tracks its publisher produces, datagram Tracks included. +A listing names a Track by its kind and name, since the two kinds have separate namespaces, and the kind tells the subscriber whether to SUBSCRIBE or send DATAGRAMS. A Track the publisher serves only on request, such as any name a transcoder answers for, is never listed, and listing never creates one. A removal, either TRACKS_REMOVE or TRACKS_FINISH, promises only that the Track is no longer listed; a SUBSCRIBE for its name MAY still succeed. TRACKS_FINISH says the Track's publisher declared its end, so its Groups are all the Track will hold; TRACKS_REMOVE says it left unfinished, such as a publisher that went away or a claim that was withdrawn, so it may go on elsewhere. @@ -692,7 +693,7 @@ The publisher MAY coalesce changes to a name it has not yet sent, but never omit It sends SYNCED exactly once, after every Track it listed when the stream opened and still lists, and sends no more events before SYNCED than it listed then. A removal of a Track already sent MAY precede SYNCED. -The subscriber MUST close the session with a PROTOCOL_VIOLATION on a TRACKS_ADD for a name already listed on the stream, a TRACKS_REMOVE or TRACKS_FINISH for a name not listed, a second SYNCED, or an unknown event type. +The subscriber MUST close the session with a PROTOCOL_VIOLATION on a TRACKS_ADD for a kind and name already listed on the stream, a TRACKS_REMOVE or TRACKS_FINISH for a kind and name not listed, a second SYNCED, or an unknown event type or kind. A FIN before SYNCED means the Broadcast ended. A publisher MUST reset a Tracks Stream with NOT_FOUND when the claim it would serve the path from covers it by a shorter prefix: a claim asserts capability, not inventory, so it names no Broadcast to list. A subscriber MAY skip the Track Stream for a Track it learned from TRACKS_ADD, since the properties are the same immutable ones. @@ -810,7 +811,7 @@ The subscriber priority takes precedence, so the subscriber can likewise full-sc ### Group Order Within a subscription, a publisher SHOULD transmit pending Groups in the subscriber's `Group Order`: newest first when descending (the default), oldest first when ascending. -Descending sheds the backlog rather than the live edge under congestion, which is what a Group boundary exists to make possible; ascending drains a backlog in sequence order, for catch-up. +Descending sheds the backlog rather than the live edge under congestion, which is what a Group boundary exists to make possible; ascending drains a backlog in start order, for catch-up. `Group Order` only orders transmission; it never decides whether a Group is delivered, which is [Expiration](#expiration)'s job. An ascending subscriber SHOULD raise its `Subscriber Max Age` so the backlog it intends to drain is not expired first. @@ -820,21 +821,21 @@ A subscriber MUST support gaps and out-of-order delivery regardless. ## Expiration Expiration governs when an older group is dropped. -The publisher SHOULD reset Group Streams for non-latest groups whose age reaches `Subscriber Max Age` (see [SUBSCRIBE](#subscribe), and the age definition below); the subscriber MAY also locally drop such groups. +The publisher SHOULD stop sending non-latest groups whose age reaches `Subscriber Max Age` (see [SUBSCRIBE](#subscribe), and the age definition below); the subscriber MAY also locally drop such groups. Expiration only removes the group from live delivery; the publisher MAY still retain it for FETCH or new subscriptions until its age exceeds `Publisher Max Age` (see [TRACK_INFO](#track-info)). A FETCH can additionally carry `Subscriber Max Age`; it can tighten, but never relax, the publisher bound. 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 its **successor** has arrived: the next group by sequence number that has arrived at this hop and was not reset. +A group is never expired until its **successor** has arrived: the next group by start that has arrived at this hop and was not reset. The latest group has no successor, so it is never expired. A group is expired once either of two ages meets the relevant `Max Age`: - Its **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. - Its **arrival age** is the time elapsed since its successor arrived at this hop. -A group of an untimed Track has no timestamps, so arrival age alone expires it. +On a scale-less Track, timestamp age counts bare units as the milliseconds of a Max Age. By timestamp age, 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. Arrival age needs no such proof: it bounds how long a superseded group may still wait to be delivered. @@ -842,20 +843,20 @@ 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 presented a frame therefore has no timestamp age, because nothing yet proves where it stops. +A group's **reach** is its own end once it finished (see [GROUP_END](#group-end)), and otherwise the first frame timestamp of the next group by start, or unbounded when no later group has presented a frame. +A group cannot present past its end or where its successor begins, so this is the furthest it could still reach. +Its frames alone 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. +An unfinished group whose successor has not presented a frame therefore has no timestamp age, 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. Timestamp age means a burst of groups delivered together still reads as its true age, so catching up never resets the clock. -Arrival age bounds what timestamps cannot: a publisher whose timestamps stop advancing, a successor that never presents a frame, an untimed Track, and a run of empty groups. +Arrival age bounds what timestamps cannot: a publisher whose timestamps stop advancing, a successor that never presents a frame, and a run of empty groups. -An expired group SHOULD be reset at the QUIC level to avoid consuming flow control. -A publisher MUST NOT finish (FIN) the Group Stream of an expired group that has not finished at this hop, even after sending every frame it holds; it resets with OLD instead, since a FIN claims the group is whole. +A publisher stops sending an expired group: it closes the group's open Group Stream without a GROUP_END, and names a group it opened no stream for in a [SUBSCRIBE_DROP](#subscribe-drop) with OLD. +The subscriber keeps the frames that arrived, and a GROUP_END never claims an expired group whole. ## Unidirectional Streams Unidirectional streams are used for data transmission. @@ -867,8 +868,6 @@ Unidirectional streams are used for data transmission. | ------ | -------- | ----------- | | 0x1 | Setup | Either | | ------ | -------- | ----------- | -| 0x2 | Padding | Either | -| ------ | -------- | ----------- | ### Setup {#setup-stream} Each endpoint MUST open a Setup Stream (0x1) at the start of the session to advertise the optional capabilities and extensions it supports. @@ -877,24 +876,19 @@ The opener sends a single SETUP message and immediately closes the stream (FIN). There is exactly one Setup Stream per direction; an endpoint that receives a second Setup Stream MUST close the session with a PROTOCOL_VIOLATION. An endpoint with no optional capabilities sends a SETUP with an empty parameter list rather than omitting the stream, giving the peer a deterministic signal that no capabilities are forthcoming. -### Padding {#padding-stream} -Either endpoint MAY open a Padding Stream (0x2), followed by arbitrary bytes until FIN. -The receiver MUST read and discard those bytes incrementally, returning stream and connection flow-control credit as they arrive without retaining the body. -Receiving padding does not change session or subscription state. -This allows bandwidth probes to measure delivery without requiring a media subscription. - -### Group +### Group {#group-stream} A publisher creates Group Streams in response to a Subscribe Stream. -A Group Stream MUST start with a GROUP message and MAY be followed by any number of FRAME messages. +A Group Stream MUST start with a GROUP message and MAY be followed by any number of FRAME messages, then a GROUP_END if the Group finished. A Group MAY contain zero FRAME messages, potentially indicating a gap in the track. A frame MAY contain an empty payload, potentially indicating a gap in the group. The GROUP message's `Frame Start` gives the index of the first FRAME on the stream, so a stream carrying only part of a Group is self-describing. -A publisher MUST NOT send two Group Streams for the same Group Sequence on one subscription, except to re-offer a Group whose stream it reset (see [SUBSCRIBE_DROP](#subscribe-drop)), or to [continue](#yield) one. -The re-offer can arrive before that reset: a subscriber holds a Group Stream for a sequence whose earlier stream is still arriving unread until that stream ends, then discards it if the earlier stream completed the Group, or reads it if the earlier stream was reset. -Since the publisher reset the earlier stream, the subscriber MAY instead end that stream at once and read the later one, ignoring the frames it holds; a browser can lose a reset that reaches a stream before its application does. +A publisher ends a Group Stream the way its Group ended (see [Group](#group)): with a GROUP_END and a FIN for a finished Group, with a FIN alone for a closed one, and with a reset for an aborted one. +A publisher MUST NOT send a GROUP_END for a Group that has not finished at this hop, and a subscriber treats bytes after a GROUP_END as a malformed Track. + +A publisher MUST NOT send two Group Streams for the same Group Start on one subscription, except to [continue](#yield) one. A subscriber assembling a Group from more than one publisher does so across separate subscriptions, and is responsible for concatenating the runs in index order and for ignoring any frame it has already received. Both the publisher and subscriber MAY reset the stream at any time. @@ -909,7 +903,7 @@ Any other Group Stream may be, including one on a session with the extension: a A Group whose stream was reset with YIELDED is paused, not given up: the subscriber keeps the frames it received, and the publisher MUST later continue the Group on another Group Stream or name it in [SUBSCRIBE_DROP](#subscribe-drop). A continuation is a Group Stream for the paused Group whose `Frame Start` is the reset stream's own `Frame Start`, since a reset can discard frames the transport acknowledged. The subscriber ignores the frames it already holds, including the part of a frame the reset cut short, and appends the rest; a continuation that starts past the frames it holds whole is malformed. -A continuation MAY overtake the earlier stream's reset, and waits unread until that stream ends, or ends it, as for a re-offer. +A continuation MAY overtake the earlier stream's reset, and waits unread until that stream ends; since the publisher reset that stream, the subscriber MAY instead end it at once and read the continuation, ignoring the frames it holds, as a browser can lose a reset that reaches a stream before its application does. A subscriber whose transport reports a Group Stream's reset without its error code, as a browser can, pauses the Group as for YIELDED: the publisher's continuation or SUBSCRIBE_DROP settles it. ## Datagrams @@ -918,7 +912,7 @@ They carry the datagrams of a datagram Track: each has the Track's own Sequence A datagram is never cached, stored, retransmitted, or returned by FETCH, and a subscriber receives one only through a [Datagrams Stream](#datagrams-stream). A publisher SHOULD drop a datagram rather than block when the transport has no room for it. -Every datagram begins with a Type (i): 0x0 for a Track Datagram, or 0x1 for a Padding Datagram. +Every datagram begins with a Type (i): 0x0 for a Track Datagram, the only type this version defines. A receiver MUST discard a datagram with an unknown type. The total datagram body, including Type, MUST NOT exceed 1200 bytes; a sender MUST NOT send a larger one and a receiver MUST silently drop it. @@ -931,32 +925,26 @@ DATAGRAM Body { Type (i) = 0x0 Subscribe ID (i) Sequence (i) - [Timestamp (i)] + Timestamp (i) Payload (b) } ~~~ **Subscribe ID**: The Subscribe ID of an active Datagrams Stream on the same session. -A subscriber MUST silently drop a datagram with an unknown Subscribe ID, or one that arrives before its stream's DATAGRAMS_INFO, since it cannot tell whether a Timestamp follows. +A subscriber MUST silently drop a datagram with an unknown Subscribe ID, or one that arrives before its stream's DATAGRAMS_INFO, since it cannot read the Timestamp without the Track's `Timescale`. **Sequence**: The datagram's sequence number within its datagram Track, which the publisher assigns in the order it produces them. It is the Track's own, not a Group Sequence, and names no cached content: a Sequence may repeat, as from a restarted publisher, and a subscriber delivers a repeat like any other datagram. **Timestamp**: -The absolute presentation timestamp of the datagram, in the Track's `Timescale`. -Present only when DATAGRAMS_INFO's `Timescale` is not 0; on a Track with a `Timescale` of 0, the Sequence stands in for the datagram's time. +The absolute presentation timestamp of the datagram, in the Track's `Timescale`, or a bare number on a Track with a `Timescale` of 0. **Payload**: The payload, extending to the end of the datagram. A payload that does not fit is not sent. -### Padding Datagram - -Either endpoint MAY send a Padding Datagram (0x1), followed by arbitrary bytes to the datagram boundary. -A receiver MUST discard it without changing session or subscription state. - # Encoding This section covers the encoding of each message. Unless specified otherwise, `(s)` is UTF-8 text and `(b)` is raw bytes, each prefixed by its byte length as an `(i)`. @@ -1596,7 +1584,6 @@ SUBSCRIBE Message { Subscriber Min Age (i) Range Count (i) Range (..) ... - Update (i) } Range { @@ -1606,9 +1593,8 @@ Range { Anchor { Anchor Type (i) - [Group Sequence (i)] - [Groups Back (i)] [Timestamp (i)] + [Groups Back (i)] } ~~~ @@ -1631,10 +1617,10 @@ Any other value is a PROTOCOL_VIOLATION. See the [Group Order](#group-order) 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, as defined in [Expiration](#expiration), reaches this duration. +The subscriber's preference for how long a non-latest group may remain in flight before being considered stale and dropped from live delivery, encoded as milliseconds plus one; `0` means no limit. +The publisher SHOULD stop sending groups whose age, as defined in [Expiration](#expiration), reaches this duration. Applies only to non-latest groups; the latest group is never dropped on staleness grounds. -A value of `0` means the subscriber wants only the latest group in live delivery (older groups are immediately stale once a newer group arrives). +An encoded value of `1` declares a duration of zero: the subscriber wants only the latest group in live delivery (older groups are immediately stale once a newer group arrives). This is a delivery-time preference, not a retention rule: the publisher MAY still hold these groups for FETCH or future subscriptions (see `Publisher Max Age` in [TRACK_INFO](#track-info)). See the [Expiration](#expiration) section for more information. @@ -1657,21 +1643,17 @@ Each Range implicitly takes the next Range ID on the stream, starting at 0, whic Which fields follow, and what the Anchor names: - None (0x0): no fields. As a `Start`, the oldest Group (no floor); as an `End`, the live edge (unbounded). -- Absolute (0x1): `Group Sequence`. A `Start` delivers from that Group and an `End` stops just before it. -- Relative (0x2): `Groups Back`, the Group that many before the latest, 0 being the latest. Included as an `End`. -- Time (0x3): `Timestamp`, the Group containing that time: the one whose sequence, its start (see [Group](#group)), is the highest at or below it. Included as an `End`. +- Time (0x1): `Timestamp`, the Group containing that time: the one whose start (see [Group](#group)) is the highest at or below it. +- Relative (0x2): `Groups Back`, the Group that many before the latest, 0 being the latest. Any other value is a PROTOCOL_VIOLATION. +Both ends include the Group they name, so a Range from Time `a` to Time `b` delivers every Group from the one containing `a` through the one containing `b`. The publisher resolves a Relative or Time Anchor against the Track as it holds it. A Range resolves once: an update that leaves it live does not resolve it again. -**Update**: -The number of the subscription's terms this message sets: 0 on SUBSCRIBE, and on each SUBSCRIBE_UPDATE a larger value than the one before it. -A [SUBSCRIBE_DROP](#subscribe-drop) echoes the number in effect when its groups were given up, so the subscriber can tell a stale verdict on its current terms from one an update has since replaced. - A `Start` is a floor, not a request; `Subscriber Max Age` is the only thing that asks for data. The publisher SHOULD start at the oldest group at or above the floor that [Expiration](#expiration) has not expired, and MUST NOT deliver an older one. -A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale. +A `Subscriber Max Age` of zero therefore starts at the latest group, since every older group is already stale. A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree. A floor above the latest group simply waits there: that is a resumed subscription naming where it left off. Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). @@ -1684,9 +1666,8 @@ A subscriber MAY send multiple SUBSCRIBE_UPDATE messages to update the subscript Every field but the Ranges restates the subscription, and the latest one applies. The Ranges are an edit, growing or shrinking the subscription: the update retires the live Ranges it names by Range ID, then adds its own, each taking the next Range ID. Lowering a `Start` covers the groups below the old one that the publisher still holds, not only those that arrive later; a group already sent is not sent again. -Growing the subscription asks for what it newly covers: the publisher MUST serve the newly covered Groups it holds and never delivered on this subscription. -Every SUBSCRIBE_UPDATE, whatever it changes, reopens every stale (OLD) SUBSCRIBE_DROP sent before it: the publisher MUST serve each Group named in one that it still holds, that the new terms cover, and that is no longer stale under them, and MUST name each that is still stale in a SUBSCRIBE_DROP carrying the new `Update`. -A SUBSCRIBE_DROP with any other Error Code is final, and no update reopens it. +Growing the subscription asks for what it newly covers: the publisher MUST serve the newly covered Groups it holds and never delivered or dropped on this subscription. +No update reopens a Group the subscription already delivered or named in a SUBSCRIBE_DROP, whatever its Error Code, even one an update makes no longer stale. A SUBSCRIBE_UPDATE never resets the subscription, since a reset would race Group Streams already in flight, and shrinking it sends no SUBSCRIBE_SKIP or SUBSCRIBE_DROP. ~~~ @@ -1700,13 +1681,11 @@ SUBSCRIBE_UPDATE Message { Range ID (i) ... Range Count (i) Range (..) ... - Update (i) - Wanted Group (i) + Wanted Start (i) } ~~~ See [SUBSCRIBE](#subscribe) for information about each field. -An `Update` no larger than the previous one only confuses the subscriber's own accounting of stale drops; the publisher echoes the latest value it read. **Remove Count** and **Range ID**: The live Ranges to retire. @@ -1717,11 +1696,11 @@ The Ranges to add, which may be none. The live Ranges after the edit MUST NOT be empty, and MUST fit in one SUBSCRIBE: once encoded they take at most 65,535 bytes. A publisher closes the session with a PROTOCOL_VIOLATION otherwise. -**Wanted Group**: -The newest group the subscriber's live-edge joins want, encoded as the sequence plus one; `0` means none. +**Wanted Start**: +The newest group start the subscriber's live-edge joins want, plus one; `0` means none. Like the other fields, it is subscription state: every SUBSCRIBE_UPDATE restates it, and the latest one applies. -A publisher MUST ignore a value at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. -A new SUBSCRIBE itself counts as a join and needs no Wanted Group field. +A publisher MUST ignore a value at or below its largest group's start, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. +A new SUBSCRIBE itself counts as a join and needs no Wanted Start field. ## TRACK TRACK is sent by a subscriber to request a Track's immutable publisher properties. @@ -1797,15 +1776,15 @@ The unit is milliseconds, matching `Subscriber Max Age`. See the [Expiration](#expiration) section for more information. **Timescale**: -The number of timestamp units per second for frame timestamps on this Track, or `0` for an untimed Track, whose FRAME messages carry no timestamp. +The number of timestamp units per second for frame timestamps and Group starts on this Track, or `0` for a scale-less Track, whose timestamps are bare numbers (see [Frame](#frame)). Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` (audio sample rate), and `90000` (RTP video clock). **Refresh**: An optional unsigned 32-bit byte ratio, encoded as the ratio plus one; `0` disables refresh. -On a live-edge join, a publisher asks for a group beyond every sequence already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. +On a live-edge join, a publisher asks for a group beyond every start already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. Joins coalesce until the requested group arrives. The request does not hold back delivery: the joiner still receives the newest cached group while it is pending. -A relay forwards its joins' demand in SUBSCRIBE_UPDATE's `Wanted Group`. +A relay forwards its joins' demand in SUBSCRIBE_UPDATE's `Wanted Start`. **Compression**: How each Group of this Track is compressed: none (0x0), or DEFLATE (0x1), each Group one DEFLATE stream as specified by {{moqflate}}. @@ -1841,16 +1820,22 @@ A publisher sends TRACKS_ADD on a Tracks Stream when a Track is listed. TRACKS_ADD Message { Type (i) = 0x0 Message Length (i) + Kind (i) Track Name (s) - Track Info (..) + Info (..) } ~~~ +**Kind**: +Which kind of Track is listed: a Track of Groups (0x0) or a datagram Track (0x1). +Any other value is a PROTOCOL_VIOLATION. + **Track Name**: -The name of the Track, unique among the Tracks listed on the stream. +The name of the Track, unique among the Tracks of its kind listed on the stream. -**Track Info**: -A [TRACK_INFO](#track-info) message, with its own Message Length, as a Track Stream would answer for the Track. +**Info**: +For a Track of Groups, a [TRACK_INFO](#track-info) message, with its own Message Length, as a Track Stream would answer for the Track. +For a datagram Track, a [DATAGRAMS_INFO](#datagrams-info) message, with its own Message Length, as a Datagrams Stream would answer for it. ## TRACKS_REMOVE {#tracks-remove} A publisher sends TRACKS_REMOVE on a Tracks Stream when a listed Track is no longer listed. @@ -1859,12 +1844,13 @@ A publisher sends TRACKS_REMOVE on a Tracks Stream when a listed Track is no lon TRACKS_REMOVE Message { Type (i) = 0x1 Message Length (i) + Kind (i) Track Name (s) } ~~~ -**Track Name**: -The name a TRACKS_ADD on the stream listed. +**Kind** and **Track Name**: +The kind and name a TRACKS_ADD on the stream listed. ## TRACKS_FINISH {#tracks-finish} A publisher sends TRACKS_FINISH on a Tracks Stream when a listed Track is no longer listed because it finished: its publisher declared its end. @@ -1873,12 +1859,13 @@ A publisher sends TRACKS_FINISH on a Tracks Stream when a listed Track is no lon TRACKS_FINISH Message { Type (i) = 0x2 Message Length (i) + Kind (i) Track Name (s) } ~~~ -**Track Name**: -The name a TRACKS_ADD on the stream listed. +**Kind** and **Track Name**: +The kind and name a TRACKS_ADD on the stream listed. ## DATAGRAMS {#datagrams-message} DATAGRAMS is sent by a subscriber to subscribe to a datagram Track. @@ -1939,6 +1926,7 @@ SUBSCRIBE_OK Message { Message Length (i) Largest Group (i) [Largest Frame (i)] + [Largest Ended (8)] Range Start Count (i) Range Start (i) ... } @@ -1949,18 +1937,23 @@ Set to 0x0 to indicate a SUBSCRIBE_OK message. **Largest Group** and **Largest Frame**: The largest position the publisher knows of for the track when it answers: the last frame that exists, like moq-transport's Largest Location, including one a relay's source reported that has yet to arrive. -`Largest Group` is the group sequence plus one, and 0 means the track has nothing yet, in which case `Largest Frame` is absent. +`Largest Group` is the group's start plus one, and 0 means the track has nothing yet, in which case `Largest Frame` and `Largest Ended` are absent. A subscriber takes it as where the live feed is: a relay holding groups from an earlier subscription serves them from cache only once this says they are current, which a publisher answering promptly lets it do without waiting for a frame. +**Largest Ended**: +Whether the largest group has ended: 0x1 when it finished, closed, or was aborted, so no frame follows `Largest Frame`, and 0x0 when it may still grow. +Any other value is a PROTOCOL_VIOLATION. +A subscriber joining a Track whose newest group ended knows at once that the group is not the live one, without waiting for its stream to end. + **Range Start**: -One per Range of the SUBSCRIBE, in Range ID order: the Group where the Range's delivery starts, plus one, so a subscriber learns where a Relative or Time Anchor landed. +One per Range of the SUBSCRIBE, in Range ID order: the start of the Group where the Range's delivery starts, plus one, so a subscriber learns where a Relative or Time Anchor landed. 0 means the Range has no Group to deliver, including one an update retired before the answer. The Range's Groups from this one are owed as described in [SUBSCRIBE_DROP](#subscribe-drop); an earlier one is not, though it MAY still arrive. A subscriber MUST treat a `Range Start Count` other than the SUBSCRIBE's `Range Count` as a PROTOCOL_VIOLATION. A Range an update adds has its start reported by [SUBSCRIBE_STARTED](#subscribe-started) instead, even one added before SUBSCRIBE_OK. ## SUBSCRIBE_FINISH {#subscribe-finish} -A SUBSCRIBE_FINISH message is sent by the publisher to signal that no group at or after a given sequence will be produced. +A SUBSCRIBE_FINISH message is sent by the publisher to signal that no group at or after a given start will be produced. It ends the Track, not the subscription: the Subscribe Stream stays open (see [Subscribe](#subscribe)). ~~~ @@ -1976,15 +1969,15 @@ SUBSCRIBE_FINISH Message { Set to 0x1 to indicate a SUBSCRIBE_FINISH message. **Group**: -The exclusive end of the range: the absolute sequence number of the first group that will never be delivered. +The exclusive end of the Track: one past the start of its last group, so no group starts at or after it. A value of 0 means the track ended before producing any groups. -The subscriber MUST NOT wait for any group at or after this sequence. +The subscriber MUST NOT wait for any group starting at or after it. **Error Code**: 0 if the track ended cleanly, otherwise the stream error code it ended with plus 1. Groups below the end stay deliverable either way; a subscriber reaching the end surfaces the error instead of a clean end, and a relay forwards it with the end. -The publisher SHOULD send SUBSCRIBE_FINISH as soon as the exclusive final group is known, even while lower groups are still in flight. +The publisher SHOULD send SUBSCRIBE_FINISH as soon as the end is known, even while lower groups are still in flight. ## SUBSCRIBE_STARTED {#subscribe-started} A SUBSCRIBE_STARTED message resolves where a Range that a [SUBSCRIBE_UPDATE](#subscribe-update) added starts. @@ -2014,84 +2007,69 @@ A Range retired before its start resolved gets none. ## SUBSCRIBE_DROP {#subscribe-drop} -A publisher names groups that existed but that it will not deliver with SUBSCRIBE_DROP on the Subscribe Stream: an aborted or reset group, one evicted or expired with no copy left to serve it, or one past the subscriber's budget (OLD). -Sequences the publisher declared it will never produce are named by [SUBSCRIBE_SKIP](#subscribe-skip) instead. -A sequence the publisher never had but never declared skipped, such as a gap between the Groups it created or one a relay never received, might have existed, so it is named in SUBSCRIBE_DROP: with OLD when it is past the subscriber's budget, otherwise with NOT_FOUND. +A publisher names starts where it holds a group it will not deliver, or holds none to deliver, with SUBSCRIBE_DROP on the Subscribe Stream: an aborted or reset group, one evicted or expired with no copy left to serve it, or one past the subscriber's budget (OLD). +Starts the publisher declared it will never produce are named by [SUBSCRIBE_SKIP](#subscribe-skip) instead. +A start the publisher never had but never declared skipped, such as a gap between the Groups it created or one a relay never received, might have held a group, so it is named in SUBSCRIBE_DROP: with OLD when it is past the subscriber's budget, otherwise with NOT_FOUND. ~~~ SUBSCRIBE_DROP Message { Type (i) = 0x2 Message Length (i) Group Start (i) - Group Count (i) + Group End (i) Error Code (i) - Update (i) } ~~~ -**Group Start** and **Group Count** name the group sequences the publisher gave up: `Group Count` of them from `Group Start`. -A `Group Count` of 0 is an empty range, and a `Group Start + Group Count` above 2^64-1 is a PROTOCOL_VIOLATION. +**Group Start** and **Group End** name the span of starts the publisher gave up, from `Group Start` up to but not including `Group End`. +A span is a span of time, so it covers the gaps between the Groups in it as well as the Groups themselves. +A `Group End` at or below `Group Start` is a PROTOCOL_VIOLATION. **Error Code** is a [stream error code](#error-codes) saying why the groups were given up, as a reset retaining the Group Stream header would: for example OLD for one past the subscriber's budget, EVICTED for one the publisher no longer holds, or NOT_FOUND for one a relay never received. A subscriber MUST end the readers of a dropped group it holds with that error, including a group whose stream is still arriving, rather than end it cleanly. -A stale (OLD) drop is the exception: it ends no group whose Group Stream arrived, since that stream wins over it (see below), and a publisher that gives up a stream it opened resets it. - -**Update**: -The [SUBSCRIBE](#subscribe) or [SUBSCRIBE_UPDATE](#subscribe-update) `Update` in effect when the publisher gave the groups up. -A subscriber MUST treat an `Update` larger than the last one it sent as a PROTOCOL_VIOLATION. -A drop whose Error Code is OLD is a stale verdict, which holds only under the update it names. -The subscriber judges it against the `Subscriber Max Age` it sent with that update, from its own record: the drop does not carry the budget. -A stale drop whose `Update` a later update has replaced is no verdict, since the update may have moved the Range or budget it was judged against: the subscriber still owes those groups, and a relay asks for such a group again rather than drop it for its own readers. -The next SUBSCRIBE_UPDATE reopens every stale drop the subscriber accounted for, which it owes again until the publisher serves the group or drops it again under the new `Update`, as described in [SUBSCRIBE_UPDATE](#subscribe-update). -A relay that received a stale drop settles with it only a reader whose own budget is no wider than the one the relay sent with that update and whose Ranges include every group the relay's own Ranges name above the dropped sequence, since the verdict on a group was judged against the groups above it. +Every drop is final on its subscription: no SUBSCRIBE_UPDATE reopens it, and a subscriber that still wants a dropped group asks for it with a SUBSCRIBE of its own. +An OLD drop was judged against the `Subscriber Max Age` in effect when the publisher gave the group up, which the drop does not carry. +A relay that received one settles with it only a reader whose own budget is no wider than the subscription's and whose Ranges include every group the relay's own Ranges name above the dropped start, since the verdict on a group was judged against the groups above it; it asks again for a reader the drop does not settle. -A drop with any other Error Code is final, whatever its `Update`, and replaces a stale drop of the same sequences, so no update reopens them. - -A later [SUBSCRIBE_SKIP](#subscribe-skip) for the same sequences overrides a drop, whatever its Error Code: the subscriber records them as skipped from then on, and a relay forwards the skip even over a drop it already forwarded. +A later [SUBSCRIBE_SKIP](#subscribe-skip) or [GROUP](#group-message) `Previous Start` passing over the same starts overrides a drop, whatever its Error Code: the subscriber records them as skipped from then on, and a relay forwards the skip even over a drop it already forwarded. A subscriber that already ended readers on the drop does not deliver anything again: those readers stay ended. -A drop that follows a skip of the same sequences changes nothing. - -A Group Stream for a sequence the subscriber already saw dropped, as after such a re-offer, wins over the drop: the subscriber delivers it. -A Group Stream also wins over a stale drop of its sequence that arrives after it, since the stream can overtake a drop the publisher sent first. -Either way the Group Stream accounts for the sequence, and the next SUBSCRIBE_UPDATE does not reopen it: the publisher, having served it, neither serves it again nor names it in another drop. +A drop that follows a skip of the same starts changes nothing. -For every sequence in the subscription's range, the publisher MUST send a Group Stream or name it in SUBSCRIBE_SKIP or SUBSCRIBE_DROP. +For every start in the subscription's range, the publisher MUST send a Group Stream, pass over it with a Group Stream's `Previous Start`, or name it in SUBSCRIBE_SKIP or SUBSCRIBE_DROP. This includes streams reset before their headers were delivered, and streams the subscriber stopped (STOP_SENDING), which it may have discarded unread; such a drop carries the STOP_SENDING's Error Code. +A publisher that names a Group in a drop after opening its stream also names, in a SUBSCRIBE_SKIP sent before the drop, the skipped starts that stream's `Previous Start` passed over, since the GROUP may never arrive. A drop naming a stopped duplicate of a Group that another Group Stream already completed changes nothing for that Group: its readers keep it whole. A reliably delivered reset retaining the Group Stream header accounts for that group instead, unless it is YIELDED or answers a STOP_SENDING. A [paused](#yield) Group is accounted for only once a continuation completes it, a reset of one other than YIELDED ends it, or a SUBSCRIBE_DROP names it. -The publisher SHOULD name a sequence as soon as it gives it up, without waiting for SUBSCRIBE_FINISH. - -Before moq-lite-07, SUBSCRIBE_DROP carries an inclusive `Group End` in place of `Group Count`, where `Group Start = Group End + 1` is an empty range and a larger Group Start is a PROTOCOL_VIOLATION. -It carries no `Update`, its Error Code is application-specific, and it also names the sequences moq-lite-07 names in SUBSCRIBE_SKIP; every such drop is final. +The publisher SHOULD name a start as soon as it gives it up, without waiting for SUBSCRIBE_FINISH. ## SUBSCRIBE_SKIP {#subscribe-skip} -A publisher names sequences it declared it will never produce with SUBSCRIBE_SKIP on the Subscribe Stream. +A publisher names starts it declared it will never produce with SUBSCRIBE_SKIP on the Subscribe Stream. ~~~ SUBSCRIBE_SKIP Message { Type (i) = 0x3 Message Length (i) Group Start (i) - Group Count (i) + Group End (i) } ~~~ -**Group Start** and **Group Count** name the sequences that will never hold a group, as in [SUBSCRIBE_DROP](#subscribe-drop). +**Group Start** and **Group End** name the span of starts that will never hold a group, as in [SUBSCRIBE_DROP](#subscribe-drop). -A skip names only sequences the original publisher declared it will never produce, and it is final: no Group will ever exist at those sequences, whatever the terms. -A publisher MUST NOT later create a Group at a sequence it skipped, and a subscriber MUST NOT deliver a Group Stream for one. -It carries no error and ends no reader, since there is nothing to read; a subscriber stops waiting for those sequences. -A skip overrides an earlier SUBSCRIBE_DROP of the same sequences, whatever its Error Code, since never produced is the most authoritative account of a sequence: no update reopens them, and a relay forwards the skip downstream even over a drop it already forwarded. +A skip names only starts the original publisher declared it will never produce, and it is final: no Group will ever exist at those starts, whatever the terms. +A publisher MUST NOT later create a Group at a start it skipped, and a subscriber MUST NOT deliver a Group Stream for one. +It carries no error and ends no reader, since there is nothing to read; a subscriber stops waiting for those starts. +A skip overrides an earlier SUBSCRIBE_DROP of the same starts, whatever its Error Code, since never produced is the most authoritative account of a start, and a relay forwards the skip downstream even over a drop it already forwarded. A subscriber that already ended readers on that drop does not deliver anything again: those readers stay ended. -A skip never overrides a Group that arrived, since that Group was produced; a subscriber ignores a skip for such a sequence, which is a protocol error the publisher made, and MAY log it. +A skip never overrides a Group that arrived, since that Group was produced; a subscriber ignores a skip for such a start, which is a protocol error the publisher made, and MAY log it. -A gap in the sequence numbers says nothing on its own: a publisher may create Groups out of order, or create again a sequence whose Group it aborted, so it never skips a sequence merely because a higher Group exists or the Track ended without it. -Only the application producing the Track knows a sequence will never exist, for example when it numbers Groups sparsely, or when it moves on to the next Group and so declares that it will not go back to fill the sequences below. -A publisher SHOULD send the skip as soon as it declares it. -A relay forwards a skip it received unchanged, and never skips a sequence on its own: one it never received is named in SUBSCRIBE_DROP (see [SUBSCRIBE_DROP](#subscribe-drop)). +A gap between starts says nothing on its own: a publisher may create Groups out of order, or create again a start whose Group it aborted, so it never skips a start merely because a higher Group exists or the Track ended without it. +Only the application producing the Track knows a start will never hold a Group, for example when it moves on to the next Group and so declares that it will not go back to fill the starts below. +A publisher SHOULD send the skip as soon as it declares it, except for the skipped starts directly below a Group whose stream it opens on the subscription, which that stream's [GROUP](#group-message) `Previous Start` passes over instead. +A relay forwards a skip it received, or one a `Previous Start` declared, and never skips a start on its own: one it never received is named in SUBSCRIBE_DROP (see [SUBSCRIBE_DROP](#subscribe-drop)). ## FETCH FETCH is sent by a subscriber to request a single group from a track. @@ -2107,7 +2085,7 @@ FETCH Message { Track Name (s) Subscriber Priority (8) Subscriber Max Age (i) - Group Sequence (i) + Group Start (i) Frame Start (i) Frame End (i) } @@ -2130,8 +2108,8 @@ See the [Prioritization](#prioritization) section for more information. The optional maximum age in milliseconds that the subscriber accepts, encoded as the value plus one; 0 omits the reader bound. The publisher still applies `Publisher Max Age`, and MUST use the tighter bound while serving and while the returned group remains open. -**Group Sequence**: -The sequence number of the group to fetch. +**Group Start**: +The start of the group to fetch. **Frame Start**: The index of the first frame to return within the group (see [Positions](#positions)). @@ -2143,11 +2121,11 @@ A value of 0 means through the end of the group (default). A `Frame End` below `Frame Start` once decoded is a protocol violation; equal bounds are a legal single-frame range. The publisher responds with FRAME messages directly on the same stream - there is no response header. -The subscriber parses them using the track's [TRACK_INFO](#track-info), which it MUST already have (see the [Track Stream](#track-stream)); the group sequence and the index of the first frame are implicit from the FETCH request. -The publisher FINs the stream after the last frame, or resets on error. +The subscriber parses them using the track's [TRACK_INFO](#track-info), which it MUST already have (see the [Track Stream](#track-stream)); the group start and the index of the first frame are implicit from the FETCH request. +The publisher ends the stream with a GROUP_END and a FIN once the response reaches the end of a finished group, with a FIN alone after the last frame requested or the last frame of a closed group, or with a reset on error. There is no FETCH_ERROR message - the publisher signals failure by resetting the stream. A publisher holding fewer frames than requested MUST reset rather than truncate, since a short response is indistinguishable from one that started elsewhere. -A group that ends before `Frame End` is not a truncation: the publisher FINs after the last frame it has, provided the group is complete and it served everything from `Frame Start` onward. +A group that ends before `Frame End` is not a truncation: the publisher ends the stream after the last frame it has, provided the group finished or closed and it served everything from `Frame Start` onward. ## PROBE PROBE is used to measure the available bitrate of the connection. @@ -2287,14 +2265,15 @@ An acceptor that cannot decide SHOULD send one of the first three codes rather t A human-readable reason, at most 8,192 bytes. Invalid UTF-8 or a reason longer than 8,192 bytes is a PROTOCOL_VIOLATION that closes the session. -## GROUP +## GROUP {#group-message} The GROUP message contains information about a Group, as well as a reference to the subscription being served. ~~~ GROUP Message { Message Length (i) Subscribe ID (i) - Group Sequence (i) + Group Start (i) + Previous Start (i) Frame Start (i) } ~~~ @@ -2303,11 +2282,16 @@ GROUP Message { The corresponding Subscribe ID. This ID is used to distinguish between multiple subscriptions for the same track. -**Group Sequence**: -The sequence number of the group. -This SHOULD increase by 1 for each new group. +**Group Start**: +The start of the group (see [Group](#group)). A subscriber MUST handle gaps, potentially caused by congestion. +**Previous Start**: +The start of the Group before this one on the Track, plus one; `0` means the publisher does not know it, such as for the first Group after a restart or a Group created out of order. +No Group has a start between the two, so the subscriber accounts for the starts strictly between them as a [SUBSCRIBE_SKIP](#subscribe-skip) would, and a cache or reader sees a hole before this Group without a round trip. +A publisher knows it when the starts below this Group were declared skipped down to a Group, or a Group starts just below it. +A value at or above `Group Start` plus one is a malformed Track. + **Frame Start**: The index of the first FRAME message on this stream within the group (see [Positions](#positions)). A plain absolute index; 0 means the stream carries the group from its beginning, which is the common case. @@ -2321,7 +2305,7 @@ The FRAME message is a payload within a group. ~~~ FRAME Message { Payload Length (i) - [Timestamp Delta (i)] + Timestamp Delta (i) [Inflated Size (i)] Payload (b) } @@ -2329,13 +2313,10 @@ FRAME Message { **Payload Length**: The size of the payload on the wire, plus one. -A `Payload Length` of 0 is malformed. - -Before moq-lite-07, FRAME carries `Message Length`, the payload size without the plus one, after `Inflated Size` and `Timestamp Delta`. +A `Payload Length` of 0 is a [GROUP_END](#group-end) instead. **Timestamp Delta**: -A signed delta from the previous frame's timestamp, in the Track's negotiated `Timescale`. -Present only on a timed Track. +A signed delta from the previous frame's timestamp, in the Track's `Timescale`, or in bare units on a scale-less Track. Encoded as a zigzag-mapped variable-length integer: - Encode: `unsigned = (signed << 1) ^ (signed >> 63)` (arithmetic right shift). @@ -2352,6 +2333,25 @@ A receiver MUST check it against its limits before inflating, and MUST treat a p **Payload**: An application-specific payload. +## GROUP_END {#group-end} +GROUP_END ends a finished Group on a Group or Fetch Stream, after its last FRAME. +It shares FRAME's leading field, reserving the `Payload Length` value 0 that a FRAME never carries. + +~~~ +GROUP_END Message { + Payload Length (i) = 0 + End (i) +} +~~~ + +**End**: +The Group's exclusive end: the timestamp where it stops presenting, in the Track's `Timescale`, or a bare number on a scale-less Track. +It is greater than every frame timestamp in the Group and no greater than the next Group's start; a receiver treats an `End` at or below the Group's start as a malformed Track. + +A Group that ends with a GROUP_END is whole: every frame it will ever hold has been sent. +The publisher FINs the stream right after it, and a receiver treats any byte that follows as a malformed Track. +A stream that FINs without a GROUP_END carries a closed Group, which may have held more frames than arrived (see [Group](#group)). + # Appendix A: Changelog @@ -2366,11 +2366,9 @@ An application-specific payload. - Capped the Message Length of every message except FRAME at 65,535 bytes. SETUP parameter counts are bounded by Message Length, without a separate count cap. - Any Setup Stream or bidirectional stream message that fails to decode closes the session with PROTOCOL_VIOLATION; previously only an unexpected Message Length did, as a SHOULD. This includes a frame bound without its group bound, which previously reset only the stream. A stream ending mid-message outside the Setup and Auth Streams, a malformed GROUP or FRAME on a Group or Fetch Stream, and an unknown stream type still affect only that stream. - A session without a negotiated subprotocol negotiates the version in a draft-14 CLIENT_SETUP and SERVER_SETUP exchange. -- Added the reliable ordered RTCDataChannel binding, with one Qmux Record per binary message and no datagrams. - Added the SETUP `Implementation` parameter (0x6): the sender's software as `name/version` product tokens. - Added the client-only Token Setup Parameter (0x7), carrying the connection credential in SETUP instead of only the request URI. - Added the Route Key Setup Parameter (0x8): an Ed25519 public key and its signature over keying material exported from the session. -- Added Padding Stream (0x2), read and discarded incrementally by either endpoint. - A Report-level publisher reads and ignores PROBE targets instead of resetting the Probe Stream. - A GOAWAY recipient MAY keep opening requests on the current session until it has moved to a replacement session; previously it MUST NOT open new streams. The sender SHOULD keep answering them and MAY reset one with GOING_AWAY, which the recipient SHOULD retry on another route. @@ -2427,18 +2425,20 @@ An application-specific payload. - An open Track Stream is interest in the Track until the subscriber closes it, which a subscriber does once its Subscribe Stream has a response. - Named 128 the midpoint priority for an unset Subscriber or Publisher Priority. - Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit. -- Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Group`, carrying ratio-based refresh demand through relays. +- Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Start`, carrying ratio-based refresh demand through relays. - Added `Compression` to TRACK_INFO: none (0x0) or DEFLATE (0x1), whose Groups are DEFLATE streams per draft-lcurley-moq-flate. FRAME carries an `Inflated Size` when it is not none. -- An untimed Track declares a `Timescale` of 0 in TRACK_INFO, and its FRAME messages omit the timestamp. The published moq-lite-05 and moq-lite-06 treat a `Timescale` of 0 as invalid, so an untimed Track served over them is forced to declare milliseconds, and each FRAME carries its Group sequence as the timestamp. -- A publisher must not start a timed Group's frame 0 at or before a lower-sequence Group's, and a receiver may refuse a Group that does. A relay serves every Track's timestamps on as received. -- A Group's sequence is its start: frame 0's timestamp on a timed Track, and a growing number on an untimed one. A Time Anchor names the Group with the highest sequence at or below it, on an untimed Track too. +- A `Timescale` of 0 in TRACK_INFO declares a scale-less Track, whose timestamps and Group starts are bare numbers; each of its frames carries its Group's start as its timestamp. +- A publisher must not start a Group's frame 0 at or before that of a Group with a lower start, and a receiver may refuse a Group that does. A relay serves every Track's timestamps on as received. +- Replaced Group sequence numbers with Group starts: a Group is addressed by its frame 0's timestamp, or a bare number on a scale-less Track, and no field carries a sequence. A Time Anchor names the Group with the highest start at or below it. - Bounded every timestamp below 2^61. A larger one is a malformed Track. -- Reserved Group sequence 2^64-1: a publisher never creates it, and a Group Stream naming it is a malformed Track. +- Reserved Group start 2^64-1: a publisher never creates it, and a Group Stream naming it is a malformed Track. +- TRACKS_ADD, TRACKS_REMOVE, and TRACKS_FINISH carry a `Kind`, so a listing names datagram Tracks too, each with its DATAGRAMS_INFO. ### Subscriptions {#changelog-07-subscribe} -- Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, an absolute Group (exclusive as an end), a count of Groups back from the latest, or a presentation time. +- Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, a time naming the Group containing it, or a count of Groups back from the latest, and both ends include the Group they name. - Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1). +- Encoded `Subscriber Max Age` in SUBSCRIBE and SUBSCRIBE_UPDATE as milliseconds plus one, with zero meaning no limit. - Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A relay forwards the smallest stated value. - FETCH reads one Group or a slice of one, and SUBSCRIBE reads whole Groups: a read starting partway through a Group FETCHes it. A publisher holding only part of a Group a subscription covers drops it. - A SUBSCRIBE_UPDATE that lowers a `Start` covers the groups below the old start that the publisher still holds, not only those that arrive later. A group already sent is not sent again. @@ -2446,16 +2446,15 @@ An application-specific payload. - Each Range takes an implicit Range ID, and SUBSCRIBE_UPDATE edits the live Ranges instead of restating them: `Remove Count` Range IDs to retire, then the Ranges to add. The live Ranges must stay non-empty and fit in one SUBSCRIBE. A Range resolves its Anchors once, however many updates leave it live. - SUBSCRIBE_OK's Range Starts answer the SUBSCRIBE's Ranges, and added SUBSCRIBE_STARTED (type 0x4) resolving where each Range an update adds starts. - A subscriber fills missing Groups through Ranges on a subscription instead of a FETCH per Group, and asks for a Group a subscription already delivered or dropped, including one dropped with OLD, with a SUBSCRIBE of its own. -- Added `Largest Group` and `Largest Frame` to SUBSCRIBE_OK: the publisher's largest position when it answers, which a subscriber takes as where the live feed is. A publisher MUST answer at once when the requested start is past it. +- Added `Largest Group`, `Largest Frame`, and `Largest Ended` to SUBSCRIBE_OK: the publisher's largest position when it answers, which a subscriber takes as where the live feed is, and whether that Group has ended. A publisher MUST answer at once when the requested start is past it. - Renamed SUBSCRIBE_END to SUBSCRIBE_FINISH, matching TRACKS_FINISH: it ends the Track, not the subscription. - Added `Error Code` to SUBSCRIBE_FINISH: a track can end with an error while keeping the groups below its end. -- Restored SUBSCRIBE_DROP (type 0x2), replacing Stream Count on SUBSCRIBE_FINISH. Every sequence is accounted for by a Group Stream or a drop; a publisher SHOULD send a drop as soon as it gives a sequence up. +- Restored SUBSCRIBE_DROP (type 0x2), replacing Stream Count on SUBSCRIBE_FINISH. Every start is accounted for by a Group Stream or a drop; a publisher SHOULD send a drop as soon as it gives a start up. - SUBSCRIBE_DROP's Error Code is a stream error code, which ends the dropped groups' readers, including one still arriving. - A Group Stream the subscriber stopped (STOP_SENDING) is named in SUBSCRIBE_DROP with the STOP_SENDING's Error Code, even after a reliable reset. -- Refuse a SUBSCRIBE_DROP whose Group Start is greater than Group End plus one on every earlier version that carries it. -- SUBSCRIBE_DROP and SUBSCRIBE_SKIP carry `Group Start` and `Group Count` in place of an inclusive `Group End`. A range past 2^64-1 is a PROTOCOL_VIOLATION. -- Added SUBSCRIBE_SKIP (type 0x3) for sequences the publisher declared it will never produce, which ends no reader and is final: a Group is never created at a skipped sequence. A skip overrides an earlier drop of the same sequences, whatever its Error Code, without re-delivering to readers the drop already ended, and never overrides a Group that arrived. A gap in the sequence numbers is not a skip, since Groups may be created out of order; a sequence never had and never declared skipped is named in SUBSCRIBE_DROP. SUBSCRIBE_DROP no longer names declared skips. -- Added `Update` to SUBSCRIBE, SUBSCRIBE_UPDATE, and SUBSCRIBE_DROP: the number of the terms in effect. A stale (OLD) drop holds only under the update it names, judged against the budget the subscriber sent with it; every later SUBSCRIBE_UPDATE reopens it, and the publisher re-offers the group or drops it again under the new `Update`. Any other drop is final. A Group Stream wins over its earlier drop, and over a stale drop that arrives after it; no update reopens a sequence its Group Stream accounted for. A re-offered Group Stream that overtakes the reset of the stream it replaces waits, unread, until that stream ends, and is read only if it was reset. +- SUBSCRIBE_DROP and SUBSCRIBE_SKIP name a span of starts, from `Group Start` up to an exclusive `Group End`, in place of an inclusive `Group End`. An empty or inverted span is a PROTOCOL_VIOLATION. +- Added SUBSCRIBE_SKIP (type 0x3) for starts the publisher declared it will never produce, which ends no reader and is final: a Group is never created at a skipped start. A skip overrides an earlier drop of the same starts, whatever its Error Code, without re-delivering to readers the drop already ended, and never overrides a Group that arrived. A gap between starts is not a skip, since Groups may be created out of order; a start never had and never declared skipped is named in SUBSCRIBE_DROP. SUBSCRIBE_DROP no longer names declared skips. +- Every SUBSCRIBE_DROP is final on its subscription, OLD included: no SUBSCRIBE_UPDATE reopens a drop, and a subscriber that still wants the Group asks for it with a SUBSCRIBE of its own. - SUBSCRIBE_FINISH declares the final boundary while lower groups can still be in flight, and no longer closes the Subscribe Stream: the publisher keeps reading SUBSCRIBE_UPDATE, so an update can reach an ended Track's history. - A covered subscription, whose every Range has an End and whose every Group was sent or dropped, also stays open for an update; the publisher never FINs first. - A publisher that withheld SUBSCRIBE_OK sends it, then the drops it withheld, once no group can resolve the start: every Group of a bounded subscription was given up, or the Track finished. @@ -2464,9 +2463,12 @@ An application-specific payload. ### Delivery {#changelog-07-delivery} - Replaced group datagrams with datagram Tracks, a namespace apart from Tracks of Groups. A subscriber subscribes to one on the Datagrams Stream (0x9) with DATAGRAMS and DATAGRAMS_UPDATE, which carry only a priority, and the publisher answers with DATAGRAMS_INFO. A datagram carries the Track's own Sequence and a Timestamp, with no Group, Inflated Size, or Range. Datagrams no longer count toward SUBSCRIBE_DROP, and a subscriber no longer deduplicates them against Group Streams. -- Added a leading Type to datagrams: Track (0x0) or Padding (0x1), which either endpoint discards without changing session or subscription state. -- Expiration also measures a group's arrival age, the time since its successor arrived at this hop, so a group of an untimed Track expires by arrival age alone. -- A publisher resets the Group Stream of an expired, unfinished group with OLD rather than finishing it, even after sending every frame it holds. +- Added a leading Type to datagrams, 0x0 for a Track Datagram; a receiver discards one of an unknown Type. +- FRAME and datagrams always carry a timestamp, a bare number on a scale-less Track. +- Replaced GROUP's `Group Sequence` with `Group Start`, and added `Previous Start`, the start of the Group before it, so a subscriber sees the gap before a Group without a SUBSCRIBE_SKIP. +- Added GROUP_END, a `Payload Length` of 0 followed by the Group's exclusive end: a Group or Fetch Stream ends with it when its Group finished, a FIN alone ends a closed Group whose frames may not all exist, and a reset aborts. A Group's own end bounds its reach. +- Expiration also measures a group's arrival age, the time since its successor arrived at this hop. +- A publisher closes the open Group Stream of a group that expires, without a GROUP_END, rather than resetting it, and a relay closes a Group it holds only the start of. - Added [YIELDED](#yield) (0x3C): a publisher out of stream credit resets the lowest-priority Group Stream with it, which pauses the Group for a later Group Stream to continue from where the reset stream started. - A subscriber MAY end a Group Stream once a later stream for its Group arrives, rather than wait for its reset, and pauses a Group whose reset arrives without its error code as for YIELDED. - FRAME leads with `Payload Length`, the payload size plus one, in place of the trailing `Message Length`; 0 is malformed. @@ -2582,6 +2584,7 @@ A quick comparison of moq-lite and moq-transport-14: - Names use utf-8 strings instead of byte arrays. - Track Namespace is a string, not an array of any array of bytes. - Subscriptions default to the latest group, not the latest object. +- Groups are addressed by their start timestamp, not a Group ID. - No subgroups - No Object ID gaps - No object properties @@ -2626,6 +2629,7 @@ Some of these fields occur in multiple messages. - Expires - ContentExists - Parameters +- Group ID - Subgroup ID - Object ID - Object Status @@ -2633,7 +2637,7 @@ Some of these fields occur in multiple messages. # Security Considerations -moq-lite inherits the transport security of the underlying connection: QUIC and WebTransport provide confidentiality and integrity via TLS 1.3, the Qmux TCP and WebSocket bindings run over TLS, and the RTCDataChannel binding inherits DTLS security. How that connection is authenticated is out of scope (see [Connection](#connection)). The considerations below are specific to moq-lite. +moq-lite inherits the transport security of the underlying connection: QUIC and WebTransport provide confidentiality and integrity via TLS 1.3, and the Qmux TCP and WebSocket bindings run over TLS. How that connection is authenticated is out of scope (see [Connection](#connection)). The considerations below are specific to moq-lite. ## Bandwidth Probing The `Increase` Probe level (see [Probe Parameter](#probe-parameter)) lets a subscriber ask the publisher to pad the connection up to a target bitrate. A publisher MUST NOT treat the target as authorization to send beyond what congestion control allows: padding is bounded by the congestion window, so probing cannot be used to amplify traffic toward the subscriber or a spoofed address. Because all data flows on an established, congestion-controlled session to the connecting peer, moq-lite offers no off-path amplification vector. From 88087002d2fca3e0539847fe874d9f1dc63661dd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:30:08 -0800 Subject: [PATCH 03/26] feat(lite)!: lite-07 drops the Padding stream and datagram The Padding Stream (0x2) and Padding Datagram (0x1) leave lite-07. A datagram keeps its type, 0x0 the only one; any other is discarded. An unknown uni stream type is now stopped with UNEXPECTED_STREAM on every version rather than just dropped, so the peer learns of it at once, as JS already did. Co-Authored-By: Claude Opus 5.5 --- js/net/bench/lite-varint.ts | 15 +-- js/net/src/lite/connection.test.ts | 15 +-- js/net/src/lite/connection.ts | 3 - js/net/src/lite/datagram.test.ts | 21 +--- js/net/src/lite/datagram.ts | 16 +-- js/net/src/lite/stream.ts | 2 - js/net/src/lite/subscriber.ts | 2 - js/net/src/lite/version.ts | 29 +++--- rs/moq-net/src/fuzz.rs | 7 +- rs/moq-net/src/lite/datagram.rs | 53 +++------- rs/moq-net/src/lite/publisher.rs | 2 +- rs/moq-net/src/lite/stream.rs | 2 - rs/moq-net/src/lite/subscriber.rs | 154 +++++++++-------------------- rs/moq-net/src/lite/version.rs | 15 +-- rs/moq-net/src/test_interop.rs | 23 ----- test/interop/lite-padding.ts | 58 ----------- test/interop/lite-varint.ts | 18 ---- 17 files changed, 93 insertions(+), 342 deletions(-) delete mode 100644 test/interop/lite-padding.ts diff --git a/js/net/bench/lite-varint.ts b/js/net/bench/lite-varint.ts index 140d4a99789..671512f8b6d 100644 --- a/js/net/bench/lite-varint.ts +++ b/js/net/bench/lite-varint.ts @@ -15,7 +15,6 @@ let checksum = 0; /** A lite object: how the publisher writes it and how the subscriber reads it back. */ interface Sample { name: string; - versions?: Version[]; encode(w: Writer, version: Version): Promise; decode(r: Reader, version: Version): Promise; } @@ -83,16 +82,6 @@ const datagram: Sample = { decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version, () => ({ timed: true }))), }; -const padding: Sample = { - name: "Padding Datagram", - versions: [Version.DRAFT_07], - async encode(w) { - await w.u53(1); - await w.write(new Uint8Array(1199)); - }, - decode: datagram.decode, -}; - const hop = randomHop(); const setup: Sample = { name: "Setup", @@ -139,8 +128,8 @@ const sink = () => }); console.log("sample,version,bytes,encode_ns,decode_ns"); -for (const sample of [video, audio, group, subscribe, datagram, padding, setup]) { - for (const version of sample.versions ?? versions) { +for (const sample of [video, audio, group, subscribe, datagram, setup]) { + for (const version of versions) { const bytes = await wire(sample, version); const encode = await time(async () => { const w = new Writer(sink(), version); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 88e89d64336..d2b32ed5e6c 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -919,13 +919,14 @@ test("a malformed complete GOAWAY closes the session", async () => { } }); -// Each write is backpressured until the receiver reads it, before FIN is sent. +// A stream type the version doesn't define, such as lite-07's removed padding (0x2), is +// stopped without ending the session. for (const [alpn, version] of [ [ALPN_05, Version.DRAFT_05], [ALPN_06, Version.DRAFT_06], [ALPN_07_WIP, Version.DRAFT_07], ] as const) { - test(`padding is discarded only on lite-07: ${alpn}`, async () => { + test(`an unknown stream type is stopped: ${alpn}`, async () => { const pair = createMockTransportPair(alpn); const connection = new Connection({ url: new URL("https://relay.example/"), @@ -939,15 +940,9 @@ for (const [alpn, version] of [ const writer = new Writer(await pair.client.createUnidirectionalStream(), version); try { await writer.u53(2); - if (version === Version.DRAFT_07) { - for (let i = 0; i < 32; i++) await writer.write(new Uint8Array(4096)); - writer.close(); - await writer.closed; - } else { - await expect(writer.closed).rejects.toThrow(); - } + await expect(writer.closed).rejects.toThrow(); expect(closed).toBe(false); - // A subsequent stream is still handled after the padding finishes or resets. + // A subsequent stream is still handled. const goaway = await Stream.open(pair.client, { version }); await goaway.writer.u53(StreamId.Goaway); await new Goaway("").encode(goaway.writer, version); diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index 3e3ed288aed..14fbd2a154c 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -41,7 +41,6 @@ import { hasDatagramTracks, hasGoaway, hasHidden, - hasPadding, hasProbeRtt, hasRouteKey, hasRoutes, @@ -564,8 +563,6 @@ export class Connection implements Session { if (typ === DataType.Group) { const msg = await Group.decode(stream, this.#version); await this.#subscriber.runGroup(msg, stream); - } else if (typ === DataType.Padding && hasPadding(this.#version)) { - await stream.discard(); } else if (typ === DataType.Setup) { // Claim the stream before decoding, so two incomplete SETUPs are duplicates too. if (this.#setupSeen) throw new ProtocolViolation("duplicate SETUP"); diff --git a/js/net/src/lite/datagram.test.ts b/js/net/src/lite/datagram.test.ts index b0eaad6156d..4ee49a61deb 100644 --- a/js/net/src/lite/datagram.test.ts +++ b/js/net/src/lite/datagram.test.ts @@ -1,27 +1,13 @@ import { expect, test } from "bun:test"; -import assert from "node:assert/strict"; import { Datagram } from "./datagram.ts"; import { Version } from "./version.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); -test("lite-07 padding is discarded before looking up a subscription", async () => { - for (const body of [ - new Uint8Array([1]), - new Uint8Array([1, ...new Uint8Array(1199).fill(0xff)]), - new Uint8Array([0x80, 1, 0xff]), - ]) { - expect( - await Datagram.decode(body, Version.DRAFT_07, () => { - throw new Error("padding must not look up a subscription"); - }), - ).toBeUndefined(); - } -}); - test("invalid datagram types never reach a subscription", async () => { - for (const bytes of [[], [0x80], [2, 1, 2, 3], new Uint8Array(9).fill(0xff)]) { + // Type 0x1 was lite-07's padding before it left the draft. + for (const bytes of [[], [0x80], [1, 1, 2, 3], [2, 1, 2, 3], new Uint8Array(9).fill(0xff)]) { let lookedUp = false; await expect( Datagram.decode(new Uint8Array(bytes), Version.DRAFT_07, () => { @@ -37,7 +23,6 @@ test("datagram body round-trips", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { const dg = new Datagram(1n, 42n, 1000, enc.encode("hello")); const decoded = await Datagram.decode(dg.encode(version), version, () => ({ timed: true })); - assert(decoded); expect(decoded.subscribe).toBe(1n); expect(decoded.sequence).toBe(42n); expect(decoded.timestamp).toBe(1000); @@ -63,7 +48,6 @@ test("datagram body varints follow the version's encoding", () => { test("datagram body round-trips an empty payload", async () => { const dg = new Datagram(0n, 0n, 0, new Uint8Array()); const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07, () => ({ timed: true })); - assert(decoded); expect(decoded.payload.byteLength).toBe(0); }); @@ -75,7 +59,6 @@ test("an untimed datagram body carries no timestamp", async () => { expect(subscribe).toBe(1n); return { timed: false }; }); - assert(decoded); expect(decoded.sequence).toBe(2n); expect(decoded.timestamp).toBeUndefined(); expect(dec.decode(decoded.payload)).toBe("world"); diff --git a/js/net/src/lite/datagram.ts b/js/net/src/lite/datagram.ts index 4e7baf6366e..d13b33edb77 100644 --- a/js/net/src/lite/datagram.ts +++ b/js/net/src/lite/datagram.ts @@ -11,12 +11,12 @@ import { Timescale } from "../time.ts"; import { decodeNode, decodePin, encodeNode, encodePin } from "./instance.ts"; import * as Message from "./message.ts"; import { fromWire, toWire } from "./priority.ts"; -import { hasDatagrams, hasDatagramTracks, hasPadding, type Version, wireTimescale } from "./version.ts"; +import { hasDatagrams, hasDatagramTracks, type Version, wireTimescale } from "./version.ts"; /** * A QUIC datagram body: `subscribe (i) | sequence (i) | [timestamp (i)] | payload (b)`, with the * timestamp present only when the subscription's track carries one (see `wireTimescale`). - * Lite-07 prefixes datagram-track bodies with type 0x0; type 0x1 is discarded padding. + * Lite-07 prefixes datagram-track bodies with type 0x0, its only datagram type. * * The payload runs to the datagram boundary, so unlike a size-prefixed lite message there is no * inner length prefix. Mirrors the Rust `lite::Datagram`; the model counterpart is @@ -53,7 +53,7 @@ export class Datagram { const subscribe = encodeVarint(this.subscribe, version); const sequence = encodeVarint(this.sequence, version); const timestamp = this.timestamp === undefined ? new Uint8Array() : encodeVarint(this.timestamp, version); - const type = hasPadding(version) ? encodeVarint(0x0, version) : new Uint8Array(); + const type = hasDatagramTracks(version) ? encodeVarint(0x0, version) : new Uint8Array(); const out = new Uint8Array( type.byteLength + @@ -76,19 +76,19 @@ export class Datagram { } /** - * Decode a group datagram or discard padding with `undefined`. `timed` reports whether the - * track of the given subscribe ID carries a timestamp, which the body itself does not say. + * Decode a datagram body. `timed` reports whether the track of the given subscribe ID carries + * a timestamp, which the body itself does not say. An unknown lite-07 type throws, so the + * caller discards it. */ static async decode( data: Uint8Array, version: Version, framing: (subscribe: bigint) => { timed: boolean }, - ): Promise { + ): Promise { if (!hasDatagrams(version)) throw new Error("datagrams require lite-05 or newer"); const r = new Reader(undefined, data, version); - if (hasPadding(version)) { + if (hasDatagramTracks(version)) { const type = await r.u62(); - if (type === 1n) return; if (type !== 0n) throw new Error(`unknown datagram type: ${type}`); } const subscribe = await r.u62(); diff --git a/js/net/src/lite/stream.ts b/js/net/src/lite/stream.ts index 486487ede3b..97fefd07133 100644 --- a/js/net/src/lite/stream.ts +++ b/js/net/src/lite/stream.ts @@ -22,8 +22,6 @@ export const StreamId = { export const DataType = { Group: 0, Setup: 1, - /** Arbitrary bytes discarded by lite-07+ receivers. */ - Padding: 2, } as const; /** A unidirectional data-stream type. See {@link DataType}. */ diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 87c757209da..054c2bf826f 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -4032,8 +4032,6 @@ export class Subscriber { entry = this.#datagrams.get(id); return { timed: entry?.timescale !== undefined }; }); - // Padding, which names no subscription. - if (!dg) return undefined; if (!entry || this.#datagrams.get(dg.subscribe) !== entry) return dg.subscribe; if (behindHeld && this.#isHeld(dg.subscribe)) return dg.subscribe; // A scale-less datagram's timestamp is its sequence. diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 56dc6455bdc..0d9d1e668d8 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -84,9 +84,19 @@ export function hasDatagrams(version: Version): boolean { } } -/** Whether datagram tracks have their own request and sequence space. */ +/** Whether datagram tracks have their own request and sequence space, and datagrams a leading type. */ export function hasDatagramTracks(version: Version): boolean { - return hasPadding(version); + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } } /** Whether the session supports the GOAWAY control stream (0x5) for graceful shutdown and migration. Added in lite-04. */ @@ -140,21 +150,6 @@ export function hasTracks(version: Version): boolean { } } -/** Whether datagrams have a type and either endpoint may send padding streams or datagrams. */ -export function hasPadding(version: Version): boolean { - switch (version) { - case Version.DRAFT_01: - case Version.DRAFT_02: - case Version.DRAFT_03: - case Version.DRAFT_04: - case Version.DRAFT_05: - case Version.DRAFT_06: - return false; - default: - return true; - } -} - /** Whether announce streams begin with ANNOUNCE_OK and omit the sender's origin from each hop chain. */ export function hasAnnounceOk(version: Version): boolean { // Explicitly list older versions so future versions keep the lite-05+ announce behavior. diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 39fb2b122e6..5fc578aa5ed 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -366,15 +366,10 @@ fn datagram(data: &[u8], version: lite::Version) -> bool { continue; }; any = true; - let Some(decoded) = decoded else { - continue; - }; let Ok(first) = decoded.encode_bytes(version) else { continue; }; - let echo = lite::Datagram::decode(first, version, |_| timed) - .expect("could not decode our own encoding") - .expect("encoded datagram decoded as padding"); + let echo = lite::Datagram::decode(first, version, |_| timed).expect("could not decode our own encoding"); assert_eq!(echo, decoded, "datagram did not survive a round trip"); } any diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index d5643497ada..658ad47c474 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -2,9 +2,9 @@ //! //! A body is `subscribe (i) | sequence (i) | [timestamp (i)] | payload (b)`, with the //! timestamp present only when the subscription's track carries one (see -//! [`Version::wire_timescale`]). Lite-07 prefixes it with type 0x0; type 0x1 is discarded -//! padding. The payload runs to the datagram boundary, so unlike a [`super::Message`] there -//! is no inner length prefix. +//! [`Version::wire_timescale`]). Lite-07 prefixes it with type 0x0, its only datagram type. +//! The payload runs to the datagram boundary, so unlike a [`super::Message`] there is no +//! inner length prefix. //! //! On lite-05/06 a body is a single-frame group on a SUBSCRIBE subscription, its sequence //! the group's. On lite-07 it is a datagram of a datagram track, subscribed through a @@ -47,7 +47,7 @@ impl Encode for Datagram { return Err(EncodeError::Version); } - if version.has_padding() { + if version.has_datagram_tracks() { w.varint(0x0)?; } w.varint(self.subscribe)?; @@ -66,26 +66,18 @@ impl Datagram { /// The largest encoded datagram body a lite hop carries. pub(super) const MAX_SIZE: usize = 1200; - /// Decode a datagram, or discard padding with `None`, without copying its payload. + /// Decode a datagram without copying its payload. /// /// `timed` says whether the track of the given subscribe ID carries timestamps, which - /// the body itself does not. - pub(crate) fn decode( - buf: Bytes, - version: Version, - timed: impl FnOnce(u64) -> bool, - ) -> Result, DecodeError> { + /// the body itself does not. An unknown lite-07 type is an error, so the caller discards it. + pub(crate) fn decode(buf: Bytes, version: Version, timed: impl FnOnce(u64) -> bool) -> Result { if !version.has_datagrams() { return Err(DecodeError::Version); } let mut r = Decoder::new(&buf, version.into()); - if version.has_padding() { - match r.varint()? { - 0x0 => (), - 0x1 => return Ok(None), - _ => return Err(DecodeError::InvalidValue), - } + if version.has_datagram_tracks() && r.varint()? != 0x0 { + return Err(DecodeError::InvalidValue); } let subscribe = r.varint()?; let sequence = r.varint()?; @@ -97,12 +89,12 @@ impl Datagram { // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); - Ok(Some(Self { + Ok(Self { subscribe, sequence, timestamp, payload, - })) + }) } } @@ -267,26 +259,10 @@ impl<'a> Message<'a> for DatagramsInfo { mod test { use super::*; - #[test] - fn padding_needs_no_subscription() { - for mut body in [vec![1], vec![1; Datagram::MAX_SIZE], vec![0x80, 1, 0xff]] { - // Padding bytes need not be valid varints or any other structured encoding. - if body.len() == Datagram::MAX_SIZE { - body[1..].fill(0xff); - } - assert!( - Datagram::decode(body.into(), Version::Lite07, |_| panic!( - "padding must not look up a subscription" - )) - .unwrap() - .is_none() - ); - } - } - #[test] fn invalid_types_never_reach_a_subscription() { - for body in [&[][..], &[0x80][..], &[2, 1, 2, 3][..], &[0xff; 9][..]] { + // Type 0x1 was lite-07's padding before it left the draft. + for body in [&[][..], &[0x80][..], &[1, 1, 2, 3][..], &[2, 1, 2, 3][..], &[0xff; 9][..]] { assert!( Datagram::decode(Bytes::copy_from_slice(body), Version::Lite07, |_| panic!( "invalid type must not look up a subscription" @@ -306,7 +282,7 @@ mod test { }; for version in [Version::Lite05, Version::Lite06, Version::Lite07] { let buf = original.encode_bytes(version).unwrap(); - let decoded = Datagram::decode(buf, version, |_| true).unwrap().unwrap(); + let decoded = Datagram::decode(buf, version, |_| true).unwrap(); assert_eq!(decoded, original); } } @@ -340,7 +316,6 @@ mod test { assert_eq!(id, 1); false }) - .unwrap() .unwrap(); assert_eq!(decoded, dg); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f60f510f90d..775e8b412e6 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -8024,7 +8024,7 @@ mod serve_group_test { let session = SinkSession::new(Log::default()).with_datagrams(transport); let log = session.log.clone(); // Lite-07's type adds one byte to the three one-byte fields. - let header = if version.has_padding() { 4 } else { 3 }; + let header = if version.has_datagram_tracks() { 4 } else { 3 }; datagram_send(version, session) .send(crate::datagram::Datagram { sequence: 1, diff --git a/rs/moq-net/src/lite/stream.rs b/rs/moq-net/src/lite/stream.rs index a888641a002..aaaa377e894 100644 --- a/rs/moq-net/src/lite/stream.rs +++ b/rs/moq-net/src/lite/stream.rs @@ -41,8 +41,6 @@ pub enum DataType { Group = 0, /// The lite-05+ SETUP stream: one SETUP message, then FIN. Setup = 1, - /// Arbitrary bytes discarded by lite-07+ receivers. - Padding = 2, } impl<'a> Decode<'a, Version> for DataType { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 2dcfa8c5857..6f58dc51e3b 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1172,19 +1172,16 @@ impl Subscriber { /// /// A datagram track's subscription takes its datagrams. On lite-05/06 a stream track's /// subscription carries its name's datagrams too, which go to that name's datagram track. - /// Padding and a body past the wire cap name no subscription. + /// A body past the wire cap names no subscription. fn route_datagram(&self, payload: bytes::Bytes) -> Result, Error> { if payload.len() > lite::Datagram::MAX_SIZE { return Ok(None); } let mut target = None; - let Some(dg) = lite::Datagram::decode(payload, self.version, |id| { + let dg = lite::Datagram::decode(payload, self.version, |id| { target = self.datagram_target(id); target.as_ref().is_some_and(|(_, timescale)| timescale.is_some()) - })? - else { - return Ok(None); - }; + })?; let Some((mut producer, timescale)) = target else { return Ok(Some(dg.subscribe)); }; @@ -1548,10 +1545,6 @@ enum UniState { Setup { reader: Reader, }, - /// Discarding a lite-07+ padding stream until FIN. - Padding { - reader: Reader, - }, Group(GroupRecv), Done, } @@ -1577,7 +1570,7 @@ impl UniServe { /// Abort the stream with the given error, wherever the reader currently lives. fn abort(&mut self, err: &Error) { match &mut self.state { - UniState::Start { reader } | UniState::Setup { reader } | UniState::Padding { reader } => reader.abort(err), + UniState::Start { reader } | UniState::Setup { reader } => reader.abort(err), UniState::Group(recv) => recv.reader.abort(err), UniState::Done => {} } @@ -1587,9 +1580,16 @@ impl UniServe { loop { match &mut self.state { UniState::Start { reader } => { - // A decode error here is only logged; the peer hung up or spoke garbage - // before the stream had a type. - let kind = ready!(reader.poll_decode::(waiter))?; + // An unknown type is stopped, never the session's failure, so a later + // version can add one. + let kind = match ready!(reader.poll_decode::(waiter)) { + Ok(kind) => kind, + Err(err) => { + tracing::debug!(%err, "unknown uni stream"); + reader.abort(&Error::UnexpectedStream); + return Poll::Ready(Ok(())); + } + }; // Claim before decoding the body, so two incomplete SETUPs are duplicates too. if matches!(kind, lite::DataType::Setup) && self.subscriber.version.has_setup_stream() { self.subscriber.peer_setup.claim()?; @@ -1604,7 +1604,6 @@ impl UniServe { reader.set_priority(crate::priority::RECV_CONTROL); UniState::Setup { reader } } - lite::DataType::Padding => UniState::Padding { reader }, }; } UniState::Setup { reader } => { @@ -1629,13 +1628,6 @@ impl UniServe { } } } - UniState::Padding { reader } => { - if !self.subscriber.version.has_padding() { - self.abort(&Error::UnexpectedStream); - return Poll::Ready(Ok(())); - } - return reader.poll_discard(waiter); - } UniState::Group(recv) => { let res = ready!(recv.poll_serve(waiter)); @@ -4661,59 +4653,6 @@ mod tests { assert_eq!(sub.owed(Some(8)), Some(vec![1..8])); } - async fn receive_padding(version: Version, bytes: Vec) { - let session = crate::lite::test_transport::ScriptedSession::new(bytes); - let stream = Stream::open(&crate::driver::Transport::new(session.clone()), version) - .await - .unwrap(); - let log = session.log.clone(); - let subscriber = Subscriber::new(SubscriberConfig { - runtime: crate::time::sim(), - session: crate::driver::Transport::new(session.clone()), - origin: origin::Config::new(std::num::NonZeroU64::new(1).unwrap()).produce(), - recv_bandwidth: None, - version, - peer_setup: lite::PeerSetup::new(false, crate::transport::Address::Setup), - peer_hop: None, - cost: None, - going_away: Default::default(), - auth: crate::auth::Link::new(false), - }); - let mut uni = UniServe { - subscriber, - state: UniState::Start { reader: stream.reader }, - }; - let waiter = kio::Waiter::noop(); - if version == Version::Lite07 { - assert!(uni.poll_serve(&waiter).is_pending()); - // The same stream can keep sending before FIN, without accumulating a body. - for _ in 0..8 { - session.push(&[0; 4096]); - assert!(uni.poll_serve(&waiter).is_pending()); - } - // A body that is all ready at once still yields the driver before FIN. - session.push(&[0; 64 * 8192]); - session.close(crate::lite::test_transport::Close::Fin); - assert!(uni.poll_serve(&waiter).is_pending()); - let mut polls = 1; - let res = loop { - if let Poll::Ready(res) = uni.poll_serve(&waiter) { - break res; - } - polls += 1; - assert!(polls < 64, "padding never finished"); - }; - assert!(res.is_ok()); - assert!(log.stops().is_empty()); - } else { - assert!(uni.poll_serve(&waiter).is_ready()); - // An unsupported stream is stopped without ending the session. - drop(uni); - assert!(!log.stops().is_empty()); - } - assert!(log.closes().is_empty()); - } - /// A peer opening streams at once gets a budget of them accepted per poll, leaving the /// rest for later so the session's other tasks run in between. #[kio::test] @@ -4915,8 +4854,10 @@ mod tests { } } + /// A stream type the version doesn't define, such as lite-07's removed padding (0x2), is + /// stopped without ending the session. #[kio::test] - async fn padding_is_discarded_only_on_lite07() { + async fn an_unknown_stream_type_is_stopped() { for version in [ Version::Lite01, Version::Lite02, @@ -4930,30 +4871,31 @@ mod tests { crate::coding::Encoder::new(&mut bytes, version.into()) .varint(2) .unwrap(); - receive_padding(version, bytes).await; - } - } - - /// Both runtimes receive the other's encoded padding and keep the session live. - #[kio::test] - #[ignore = "requires Bun; run by just test interop"] - async fn lite_padding_interop() { - for (version, alpn) in [ - (Version::Lite05, "moq-lite-05"), - (Version::Lite06, "moq-lite-06"), - (Version::Lite07, "moq-lite-07-wip"), - ] { - let mut bytes = Vec::new(); - let mut writer = crate::coding::Encoder::new(&mut bytes, version.into()); - lite::DataType::Padding.encode(&mut writer, version).unwrap(); - writer.slice(&[0xab; 4096]); - let echo: Vec = serde_json::from_slice(&crate::test_interop::bun( - "lite-padding.ts", - serde_json::json!({ "alpn": alpn, "bytes": bytes }), - )) - .unwrap(); - assert_eq!(echo, bytes); - receive_padding(version, echo).await; + let session = crate::lite::test_transport::ScriptedSession::new(bytes); + let stream = Stream::open(&crate::driver::Transport::new(session.clone()), version) + .await + .unwrap(); + let log = session.log.clone(); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::sim(), + session: crate::driver::Transport::new(session.clone()), + origin: origin::Config::new(std::num::NonZeroU64::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup: lite::PeerSetup::new(false, crate::transport::Address::Setup), + peer_hop: None, + cost: None, + going_away: Default::default(), + auth: crate::auth::Link::new(false), + }); + let mut uni = UniServe { + subscriber, + state: UniState::Start { reader: stream.reader }, + }; + assert!(uni.poll_serve(&kio::Waiter::noop()).is_ready()); + drop(uni); + assert!(!log.stops().is_empty(), "{version}: the stream was not stopped"); + assert!(log.closes().is_empty(), "{version}: the session closed"); } } @@ -7382,7 +7324,7 @@ mod tests { } /// The session routes a datagram to its datagram track's subscription by Subscribe ID, - /// dropping lite-07 padding and a body past the wire cap. + /// dropping a body past the wire cap. #[kio::test] async fn route_datagram_delivers_to_its_subscription() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { @@ -7413,14 +7355,6 @@ mod tests { ); let mut recv = || received.poll_recv(&kio::Waiter::noop()); - if version.has_padding() { - // These bytes would name the active subscription without the discriminator. - for body in [vec![1], vec![1; 1200], vec![1; 1201]] { - assert_eq!(subscriber.route_datagram(body.into()).unwrap(), None); - assert!(recv().is_pending()); - } - } - let payload = |key, size| { lite::Datagram { subscribe: 1, @@ -7450,7 +7384,7 @@ mod tests { // An unknown subscription's datagram goes nowhere, and names it. let mut other = payload(4, 1).to_vec(); - other[usize::from(version.has_padding())] = 2; + other[usize::from(version.has_datagram_tracks())] = 2; assert_eq!(subscriber.route_datagram(other.into()).unwrap(), Some(2)); assert!(recv().is_pending()); } diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index ed399c5e5ff..4079c6c2e3b 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -81,14 +81,15 @@ impl Version { /// Whether the session may carry unreliable QUIC datagrams (lite-05 §6.4): single-frame /// groups on lite-05/06, a datagram track's datagrams on lite-07, which adds a leading - /// type and padding. Older than lite-05 never sends or accepts datagrams. + /// type. Older than lite-05 never sends or accepts datagrams. pub fn has_datagrams(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04) } /// Whether a subscriber subscribes to a datagram track through its own Datagrams Stream - /// (0x9), whose datagrams carry the datagram track's own sequence. Added in lite-07; - /// earlier versions carry single-frame groups as datagrams on a SUBSCRIBE subscription. + /// (0x9), whose datagrams carry the datagram track's own sequence and a leading type. + /// Added in lite-07; earlier versions carry single-frame groups as datagrams on a + /// SUBSCRIBE subscription. pub(crate) fn has_datagram_tracks(self) -> bool { !matches!( self, @@ -117,14 +118,6 @@ impl Version { ) } - /// Whether datagrams have a type and either endpoint may send padding streams or datagrams. - pub(crate) fn has_padding(self) -> bool { - !matches!( - self, - Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 - ) - } - /// Whether a subscriber may open a Tracks Stream (0x8) to list a broadcast's /// tracks. Added in lite-07. pub fn has_tracks(self) -> bool { diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 6886ac8b308..d71512779c3 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -291,7 +291,6 @@ struct Echo { varints: Vec, setup: Vec, datagram: Vec, - padding: Vec, untimed_datagram: Vec, track_info: Vec, group: Vec, @@ -333,17 +332,6 @@ fn lite_varint_interop() { // Only lite-07 can carry an untimed track; lite-06 stamps it, so it has no untimed bytes. let untimed = version.wire_timescale(None).is_none(); - let padding = match version.has_padding() { - true => { - let mut bytes = Vec::new(); - let mut w = Encoder::new(&mut bytes, version.into()); - w.varint(1).unwrap(); - w.slice(&[0xff; 1199]); - bytes - } - false => Vec::new(), - }; - // The body doesn't say it is untimed; the subscription's track does. let untimed_datagram = lite::Datagram { subscribe: 9, @@ -396,7 +384,6 @@ fn lite_varint_interop() { "varints": varints, "setup": setup.to_vec(), "datagram": datagram.to_vec(), - "padding": padding, "untimedDatagram": untimed_datagram, "trackInfo": track_info.to_vec(), "group": group, @@ -409,16 +396,6 @@ fn lite_varint_interop() { assert_eq!(echo.varints, varints, "{version}: JS encoded the values differently"); assert_eq!(echo.setup, setup, "{version}: SETUP"); assert_eq!(echo.datagram, datagram, "{version}: datagram"); - assert_eq!(echo.padding, padding, "{version}: padding"); - if version.has_padding() { - assert!( - lite::Datagram::decode(echo.padding.into(), version, |_| { - panic!("padding must not look up a subscription") - }) - .unwrap() - .is_none() - ); - } assert_eq!(echo.untimed_datagram, untimed_datagram, "{version}: untimed datagram"); assert_eq!(echo.track_info, track_info, "{version}: TRACK_INFO"); assert_eq!(echo.group, group, "{version}: group"); diff --git a/test/interop/lite-padding.ts b/test/interop/lite-padding.ts deleted file mode 100644 index 1a911c704cc..00000000000 --- a/test/interop/lite-padding.ts +++ /dev/null @@ -1,58 +0,0 @@ -/** Receive Rust padding on a JS session, then return JS padding for Rust's receiver. */ -import assert from "node:assert/strict"; -import { Connection } from "../../js/net/src/lite/connection.ts"; -import { Goaway } from "../../js/net/src/lite/goaway.ts"; -import { DataType, StreamId } from "../../js/net/src/lite/stream.ts"; -import { ALPN_05, ALPN_06, ALPN_07_WIP, Version } from "../../js/net/src/lite/version.ts"; -import { createMockTransportPair } from "../../js/net/src/mock.ts"; -import { Stream, Writer } from "../../js/net/src/stream.ts"; - -console.debug = console.error; -const input: { alpn: string; bytes: number[] } = JSON.parse(process.argv[2]); -const versions: Record = { - [ALPN_05]: Version.DRAFT_05, - [ALPN_06]: Version.DRAFT_06, - [ALPN_07_WIP]: Version.DRAFT_07, -}; -const version = versions[input.alpn]; -assert(version); -const pair = createMockTransportPair(input.alpn); -const connection = new Connection({ url: new URL("https://example.com/"), quic: pair.server, version }); -let closed = false; -void connection.closed.then(() => { - closed = true; -}); -try { - const sender = new Writer(await pair.client.createUnidirectionalStream(), version); - await sender.write(Uint8Array.from(input.bytes)); - if (version === Version.DRAFT_07) { - // A write must drain before FIN, not just when the whole body is available. - await sender.write(new Uint8Array(4096)); - sender.close(); - await sender.closed; - } else { - await assert.rejects(sender.closed); - } - const goaway = await Stream.open(pair.client, { version }); - await goaway.writer.u53(StreamId.Goaway); - await new Goaway("").encode(goaway.writer, version); - goaway.writer.close(); - assert.equal((await connection.draining).uri, ""); - assert.equal(closed, false); - const bytes: number[] = []; - const output = new Writer( - new WritableStream({ - write: (chunk) => { - bytes.push(...chunk); - }, - }), - version, - ); - await output.u53(DataType.Padding); - await output.write(new Uint8Array(4096).fill(0xab)); - output.close(); - await output.closed; - console.log(JSON.stringify(bytes)); -} finally { - connection.abort(); -} diff --git a/test/interop/lite-varint.ts b/test/interop/lite-varint.ts index 489d232fb3f..f6946a83fde 100644 --- a/test/interop/lite-varint.ts +++ b/test/interop/lite-varint.ts @@ -13,7 +13,6 @@ const input: { varints: number[]; setup: number[]; datagram: number[]; - padding: number[]; untimedDatagram: number[]; trackInfo: number[]; group: number[]; @@ -66,30 +65,14 @@ const setup = await Setup.decode(reader(input.setup), version); const setupBytes = await write((w) => setup.encode(w, version)); const datagram = await Datagram.decode(Uint8Array.from(input.datagram), version, () => ({ timed: true })); -assert(datagram); const datagramBytes = [...datagram.encode(version)]; // Only lite-07 can carry an untimed track; lite-06 stamps it, so it has no untimed bytes. const untimed = version === Version.DRAFT_07; -let padding: number[] = []; -if (version === Version.DRAFT_07) { - assert.equal( - await Datagram.decode(Uint8Array.from(input.padding), version, () => { - throw new Error("padding must not look up a subscription"); - }), - undefined, - ); - padding = await write(async (w) => { - await w.u53(1); - await w.write(new Uint8Array(1199).fill(0xff)); - }); -} - let untimedDatagramBytes: number[] = []; if (untimed) { const datagram = await Datagram.decode(Uint8Array.from(input.untimedDatagram), version, () => ({ timed: false })); - assert(datagram); assert.equal(datagram.timestamp, undefined); untimedDatagramBytes = [...datagram.encode(version)]; } else { @@ -153,7 +136,6 @@ console.log( varints, setup: setupBytes, datagram: datagramBytes, - padding, untimedDatagram: untimedDatagramBytes, trackInfo: trackInfoBytes, group: groupBytes, From ca2c1901e90910ae53ff0d512ccd796aab4cf027 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:48:08 -0800 Subject: [PATCH 04/26] feat(lite)!: lite-07 SUBSCRIBE says no max age, one inclusive time anchor, and whether the largest ended Subscriber Max Age on lite-07 SUBSCRIBE and SUBSCRIBE_UPDATE is milliseconds plus one, 0 for no limit, so the model's unlimited budget crosses the wire as itself. The codec carries Option: Lite01/02, which have no field, decode as no limit, which retires the publisher's serving_max_delay, and lite03-06 still send 2^53 - 1 for none. Lite-07 range anchors are 0 None, 1 Time, 2 Relative; type 3 is gone and is malformed. Time is inclusive at both ends. An in-memory absolute position goes out as its group's time, an exclusive end as the inclusive time before it, so the subscriber's ranges and fills need no change. SUBSCRIBE_OK on lite-07 adds Largest Ended after Largest Frame: the publisher sends whether its cache's largest group ended (finished or closed, or reported ended by its source), and a subscriber records it so a relay forwards it. It stays crate-private: nothing in this repo reads it yet. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/fuzz.rs | 8 +- rs/moq-net/src/lite/publisher.rs | 205 +++++++++++---------- rs/moq-net/src/lite/subscribe.rs | 286 ++++++++++++++++++++---------- rs/moq-net/src/lite/subscriber.rs | 51 +++--- rs/moq-net/src/lite/version.rs | 9 + rs/moq-net/src/model/cache.rs | 18 ++ rs/moq-net/src/model/resume.rs | 10 ++ rs/moq-net/src/model/track.rs | 43 ++++- 8 files changed, 408 insertions(+), 222 deletions(-) diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 5fc578aa5ed..2dc07869fa8 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -1480,7 +1480,7 @@ impl LiteSample { broadcast: Path::from_static("room/alice"), track: "video".into(), priority: 2, - max_delay: std::time::Duration::from_secs(10), + max_delay: Some(std::time::Duration::from_secs(10)), min_delay: None, ranges: vec![lite::Range::OLDEST], update: 0, @@ -1681,7 +1681,7 @@ impl Default for Messages { broadcast: Path::from_static("room/alice"), track: "video".into(), priority: 3, - max_delay: Duration::from_millis(500), + max_delay: Some(Duration::from_millis(500)), min_delay: None, ranges: vec![lite::Range { start: Some(lite::Anchor::Absolute(crate::track::Position::group(1_000))), @@ -1693,7 +1693,7 @@ impl Default for Messages { wanted_group: None, order: crate::track::Order::Descending, priority: 4, - max_delay: Duration::from_millis(500), + max_delay: Some(Duration::from_millis(500)), min_delay: None, // Lite-06, the bench's version, restates the ranges. ranges: lite::RangeEdit::Replace(vec![lite::Range { @@ -1865,7 +1865,7 @@ pub fn encode_subscribe(broadcast: &Path, track: &str, ietf: bool, out: &mut Vec depth: 0, track: track.into(), priority: 0, - max_delay: std::time::Duration::ZERO, + max_delay: Some(std::time::Duration::ZERO), min_delay: None, ranges: vec![lite::Range::OLDEST], order: track::Order::Descending, diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 775e8b412e6..20dbe99db24 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -115,20 +115,6 @@ struct PeerTargets { writes: u64, } -/// Largest millisecond duration every implementation can carry losslessly. -pub(super) const MAX_SAFE_DELAY_MS: u64 = (1_u64 << 53) - 1; - -/// The budget to serve a peer with, given what its wire could tell us. -/// -/// A version without the field decodes as [`Duration::ZERO`], which is -/// indistinguishable from a peer genuinely asking for the live edge. Serving that -/// as real time would discard backlog a legacy subscriber never declined, so serve the -/// publisher's max age alone and leave enforcement to the receiver, exactly as the IETF -/// path does for the same reason. -fn serving_max_delay(version: Version, requested: Duration) -> Option { - version.carries_max_delay().then_some(requested) -} - /// The floor of a subscription's read cursor for the wire serving it. /// /// On lite-06 there is nothing to do: `Consumer::subscribe` resolves the cursor from the @@ -138,8 +124,8 @@ fn serving_max_delay(version: Version, requested: Duration) -> Option /// Pre-06 wires are the exception: their drafts define an absent `Group Start` as the /// latest group, so say so explicitly rather than letting the budget reach back. Lite03-05 /// carry a `Subscriber Max Age`, but there it is a staleness tolerance only; Lite01/02 additionally get -/// an unbounded budget so nothing is dropped under them (see [`serving_max_delay`]), which -/// must not read as a request to replay the whole cache on join. +/// an unbounded budget so nothing is dropped under them (they carry no max age, which decodes +/// as none), which must not read as a request to replay the whole cache on join. /// /// `latest` is the newest group known once the track resolves, which a SUBSCRIBE can beat, as /// one a relay serves from a copy still fetching upstream, or on lite-05 one sent alongside its @@ -2428,7 +2414,7 @@ impl Request for SubscribeServe { }; let latest = track.latest_key(); let bounds = Bounds::new(&msg.ranges, !shared.version.has_ranges()); - Ok(Self::subscribe(shared, msg, bounds, &track, latest, None, legacy)) + Ok(Self::subscribe(msg, bounds, &track, latest, None, legacy)) } fn update(&mut self, update: LiveUpdate) { @@ -3070,7 +3056,6 @@ impl SubscribeServe { /// One subscriber for the whole subscription, so a track opens exactly one (no duplicate /// demand). fn subscribe( - shared: &Shared, msg: lite::Subscribe<'static>, bounds: Bounds, track: &track::Consumer, @@ -3082,7 +3067,7 @@ impl SubscribeServe { priority: msg.priority, delay: track::Delay { min: msg.min_delay, - max: serving_max_delay(shared.version, msg.max_delay), + max: msg.max_delay, }, order: msg.order, ..bounds.groups() @@ -3363,13 +3348,9 @@ mod test { group.close().unwrap(); } - // What run_subscribe hands the model for a peer that sent no budget at all. + // What run_subscribe hands the model for a Lite01/02 peer, which sends no budget at all. let served = - |version| { - producer.subscribe(track::Subscription::default().with_delay( - track::Delay::default().with_max(serving_max_delay(version, std::time::Duration::ZERO)), - )) - }; + || producer.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(None))); let drain = |subscriber: &mut track::Subscriber| { let mut keys = Vec::new(); while let Some(Ok(Some(group))) = subscriber.recv_group().now_or_never() { @@ -3378,14 +3359,14 @@ mod test { keys }; - let mut unpinned = served(Version::Lite01); + let mut unpinned = served(); assert_eq!( drain(&mut unpinned), vec![0, 1, 2], "the unbounded budget alone resolves to the whole cache" ); - let legacy = served(Version::Lite01); + let legacy = served(); let mut legacy = legacy.with_range(cursor_floor(Version::Lite01, None, producer.latest_key())..); assert_eq!(drain(&mut legacy), vec![2]); @@ -4825,7 +4806,7 @@ struct Bounds { impl Bounds { /// Read `ranges` as they arrived. Group IDs are group starts, so an absolute anchor and a - /// time anchor both name a start. + /// time anchor both name a start. Lite-07 carries only time anchors, both ends inclusive. /// /// A `legacy` wire (one without ranges) means its start as the first group starting at /// or after it, never one before it that contains it, so the frames narrow to that @@ -5283,7 +5264,7 @@ impl TrackRun { priority: upd.priority, delay: crate::track::Delay { min: upd.min_delay, - max: serving_max_delay(self.ctx.version, upd.max_delay), + max: upd.max_delay, }, order: upd.order, ..groups @@ -6064,7 +6045,10 @@ impl TrackRun { Poll::Pending => None, }, }; - let largest = live.max(self.track.peek_largest()); + let largest = live.max(self.track.peek_largest()).map(|position| lite::Largest { + position, + ended: self.track.largest_finished(position), + }); writer.buffer(&lite::SubscribeResponse::Start(lite::SubscribeStart { largest, starts: self.starts(start), @@ -7709,28 +7693,6 @@ mod serve_group_test { assert_eq!(log.resets(), vec![crate::StreamError::Evicted.to_code()]); } - /// Lite01/02 have no max delay field, so a SUBSCRIBE from one decodes as - /// `Duration::ZERO`. Serving that as a real-time budget would hold every legacy - /// peer to the live edge and discard backlog it never declined, so those versions - /// get a non-dropping window and leave enforcement to the receiver. - /// - /// These are the two most-preferred negotiated versions, so this is the common - /// wire, not an edge case. - #[test] - fn a_version_without_the_field_serves_a_non_dropping_budget() { - for version in [Version::Lite01, Version::Lite02] { - let max_delay = serving_max_delay(version, Duration::ZERO); - assert_eq!(max_delay, None, "{version:?} must not be served as real time"); - } - - // A version that does carry it is taken at its word, zero included. - assert_eq!(serving_max_delay(Version::Lite05, Duration::ZERO), Some(Duration::ZERO)); - assert_eq!( - serving_max_delay(Version::Lite05, Duration::from_secs(3)), - Some(Duration::from_secs(3)) - ); - } - /// A group that completes cleanly must not reset at all. The completion path /// releases the stream via `poll_close`; leaving the writer to drop after /// `finish()` would fire the Drop fallback and tack a spurious Cancel reset @@ -7971,7 +7933,7 @@ mod serve_group_test { let update = |wanted_group| lite::SubscribeUpdate { wanted_group, priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], order: Order::Descending, @@ -8133,7 +8095,7 @@ mod serve_group_test { wanted_group: None, order: Order::Ascending, priority: 7, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -8291,7 +8253,7 @@ mod serve_group_test { lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges, order: Order::Descending, @@ -8503,11 +8465,12 @@ mod serve_group_test { let _track = track.finish().unwrap(); assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); - // SUBSCRIBE_START with the range starting at 0, a DROP for group 1 with OLD (0x34) - // under update 0, which the end gives up on at once, and SUBSCRIBE_FINISH at 3. + // SUBSCRIBE_START with group 0 ended as the largest and the range starting at 0, a + // DROP for group 1 with OLD (0x34) under update 0, which the end gives up on at once, + // and SUBSCRIBE_FINISH at 3. assert_eq!( *log.writes.lock().unwrap(), - [0, 4, 1, 0, 1, 1, 2, 4, 1, 1, 0x34, 0, 1, 2, 3, 0] + [0, 5, 1, 0, 1, 1, 1, 2, 4, 1, 1, 0x34, 0, 1, 2, 3, 0] ); } @@ -8531,9 +8494,10 @@ mod serve_group_test { let _track = track.finish().unwrap(); assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); - // SUBSCRIBE_START with the range starting at 0, a SKIP for group 1, and + // SUBSCRIBE_START with group 0 ended as the largest and the range starting at 0, a + // SKIP for group 1, and // SUBSCRIBE_FINISH at 3. - assert_eq!(*log.writes.lock().unwrap(), [0, 4, 1, 0, 1, 1, 3, 2, 1, 1, 1, 2, 3, 0]); + assert_eq!(*log.writes.lock().unwrap(), [0, 5, 1, 0, 1, 1, 1, 3, 2, 1, 1, 1, 2, 3, 0]); } /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the @@ -8625,7 +8589,7 @@ mod serve_group_test { crate::track::Info::timed(), ); // The source answered with group 4 as its largest; only group 0 has landed. - track.report_largest(track::Position::group(4)); + track.report_largest(track::Position::group(4), false); let subscriber = track.subscribe(None); let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); write_group(&mut track, 0, 0); @@ -8641,10 +8605,55 @@ mod serve_group_test { }; assert_eq!( (start.starts, start.largest), - (vec![Some(0)], Some(track::Position::group(4))) + ( + vec![Some(0)], + Some(lite::Largest { + position: track::Position::group(4), + ended: false, + }) + ) ); } + /// SUBSCRIBE_OK says whether its largest group ended: one closed or finished here, or one + /// the source said ended, but not one still open. + #[kio::test] + async fn lite07_start_says_whether_the_largest_ended() { + for (case, ended) in [("open", false), ("closed", true), ("reported", true)] { + let track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut group = track.create_group(group::Info { start: 0 }).unwrap(); + group + .write_frame(Timestamp::from_millis(0).unwrap(), b"x".as_slice()) + .unwrap(); + match case { + "closed" => drop(group.close().unwrap()), + "reported" => track.report_largest(track::Position { group: 0, frame: 0 }, true), + _ => {} + } + let subscriber = track.subscribe(None); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + while run.start.resolved().is_none() { + assert!(run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready()); + } + kio::wait(|waiter| writer.poll_flush(waiter)).await.unwrap(); + + let writes = log.writes.lock().unwrap().clone(); + let (msg, _) = lite::SubscribeResponse::decode_slice(&writes, Version::Lite07).unwrap(); + let lite::SubscribeResponse::Start(start) = msg else { + panic!("expected SUBSCRIBE_START, got {msg:?}"); + }; + let largest = lite::Largest { + position: track::Position { group: 0, frame: 0 }, + ended, + }; + assert_eq!(start.largest, Some(largest), "{case}"); + } + } + /// The SUBSCRIBE_DROP ranges a run loop's subscribe stream carried, once flushed, each as /// its first and last group. async fn drops( @@ -8747,7 +8756,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 1, - max_delay: budget, + max_delay: Some(budget), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -8788,7 +8797,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 1, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -8834,7 +8843,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: if widen { Duration::from_secs(10) } else { budget }, + max_delay: Some(if widen { Duration::from_secs(10) } else { budget }), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -8879,7 +8888,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 5, - max_delay: if widen { Duration::from_secs(10) } else { budget }, + max_delay: Some(if widen { Duration::from_secs(10) } else { budget }), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -8925,7 +8934,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 1, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -8962,7 +8971,7 @@ mod serve_group_test { let update = |update, max_delay| lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay, + max_delay: Some(max_delay), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -9031,7 +9040,7 @@ mod serve_group_test { run.replace(lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: if widen { Duration::from_secs(10) } else { budget }, + max_delay: Some(if widen { Duration::from_secs(10) } else { budget }), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], order: Order::Descending, @@ -9081,7 +9090,7 @@ mod serve_group_test { let update = |id, start, update| lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: Duration::from_secs(10), + max_delay: Some(Duration::from_secs(10)), min_delay: None, ranges: vec![(id, lite::Range::span(start, 0, None, None))], order: Order::Descending, @@ -9139,7 +9148,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay, + max_delay: Some(max_delay), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -9175,7 +9184,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 1, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -9217,7 +9226,7 @@ mod serve_group_test { run.update(lite::SubscribeUpdate { wanted_group: None, priority: 0, - max_delay, + max_delay: Some(max_delay), min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, @@ -9413,7 +9422,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(60), + max_delay: Some(Duration::from_secs(60)), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], update: 0, @@ -9840,7 +9849,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(60), + max_delay: Some(Duration::from_secs(60)), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], update: 0, @@ -9882,7 +9891,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(1), + max_delay: Some(Duration::from_secs(1)), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], update: 0, @@ -9929,7 +9938,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(1), + max_delay: Some(Duration::from_secs(1)), min_delay: None, ranges: vec![lite::Range::span(Some(start_group), 0, None, None)], update: 0, @@ -9976,7 +9985,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Ascending, priority: 0, - max_delay: Duration::from_secs(10), + max_delay: Some(Duration::from_secs(10)), min_delay: None, ranges: vec![lite::Range::span(Some(start_group), 0, None, None)], update: 0, @@ -10023,7 +10032,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(60), + max_delay: Some(Duration::from_secs(60)), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -10116,7 +10125,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(60), + max_delay: Some(Duration::from_secs(60)), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -10254,7 +10263,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(30), + max_delay: Some(Duration::from_secs(30)), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -10285,7 +10294,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(30), + max_delay: Some(Duration::from_secs(30)), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -10313,7 +10322,7 @@ mod serve_group_test { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(Some(7), 0, None, None)], update: 0, @@ -10456,7 +10465,7 @@ mod serve_group_test { *log.writes.lock().unwrap(), // The DROP names group 0 as a start and count, with OLD (0x34) and the SUBSCRIBE's // update, 0. - [0, 4, 1, 0, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0], + [0, 5, 1, 0, 1, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0], "the expired group is dropped and the end precedes stream credit" ); @@ -10468,7 +10477,7 @@ mod serve_group_test { assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); assert_eq!( *log.writes.lock().unwrap(), - [0, 4, 1, 0, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0] + [0, 5, 1, 0, 1, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0] ); } } @@ -11185,7 +11194,7 @@ mod tests { broadcast: broadcast.clone(), track: "video".into(), priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -11250,7 +11259,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -11406,7 +11415,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "events".into(), priority, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -11719,7 +11728,7 @@ mod tests { let mut resolved = staged.take().unwrap().commit(); write(&mut resolved, &[0, 3]); if let Answer::Warm = answer { - resolved.report_largest(track::Position::group(9)); + resolved.report_largest(track::Position::group(9), false); } track = Some(resolved); } @@ -11751,7 +11760,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 0, - max_delay: Duration::from_secs(60), + max_delay: Some(Duration::from_secs(60)), min_delay: None, ranges: vec![lite::Range::span(start, 0, None, None)], update: 0, @@ -11791,7 +11800,7 @@ mod tests { Answer::Reported => { let mut staged = staged.take().unwrap(); write(&mut staged, &[3]); - staged.report_largest(track::Position::group(9)); + staged.report_largest(track::Position::group(9), false); staged.commit() } Answer::Empty => staged.take().unwrap().commit(), @@ -11887,7 +11896,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 1, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, // A relay asks from its cached group, so the SUBSCRIBE is not a live-edge join. ranges: vec![lite::Range::span(Some(1), 0, None, None)], @@ -11913,7 +11922,7 @@ mod tests { wanted_group, order: crate::track::Order::Descending, priority, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: lite::RangeEdit::Edit { remove: Vec::new(), @@ -11976,7 +11985,7 @@ mod tests { wanted_group: None, order: crate::track::Order::Descending, priority: 0, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges: lite::RangeEdit::Edit { remove: Vec::new(), @@ -12021,7 +12030,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 0, - max_delay: Duration::from_secs(3600), + max_delay: Some(Duration::from_secs(3600)), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -12550,7 +12559,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -12667,7 +12676,7 @@ mod tests { broadcast: crate::Path::from_static("room"), track: "video".into(), priority: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, @@ -12808,7 +12817,7 @@ mod tests { broadcast: crate::Path::new(broadcast).unwrap(), track: track.into(), priority, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], update: 0, diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 7e17aa6a199..279117aa298 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -26,7 +26,10 @@ pub struct Subscribe<'a> { pub depth: u64, pub track: Cow<'a, str>, pub priority: i8, - pub max_delay: std::time::Duration, + /// The subscriber's `Subscriber Max Age`, or `None` for no limit beyond the publisher's. + /// Lite01/02 carry none and decode as `None`; lite03-06 can't say `None` (see + /// [`encode_max_delay`]). + pub max_delay: Option, /// The subscriber's `Subscriber Min Age`, or `None` when not stated. Lite07+ only; earlier /// wires decode as not stated and drop it on encode. pub min_delay: Option, @@ -65,14 +68,16 @@ impl Subscribe<'_> { /// One end of a [`Range`], as the wire carries it. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum Anchor { - /// A position: a start delivers from it, and an end stops just before it. Lite-07 names - /// only a group, so its frame is 0 there; only lite-06 bounds a range partway through one. + /// A position: a start delivers from it, and an end stops just before it. Only lite-06 + /// bounds a range partway through a group. Lite-07 has no such type: a group's start is its + /// time, so it goes out as a [`Anchor::Time`], an end as the time just before it, and + /// decodes as one. Absolute(crate::track::Position), /// The group this many before the latest, included as an end. Lite07+ only, except a /// start of 0 (see [`Range`]). Relative(u64), - /// The group containing this presentation time in the track's timescale, included as - /// an end. Lite07+ only. + /// The group containing this time in the track's timescale (the highest start at or + /// below it), included as an end. Lite07+ only. Time(u64), } @@ -125,17 +130,6 @@ impl Range { } } -impl Version { - /// Whether this version's SUBSCRIBE carries the subscriber's max delay preference. - /// - /// Lite01/02 have no field for it, so a decoded `std::time::Duration::ZERO` there means - /// "not stated", not "real time". Callers that act on the budget must tell the - /// two apart or they will hold every legacy peer to the live edge. - pub(crate) fn carries_max_delay(self) -> bool { - !matches!(self, Version::Lite01 | Version::Lite02) - } -} - impl<'a> Message<'a> for Subscribe<'a> { const CONTROL: Option = Some(crate::stats::Message::Subscribe); fn decode_msg(r: &mut Decoder<'a>, version: Version) -> Result { @@ -147,12 +141,10 @@ impl<'a> Message<'a> for Subscribe<'a> { let priority = super::priority::from_wire(r.u8()?); let (order, max_delay, min_delay, ranges) = match version { - Version::Lite01 | Version::Lite02 => { - (Order::Descending, std::time::Duration::ZERO, None, vec![Range::OLDEST]) - } + Version::Lite01 | Version::Lite02 => (Order::Descending, None, None, vec![Range::OLDEST]), _ => { let order = decode_order(r, version)?; - let max_delay = std::time::Duration::from_millis(r.varint()?); + let max_delay = decode_max_delay(r, version)?; let min_delay = decode_min_delay(r, version)?; (order, max_delay, min_delay, decode_ranges(r, version)?) } @@ -188,7 +180,7 @@ impl<'a> Message<'a> for Subscribe<'a> { Version::Lite01 | Version::Lite02 => {} _ => { encode_order(w, version, self.order)?; - w.varint(u64::try_from(self.max_delay.as_millis()).map_err(|_| EncodeError::BoundsExceeded)?)?; + encode_max_delay(w, version, self.max_delay)?; encode_min_delay(w, version, self.min_delay)?; encode_ranges(w, version, &self.ranges)?; } @@ -215,6 +207,35 @@ fn encode_update(w: &mut Encoder<'_>, version: Version, update: u64) -> Result<( } } +/// What lite03-06 send for no `Subscriber Max Age` limit, which their bare milliseconds can't +/// say: the largest every implementation carries losslessly. +const MAX_SAFE_DELAY_MS: u64 = (1 << 53) - 1; + +/// Decode the `Subscriber Max Age`: on lite-07 milliseconds plus one, zero meaning no limit; +/// before it bare milliseconds. +fn decode_max_delay(r: &mut Decoder<'_>, version: Version) -> Result, DecodeError> { + Ok(match version.has_unlimited_max_delay() { + true => r.varint_opt()?.map(std::time::Duration::from_millis), + false => Some(std::time::Duration::from_millis(r.varint()?)), + }) +} + +/// Encode the inverse of [`decode_max_delay`]. Before lite-07 no limit goes out as +/// [`MAX_SAFE_DELAY_MS`]. +fn encode_max_delay( + w: &mut Encoder<'_>, + version: Version, + max_delay: Option, +) -> Result<(), EncodeError> { + let millis = max_delay + .map(|max| u64::try_from(max.as_millis()).map_err(|_| EncodeError::BoundsExceeded)) + .transpose()?; + match version.has_unlimited_max_delay() { + true => w.varint_opt(millis), + false => w.varint(millis.unwrap_or(MAX_SAFE_DELAY_MS)), + } +} + /// Decode the `Subscriber Min Age` after the max age: milliseconds plus one, zero meaning not /// stated. A wire without the field decodes as not stated. fn decode_min_delay(r: &mut Decoder<'_>, version: Version) -> Result, DecodeError> { @@ -330,22 +351,25 @@ fn decode_range_list(r: &mut Decoder<'_>) -> Result, DecodeError> { fn encode_range_list(w: &mut Encoder<'_>, ranges: &[Range]) -> Result<(), EncodeError> { w.varint(ranges.len() as u64)?; for range in ranges { - encode_anchor(w, range.start)?; - encode_anchor(w, range.end)?; + for (anchor, end) in [(range.start, false), (range.end, true)] { + let (kind, value) = wire_anchor(anchor, end)?; + w.varint(kind)?; + if let Some(value) = value { + w.varint(value)?; + } + } } Ok(()) } -/// The bytes a lite-07 range takes on the wire, or `None` past the varint's reach. +/// The bytes a lite-07 range takes on the wire, or `None` when it can't go out. fn range_size(range: &Range, form: Form) -> Option { let size = |value| varint::size(value, form).ok(); - let anchor = |anchor: Option| match anchor { - None => size(0), - Some(Anchor::Absolute(position)) => Some(size(1)? + size(position.group)?), - Some(Anchor::Relative(back)) => Some(size(2)? + size(back)?), - Some(Anchor::Time(pts)) => Some(size(3)? + size(pts)?), + let anchor = |anchor, end| -> Option { + let (kind, value) = wire_anchor(anchor, end).ok()?; + Some(size(kind)? + value.map_or(Some(0), size)?) }; - Some(anchor(range.start)? + anchor(range.end)?) + Some(anchor(range.start, false)? + anchor(range.end, true)?) } /// Decode one lite-07 range end: its type, then the fields that type carries. Type 0 is no @@ -353,32 +377,30 @@ fn range_size(range: &Range, form: Form) -> Option { fn decode_anchor(r: &mut Decoder<'_>) -> Result, DecodeError> { Ok(match r.varint()? { 0 => None, - 1 => Some(Anchor::Absolute(crate::track::Position::group(r.varint()?))), + 1 => Some(Anchor::Time(r.varint()?)), 2 => Some(Anchor::Relative(r.varint()?)), - 3 => Some(Anchor::Time(r.varint()?)), _ => return Err(DecodeError::InvalidValue), }) } -/// Encode the inverse of [`decode_anchor`]. A range covers whole groups, so a position -/// partway through one is refused: FETCH reads a slice of a group. -fn encode_anchor(w: &mut Encoder<'_>, anchor: Option) -> Result<(), EncodeError> { - match anchor { - None => w.varint(0), - Some(Anchor::Absolute(position)) if position.frame != 0 => Err(EncodeError::Version), - Some(Anchor::Absolute(position)) => { - w.varint(1)?; - w.varint(position.group) - } - Some(Anchor::Relative(back)) => { - w.varint(2)?; - w.varint(back) - } - Some(Anchor::Time(pts)) => { - w.varint(3)?; - w.varint(pts) - } - } +/// The lite-07 type and value of a range's start or `end`, the inverse of [`decode_anchor`]. +/// +/// An absolute position goes out as its group's time: a start as is, and an exclusive end as +/// the inclusive time just before it, an end at group 0 holding nothing a time can say. A +/// range covers whole groups, so a position partway through one is refused: FETCH reads a +/// slice of a group. +fn wire_anchor(anchor: Option, end: bool) -> Result<(u64, Option), EncodeError> { + Ok(match anchor { + None => (0, None), + Some(Anchor::Time(time)) => (1, Some(time)), + Some(Anchor::Relative(back)) => (2, Some(back)), + Some(Anchor::Absolute(position)) if position.frame != 0 => return Err(EncodeError::Version), + Some(Anchor::Absolute(position)) if end => ( + 1, + Some(position.group.checked_sub(1).ok_or(EncodeError::InvalidState)?), + ), + Some(Anchor::Absolute(position)) => (1, Some(position.group)), + }) } /// Step over the retired `Ordered` byte on a version whose layout still has it. @@ -592,14 +614,24 @@ impl<'a> Message<'a> for SubscribeOk { /// group, and at frame 0 of a later one otherwise. #[derive(Clone, Debug)] pub struct SubscribeStart { - /// The publisher's largest (group, frame) when it answered, `None` for a track with - /// nothing yet. Lite07+ only; not on the wire before, where it decodes as `None`. - pub largest: Option, + /// The publisher's largest when it answered, `None` for a track with nothing yet. Lite07+ + /// only; not on the wire before, where it decodes as `None`. + pub largest: Option, /// The group each range's delivery starts at, by index, `None` for a range with no /// group there. Before lite-07 the wire carries the one range's start as `Group`. pub starts: Vec>, } +/// The publisher's largest position, as SUBSCRIBE_OK reports it. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Largest { + /// The newest group and its last frame so far. + pub position: crate::track::Position, + /// The group ended at that frame, so no frame follows it: a reader knows at once that it + /// isn't the live one. + pub ended: bool, +} + impl<'a> Message<'a> for SubscribeStart { const CONTROL: Option = Some(crate::stats::Message::Subscribe); fn decode_msg(r: &mut Decoder<'a>, version: Version) -> Result { @@ -613,11 +645,19 @@ impl<'a> Message<'a> for SubscribeStart { starts: vec![Some(r.varint()?)], }); } - // Group + 1, so 0 is a track with nothing yet; the frame follows only otherwise. + // Group + 1, so 0 is a track with nothing yet; the frame and whether the group ended + // follow only otherwise. let largest = match r.varint_opt()? { - Some(group) => Some(crate::track::Position { - group, - frame: r.varint()?, + Some(group) => Some(Largest { + position: crate::track::Position { + group, + frame: r.varint()?, + }, + ended: match r.u8()? { + 0 => false, + 1 => true, + _ => return Err(DecodeError::InvalidValue), + }, }), None => None, }; @@ -639,9 +679,10 @@ impl<'a> Message<'a> for SubscribeStart { }; return w.varint(group); } - w.varint_opt(self.largest.map(|largest| largest.group))?; + w.varint_opt(self.largest.map(|largest| largest.position.group))?; if let Some(largest) = self.largest { - w.varint(largest.frame)?; + w.varint(largest.position.frame)?; + w.u8(largest.ended.into()); } w.varint(self.starts.len() as u64)?; for start in &self.starts { @@ -706,7 +747,8 @@ pub struct SubscribeUpdate { /// A join requesting this group or later, judged against the local refresh ratio. pub wanted_group: Option, pub priority: i8, - pub max_delay: std::time::Duration, + /// See [`Subscribe::max_delay`]. + pub max_delay: Option, /// See [`Subscribe::min_delay`]. pub min_delay: Option, /// The change to the ranges; see [`Subscribe::ranges`]. @@ -744,7 +786,7 @@ impl<'a> Message<'a> for SubscribeUpdate { let priority = super::priority::from_wire(r.u8()?); let order = decode_order(r, version)?; - let max_delay = std::time::Duration::from_millis(r.varint()?); + let max_delay = decode_max_delay(r, version)?; let min_delay = decode_min_delay(r, version)?; let ranges = match version.has_ranges() { true => { @@ -788,7 +830,7 @@ impl<'a> Message<'a> for SubscribeUpdate { w.u8(super::priority::to_wire(self.priority)); encode_order(w, version, self.order)?; - w.varint(u64::try_from(self.max_delay.as_millis()).map_err(|_| EncodeError::BoundsExceeded)?)?; + encode_max_delay(w, version, self.max_delay)?; encode_min_delay(w, version, self.min_delay)?; match (&self.ranges, version.has_ranges()) { (RangeEdit::Edit { remove, add }, true) => { @@ -1336,11 +1378,16 @@ mod test { } } - /// Lite-07 carries the publisher's largest position; earlier versions leave it off the - /// wire, so it decodes as `None` there. + /// Lite-07 carries the publisher's largest position and whether its group ended; + /// earlier versions leave it off the wire, so it decodes as `None` there. #[test] fn subscribe_start_carries_the_largest_position_on_lite07() { - for largest in [None, Some(crate::track::Position { group: 3, frame: 2 })] { + let position = crate::track::Position { group: 3, frame: 2 }; + for largest in [ + None, + Some(Largest { position, ended: false }), + Some(Largest { position, ended: true }), + ] { let resp = SubscribeResponse::Start(SubscribeStart { largest, starts: vec![Some(4)], @@ -1352,11 +1399,17 @@ mod test { } } let resp = SubscribeResponse::Start(SubscribeStart { - largest: Some(crate::track::Position { group: 3, frame: 2 }), + largest: Some(Largest { position, ended: true }), starts: vec![Some(4)], }); let buf = resp.encode_bytes(Version::Lite06).unwrap(); assert_eq!(buf.as_ref(), [0, 1, 4], "lite-06 has no largest position"); + + // Type, length, group + 1, frame, ended, then one start: any other ended is malformed. + let mut buf = resp.encode_bytes(Version::Lite07).unwrap().to_vec(); + assert_eq!(buf, [0, 5, 4, 2, 1, 1, 5]); + buf[4] = 2; + assert!(SubscribeResponse::decode_slice(&buf, Version::Lite07).is_err()); } /// Lite-07 says where each range starts in place of the one `Group` earlier versions @@ -1545,7 +1598,7 @@ mod test { broadcast: Path::from_static("room"), track: Cow::Borrowed("video"), priority: 3, - max_delay: std::time::Duration::from_millis(250), + max_delay: Some(std::time::Duration::from_millis(250)), min_delay: None, // Groups 7 through 9. ranges: vec![Range { @@ -1721,16 +1774,12 @@ mod test { )); } - /// Lite-07 carries every range, each end absolute, relative, at a time, or open. + /// Lite-07 carries every range, each end relative, at a time, or open. #[test] fn ranges_roundtrip_on_lite07() { let mut msg = subscribe_sample(); msg.ranges = vec![ Range::OLDEST, - Range { - start: absolute(7, 0), - end: absolute(9, 0), - }, Range { start: Some(Anchor::Relative(2)), end: Some(Anchor::Relative(0)), @@ -1740,8 +1789,8 @@ mod test { end: Some(Anchor::Time(3_500)), }, Range { - start: absolute(0, 0), - end: None, + start: Some(Anchor::Time(0)), + end: Some(Anchor::Time(u64::MAX)), }, ]; assert_eq!(roundtrip(&msg, Version::Lite07).ranges, msg.ranges); @@ -1751,7 +1800,7 @@ mod test { let update = SubscribeUpdate { wanted_group: None, priority: 3, - max_delay: std::time::Duration::from_millis(250), + max_delay: Some(std::time::Duration::from_millis(250)), min_delay: None, ranges: sent.edit(&msg.ranges).unwrap(), order: crate::track::Order::Ascending, @@ -1770,6 +1819,30 @@ mod test { assert_eq!(resolved, msg.ranges); } + /// Lite-07 has no absolute anchor: a group's position goes out as its start's time, an + /// exclusive end as the inclusive time before it, so the publisher reads the same groups. + #[test] + fn lite07_sends_an_absolute_anchor_as_a_time() { + let mut msg = subscribe_sample(); + msg.ranges = vec![Range { + start: absolute(7, 0), + end: absolute(10, 0), + }]; + assert_eq!( + roundtrip(&msg, Version::Lite07).ranges, + [Range { + start: Some(Anchor::Time(7)), + end: Some(Anchor::Time(9)), + }] + ); + // Nothing comes before group 0, so an end there is refused, as on the older wires. + msg.ranges[0] = Range { + start: None, + end: absolute(0, 0), + }; + assert!(matches!(encode(&msg, Version::Lite07), Err(EncodeError::InvalidState))); + } + /// A lite-07 range covers whole groups: an absolute anchor is its type and group alone, /// and one partway through a group is refused, since FETCH reads a slice of a group. #[test] @@ -1803,8 +1876,8 @@ mod test { let version = Version::Lite07; let (a, b, c) = ( Range { - start: absolute(1, 0), - end: absolute(5, 0), + start: Some(Anchor::Time(1)), + end: Some(Anchor::Time(4)), }, Range { start: Some(Anchor::Relative(3)), @@ -1823,7 +1896,7 @@ mod test { let update = SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: std::time::Duration::ZERO, + max_delay: Some(std::time::Duration::ZERO), min_delay: None, ranges: edit, order: crate::track::Order::Descending, @@ -1940,13 +2013,16 @@ mod test { Err(DecodeError::InvalidSubscribeLocation) )); - let mut buf = encode(&msg, version).unwrap(); - let last = buf.len() - 2; - buf[last] = 4; - assert!(matches!( - crate::coding::decode_from(&mut buf.as_slice(), version, Subscribe::decode_msg), - Err(DecodeError::InvalidValue) - )); + // Type 3 was a second time anchor before lite-07 settled on one. + for kind in [3, 4] { + let mut buf = encode(&msg, version).unwrap(); + let last = buf.len() - 2; + buf[last] = kind; + assert!(matches!( + crate::coding::decode_from(&mut buf.as_slice(), version, Subscribe::decode_msg), + Err(DecodeError::InvalidValue) + )); + } } /// An older wire carries one span with absolute ends, so anything else is refused for @@ -2003,7 +2079,7 @@ mod test { let update = SubscribeUpdate { wanted_group: wanted, priority: 0, - max_delay: std::time::Duration::ZERO, + max_delay: Some(std::time::Duration::ZERO), min_delay: None, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order: crate::track::Order::Descending, @@ -2017,6 +2093,38 @@ mod test { } } + /// Lite-07 encodes `Subscriber Max Age` as milliseconds plus one, 0 for no limit. An earlier + /// wire carries bare milliseconds, so no limit goes out as the largest every peer reads, and + /// Lite01/02 carry none at all, which decodes as no limit rather than the live edge. + #[test] + fn max_delay_says_no_limit_on_lite07() { + let ms = std::time::Duration::from_millis; + let encoded = |version: Version, max_delay| { + let mut buf = Vec::new(); + encode_max_delay(&mut Encoder::new(&mut buf, version.into()), version, max_delay).unwrap(); + let wire = Decoder::new(&buf, version.into()).varint().unwrap(); + let got = decode_max_delay(&mut Decoder::new(&buf, version.into()), version).unwrap(); + (wire, got) + }; + assert_eq!(encoded(Version::Lite07, None), (0, None)); + assert_eq!(encoded(Version::Lite07, Some(ms(0))), (1, Some(ms(0)))); + assert_eq!(encoded(Version::Lite07, Some(ms(250))), (251, Some(ms(250)))); + assert_eq!(encoded(Version::Lite06, Some(ms(250))), (250, Some(ms(250)))); + assert_eq!( + encoded(Version::Lite06, None), + (MAX_SAFE_DELAY_MS, Some(ms(MAX_SAFE_DELAY_MS))) + ); + + let mut msg = subscribe_sample(); + msg.max_delay = Some(ms(250)); + for version in [Version::Lite01, Version::Lite02] { + assert_eq!(roundtrip(&msg, version).max_delay, None, "{version}"); + } + assert_eq!(roundtrip(&msg, Version::Lite03).max_delay, Some(ms(250))); + msg.max_delay = None; + assert_eq!(roundtrip(&msg, Version::Lite07).max_delay, None); + } + /// Lite-07 carries `Subscriber Min Age` on SUBSCRIBE and SUBSCRIBE_UPDATE, keeping a stated /// zero apart from not stated; an earlier wire drops it, so it decodes as not stated. #[test] @@ -2037,7 +2145,7 @@ mod test { let update = SubscribeUpdate { wanted_group: None, priority: 0, - max_delay: std::time::Duration::ZERO, + max_delay: Some(std::time::Duration::ZERO), min_delay, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order: crate::track::Order::Descending, @@ -2066,7 +2174,7 @@ mod test { let update = SubscribeUpdate { wanted_group: None, priority: 3, - max_delay: std::time::Duration::from_millis(250), + max_delay: Some(std::time::Duration::from_millis(250)), min_delay: None, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 6f58dc51e3b..885d6d26f66 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -3782,7 +3782,7 @@ mod tests { .await .unwrap(), id: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, start: None, priority: 0, @@ -3944,7 +3944,7 @@ mod tests { .await .unwrap(), id: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, start: Some(floor), priority: 0, @@ -4419,7 +4419,7 @@ mod tests { order: crate::track::Order::Descending, stream, id: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, start: Some(2), priority: 0, @@ -4536,7 +4536,7 @@ mod tests { order: crate::track::Order::Descending, stream, id: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, start: Some(4), priority: 0, @@ -4605,7 +4605,7 @@ mod tests { order: crate::track::Order::Descending, stream, id: 0, - max_delay: Duration::ZERO, + max_delay: Some(Duration::ZERO), min_delay: None, start: Some(4), priority: 0, @@ -4979,7 +4979,8 @@ mod tests { ); let mut accept = UniAccept::new(subscriber, early); assert!(accept.poll(&kio::Waiter::noop()).is_pending()); - assert!(log.stops().is_empty()); + // Only the early stream of an unknown type is stopped. + assert_eq!(log.stops().len(), usize::from(pre_read)); let mut group = consumer.recv_group().await.unwrap().unwrap(); assert_eq!(group.start, 3); let frame = group.read_frame().await.unwrap().unwrap(); @@ -6311,7 +6312,10 @@ mod tests { let largest = track::Position { group: 4, frame: 2 }; let mut responses = Vec::new(); lite::SubscribeResponse::Start(lite::SubscribeStart { - largest: Some(largest), + largest: Some(lite::Largest { + position: largest, + ended: true, + }), starts: vec![Some(4)], }) .encode( @@ -6363,6 +6367,8 @@ mod tests { }; kio::wait(|waiter| kio::Task::poll(&mut running, waiter)).await; + // Recorded as ended, so a relay serving this copy says so in its own SUBSCRIBE_OK. + assert!(reader.largest_finished(largest)); assert_eq!(reader.largest().await, Some(largest)); assert_eq!(reader.largest().await, None, "the stream ends with the aborted track"); assert!(matches!(reader.recv_group().await, Err(Error::ProtocolViolation))); @@ -6408,7 +6414,7 @@ mod tests { .await .unwrap(), id: 0, - max_delay: budget, + max_delay: Some(budget), min_delay: None, start: None, priority: 0, @@ -7778,7 +7784,7 @@ mod tests { waiting.now_or_never().expect("accepted").unwrap(); let (msg, trailing) = sent_subscribe(&sent(&session.log, 1), version); - assert_eq!(msg.max_delay, wait, "{version}: the subscriber's own max delay"); + assert_eq!(msg.max_delay, Some(wait), "{version}: the subscriber's own max delay"); assert!(!trailing, "{version}: a SUBSCRIBE_UPDATE followed the accept"); } } @@ -11215,7 +11221,8 @@ mod tests { /// /// A group ID is the group's start, so a time anchor goes out as the group ID it names, /// on every version: a time start as the start, and a time end as the exclusive group past -/// it. `None` when nothing is left to ask for, which no wire can say. The caller narrows a +/// it, which lite-07 carries as the inclusive time again (see [`lite::Anchor::Absolute`]). +/// `None` when nothing is left to ask for, which no wire can say. The caller narrows a /// subscription for a wire without ranges to the one span it carries first (see /// [`wire_span`]). /// @@ -11277,7 +11284,7 @@ struct SubStream { id: u64, /// Original SUBSCRIBE params, echoed in every SUBSCRIBE_UPDATE; refreshed as the /// downstream aggregate changes. - max_delay: Duration, + max_delay: Option, min_delay: Option, /// The lowest absolute start among the ranges, or `None` when one counts back from /// the latest group: the floor below which nothing is asked for. @@ -11965,7 +11972,7 @@ impl TrackServe { let start_moved = demand.is_some() && active.start != subscription.start(); active.priority = subscription.priority; active.order = subscription.order; - active.max_delay = wire_max_delay(subscription.delay.max); + active.max_delay = subscription.delay.max; active.min_delay = subscription.delay.min; // A lowered floor owes groups nobody asked for until now, in the session's // tail as well as in the track's arrivals, which its start declaration @@ -12282,12 +12289,6 @@ enum Begin { Establish(Establish), } -/// The `Subscriber Max Age` a SUBSCRIBE carries for [`Delay::max`](crate::track::Delay::max): `None` is the publisher's -/// max age alone, which the largest value every peer can read leaves to its clamp. -fn wire_max_delay(max_delay: Option) -> std::time::Duration { - max_delay.unwrap_or(std::time::Duration::from_millis(super::MAX_SAFE_DELAY_MS)) -} - /// Every group `ranges` name, which a stale drop under them was judged against. A bound only /// the publisher resolves is taken at its widest: a start from group 0, an end past the live /// edge (an exclusive end of `u64::MAX`). @@ -12409,7 +12410,7 @@ impl Establish { broadcast: self.serve.path.clone(), track: self.serve.name.as_str().into(), priority: self.subscription.priority, - max_delay: wire_max_delay(self.subscription.delay.max), + max_delay: self.subscription.delay.max, min_delay: self.subscription.delay.min, ranges: self.ranges.clone(), order: self.subscription.order, @@ -12454,7 +12455,7 @@ impl Establish { unanswered: (!answered).then(|| self.validity.clone()), stream, id: self.id, - max_delay: wire_max_delay(self.subscription.delay.max), + max_delay: self.subscription.delay.max, min_delay: self.subscription.delay.min, start: self.subscription.start(), live: lite::LiveRanges::new(self.serve.subscriber.version, &self.ranges), @@ -13749,13 +13750,15 @@ impl ServeLoop { // A bounded feed that never delivers Largest goes live at the // answer alone; one that does waits for it to show. // An answer behind the copy's cache fails it. - match active.never_serves(start.largest) { + let position = start.largest.map(|largest| largest.position); + match active.never_serves(position) { Some(largest) => self.serving.set_live_ahead(largest, served), - None => self.serving.set_live(start.largest, served), + None => self.serving.set_live(position, served), } .inspect_err(|err| tracing::warn!(track = %serve.name, %err, "subscribe start behind the cache"))?; + // Recorded whole, so a relay answers its own readers that the group ended. if let Some(largest) = start.largest { - self.serving.report_largest(largest); + self.serving.report_largest(largest.position, largest.ended); } } else if active.demand.is_some() && let Some(entry) = serve.subscriber.subscribes.lock().get_mut(&active.id) @@ -13876,7 +13879,7 @@ impl ServeLoop { for given in given.iter() { owed.extend( self.serving - .give_up(given.clone(), track::Hole::stale(active.max_delay)), + .give_up(given.clone(), track::Hole::stale(active.max_delay.unwrap_or(Duration::MAX))), ); } // Owed again by the next update, save what a stream may have won. diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 4079c6c2e3b..953effe71cf 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -194,6 +194,15 @@ impl Version { ) } + /// Whether SUBSCRIBE and SUBSCRIBE_UPDATE's `Subscriber Max Age` is milliseconds plus one, + /// so 0 says no limit. Added in lite-07; earlier wires carry bare milliseconds. + pub(crate) fn has_unlimited_max_delay(self) -> bool { + !matches!( + self, + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 + ) + } + /// Whether FETCH carries the subscriber's optional max delay. Added in lite-07; an /// earlier fetch is bounded by the publisher's max age alone. pub(crate) fn has_fetch_max_delay(self) -> bool { diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index c4eb29abb92..b98181e1326 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -779,6 +779,24 @@ impl Track { self.largest.read().open } + /// Whether `position` is the largest and its group ended there; see [`Self::finish_largest`]. + pub(super) fn largest_finished(&self, position: Position) -> bool { + let largest = self.largest.read(); + largest.position == Some(position) && !largest.open + } + + /// The source reported `position` as its largest, its group ended there when `finished`. + pub(super) fn report_largest(&self, position: Position, finished: bool) { + let mut largest = self.largest.lock(); + if largest.position.is_none_or(|current| position > current) { + largest.position = Some(position); + largest.open = true; + } + if finished && largest.position == Some(position) { + largest.open = false; + } + } + /// End the largest stream once the track ends: no newer frame can follow. pub(super) fn end_largest(&self) { let mut largest = self.largest.lock(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 666c7a21c09..7f809289b2a 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -331,6 +331,11 @@ impl Consumer { } } + /// Whether `position` is the serving copy's largest and its group ended there. + pub(super) fn largest_finished(&self, position: Position) -> bool { + self.serving().is_some_and(|copy| copy.largest_finished(position)) + } + /// Poll for a largest location within `bounds` newer than `seen` on the serving copy, /// recording it there. A copy ending is its route failing, so the logical track ends /// only with the route: at once when the front ends it, or with the last copy once the @@ -999,6 +1004,11 @@ impl Subscriber { self.reader().latest() } + /// Whether `position` is the serving copy's largest and its group ended there. + pub(super) fn largest_finished(&self, position: Position) -> bool { + self.reader().route.largest_finished(position) + } + /// Poll for a largest location within `bounds` newer than `seen`; see [`Consumer::poll_largest`]. pub(super) fn poll_largest( &mut self, diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index eeda631ad97..287f89ce641 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -4879,10 +4879,11 @@ impl Producer { } /// The source reported its largest frame, which [`Self::largest`] follows before the - /// frame itself arrives. A hint about the edge: it never makes the frame readable. + /// frame itself arrives, and whether its group ended there, which a relay forwards. A + /// hint about the edge: it never makes the frame readable. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn report_largest(&self, largest: Position) { - self.state.read().cache.advance_largest(largest); + pub(crate) fn report_largest(&self, largest: Position, finished: bool) { + self.state.read().cache.report_largest(largest, finished); } /// Whether readers may take from the cache; see [`Self::set_idle`]. @@ -6570,6 +6571,24 @@ impl Consumer { next } + /// Whether `position` is the largest and its group ended there, so no frame follows it. A + /// front's logical track asks the route serving it. + pub(super) fn largest_finished(&self, position: Position) -> bool { + self.with_state(|state| { + let Some(state) = state else { + return false; + }; + let (routes, cache) = { + let state = state.read(); + (state.routes.clone(), state.cache.clone()) + }; + match routes { + Some(routes) => routes.largest_finished(position), + None => cache.largest_finished(position), + } + }) + } + /// Poll for a largest frame within `bounds` newer than `seen`, recording it there. A /// front's logical track follows the route serving it. Reads the instance served now /// without asking for it, so a broadcast serving nothing under the name ends the stream. @@ -10589,6 +10608,16 @@ impl Subscriber { } } + /// Whether `position`, the largest, ended there: its group finished or closed, or its + /// source said so. An aborted group stays open, since it can be recreated or fetched. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn largest_finished(&self, position: Position) -> bool { + match &self.inner { + Inner::Plain(cursor) => cursor.state.read().cache.largest_finished(position), + Inner::Resume(resume, _) => resume.largest_finished(position), + } + } + /// The track's largest location known now, ignoring [`Self::with_range`], without waiting /// or moving [`Self::poll_largest`] on: past what the cache holds once the source /// reported a newer one. @@ -11704,21 +11733,21 @@ mod test { async fn largest_starts_with_the_sources_report() { let producer = track_producer("test", Info::default()); let mut subscriber = producer.subscribe(replay()); - producer.report_largest(Position { group: 7, frame: 3 }); + producer.report_largest(Position { group: 7, frame: 3 }, false); assert_eq!(subscriber.largest().await, Some(Position { group: 7, frame: 3 })); // A report is a hint about the edge, not a cached group. assert!(subscriber.recv_group().now_or_never().is_none()); // An older report or frame does not move it back. - producer.report_largest(Position { group: 7, frame: 1 }); + producer.report_largest(Position { group: 7, frame: 1 }, false); let mut _open = producer.create_group(group::Info { start: 2 }).unwrap(); _open .write_frame(crate::Timestamp::unscaled(_open.start), &b"a"[..]) .unwrap(); assert!(subscriber.largest().now_or_never().is_none()); - producer.report_largest(Position { group: 8, frame: 0 }); + producer.report_largest(Position { group: 8, frame: 0 }, false); assert_eq!(subscriber.largest().await, Some(Position { group: 8, frame: 0 })); } @@ -12046,7 +12075,7 @@ mod test { assert!(reader.poll_largest(&waiter).is_pending(), "the copy is idle"); producer.set_live(Some(Position::group(5)), None).unwrap(); - producer.report_largest(Position::group(5)); + producer.report_largest(Position::group(5), false); assert!( reader.poll_largest(&waiter).is_pending(), "the answer has not shown yet" From 28c5f03bb10669ccf794d93895b150014f36d8ab Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:56:33 -0800 Subject: [PATCH 05/26] feat(net)!: lite-07 drops and skips carry a span, and stale drops are final (JS) SUBSCRIBE_DROP and SUBSCRIBE_SKIP on lite-07 carry a non-empty [Group Start, Group End) span with an exclusive end. A decoded End not past Start is a protocol violation, and an empty span has no encoding. The version predicate is renamed hasGroupSpan. Earlier versions keep their inclusive Group End. The Update field leaves SUBSCRIBE, SUBSCRIBE_UPDATE, and SUBSCRIBE_DROP, and a SUBSCRIBE_UPDATE reopens nothing: - Publisher: no update numbers, no update-time re-offer or re-drop. A group the subscription told the wire about, served or dropped (stale or not), is never served or dropped again on it; only a skip goes out over a drop. The wire record's stale variant collapses into a plain final drop. - Subscriber: an OLD drop is final, accounted in the tail and recorded in the copy as a stale hole under the subscription's current budget, so a wider reader recovers the group through a request of its own. The per-update stale bookkeeping, the tail's reopen paths (restore, unaccount, finished streams) and Ledger.unaccount are gone. A drop that named a group being read ends it on a later YIELDED reset. - Model: the copy's judged ranges are gone; supersedeStale runs only when a new upstream subscription opens. reofferStale and reofferGroups are replaced by continueGroup, which serves only the YIELDED continuation. Tests that asserted reopening are deleted or flipped to the final behavior. Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 81 +----- js/net/src/fill.ts | 5 +- js/net/src/internal.ts | 48 +--- js/net/src/ledger.test.ts | 27 -- js/net/src/ledger.ts | 28 -- js/net/src/lite/drop_record.test.ts | 138 ++-------- js/net/src/lite/fills.test.ts | 3 +- js/net/src/lite/fills.ts | 4 +- js/net/src/lite/publisher.test.ts | 225 ++-------------- js/net/src/lite/publisher.ts | 107 ++------ js/net/src/lite/subscribe.test.ts | 73 +++--- js/net/src/lite/subscribe.ts | 68 ++--- js/net/src/lite/subscriber.test.ts | 234 +++-------------- js/net/src/lite/subscriber.ts | 242 ++++-------------- js/net/src/lite/version.ts | 6 +- js/net/src/lite/widened_max_age.test.ts | 86 +------ js/net/src/resume.test.ts | 152 +---------- js/net/src/resume.ts | 49 +--- js/net/src/tail.ts | 43 +--- js/net/src/track.test.ts | 138 +--------- js/net/src/track.ts | 324 +++++------------------- 21 files changed, 322 insertions(+), 1759 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 61763a19ca7..01763a2a833 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -1200,85 +1200,6 @@ test("fill: a stale run that does not settle the reader keeps its pending refusa await first.catch(() => undefined); }); -// The upstream judged 0..2 and 4..6 under 500ms, and gave up both of them as stale. -function judgedTwice() { - const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video", { maxAge: null }); - hooks.receiveTrack(track); - const requests = track.requests(); - hooks.supersedeStale(track, [ - { start: 0n, end: 2n }, - { start: 4n, end: 6n }, - ]); - hooks.dropTrackGroups(track, 0n, 2n, staleHole(500)); - hooks.dropTrackGroups(track, 4n, 6n, staleHole(500)); - const reader = (ranges: [bigint, bigint][]) => - track.subscribe({ - ranges: ranges.map(([start, end]) => ({ start: { absolute: start }, end: { absolute: end } })), - delay: { max: Duration.millis(500) }, - }); - return { broadcast, requests, reader }; -} - -// A stale verdict settles a reader that reads every range the upstream judged it against, however -// many there are, with nothing received and no fill asked. Mirrors Rust. -test("fill: a stale verdict settles a reader of every range it judged", async () => { - const { broadcast, requests, reader: subscribe } = judgedTwice(); - const reader = subscribe([ - [0n, 2n], - [4n, 6n], - ]); - expect(hooks.tryDrop(reader)).toMatchObject({ start: 0n, end: 2n, stale: 500 }); - expect(hooks.tryDrop(reader)).toMatchObject({ start: 4n, end: 6n, stale: 500 }); - expect(hooks.tryRecvGroup(reader, false)).toEqual({ kind: "done" }); - const fill = await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)]); - expect(fill).toBeUndefined(); - - reader.close(); - requests.close(); - broadcast.close(); -}); - -// A reader whose ranges only partly overlap the ones a stale verdict was judged against is settled -// where it reads every judged group above the run, and asks a fill for the rest, even with nothing -// received: no update brings it, since its ranges add nothing to the upstream's terms. Mirrors Rust. -test("fill: a stale verdict settles a partly overlapping reader only where it reads above", async () => { - const { broadcast, requests, reader: subscribe } = judgedTwice(); - // Reads every judged group above each run, and more past them: settled. - const wider = subscribe([ - [1n, 2n], - [4n, 8n], - ]); - expect(hooks.tryDrop(wider)).toMatchObject({ start: 1n, end: 2n, stale: 500 }); - expect(hooks.tryDrop(wider)).toMatchObject({ start: 4n, end: 6n, stale: 500 }); - expect(hooks.tryDrop(wider)).toBeUndefined(); - expect(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)])).toBeUndefined(); - // Stops at 4, which the upstream judged against 5: its own newest, which no verdict convicts. - // Both runs are unknown to it, and asked for. - const narrower = subscribe([ - [0n, 2n], - [4n, 5n], - ]); - expect(hooks.tryRecvGroup(narrower, false)).toEqual({ kind: "idle" }); - expect(hooks.tryDrop(narrower)).toBeUndefined(); - const asked: bigint[][] = []; - for (;;) { - const fill = await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)]); - if (!fill) break; - asked.push([fill.start, fill.end]); - } - asked.sort((a, b) => Number(a[0] - b[0])); - expect(asked).toEqual([ - [0n, 2n], - [4n, 5n], - ]); - - wider.close(); - narrower.close(); - requests.close(); - broadcast.close(); -}); - test("fill: a cache-miss fetch of a dynamic track serves the one track the broadcast already has", async () => { const broadcast = new BroadcastProducer(); // Pulled first, so the broadcast serves tracks on demand. @@ -1455,7 +1376,7 @@ test("fill: an OLD answer under the max age is held as stale until forgotten", a expect(hooks.tryDrop(later)).toMatchObject({ kind: "drop", start: 0n, end: 3n, stale: 10_000 }); expect(await asked()).toEqual([]); - expect(hooks.supersedeStale(track, undefined)).toEqual([{ start: 0n, end: 3n }]); + hooks.supersedeStale(track); const again = track.subscribe(terms); expect(again.tryRecvGroup()?.sequence).toBe(3n); again.tryRecvGroup(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index a7c7442494c..c519013a370 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -473,8 +473,9 @@ export interface Lookup { * judged under the request's own budget, or a max age not known here (`judged` undefined), it is * refused to the readers waiting now, a verdict only on those no more tolerant, so a wider reader * asks again; under the publisher's max age it binds every reader, so the track records it as a - * stale verdict under that age, which new terms or the drop set's expiry window forget. Any other - * refusal answers only `[start, end)`, for now. Mirrors the Rust `Fill::reject_groups`. + * stale verdict under that age, which a new upstream subscription or the drop set's expiry window + * forgets. Any other refusal answers only `[start, end)`, for now. Mirrors the Rust + * `Fill::reject_groups`. * @internal */ export let rejectGroups: (fill: Fill, start: bigint, end: bigint, error: Error, judged: Judged | undefined) => void; diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index de11cacebdb..367bbd672b2 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -526,13 +526,8 @@ export interface ResumeSource { fork(options?: Subscription): Subscriber; /** A fresh reader for a group still cached by one of this reader's copies. */ cachedGroup(sequence: bigint, from?: number): GroupConsumer | undefined; - /** See {@link hooks.reofferGroups}, answered by the serving copy. */ - reofferGroups(start: bigint, end: bigint, from?: number): { groups: GroupConsumer[]; givenUp: Run[] }; - /** - * See {@link hooks.reofferStale}: the stale runs queued here, those this reader reported, which a - * route change keeps, and those the serving copy reported. - */ - reofferStale(): Run[]; + /** See {@link hooks.continueGroup}, answered by the serving copy. */ + continueGroup(sequence: bigint, from: number): GroupConsumer | undefined; /** Let go of every copy. */ close(abort?: Error): void; } @@ -639,12 +634,10 @@ export const hooks: { */ skipTrackGroups: (producer: Producer, start: bigint, end: bigint) => Run[]; /** - * Forget every run a received copy holds as stale: the terms its upstream judged them under - * were replaced, so they are unknown again. `judged` is every group the new terms' ranges name, - * undefined when unknown. Returns the runs forgotten: a group that arrived since its stale drop - * replaced it, so it is not among them. Mirrors the Rust `supersede_stale`. + * Forget every run a received copy holds as stale: a new upstream subscription opened, whose + * terms are new, so those groups are unknown again. Mirrors the Rust `supersede_stale`. */ - supersedeStale: (producer: Producer, judged: readonly Run[] | undefined) => Run[]; + supersedeStale: (producer: Producer) => void; /** * Mark a track as fed by a wire subscription, which owes missing groups, until * {@link cacheTrack} ends it. `starts` says how that wire's start bounds the fills its readers @@ -799,26 +792,11 @@ export const hooks: { */ wire: (subscriber: Subscriber) => WireRecord; /** - * Re-offer what a subscriber gave up as stale through dispositions, as a wire whose every update - * reopens its stale drops does: each run is judged again under the new terms. Returns the runs - * taken back, which are owed again. Mirrors the Rust crate-private - * `track::Subscriber::reoffer_stale`. - */ - reofferStale: (subscriber: Subscriber) => Run[]; - /** - * Fresh reads of the groups in `[start, end)` a subscriber's track still caches, its range still - * admits, and its current budget no longer judges stale, each expiring against that budget, and - * the runs still given up: for a wire whose update re-offers a group whose stream it gave up as - * stale, or a lite-07 continuation of a group whose stream yielded. Each read starts at frame - * `from`, so a group whose cache holds only frames past it is given up. Mirrors the Rust - * crate-private `track::Subscriber::reoffer_groups`. + * A fresh read from frame `from` of group `sequence`, if a subscriber's track still caches it from + * there, its range still admits it, and its current budget does not judge it stale, expiring + * against that budget: a lite-07 continuation of a group whose stream yielded. */ - reofferGroups: ( - subscriber: Subscriber, - start: bigint, - end: bigint, - from?: number, - ) => { groups: GroupConsumer[]; givenUp: Run[] }; + continueGroup: (subscriber: Subscriber, sequence: bigint, from: number) => GroupConsumer | undefined; /** Whether this subscriber's budget gives up on `sequence`, judged by its successor; see {@link expireGroup}. */ staleAt: (subscriber: Subscriber, sequence: bigint) => Expiry; /** A group the subscriber's track still caches, as a fresh read handle. */ @@ -829,7 +807,8 @@ export const hooks: { givenUp: (subscriber: Subscriber, sequence: bigint) => { error?: Error; changed: Getter[] }; /** * The parts of `[start, end)` the subscriber's track still holds as a received stale run: one - * new terms superseded is gone. Mirrors the Rust crate-private `track::Subscriber::stale_held`. + * a new upstream subscription superseded is gone. Mirrors the Rust crate-private + * `track::Subscriber::stale_held`. */ staleHeld: (subscriber: Subscriber, start: bigint, end: bigint) => Run[]; /** Whether a group may still land on the live feed of the subscriber's track; see {@link Land}. */ @@ -1125,10 +1104,7 @@ export const hooks: { supersedeStale: () => { throw new Error("track.ts not loaded"); }, - reofferStale: () => { - throw new Error("track.ts not loaded"); - }, - reofferGroups: () => { + continueGroup: () => { throw new Error("track.ts not loaded"); }, deliveredRuns: () => { diff --git a/js/net/src/ledger.test.ts b/js/net/src/ledger.test.ts index cd790fa16dd..b687d942003 100644 --- a/js/net/src/ledger.test.ts +++ b/js/net/src/ledger.test.ts @@ -111,30 +111,3 @@ test("shuffled arrivals and bulk merges agree with the accounted sequence set", expect(ledger.hasGaps()).toBe(false); expect(ledger.covers(0n, 4128n)).toBe(true); }); - -test("unaccount reopens a gap for a fresh grace", () => { - const ledger = new Ledger(); - const grace = Duration.millis(1000); - ledger.account(0n, 10n, at(0)); - ledger.unaccount(3n, 5n, at(1000)); - expect(ledger.covers(0n, 3n) && ledger.covers(5n, 10n)).toBe(true); - expect(ledger.covers(3n, 5n)).toBe(false); - // Its grace runs from the reversal. - ledger.expire(at(1500), grace); - expect(ledger.covers(3n, 5n)).toBe(false); - ledger.expire(at(2000), grace); - expect(ledger.covers(0n, 10n)).toBe(true); -}); - -test("unaccount restarts the older gap it joins", () => { - const ledger = new Ledger(); - const grace = Duration.millis(1000); - ledger.account(0n, 2n, at(0)); - ledger.account(4n, 6n, at(0)); - ledger.unaccount(1n, 2n, at(900)); - // Its grace runs from the reversal, not from when the older gap opened. - ledger.expire(at(1000), grace); - expect(ledger.covers(1n, 2n)).toBe(false); - ledger.expire(at(1900), grace); - expect(ledger.covers(0n, 6n)).toBe(true); -}); diff --git a/js/net/src/ledger.ts b/js/net/src/ledger.ts index 818399320d3..0fc199e3274 100644 --- a/js/net/src/ledger.ts +++ b/js/net/src/ledger.ts @@ -152,34 +152,6 @@ export class Ledger { return gaps; } - /** - * Take `[start, end)` back out of what is accounted for, owed again from `at`: a verdict that - * accounted for it was reversed. The gap it leaves opens at `at`, so it is waited for a fresh - * grace, even where it joins an older gap. Mirrors the Rust `Ledger::unaccount`. - */ - unaccount(start: bigint, end: bigint, at: Instant): void { - if (start >= end) return; - const lower = this.#runs.floor(start); - const overlapping: Run[] = []; - for (const run of this.#runs.from(lower?.start ?? start)) { - if (run.start >= end) break; - if (run.end > start) overlapping.push(run); - } - if (overlapping.length === 0) return; - for (const run of overlapping) { - this.#remove(run); - if (this.#last === run) this.#last = undefined; - if (run.start < start) { - this.#insert({ start: run.start, end: start, since: run.since }); - } - if (end < run.end) { - this.#insert({ start: end, end: run.end, since: at }); - } - } - this.#last = this.#runs.last(); - this.demand(start, end, at); - } - /** Restart the age of every gap reaching into `[start, end)`, which the demand newly asks for. */ demand(start: bigint, end: bigint, at: Instant): void { if (start >= end) return; diff --git a/js/net/src/lite/drop_record.test.ts b/js/net/src/lite/drop_record.test.ts index 7198a775f42..25ff74d2001 100644 --- a/js/net/src/lite/drop_record.test.ts +++ b/js/net/src/lite/drop_record.test.ts @@ -34,7 +34,6 @@ interface Heard { start: bigint; end: bigint; error?: number; - update?: bigint; } /** @@ -64,7 +63,6 @@ function tap() { start: msg.start, end: msg.end, error: msg.error, - update: msg.update, }; heard.push(entry); if (hold?.(entry)) await new Promise((release) => held.push(release)); @@ -87,12 +85,12 @@ function tap() { heard, updates, held, - /** The drops and skips heard on `hop` from entry `from` on, as `[kind, start, end, code, update]`. */ + /** The drops and skips heard on `hop` from entry `from` on, as `[kind, start, end, code]`. */ on(hop: Hop, from = 0) { return heard .slice(from) .filter((entry) => entry.hop === hop) - .map((entry) => [entry.kind, entry.start, entry.end, entry.error, entry.update]); + .map((entry) => [entry.kind, entry.start, entry.end, entry.error]); }, hold(fn: ((heard: Heard) => boolean) | undefined) { hold = fn; @@ -107,10 +105,10 @@ function tap() { /** * A publisher's session on `up` to a relay, and the relay's session on `down` to a viewer. The * relay serves the viewer from its received copy of the publisher's broadcast, as a JS relay does. - * The publisher's track caches into a pool that ages a group out only past `expiry`, never by - * default, so it still holds what the relay and the viewer evict on the manual clock. + * The publisher's track caches into a pool that never ages a group out, so it still holds what the + * relay and the viewer evict on the manual clock. */ -async function chain(up: Version, down: Version, expiry?: Duration) { +async function chain(up: Version, down: Version) { const alpn = (version: Version) => (version === Version.DRAFT_07 ? ALPN_07_WIP : ALPN_06); const upstream = createMockTransportPair(alpn(up)); const downstream = createMockTransportPair(alpn(down)); @@ -136,7 +134,7 @@ async function chain(up: Version, down: Version, expiry?: Duration) { })(); const broadcast = source.route(path).broadcast; const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); - hooks.poolTrack(track, new cache.Pool({ expiry })); + hooks.poolTrack(track, new cache.Pool({})); const remote = wireOf(viewer).consume(path); return { @@ -261,78 +259,6 @@ function behindTheEdge(write: (sequence: bigint, millis: number) => void) { write(sequence, millis); } -// Short enough for the publisher to age out what the relay and the viewer still hold. -const PUBLISHER_EXPIRY = Duration.millis(10_000); - -// A reader with a 1.5s budget is reported groups 1 and 2 stale through the relay, and those OLD -// drops are still in flight to the viewer when it widens to 10s, which the publisher, having -// evicted both, can only drop again. With `prompt`, that re-drop goes out under the widening -// before the track ends; otherwise the publisher's end sweep names it. -async function widening(prompt: boolean): Promise { - using clock = manual(); - const wire = tap(); - const chained = await chain(Version.DRAFT_07, Version.DRAFT_07, PUBLISHER_EXPIRY); - const reader = chained.remote.track("video").subscribe({ delay: { max: Duration.millis(1500) } }); - await chained.reached(); - chained.write(0n, 0); - expect(settled(await next(reader))).toEqual(["group", 0n]); - - wire.hold((heard) => heard.hop === "down" && heard.update === 0n); - behindTheEdge(chained.write); - expect([settled(await next(reader)), settled(await next(reader))]).toEqual([ - ["group", 3n], - ["group", 4n], - ]); - await until(clock, () => wire.held.length > 0); - expect(wire.on("up")).toEqual([ - ["drop", 1n, 2n, StreamCode.Old, 0n], - ["drop", 2n, 3n, StreamCode.Old, 0n], - ]); - - // The publisher no longer holds them: everything but its live edge ages out. - await clock.advance(PUBLISHER_EXPIRY.mul(2)); - chained.write(5n, 6100); - expect(settled(await next(reader))).toEqual(["group", 5n]); - - // The widening reaches both hops before the old drops land, which then settle nothing. - reader.update({ delay: { max: Duration.millis(10_000) } }); - await until(clock, () => wire.updates.length >= 2); - expect(wire.updates.map((update) => update.update)).toEqual([1n, 1n]); - wire.hold((heard) => heard.hop === "down" && heard.update === 1n); - wire.release(); - await until(clock, () => wire.on("down").length >= 2); - expect(hooks.staleHeld(reader, 1n, 3n)).toEqual([]); - expect(hooks.tryRecvGroup(reader, true).kind).toBe("idle"); - - // The re-drop under the widening's own number settles the widened reader for good. - if (!prompt) chained.track.finish(); - await until(clock, () => wire.held.length > 0); - expect(wire.on("down")).toEqual([ - ["drop", 1n, 2n, StreamCode.Old, 0n], - ["drop", 2n, 3n, StreamCode.Old, 0n], - ["drop", 1n, 3n, StreamCode.NotFound, 1n], - ]); - expect(hooks.tryRecvGroup(reader, true).kind).toBe("idle"); - wire.hold(undefined); - wire.release(); - expect(settled(await next(reader))).toEqual(["drop", 1n, 3n, StreamCode.NotFound]); - if (prompt) chained.track.finish(); - expect(await drain(clock, reader)).toEqual([["done"]]); - expect(chained.ended()).toBe(false); - - reader.close(); - await chained.close(); -} - -// Mirrors Rust `after_a_widening_the_old_updates_drop_settles_no_reader` in -// rs/moq-net/tests/integration/drop_record.rs. -test("a drop under the narrower update settles no reader once the widening is sent, and the end's re-drop under it does", () => - widening(false)); - -// Mirrors Rust `after_a_widening_the_old_updates_drop_settles_no_reader` in -// rs/moq-net/tests/integration/drop_record.rs. -test("a widening drops again at once what the publisher evicted", () => widening(true)); - // Readers on the viewer while the publisher still holds groups 0 to 5 and the relay and the // viewer evicted all but group 5: `owed` subscribed before the eviction and read nothing, `fresh` // subscribes after it, and `widened` gave groups 1 and 2 up as stale and widens after it. Each @@ -429,8 +355,8 @@ test("an origin's evicted drops cross the relay unchanged, and no update re-offe ]); for (const hop of ["up", "down"] as const) { expect(wire.on(hop)).toEqual([ - ["drop", 1n, 2n, StreamCode.Evicted, 0n], - ["drop", 3n, 4n, StreamCode.Evicted, 0n], + ["drop", 1n, 2n, StreamCode.Evicted], + ["drop", 3n, 4n, StreamCode.Evicted], ]); } @@ -470,8 +396,8 @@ for (const down of [Version.DRAFT_06, Version.DRAFT_07]) { ["drop", 2n, 3n, StreamCode.Old], ]); expect(wire.on("up")).toEqual([ - ["drop", 1n, 2n, 0, 0n], - ["drop", 2n, 3n, 0, 0n], + ["drop", 1n, 2n, 0], + ["drop", 2n, 3n, 0], ]); // A widened reader and a new one each find groups 1 and 2 still dropped, though the @@ -519,9 +445,9 @@ test("through a lite-06 upstream, a group reported dropped as it lands is fetche chained.write(7n, 7000); expect(groupsOf(await drain(clock, first))).toEqual([]); - // Reaches every group: the relay forwards the drop to the lite-07 viewer as a stale one, so - // the widening reopens it, and the widened reader fills 0 to 4 and 7 from the publisher, as - // a later reader does. + // Reaches every group: the relay forwards the drop to the lite-07 viewer as a stale one, which + // holds only for a budget no wider than its own, so the widened reader fills 0 to 4 and 7 from + // the publisher, as a later reader does. const all = [0n, 1n, 2n, 3n, 4n, 5n, 6n, 7n, 8n, 9n]; first.update({ delay: { max: Duration.millis(60_000) }, ranges: [{}] }); expect(groupsOf(await drain(clock, first))).toEqual([0n, 1n, 2n, 3n, 4n, 7n]); @@ -542,8 +468,7 @@ test("through a lite-06 upstream, a group reported dropped as it lands is fetche // pool's idle window. The readers in `readers` subscribe next: // a narrow one is judged stale for groups 1 and 2 while the viewer still holds the run, and takes // them once every hop forgot it, and a wide one is filled them through the relay from -// the publisher, which still holds them: fetched once the viewer's copy forgot the run too, and -// re-offered over both subscriptions by the widening update while it still holds it stale. +// the publisher, which still holds them. async function lostRun(readers: ("wide" | "narrow")[]): Promise { using clock = manual(); const wire = tap(); @@ -566,15 +491,13 @@ async function lostRun(readers: ("wide" | "narrow")[]): Promise { expect(settled(await next(reader))).toEqual(["group", 5n]); const before = chained.fetches(); const heard = wire.heard.length; - let received: bigint[] = []; for (const name of readers) { if (name === "wide") { const wide = chained.remote.track("video").subscribe(WIDE); const filled = await drain(clock, wide); expect(filled.filter((row) => row[0] !== "group")).toEqual([]); - received = groupsOf(filled) as bigint[]; - expect(received).toEqual(expect.arrayContaining([1n, 2n])); + expect(groupsOf(filled)).toEqual(expect.arrayContaining([1n, 2n])); expect(chained.fetches().up).toBeGreaterThan(before.up); wide.close(); } else { @@ -589,23 +512,10 @@ async function lostRun(readers: ("wide" | "narrow")[]): Promise { narrow.close(); } } - // Nothing a narrow budget gave up is named dropped for good on the wire, where it would settle - // every reader, wide ones too: a stale drop is reopened by the next update. The update asking - // for a recovered run may re-offer a group its recovery already delivered, whose duplicate - // stream the relay resets, which settles no reader. + // Nothing a narrow budget gave up is named dropped with anything but OLD on the wire, which + // would settle every reader, wide ones too. if (readers.includes("wide")) { - const final = wire.heard - .slice(heard) - .filter((row) => row.kind !== "drop" || row.error !== StreamCode.Old) - .filter( - (row) => - !( - row.kind === "drop" && - row.error !== StreamCode.NotFound && - row.end === row.start + 1n && - received.includes(row.start) - ), - ); + const final = wire.heard.slice(heard).filter((row) => row.kind !== "drop" || row.error !== StreamCode.Old); expect(final).toEqual([]); } expect(chained.ended()).toBe(false); @@ -651,8 +561,8 @@ test("a run of billions of sequences is settled by each reader in one step, drop } for (const hop of ["up", "down"] as const) { expect(wire.on(hop)).toEqual([ - ["drop", 1n, 1n + BILLIONS, StreamCode.Cancel, 0n], - ["skip", 1n + BILLIONS, 1n + 2n * BILLIONS, undefined, undefined], + ["drop", 1n, 1n + BILLIONS, StreamCode.Cancel], + ["skip", 1n + BILLIONS, 1n + 2n * BILLIONS, undefined], ]); } expect(chained.fetches()).toEqual(before); @@ -663,7 +573,7 @@ test("a run of billions of sequences is settled by each reader in one step, drop // Mirrors Rust `a_run_of_billions_settles_in_one_step` in // rs/moq-net/tests/integration/drop_record.rs. -for (const judged of ["reopened by a widening", "forgotten by the relay"] as const) { +for (const judged of ["unsettled by a widening", "forgotten by the relay"] as const) { test(`a run of billions ${judged} is judged again in one step`, async () => { using clock = manual(); const chained = await chain(Version.DRAFT_07, Version.DRAFT_07); @@ -676,17 +586,17 @@ for (const judged of ["reopened by a widening", "forgotten by the relay"] as con await chained.reached(); chained.write(0n, 0); expect(settled(await next(reader))).toEqual(["group", 0n]); - if (judged === "reopened by a widening") + if (judged === "unsettled by a widening") hooks.dropTrackGroups(chained.track, 1n, 1n + BILLIONS, staleHole(1500)); else chained.track.skipGroups(1n, 1n + BILLIONS); chained.write(1n + BILLIONS, 1000); - const expected = judged === "reopened by a widening" ? StreamCode.Old : StreamCode.NotFound; + const expected = judged === "unsettled by a widening" ? StreamCode.Old : StreamCode.NotFound; expect(settled(await next(reader))[3]).toBe(expected); expect(settled(await next(reader))).toEqual(["group", 1n + BILLIONS]); if (wide) await drain(clock, wide); const before = chained.fetches(); - if (judged === "reopened by a widening") reader.update({ delay: { max: null } }); + if (judged === "unsettled by a widening") reader.update({ delay: { max: null } }); else await clock.advance(cache.DEFAULT_EXPIRY.mul(2)); const after = await drain(clock, reader); expect(after.length).toBeLessThanOrEqual(1); diff --git a/js/net/src/lite/fills.test.ts b/js/net/src/lite/fills.test.ts index d5e50374ff3..c5e73c7378a 100644 --- a/js/net/src/lite/fills.test.ts +++ b/js/net/src/lite/fills.test.ts @@ -119,8 +119,7 @@ test("range fills: a stale drop of asked groups is recovered once, on a subscrip fills.poll(tail, true); expect(opened.map((entry) => entry.groups)).toEqual([{ start: 1n, end: 3n }]); // With the fill's priority. The recovered run leaves the subscription, though the rest of the - // fill's run stays asked: left in, any later update would reopen its stale drop there, and the - // publisher would serve it on both. + // fill's run stays asked: the subscription dropped it for good. expect(opened[0]?.priority).toBe(peer.fill.priority); expect(fills.ask.groups).toEqual([ { start: 0n, end: 1n }, diff --git a/js/net/src/lite/fills.ts b/js/net/src/lite/fills.ts index 0848c06e1ae..901c1142059 100644 --- a/js/net/src/lite/fills.ts +++ b/js/net/src/lite/fills.ts @@ -331,8 +331,8 @@ export class RangeFills { for (const sequence of this.#reading.keys()) if (!draining.some((run) => run.start <= sequence && sequence < run.end)) this.#reading.delete(sequence); this.#draining = draining; - // A run being recovered leaves the subscription, even out of a run kept whole: any later update - // reopens its stale drop there, and the publisher would serve it on both. + // A run being recovered leaves the subscription, even out of a run kept whole: the subscription + // dropped it for good, so asking it there again would never be answered. const remaining = this.#recovering.reduce((runs, run) => removeRun(runs, run.start, run.end), groups); // What finishes a stream still asks with what its fills asked. if (this.#held.length === 0 && remaining.length > 0) ask.priority = this.ask.priority; diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index a4f33c9dc93..fcc9526e4e3 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -1328,10 +1328,9 @@ for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { } }); - // A lite-07 stale (OLD) drop is no final verdict, so a group handed out after it is served, as - // when a front switches to a route that delivers what the old route reported stale, before the - // update that reopens it. Earlier versions' drops are final. Mirrors Rust. - test(`lite ${version}: a group ${version === Version.DRAFT_07 ? "replaces" : "stays dropped after"} a stale drop`, async () => { + // A stale (OLD) drop is final on its subscription, so a group handed out after it, as when a + // front switches to a route that delivers what the old route reported stale, is not served. + test(`lite ${version}: a group stays dropped after a stale drop`, async () => { const sub = await servedSubscription({ version, startGroup: 0n }); try { sub.serve(0n); @@ -1345,8 +1344,7 @@ for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { sub.serve(1n); sub.serve(2n); - const next = await sub.servedSequence(); - expect(next).toBe(version === Version.DRAFT_07 ? 1n : 2n); + expect(await sub.servedSequence()).toBe(2n); } finally { await sub.close(); } @@ -1490,177 +1488,45 @@ test("lite draft-06: a group stream that never completes is reset once the group } }); -// Lite-07 reopens every stale drop on an update, including one for a stream the publisher reset -// as stale: a group still stale under the new terms is dropped again under the new update's -// number, so the subscriber settles at once. Mirrors the Rust -// `an_update_reoffers_a_cached_expired_stream_on_lite07`. -test("lite draft-07: an update drops an expired stream again while it is still stale", async () => { - const clock = new Manual(); - const installed = clock.install(); - const budget = 1_000; - const sub = await servedSubscription({ - version: Version.DRAFT_07, - startGroup: 0n, - maxAge: Duration.millis(budget), - }); - try { - sub.serve(0n); - expect(await sub.servedSequence()).toBe(0n); - expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - - const reset = sub.stall(); - sub.serve(1n); - expect(await sub.servedHeader()).toBe(1n); - await flush(); - await clock.advance(Duration.millis(budget * 10)); - sub.serve(2n); - expect(await sub.servedSequence()).toBe(2n); - await clock.advance(Duration.millis(budget)); - expect(toStreamCode(fromTransport(await reset))).toBe(StreamCode.Old); - const first = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in first)) throw new Error("expected SUBSCRIBE_DROP"); - expect([first.drop.start, first.drop.end, first.drop.update]).toEqual([1n, 2n, 0n]); - - // The track's max age still caps the budget, so group 1 is still stale. - await replayUpdate({ priority: 1, startGroup: 0n, update: 1n, ...restate(Version.DRAFT_07) }).encode( - sub.client.writer, - Version.DRAFT_07, - ); - const again = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in again)) throw new Error("expected SUBSCRIBE_DROP"); - expect([again.drop.start, again.drop.end, again.drop.update]).toEqual([1n, 2n, 1n]); - } finally { - await sub.close(); - installed.close(); - } -}); - -// The drops and skips on a lite-07 subscribe stream up to its SUBSCRIBE_FINISH, with the update each -// drop names. +// The drops and skips on a lite-07 subscribe stream up to its SUBSCRIBE_FINISH. async function holesToEnd(reader: Reader): Promise { const holes: unknown[] = []; for (;;) { const next = await decodeSubscribeResponseMaybe(reader, Version.DRAFT_07); if (!next) return holes; - if ("drop" in next) holes.push(["drop", next.drop.start, next.drop.end, next.drop.update]); + if ("drop" in next) holes.push(["drop", next.drop.start, next.drop.end]); if ("skip" in next) holes.push(["skip", next.skip.start, next.skip.end]); if ("finish" in next) return holes; } } -// A group that wins over a lite-07 stale drop already sent retires it: the next update neither -// sends the drop again nor reopens the served group, and the end names nothing for it. Here a -// relay's upstream reported group 1 stale, then delivered it, as a front that switched routes -// does. Mirrors the Rust `a_group_served_over_a_stale_drop_retires_it`. -test("lite draft-07: a group served over a stale drop retires it", async () => { - const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); - try { - sub.serve(0n); - expect(await sub.servedSequence()).toBe(0n); - expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - - hooks.dropTrackGroups(sub.track, 1n, 2n, staleHole(60_000)); - const resp = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in resp)) throw new Error("expected SUBSCRIBE_DROP"); - expect([resp.drop.start, resp.drop.end]).toEqual([1n, 2n]); - sub.serve(1n); - expect(await sub.servedSequence()).toBe(1n); - - await replayUpdate({ priority: 1, startGroup: 0n, update: 1n, ...restate(Version.DRAFT_07) }).encode( - sub.client.writer, - Version.DRAFT_07, - ); - await flush(); - sub.serve(2n); - expect(await sub.servedSequence()).toBe(2n); - sub.track.finish(); - sub.track.close(); - // No second OLD, and no NOT_FOUND at the end. - expect(await holesToEnd(sub.client.reader)).toEqual([]); - } finally { - await sub.close(); - } -}); - -// A lite-07 stream that expired as stale is a stale drop like any other: a final drop the reader -// reaches for it later replaces it, and no update drops it again then. Mirrors the Rust -// `a_final_drop_replaces_an_expired_stream_on_lite07`. -test("lite draft-07: a final drop replaces an expired stream", async () => { +// A lite-07 stream that expired as stale is dropped for good: a final drop the reader reaches for it +// later does not go out over it (one still arriving, as a relay's copy from upstream, is cut by +// it), and a widening that admits it again does not re-offer it (one cached whole). +test.each([ + ["still arriving", true], + ["cached whole", false], +])("lite draft-07: an expired stream %s stays dropped", async (_, arriving) => { const clock = new Manual(); const installed = clock.install(); const budget = 1_000; - const sub = await servedSubscription({ - version: Version.DRAFT_07, - startGroup: 0n, - maxAge: Duration.millis(budget), - }); - try { - sub.serve(0n); - expect(await sub.servedSequence()).toBe(0n); - expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - - const reset = sub.stall(); - // Still arriving, as a relay's copy from upstream: the upstream's final drop ends it. One - // held whole would stay, since a group stream wins over its drop. - const arriving = sub.track.createGroup(1n); - arriving.writeFrame(textFrame("hello", Timestamp.fromMillis(1))); - expect(await sub.servedHeader()).toBe(1n); - await flush(); - await clock.advance(Duration.millis(budget * 10)); - sub.serve(2n); - expect(await sub.servedSequence()).toBe(2n); - await clock.advance(Duration.millis(budget)); - expect(toStreamCode(fromTransport(await reset))).toBe(StreamCode.Old); - const first = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in first)) throw new Error("expected SUBSCRIBE_DROP"); - expect([first.drop.start, first.drop.end, first.drop.update]).toEqual([1n, 2n, 0n]); - - hooks.dropTrackGroups(sub.track, 1n, 2n, { error: new StreamError(StreamCode(70), { message: "cut" }) }); - const final = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in final)) throw new Error("expected SUBSCRIBE_DROP"); - expect([final.drop.start, final.drop.end, final.drop.error]).toEqual([1n, 2n, 70]); - - await replayUpdate({ priority: 1, startGroup: 0n, update: 1n, ...restate(Version.DRAFT_07) }).encode( + const update = (maxDelay: number, id: bigint) => + new SubscribeUpdate({ priority: 1, startGroup: 0n, maxDelay, ...restate(Version.DRAFT_07, id) }).encode( sub.client.writer, Version.DRAFT_07, ); - await flush(); - sub.track.finish(); - sub.track.close(); - expect(await holesToEnd(sub.client.reader)).toEqual([]); - } finally { - await sub.close(); - installed.close(); - } -}); - -// A queued re-offer that a later update drops again as stale counts as given up: the track's end -// leaves that stale drop standing, rather than replacing it with a final one. Mirrors the Rust -// `a_redropped_reoffer_stays_stale_at_the_end_on_lite07`. -test("lite draft-07: a re-offer dropped again before it opens stays stale at the end", async () => { - const clock = new Manual(); - const installed = clock.install(); - // Well inside the cache window, so the expired group is still cached to re-offer. - const budget = 1_000; - const update = (update: bigint, maxDelay: number, writer: Writer) => - new SubscribeUpdate({ - priority: 1, - startGroup: 0n, - update, - maxDelay, - ...restate(Version.DRAFT_07, update - 1n), - }).encode(writer, Version.DRAFT_07); const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); try { sub.serve(0n); expect(await sub.servedSequence()).toBe(0n); expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - await update(1n, budget, sub.client.writer); + await update(budget, 0n); // The restated range resolves at once. expect("started" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); const reset = sub.stall(); - sub.serve(1n); + if (arriving) sub.track.createGroup(1n).writeFrame(textFrame("hello", Timestamp.fromMillis(1))); + else sub.serve(1n); expect(await sub.servedHeader()).toBe(1n); await flush(); await clock.advance(Duration.millis(budget * 10)); @@ -1670,62 +1536,23 @@ test("lite draft-07: a re-offer dropped again before it opens stays stale at the expect(toStreamCode(fromTransport(await reset))).toBe(StreamCode.Old); const first = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); if (!("drop" in first)) throw new Error("expected SUBSCRIBE_DROP"); - expect([first.drop.start, first.drop.end, first.drop.update]).toEqual([1n, 2n, 1n]); - - // Update 2 widens the budget, so group 1 is re-offered; update 3 restores it. Both arrive in - // one chunk, which the decoder reads without leaving the task, so update 3 is decoded - // before the task boundary the publisher yields after an update, and so before any pop. - const batch = await Writer.collect(Version.DRAFT_07, async (writer) => { - await update(2n, budget * 100, writer); - await update(3n, budget, writer); - }); - await sub.client.writer.write(batch); + expect([first.drop.start, first.drop.end, first.drop.error]).toEqual([1n, 2n, StreamCode.Old]); + + hooks.dropTrackGroups(sub.track, 1n, 2n, { error: new StreamError(StreamCode(70), { message: "cut" }) }); + await update(budget * 100, 1n); + expect("started" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); await flush(); + sub.serve(3n); + expect(await sub.servedSequence()).toBe(3n); sub.track.finish(); sub.track.close(); - expect(await holesToEnd(sub.client.reader)).toEqual([["drop", 1n, 2n, 3n]]); + expect(await holesToEnd(sub.client.reader)).toEqual([]); } finally { await sub.close(); installed.close(); } }); -// A drop the reader gave up as final with OLD, as one relayed from a lite-06 upstream is, goes out as -// a stale drop on lite-07, which the subscriber reopens on its next update, so each update drops it -// again rather than leave it owed. Mirrors the Rust -// `a_final_old_drop_is_dropped_again_by_each_update_on_lite07`. -test("lite draft-07: a final OLD drop is dropped again by each update", async () => { - const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); - try { - sub.serve(0n); - expect(await sub.servedSequence()).toBe(0n); - expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - - hooks.dropTrackGroups(sub.track, 1n, 2n, { error: new StreamError(StreamCode.Old) }); - const first = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in first)) throw new Error("expected SUBSCRIBE_DROP"); - expect([first.drop.start, first.drop.end, first.drop.update]).toEqual([1n, 2n, 0n]); - - for (const update of [1n, 2n]) { - await replayUpdate({ - priority: 1, - startGroup: 0n, - update, - ...restate(Version.DRAFT_07, update - 1n), - }).encode(sub.client.writer, Version.DRAFT_07); - await flush(); - } - sub.track.finish(); - sub.track.close(); - expect(await holesToEnd(sub.client.reader)).toEqual([ - ["drop", 1n, 2n, 1n], - ["drop", 1n, 2n, 2n], - ]); - } finally { - await sub.close(); - } -}); - // An update that lowers the start below SUBSCRIBE_START asks for those groups too, so the // end sweep drops them, as the Rust publisher does. test("lite draft-06: an update lowering the start is swept at the end", async () => { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 2bcc23536ed..c7697f4da5d 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -1262,7 +1262,6 @@ export class Publisher { named, floor, bounds, - update: msg.update, initial: BigInt(asked.length), }); @@ -1435,8 +1434,6 @@ export class Publisher { // The read cursor's floor; see {@link cursorFloor}. floor: bigint; bounds: FrameBounds; - /** The SUBSCRIBE's update number (0), which a drop echoes until an update replaces it. */ - update: bigint; // How many ranges the SUBSCRIBE carried, whose starts SUBSCRIBE_START reports. initial: bigint; }, @@ -1445,7 +1442,6 @@ export class Publisher { // What the wire was told of each sequence: served, or given up, and how. Kept in the // reader's own record, which its drops consult too. Undefined before lite-05. const record = named ? hooks.wire(track) : undefined; - let updateNumber = serving.update; // The read cursor's floor; the subscription's ranges cap it. let floor = serving.floor; const moveCursor = () => track.withRange({ start: { included: floor } }); @@ -1522,21 +1518,13 @@ export class Publisher { const holeMessage = (start: bigint, end: bigint, hole: Hole): SubscribeResponse => hole.skip && hasSkip(this.version) ? { skip: new SubscribeSkip({ start, end }) } - : { drop: SubscribeDrop.given(start, end, hole.error, this.version, updateNumber) }; + : { drop: SubscribeDrop.given(start, end, hole.error, this.version) }; - // Whether lite-07 names `hole` stale: an OLD drop, which the next update reopens. - const sentStale = (hole: Hole) => !hole.skip && toStreamCode(hole.error) === StreamCode.Old; - - // What the wire is told when `hole` goes out. Mirrors the Rust `TrackRun::report`. + // What the wire is told when `hole` goes out: on lite-07 a drop, which only a skip replaces. + // Mirrors the Rust `TrackRun::report`. const reportOf = (hole: Hole): Omit => { - // Every drop is final before lite-07. if (!hasSkip(this.version)) return { kind: "settled" }; - if (hole.skip) return { kind: "skip" }; - // The wire names every OLD drop stale, which the next update reopens. One given up as - // final, such as one relayed from a version whose drops are all final, is dropped again - // by each update, as an expired stream is. - if (sentStale(hole)) return { kind: "stale", ...(hole.stale === undefined ? { expired: true } : {}) }; - return { kind: "dropped" }; + return { kind: hole.skip ? "skip" : "dropped" }; }; // Give up, as `hole` says, whatever part of `[start, end)` this subscription has not been @@ -1553,9 +1541,8 @@ export class Publisher { }; // Forward a verdict the reader reached on `[start, end)`, which its record already took in, - // replacing what it goes out over: on lite-07, a skip any drop already sent, and a final - // drop a stale one, which the next update would otherwise reopen. A reader the earlier drop - // ended stays ended. + // replacing what it goes out over: on lite-07, a skip any drop already sent. A reader the + // earlier drop ended stays ended. const forward = async (start: bigint, end: bigint, hole: Hole): Promise => { if (!record || start >= end) return true; record.tell(start, end, reportOf(hole)); @@ -1563,10 +1550,6 @@ export class Publisher { return controls.response(encodeSubscribeResponse(stream, msg, this.version)); }; - // Record `[start, end)` as named stale (OLD) in a lite-07 drop that each update drops - // again, which a later verdict or group replaces. - const toldStale = (start: bigint, end: bigint) => record?.tell(start, end, { kind: "stale", expired: true }); - // The track's exclusive final boundary. A Rust subscriber feeds SUBSCRIBE_FINISH // straight into finish_at, so it must name the track's boundary (which counts // datagram sequences too), not the delivered range: a subscription cap can hold @@ -1616,17 +1599,13 @@ export class Publisher { const drops = new Signal(0); // Groups whose stream failed, with why, for the control stream to name, as runs. const pendingDrops: { start: bigint; end: bigint; error: Error }[] = []; - // The expired groups an update re-offers, still cached and in range, served again in turn. - const reoffered: group.Consumer[] = []; // Lite-07: a fresh read of the group `serving` served, whose stream the session reset to make // room, for a new stream to continue it at the same frames; undefined once the subscription's // budget or the cache gave it up. The Rust publisher keeps an unread clone of the reset // stream's cursor instead, which a read handle here cannot make. const continuation = (serving: RunGroup): RunGroup | undefined => { - const sequence = serving.group.sequence; // From the reset stream's Frame Start, which a cache holding only the group's tail can serve. - const [resumed, ...extra] = hooks.reofferGroups(track, sequence, sequence + 1n, serving.start).groups; - for (const other of extra) other.close(); + const resumed = hooks.continueGroup(track, serving.group.sequence, serving.start); if (!resumed) return undefined; return { ...serving, group: resumed, givenUp: new GivenUp(resumed) }; }; @@ -1657,14 +1636,8 @@ export class Publisher { } if (pendingDrops.length > 0) { for (const { start, end, error } of pendingDrops.splice(0)) { - const old = hasSkip(this.version) && toStreamCode(error) === StreamCode.Old; - // A stream expired under this subscription's budget is a stale verdict, which - // a later verdict or group replaces as any stale drop sent, and each update drops - // again. A re-offer an update owed again is given up now, so the end sweep never - // names it. - if (old) toldStale(start, end); - else record?.tell(start, end, reportOf({ error })); - const msg = SubscribeDrop.given(start, end, error, this.version, updateNumber); + record?.tell(start, end, reportOf({ error })); + const msg = SubscribeDrop.given(start, end, error, this.version); if (!(await controls.response(encodeSubscribeResponse(stream, { drop: msg }, this.version)))) return false; } @@ -1689,7 +1662,6 @@ export class Publisher { // An update may reach the finished track's history, so it is served again. finished = false; const update = control.update; - updateNumber = update.update; if (hasRanges(this.version)) { // A range retired before its start resolved is owed no SUBSCRIBE_STARTED. const live = new Set(control.ids); @@ -1718,7 +1690,7 @@ export class Publisher { // A lowered floor owes the groups it newly asks for, so the end sweep // covers them. A raised one sends no early drop: the subscriber already // stops owing below its floor, and a later update may lower it again to - // reopen those groups. + // ask for the groups the wire was told nothing of. if (startSequence !== undefined) startSequence = min(startSequence, start); } bounds.startGroup = update.startGroup; @@ -1726,44 +1698,6 @@ export class Publisher { bounds.endGroup = update.endGroup; bounds.endFrame = update.endFrame; moveCursor(); - // Lite-07 reopens every stale drop on any update, judged under its new terms - // (applied as the update was decoded): what was reported stale is offered - // again, and dropped again under this update's number if still stale. - if (hasSkip(this.version)) { - const owe = (start: bigint, end: bigint) => record?.untell(start, end); - for (const run of hooks.reofferStale(track)) owe(run.start, run.end); - // What each update drops again: the stale runs whose stream expired, or - // that went out OLD for good. - const expired: Run[] = record?.expired() ?? []; - // A stale drop not sent yet, such as one an earlier update left to drop - // again, is judged again under these terms too. - for (const pending of pendingDrops.filter( - (d) => toStreamCode(d.error) === StreamCode.Old, - )) - insertRun(expired, pending.start, pending.end); - pendingDrops.splice( - 0, - pendingDrops.length, - ...pendingDrops.filter((d) => toStreamCode(d.error) !== StreamCode.Old), - ); - // A group re-offered that has not opened yet is judged again too, since these - // terms may no longer admit it. - for (const group of reoffered.splice(0)) { - insertRun(expired, group.sequence, group.sequence + 1n); - group.close(); - } - // A group whose stream already reset as stale: one still cached, in range, and - // fresh under the new budget is served again; the rest is dropped again, by run. - for (const run of expired.splice(0)) { - const { groups, givenUp } = hooks.reofferGroups(track, run.start, run.end); - for (const group of groups) { - owe(group.sequence, group.sequence + 1n); - reoffered.push(group); - } - for (const gone of givenUp) - pendingDrops.push({ ...gone, error: new StreamError(StreamCode.Old) }); - } - } // A microtask is too short: decoding one framed update crosses several // awaits, each of which can requeue behind the serving continuation. A // task boundary usually lets the decoder finish whatever the transport @@ -1785,13 +1719,9 @@ export class Publisher { !startSent && hasLargest(this.version) ? newer(first?.largest, newer(hooks.bufferedLargest(track), hooks.peekLargest(track).largest)) : undefined; - // A group an update re-offers goes ahead of new ones. - const again = first ? undefined : reoffered.shift(); const recv = first ? ({ kind: "group", group: first.group } as const) - : again - ? ({ kind: "group", group: again } as const) - : hooks.tryRecvGroup(track, emitRange); + : hooks.tryRecvGroup(track, emitRange); first = undefined; switch (recv.kind) { case "error": @@ -1930,15 +1860,10 @@ export class Publisher { } const group = recv.group; - // Never a second stream for a sequence this subscription already accounted for - // (served, sent as a datagram, or dropped): before lite-07 a subscriber settles a - // drop for good. A stale drop a lite-07 update reopened is owed again (see the update above). - // A lite-07 stale drop is no final verdict, and a Group Stream wins over it, so a group - // handed out after one is served, as one a route the front switched to delivers: the - // update that reopens the drop would never re-offer it. - if (record?.toldStale(group.sequence)) { - record.replaceDrops(group.sequence, group.sequence + 1n); - } else if (record?.told(group.sequence)) { + // Never a second stream for a sequence this subscription already accounted for (served, + // sent as a datagram, or dropped, stale or not): a subscriber settles every drop for good, + // and a reader wider than a stale one asks for the group with a request of its own. + if (record?.told(group.sequence)) { group.close(); continue; } @@ -2040,8 +1965,6 @@ export class Publisher { } } finally { if (!finished) unsubscribe(); - // An update's re-offers are reads of their own, which closing the track leaves open. - for (const group of reoffered.splice(0)) group.close(); // A lite-07 subscriber FINs once it read the finished track's tail, or once it wants // nothing more, even while a reply is still being written. Either way the groups still // waiting for a slot are cancelled, but an opened stream may be a final group whose FIN diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 678dc05a089..d14a7506a0c 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -203,10 +203,10 @@ test("lite-07 carries the span as its only range, exclusive at the end", async ( test("a lite-07 list decodes as the span covering it", async () => { // Priority, order, max delay, and an unstated min delay as SubscribeUpdate writes them, - // then no Range ID to retire, the ranges it adds, the update number, and an absent wanted group. + // then no Range ID to retire, the ranges it adds, and an absent wanted group. const head = (await encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0, ranges: [] }))).slice(1, 5); const update = async (ranges: number[]) => { - const body = [...head, 0, ...ranges, 0, 0]; + const body = [...head, 0, ...ranges, 0]; const got = await SubscribeUpdate.decode( new Reader(undefined, new Uint8Array([body.length, ...body]), Version.DRAFT_07), Version.DRAFT_07, @@ -338,58 +338,63 @@ test("SubscribeFinish carries its error on draft-07", async () => { test("SubscribeDrop is restored on draft-07", async () => { const drop: SubscribeResponse = { drop: new SubscribeDrop({ start: 1n, end: 4n, error: 7 }) }; const wire = await encode(Version.DRAFT_07, drop); - // Groups 1 to 3 as a start and count; the drop names the SUBSCRIBE's update, 0. - expect(wire).toEqual(new Uint8Array([2, 4, 1, 3, 7, 0])); + // Groups 1 to 3 as a start and an exclusive end, then the code. + expect(wire).toEqual(new Uint8Array([2, 3, 1, 4, 7])); const got = await responseRoundtrip(Version.DRAFT_07, drop); if (!("drop" in got)) throw new Error("expected drop"); expect([got.drop.start, got.drop.end, got.drop.error]).toEqual([1n, 4n, 7]); -}); - -test("a drop names its update on draft-07 alone", async () => { - const drop = new SubscribeDrop({ start: 4n, end: 5n, error: 0x34, update: 2n }); - expect(await encode(Version.DRAFT_07, { drop })).toEqual(new Uint8Array([2, 4, 4, 1, 0x34, 2])); - const got = await responseRoundtrip(Version.DRAFT_07, { drop }); - if (!("drop" in got)) throw new Error("expected drop"); - expect(got.drop.update).toBe(2n); - const old = new SubscribeDrop({ start: 4n, end: 5n, error: 0, update: 2n }); - expect(await encode(Version.DRAFT_06, { drop: old })).toEqual(new Uint8Array([2, 3, 4, 4, 0])); - const back = await responseRoundtrip(Version.DRAFT_06, { drop: old }); - if (!("drop" in back)) throw new Error("expected drop"); - expect(back.drop.update).toBe(0n); + // Draft-06 carries an inclusive end. + expect(await encode(Version.DRAFT_06, drop)).toEqual(new Uint8Array([2, 3, 1, 3, 7])); }); test("SubscribeSkip is type 3 on draft-07 alone", async () => { const skip: SubscribeResponse = { skip: new SubscribeSkip({ start: 1n, end: 4n }) }; - expect(await encode(Version.DRAFT_07, skip)).toEqual(new Uint8Array([3, 2, 1, 3])); + expect(await encode(Version.DRAFT_07, skip)).toEqual(new Uint8Array([3, 2, 1, 4])); const got = await responseRoundtrip(Version.DRAFT_07, skip); if (!("skip" in got)) throw new Error("expected skip"); expect([got.skip.start, got.skip.end]).toEqual([1n, 4n]); await expect(encode(Version.DRAFT_06, skip)).rejects.toThrow(); }); -// Lite-07 carries Group Start and Group Count, which reach but never pass the reserved group 2^64-1. -// Mirrors the Rust `skip_ranges_on_lite07_count_up_to_the_reserved_group`. -test("lite-07 skip ranges count up to the reserved group", async () => { +// Lite-07 carries a non-empty `[Group Start, Group End)`, which reaches but never passes the +// reserved group 2^64-1. +test("lite-07 drop and skip spans are non-empty and stop at the reserved group", async () => { const top = (1n << 64n) - 1n; for (const [start, end] of [ - [0n, 0n], + [0n, 1n], [3n, 4n], [0n, top], - [top, top], + [top - 1n, top], ]) { - const got = await responseRoundtrip(Version.DRAFT_07, { skip: new SubscribeSkip({ start, end }) }); - if (!("skip" in got)) throw new Error("expected skip"); - expect([got.skip.start, got.skip.end]).toEqual([start, end]); + const skip = await responseRoundtrip(Version.DRAFT_07, { skip: new SubscribeSkip({ start, end }) }); + if (!("skip" in skip)) throw new Error("expected skip"); + expect([skip.skip.start, skip.skip.end]).toEqual([start, end]); + const drop = await responseRoundtrip(Version.DRAFT_07, { drop: new SubscribeDrop({ start, end, error: 7 }) }); + if (!("drop" in drop)) throw new Error("expected drop"); + expect([drop.drop.start, drop.drop.end, drop.drop.error]).toEqual([start, end, 7]); } - // Group Start 2^64-1, Group Count 1. - const wire = await encodeMessage(Version.DRAFT_07, new SubscribeSkip({ start: top, end: top })); - wire[wire.length - 1] = 1; - await expect(SubscribeSkip.decode(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow( - "invalid group range", - ); - for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { - await expect(encode(version, { drop: new SubscribeDrop({ start: 3n, end: 1n, error: 0 }) })).rejects.toThrow(); + + const decode = (body: number[]) => + decodeSubscribeResponse(new Reader(undefined, new Uint8Array(body), Version.DRAFT_07), Version.DRAFT_07); + // A Group End not past its Group Start is a protocol violation, empty or reversed. + await expect(decode([3, 2, 4, 4])).rejects.toThrow(ProtocolViolation); + await expect(decode([3, 2, 4, 3])).rejects.toThrow(ProtocolViolation); + await expect(decode([2, 3, 4, 4, 7])).rejects.toThrow(ProtocolViolation); + await expect(decode([2, 3, 4, 3, 7])).rejects.toThrow(ProtocolViolation); + + // An empty or reversed span has no encoding. + for (const [start, end] of [ + [3n, 3n], + [3n, 1n], + ]) { + await expect(encode(Version.DRAFT_07, { skip: new SubscribeSkip({ start, end }) })).rejects.toThrow(RangeError); + await expect(encode(Version.DRAFT_07, { drop: new SubscribeDrop({ start, end, error: 0 }) })).rejects.toThrow( + RangeError, + ); } + await expect( + encode(Version.DRAFT_06, { drop: new SubscribeDrop({ start: 3n, end: 1n, error: 0 }) }), + ).rejects.toThrow(); }); test("SubscribeDrop is type 0x2 on draft-05 and 0x1 on draft-04", async () => { diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 7dd534d0680..22337857112 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -21,8 +21,8 @@ import { hasDropCode, hasEndError, hasFrameBounds, - hasGroupCount, hasGroupOrder, + hasGroupSpan, hasMinDelay, hasOrder, hasRanges, @@ -32,16 +32,6 @@ import { Version, } from "./version.ts"; -/** Decode the `Update` number after the ranges. A wire without the field decodes as 0. */ -async function decodeUpdate(r: Reader, version: Version): Promise { - return hasSkip(version) ? await r.u62() : 0n; -} - -/** Encode the `Update` number, dropping it on a wire without the field. */ -async function encodeUpdate(w: Writer, version: Version, update: bigint) { - if (hasSkip(version)) await w.u62(update); -} - /** * Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. * @@ -627,8 +617,6 @@ export class SubscribeUpdate { * {@link remove}; {@link LiveRanges.apply} resolves a received update to every live range. */ ranges?: WireRange[]; - /** See {@link Subscribe.update}: larger than the subscription's previous one. */ - update: bigint; /** Lite-07: the Range IDs of the live ranges to retire before adding {@link ranges}. */ remove?: bigint[]; @@ -643,7 +631,6 @@ export class SubscribeUpdate { startFrame?: number; endFrame?: number; ranges?: WireRange[]; - update?: bigint; remove?: bigint[]; }) { if (props.wantedGroup !== undefined && props.wantedGroup < 0n) @@ -658,7 +645,6 @@ export class SubscribeUpdate { this.startFrame = props.startFrame ?? 0; this.endFrame = props.endFrame; this.ranges = props.ranges; - this.update = props.update ?? 0n; this.remove = props.remove; } @@ -693,7 +679,6 @@ export class SubscribeUpdate { } else { await encodeSpan(w, version, this, this.ranges); } - await encodeUpdate(w, version, this.update); if (hasRefresh(version)) await w.u62(this.wantedGroup === undefined ? 0n : this.wantedGroup + 1n); break; } @@ -718,7 +703,6 @@ export class SubscribeUpdate { } else { span = await decodeSpan(r, version); } - const update = await decodeUpdate(r, version); const wanted = hasRefresh(version) ? await r.u62() : 0n; return new SubscribeUpdate({ wantedGroup: wanted === 0n ? undefined : wanted - 1n, @@ -727,7 +711,6 @@ export class SubscribeUpdate { maxDelay, minDelay, ...span, - update, }); } } @@ -794,13 +777,6 @@ export class Subscribe { */ ranges?: WireRange[]; - /** - * The number of the terms in effect: the SUBSCRIBE is 0 and every SUBSCRIBE_UPDATE carries a - * larger one, which a {@link SubscribeDrop} echoes. Lite-07+; earlier wires decode as 0 and - * drop it on encode. - */ - update: bigint; - constructor(props: { id: bigint; broadcast: Path.Valid; @@ -817,7 +793,6 @@ export class Subscribe { startFrame?: number; endFrame?: number; ranges?: WireRange[]; - update?: bigint; }) { this.id = props.id; this.broadcast = props.broadcast; @@ -834,7 +809,6 @@ export class Subscribe { this.startFrame = props.startFrame ?? 0; this.endFrame = props.endFrame; this.ranges = props.ranges; - this.update = props.update ?? 0n; } async #encode(w: Writer, version: Version) { @@ -856,7 +830,6 @@ export class Subscribe { await encodeSpan(w, version, this, this.ranges); break; } - await encodeUpdate(w, version, this.update); } static async #decode(r: Reader, version: Version): Promise { @@ -876,7 +849,6 @@ export class Subscribe { const maxDelay = await r.u53(); const minDelay = await decodeMinDelay(r, version); const span = await decodeSpan(r, version); - const update = await decodeUpdate(r, version); return new Subscribe({ id, broadcast, @@ -889,7 +861,6 @@ export class Subscribe { maxDelay, minDelay, ...span, - update, }); } } @@ -1128,23 +1099,26 @@ export class SubscribeStarted { } /** - * A SUBSCRIBE_DROP or SUBSCRIBE_SKIP range: `Group Start` and `Group Count` on lite-07, an inclusive - * `Group Start` and `Group End` before. Either way it ends by the reserved sequence 2^64-1, so it - * never names that group. + * A SUBSCRIBE_DROP or SUBSCRIBE_SKIP range: a non-empty `[Group Start, Group End)` on lite-07, an + * inclusive `Group Start` and `Group End` before. Either way it ends by the reserved sequence + * 2^64-1, so it never names that group. */ async function decodeGroups(r: Reader, version: Version): Promise<{ start: bigint; end: bigint }> { const start = await r.u62(); - const end = hasGroupCount(version) ? start + (await r.u62()) : (await r.u62()) + 1n; - if (end < start || end >= UNBOUNDED) throw new ProtocolViolation(`invalid group range: [${start}, ${end})`); + const span = hasGroupSpan(version); + const end = span ? await r.u62() : (await r.u62()) + 1n; + if (end < start || (span && end === start) || end >= UNBOUNDED) + throw new ProtocolViolation(`invalid group range: [${start}, ${end})`); return { start, end }; } async function encodeGroups(w: Writer, start: bigint, end: bigint, version: Version) { - // An empty range at 0 has no inclusive end to spell before lite-07. - if (end < start || end >= UNBOUNDED || (end === 0n && !hasGroupCount(version))) + const span = hasGroupSpan(version); + // An empty range at 0 has no inclusive end to spell before lite-07, and lite-07 has no empty one. + if (end < start || end >= UNBOUNDED || (span ? end === start : end === 0n)) throw new RangeError(`invalid group range: [${start}, ${end})`); await w.u62(start); - await w.u62(hasGroupCount(version) ? end - start : end - 1n); + await w.u62(span ? end : end - 1n); } /** @@ -1160,28 +1134,20 @@ export class SubscribeDrop { /** One past the last dropped group sequence. */ end: bigint; error: number; - /** - * The number of the SUBSCRIBE or SUBSCRIBE_UPDATE in effect when the groups were given up - * ({@link Subscribe.update}): a stale (OLD) drop under a superseded one is no verdict. - * Lite-07+; earlier wires decode as 0. - */ - update: bigint; - constructor(props: { start: bigint; end: bigint; error: number; update?: bigint }) { + constructor(props: { start: bigint; end: bigint; error: number }) { this.start = props.start; this.end = props.end; this.error = props.error; - this.update = props.update ?? 0n; } - /** Name `[start, end)` given up with `err` under the terms numbered `update`, as `version` carries it. */ - static given(start: bigint, end: bigint, err: unknown, version: Version, update = 0n): SubscribeDrop { + /** Name `[start, end)` given up with `err`, as `version` carries it. */ + static given(start: bigint, end: bigint, err: unknown, version: Version): SubscribeDrop { return new SubscribeDrop({ start, end, // Before lite-07 the code is the application's, so it says nothing of why. error: hasDropCode(version) ? toStreamCode(err) : 0, - update: hasSkip(version) ? update : 0n, }); } @@ -1201,14 +1167,12 @@ export class SubscribeDrop { async #encode(w: Writer, version: Version) { await encodeGroups(w, this.start, this.end, version); await w.u53(this.error); - await encodeUpdate(w, version, this.update); } static async #decode(r: Reader, version: Version): Promise { const { start, end } = await decodeGroups(r, version); const error = await r.u53(); - const update = await decodeUpdate(r, version); - return new SubscribeDrop({ start, end, error, update }); + return new SubscribeDrop({ start, end, error }); } async encode(w: Writer, version: Version): Promise { diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 6ca2d3ec1e5..b0fe4889f14 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1578,58 +1578,13 @@ test("a yielded group a drop named ends", async () => { } }); -// Lite-07: a stale drop that overtook the YIELDED reset of the stream it names holds only under the -// update it names: once the subscriber sends another, the reset pauses the group, which the -// publisher then continues or drops again. Mirrors the Rust -// `a_yielded_group_pauses_once_an_update_supersedes_its_stale_drop`. -test("a yielded group pauses once an update supersedes its stale drop", async () => { - const version = Version.DRAFT_07; - const { quic, streams, opened } = fakeSession(); - const subscriber = new Subscriber(quic, version, toHop(1n)); - const track = subscriber - .consume(Path.from("room")) - .track("video") - .subscribe({ delay: { max: Duration.millis(60_000) } }); - try { - await opened(0); - await answerTrackInfo(streams[0], version, 1000); - const request = await opened(1); - await request.reading; - await respond(request, version, [{ start: new SubscribeStart([0n]) }]); - - const first = handStream(version); - first.write(await liteFrame(300, new Uint8Array([1]))); - const yielded = subscriber.runGroup(new Group({ subscribe: 0n, sequence: 3n }), first.reader); - const group = await track.recvGroup(); - expect(group?.sequence).toBe(3n); - expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([1])); - - await respond(request, version, [{ drop: new SubscribeDrop({ start: 3n, end: 4n, error: StreamCode.Old }) }]); - await drainReactions(); - track.update({ priority: 1, delay: { max: Duration.millis(60_000) } }); - await drainReactions(); - first.reset(StreamCode.Yielded); - await yielded; - await drainReactions(); - - expect(group?.closed.peek()).toBeUndefined(); - // The continuation picks the group up where the reset left it. - const second = handStream(version); - second.write(await liteFrame(10, new Uint8Array([2]))); - second.finish(); - await subscriber.runGroup(new Group({ subscribe: 0n, sequence: 3n, frameStart: 1 }), second.reader); - expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([2])); - expect(await group?.readFrame()).toBeUndefined(); - } finally { - track.close(); - subscriber.close(); - } -}); - -// Lite-07: a stale drop that overtook the header of the stream it names holds only under the update -// it names: once the subscriber sends another, a YIELDED reset of that stream pauses the group. -// Mirrors the Rust `a_yielded_group_pauses_once_an_update_supersedes_a_stale_drop_before_its_header`. -test("a yielded group pauses once an update supersedes a stale drop before its header", async () => { +// Lite-07: a stale drop is final on its subscription, so an update sent since does not undo it: a +// YIELDED reset of the stream it named, whether the drop overtook the reset or the stream's header, +// ends the group with OLD rather than pausing it for a continuation that never comes. +test.each([ + ["the reset", false], + ["the header", true], +])("a stale drop that overtook %s ends a yielded group after an update", async (_, beforeHeader) => { const version = Version.DRAFT_07; const { quic, streams, opened } = fakeSession(); const subscriber = new Subscriber(quic, version, toHop(1n)); @@ -1644,7 +1599,9 @@ test("a yielded group pauses once an update supersedes a stale drop before its h await request.reading; await respond(request, version, [{ start: new SubscribeStart([0n]) }]); - await respond(request, version, [{ drop: new SubscribeDrop({ start: 3n, end: 4n, error: StreamCode.Old }) }]); + const drop = () => + respond(request, version, [{ drop: new SubscribeDrop({ start: 3n, end: 4n, error: StreamCode.Old }) }]); + if (beforeHeader) await drop(); await drainReactions(); const first = handStream(version); first.write(await liteFrame(300, new Uint8Array([1]))); @@ -1652,21 +1609,20 @@ test("a yielded group pauses once an update supersedes a stale drop before its h const group = await track.recvGroup(); expect(group?.sequence).toBe(3n); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([1])); + if (!beforeHeader) await drop(); + await drainReactions(); track.update({ priority: 1, delay: { max: Duration.millis(60_000) } }); await drainReactions(); first.reset(StreamCode.Yielded); await yielded; - await drainReactions(); - expect(group?.closed.peek()).toBeUndefined(); - // The continuation picks the group up where the reset left it. - const second = handStream(version); - second.write(await liteFrame(10, new Uint8Array([2]))); - second.finish(); - await subscriber.runGroup(new Group({ subscribe: 0n, sequence: 3n, frameStart: 1 }), second.reader); - expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([2])); - expect(await group?.readFrame()).toBeUndefined(); + const read = await group?.readFrame().then( + () => undefined, + (err: unknown) => err, + ); + expect(read).toBeInstanceOf(StreamError); + expect((read as StreamError).code).toBe(StreamCode.Old); } finally { track.close(); subscriber.close(); @@ -1915,9 +1871,9 @@ test("a recovery waits for the continuation of a group a reset without its code } }); -// Lite-07: an update reopens a stale drop, so a stream that drop excused holds the end again -// until it finishes, even once the grace the end started before the update has passed. -test("an update restores the hold a stale drop excused", async () => { +// Lite-07: a stale drop is final, so a stream it excused stays excused through an update: the end +// waits for it no longer than the grace, as a browser may have lost its reset. +test("a stream a stale drop excused stays excused after an update", async () => { const clock = new Manual(); const installed = clock.install(); const version = Version.DRAFT_07; @@ -1943,18 +1899,10 @@ test("an update restores the hold a stale drop excused", async () => { track.update({ priority: 0, delay: { max: Duration.millis(60_000) } }); await drainReactions(); - let fin = false; - void request.finished.then(() => { - fin = true; - }); await clock.advance(GRACE.mul(3)); - expect(fin).toBe(false); - // The stream finishes the group, which lets the end go. - slow.write(await liteFrame(10, new Uint8Array([2]))); + await request.finished; slow.finish(); await running; - expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([2])); - await request.finished; } finally { track.close(); subscriber.close(); @@ -1962,9 +1910,9 @@ test("an update restores the hold a stale drop excused", async () => { } }); -// Lite-07: a continuation judged against a stale drop while it waits out the copy it replaces holds -// the end if an update reopened that drop meanwhile, as the copy it replaces would have. -test("an update while a continuation waits keeps its hold on the end", async () => { +// Lite-07: a duplicate stream waiting out the copy it may take over holds the end, even under a +// stale drop that overtook the first copy's header: it is owed once that copy fails or pauses. +test("a duplicate stream waiting out its copy holds the end", async () => { const clock = new Manual(); const installed = clock.install(); const version = Version.DRAFT_07; @@ -1987,14 +1935,12 @@ test("an update while a continuation waits keeps its hold on the end", async () const group = await track.recvGroup(); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([1])); - // SUBSCRIBE_FINISH starts the end's grace. The continuation arrives under the stale drop, and - // the update lands while it waits out the first copy. + // SUBSCRIBE_FINISH starts the end's grace. The duplicate arrives under the stale drop. await respond(request, version, [{ finish: new SubscribeFinish(1n) }]); await drainReactions(); const second = handStream(version); second.write(await liteFrame(0, new Uint8Array([1]))); const running = subscriber.runGroup(new Group({ subscribe: 0n, sequence: 0n }), second.reader); - track.update({ priority: 0, delay: { max: Duration.millis(60_000) } }); await drainReactions(); let fin = false; @@ -2103,10 +2049,10 @@ test("a lite-06 group reset with YIELDED ends", async () => { } }); -// A lite-07 re-offer can overtake the reset of the stream it replaces. It proves that reset, which -// a browser can lose, so it ends that copy at once and continues the group from the frames it -// holds: a reader already handed the group reads on, and a later one reads it whole. -test("a re-offer ends the copy still arriving and continues its group", async () => { +// A lite-07 continuation can overtake the YIELDED reset of the stream it replaces. It proves that +// reset, which a browser can lose, so it ends that copy at once and continues the group from the +// frames it holds: a reader already handed the group reads on, and a later one reads it whole. +test("a continuation ends the copy still arriving and continues its group", async () => { const version = Version.DRAFT_07; const { quic, streams, opened } = fakeSession(); const subscriber = new Subscriber(quic, version, toHop(1n)); @@ -2170,7 +2116,7 @@ test("a re-offer ends the copy still arriving and continues its group", async () expect((await next)?.payload).toEqual(new Uint8Array([8])); expect(await group?.readFrame()).toBeUndefined(); expect(await group?.closed).toBeNull(); - // One that had not reached it reads the re-offer whole. + // One that had not reached it reads the continuation whole. const later = subscriber.consume(Path.from("room")).track("video").subscribe(); try { const again = await later.recvGroup(); @@ -3328,11 +3274,10 @@ test("a widened range's SUBSCRIBE_STARTED resolves the feed's start", async () = } }); -// A group that arrives over a lite-07 stale (OLD) drop wins over it, whichever lands first: the -// publisher serves a group after its stale drop, as a front that switched routes does, and the -// group's stream may overtake the drop. The next update owes it no more, and a group still -// arriving is never aborted by the drop. Mirrors the Rust `a_group_wins_over_its_stale_drop`. -test("a group wins over its stale drop on lite-07", async () => { +// A lite-07 stale (OLD) drop accounts for its groups for good, whichever of it and a group's stream +// lands first: an update owes none of them again, and a group still arriving, such as one another +// subscription sharing the copy delivers, is never aborted by the drop. +test("a stale drop accounts for its groups for good on lite-07", async () => { const version = Version.DRAFT_07; const { quic, streams, opened } = fakeSession(); const subscriber = new Subscriber(quic, version, toHop(1n)); @@ -3394,9 +3339,7 @@ test("a group wins over its stale drop on lite-07", async () => { track.update({ priority: 1, delay: { max: Duration.millis(500) } }); await drainReactions(); - // Every group that arrived stays accounted for; the one that never arrived is owed again. - expect(entry.tail.covers(1n, 4n)).toBe(true); - expect(entry.tail.covers(4n, 5n)).toBe(false); + expect(entry.tail.covers(1n, 5n)).toBe(true); // Neither the drop nor the update aborts a group still arriving. expect(two.group.closed.peek()).toBeUndefined(); expect(three.group.closed.peek()).toBeUndefined(); @@ -3410,94 +3353,8 @@ test("a group wins over its stale drop on lite-07", async () => { } }); -// A group whose stream finished wins over a lite-07 stale drop that lands after the cache evicted -// it: the publisher served it over that drop, so the next update owes it no more. A stream that -// finished under an earlier update says nothing of a drop under the new one. Mirrors the Rust -// `a_finished_group_wins_over_a_late_stale_drop_once_evicted`. -test("a finished group wins over a late stale drop once evicted on lite-07", async () => { - const clock = new Manual(); - const installed = clock.install(); - const version = Version.DRAFT_07; - const { quic, streams, opened } = fakeSession(); - const subscriber = new Subscriber(quic, version, toHop(1n)); - type Entry = { - track: Producer; - tail: { - covers(start: bigint, end: bigint): boolean; - fold(): boolean; - }; - }; - let entry: Entry | undefined; - const internal = subscriber as unknown as { - runResponses: (stream: unknown, entry: Entry) => Promise; - }; - const runResponses = internal.runResponses.bind(internal); - const responses = spyOn(internal, "runResponses").mockImplementation((stream, captured) => { - entry = captured; - return runResponses(stream, captured); - }); - const broadcast = subscriber.consume(Path.from("room")); - const track = broadcast.track("video").subscribe({ delay: { max: Duration.millis(500) } }); - try { - await opened(0); - await answerTrackInfo(streams[0], version); - const stream = await opened(1); - await stream.reading; - const send = async (...resps: SubscribeResponse[]) => { - const chunks: Uint8Array[] = []; - const writer = new Writer( - new WritableStream({ write: (chunk) => void chunks.push(new Uint8Array(chunk)) }), - version, - ); - for (const resp of resps) await encodeSubscribeResponse(writer, resp, version); - for (const chunk of chunks) stream.inbound.enqueue(chunk); - await drainReactions(); - }; - const old = (sequence: bigint, update: bigint): SubscribeResponse => ({ - drop: new SubscribeDrop({ start: sequence, end: sequence + 1n, error: StreamCode.Old, update }), - }); - // A group stream that arrives whole, through the path that records it. - const arrive = (sequence: bigint) => - subscriber.runGroup( - new Group({ subscribe: 0n, sequence }), - new Reader(new ReadableStream({ start: (controller) => controller.close() }), undefined, version), - ); - // Everything below the live edge ages out of the cache. - const evict = () => clock.advance(DEFAULT_EXPIRY.mul(2)); - let priority = 0; - const update = async () => { - track.update({ priority: ++priority, delay: { max: Duration.millis(500) } }); - await drainReactions(); - }; - - await send({ start: new SubscribeStart([0n]) }); - await arrive(1n); - await arrive(10n); - await evict(); - await send(old(1n, 0n)); - await update(); - if (!entry) throw new Error("no subscription"); - expect(entry.tail.covers(1n, 2n)).toBe(true); - - // Finished under the first update, then judged stale under the second. - await arrive(2n); - await update(); - await evict(); - await send(old(2n, 2n)); - await update(); - expect(entry.tail.covers(2n, 3n)).toBe(false); - } finally { - responses.mockRestore(); - track.close(); - broadcast.close(); - subscriber.close(); - installed.close(); - } -}); - -// A SKIP, or any final drop, that follows an OLD drop of the same groups replaces it: an update -// reopens only stale verdicts, so the groups stay accounted for, and the skip stays final rather -// than being superseded with the OLD drop. An empty range names nothing. Mirrors Rust. +// A SKIP, or any final drop, that follows an OLD drop of the same groups replaces it in the copy: +// the groups stay accounted for through an update, and the skip stays final. Mirrors Rust. test("a skip or final drop replaces an earlier stale one on lite-07", async () => { const version = Version.DRAFT_07; const { quic, streams, opened } = fakeSession(); @@ -3533,9 +3390,6 @@ test("a skip or final drop replaces an earlier stale one on lite-07", async () = old(4n, 5n), { skip: new SubscribeSkip({ start: 1n, end: 3n }) }, { drop: new SubscribeDrop({ start: 4n, end: 5n, error: StreamCode.NotFound }) }, - // Empty ranges. - old(6n, 6n), - { skip: new SubscribeSkip({ start: 6n, end: 6n }) }, ] satisfies SubscribeResponse[]) { await encodeSubscribeResponse(writer, resp, version); } @@ -3797,9 +3651,8 @@ test("an update whose bound the wire can't carry fails the track", async () => { } }); -// A SUBSCRIBE_DROP can only echo an update the subscriber sent: one naming a later update is a -// protocol violation. Mirrors the Rust `a_drop_naming_an_unsent_update_is_a_protocol_violation`. -test("a lite-07 drop naming an unsent update closes the session", async () => { +// A lite-07 SUBSCRIBE_DROP whose Group End is not past its Group Start is a protocol violation. +test("a lite-07 drop with an empty span closes the session", async () => { const version = Version.DRAFT_07; const { quic, streams, opened, closes } = fakeSession(); const subscriber = new Subscriber(quic, version, toHop(1n)); @@ -3816,12 +3669,9 @@ test("a lite-07 drop naming an unsent update closes the session", async () => { version, ); await encodeSubscribeResponse(writer, { start: new SubscribeStart([0n]) }, version); - await encodeSubscribeResponse( - writer, - { drop: new SubscribeDrop({ start: 1n, end: 2n, error: StreamCode.Old, update: 1n }) }, - version, - ); for (const chunk of chunks) stream.inbound.enqueue(chunk); + // Type, length, Group Start 4, Group End 4, OLD. + stream.inbound.enqueue(new Uint8Array([2, 3, 4, 4, StreamCode.Old])); expect(await track.closed).toBeInstanceOf(ProtocolViolation); await drainReactions(); expect(closes.map((info) => info?.closeCode)).toEqual([SessionCode.ProtocolViolation]); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 87c757209da..39af2986664 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -22,7 +22,7 @@ import { toStreamCode, unauthorized, } from "../error.ts"; -import { fillChanged, type Judged, rejectGroups } from "../fill.ts"; +import { type Judged, rejectGroups } from "../fill.ts"; import type { Producer as FrameProducer } from "../frame.ts"; import * as netGroup from "../group.ts"; import { Cost, type Hop, MAX_HOPS, routesEqual, UNKNOWN_HOP, WireRoute } from "../hop.ts"; @@ -30,11 +30,8 @@ import * as Instance from "../instance.ts"; import { type Arriving, bestCandidate, - type DropRun, hiddenBelow, hooks, - insertDrop, - insertRun, maxDelayOf, minDelayOf, type Run, @@ -225,18 +222,9 @@ interface SubscribeEntry { floor?: bigint; // What `#declare` last declared, so an unchanged one is not declared again. declared?: { start?: bigint | null; requested?: bigint }; - // Whether a SUBSCRIBE_UPDATE went out, which the publisher may have read before answering. - updated?: boolean; - // The number of the latest SUBSCRIBE (0) or SUBSCRIBE_UPDATE sent: a stale drop given up under - // an earlier one is no verdict on the current terms. - update: bigint; // The max delay the latest SUBSCRIBE or SUBSCRIBE_UPDATE asked for, in milliseconds: the budget - // a stale drop under it was judged by. + // a stale drop is recorded under. maxDelay?: number; - // The runs `tail` accounts for by a stale drop under `update`: the next update reopens them, - // since the publisher re-offers or drops them again under it. - // Coalesced, so a peer repeating a drop holds one run, not one per message. - stale?: DropRun[]; // The subscribe stream, from the setup that registered this entry to its end. stream: SubscribeStream; // How many SUBSCRIBE_UPDATEs went out, so a tail settling past SUBSCRIBE_FINISH waits a fresh @@ -296,61 +284,32 @@ interface Yielding { supersede: () => void; } -// Stale drops expire on the next update. An already accounted header stays accounted, and -// `dropped` says whether a final drop overtook it, rather than a gap the grace gave up on. -type YieldVerdict = - | { kind: "owed" } - | { kind: "accounted"; dropped: boolean } - | { kind: "stale"; under: bigint; error: Error } - | { kind: "accounted-stale"; dropped: boolean; under: bigint; error: Error } - | { kind: "dropped"; error: Error }; - -// Whether a drop accounts for the group under `update`, so the subscription's end waits for its -// stream at most the grace: a browser can lose that stream's reset. Only a drop excuses it: a stream -// whose header came after the grace gave up on its gap is still delivering, and no reset is owed. -// A stale drop expires; one over a final drop falls back to it, as `yieldError` does. -function excused(verdict: YieldVerdict, update: bigint): boolean { +// An already accounted header stays accounted, and `dropped` says whether a drop overtook it, +// rather than a gap the grace gave up on. +type YieldVerdict = { kind: "owed" } | { kind: "accounted"; dropped: boolean } | { kind: "dropped"; error: Error }; + +// Whether a drop accounts for the group, so the subscription's end waits for its stream at most the +// grace: a browser can lose that stream's reset. Only a drop excuses it: a stream whose header came +// after the grace gave up on its gap is still delivering, and no reset is owed. +function excused(verdict: YieldVerdict): boolean { switch (verdict.kind) { case "owed": return false; case "accounted": return verdict.dropped; - case "stale": - return verdict.under >= update; - case "accounted-stale": - return verdict.dropped || verdict.under >= update; case "dropped": return true; } } -// The verdict a header starts with: owed, or accounted by a final drop (`dropped`), a stale drop -// under `staleUnder`, or a gap the grace gave up on. A stale drop over a final one falls back to it. -function headerVerdict(owed: boolean, dropped: boolean, staleUnder: bigint | undefined): YieldVerdict { - if (owed) return { kind: "owed" }; - if (staleUnder === undefined) return { kind: "accounted", dropped }; - const error = new StreamError(StreamCode.Old); - return dropped - ? { kind: "accounted-stale", dropped, under: staleUnder, error } - : { kind: "stale", under: staleUnder, error }; -} - -// Excuse the stream's hold on the end, or restore it, as its verdict now says. -function judge(yielding: Yielding, update: bigint): void { - if (excused(yielding.verdict, update)) yielding.counted.excuse(); - else yielding.counted.restore(); -} - -function yieldError(verdict: YieldVerdict, update: bigint): Error | undefined { +// The error a YIELDED reset ends the group with, since no continuation follows, or undefined when +// the group pauses. +function yieldError(verdict: YieldVerdict): Error | undefined { switch (verdict.kind) { case "owed": return undefined; case "accounted": return new StreamError(StreamCode.Old); - case "stale": - return verdict.under < update ? undefined : verdict.error; - case "accounted-stale": - return verdict.under < update ? new StreamError(StreamCode.Old) : verdict.error; case "dropped": return verdict.error; } @@ -418,21 +377,6 @@ export class Minted { } } -/** - * Every group `ranges` name, which a stale drop under them was judged against. A bound only the - * publisher resolves is taken at its widest: a start from group 0, an end past the live edge - * (`UNBOUNDED`). Mirrors the Rust `judged`. - */ -function judged(ranges: readonly track.Range[]): Run[] { - const runs: Run[] = []; - for (const range of ranges) { - const start = range.start?.absolute ?? 0n; - const end = range.end?.absolute ?? UNBOUNDED; - if (start < end) insertRun(runs, start, end); - } - return runs; -} - /** The groups a fill's range asks for: absolute at both ends, as `RangeFills` asks them. */ function fillRun(range: WireRange): Run | undefined { const start = range.start?.absolute; @@ -494,11 +438,6 @@ export class Subscriber { // group closes. #fetches = new Map }>(); - // The runs a lite-07 copy's subscription reported stale under an update it has since - // superseded: its publisher re-offers them, or drops them again under the new number, so a - // fill waits on the subscription for them rather than FETCHing a copy the re-offer duplicates. - #reoffers = new WeakMap>(); - // The peer's PROBE estimates, written as they arrive (Lite03+ only). #probe?: Signal; @@ -2234,9 +2173,6 @@ export class Subscriber { stream.abort(e); } finally { answering?.removeEventListener("abort", replaced); - // Nothing more is re-offered on this subscription. - this.#reoffers.get(producer)?.set([]); - this.#reoffers.delete(producer); this.#endPaused(entry); entry.tail.close(); entry.unanswered?.held.close(); @@ -2376,8 +2312,8 @@ export class Subscriber { resolvesStart: resolvesStart(this.version), fillsFromStart: fillsFromStart(this.version), }); - // The SUBSCRIBE's terms: the groups a stale drop under them was judged against. - hooks.supersedeStale(producer, judged(ranges)); + // A new upstream subscription: stale runs an earlier one reported were judged under other terms. + hooks.supersedeStale(producer); if (!hasRanges(this.version)) hooks.dropAnchors(producer); // Lite-06+ resolves where the feed starts only with SUBSCRIBE_START, so a relay serving // this copy holds its first group until the answer arrives. @@ -2395,7 +2331,6 @@ export class Subscriber { asked: [...ranges], live: new LiveRanges(this.version, msg.ranges ?? []), starts: new Map(), - update: 0n, sent: 0, stream: { kind: "setup" }, fillIds: new Set(), @@ -2812,13 +2747,6 @@ export class Subscriber { try { let last: bigint | undefined; for (let sequence = fill.wanted(); sequence !== undefined; sequence = fill.wanted()) { - // The subscription re-offers it, or drops it again, either of which answers the fill. - const reoffers = this.#reoffers.get(producer); - const reoffered = reoffers?.peek() ?? []; - if (reoffers && reoffered.some((run) => run.start <= sequence && sequence < run.end)) { - await race([fillChanged(fill), reoffers.changed()]); - continue; - } // Every fetch answers its group, so the same one coming back is a bug: closing the // fill names it dropped rather than fetching it forever. if (sequence === last) break; @@ -2867,7 +2795,6 @@ export class Subscriber { asked: ranges, live: new LiveRanges(this.version, msg.ranges ?? []), starts: new Map(), - update: 0n, sent: 0, // Its responses are read here, which owns this stream's end. stream: { kind: "setup" }, @@ -3052,15 +2979,6 @@ export class Subscriber { return bound === undefined ? undefined : { budget: bound, everyone: true }; } - // Settle `[start, end)` of what `producer`'s subscription re-offers: a stream or a verdict - // under the latest update answered it. - #reoffered(producer: track.Producer, start: bigint, end: bigint): void { - const reoffers = this.#reoffers.get(producer); - const runs = reoffers?.peek(); - if (!runs?.some((run) => run.start < end && start < run.end)) return; - reoffers?.set(removeRun(runs, start, end)); - } - // FETCH group `sequence` of `fill` and write it into the copy once the publisher answers: lite // has no FETCH_OK, so a publisher without the group resets the stream, which refuses the group // to the readers waiting now, as the Rust `GroupFill::reject` does. A fetch nobody waits on any @@ -3295,49 +3213,26 @@ export class Subscriber { this.#declare(entry); } } else if ("drop" in resp) { - // The publisher will never send these groups, so they are accounted for without a - // stream, and a reader of one still arriving ends with the drop's error now. A lite-07 - // stale drop leaves a group whose stream arrived, since the stream wins over it. - const { start, end, update } = resp.drop; - // It can only echo an update this subscriber sent. - if (update > entry.update) - throw new ProtocolViolation(`SUBSCRIBE_DROP names update ${update}, which was never sent`); + // The publisher will never send these groups on this subscription, so they are accounted + // for without a stream, and a reader of one still arriving ends with the drop's error now. + const { start, end } = resp.drop; const error = resp.drop.cause(this.version); - // On lite-07 an OLD drop is a stale verdict, which the next update reopens; every other - // drop is final, whatever update it names. - const stale = hasSkip(this.version) && toStreamCode(error) === StreamCode.Old; - // One given up under an update since replaced says nothing of the current terms: the - // publisher re-offers it or drops it again under the new number, so it is still owed, - // and a reader that wants it fills it meanwhile. - if (stale && update < entry.update) continue; - this.#reoffered(entry.track, start, end); - // Lite-07 tells a stream a final drop overtook from one whose gap the grace gave up on. - if (!stale && hasYield(this.version)) entry.tail.drop(start, end); + // Lite-07 tells a stream a drop overtook from one whose gap the grace gave up on. + if (hasYield(this.version)) entry.tail.drop(start, end); else entry.tail.account(start, end); // A paused group the drop names ends there: no continuation follows. - this.#dropPaused(entry, start, end, error, stale ? update : undefined); - // Judged under the budget this subscriber sent with that update. + this.#dropPaused(entry, start, end, error); + // On lite-07 an OLD drop is stale, judged under this subscription's budget: a reader + // wider than that does not settle on it, and asks for the group with a request of its own. + const stale = hasSkip(this.version) && toStreamCode(error) === StreamCode.Old; const hole = stale ? staleHole(entry.maxDelay ?? 0) : { error }; - // A group whose stream finished under this update was served over a stale drop, so it - // won, even once the cache evicted it. - const named = stale ? entry.tail.unfinished(start, end) : [{ start, end }]; - const recorded = named.flatMap((run) => hooks.dropTrackGroups(entry.track, run.start, run.end, hole)); - // A final drop is never reopened, even where it replaces a stale one. A sequence - // already skipped stays skipped, and one whose group arrived keeps it, so no update - // reopens either. - // Owed again by the next update. - entry.stale = stale - ? recorded.reduce((runs, run) => insertDrop(runs, run.start, run.end, hole), entry.stale ?? []) - : removeRun(entry.stale ?? [], start, end); + hooks.dropTrackGroups(entry.track, start, end, hole); entry.fills?.refuse(start, end, error); } else if ("skip" in resp) { - // Never produced, so nothing is waited for and no reader ends. A skip is final and - // replaces any drop of the same groups, stale or final, so no update reopens them; a - // reader a drop already ended stays ended. + // Never produced, so nothing is waited for and no reader ends. A skip replaces any drop of + // the same groups; a reader a drop already ended stays ended. const { start, end } = resp.skip; - this.#reoffered(entry.track, start, end); entry.tail.account(start, end); - entry.stale = removeRun(entry.stale ?? [], start, end); // A fill owing them is answered: the source never had them. entry.fills?.refuse(start, end, new NotFound(`group ${start}`)); // A group that arrived was produced after all, so the skip contradicts it: it keeps @@ -3545,37 +3440,8 @@ export class Subscriber { endGroup: inclusiveGroupEnd(span.end), ranges: edit?.add, remove: edit?.remove, - update: entry.update + 1n, }); - // A stale drop given up under the previous update may still be in flight, and this one - // may move the range or budget it was judged against, so the runs held as stale become - // unknown again: a reader fills them rather than trust an old verdict. - entry.update = update.update; entry.maxDelay = update.maxDelay; - entry.tail.updated(); - // A stream a stale drop excused holds the end again: that verdict no longer stands. - for (const yielding of entry.yielding?.values() ?? []) judge(yielding, entry.update); - const held = hooks.supersedeStale(entry.track, judged([...ranges, ...fillRanges])); - // A lite-07 publisher re-offers every group it reported stale on any update, and drops - // again under the new number what is still stale, so the tail owes every stale run again. - // A group that arrived since its stale drop won over it: the publisher served it, so it - // is neither re-offered nor owed again. - for (const run of entry.stale ?? []) { - for (const reopened of held) { - const start = max(run.start, reopened.start); - const end = min(run.end, reopened.end); - if (start < end) entry.tail.unaccount(start, end); - } - } - // Re-offered whether or not the copy still holds the stale verdict. - if (entry.stale?.length) { - const reoffers = this.#reoffers.get(track) ?? new Signal([]); - this.#reoffers.set(track, reoffers); - const runs = [...reoffers.peek()]; - for (const run of entry.stale) insertRun(runs, run.start, run.end); - reoffers.set(runs); - } - entry.stale = undefined; // Encoded apart from the write, so a bound the wire can't carry still fails the track. const encoded = await Writer.collect(this.version, (w) => update.encode(w, this.version)); // A failed write means the publisher stopped reading, as it does once it finishes the @@ -3586,7 +3452,6 @@ export class Subscriber { return; } if (refresh !== undefined) sentWanted = refresh; - entry.updated = true; entry.sent += 1; // A tail settling past SUBSCRIBE_FINISH re-judges what the update now asks for. entry.tail.touch(); @@ -3673,14 +3538,8 @@ export class Subscriber { const yields = hasYield(this.version); // Asked before this stream accounts for the group: a drop that overtook it named it. let owed = !tail.covers(group.sequence, group.sequence + 1n); - // A final drop that overtook this stream, rather than a gap the grace gave up on. + // A drop that overtook this stream, rather than a gap the grace gave up on. const dropped = !owed && tail.dropped(group.sequence); - // A stale drop that overtook this stream: the next update supersedes that verdict, so a - // YIELDED reset after it pauses the group. - const unowedUnder = - !owed && entry.stale?.some((run) => run.start <= group.sequence && group.sequence < run.end) - ? entry.update - : undefined; let producer: netGroup.Producer | undefined; let arriving: Arriving | undefined; let ingest: Ingest | undefined; @@ -3688,7 +3547,6 @@ export class Subscriber { const counted = tail.open(group.sequence); // Until the stream is read, or a pause hands it to the paused group. let read: (() => void) | undefined = counted.done; - this.#reoffered(track, group.sequence, group.sequence + 1n); try { // The publisher contradicted its own end, which no later group can repair. lite-05 @@ -3701,9 +3559,9 @@ export class Subscriber { track.abort(violation); throw violation; } - // A duplicate of a copy still arriving, such as a lite-07 re-offer that overtook the reset - // of the stream it replaces, waits unread, which flow control bounds. Created once that copy - // ends, it is refused as a duplicate if the copy finished and takes the group if it failed, + // A duplicate of a copy still arriving, such as one another subscription sharing the copy + // delivers, waits unread, which flow control bounds. Created once that copy ends, it is + // refused as a duplicate if the copy finished and takes the group if it failed, // continuing the reads of that copy, which wait while it is held. Its own reset ends the // wait; a clean end leaves it on the copy alone. A lite-07 copy a YIELDED reset pauses is // continued by this stream instead. @@ -3750,14 +3608,14 @@ export class Subscriber { supersede = resolve; }); yielding = { - verdict: headerVerdict(owed, dropped, unowedUnder), + verdict: owed ? { kind: "owed" } : { kind: "accounted", dropped }, counted, supersede, }; entry.yielding ??= new Map(); entry.yielding.set(group.sequence, yielding); - // A stale drop that still stands may already account for the group. - judge(yielding, entry.update); + // A drop may already account for the group. + if (excused(yielding.verdict)) counted.excuse(); } const format = { scale: timescale, compress: entry.compress, lengthFirst: hasLengthFirst(this.version) }; @@ -3773,9 +3631,6 @@ export class Subscriber { } producer.finish(); - // Only a group that arrived whole, not one a drop or the track ended meanwhile, and only - // where a lite-07 stale drop asks for it. - if (hasSkip(this.version) && producer.closed.peek() === null) tail.finish(group.sequence); stream.stop(StreamCode.Cancel); } catch (err: unknown) { // A violation ends the session, which the connection does once it escapes; anything @@ -3796,10 +3651,8 @@ export class Subscriber { if (producer && ingest && yielding && (toStreamCode(e) === StreamCode.Yielded || uncoded)) { this.#endYielding(entry, group.sequence, yielding); if (uncoded) counted.excuse(); - // A drop named the group first: the publisher gave it up, so nothing continues it. One - // that overtook the stream's header carried a stale verdict. - // A stale drop an update sent since superseded no longer ends the group. - const given = yieldError(yielding.verdict, entry.update); + // A drop named the group first: the publisher gave it up, so nothing continues it. + const given = yieldError(yielding.verdict); if (given) { producer.abort(given); return; @@ -3865,23 +3718,16 @@ export class Subscriber { if (entry.yielding?.get(sequence) === yielding) entry.yielding.delete(sequence); } - // A SUBSCRIBE_DROP named `[start, end)` with `error`, under update `staleUnder` when it is a - // lite-07 stale verdict: a paused group ends there, and one a stream is reading ends with it if - // a YIELDED reset would otherwise pause it, since no continuation follows, unless an update - // supersedes a stale drop first. Mirrors the Rust `TrackEntry::dropped`. - #dropPaused(entry: SubscribeEntry, start: bigint, end: bigint, error: Error, staleUnder?: bigint): void { + // A SUBSCRIBE_DROP named `[start, end)` with `error`: a paused group ends there, and one a stream + // is reading ends with it if a YIELDED reset would otherwise pause it, since no continuation + // follows. Mirrors the Rust `TrackEntry::dropped`. + #dropPaused(entry: SubscribeEntry, start: bigint, end: bigint, error: Error): void { for (const [sequence, yielding] of entry.yielding ?? []) { if (sequence < start || sequence >= end) continue; - const verdict = yielding.verdict; - if (staleUnder === undefined) yielding.verdict = { kind: "dropped", error }; - else if (verdict.kind !== "dropped") - yielding.verdict = - verdict.kind === "accounted" || verdict.kind === "accounted-stale" - ? { kind: "accounted-stale", dropped: verdict.dropped, under: staleUnder, error } - : { kind: "stale", under: staleUnder, error }; - // A drop that stands accounts for the group, so the end no longer waits on its stream - // past the grace: a browser that lost the stream's reset would otherwise hold it forever. - judge(yielding, entry.update); + yielding.verdict = { kind: "dropped", error }; + // The drop accounts for the group, so the end no longer waits on its stream past the + // grace: a browser that lost the stream's reset would otherwise hold it forever. + yielding.counted.excuse(); } const paused = entry.paused; if (!paused) return; diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 56dc6455bdc..4bd4b334b5e 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -598,10 +598,10 @@ export function hasDropCode(version: Version): boolean { } /** - * Whether SUBSCRIBE_DROP and SUBSCRIBE_SKIP carry `Group Start` and `Group Count`. Added in lite-07; - * earlier versions carry an inclusive `Group Start` and `Group End`. + * Whether SUBSCRIBE_DROP and SUBSCRIBE_SKIP carry a non-empty `[Group Start, Group End)` with an + * exclusive end. Added in lite-07; earlier versions carry an inclusive `Group Start` and `Group End`. */ -export function hasGroupCount(version: Version): boolean { +export function hasGroupSpan(version: Version): boolean { // Explicitly list older versions so future versions keep the lite-07+ behavior. switch (version) { case Version.DRAFT_01: diff --git a/js/net/src/lite/widened_max_age.test.ts b/js/net/src/lite/widened_max_age.test.ts index 293fa3a89ee..bb4c1d3552c 100644 --- a/js/net/src/lite/widened_max_age.test.ts +++ b/js/net/src/lite/widened_max_age.test.ts @@ -4,7 +4,6 @@ import { expect, test } from "bun:test"; import { Duration } from "@moq/clock"; import { accept, connect } from "../connection/index.ts"; -import { hooks } from "../internal.ts"; import { createMockTransportPair } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -26,26 +25,6 @@ async function received(reader: TrackSubscriber, count: number): Promise (a < b ? -1 : a > b ? 1 : 0)); } -/** - * Resolves once the publisher's re-drop of groups 1 and 2 reaches `reader`: the update clears - * their stale verdict, and the drop under the update's number sets it again. Each change is - * heard as it lands, so the clear is seen even when the re-drop follows it at once. - */ -function redropped(reader: TrackSubscriber): Promise { - return new Promise((resolve) => { - let cleared = false; - const check = () => { - const held = hooks.staleHeld(reader, 1n, 3n); - if (held.length === 0) cleared = true; - else if (cleared && held.length === 1 && held[0].start === 1n && held[0].end === 3n) { - for (const dispose of disposes) dispose(); - resolve(); - } - }; - const disposes = hooks.givenUp(reader, 1n).changed.map((signal) => signal.subscribe(check)); - }); -} - test("a widened maxDelay re-offers what the publisher skipped below the start", async () => { const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); @@ -87,8 +66,8 @@ for (const [version, alpn] of [ [Version.DRAFT_06, ALPN_06], [Version.DRAFT_07, ALPN_07_WIP], ] as const) { - const reoffers = version === Version.DRAFT_07; - test(`a widened maxDelay ${reoffers ? "re-offers" : "keeps dropped"} the groups reported stale on ${alpn}`, async () => { + const recovers = version === Version.DRAFT_07; + test(`a widened maxDelay ${recovers ? "recovers" : "keeps dropped"} the groups reported stale on ${alpn}`, async () => { const pair = createMockTransportPair(alpn); const origin = new OriginProducer(); const publication = origin.route(Path.from("room")); @@ -120,9 +99,11 @@ for (const [version, alpn] of [ } expect(await received(reader, 2)).toEqual([3n, 4n]); - // Lite-07 re-offers only the groups reported stale; earlier subscribers settled them for good. + // A lite-07 stale drop holds only for a budget no wider than the one it was judged under, so the + // widened reader asks for the groups with a request of its own; earlier versions' drops are + // final for every reader. reader.update({ delay: { max: Duration.millis(10_000) } }); - if (reoffers) expect(await received(reader, 2)).toEqual([1n, 2n]); + if (recovers) expect(await received(reader, 2)).toEqual([1n, 2n]); producer.finish(); producer.close(); expect(await reader.recvGroup()).toBeUndefined(); @@ -136,7 +117,7 @@ for (const [version, alpn] of [ }); } -test("a widening keeps a bounded lite-07 subscription open for the stale groups it re-offers", async () => { +test("a widening recovers the stale groups for a bounded lite-07 reader", async () => { const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); const publication = origin.route(Path.from("room")); @@ -168,61 +149,10 @@ test("a widening keeps a bounded lite-07 subscription open for the stale groups } expect(await received(reader, 2)).toEqual([3n, 4n]); - // The widening re-offers them, and the track's end does not settle the tail before they arrive. + // The widened reader asks for them with a request of its own. reader.update({ delay: { max: Duration.millis(10_000) }, ranges }); - producer.finish(); expect(await received(reader, 2)).toEqual([1n, 2n]); - - reader.close(); - remote.close(); - broadcast.close(); - origin.close(); - client.abort(); - server.abort(); -}); - -// Every lite-07 update reopens the stale drops, widening or not: the publisher drops again, under -// the new update's number, what is still stale, so the subscriber settles at once rather than -// waiting out its grace for a re-offer that never comes. -test("an update keeping the budget drops the stale groups again on lite-07", async () => { - const pair = createMockTransportPair(ALPN_07_WIP); - const origin = new OriginProducer(); - const publication = origin.route(Path.from("room")); - const broadcast = publication.broadcast; - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); - const write = (sequence: number, millis: number) => { - const group = producer.createGroup(BigInt(sequence)); - group.writeFrame({ payload: new Uint8Array([sequence]), timestamp: Timestamp.fromMillis(millis) }); - group.finish(); - }; - write(0, 0); - - const [client, server] = await Promise.all([ - connect({ url, transport: pair.client }), - accept({ transport: pair.server, url, version: Version.DRAFT_07, publish: origin.consume() }), - ]); - const remote = wireOf(client).consume(Path.from("room")); - const reader = remote.track("video").subscribe({ delay: { max: Duration.millis(1500) } }); - expect(await received(reader, 1)).toEqual([0n]); - for (const [sequence, millis] of [ - [1, 1000], - [2, 2000], - [3, 3000], - [4, 6000], - ]) { - write(sequence, millis); - } - expect(await received(reader, 2)).toEqual([3n, 4n]); - - // Only the priority changes (the budget is resent, since an update replaces it): groups 1 and 2 are still stale, so they are dropped again. The - // track ends only once that re-drop has reached the reader, so the end is a FIN, not a reset - // of the reply still writing; a missing re-drop fails here instead of waiting out the grace. - const reached = redropped(reader); - reader.update({ priority: 5, delay: { max: Duration.millis(1500) } }); - await reached; producer.finish(); - producer.close(); - expect(await reader.recvGroup()).toBeUndefined(); reader.close(); remote.close(); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 0d3531f56bc..f9c2f623f2f 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -2094,9 +2094,9 @@ test("a drop waits while a copy the serving one replaced may still deliver it", } }); -// A received stale run the reader held back is unknown again once new terms supersede it on the -// serving copy: its upstream re-offers or drops it again, so it is not reported meanwhile. -test("a held-back stale run new terms supersede is not reported", async () => { +// A received stale run the reader held back is unknown again once a new upstream subscription +// supersedes it on the serving copy, so it is not reported. +test("a held-back stale run a new subscription supersedes is not reported", async () => { const clock = new Manual(); const installed = clock.install(); try { @@ -2116,8 +2116,8 @@ test("a held-back stale run new terms supersede is not reported", async () => { expect(recvDisposition(sub)).toBe("idle"); tb.write(3n); expect(recvDisposition(sub)).toBe(3n); - // The route's subscription updates before the old copy is past the budget. - hooks.supersedeStale(tb.producer, undefined); + // The route subscribes anew before the old copy is past the budget. + hooks.supersedeStale(tb.producer); await clock.advance(Duration.nanos(1_000_000_000)); expect(recvDisposition(sub)).toBe("idle"); @@ -2130,40 +2130,6 @@ test("a held-back stale run new terms supersede is not reported", async () => { } }); -// A group the new route delivers over a stale run the old route reported retires that report, and -// a final drop the new route gives replaces it: only what is still stale is taken back, so an -// update reopens no group already served. Mirrors Rust. -test("a resumed reader retires a stale report its group or final drop replaces", async () => { - const front = new Front(); - const a = new BroadcastProducer(); - const b = new BroadcastProducer(); - const ta = copy(a); - const tb = copy(b); - front.serve(a.consume()); - const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(60_000) } }); - ta.write(0n); - expect(drain(sub)).toEqual([0n]); - hooks.dropTrackGroups(ta.producer, 1n, 4n, staleHole(60_000)); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 1n, end: 4n, stale: 60_000 }); - - front.serve(b.consume()); - await settle(); - tb.write(1n); - expect(drain(sub)).toEqual([1n]); - // Reported once the replaced route no longer feeds. - ta.producer.abort(new StreamError(StreamCode.SessionClosed)); - await settle(); - const cut = new StreamError(StreamCode(70), { message: "cut" }); - hooks.dropTrackGroups(tb.producer, 2n, 3n, { error: cut }); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 2n, end: 3n, stale: undefined }); - // Only group 3 is still stale. - expect(hooks.reofferStale(sub)).toEqual([{ start: 3n, end: 4n }]); - sub.close(); - front.consumer.close(); - a.close(); - b.close(); -}); - test("a drop a replaced route held back is no verdict on the route serving next", async () => { const front = new Front(); const a = new BroadcastProducer(); @@ -3946,9 +3912,9 @@ test("a route whose IETF session closed before subscribing moves the track to th b.close(); }); -// A front's reader re-offers what its serving route's copy still caches and judges fresh, and gives -// up the rest, so a relay's publisher re-serves an expired stream through it. Mirrors Rust. -test("a resumed reader re-offers a group its serving copy still caches", () => { +// A front's reader continues a yielded group its serving route's copy still caches and judges fresh, +// so a relay's publisher continues the group through it, and nothing it lacks. +test("a resumed reader continues a group its serving copy still caches", () => { const front = new Front(); const a = new BroadcastProducer(); const ta = copy(a); @@ -3956,107 +3922,13 @@ test("a resumed reader re-offers a group its serving copy still caches", () => { const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(60_000) } }); ta.write(0n); expect(drain(sub)).toEqual([0n]); - const { groups, givenUp } = hooks.reofferGroups(sub, 0n, 3n); - expect(groups.map((group) => group.sequence)).toEqual([0n]); - expect(givenUp).toEqual([{ start: 1n, end: 3n }]); - for (const group of groups) group.close(); - sub.close(); - front.consumer.close(); - a.close(); -}); - -// A front's reader takes back the stale runs its serving route's copy reported, so a relay's -// publisher re-offers them under a new update rather than keep them reported. Mirrors Rust. -test("a resumed reader takes back its stale reports", () => { - const front = new Front(); - const a = new BroadcastProducer(); - const ta = copy(a); - front.serve(a.consume()); - const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(60_000) } }); - ta.write(0n); - expect(drain(sub)).toEqual([0n]); - hooks.dropTrackGroups(ta.producer, 1n, 3n, staleHole(60_000)); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 1n, end: 3n, stale: 60_000 }); - expect(hooks.reofferStale(sub)).toEqual([{ start: 1n, end: 3n }]); - expect(hooks.reofferStale(sub)).toEqual([]); - sub.close(); - front.consumer.close(); - a.close(); -}); - -// A stale run the reader queued and has yet to report is taken back by an update too, as a plain -// reader's is: the new terms judge it anew, rather than an old verdict going out under the new -// update number. The update widens past the verdict, so nothing goes out at all. Mirrors Rust -// `a_resumed_reader_takes_back_its_queued_stale_runs`, which checks the queue directly. -test("a resumed reader takes back its queued stale runs", async () => { - const clock = new Manual(); - const installed = clock.install(); - try { - const front = new Front(); - const a = new BroadcastProducer(); - const b = new BroadcastProducer(); - const ta = copy(a); - const tb = copy(b); - front.serve(a.consume()); - const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(1_000) } }); - ta.write(0n); - expect(drain(sub)).toEqual([0n]); - hooks.dropTrackGroups(ta.producer, 2n, 3n, staleHole(1_000)); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 2n, end: 3n }); - - // The new route's stale run around the one already reported goes out in parts once the old - // route can no longer deliver it: the part below it first, with the rest queued. - front.serve(b.consume()); - await settle(); - hooks.dropTrackGroups(tb.producer, 1n, 5n, staleHole(1_000)); - tb.write(5n); - expect(drain(sub)).toEqual([5n]); - await clock.advance(Duration.millis(1_000)); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 1n, end: 2n }); - - // An update that widens the budget past the verdict: nothing is stale under it. - sub.update({ delay: { max: Duration.millis(60_000) } }); - expect(hooks.reofferStale(sub)).toEqual([{ start: 1n, end: 5n }]); - await settle(); - expect(hooks.tryDrop(sub)).toBeUndefined(); - sub.close(); - front.consumer.close(); - a.close(); - b.close(); - } finally { - installed.close(); - } -}); - -// A stale run one route reported is still taken back once another serves: the update reopened it -// downstream, and the new route's copy knows nothing of it, so the groups it delivers there -// afterwards are owed rather than kept reported. Mirrors Rust. -test("a resumed reader takes back a replaced route's stale reports", async () => { - const front = new Front(); - const a = new BroadcastProducer(); - const b = new BroadcastProducer(); - const ta = copy(a); - const tb = copy(b); - front.serve(a.consume()); - const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(60_000) } }); - ta.write(0n); - expect(drain(sub)).toEqual([0n]); - hooks.dropTrackGroups(ta.producer, 1n, 3n, staleHole(60_000)); - expect(hooks.tryDrop(sub)).toMatchObject({ kind: "drop", start: 1n, end: 3n, stale: 60_000 }); - - front.serve(b.consume()); - await settle(); - expect(hooks.tryDrop(sub)).toBeUndefined(); - // Reopened, though the new route never reported it. - expect(hooks.reofferStale(sub)).toEqual([{ start: 1n, end: 3n }]); - expect(hooks.reofferStale(sub)).toEqual([]); - tb.write(1n); - tb.write(2n); - expect(drain(sub)).toEqual([1n, 2n]); + const group = hooks.continueGroup(sub, 0n, 0); + expect(group?.sequence).toBe(0n); + group?.close(); + expect(hooks.continueGroup(sub, 1n, 0)).toBeUndefined(); sub.close(); front.consumer.close(); a.close(); - b.close(); }); test("routed metadata receives a refusal without polling a group cursor", async () => { diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index ac9a55e89f7..81decc39b13 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -433,11 +433,6 @@ class Reader implements ResumeSource { #delivered = new Delivered(); /** Runs the serving copy gave up and the reader has yet to report; see {@link #tryDrop}. */ #drops: DropRun[] = []; - /** - * The stale runs reported since the last {@link reofferStale}, whichever copy gave them up: an - * update reopens each, and the copy that reported it may no longer serve. - */ - #reportedStale: Run[] = []; /** A copy that declared the track's end ran out cleanly at it, even if since let go. */ #settled = false; /** Whether groups were ever asked for; until then the reader keeps no replaced copy. */ @@ -750,33 +745,13 @@ class Reader implements ResumeSource { } /** - * Fresh reads of the groups in `[start, end)` the serving copy still caches and judges fresh, - * handed out as any group of that copy is, and the runs still given up: all of them while no - * copy serves. Mirrors the Rust `Reader::reoffer_groups`. - */ - reofferGroups(start: bigint, end: bigint, from = 0): { groups: GroupConsumer[]; givenUp: Run[] } { - const serving = this.#serving(); - if (!serving) return { groups: [], givenUp: [{ start, end }] }; - const { groups, givenUp } = hooks.reofferGroups(serving.sub, start, end, from); - return { groups: groups.map((group) => this.#handOut(serving, group)), givenUp }; - } - - /** - * Take back every stale run: those queued here, those this reader reported, and those the - * serving copy reported, which its cursor owes again. What this reader reported counts - * whichever copy gave it up, since a route change since leaves the serving copy knowing - * nothing of it, though the update reopened it. Only the serving copy is judged again: a - * replaced copy may no longer deliver, so what it gave up is the new route's to deliver or - * give up. Mirrors the Rust `Reader::reoffer_stale`. + * A fresh read from frame `from` of group `sequence`, if the serving copy still caches it and + * judges it fresh, handed out as any group of that copy is. */ - reofferStale(): Run[] { - const taken = this.#reportedStale; - this.#reportedStale = []; - for (const run of this.#drops) if (run.stale !== undefined) insertRun(taken, run.start, run.end); - this.#drops = this.#drops.filter((run) => run.stale === undefined); + continueGroup(sequence: bigint, from: number): GroupConsumer | undefined { const serving = this.#serving(); - if (serving) for (const run of hooks.reofferStale(serving.sub)) insertRun(taken, run.start, run.end); - return taken; + const group = serving && hooks.continueGroup(serving.sub, sequence, from); + return group && this.#handOut(serving, group); } cachedGroup(sequence: bigint, from = 0): GroupConsumer | undefined { @@ -918,8 +893,8 @@ class Reader implements ResumeSource { if (this.#closed) return undefined; const serving = this.#serving(); if (serving) { - // A received stale run queued here that new terms superseded since is unknown again: the - // copy no longer holds it, and its upstream re-offers or drops it again. + // A received stale run queued here that a new upstream subscription superseded since is + // unknown again: the copy no longer holds it. for (const run of this.#drops) { if (!run.received) continue; const held = hooks.staleHeld(serving.sub, run.start, run.end); @@ -930,7 +905,7 @@ class Reader implements ResumeSource { // A route failing is no verdict: another route may still deliver the group, and // one it failed while buffered is handed out to continue through its recovery. if (routeFailed(dropped.error)) continue; - // A stale run the copy holds came from its upstream, which new terms may supersede. + // A stale run the copy holds came from its upstream, which a new subscription may supersede. const received = dropped.stale !== undefined && hooks.staleHeld(serving.sub, dropped.start, dropped.end).length > 0; this.#drops = insertDrop(this.#drops, dropped.start, dropped.end, { ...dropped, received }); @@ -951,9 +926,6 @@ class Reader implements ResumeSource { if (open) { // Report once without marking it delivered: a late fill may still land. this.#drops = removeRun(this.#drops, open.start, open.end); - if (run.stale !== undefined) insertRun(this.#reportedStale, open.start, open.end); - // A skip or final drop is final, so no update reopens a stale report it replaced. - else this.#reportedStale = removeRun(this.#reportedStale, open.start, open.end); return { kind: "drop", ...open, error: run.error, skip: run.skip, stale: run.stale }; } } @@ -1269,11 +1241,6 @@ class Reader implements ResumeSource { #handOut(copy: Copy, group: GroupConsumer): GroupConsumer { this.#newest = max(this.#newest ?? 0n, group.sequence); - // The group won over any stale report on it, whichever copy made it, so no update reopens - // it. - if (this.#reportedStale.length > 0) { - this.#reportedStale = removeRun(this.#reportedStale, group.sequence, group.sequence + 1n); - } // Another copy holding the group, now or once it lands there, is where a failure continues // it, so it stays while the group is read; see #backs. Recorded even with one copy, since a // later route's copy may come to hold it. diff --git a/js/net/src/tail.ts b/js/net/src/tail.ts index a1d6c28ed12..1e13bf3c9b1 100644 --- a/js/net/src/tail.ts +++ b/js/net/src/tail.ts @@ -18,8 +18,6 @@ export interface Counted { * waits for it at most the grace. Idempotent. */ excuse(): void; - /** Hold the end again: the drop that excused it no longer stands, as an update reopens a stale one. */ - restore(): void; } /** @@ -46,11 +44,7 @@ export class Tail { #excused = new Set(); #changed = new Signal(0); #grace: () => Duration; - // Groups whose stream finished since the last update was sent. A lite-07 stale drop under that - // update names one only if it was sent before the publisher served the group, so the group won - // over it, even once the cache evicted it. - #finished: Run[] = []; - // Sequences a final drop named, so a stream whose header the drop overtook can be told from one + // Sequences a drop named, so a stream whose header the drop overtook can be told from one // whose gap the grace gave up on. #dropped: Run[] = []; @@ -60,7 +54,6 @@ export class Tail { /** Release what the tail keeps beside its ledger, once its subscription ended. */ close(): void { - this.#finished = []; this.#dropped = []; } @@ -92,13 +85,6 @@ export class Tail { this.#excused.add(token); this.#bump(); }, - restore: () => { - if (state !== "excused") return; - state = "held"; - this.#excused.delete(token); - this.#active += 1; - this.#bump(); - }, }; } @@ -134,24 +120,6 @@ export class Tail { }; } - /** Record that the group stream for `sequence` arrived whole. */ - finish(sequence: bigint): void { - insertRun(this.#finished, sequence, sequence + 1n); - } - - /** The parts of `[start, end)` whose stream did not finish since the last update was sent. */ - unfinished(start: bigint, end: bigint): Run[] { - return runGaps(this.#finished, start, end); - } - - /** - * Forget which streams finished, for an update being sent: a stale drop under an earlier one is - * no verdict, so none needs them. - */ - updated(): void { - this.#finished = []; - } - /** Re-check what {@link settle} waits on, after something outside the ledger changed. */ touch(): void { this.#bump(); @@ -162,23 +130,18 @@ export class Tail { this.#account(start, end); } - /** Record `[start, end)` as given up by a final drop, accounting for it. */ + /** Record `[start, end)` as given up by a drop, accounting for it. */ drop(start: bigint, end: bigint): void { insertRun(this.#dropped, start, end); this.#account(start, end); } - /** Whether a final drop named `sequence`. */ + /** Whether a drop named `sequence`. */ dropped(sequence: bigint): boolean { const run = this.#dropped[runsFrom(this.#dropped, sequence)]; return run !== undefined && run.start <= sequence; } - /** Owe `[start, end)` again: a stale drop that accounted for it was reversed by a widening. */ - unaccount(start: bigint, end: bigint): void { - this.#ledger.unaccount(start, end, now()); - } - /** Restart the age of every gap reaching into `[start, end)`, which the demand newly asks for. */ demand(start: bigint, end: bigint): void { this.#ledger.demand(start, end, now()); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index e6be84d4f0f..a134ca46011 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -3922,7 +3922,7 @@ test("a superseded stale run is unknown again, and its group is handed out", () const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ delay: { max: Duration.millis(500) }, ranges: [{ start: { absolute: 0n } }] }); hooks.dropTrackGroups(producer, 1n, 2n, staleHole(500)); - hooks.supersedeStale(producer, undefined); + hooks.supersedeStale(producer); expect(hooks.tryDrop(reader)).toBeUndefined(); producer.createGroup(1n).finish(); const recv = hooks.tryRecvGroup(reader, true); @@ -3940,7 +3940,7 @@ test("superseding withdraws a partly reported stale run", () => { expect(hooks.tryDrop(reader)).toMatchObject({ start: 4n, end: 5n }); hooks.dropTrackGroups(producer, 3n, 7n, staleHole(500)); expect(hooks.tryDrop(reader)).toMatchObject({ start: 3n, end: 4n, stale: 500 }); - hooks.supersedeStale(producer, undefined); + hooks.supersedeStale(producer); // 5 and 6 are unknown again. expect(hooks.tryDrop(reader)).toBeUndefined(); reader.close(); @@ -3948,80 +3948,6 @@ test("superseding withdraws a partly reported stale run", () => { producer.close(); }); -// A received stale run a reader reported and the relay's own update then superseded is unknown -// again: the reader's update owes it until the upstream serves or drops it again, rather than -// dropping it again as if the reader had judged it stale itself. Mirrors Rust. -test("a superseded received stale report stays owed after an update", () => { - const producer = new TrackProducer("video").accept({}); - const reader = producer.subscribe({ delay: { max: Duration.millis(500) }, ranges: [{ start: { absolute: 0n } }] }); - hooks.dropTrackGroups(producer, 1n, 3n, staleHole(500)); - expect(hooks.tryDrop(reader)).toMatchObject({ start: 1n, end: 3n, stale: 500 }); - hooks.supersedeStale(producer, undefined); - expect(hooks.reofferStale(reader)).toEqual([{ start: 1n, end: 3n }]); - expect(hooks.tryDrop(reader)).toBeUndefined(); - // The upstream drops it again under the new terms: reported again. - hooks.dropTrackGroups(producer, 1n, 3n, staleHole(500)); - expect(hooks.tryDrop(reader)).toMatchObject({ start: 1n, end: 3n, stale: 500 }); - reader.close(); - producer.finish(); - producer.close(); -}); - -test("a received stale run settles a bounded reader only through the judged ranges", () => { - const producer = new TrackProducer("video").accept({ maxAge: null }); - hooks.receiveTrack(producer); - const bounded = (max: number) => - producer.subscribe({ - delay: { max: Duration.millis(max) }, - ranges: [{ start: { absolute: 0n }, end: { absolute: 2n } }], - }); - const wider = bounded(5000); - const matching = bounded(500); - // The upstream judged its own range of 0..2 under 500ms. - hooks.supersedeStale(producer, [{ start: 0n, end: 2n }]); - hooks.dropTrackGroups(producer, 0n, 2n, staleHole(500)); - // A wider budget still wants the groups, however the feed accounted for them. - expect(hooks.tryRecvGroup(wider, false)).toEqual({ kind: "idle" }); - expect(hooks.tryDrop(matching)).toMatchObject({ start: 0n, end: 2n, stale: 500 }); - expect(hooks.tryRecvGroup(matching, false)).toEqual({ kind: "done" }); - // Judged against an open range, a capped reader may see an older edge. - hooks.supersedeStale(producer, undefined); - hooks.dropTrackGroups(producer, 0n, 2n, staleHole(500)); - const capped = bounded(500); - expect(hooks.tryDrop(capped)).toBeUndefined(); - producer.createGroup(0n).finish(); - const recv = hooks.tryRecvGroup(wider, false); - expect(recv.kind === "group" ? recv.group.sequence : recv).toBe(0n); - if (recv.kind === "group") recv.group.close(); - for (const reader of [wider, matching, capped]) reader.close(); - producer.finish(); - producer.close(); -}); - -test("a superseded stale run leaves a bounded reader waiting, and a later reader judges it too", () => { - const producer = new TrackProducer("video").accept({ maxAge: null }); - hooks.receiveTrack(producer); - const bounded = (max: number) => - producer.subscribe({ - delay: { max: Duration.millis(max) }, - ranges: [{ start: { absolute: 0n }, end: { absolute: 2n } }], - }); - const wider = bounded(5000); - hooks.supersedeStale(producer, [{ start: 0n, end: 2n }]); - producer.createGroup(2n).finish(); - hooks.dropTrackGroups(producer, 0n, 2n, staleHole(500)); - // A reader added after the verdict judges it against the same judged ranges. - const later = bounded(500); - expect(hooks.tryDrop(later)).toMatchObject({ start: 0n, end: 2n, stale: 500 }); - expect(hooks.tryRecvGroup(wider, false)).toEqual({ kind: "idle" }); - // New terms make the groups unknown again: still wanted, never proven delivered. - hooks.supersedeStale(producer, [{ start: 0n, end: 2n }]); - expect(hooks.tryRecvGroup(wider, false)).toEqual({ kind: "idle" }); - for (const reader of [wider, later]) reader.close(); - producer.finish(); - producer.close(); -}); - test("a wide drop is held and reported as one run", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ delay: { max: Duration.millis(60_000) } }); @@ -4849,10 +4775,9 @@ for (const reported of [false, true]) { }); } -// The lite publisher unreports a stale skip below an idle SUBSCRIBE_START, which never went out. -// An update between that START and the first group then neither reopens nor drops it again, -// while a widening still re-offers its cached group. -test("an update after an idle start leaves an unreported stale skip to a widening", () => { +// The lite publisher unreports a stale skip below an idle SUBSCRIBE_START, which never went out, so a +// widening still offers its cached group. +test("an unreported stale skip below an idle start is left to a widening", () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Duration.millis(1500) } }); expect(hooks.tryDrop(subscriber)).toBeUndefined(); @@ -4865,8 +4790,6 @@ test("an update after an idle start leaves an unreported stale skip to a widenin // SUBSCRIBE_START resolved at group 1 with the skip still held for it. hooks.wire(subscriber).untell(0n, 1n); - // An update under the same budget reopens nothing below the start. - expect(hooks.reofferStale(subscriber)).toEqual([]); expect(hooks.tryDrop(subscriber)).toBeUndefined(); subscriber.update({ delay: { max: Duration.millis(10_000) } }); @@ -5094,7 +5017,7 @@ test("creating a skipped sequence throws Skipped", () => { hooks.dropTrackGroups(other, 3n, 4n, { error: DROPPED }); hooks.dropTrackGroups(other, 4n, 5n, staleHole(1000)); other.skipGroups(0n, 5n); - hooks.supersedeStale(other, undefined); + hooks.supersedeStale(other); const drops: unknown[] = []; for (let next = hooks.tryRecvGroup(reader, true); next.kind !== "idle"; next = hooks.tryRecvGroup(reader, true)) { if (next.kind === "drop") drops.push([next.start, next.end, next.skip === true]); @@ -5142,23 +5065,6 @@ test("a skip is reported over a reported drop", () => { producer.close(); }); -// A received stale run is judged from where it meets the reader's span, as Rust clips it: a reader -// asking only its suffix, through every group the upstream's range named, is settled by that suffix. -test("a received stale run settles the suffix a narrower range asks for", () => { - const producer = new TrackProducer("video").accept({}); - hooks.receiveTrack(producer); - hooks.supersedeStale(producer, [{ start: 0n, end: 10n }]); - const reader = producer.subscribe({ - delay: { max: Duration.millis(500) }, - ranges: [{ start: { absolute: 5n }, end: { absolute: 10n } }], - }); - hooks.dropTrackGroups(producer, 0n, 10n, staleHole(500)); - expect(hooks.tryDrop(reader)).toMatchObject({ kind: "drop", start: 5n, end: 10n, stale: 500 }); - expect(hooks.tryDrop(reader)).toBeUndefined(); - reader.close(); - producer.close(); -}); - // Skips are kept and reported as runs: a huge skipGroups or append gap costs one run and one // report, whatever its length. Mirrors Rust. test("a huge skip costs one run", () => { @@ -5190,38 +5096,6 @@ test("a huge skip costs one run", () => { } }); -// A group stale at the track's max age bound is final under any budget, yet an update that reopens -// its stale drop must report it again rather than leave it owed: no skip offers it again. Mirrors -// Rust. -test("reopening stale drops reports again what is stale at the max age bound", () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Duration.millis(1500) }); - const reader = producer.subscribe({ delay: { max: Duration.millis(1500) } }); - const drain = () => { - const got: unknown[] = []; - for ( - let next = hooks.tryRecvGroup(reader, true); - next.kind !== "idle"; - next = hooks.tryRecvGroup(reader, true) - ) { - if (next.kind === "group") got.push(next.group.sequence); - else if (next.kind === "drop") got.push([next.start, next.end, next.stale]); - } - return got; - }; - putGroup(producer, 0n, 0); - expect(drain()).toEqual([0n]); - for (const [sequence, millis] of [ - [1n, 1000], - [2n, 2000], - [3n, 3000], - [4n, 6000], - ] as const) - putGroup(producer, sequence, millis); - expect(drain()).toEqual([[1n, 2n, 1500], [2n, 3n, 1500], 3n, 4n]); - expect(hooks.reofferStale(reader)).toEqual([{ start: 1n, end: 3n }]); - expect(drain()).toEqual([[1n, 3n, 1500]]); -}); - // Mirrors moq-net's `the_reserved_sequence_is_refused` and `a_group_at_the_reserved_sequence_is_refused`. test("the reserved sequence is refused", () => { const reserved = (1n << 64n) - 1n; diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0ce09c6b669..f41c2e8eb45 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -722,9 +722,6 @@ class TrackState { drops = new DropSet(); // The runs this sink's own fills refused, which it reads as given up beside `drops`. refused = new Signal([]); - // Every group the ranges of a received copy's current upstream terms name, which its stale runs - // were judged against; undefined when unknown, which counts as every group. - judged?: readonly Run[]; // Every group still in the producer's replay cache, including groups this // subscriber already consumed, sorted by sequence. Drift anchors have the same // lifetime as content. Sorted so the latency guard, evaluated per group and per @@ -964,29 +961,18 @@ function reaches(received: bigint, drops: DropSet, end: End, refused: readonly R } /** - * Whether `run` settles a reader judging under `budget` with `coverage`, on a track whose upstream - * judged stale runs against ranges naming the groups in `judged` (undefined for every group). Any - * run but a received stale one does. A stale verdict holds for a reader no wider than the budget it - * was judged under that reads every group the upstream's ranges name above the run's start: its - * own successor and edge are then no older than those the verdict was judged against, since a - * group's verdict looks only above it. Mirrors the Rust `settles`. + * Whether `run` settles a reader judging under `budget` with `coverage`. Any run but a received + * stale one does. A stale verdict holds for a reader no wider than the budget it was judged under + * that reads every group above the run's start, past the live edge: its own successor and edge are + * then no older than those the verdict was judged against, since a group's verdict looks only + * above it. Mirrors the Rust `settles`. */ -function settles(run: DropRun, budget: number, coverage: Coverage, judged: readonly Run[] | undefined): boolean { +function settles(run: DropRun, budget: number, coverage: Coverage): boolean { if (run.stale === undefined) return true; - if (budget > run.stale || coverage === undefined) return false; + if (budget > run.stale || coverage === undefined || coverage.cap !== undefined) return false; const above = run.start + 1n; - // Whether the reader reads every group from `start` up to the exclusive `end`, `UNBOUNDED` - // past the live edge. - const reads = (start: bigint, end: bigint): boolean => { - if (coverage.cap !== undefined && (end === UNBOUNDED || end > coverage.cap)) return false; - const held = coverage.runs.find((run) => run.start <= start && start < run.end); - return held !== undefined && held.end >= end; - }; - for (const range of judged ?? [{ start: 0n, end: UNBOUNDED }]) { - if (range.end <= above) continue; - if (!reads(max(range.start, above), range.end)) return false; - } - return true; + const held = coverage.runs.find((run) => run.start <= above && above < run.end); + return held !== undefined && held.end >= UNBOUNDED; } // Actual object metadata outlives cached payloads, unlike empty group heads in model largest. let objectLargest: (producer: Producer) => Position | undefined; @@ -1329,13 +1315,9 @@ export class Producer { hooks.trackFinished = (producer) => producer.#state.end.peek() !== undefined; hooks.dropTrackGroups = (producer, start, end, hole) => producer.#drop(start, end, hole, true); hooks.skipTrackGroups = (producer, start, end) => producer.#skipReceived(start, end); - hooks.supersedeStale = (producer, judged) => { - const held = producer.#state.drops.all - .filter((run) => run.stale !== undefined) - .map(({ start, end }) => ({ start, end })); - for (const state of [producer.#state, ...producer.#sinks]) state.judged = judged; + hooks.supersedeStale = (producer) => { + const held = producer.#state.drops.all.filter((run) => run.stale !== undefined); for (const run of held) producer.#setDrops(run.start, run.end); - return held; }; hooks.dropAnchors = (producer) => { for (const state of [producer.#state, ...producer.#sinks]) state.dropsAnchors.set(true); @@ -1464,10 +1446,10 @@ export class Producer { for (const [sequence, entry] of this.#cached) { const closed = entry.group.closed.peek(); if (sequence < start || sequence >= end || closed instanceof Error) continue; - // A lite-07 publisher may serve a group after its stale drop, and the group's stream - // may land first. A final drop ends a group still arriving, but one that finished here - // stays whole, as a re-sent copy the subscriber refused leaves it: naming it given up - // would hide it from every reader. + // A final drop ends a group still arriving, but one that finished here stays whole, as a + // re-sent copy the subscriber refused leaves it: naming it given up would hide it from + // every reader. A stale drop settles only the readers its budget covers, so it leaves a + // group arriving too, which another subscription sharing the copy may be delivering. if (hole.stale === undefined && closed === undefined) arriving.push(entry.group); else runs = removeRun(runs, sequence, sequence + 1n); } @@ -1477,8 +1459,8 @@ export class Producer { if (hole.stale === undefined) this.#fills.dropped(start, end); for (const run of runs) this.#setDrops(run.start, run.end, hole); for (const group of arriving) group.abort(hole.error); - // A pending tail owes nothing the publisher gave up. A stale verdict is not receipt: new - // terms may supersede it, leaving those groups unknown again, as in Rust. + // A pending tail owes nothing the publisher gave up. A stale verdict is not receipt: a new + // upstream subscription supersedes it, leaving those groups unknown again, as in Rust. if (hole.stale === undefined) this.#arrive(start, end); // Giving up the last sequences below the end reaches it, as writing them would. this.#endLargest(); @@ -1670,7 +1652,6 @@ export class Producer { // Full, unlike a write's bounded scan, so the subscriber gets no group already idled out. this.#evictExpired(true); for (const entry of this.#cache) this.#mirror(entry, sink); - sink.judged = this.#state.judged; sink.received.set(this.#received); sink.end.set(this.#state.end.peek()); @@ -2503,48 +2484,23 @@ type Superseded = { successor?: Successor }; // the oldest held. type Successor = { sequence: bigint; arrived: Instant; fate: () => Error | undefined }; -// A run a reader already reported, and how: dropped for good (or stale until its group was handed -// out, so no update reopens it), dropped as stale, which an update reopens, or skipped, which -// replaces a drop. `received` when an upstream's stale run decided it, which is the upstream's to -// judge again then. Mirrors the Rust `Report`. /** * How a reader reported a run, and what its wire was told. Mirrors the Rust `record::Report`: - * `settled` is a group served, or a drop on a version whose drops are all final. + * `settled` is a group served, or a drop on a version whose drops are all final, and a skip + * replaces a drop. * * @internal */ export interface Reported extends Run { - kind: "settled" | "dropped" | "stale" | "skip"; - /** A stale run an upstream decided, which is the upstream's to judge again. */ - received?: boolean; - /** A stale run whose Group Stream expired, or that went out OLD for good: its publisher drops it again under each update. */ - expired?: boolean; - /** A stale run whose group was handed out after the drop, which the group won: no update reopens it. */ - taken?: boolean; + kind: "settled" | "dropped" | "skip"; } -const sameReport = (a: Reported, b: Reported) => - a.kind === b.kind && !a.received === !b.received && !a.expired === !b.expired && !a.taken === !b.taken; - -// Whether `reported` settles its run for good, so a fold may forget it. -const finalReport = (reported: Reported) => reported.kind !== "stale" || reported.taken === true; +const sameReport = (a: Reported, b: Reported) => a.kind === b.kind; -// Whether an update reopens `reported`: a stale drop nothing settled since. -const reopens = (reported: Reported) => reported.kind === "stale" && !reported.expired && !reported.taken; - -// Whether `reported` stops `hole` going out over it: a skip goes out over a drop, and a final -// drop over a stale one, since each replaces what it goes out over. An OLD drop never goes out -// over a stale one, which already said OLD. Mirrors the Rust `Report::blocks`. +// Whether `reported` stops `hole` going out over it: only a skip goes out over a drop, which it +// replaces. Mirrors the Rust `Report::blocks`. function blocksHole(reported: Reported, hole: Hole): boolean { - switch (reported.kind) { - case "settled": - case "skip": - return true; - case "dropped": - return !hole.skip; - case "stale": - return reported.taken ? !hole.skip : !hole.skip && toStreamCode(hole.error) === StreamCode.Old; - } + return reported.kind !== "dropped" || !hole.skip; } /** @@ -2557,18 +2513,12 @@ function blocksHole(reported: Reported, hole: Hole): boolean { export interface WireRecord { /** Whether the wire was told of `sequence`: served, or given up. */ told(sequence: bigint): boolean; - /** Whether `sequence` went out as a stale drop, which a group still replaces. */ - toldStale(sequence: bigint): boolean; /** The parts of `[start, end)` the wire was told nothing of. */ untold(start: bigint, end: bigint): Run[]; /** Record that the wire was told `report` of `[start, end)`. */ tell(start: bigint, end: bigint, report: Omit): void; - /** Forget what the wire was told of `[start, end)` that an update may reopen, which is owed again. */ + /** Forget what was recorded of `[start, end)` without going out on the wire. */ untell(start: bigint, end: bigint): void; - /** Forget the drops of `[start, end)` the wire was told, which a verdict or group replaces. */ - replaceDrops(start: bigint, end: bigint): void; - /** The runs each update drops again: stale ones whose stream expired, or that went out OLD for good. */ - expired(): Run[]; } /** @@ -2666,7 +2616,6 @@ export class Subscriber { revision: number; budget: number; coverage?: Coverage; - judged?: readonly Run[]; }; #reported = new Runs(sameReport); // The group the frame-level helpers are currently draining, acquired through the @@ -2703,7 +2652,6 @@ export class Subscriber { producer: Producer; budget: number; coverage: Coverage; - judged: readonly Run[] | undefined; opened: number; drops: number; edge: bigint; @@ -2712,7 +2660,6 @@ export class Subscriber { // under; see #unknownRuns. #unknown?: { drops: number; - judged: readonly Run[] | undefined; budget: number; coverage: Coverage; runs: DropRun[]; @@ -2951,11 +2898,6 @@ export class Subscriber { if (ordered) this.#delivered.forgetBelow(sequence); this.#delivered.add(sequence); this.#skipped.delete(sequence); - // The group won over any stale report on it, so no update reopens it. A resumed reader - // retires its own. - const stale = this.#reported.at(sequence); - if (stale?.kind === "stale") - this.#reported.set(sequence, sequence + 1n, { ...stale, start: sequence, end: sequence + 1n, taken: true }); // Another copy of it buffered here is never handed out. this.#judge(sequence, sequence + 1n); if (this.#resume) this.#resume.forgetPastBudget(this.#delivered); @@ -3112,164 +3054,28 @@ export class Subscriber { const reported = this.#reported; return { told: (sequence) => reported.at(sequence) !== undefined, - toldStale: (sequence) => reported.at(sequence)?.kind === "stale", untold: (start, end) => (start < end ? runGaps(reported.overlapping(start, end), start, end) : []), tell: (start, end, report) => { - if (start >= end) return; - // A stale report keeps the parts an upstream decided, which stay its to judge again. - const received = - report.kind === "stale" && !report.received - ? reported.overlapping(start, end).filter((run) => run.kind === "stale" && run.received) - : []; - reported.set(start, end, { ...report, start, end } as Reported); - for (const run of received) { - const from = max(run.start, start); - const to = min(run.end, end); - reported.set(from, to, { ...report, start: from, end: to, received: true } as Reported); - } + if (start < end) reported.set(start, end, { ...report, start, end }); }, untell: (start, end) => { - // A final report stays: nothing reopens it, and a stale verdict must never go out over it. - const reopened = reported.overlapping(start, end).filter((run) => !finalReport(run)); - for (const run of reopened) reported.set(max(run.start, start), min(run.end, end)); + if (start < end) reported.set(start, end); }, - replaceDrops: (start, end) => { - const drops = reported - .overlapping(start, end) - .filter((run) => run.kind === "dropped" || run.kind === "stale"); - for (const run of drops) reported.set(max(run.start, start), min(run.end, end)); - }, - expired: () => - reported.all - .filter((run) => run.kind === "stale" && run.expired) - .map(({ start, end }) => ({ start, end })), }; } - // Owe again every run this cursor gave up as stale, reported or not: an update reopens the - // verdict. A group still cached is offered again as a widened skip is, a missing one is missed - // again (asked of a fill, or dropped as not found when none can serve it), and whatever is - // still stale under the new terms is given up and reported again. Returns the runs taken back. A - // resumed reader takes back what it queued and what its serving route's copy reported. - #reofferStale(): Run[] { - if (this.#resume) { - const taken = this.#resume.reofferStale(); - // A stale run this reader queued and has yet to report is owed again too, as the plain - // path below takes back its own: the new terms judge it anew. Mirrors Rust. - for (const run of this.#pending) if (run.stale !== undefined) insertRun(taken, run.start, run.end); - this.#pending = this.#pending.filter((run) => run.stale === undefined); - return taken; - } - const taken: Run[] = []; - const received: Run[] = []; - const stale = this.#reported.all.filter(reopens); - for (const run of stale) { - insertRun(taken, run.start, run.end); - if (run.received) insertRun(received, run.start, run.end); - } - this.#reported.clear(stale); - for (const run of this.#pending) { - if (run.stale === undefined) continue; - insertRun(taken, run.start, run.end); - if (run.received) insertRun(received, run.start, run.end); - } - this.#pending = this.#pending.filter((run) => run.stale === undefined); - // A received stale run is folded in again by the next scan, if the track still holds it. - this.#dropsSeen = undefined; + // A fresh read from frame `from` of group `sequence`, if the cache still holds it from there and + // this cursor admits it and does not judge it stale, expiring against the budget: a lite-07 + // continuation of a group whose stream yielded. A resumed reader asks its serving route's copy. + #continueGroup(sequence: bigint, from: number): GroupConsumer | undefined { + if (this.#resume) return this.#resume.continueGroup(sequence, from); const producer = this.#state.producer; - const sequences: bigint[] = []; - for (const sequence of this.#skipped.keys()) { - if (!taken.some((run) => run.start <= sequence && sequence < run.end)) continue; - // A skip whose group left the cache can never be offered again: forgotten, so the - // run is judged again below, as the Rust `prune_skipped` forgets it first. - if (producer && !cachedHolds(producer, sequence)) this.#skipped.delete(sequence); - else sequences.push(sequence); - } - // What no skip offers again, such as a group written off at the track's max age bound, - // which no budget reverses, is still stale under the new terms: reported again, as is a - // missing group they still convict. What an - // upstream's stale run decided is the upstream's to judge again: the scan above folds it - // in again if the track still holds it, and it stays owed if new terms superseded it. - // Mirrors Rust. - let kept: Run[] = taken.map((run) => ({ ...run })); - for (const sequence of sequences) kept = removeRun(kept, sequence, sequence + 1n); - for (const decided of received) kept = removeRun(kept, decided.start, decided.end); - if (kept.length > 0) { - const drift = this.#drift(); - const stale = staleHole(drift.budget); - for (const run of kept) { - for (const part of this.#missed(run)) { - // A miss the new terms still convict is stale again; one a fill can still bring - // stays owed, asked afresh; the rest no copy left here can serve. - if (!part.missed || this.#staleAt(part.end - 1n, drift)) { - this.#pending = insertDrop(this.#pending, part.start, part.end, stale); - } else if (!this.#retry(part)) { - const hole = { error: new StreamError(StreamCode.NotFound, { message: "group not found" }) }; - this.#pending = insertDrop(this.#pending, part.start, part.end, hole); - } - } - } - } - if (sequences.length > 0 && producer && !this.#left) reofferSequences(producer, this.#state, sequences); - return taken; - } - - // `run` split into its cached groups, which no skip offers again and so stay stale, and the - // gaps between them, which the cache no longer holds: misses, judged as the Rust `Misses` - // judges a gap, by its newest sequence. - #missed(run: Run): (Run & { missed: boolean })[] { - const producer = this.#state.producer; - if (!producer) return [{ ...run, missed: false }]; - const parts: (Run & { missed: boolean })[] = []; - let next = run.start; - // A failed copy holds nothing to read, so it is missed like an evicted one. - const held = cachedIn(producer, run.start, run.end).filter((sequence) => cachedHolds(producer, sequence)); - for (const sequence of held.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))) { - if (next < sequence) parts.push({ start: next, end: sequence, missed: true }); - parts.push({ start: sequence, end: sequence + 1n, missed: false }); - next = sequence + 1n; - } - if (next < run.end) parts.push({ start: next, end: run.end, missed: true }); - return parts; - } - - // Ask a fill again for `run`, which an update reopened: no longer judged, so the next read - // asks it or gives it up afresh, as the Rust `Misses::retry`. False when no fill can answer. - #retry(run: Run): boolean { - const producer = this.#state.producer; - if (!producer || this.#left) return false; - const fills = fillsOf(producer); - if (!fills.serving && !fills.active) return false; - this.#givenUp = removeRun(this.#givenUp, run.start, run.end); - this.#heads = removeRun(this.#heads, run.start, run.end); - this.#asked = removeRun(this.#asked, run.start, run.end); - this.#refilled = removeRun(this.#refilled, run.start, run.end); - insertRun(this.#unjudged, run.start, run.end); - return true; - } - - // Fresh reads from frame `from` of the cached groups in `[start, end)` this cursor admits and no - // longer judges stale, each expiring against the budget, and the runs still given up. A resumed - // reader asks its serving route's copy. Mirrors the Rust `reoffer_groups`. - #reofferGroups(start: bigint, end: bigint, from = 0): { groups: GroupConsumer[]; givenUp: Run[] } { - if (this.#resume) return this.#resume.reofferGroups(start, end, from); - const groups: GroupConsumer[] = []; - let givenUp: Run[] = [{ start, end }]; - const producer = this.#state.producer; - if (!producer) return { groups, givenUp }; - const drift = this.#drift(); + if (!producer) return undefined; const cap = this.#cursor.peek().end; - // Only what the cache holds, so a long run of groups long gone costs nothing. - const cached = cachedIn(producer, start, end).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)); - for (const sequence of cached) { - const admitted = (cap === undefined || sequence < cap) && this.#window.contains(sequence); - if (!admitted || this.#staleAt(sequence, drift)) continue; - const group = cachedMirror(producer, sequence, from); - if (!group) continue; - groups.push(this.#guard(group)); - givenUp = removeRun(givenUp, sequence, sequence + 1n); - } - return { groups, givenUp }; + const admitted = (cap === undefined || sequence < cap) && this.#window.contains(sequence); + if (!admitted || this.#staleAt(sequence, this.#drift())) return undefined; + const group = cachedMirror(producer, sequence, from); + return group && this.#guard(group); } private constructor(name: string, state: TrackState) { @@ -3534,7 +3340,7 @@ export class Subscriber { for (let i = runsFrom(unknown, over); i < unknown.length && unknown[i].start < to; i++) { const dropped = unknown[i]; const span = { ...dropped, start: max(dropped.start, over), end: min(dropped.end, to) }; - if (span.start < span.end && !settles(span, budget, coverage, this.#state.judged)) spans.push(span); + if (span.start < span.end && !settles(span, budget, coverage)) spans.push(span); } // Only what the window lets a miss ask for: none below the oldest group held for a time // start reaching back past it. @@ -3542,12 +3348,11 @@ export class Subscriber { for (const run of missable.flatMap((span) => this.#wants(span.start, span.end))) { const gone = [...accounted]; for (const dropped of givenUp(drops, refused.peek(), run.start, run.end, (run) => - settles(run, budget, coverage, this.#state.judged), + settles(run, budget, coverage), )) { // Judged from where it meets the asked run, as the reader would read it. const clipped = { ...dropped, start: max(dropped.start, run.start) }; - if (settles(clipped, budget, coverage, this.#state.judged)) - insertRun(gone, clipped.start, dropped.end); + if (settles(clipped, budget, coverage)) insertRun(gone, clipped.start, dropped.end); } for (const open of runGaps(gone, run.start, run.end)) { let next = open.start; @@ -3608,7 +3413,6 @@ export class Subscriber { at.producer !== producer || at.budget !== budget || !sameCoverage(at.coverage, coverage) || - at.judged !== state.judged || at.opened !== opened ) { this.#unjudged = [{ start: 0n, end: UNBOUNDED }]; @@ -3636,7 +3440,6 @@ export class Subscriber { producer, budget, coverage, - judged: state.judged, opened, drops: state.drops.revision, edge, @@ -3651,15 +3454,11 @@ export class Subscriber { // reader to read, so a run that settles here settles clipped too. Mirrors the Rust // `Misses::unknown`. #unknownRuns(budget: number, coverage: Coverage): readonly DropRun[] { - const { drops, judged } = this.#state; - const unsettled = (run: DropRun) => !settles(run, budget, coverage, judged); + const { drops } = this.#state; + const unsettled = (run: DropRun) => !settles(run, budget, coverage); const memo = this.#unknown; const removed = - memo && - memo.judged === judged && - memo.budget === budget && - sameCoverage(memo.coverage, coverage) && - drops.removedSince(memo.drops); + memo && memo.budget === budget && sameCoverage(memo.coverage, coverage) && drops.removedSince(memo.drops); if (memo && removed) { if (memo.drops === drops.revision) return memo.runs; // Updated in place: its one caller is done with the last answer. @@ -3680,7 +3479,7 @@ export class Subscriber { return runs; } const runs = drops.all.filter(unsettled); - this.#unknown = { drops: drops.revision, judged, budget, coverage, runs }; + this.#unknown = { drops: drops.revision, budget, coverage, runs }; return runs; } @@ -3826,14 +3625,14 @@ export class Subscriber { for (const gap of gaps) { // Each run judged from where it meets the gap, as the reader would read it. const overlapping = givenUp(all, refused.peek(), gap.start, gap.end, (run) => - settles(run, budget, coverage, this.#state.judged), + settles(run, budget, coverage), ).map((run) => ({ ...run, start: max(run.start, gap.start), end: min(run.end, gap.end), })); - const drops = overlapping.filter((run) => settles(run, budget, coverage, this.#state.judged)); - const unknown = overlapping.filter((run) => !settles(run, budget, coverage, this.#state.judged)); + const drops = overlapping.filter((run) => settles(run, budget, coverage)); + const unknown = overlapping.filter((run) => !settles(run, budget, coverage)); for (const open of runGaps(drops, gap.start, gap.end)) { if (unknown.some((run) => run.start < open.end && open.start < run.end)) return false; // Not received yet, so it may still arrive. @@ -3925,8 +3724,7 @@ export class Subscriber { }; hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); hooks.wire = (subscriber) => subscriber.#wireRecord(); - hooks.reofferStale = (subscriber) => subscriber.#reofferStale(); - hooks.reofferGroups = (subscriber, start, end, from) => subscriber.#reofferGroups(start, end, from); + hooks.continueGroup = (subscriber, sequence, from) => subscriber.#continueGroup(sequence, from); hooks.deliveredRuns = (subscriber) => subscriber.#delivered.runs; hooks.handedOut = (subscriber, sequence) => subscriber.#delivered.has(sequence); hooks.hasUnreadGroup = (subscriber, start, end, delivered) => @@ -3967,14 +3765,14 @@ export class Subscriber { return held; }; hooks.givenUp = (subscriber, sequence) => { - const { drops, refused, judged } = subscriber.#state; + const { drops, refused } = subscriber.#state; const drop = drops.at(sequence); const own = dropAt(refused.peek(), sequence); // As in `givenUp`: only a drop that settles the reader hides its own refusal. const wins = drop && (own === undefined || - settles({ ...drop, start: sequence }, subscriber.#drift().budget, subscriber.#coverage(), judged)); + settles({ ...drop, start: sequence }, subscriber.#drift().budget, subscriber.#coverage())); return { error: wins ? drop.error : own, changed: [drops.version, refused], @@ -4473,7 +4271,7 @@ export class Subscriber { // The first part of `[from, to)` this cursor has not reported yet within its window, now // reported, with why. - #report(from: bigint, to: bigint, hole: Hole & { received?: boolean }): (Recv & { kind: "drop" }) | undefined { + #report(from: bigint, to: bigint, hole: Hole): (Recv & { kind: "drop" }) | undefined { const { start, end } = this.#cursor.peek(); for (const run of this.#window.runs(max(from, start), min(to, end ?? to))) { const dropped = this.#reportRun(run.start, run.end, hole); @@ -4484,18 +4282,13 @@ export class Subscriber { // The first part of `[from, to)` nothing already reported blocks, now reported, with why, // replacing what it goes out over. Mirrors the Rust `Record::report`. - #reportRun(from: bigint, to: bigint, hole: Hole & { received?: boolean }): (Recv & { kind: "drop" }) | undefined { + #reportRun(from: bigint, to: bigint, hole: Hole): (Recv & { kind: "drop" }) | undefined { const start = from; if (start >= to) return undefined; const blocked = this.#reported.overlapping(start, to).filter((reported) => blocksHole(reported, hole)); const [gap] = runGaps(blocked, start, to); if (!gap) return undefined; - const kind = hole.skip ? "skip" : hole.stale !== undefined ? "stale" : "dropped"; - this.#reported.set(gap.start, gap.end, { - ...gap, - kind, - ...(kind === "stale" && hole.received ? { received: true } : {}), - }); + this.#reported.set(gap.start, gap.end, { ...gap, kind: hole.skip ? "skip" : "dropped" }); return { kind: "drop", ...gap, error: hole.error, skip: hole.skip, stale: hole.stale }; } @@ -4522,7 +4315,6 @@ export class Subscriber { const revision = this.#revision; const { budget } = this.#drift(); const coverage = this.#coverage(); - const judged = this.#state.judged; const seen = this.#dropsSeen; const full = !seen || @@ -4531,8 +4323,7 @@ export class Subscriber { seen.end !== end || seen.revision !== revision || seen.budget !== budget || - !sameCoverage(seen.coverage, coverage) || - seen.judged !== judged; + !sameCoverage(seen.coverage, coverage); const changed: Run[] = full ? [{ start, end: end ?? UNBOUNDED }] : drops.since(seen.drops); if (full) this.#pending = this.#pending.filter((run) => !run.received); this.#dropsSeen = { @@ -4543,7 +4334,6 @@ export class Subscriber { revision, budget, coverage, - judged, }; for (const span of changed) { const from = max(span.start, start); @@ -4553,14 +4343,14 @@ export class Subscriber { this.#pending = this.#pending.flatMap((run) => (run.received ? removeRun([run], from, to) : [run])); } // The reader's own refusals too: clearing the span above took out those it covered. - const folded = givenUp(drops, refused.peek(), from, to, (run) => settles(run, budget, coverage, judged)); + const folded = givenUp(drops, refused.peek(), from, to, (run) => settles(run, budget, coverage)); const received: DropRun[] = []; for (const dropped of folded) { // Judged from where it meets this cursor's span, as Rust clips it. const run = { ...dropped, start: max(dropped.start, from), end: min(dropped.end, to) }; if (run.start >= run.end) continue; // A received stale run that does not settle this reader is unknown to it. - if (!settles(run, budget, coverage, judged)) continue; + if (!settles(run, budget, coverage)) continue; received.push({ ...run, received: true }); } // Sorted and disjoint: the settling drops and the refusals they leave never overlap. @@ -4572,7 +4362,7 @@ export class Subscriber { if (run.received) { const folded = run; const held = givenUp(drops, refused.peek(), run.start, run.end, (run) => - settles(run, budget, coverage, judged), + settles(run, budget, coverage), ).find((given) => sameVerdict(given, folded)); if (!held) continue; if (held.end < run.end) this.#pending.unshift({ ...run, start: held.end }); From d262d4e16378097aac0a6c65dc5aab0aa1e0a651 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 03:41:20 -0800 Subject: [PATCH 06/26] feat(net)!: a track listing carries each track's kind, so datagram tracks are listed Lite-07 TRACKS_ADD now leads with a Kind (0x0 a track of groups with its TRACK_INFO, 0x1 a datagram track with its DATAGRAMS_INFO), and TRACKS_REMOVE and TRACKS_FINISH name the kind before the name. Any other kind is a PROTOCOL_VIOLATION. A name is listed at most once per kind, and the duplicate add / unknown removal rules apply per (kind, name). The model lists a datagram track a broadcast creates until it ends (finished or not), and a handler's answer lists either kind, so a relay's copy forwards its upstream's datagram tracks too. A datagram track served on request, or a session's datagram track riding a stream subscription (lite-05/06, moq-transport), is never listed: sessions create those unlisted. Rust: broadcast::TracksEvent::Added carries info: Listed (Track(track::Info) or Datagrams(datagram::Info)); Removed and Finished carry kind: Kind. Lister::add takes impl Into; remove and finish take (kind, name). moq-crypto's e2ee Lister mirrors that. lite::TracksEvent mirrors the model with lite::Listed. JS: TracksEvent's added variant is { kind, name } & Listed, where Listed is { info: track.Info, datagrams?: false } or { info: datagram.Info, datagrams: true }; removed and finished set datagrams for a datagram track. Lister.add takes a Listed; remove and finish take (name, datagrams). moq-archive and moq-stats (Rust and JS) ignore datagram tracks: neither has anything to do with one. The IETF listing lists only tracks of groups, as before. Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 12 +- js/net/src/broadcast.ts | 47 ++- js/net/src/datagram.ts | 1 + js/net/src/ietf/subscriber.ts | 2 +- js/net/src/internal.ts | 5 + js/net/src/listing.test.ts | 86 +++- js/net/src/listing.ts | 231 +++++++---- js/net/src/lite/publisher.ts | 16 +- js/net/src/lite/subscriber.ts | 29 +- js/net/src/lite/tracks.test.ts | 63 ++- js/net/src/lite/tracks.ts | 60 ++- js/net/src/resume.test.ts | 6 +- js/net/src/resume.ts | 43 +- js/net/src/wire.ts | 3 +- js/stats/src/consumer.ts | 2 + rs/moq-archive/src/producer/mod.rs | 16 +- rs/moq-crypto/src/e2ee/broadcast.rs | 21 +- rs/moq-crypto/src/e2ee/tests.rs | 21 +- rs/moq-net/src/ietf/subscriber/datagrams.rs | 2 +- rs/moq-net/src/ietf/subscriber/tracks.rs | 9 +- rs/moq-net/src/lite/ietf.rs | 5 +- rs/moq-net/src/lite/publisher.rs | 13 +- rs/moq-net/src/lite/subscriber.rs | 74 ++-- rs/moq-net/src/lite/tracks.rs | 164 +++++++- rs/moq-net/src/model/broadcast.rs | 69 +++- rs/moq-net/src/model/datagram.rs | 42 +- rs/moq-net/src/model/listing.rs | 416 ++++++++++++++------ rs/moq-net/src/model/origin.rs | 55 ++- rs/moq-net/src/test_interop.rs | 45 ++- rs/moq-net/tests/integration/tracks.rs | 85 +++- rs/moq-net/tests/integration/tracks_ietf.rs | 4 +- rs/moq-stats/src/aggregate.rs | 18 +- rs/moq-stats/src/lib.rs | 16 +- rs/moq-stats/src/produce.rs | 16 +- test/interop/README.md | 7 +- test/interop/tracks.ts | 7 +- 36 files changed, 1263 insertions(+), 448 deletions(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 0a60027e0ec..a4c370b6c23 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -97,6 +97,13 @@ export namespace Broadcast { track(name: string): Track.Consumer; tracks(): Broadcast.Tracks; } + export type Listed = { + datagrams?: false; + info: Track.Info; + } | { + datagrams: true; + info: Datagram.Info; + }; export class Producer { constructor(); close(): void; @@ -113,15 +120,16 @@ export namespace Broadcast { next(): Promise; } export type TracksEvent = { - info: Track.Info; kind: "added"; name: string; - } | { + } & Broadcast.Listed | { kind: "synced"; } | { + datagrams?: boolean; kind: "removed"; name: string; } | { + datagrams?: boolean; kind: "finished"; name: string; }; diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index cd3314269dc..2d4a12e6d7f 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -16,7 +16,7 @@ import * as track from "./track.ts"; import { untilAborted } from "./util/abort.ts"; import { registerWire, trackOf, wireOf } from "./wire.ts"; -export { Tracks, type TracksEvent } from "./listing.ts"; +export { type Listed, Tracks, type TracksEvent } from "./listing.ts"; let stampProducer: (producer: Producer, path: Path.Valid) => void; @@ -67,7 +67,7 @@ function createProducer(state: BroadcastState, name: string): track.Producer { return producer; } -// Datagram tracks never enter the stream listing or cache. +// Datagram tracks never enter the stream cache. function liveDatagrams(state: BroadcastState, name: string, passive = false): datagram.Consumer | undefined { const producer = state.datagrams.get(name); if (!producer) return; @@ -78,23 +78,38 @@ function liveDatagrams(state: BroadcastState, name: string, passive = false): da return passive ? hooks.observeDatagrams(producer) : producer.consume(); } -function createDatagrams(state: BroadcastState, name: string, info: Partial): datagram.Producer { +// Create the datagram track `name`, listed until it ends unless `listed` is false: a session's +// datagram track riding a stream track's subscription serves a request, not the inventory. +function createDatagrams( + state: BroadcastState, + name: string, + info: Partial, + listed = true, +): datagram.Producer { if (state.closed.peek() !== undefined) throw new Error("broadcast is closed"); // A request its readers closed waits for async cleanup; serve the name fresh instead. const queued = state.datagramRequested .peek() .find((request) => request.name === name && request.closed.peek() === undefined); + let producer: datagram.Producer; if (queued) { state.datagramRequested.mutate((requests) => requests.splice(requests.indexOf(queued), 1)); - return queued.accept(info); + producer = queued.accept(info); + } else { + const existing = state.datagrams.get(name); + if (existing?.closed.peek() === undefined && existing) throw new Error(`duplicate datagram track: ${name}`); + producer = new datagram.Producer(name).accept(info); + state.datagrams.set(name, producer); + void producer.closed.then(() => { + if (state.datagrams.get(name) === producer) state.datagrams.delete(name); + }); + } + if (listed) { + const accepted = hooks.datagramInfo(producer); + if (!accepted) throw new Error("datagram track has not been accepted"); + state.listing.listDatagrams(producer, accepted); + void producer.closed.then(() => state.listing.unlistOwn(producer, true)); } - const existing = state.datagrams.get(name); - if (existing?.closed.peek() === undefined && existing) throw new Error(`duplicate datagram track: ${name}`); - const producer = new datagram.Producer(name).accept(info); - state.datagrams.set(name, producer); - void producer.closed.then(() => { - if (state.datagrams.get(name) === producer) state.datagrams.delete(name); - }); return producer; } @@ -380,13 +395,13 @@ function adopt(state: BroadcastState, producer: track.Producer, info: track.Info const lookups = state.lookups.get(producer) ?? new Lookups(); state.lookups.set(producer, lookups); state.tracks.set(producer.name, producer); - state.listing.listOwn(producer.name, producer, info); + state.listing.listTrack(producer, info); // A finished track keeps serving its cache, so only an abort evicts it. void hooks.trackReleased(producer).then((closed) => { if (!(closed instanceof Error)) return; if (state.tracks.get(producer.name) === producer) state.tracks.delete(producer.name); - state.listing.unlistOwn(producer.name, producer); + state.listing.unlistOwn(producer); }); } @@ -409,7 +424,7 @@ export class Producer { requested: () => requested(this.#state), datagrams: (name) => datagrams(this.#state, name), liveDatagrams: (name) => liveDatagrams(this.#state, name, true), - createDatagrams: (name, info) => createDatagrams(this.#state, name, info), + createDatagrams: (name, info, listed) => createDatagrams(this.#state, name, info, listed), requestedDatagrams: () => requestedDatagrams(this.#state), tracks: (owner) => listTracks(this.#state.listing, owner), lister: () => makeLister(this.#state.listing), @@ -503,7 +518,7 @@ export class Producer { const track = this.#state.tracks.get(name); if (!track) return; this.#state.tracks.delete(name); - this.#state.listing.unlistOwn(name, track); + this.#state.listing.unlistOwn(track); } /** A lazy read handle for a track on this broadcast. */ @@ -571,7 +586,7 @@ export class Consumer { requested: () => requested(this.#state), datagrams: (name) => datagrams(this.#state, name), liveDatagrams: (name) => liveDatagrams(this.#state, name, true), - createDatagrams: (name, info) => createDatagrams(this.#state, name, info), + createDatagrams: (name, info, listed) => createDatagrams(this.#state, name, info, listed), requestedDatagrams: () => requestedDatagrams(this.#state), tracks: (owner) => this.#tracks(owner), lister: () => makeLister(this.#state.listing), diff --git a/js/net/src/datagram.ts b/js/net/src/datagram.ts index 0a559368f05..dee10663ca9 100644 --- a/js/net/src/datagram.ts +++ b/js/net/src/datagram.ts @@ -109,6 +109,7 @@ export class Producer { static { hooks.observeDatagrams = (producer) => consume(producer.name, producer.#state, undefined, null); + hooks.datagramInfo = (producer) => producer.#state.info.peek(); hooks.closeUnusedDatagrams = (producer) => { if (producer.#state.consumers.size > 0) return false; producer.abort(new StreamError(StreamCode.Cancel)); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 2b898d488b8..a06dab983b3 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -2334,7 +2334,7 @@ export class Subscriber { const entry = pending?.get(track.name); let producer: datagram.Producer; try { - producer = entry ? entry.request.accept(info) : wireOf(source).createDatagrams(track.name, info); + producer = entry ? entry.request.accept(info) : wireOf(source).createDatagrams(track.name, info, false); } catch (err) { entry?.request.reject(error(err)); console.debug(`serving the stream track without datagrams: ${reason(err)}`); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index de11cacebdb..5624210a6cd 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -589,6 +589,8 @@ export const hooks: { datagramRequest: (producer: datagram.Producer, pending: Set) => datagram.Request; /** End a received datagram track if its last consumer left. */ closeUnusedDatagrams: (producer: datagram.Producer) => boolean; + /** A datagram track's properties, once accepted. */ + datagramInfo: (producer: datagram.Producer) => datagram.Info | undefined; /** Follow this consumer's subscriber priority for transport scheduling. */ datagramPriority: (consumer: datagram.Consumer) => Getter; /** Forward data carried by an existing stream without contributing another subscription's demand. */ @@ -996,6 +998,9 @@ export const hooks: { closeUnusedDatagrams: () => { throw new Error("datagram module not loaded"); }, + datagramInfo: () => { + throw new Error("datagram module not loaded"); + }, observeDatagrams: () => { throw new Error("datagram module not loaded"); }, diff --git a/js/net/src/listing.test.ts b/js/net/src/listing.test.ts index f8ea7acc715..ec24e17f2f8 100644 --- a/js/net/src/listing.test.ts +++ b/js/net/src/listing.test.ts @@ -14,8 +14,9 @@ function settle(): Promise { } /** - * Reads a listing as `+name`, `-name`, `synced`, `end`, or `error: ..`, keeping one pending read - * across calls so a read that loses to {@link drain}'s settle never drops an event. + * Reads a listing as `+name`, `-name`, `~name` (finished), `synced`, `end`, or `error: ..`, a + * datagram track's name prefixed `d:`, keeping one pending read across calls so a read that loses + * to {@link drain}'s settle never drops an event. */ class Events { readonly tracks: Tracks; @@ -34,7 +35,7 @@ class Events { if (!event) return "end"; if (event.kind === "synced") return "synced"; const sign = { added: "+", removed: "-", finished: "~" }[event.kind]; - return `${sign}${event.name}`; + return `${sign}${event.datagrams ? "d:" : ""}${event.name}`; }, (err: unknown) => `error: ${err instanceof StreamError ? err.code : String(err)}`, ); @@ -73,6 +74,61 @@ test("a listed track reports its info", async () => { expect(event?.kind === "added" && event.info).toMatchObject({ priority: 9, refresh: 4 }); }); +test("a datagram track is listed until it ends", async () => { + const broadcast = new BroadcastProducer(); + const early = broadcast.createDatagrams("early", { priority: 4 }); + const event = await broadcast.consume().tracks().next(); + expect(event).toMatchObject({ kind: "added", name: "early", datagrams: true, info: { priority: 4 } }); + + const tracks = list(broadcast); + expect(await tracks.drain()).toEqual(["+d:early", "synced"]); + const late = broadcast.createDatagrams("late"); + expect(await tracks.drain()).toEqual(["+d:late"]); + early.finish(); + late.abort(new Error("aborted")); + expect(await tracks.drain()).toEqual(["~d:early", "-d:late"]); + + // A name ended is free for a new track, listed afresh. + broadcast.createDatagrams("early"); + expect(await tracks.drain()).toEqual(["+d:early"]); +}); + +test("the two kinds of a name are listed apart", async () => { + const broadcast = new BroadcastProducer(); + broadcast.createTrack("a"); + const datagrams = broadcast.createDatagrams("a"); + const tracks = list(broadcast); + expect(await tracks.drain()).toEqual(["+a", "+d:a", "synced"]); + broadcast.removeTrack("a"); + expect(await tracks.drain()).toEqual(["-a"]); + datagrams.finish(); + expect(await tracks.drain()).toEqual(["~d:a"]); + + const lister = wireOf(broadcast).lister(); + lister.add("b", { info: INFO }); + lister.add("b", { datagrams: true, info: { priority: 0, timescale: null } }); + expect(() => lister.add("b", { datagrams: true, info: { priority: 0, timescale: null } })).toThrow("duplicate"); + lister.synced(); + expect(await tracks.drain()).toEqual(["+b", "+d:b"]); + lister.finish("b", true); + expect(() => lister.remove("b", true)).toThrow("not listed"); + lister.remove("b"); + expect(await tracks.drain()).toEqual(["~d:b", "-b"]); +}); + +test("a datagram track served on request is never listed", async () => { + const broadcast = new BroadcastProducer(); + const consumer = broadcast.consume(); + const requested = wireOf(broadcast).requestedDatagrams(); + const tracks = new Events(consumer.tracks()); + expect(await tracks.drain()).toEqual(["synced"]); + consumer.datagrams("x"); + (await requested)?.accept({}); + // A session's datagram track riding a stream track's subscription is not listed either. + wireOf(broadcast).createDatagrams("y", {}, false); + expect(await tracks.drain()).toEqual([]); +}); + test("a track leaving the table is removed", async () => { const broadcast = new BroadcastProducer(); broadcast.createTrack("a"); @@ -113,8 +169,8 @@ test("a lister finishes or removes a track", async () => { const broadcast = new BroadcastProducer(); const lister = wireOf(broadcast).lister(); const tracks = list(broadcast); - lister.add("up", INFO); - lister.add("gone", INFO); + lister.add("up", { info: INFO }); + lister.add("gone", { info: INFO }); lister.synced(); expect(await tracks.drain()).toEqual(["+up", "+gone", "synced"]); lister.finish("up"); @@ -237,7 +293,7 @@ test("a clean end follows the removals before it", async () => { // The producer's finished track is what a handler's answer of its name served. const both = new BroadcastProducer(); const handler = wireOf(both).lister(); - handler.add("a", INFO); + handler.add("a", { info: INFO }); handler.synced(); const own = both.createTrack("a"); const served = list(both); @@ -263,7 +319,7 @@ test("a clean end follows the removals before it", async () => { const answered = new BroadcastProducer(); const lister = wireOf(answered).lister(); const reader = list(answered); - lister.add("up", INFO); + lister.add("up", { info: INFO }); lister.synced(); expect(await reader.drain()).toEqual(["+up", "synced"]); lister.finish("up"); @@ -298,8 +354,8 @@ test("readers wait for the lister to sync", async () => { const tracks = list(broadcast); expect(lister.wanted.peek()).toBe(true); expect(await tracks.drain()).toEqual(["+own"]); - lister.add("up", INFO); - expect(() => lister.add("up", INFO)).toThrow("duplicate"); + lister.add("up", { info: INFO }); + expect(() => lister.add("up", { info: INFO })).toThrow("duplicate"); lister.synced(); expect(await tracks.drain()).toEqual(["+up", "synced"]); @@ -315,7 +371,7 @@ test("a name listed by both is reported once", async () => { const broadcast = new BroadcastProducer(); broadcast.createTrack("a"); const lister = wireOf(broadcast).lister(); - lister.add("a", INFO); + lister.add("a", { info: INFO }); lister.synced(); const tracks = list(broadcast); expect(await tracks.drain()).toEqual(["+a", "synced"]); @@ -329,7 +385,7 @@ test("an aborted answer fails its readers and a later reader asks again", async const broadcast = new BroadcastProducer(); const lister = wireOf(broadcast).lister(); const tracks = list(broadcast); - lister.add("up", INFO); + lister.add("up", { info: INFO }); lister.abort(new NotFound("broadcast")); expect(await tracks.drain()).toEqual([`error: ${StreamCode.NotFound}`]); expect(lister.wanted.peek()).toBe(false); @@ -347,7 +403,7 @@ test("an aborted answer fails its readers and a later reader asks again", async test("a closed lister withdraws its answer and syncs", async () => { const broadcast = new BroadcastProducer(); const lister = wireOf(broadcast).lister(); - lister.add("up", INFO); + lister.add("up", { info: INFO }); const tracks = list(broadcast); expect(await tracks.drain()).toEqual(["+up"]); lister.close(); @@ -360,11 +416,11 @@ test("a closed lister answers nothing more, even beside its successor", async () stale.close(); const lister = wireOf(broadcast).lister(); const tracks = list(broadcast); - stale.add("stale", INFO); + stale.add("stale", { info: INFO }); stale.synced(); stale.abort(new Error("stale")); expect(await tracks.drain()).toEqual([]); - lister.add("up", INFO); + lister.add("up", { info: INFO }); lister.synced(); expect(await tracks.drain()).toEqual(["+up", "synced"]); }); @@ -404,7 +460,7 @@ test("an ended answer ends its readers and a later reader asks again", async () const broadcast = new BroadcastProducer(); const lister = wireOf(broadcast).lister(); const tracks = list(broadcast); - lister.add("up", INFO); + lister.add("up", { info: INFO }); lister.synced(); expect(await tracks.drain()).toEqual(["+up", "synced"]); lister.end(); diff --git a/js/net/src/listing.ts b/js/net/src/listing.ts index ec7ba1152d6..b711dea9168 100644 --- a/js/net/src/listing.ts +++ b/js/net/src/listing.ts @@ -1,68 +1,102 @@ /** * A broadcast's track listing: the tracks it lists, reported to each reader in order. * - * A track is listed while it is in the broadcast's table: created by its producer until it - * aborts or is removed, or answered by a {@link Lister}, as a session lists its peer's tracks. - * A track served only on request is never listed, and listing never requests one. + * A track is listed while it is in the broadcast's table: created by its producer (a track of + * groups until it aborts or is removed, a datagram track until it ends), or answered by a + * {@link Lister}, as a session lists its peer's tracks. A track served only on request is never + * listed, and listing never requests one. * - * Each {@link Tracks} reader keeps its own queue, keyed by name in insertion order, so a - * stalled reader holds at most one pending change per name: an add and a removal it has not - * reached cancel, and a removal and re-add of a name it saw collapse in place. Its state is - * bounded by the names it saw plus the live set, however long it stalls. + * Datagram tracks are a namespace apart from tracks of groups, so a name is listed at most once + * per kind. + * + * Each {@link Tracks} reader keeps its own queue, keyed by kind and name in insertion order, so a + * stalled reader holds at most one pending change per listed track: an add and a removal it has + * not reached cancel, and a removal and re-add of a track it saw collapse in place. Its state is + * bounded by the tracks it saw plus the live set, however long it stalls. * * @module */ import { type GetPromise, type Getter, Signal } from "@moq/signals"; +import type * as datagram from "./datagram.ts"; import { StreamCode, StreamError } from "./error.ts"; import { hooks } from "./internal.ts"; import type * as track from "./track.ts"; +/** + * A listed track's kind and fixed properties: a track of groups with its {@link track.Info}, or + * with `datagrams` set, a datagram track with its {@link datagram.Info}. + * + * @public + */ +export type Listed = { datagrams?: false; info: track.Info } | { datagrams: true; info: datagram.Info }; + /** * What a {@link Tracks} listing reports, in order. * - * `added`: a track the broadcast lists, with its fixed properties. `synced`: every track - * listed when the listing began, and still listed, was reported; sent once, and later events - * are live. `removed`: a track an earlier `added` reported is no longer listed, unfinished: its - * producer aborted, or the answer that listed it withdrew it; a handler may still serve its name - * on request. `finished`: a track an earlier `added` reported is no longer listed because it - * finished. + * `added`: a track the broadcast lists, with its kind and fixed properties. `synced`: every + * track listed when the listing began, and still listed, was reported; sent once, and later + * events are live. `removed`: a track an earlier `added` reported is no longer listed, + * unfinished: its producer aborted, or the answer that listed it withdrew it; a handler may still + * serve its name on request. `finished`: a track an earlier `added` reported is no longer listed + * because it finished. A removal of a datagram track sets `datagrams`, as its `added` did. * * @public */ export type TracksEvent = - | { kind: "added"; name: string; info: track.Info } + | ({ kind: "added"; name: string } & Listed) | { kind: "synced" } - | { kind: "removed"; name: string } - | { kind: "finished"; name: string }; + | { kind: "removed"; name: string; datagrams?: boolean } + | { kind: "finished"; name: string; datagrams?: boolean }; + +/** A producer whose track the listing lists. */ +type Own = { datagrams?: false; producer: track.Producer } | { datagrams: true; producer: datagram.Producer }; /** - * Whether `own` leaves the listing as finished: it closed cleanly, or it declared its end and is - * still open, as the Rust listing counts a producer that finished but still holds its track. + * Whether `own` leaves the listing as finished: it closed cleanly, or a track of groups declared + * its end and is still open, as the Rust listing counts a producer that finished but still holds + * its track. + */ +function finished(own: Own): boolean { + if (own.datagrams) return own.producer.closed.peek() === null; + const released = hooks.trackReleased(own.producer).peek(); + return released === null || (released === undefined && hooks.trackFinished(own.producer)); +} + +/** + * The key a listed track is held under: its kind, then its name, so the kinds never collide. + * + * @internal */ -function finished(own: track.Producer): boolean { - const released = hooks.trackReleased(own).peek(); - return released === null || (released === undefined && hooks.trackFinished(own)); +export function keyOf(name: string, datagrams: boolean | undefined): string { + return (datagrams ? "d" : "t") + name; +} + +/** The event for the track under `key` leaving the listing. */ +function removal(key: string, finished: boolean): TracksEvent { + const kind = finished ? "finished" : "removed"; + const name = key.slice(1); + return key[0] === "d" ? { kind, name, datagrams: true } : { kind, name }; } /** One listed track and who lists it. */ interface Entry { - info: track.Info; + listed: Listed; /** The producer whose track lists it, so a stale unlist never removes a later track of the name. */ - own?: track.Producer; + own?: Own; /** Whether the lister's answer lists it. */ answered: boolean; } /** - * A change a reader has yet to read. `readd` is a removal of a name it saw, then the name listed - * again. A removal carries whether the track finished. + * A change a reader has yet to read. `readd` is a removal of a track it saw, then a track of the + * same kind and name listed again. A removal carries whether the track finished. */ type Pending = - | { kind: "add"; info: track.Info } + | { kind: "add"; listed: Listed } | { kind: "remove"; finished: boolean } - | { kind: "readd"; finished: boolean; info: track.Info }; + | { kind: "readd"; finished: boolean; listed: Listed }; -/** One reader's pending changes, keyed by name in the order they happened. */ +/** One reader's pending changes, keyed by kind and name in the order they happened. */ class Queue { pending = new Map(); /** Events left to send before SYNCED, once the listing has synced. */ @@ -79,18 +113,18 @@ class Queue { this.changed.update((n) => n + 1); } - add(name: string, info: track.Info) { - // A name is listed once at a time, so only its removal can be pending. - const pending = this.pending.get(name); - if (pending?.kind === "remove") this.pending.set(name, { kind: "readd", finished: pending.finished, info }); - else this.pending.set(name, { kind: "add", info }); + add(key: string, listed: Listed) { + // A track is listed once at a time, so only its removal can be pending. + const pending = this.pending.get(key); + if (pending?.kind === "remove") this.pending.set(key, { kind: "readd", finished: pending.finished, listed }); + else this.pending.set(key, { kind: "add", listed }); this.wake(); } - remove(name: string, finished: boolean) { + remove(key: string, finished: boolean) { // Never read: the two cancel. Otherwise the removal replaces a pending re-add in place. - if (this.pending.get(name)?.kind === "add") this.pending.delete(name); - else this.pending.set(name, { kind: "remove", finished }); + if (this.pending.get(key)?.kind === "add") this.pending.delete(key); + else this.pending.set(key, { kind: "remove", finished }); this.wake(); } @@ -128,9 +162,9 @@ class Queue { if (this.end === null) { // A clean end still reports each track that left before it, and how; an add the // reader never read is dropped. - for (const [name, pending] of this.pending) { - this.pending.delete(name); - if (pending.kind !== "add") return { kind: pending.finished ? "finished" : "removed", name }; + for (const [key, pending] of this.pending) { + this.pending.delete(key); + if (pending.kind !== "add") return removal(key, pending.finished); } return undefined; } @@ -140,19 +174,19 @@ class Queue { } const first = this.pending.entries().next(); if (first.done) throw new Error("a ready queue has a pending change"); - const [name, pending] = first.value; + const [key, pending] = first.value; if (!this.synced && this.bound !== undefined) this.bound -= 1; switch (pending.kind) { case "add": - this.pending.delete(name); - return { kind: "added", name, info: pending.info }; + this.pending.delete(key); + return { kind: "added", name: key.slice(1), ...pending.listed }; case "remove": - this.pending.delete(name); - return { kind: pending.finished ? "finished" : "removed", name }; + this.pending.delete(key); + return removal(key, pending.finished); case "readd": // Setting an existing key keeps its place, so the add is read next. - this.pending.set(name, { kind: "add", info: pending.info }); - return { kind: pending.finished ? "finished" : "removed", name }; + this.pending.set(key, { kind: "add", listed: pending.listed }); + return removal(key, pending.finished); } } } @@ -205,15 +239,15 @@ export class Listing { if (was && !now) for (const queue of this.#readers) queue.unsync(); } - #insert(name: string, entry: Entry) { - this.#live.set(name, entry); - for (const queue of this.#readers) queue.add(name, entry.info); + #insert(key: string, entry: Entry) { + this.#live.set(key, entry); + for (const queue of this.#readers) queue.add(key, entry.listed); } - /** Unlist `name`, telling readers whether it `finished`. */ - #remove(name: string, finished: boolean) { - if (!this.#live.delete(name)) return; - for (const queue of this.#readers) queue.remove(name, finished); + /** Unlist the track under `key`, telling readers whether it `finished`. */ + #remove(key: string, finished: boolean) { + if (!this.#live.delete(key)) return; + for (const queue of this.#readers) queue.remove(key, finished); } /** @@ -225,7 +259,7 @@ export class Listing { throw new StreamError(StreamCode.Unroutable, { message: "broadcast is closed" }); } const queue = new Queue(); - for (const [name, entry] of this.#live) queue.pending.set(name, { kind: "add", info: entry.info }); + for (const [key, entry] of this.#live) queue.pending.set(key, { kind: "add", listed: entry.listed }); if (this.#synced()) queue.bound = queue.pending.size; this.#readers.add(queue); if (owner) { @@ -250,28 +284,39 @@ export class Listing { this.#counted(); } - /** List a track `own` created. */ - listOwn(name: string, own: track.Producer, info: track.Info) { - const entry = this.#live.get(name); + /** List the track of groups `producer` created. */ + listTrack(producer: track.Producer, info: track.Info) { + this.#listOwn(producer.name, { producer }, { info }); + } + + /** List the datagram track `producer` created. */ + listDatagrams(producer: datagram.Producer, info: datagram.Info) { + this.#listOwn(producer.name, { datagrams: true, producer }, { datagrams: true, info }); + } + + #listOwn(name: string, own: Own, listed: Listed) { + const key = keyOf(name, listed.datagrams); + const entry = this.#live.get(key); if (!entry) { - this.#insert(name, { info, own, answered: false }); + this.#insert(key, { listed, own, answered: false }); } else if (entry.own && !entry.answered) { // The earlier track of the name has not unlisted yet, but it left the table for this // one: readers see it go, as it ended, and the new one arrive. - this.#remove(name, finished(entry.own)); - this.#insert(name, { info, own, answered: false }); + this.#remove(key, finished(entry.own)); + this.#insert(key, { listed, own, answered: false }); } else { // Listed already by the answer, and it never stopped being listed: only the owner moves. entry.own = own; } } - /** Unlist a track `own` created, as it ended, unless a later one took its name. */ - unlistOwn(name: string, own: track.Producer) { - const entry = this.#live.get(name); - if (entry?.own !== own) return; + /** Unlist the track `producer` created, as it ended, unless a later one took its name. */ + unlistOwn(producer: track.Producer | datagram.Producer, datagrams = false) { + const entry = this.#live.get(keyOf(producer.name, datagrams)); + if (!entry?.own || entry.own.producer !== producer) return; + const own = entry.own; entry.own = undefined; - if (!entry.answered) this.#remove(name, finished(own)); + if (!entry.answered) this.#remove(keyOf(producer.name, datagrams), finished(own)); } /** Lister support; see {@link Lister}. */ @@ -290,18 +335,28 @@ export class Listing { this.#resync(was); } - answerAdd(name: string, info: track.Info) { - const entry = this.#live.get(name); + answerAdd(name: string, listed: Listed) { + const key = keyOf(name, listed.datagrams); + const entry = this.#live.get(key); if (entry?.answered) throw new Error(`duplicate listed track: ${name}`); if (entry) entry.answered = true; - else this.#insert(name, { info, answered: true }); + // Copied, so an event forwarded as the answer lends it nothing else. + else + this.#insert(key, { + listed: listed.datagrams ? { datagrams: true, info: listed.info } : { info: listed.info }, + answered: true, + }); } - answerRemove(name: string, finished: boolean) { - const entry = this.#live.get(name); - if (!entry?.answered) throw new Error(`track not listed: ${name}`); + answerRemove(name: string, finished: boolean, datagrams = false) { + this.#answerRemove(keyOf(name, datagrams), finished); + } + + #answerRemove(key: string, finished: boolean) { + const entry = this.#live.get(key); + if (!entry?.answered) throw new Error(`track not listed: ${key.slice(1)}`); entry.answered = false; - if (!entry.own) this.#remove(name, finished); + if (!entry.own) this.#remove(key, finished); } answerSynced() { @@ -318,8 +373,8 @@ export class Listing { } #unanswer() { - for (const [name, entry] of [...this.#live]) { - if (entry.answered) this.answerRemove(name, false); + for (const [key, entry] of [...this.#live]) { + if (entry.answered) this.#answerRemove(key, false); } this.#answered = false; } @@ -330,8 +385,8 @@ export class Listing { * track is what served it. */ close() { - for (const [name, entry] of [...this.#live]) { - if (entry.own && finished(entry.own)) this.#remove(name, true); + for (const [key, entry] of [...this.#live]) { + if (entry.own && finished(entry.own)) this.#remove(key, true); } this.detach(null); } @@ -448,19 +503,25 @@ export class Lister { return this.#listing.closed; } - /** List a track. Throws if this answer already lists it. */ - add(name: string, info: track.Info): void { - this.#answering?.answerAdd(name, info); + /** List a track of the kind `listed` says. Throws if this answer already lists that kind and name. */ + add(name: string, listed: Listed): void { + this.#answering?.answerAdd(name, listed); } - /** Stop listing a track that left unfinished, reported as `removed`. Throws if this answer does not list it. */ - remove(name: string): void { - this.#answering?.answerRemove(name, false); + /** + * Stop listing a track that left unfinished, reported as `removed`; a datagram track with + * `datagrams`. Throws if this answer does not list that kind and name. + */ + remove(name: string, datagrams = false): void { + this.#answering?.answerRemove(name, false, datagrams); } - /** Stop listing a track that finished, reported as `finished`. Throws if this answer does not list it. */ - finish(name: string): void { - this.#answering?.answerRemove(name, true); + /** + * Stop listing a track that finished, reported as `finished`; a datagram track with + * `datagrams`. Throws if this answer does not list that kind and name. + */ + finish(name: string, datagrams = false): void { + this.#answering?.answerRemove(name, true, datagrams); } /** The answer holds everything this hop knows now; later changes are live. */ diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 2bcc23536ed..aab4b5f5b5d 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -82,7 +82,7 @@ import { type WireRange, } from "./subscribe.ts"; import { TrackInfo as TrackInfoMessage, type Track as TrackMessage } from "./track.ts"; -import { encodeTracksEvent, type Tracks as TracksMessage } from "./tracks.ts"; +import { encodeTracksEvent, type Tracks as TracksMessage, type TracksEvent as TracksMessageEvent } from "./tracks.ts"; import { hasAnnounceId, hasAnnounceOk, @@ -172,6 +172,14 @@ function acknowledged(writer: Writer): Promise { } // The TRACK_INFO a TRACK stream, or a listing's TRACKS_ADD, answers for a track. +/** A listing event as TRACKS carries it: an added track's info as its kind's request would answer. */ +function tracksEvent(event: broadcast.TracksEvent, version: Version): TracksMessageEvent { + if (event.kind !== "added") return event; + if (event.datagrams) + return { kind: "added", name: event.name, datagrams: true, info: new DatagramsInfo(event.info) }; + return { kind: "added", name: event.name, info: trackInfoMessage(event.info, version) }; +} + function trackInfoMessage(info: track.Info, version: Version): TrackInfoMessage { return new TrackInfoMessage({ priority: info.priority, @@ -2180,11 +2188,7 @@ export class Publisher { const event = await untilAborted(tracks.next(), cancel.signal); if (!event) break; await untilAborted( - encodeTracksEvent( - stream.writer, - event.kind === "added" ? { ...event, info: trackInfoMessage(event.info, this.version) } : event, - this.version, - ), + encodeTracksEvent(stream.writer, tracksEvent(event, this.version), this.version), cancel.signal, ); } diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 87c757209da..4046953378a 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1903,8 +1903,11 @@ export class Subscriber { lister.abort(refused); return; } - // Each listed track holds an announces slot: discovery state the peer makes us hold. - const listed = new Set(); + // Each listed track holds an announces slot: discovery state the peer makes us hold. Each + // kind is a namespace apart. + const listedTracks = new Set(); + const listedDatagrams = new Set(); + const listed = (datagrams?: boolean) => (datagrams ? listedDatagrams : listedTracks); const unused = new AbortController(); const stop = AbortSignal.any([unused.signal, revoked.signal, this.#closed.signal]); const disposeWanted = lister.wanted.subscribe((wanted) => { @@ -1937,18 +1940,24 @@ export class Subscriber { return; } if (event.kind === "added") { - if (listed.has(event.name)) throw new ProtocolViolation(`track listed twice: ${event.name}`); + if (listed(event.datagrams).has(event.name)) + throw new ProtocolViolation(`track listed twice: ${event.name}`); if (!this.#announces.tryAcquire()) { throw new SessionError(SessionCode.TooManyRequests, { reason: "too many listed tracks" }); } - listed.add(event.name); - lister.add(event.name, this.#toModelInfo(event.info)); + listed(event.datagrams).add(event.name); + if (event.datagrams) { + const info = { priority: event.info.priority, timescale: event.info.timescale ?? null }; + lister.add(event.name, { datagrams: true, info }); + } else { + lister.add(event.name, { info: this.#toModelInfo(event.info) }); + } } else if (event.kind === "removed" || event.kind === "finished") { - if (!listed.delete(event.name)) + if (!listed(event.datagrams).delete(event.name)) throw new ProtocolViolation(`unlisted track removed: ${event.name}`); this.#announces.release(); - if (event.kind === "finished") lister.finish(event.name); - else lister.remove(event.name); + if (event.kind === "finished") lister.finish(event.name, event.datagrams); + else lister.remove(event.name, event.datagrams); } else { if (synced) throw new ProtocolViolation("duplicate SYNCED"); synced = true; @@ -1978,7 +1987,7 @@ export class Subscriber { } finally { disposeGrant?.(); disposeWanted(); - this.#announces.release(listed.size); + this.#announces.release(listedTracks.size + listedDatagrams.size); } } @@ -2409,7 +2418,7 @@ export class Subscriber { this.#legacyRequests.delete(state.legacyKey); const datagrams = request ? request.accept(info) - : wireOf(state.consumer).createDatagrams(producer.name, info); + : wireOf(state.consumer).createDatagrams(producer.name, info, false); entry.datagrams = { producer: datagrams, timescale: framing.scale }; entry.legacyKey = state.legacyKey; this.#datagrams.set(id, entry.datagrams); diff --git a/js/net/src/lite/tracks.test.ts b/js/net/src/lite/tracks.test.ts index 36f35d3a1de..fcbbfb40fbd 100644 --- a/js/net/src/lite/tracks.test.ts +++ b/js/net/src/lite/tracks.test.ts @@ -14,6 +14,7 @@ import { Reader, Stream, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; import type { Limits } from "../util/limits.ts"; import { wireOf } from "../wire.ts"; +import { DatagramsInfo } from "./datagram.ts"; import { Publisher } from "./publisher.ts"; import { StreamId } from "./stream.ts"; import { Subscriber } from "./subscriber.ts"; @@ -98,6 +99,47 @@ test("events and the request round-trip", async () => { expect(got.instance).toBe(instance); }); +test("a datagram track's events carry its kind ahead of its name", async () => { + const info = new DatagramsInfo({ priority: 0 }); + // Type, length, kind 1, name "a", then DATAGRAMS_INFO: length 2, priority 0x80, no timescale. + expect( + await bytes((w) => encodeTracksEvent(w, { kind: "added", name: "a", datagrams: true, info }, version)), + ).toEqual(new Uint8Array([0x00, 0x06, 0x01, 0x01, 0x61, 0x02, 0x80, 0x00])); + expect(await bytes((w) => encodeTracksEvent(w, { kind: "removed", name: "a", datagrams: true }, version))).toEqual( + new Uint8Array([0x01, 0x03, 0x01, 0x01, 0x61]), + ); + + const events: TracksEvent[] = [ + { + kind: "added", + name: "a", + datagrams: true, + info: new DatagramsInfo({ priority: -2, timescale: Timescale.MILLI }), + }, + { kind: "finished", name: "a", datagrams: true }, + { kind: "removed", name: "a", datagrams: true }, + ]; + const encoded = await bytes(async (w) => { + for (const event of events) await encodeTracksEvent(w, event, version); + }); + const reader = new Reader(undefined, encoded, version); + const added = await decodeTracksEventMaybe(reader, version); + expect(added).toMatchObject({ kind: "added", name: "a", datagrams: true, info: { priority: -2 } }); + expect(added?.kind === "added" && added.info.timescale).toBe(Timescale.MILLI); + expect(await decodeTracksEventMaybe(reader, version)).toEqual({ kind: "finished", name: "a", datagrams: true }); + expect(await decodeTracksEventMaybe(reader, version)).toEqual({ kind: "removed", name: "a", datagrams: true }); + + // Any kind but the two is malformed. + for (const typ of [0x00, 0x01, 0x02]) { + await expect( + decodeTracksEventMaybe( + new Reader(undefined, new Uint8Array([typ, 0x03, 0x02, 0x01, 0x61]), version), + version, + ), + ).rejects.toThrow("unknown listed track kind"); + } +}); + test("older versions have no tracks stream", async () => { await expect(bytes((w) => new TracksMessage(Path.from("room")).encode(w, Version.DRAFT_06))).rejects.toThrow( "not supported", @@ -155,8 +197,18 @@ test("a session forwards the peer's tracks as they arrive, and syncs when the pe await peer.send({ kind: "removed", name: "b" }); expect(await next(tracks)).toBe("-b"); + // A datagram track of a listed name is a track apart. + await peer.send({ kind: "added", name: "a", datagrams: true, info: new DatagramsInfo({ priority: 1 }) }); + expect(await tracks.next()).toEqual({ + kind: "added", + name: "a", + datagrams: true, + info: { priority: 1, timescale: null }, + }); await peer.send({ kind: "removed", name: "a" }); - expect(await next(tracks)).toBe("-a"); + expect(await tracks.next()).toEqual({ kind: "removed", name: "a" }); + await peer.send({ kind: "finished", name: "a", datagrams: true }); + expect(await tracks.next()).toEqual({ kind: "finished", name: "a", datagrams: true }); // The peer's broadcast ended: so does the listing, whether or not its retraction arrived. peer.stream.writer.close(); @@ -495,6 +547,15 @@ test("a listing over a session carries each track's info, end to end", async () expect(await next(tracks)).toBe("+b"); broadcast.removeTrack("a"); expect(await next(tracks)).toBe("-a"); + const datagrams = broadcast.createDatagrams("a", { timescale: Timescale.MILLI, priority: 3 }); + expect(await tracks.next()).toEqual({ + kind: "added", + name: "a", + datagrams: true, + info: { timescale: Timescale.MILLI, priority: 3 }, + }); + datagrams.finish(); + expect(await tracks.next()).toEqual({ kind: "finished", name: "a", datagrams: true }); broadcast.close(); expect(await next(tracks)).toBe("end"); client.abort(); diff --git a/js/net/src/lite/tracks.ts b/js/net/src/lite/tracks.ts index 3c25a629fb1..761d1a48008 100644 --- a/js/net/src/lite/tracks.ts +++ b/js/net/src/lite/tracks.ts @@ -3,6 +3,7 @@ import type * as Instance from "../instance.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import { decodeError } from "../util/decode_error.ts"; +import { DatagramsInfo } from "./datagram.ts"; import { decodeNode, decodePin, encodeNode, encodePin } from "./instance.ts"; import * as Message from "./message.ts"; import { TrackInfo } from "./track.ts"; @@ -14,6 +15,9 @@ const TRACKS_FINISH = 0x2; // The same event the announce stream marks its initial set with. const SYNCED = 0x4; +const KIND_TRACK = 0x0; +const KIND_DATAGRAMS = 0x1; + function guardTracks(version: Version) { if (!hasTracks(version)) throw new Error("tracks stream not supported for this version"); } @@ -59,16 +63,41 @@ export class Tracks { } /** - * One event the publisher sends on a Tracks Stream: TRACKS_ADD with the TRACK_INFO a Track - * Stream would answer, TRACKS_REMOVE for a track that left unfinished, TRACKS_FINISH for one that - * finished, or SYNCED once the listing's initial set was sent. + * A listed track's info on a Tracks Stream: the TRACK_INFO a Track Stream would answer, or with + * `datagrams`, the DATAGRAMS_INFO a Datagrams Stream would. + */ +export type Listed = { datagrams?: false; info: TrackInfo } | { datagrams: true; info: DatagramsInfo }; + +/** + * One event the publisher sends on a Tracks Stream: TRACKS_ADD with the listed track's kind and + * info, TRACKS_REMOVE for a track that left unfinished, TRACKS_FINISH for one that finished, or + * SYNCED once the listing's initial set was sent. A name is listed at most once per kind. */ export type TracksEvent = - | { kind: "added"; name: string; info: TrackInfo } - | { kind: "removed"; name: string } - | { kind: "finished"; name: string } + | ({ kind: "added"; name: string } & Listed) + | { kind: "removed"; name: string; datagrams?: boolean } + | { kind: "finished"; name: string; datagrams?: boolean } | { kind: "synced" }; +async function encodeKind(w: Writer, datagrams: boolean | undefined): Promise { + await w.u53(datagrams ? KIND_DATAGRAMS : KIND_TRACK); +} + +/** Whether the kind read next is a datagram track; any kind but the two is malformed. */ +async function decodeKind(r: Reader): Promise { + const kind = await r.u53(); + if (kind === KIND_TRACK) return false; + if (kind === KIND_DATAGRAMS) return true; + throw decodeError(new ProtocolViolation(`unknown listed track kind: ${kind}`)); +} + +/** A removal's body: its kind, then its name. */ +async function decodeRemoval(r: Reader): Promise<{ name: string; datagrams?: boolean }> { + const datagrams = await decodeKind(r); + const name = await r.string(); + return datagrams ? { name, datagrams } : { name }; +} + /** Write one {@link TracksEvent}: its type, then its size-prefixed body. */ export async function encodeTracksEvent(w: Writer, event: TracksEvent, version: Version): Promise { guardTracks(version); @@ -77,15 +106,22 @@ export async function encodeTracksEvent(w: Writer, event: TracksEvent, version: return Message.encode( w, async (w) => { + await encodeKind(w, event.datagrams); await w.string(event.name); await event.info.encode(w, version); }, { id: TRACKS_ADD }, ); case "removed": - return Message.encode(w, (w) => w.string(event.name), { id: TRACKS_REMOVE }); case "finished": - return Message.encode(w, (w) => w.string(event.name), { id: TRACKS_FINISH }); + return Message.encode( + w, + async (w) => { + await encodeKind(w, event.datagrams); + await w.string(event.name); + }, + { id: event.kind === "removed" ? TRACKS_REMOVE : TRACKS_FINISH }, + ); case "synced": return Message.encode(w, async () => {}, { id: SYNCED }); } @@ -98,14 +134,16 @@ export async function decodeTracksEventMaybe(r: Reader, version: Version): Promi const typ = await r.u53(); switch (typ) { case TRACKS_ADD: - return Message.decode(r, async (r) => { + return Message.decode(r, async (r): Promise => { + const datagrams = await decodeKind(r); const name = await r.string(); + if (datagrams) return { kind: "added", name, datagrams, info: await DatagramsInfo.decode(r, version) }; return { kind: "added", name, info: await TrackInfo.decode(r, version) }; }); case TRACKS_REMOVE: - return Message.decode(r, async (r) => ({ kind: "removed", name: await r.string() })); + return Message.decode(r, async (r) => ({ kind: "removed", ...(await decodeRemoval(r)) })); case TRACKS_FINISH: - return Message.decode(r, async (r) => ({ kind: "finished", name: await r.string() })); + return Message.decode(r, async (r) => ({ kind: "finished", ...(await decodeRemoval(r)) })); case SYNCED: return Message.decode(r, async () => ({ kind: "synced" })); default: diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 0d3531f56bc..cbe02f6fa66 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -3659,7 +3659,7 @@ test.each(["handed out", "buffered"])("an end below a group another copy %s leav test.each([ ["fails", (answer: Lister) => answer.abort(new Error("old route failed"))], ["ends", (answer: Lister) => answer.end()], - ["changes", (answer: Lister) => answer.add("gone", INFO)], + ["changes", (answer: Lister) => answer.add("gone", { info: INFO })], ])("a listing follows the source that took over as the old one's listing %s", async (_, end) => { const front = new Front(); const a = new BroadcastProducer(); @@ -3701,8 +3701,8 @@ test("a concluded front's listing keeps its closed source's finishes", async () const a = new BroadcastProducer(); const from = a.consume(); const answer = wireOf(from).lister(); - answer.add("seq", INFO); - answer.add("live", INFO); + answer.add("seq", { info: INFO }); + answer.add("live", { info: INFO }); answer.synced(); front.serve(from); const tracks = front.consumer.tracks(); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index ac9a55e89f7..2b89a0e8907 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -68,7 +68,7 @@ import { runGaps, } from "./internal.ts"; import { grace } from "./ledger.ts"; -import type { Lister, Tracks, TracksEvent } from "./listing.ts"; +import { keyOf, type Lister, type Tracks, type TracksEvent } from "./listing.ts"; import * as track from "./track.ts"; import { max, min, UNBOUNDED } from "./util/sequence.ts"; import { clamped, type Resolved, type Window } from "./window.ts"; @@ -1851,12 +1851,13 @@ export class Front { */ async #list(lister: Lister): Promise { const closed = this.consumer.closed; - // What the front lists, the source being read, and its pending next event. + // What the front lists, by kind and name, the source being read, and its pending next event. + type Named = { name: string; datagrams?: boolean }; let listing: | { - listed: Set; - /** Names an earlier source listed that the current one has yet to list. */ - stale: Set; + listed: Map; + /** Tracks an earlier source listed that the current one has yet to list. */ + stale: Map; source?: Source; reader?: Tracks; next?: Promise<{ event?: TracksEvent; err?: Error }>; @@ -1874,14 +1875,15 @@ export class Front { ); // Forwarded as the source reported it, finished or not. const unlist = ( - listed: Set, - stale: Set, - event: { kind: "removed" | "finished"; name: string }, + listed: Map, + stale: Map, + event: { kind: "removed" | "finished"; name: string; datagrams?: boolean }, ) => { - stale.delete(event.name); - if (!listed.delete(event.name)) return; - if (event.kind === "finished") lister.finish(event.name); - else lister.remove(event.name); + const key = keyOf(event.name, event.datagrams); + stale.delete(key); + if (!listed.delete(key)) return; + if (event.kind === "finished") lister.finish(event.name, event.datagrams); + else lister.remove(event.name, event.datagrams); }; try { for (;;) { @@ -1908,11 +1910,11 @@ export class Front { lister.end(); continue; } - listing ??= { listed: new Set(), stale: new Set() }; + listing ??= { listed: new Map(), stale: new Map() }; if (listing.source !== this.#source) { listing.reader?.close(); listing.source = this.#source; - listing.stale = new Set(listing.listed); + listing.stale = new Map(listing.listed); listing.next = undefined; try { listing.reader = this.#source?.wire.tracks(); @@ -1955,17 +1957,18 @@ export class Front { lister.end(); } } else if (event.kind === "added") { - if (!listing.stale.delete(event.name) && !listing.listed.has(event.name)) { - listing.listed.add(event.name); - lister.add(event.name, event.info); + const key = keyOf(event.name, event.datagrams); + if (!listing.stale.delete(key) && !listing.listed.has(key)) { + listing.listed.set(key, { name: event.name, datagrams: event.datagrams }); + lister.add(event.name, event); } } else if (event.kind === "removed" || event.kind === "finished") { unlist(listing.listed, listing.stale, event); } else { // What the new source still lacks at its SYNCED is gone. - for (const name of listing.stale) { - listing.listed.delete(name); - lister.remove(name); + for (const [key, { name, datagrams }] of listing.stale) { + listing.listed.delete(key); + lister.remove(name, datagrams); } listing.stale.clear(); lister.synced(); diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index cc41b68d359..67fc2fb2e63 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -25,7 +25,8 @@ export interface Broadcast { localDatagrams: boolean; datagrams(name: string): datagram.Consumer; liveDatagrams(name: string): datagram.Consumer | undefined; - createDatagrams(name: string, info: Partial): datagram.Producer; + /** Create a datagram track, listed unless `listed` is false, as a session's track riding a stream track's subscription. */ + createDatagrams(name: string, info: Partial, listed?: boolean): datagram.Producer; requestedDatagrams(): Promise; subscribe(name: string, options?: track.Subscription): track.Subscriber; /** The track's properties; `hold` keeps the track wanted until it aborts, the way a held TRACK stream does, and aborting it before the answer abandons the lookup. */ diff --git a/js/stats/src/consumer.ts b/js/stats/src/consumer.ts index 963affaebda..dbf9fb4d357 100644 --- a/js/stats/src/consumer.ts +++ b/js/stats/src/consumer.ts @@ -170,6 +170,8 @@ export class BucketReader { this.close(); return undefined; } + // Buckets are tracks of groups, so a datagram track of the same name is not one. + if (event.kind === "synced" || event.datagrams) continue; if (event.kind === "added" && parseBucketTrack(event.name)?.bucket === this.#bucket) { // A newer run supersedes the current one. if (this.#run) this.#end(this.#run); diff --git a/rs/moq-archive/src/producer/mod.rs b/rs/moq-archive/src/producer/mod.rs index ed2c2f91e68..31f1a7605ec 100644 --- a/rs/moq-archive/src/producer/mod.rs +++ b/rs/moq-archive/src/producer/mod.rs @@ -37,7 +37,7 @@ use std::time::Duration; use futures::future::BoxFuture; use futures::stream::FuturesUnordered; use futures::{FutureExt, StreamExt}; -use moq_net::broadcast::TracksEvent; +use moq_net::broadcast::{Listed, TracksEvent}; use moq_net::{StreamError, broadcast}; use object_store::{ObjectStore, ObjectStoreExt, PutPayload}; @@ -182,7 +182,10 @@ impl Producer { .await; match event { - Event::Listed(Ok(Some(TracksEvent::Added { name, info }))) => { + Event::Listed(Ok(Some(TracksEvent::Added { + name, + info: Listed::Track(info), + }))) => { let queue = queues.entry(name.to_string()).or_insert_with(|| { let queue = kio::Queue::new(); let record = track::record( @@ -200,8 +203,15 @@ impl Producer { // Only fails once closed, which happens when the listing ends. let _ = queue.try_push(info); } + // A datagram track is never cached, so there is nothing of it to archive. Event::Listed(Ok(Some( - TracksEvent::Synced | TracksEvent::Removed { .. } | TracksEvent::Finished { .. }, + TracksEvent::Added { + info: Listed::Datagrams(_), + .. + } + | TracksEvent::Synced + | TracksEvent::Removed { .. } + | TracksEvent::Finished { .. }, ))) => {} Event::Listed(Ok(None)) => { listing = None; diff --git a/rs/moq-crypto/src/e2ee/broadcast.rs b/rs/moq-crypto/src/e2ee/broadcast.rs index b0a7e7de51a..eab76f654d9 100644 --- a/rs/moq-crypto/src/e2ee/broadcast.rs +++ b/rs/moq-crypto/src/e2ee/broadcast.rs @@ -249,36 +249,37 @@ impl Lister { self.inner.poll_unwanted(waiter).map_err(Error::Net) } - /// List the track for `semantic`. + /// List the track for `semantic`, of the kind `info` is: a [`moq_net::track::Info`] or a + /// [`moq_net::datagram::Info`]. /// /// # Errors /// /// [`Error::Identity`] if `semantic` exceeds 65535 bytes, or [`moq_net::Error::Duplicate`] - /// if this answer already lists it. - pub fn add(&self, semantic: &str, info: moq_net::track::Info) -> Result<()> { + /// if this answer already lists that kind and name. + pub fn add(&self, semantic: &str, info: impl Into) -> Result<()> { let name = self.generation.name(semantic)?; Ok(self.inner.add(name.as_str(), info)?) } - /// Stop listing the track for `semantic`, which left unfinished. + /// Stop listing the track of `kind` for `semantic`, which left unfinished. /// /// # Errors /// /// [`Error::Identity`] if `semantic` exceeds 65535 bytes, or [`moq_net::Error::NotFound`] - /// if this answer does not list it. - pub fn remove(&self, semantic: &str) -> Result<()> { + /// if this answer does not list that kind and name. + pub fn remove(&self, kind: moq_net::broadcast::Kind, semantic: &str) -> Result<()> { let name = self.generation.name(semantic)?; - Ok(self.inner.remove(name.as_str())?) + Ok(self.inner.remove(kind, name.as_str())?) } - /// Stop listing the track for `semantic`, which finished. + /// Stop listing the track of `kind` for `semantic`, which finished. /// /// # Errors /// /// Same as [`Self::remove`]. - pub fn finish(&self, semantic: &str) -> Result<()> { + pub fn finish(&self, kind: moq_net::broadcast::Kind, semantic: &str) -> Result<()> { let name = self.generation.name(semantic)?; - Ok(self.inner.finish(name.as_str())?) + Ok(self.inner.finish(kind, name.as_str())?) } /// The answer holds everything this hop knows now; later changes are live. diff --git a/rs/moq-crypto/src/e2ee/tests.rs b/rs/moq-crypto/src/e2ee/tests.rs index 464ef24f614..b1e47e80f9a 100644 --- a/rs/moq-crypto/src/e2ee/tests.rs +++ b/rs/moq-crypto/src/e2ee/tests.rs @@ -1004,6 +1004,8 @@ fn datagram_requests_serve_issued_names() { #[test] fn lister_lists_physical_names() { + use moq_net::broadcast::Kind; + let protected = protected(); let requests = protected.producer.requests(); let lister = requests.lister().unwrap(); @@ -1028,15 +1030,28 @@ fn lister_lists_physical_names() { ); assert!(matches!(next(&mut tracks), moq_net::broadcast::TracksEvent::Synced)); - lister.finish("stats/viewers").unwrap(); + lister.finish(Kind::Track, "stats/viewers").unwrap(); assert!(matches!( next(&mut tracks), - moq_net::broadcast::TracksEvent::Finished { name: finished } if finished == name + moq_net::broadcast::TracksEvent::Finished { kind: Kind::Track, name: finished } if finished == name )); assert!(matches!( - lister.remove("stats/viewers"), + lister.remove(Kind::Track, "stats/viewers"), Err(Error::Net(moq_net::Error::NotFound)) )); + + // A datagram track of the same semantic name lists under the same physical name. + lister.add("stats/viewers", moq_net::datagram::Info::default()).unwrap(); + assert!(matches!( + next(&mut tracks), + moq_net::broadcast::TracksEvent::Added { name: listed, info: moq_net::broadcast::Listed::Datagrams(_) } + if listed == name + )); + lister.remove(Kind::Datagrams, "stats/viewers").unwrap(); + assert!(matches!( + next(&mut tracks), + moq_net::broadcast::TracksEvent::Removed { kind: Kind::Datagrams, name: removed } if removed == name + )); // Listing claims nothing: only serving a name does. assert_eq!(protected.producer.generation().claims(), 0); } diff --git a/rs/moq-net/src/ietf/subscriber/datagrams.rs b/rs/moq-net/src/ietf/subscriber/datagrams.rs index e0c9e41ba66..45f5b0fdc8d 100644 --- a/rs/moq-net/src/ietf/subscriber/datagrams.rs +++ b/rs/moq-net/src/ietf/subscriber/datagrams.rs @@ -108,7 +108,7 @@ impl Shared { let pending = this.state.lock().datagram_requests.remove(&key); let producer = match pending { Some((_, request)) => request.accept(info), - None => source.create_datagrams(key.1, info).ok()?, + None => source.create_unlisted_datagrams(key.1, info).ok()?, }; Some(Self { producer, diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index ff282d90eb2..7fb0d6b1be2 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -270,9 +270,10 @@ impl Listings { }; if entry.info.is_some() { for lister in self.listers(&key.0) { + // Moq-transport has no datagram tracks to list. let _ = match finished { - true => lister.finish(&key.1), - false => lister.remove(&key.1), + true => lister.finish(broadcast::Kind::Track, key.1.clone()), + false => lister.remove(broadcast::Kind::Track, key.1.clone()), }; } } @@ -1884,8 +1885,8 @@ mod tests { fn event(tracks: &mut crate::broadcast::Tracks) -> Option { match tracks.poll_next(&kio::Waiter::noop()) { Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Added { name, .. }))) => Some(format!("+{name}")), - Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Removed { name }))) => Some(format!("-{name}")), - Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Finished { name }))) => Some(format!("~{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Removed { name, .. }))) => Some(format!("-{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Finished { name, .. }))) => Some(format!("~{name}")), Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Synced))) => Some("synced".into()), Poll::Ready(other) => Some(format!("{other:?}")), Poll::Pending => None, diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index 85a1d4ad8ba..765ee77a0ba 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -1153,7 +1153,10 @@ mod hop_tests { let mut tracks = broadcast.tracks().unwrap(); let listed = loop { match kio::clock::timeout(TIMEOUT, tracks.next()).await.unwrap().unwrap() { - Some(crate::broadcast::TracksEvent::Added { name, info }) if &*name == "video" => break info, + Some(crate::broadcast::TracksEvent::Added { + name, + info: crate::broadcast::Listed::Track(info), + }) if &*name == "video" => break info, Some(_) => continue, None => panic!("listing ended before the track"), } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f60f510f90d..f9dca3e66cc 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2330,12 +2330,19 @@ impl Request for TracksServe { let event = match ready!(self.tracks.poll_next(waiter))? { Some(crate::broadcast::TracksEvent::Added { name, info }) => lite::TracksEvent::Added { name: name.to_string().into(), - info: lite::TrackInfo::serve(&info, shared.version), + info: match info { + crate::broadcast::Listed::Track(info) => { + lite::Listed::Track(lite::TrackInfo::serve(&info, shared.version)) + } + crate::broadcast::Listed::Datagrams(info) => lite::Listed::Datagrams(info.into()), + }, }, - Some(crate::broadcast::TracksEvent::Removed { name }) => lite::TracksEvent::Removed { + Some(crate::broadcast::TracksEvent::Removed { kind, name }) => lite::TracksEvent::Removed { + kind, name: name.to_string().into(), }, - Some(crate::broadcast::TracksEvent::Finished { name }) => lite::TracksEvent::Finished { + Some(crate::broadcast::TracksEvent::Finished { kind, name }) => lite::TracksEvent::Finished { + kind, name: name.to_string().into(), }, Some(crate::broadcast::TracksEvent::Synced) => lite::TracksEvent::Synced, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 2dcfa8c5857..f00234ad6a9 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -3039,9 +3039,9 @@ struct TracksRecv { open: crate::transport::open::Open, session: Transport, stream: Option>, - /// What the peer lists, each holding an `announces` slot: discovery state the peer - /// makes us hold. - listed: HashMap, crate::session::Slot>, + /// What the peer lists, by kind then name, each holding an `announces` slot: discovery + /// state the peer makes us hold. + listed: TracksListed, synced: bool, /// Each event fans out to every reader, so a peer streaming add/remove churn must not /// hold the thread for as long as its bytes keep arriving. @@ -3055,22 +3055,42 @@ struct TracksRecv { unanswered: Option, } +/// The tracks a peer lists, one map per kind since each kind is a namespace apart. +#[derive(Default)] +struct TracksListed { + tracks: HashMap, crate::session::Slot>, + datagrams: HashMap, crate::session::Slot>, +} + +impl TracksListed { + fn of(&mut self, kind: crate::broadcast::Kind) -> &mut HashMap, crate::session::Slot> { + match kind { + crate::broadcast::Kind::Track => &mut self.tracks, + crate::broadcast::Kind::Datagrams => &mut self.datagrams, + } + } + + /// The key listed for `name` of `kind`, shared rather than copied. + fn known(&self, kind: crate::broadcast::Kind, name: &str) -> Option> { + let listed = match kind { + crate::broadcast::Kind::Track => &self.tracks, + crate::broadcast::Kind::Datagrams => &self.datagrams, + }; + listed.get_key_value(name).map(|(name, _)| name.clone()) + } +} + /// A TRACKS event, with its name resolved against what the listing holds. #[derive(Debug)] enum Listing { - Added(Arc, lite::TrackInfo), - /// The listed name, or `None` if nothing by that name is listed. - Removed(Option>), + Added(Arc, lite::Listed), + /// The listed name of that kind, or `None` if nothing of that kind and name is listed. + Removed(crate::broadcast::Kind, Option>), /// Like [`Self::Removed`]. - Finished(Option>), + Finished(crate::broadcast::Kind, Option>), Synced, } -/// The key `listed` holds for `name`, shared rather than copied. -fn known(listed: &HashMap, crate::session::Slot>, name: &str) -> Option> { - listed.get_key_value(name).map(|(name, _)| name.clone()) -} - impl TracksRecv { /// Apply the peer's events until it ends the listing, or the error that ends it. fn poll(&mut self, source: &SourceServe, waiter: &kio::Waiter) -> Poll> { @@ -3108,8 +3128,8 @@ impl TracksRecv { let event = ready!(stream.reader.poll_decode_maybe_with(waiter, |r| { Ok(match lite::TracksEvent::decode(r, version)? { lite::TracksEvent::Added { name, info } => Listing::Added(name.as_ref().into(), info), - lite::TracksEvent::Removed { name } => Listing::Removed(known(listed, &name)), - lite::TracksEvent::Finished { name } => Listing::Finished(known(listed, &name)), + lite::TracksEvent::Removed { kind, name } => Listing::Removed(kind, listed.known(kind, &name)), + lite::TracksEvent::Finished { kind, name } => Listing::Finished(kind, listed.known(kind, &name)), lite::TracksEvent::Synced => Listing::Synced, }) }))?; @@ -3119,22 +3139,26 @@ impl TracksRecv { }; match event { Listing::Added(name, info) => { - if self.listed.contains_key(&name) { + let listed = self.listed.of(info.kind()); + if listed.contains_key(&name) { return Poll::Ready(Err(Error::ProtocolViolation)); } let slot = source.subscriber.announces.acquire()?; - source.lister.add(name.clone(), info.into())?; - self.listed.insert(name, slot); + match info { + lite::Listed::Track(info) => source.lister.add(name.clone(), crate::track::Info::from(info))?, + lite::Listed::Datagrams(info) => source.lister.add(name.clone(), datagram::Info::from(info))?, + } + listed.insert(name, slot); } - Listing::Removed(name) => { + Listing::Removed(kind, name) => { let name = name.ok_or(Error::ProtocolViolation)?; - self.listed.remove(&name); - source.lister.remove(&name)?; + self.listed.of(kind).remove(&name); + source.lister.remove(kind, name)?; } - Listing::Finished(name) => { + Listing::Finished(kind, name) => { let name = name.ok_or(Error::ProtocolViolation)?; - self.listed.remove(&name); - source.lister.finish(&name)?; + self.listed.of(kind).remove(&name); + source.lister.finish(kind, name)?; } Listing::Synced => { if std::mem::replace(&mut self.synced, true) { @@ -3192,7 +3216,7 @@ impl SourceServe { open: Default::default(), session: self.subscriber.session.clone(), stream: None, - listed: HashMap::new(), + listed: TracksListed::default(), synced: false, budget: kio::coop::Budget::new(32), gate: crate::auth::Gate::new( @@ -12692,7 +12716,7 @@ impl SharedDatagrams { let producer = serve .source .as_ref()? - .create_datagrams(serve.name.as_str(), info) + .create_unlisted_datagrams(serve.name.as_str(), info) .ok()?; let key = (serve.path.clone(), serve.name.clone()); serve.subscriber.legacy_datagrams.lock().insert( diff --git a/rs/moq-net/src/lite/tracks.rs b/rs/moq-net/src/lite/tracks.rs index bebd2296387..09b65e21546 100644 --- a/rs/moq-net/src/lite/tracks.rs +++ b/rs/moq-net/src/lite/tracks.rs @@ -2,10 +2,11 @@ use std::borrow::Cow; use crate::{ Path, + broadcast::Kind, coding::{Decode, DecodeError, Decoder, Encode, EncodeError, Encoder}, }; -use super::{Message, TrackInfo, Version, message::MAX_MESSAGE_SIZE, message::decode_size}; +use super::{DatagramsInfo, Message, TrackInfo, Version, message::MAX_MESSAGE_SIZE, message::decode_size}; const TRACKS_ADD: u64 = 0x0; const TRACKS_REMOVE: u64 = 0x1; @@ -13,6 +14,9 @@ const TRACKS_FINISH: u64 = 0x2; // The same event the announce stream marks its initial set with. const SYNCED: u64 = 0x4; +const KIND_TRACK: u64 = 0x0; +const KIND_DATAGRAMS: u64 = 0x1; + /// Sent by the subscriber on a Tracks Stream (0x8) to list one broadcast's tracks. /// /// Lite07+ only. @@ -56,18 +60,54 @@ impl<'a> Message<'a> for Tracks { } } +/// A listed track's info on a Tracks Stream, whose variant is its kind: what the request +/// for that kind of track would answer. +#[derive(Clone, Debug)] +pub enum Listed { + /// A track of groups, with the TRACK_INFO a Track Stream would answer. + Track(TrackInfo), + /// A datagram track, with the DATAGRAMS_INFO a Datagrams Stream would answer. + Datagrams(DatagramsInfo), +} + +impl Listed { + /// The kind of track this info is for. + pub fn kind(&self) -> Kind { + match self { + Self::Track(_) => Kind::Track, + Self::Datagrams(_) => Kind::Datagrams, + } + } +} + +fn encode_kind(w: &mut Encoder<'_>, kind: Kind) -> Result<(), EncodeError> { + w.varint(match kind { + Kind::Track => KIND_TRACK, + Kind::Datagrams => KIND_DATAGRAMS, + }) +} + +fn decode_kind(r: &mut Decoder<'_>) -> Result { + match r.varint()? { + KIND_TRACK => Ok(Kind::Track), + KIND_DATAGRAMS => Ok(Kind::Datagrams), + _ => Err(DecodeError::InvalidValue), + } +} + /// One event the publisher sends on a Tracks Stream, each a type, then a size-prefixed body. +/// A name is listed at most once per kind. /// /// Lite07+ only. #[derive(Clone, Debug)] pub enum TracksEvent<'a> { - /// TRACKS_ADD: a listed track, with the TRACK_INFO a Track Stream would answer. - Added { name: Cow<'a, str>, info: TrackInfo }, + /// TRACKS_ADD: a listed track, with its kind and info. + Added { name: Cow<'a, str>, info: Listed }, /// TRACKS_REMOVE: a track named by an earlier TRACKS_ADD is no longer listed, unfinished. - Removed { name: Cow<'a, str> }, + Removed { kind: Kind, name: Cow<'a, str> }, /// TRACKS_FINISH: a track named by an earlier TRACKS_ADD is no longer listed because it /// finished. - Finished { name: Cow<'a, str> }, + Finished { kind: Kind, name: Cow<'a, str> }, /// SYNCED: every track this hop listed when the stream opened, and still lists, was sent. Synced, } @@ -87,10 +127,17 @@ impl Encode for TracksEvent<'_> { let prefix = w.prefix_varint(); match self { Self::Added { name, info } => { + encode_kind(w, info.kind())?; + w.string(name)?; + match info { + Listed::Track(info) => info.encode(w, version)?, + Listed::Datagrams(info) => info.encode(w, version)?, + } + } + Self::Removed { kind, name } | Self::Finished { kind, name } => { + encode_kind(w, *kind)?; w.string(name)?; - info.encode(w, version)?; } - Self::Removed { name } | Self::Finished { name } => w.string(name)?, Self::Synced => {} } if w.since(&prefix) > MAX_MESSAGE_SIZE { @@ -113,14 +160,21 @@ impl<'a> Decode<'a, Version> for TracksEvent<'a> { // The body is complete, so running short inside it is malformed, not a wait for more. let msg = (|| { Ok(match typ { - TRACKS_ADD => Self::Added { - name: Cow::Borrowed(body.str()?), - info: TrackInfo::decode(&mut body, version)?, - }, + TRACKS_ADD => { + let kind = decode_kind(&mut body)?; + let name = Cow::Borrowed(body.str()?); + let info = match kind { + Kind::Track => Listed::Track(TrackInfo::decode(&mut body, version)?), + Kind::Datagrams => Listed::Datagrams(DatagramsInfo::decode(&mut body, version)?), + }; + Self::Added { name, info } + } TRACKS_REMOVE => Self::Removed { + kind: decode_kind(&mut body)?, name: Cow::Borrowed(body.str()?), }, TRACKS_FINISH => Self::Finished { + kind: decode_kind(&mut body)?, name: Cow::Borrowed(body.str()?), }, SYNCED => Self::Synced, @@ -150,10 +204,12 @@ mod test { name: name.into_owned().into(), info, }, - TracksEvent::Removed { name } => TracksEvent::Removed { + TracksEvent::Removed { kind, name } => TracksEvent::Removed { + kind, name: name.into_owned().into(), }, - TracksEvent::Finished { name } => TracksEvent::Finished { + TracksEvent::Finished { kind, name } => TracksEvent::Finished { + kind, name: name.into_owned().into(), }, TracksEvent::Synced => TracksEvent::Synced, @@ -169,10 +225,14 @@ mod test { timescale: Some(Timescale::MICRO), compression: crate::track::Compression::Deflate, }; - let TracksEvent::Added { name, info: got } = roundtrip(&TracksEvent::Added { + let TracksEvent::Added { + name, + info: Listed::Track(got), + } = roundtrip(&TracksEvent::Added { name: "video".into(), - info, - }) else { + info: Listed::Track(info), + }) + else { panic!("expected an add"); }; assert_eq!(name, "video"); @@ -182,17 +242,79 @@ mod test { assert_eq!(got.timescale, Some(Timescale::MICRO)); assert_eq!(got.compression, crate::track::Compression::Deflate); - let TracksEvent::Finished { name } = roundtrip(&TracksEvent::Finished { name: "audio".into() }) else { - panic!("expected TRACKS_FINISH"); + let datagrams = DatagramsInfo { + priority: -2, + timescale: Some(Timescale::MILLI), }; - assert_eq!(name, "audio"); - let TracksEvent::Removed { name } = roundtrip(&TracksEvent::Removed { name: "video".into() }) else { - panic!("expected a removal"); + let TracksEvent::Added { + name, + info: Listed::Datagrams(got), + } = roundtrip(&TracksEvent::Added { + name: "video".into(), + info: Listed::Datagrams(datagrams), + }) + else { + panic!("expected a datagram track"); }; assert_eq!(name, "video"); + assert_eq!(got, datagrams); + + for kind in [Kind::Track, Kind::Datagrams] { + let TracksEvent::Finished { kind: got, name } = roundtrip(&TracksEvent::Finished { + kind, + name: "audio".into(), + }) else { + panic!("expected TRACKS_FINISH"); + }; + assert_eq!((got, &*name), (kind, "audio")); + let TracksEvent::Removed { kind: got, name } = roundtrip(&TracksEvent::Removed { + kind, + name: "video".into(), + }) else { + panic!("expected a removal"); + }; + assert_eq!((got, &*name), (kind, "video")); + } assert!(matches!(roundtrip(&TracksEvent::Synced), TracksEvent::Synced)); } + /// Each event names its kind ahead of the track's name: TRACKS_ADD of a datagram track + /// is the kind, the name, then a DATAGRAMS_INFO with its own length. + #[test] + fn the_kind_leads_each_listed_track() { + let added = TracksEvent::Added { + name: "a".into(), + info: Listed::Datagrams(DatagramsInfo { + priority: 0, + timescale: None, + }), + }; + // Type, length, kind 1, name "a", then DATAGRAMS_INFO: length 2, priority 0x80, no timescale. + assert_eq!( + added.encode_bytes(Version::Lite07).unwrap(), + &[0x00u8, 0x06, 0x01, 0x01, b'a', 0x02, 0x80, 0x00][..] + ); + let removed = TracksEvent::Removed { + kind: Kind::Datagrams, + name: "a".into(), + }; + assert_eq!( + removed.encode_bytes(Version::Lite07).unwrap(), + &[0x01u8, 0x03, 0x01, 0x01, b'a'][..] + ); + } + + /// A kind other than a track or a datagram track is malformed. + #[test] + fn an_unknown_kind_is_refused() { + for typ in [0x00u8, 0x01, 0x02] { + assert!(matches!( + TracksEvent::decode_slice(&[typ, 0x03, 0x02, 0x01, b'a'], Version::Lite07), + Err(DecodeError::InvalidValue) + )); + } + } + #[test] fn synced_is_an_empty_type_four() { assert_eq!( diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 5d5b5f0565b..a9ee366becc 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -26,8 +26,8 @@ mod listing; // Sessions dedup a peer's listings per broadcast; a custom session has no public owner yet. #[cfg(feature = "async")] pub(crate) use listing::Owner; +pub use listing::{Kind, Listed, Lister, Tracks, TracksEvent}; pub(super) use listing::{ListOnAccept, Unlist}; -pub use listing::{Lister, Tracks, TracksEvent}; /// A collection of media tracks that can be published and subscribed to. /// @@ -329,17 +329,17 @@ impl Producer { // live same-name entry cannot exist (its presence would have kept // the request from queuing). let _ = state.cache_track(track.weak()); - let unlist = Unlist::list(&self.state, &mut state.listing, name, &info); + let unlist = Unlist::list(&self.state, &mut state.listing, name, Listed::Track(info)); return Ok(track.listed(unlist)); } let track = track::Producer::new(self.info.clone(), name.clone(), info.clone()).with_stats(self.stats.clone()); state.insert_track(track.weak())?; - let unlist = Unlist::list(&self.state, &mut state.listing, name, &info); + let unlist = Unlist::list(&self.state, &mut state.listing, name, Listed::Track(info)); Ok(track.listed(unlist)) } - /// Produce a new datagram track and insert it into the broadcast. + /// Produce a new datagram track and insert it into the broadcast, listed until it ends. /// /// Datagram tracks are a namespace apart from stream tracks, so this never conflicts with /// [`Self::create_track`]. Fails with [`Error::Duplicate`] while a live datagram track @@ -353,24 +353,53 @@ impl Producer { name: impl Into>, info: datagram::Info, ) -> Result { - let name = name.into(); + self.insert_datagrams(name.into(), info, true) + } + + /// [`Self::create_datagrams`] for a track no listing ever names, as a session's datagram + /// track riding a stream track's subscription, which serves a request rather than the + /// broadcast's inventory. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn create_unlisted_datagrams( + &self, + name: impl Into>, + info: datagram::Info, + ) -> Result { + self.insert_datagrams(name.into(), info, false) + } + + fn insert_datagrams( + &self, + name: Arc, + info: datagram::Info, + listed: bool, + ) -> Result { let mut state = self.state.lock(); - if let Some(live) = state.datagrams.get(name.as_ref()) { - // A consumer asked for it before it existed, and no handler took the request yet: - // creating the track serves those consumers. - let queued = state - .datagram_requests - .iter() - .position(|request| live.same_channel(&request.weak())); - let Some(queued) = queued else { - return Err(Error::Duplicate); - }; - let request = state.datagram_requests.remove(queued).expect("found above"); - return Ok(request.with_stats(self.stats.clone()).accept(info)); + let producer = match state.datagrams.get(name.as_ref()) { + Some(live) => { + // A consumer asked for it before it existed, and no handler took the request + // yet: creating the track serves those consumers. + let queued = state + .datagram_requests + .iter() + .position(|request| live.same_channel(&request.weak())); + let Some(queued) = queued else { + return Err(Error::Duplicate); + }; + let request = state.datagram_requests.remove(queued).expect("found above"); + request.with_stats(self.stats.clone()).accept(info) + } + None => { + let producer = datagram::Producer::new(name.clone(), Some(info)).with_stats(self.stats.clone()); + state.datagrams.insert(name.clone(), producer.weak()); + producer + } + }; + if !listed { + return Ok(producer); } - let producer = datagram::Producer::new(name.clone(), Some(info)).with_stats(self.stats.clone()); - state.datagrams.insert(name, producer.weak()); - Ok(producer) + let unlist = Unlist::list(&self.state, &mut state.listing, name, Listed::Datagrams(info)); + Ok(producer.listed(unlist)) } /// Answer datagram lookups from `source`, the broadcast an origin's front serves from, diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index c901bd30841..fe40023961f 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -9,7 +9,8 @@ //! [`broadcast::Producer::create_datagrams`](crate::broadcast::Producer::create_datagrams), //! and a reader asks for a [`Consumer`] with //! [`broadcast::Consumer::datagrams`](crate::broadcast::Consumer::datagrams). A consumer -//! is live from when it is created: it never receives a datagram written before it. +//! is live from when it is created: it never receives a datagram written before it. A +//! created track is in the broadcast's [listing](crate::broadcast::Tracks) until it ends. //! //! Delivery is best-effort per hop: a session drops (with a debug log) any datagram whose //! encoded body exceeds the transport's datagram size, and sessions that can't carry @@ -40,7 +41,7 @@ use std::{ use bytes::Bytes; -use crate::{Error, Result, Timescale, Timestamp, stats}; +use crate::{Error, Result, Timescale, Timestamp, broadcast, stats}; /// Hard ceiling on a datagram payload, matching the QUIC DATAGRAM frame limit. /// @@ -142,6 +143,8 @@ struct State { producers: usize, // Each live consumer's priority, or None for passive forwarding over an existing stream. priorities: slab::Slab>, + // The broadcast's listing of a track its producer created, withdrawn once the track ends. + listed: Option, } impl State { @@ -167,10 +170,14 @@ impl State { self.buffer.push_back(datagram); } - fn end(&mut self, end: Result<()>) { + /// End the track, returning its listing to withdraw once this lock is released, since + /// the broadcast's lock is taken first. + #[must_use = "drop the listing after releasing the lock"] + fn end(&mut self, end: Result<()>) -> Option { if self.end.is_some() { - return; + return None; } + let finished = end.is_ok(); // A finish leaves what is buffered for the consumers already reading; an error // ends the track at once, so nobody reads what is left. let unread = end.is_err() || self.priorities.is_empty(); @@ -178,6 +185,7 @@ impl State { if unread { self.release(); } + self.listed.take().map(|listed| listed.finished(finished)) } /// Drop what is buffered: nobody can read it any more. A consumer joining later starts @@ -264,6 +272,12 @@ impl Producer { self } + /// Keep the track in its broadcast's listing until it ends. Called under the broadcast's lock. + pub(super) fn listed(self, unlist: broadcast::Unlist) -> Self { + self.state.lock().listed = Some(unlist); + self + } + pub(super) fn weak(&self) -> Weak { Weak { name: self.name.clone(), @@ -341,12 +355,14 @@ impl Producer { /// End the track cleanly: consumers read `None` once they have read what is buffered. pub fn finish(self) { - self.state.lock().end(Ok(())); + let unlist = self.state.lock().end(Ok(())); + drop(unlist); } /// End the track with an error. pub fn abort(self, err: Error) { - self.state.lock().end(Err(err)); + let unlist = self.state.lock().end(Err(err)); + drop(unlist); } /// The highest subscriber priority among the track's consumers, or `None` when it has none. @@ -397,7 +413,9 @@ impl Producer { if !state.priorities.is_empty() { return false; } - state.end(Err(Error::Cancel)); + let unlist = state.end(Err(Error::Cancel)); + drop(state); + drop(unlist); true } @@ -426,7 +444,9 @@ impl Drop for Producer { let mut state = self.state.lock(); state.producers -= 1; if state.producers == 0 { - state.end(Err(Error::Dropped)); + let unlist = state.end(Err(Error::Dropped)); + drop(state); + drop(unlist); } } } @@ -673,7 +693,11 @@ impl Drop for Consumer { // Nobody waits for a request no handler accepted yet: withdraw it, so a handler // that stops polling never holds requests nobody reads. if state.priorities.is_empty() && state.info.is_none() { - state.end(Err(Error::Cancel)); + let unlisted = state.end(Err(Error::Cancel)); + debug_assert!( + unlisted.is_none(), + "only a created track is listed, and it has its info" + ); } // The last reader of a finished track leaves what it never read. if state.priorities.is_empty() && state.end.is_some() { diff --git a/rs/moq-net/src/model/listing.rs b/rs/moq-net/src/model/listing.rs index 668ee4e2149..233f50a46e6 100644 --- a/rs/moq-net/src/model/listing.rs +++ b/rs/moq-net/src/model/listing.rs @@ -1,14 +1,17 @@ //! A broadcast's track listing: the tracks it lists, reported to each reader in order. //! //! A track is listed while it is in the broadcast's inventory: created by its -//! [`Producer`](super::Producer) (until it leaves the track table), or answered by a -//! handler through a [`Lister`], as a relay's copy lists its upstream's tracks. A track -//! served only on request is never listed, and listing never requests one. +//! [`Producer`](super::Producer) (a track of groups until it leaves the track table, a +//! datagram track until it ends), or answered by a handler through a [`Lister`], as a +//! relay's copy lists its upstream's tracks. A track served only on request is never +//! listed, and listing never requests one. //! -//! Each [`Tracks`] reader keeps its own queue, keyed by name in insertion order, so a -//! stalled reader holds at most one pending change per name: an add and a removal it -//! has not reached cancel, and a removal and re-add of a name it saw collapse in place. -//! Its state is bounded by the names it saw plus the live set, however long it stalls. +//! The two [`Kind`]s are namespaces apart, so a name is listed at most once per kind. +//! +//! Each [`Tracks`] reader keeps its own queue, keyed by kind and name in insertion order, so +//! a stalled reader holds at most one pending change per listed track: an add and a removal +//! it has not reached cancel, and a removal and re-add of a track it saw collapse in place. +//! Its state is bounded by the tracks it saw plus the live set, however long it stalls. use std::{ sync::Arc, @@ -21,17 +24,60 @@ use std::sync::atomic::{AtomicU64, Ordering}; use hashlink::LinkedHashMap; use super::{BroadcastState, Consumer}; -use crate::{Error, track}; +use crate::{Error, datagram, track}; + +/// Which of a broadcast's two namespaces a listed track is in. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Kind { + /// A track of groups, read through [`Consumer::track`]. + Track, + /// A datagram track, read through [`Consumer::datagrams`]. + Datagrams, +} + +/// A listed track's fixed properties, whose variant is its [`Kind`]. +#[derive(Clone, Debug)] +pub enum Listed { + /// A track of groups, with the properties its TRACK_INFO carries. + Track(track::Info), + /// A datagram track, with the properties its DATAGRAMS_INFO carries. + Datagrams(datagram::Info), +} + +impl Listed { + /// The namespace the track is in. + pub fn kind(&self) -> Kind { + match self { + Self::Track(_) => Kind::Track, + Self::Datagrams(_) => Kind::Datagrams, + } + } +} + +impl From for Listed { + fn from(info: track::Info) -> Self { + Self::Track(info) + } +} + +impl From for Listed { + fn from(info: datagram::Info) -> Self { + Self::Datagrams(info) + } +} + +/// A listed track's identity: a name is unique within its kind. +type Key = (Kind, Arc); /// What a [`Tracks`] listing reports, in order. #[derive(Clone, Debug)] pub enum TracksEvent { - /// A track the broadcast lists, with its fixed properties. + /// A track the broadcast lists, with its kind and fixed properties. Added { - /// The track's name, unique among the broadcast's listed tracks. + /// The track's name, unique among the broadcast's listed tracks of its kind. name: Arc, - /// The track's properties, the same its TRACK_INFO carries. - info: track::Info, + /// The track's kind and properties. + info: Listed, }, /// Every track this hop listed when the listing began, and still lists, has been /// reported. Sent once; later events are live. @@ -40,12 +86,16 @@ pub enum TracksEvent { /// declaring its end, or the route or handler that listed it withdrew. A handler may still /// serve its name on request. Removed { + /// The kind an earlier [`Self::Added`] reported. + kind: Kind, /// The name an earlier [`Self::Added`] reported. name: Arc, }, - /// A track is no longer listed because it finished: its producer declared its end. Its - /// groups stay readable while the cache retains them. + /// A track is no longer listed because it finished: its producer declared its end. A + /// track of groups stays readable while the cache retains its groups. Finished { + /// The kind an earlier [`Self::Added`] reported. + kind: Kind, /// The name an earlier [`Self::Added`] reported. name: Arc, }, @@ -53,7 +103,7 @@ pub enum TracksEvent { /// One listed track and who lists it. struct Entry { - info: track::Info, + info: Listed, /// The producer's listing, numbered so a stale unlist never removes a later track /// of the name. own: Option, @@ -82,7 +132,7 @@ impl Owner { #[derive(Default)] pub(super) struct ListingState { /// Every listed track, in the order it was listed. - live: LinkedHashMap, Entry>, + live: LinkedHashMap, /// The queue of every reader of the current answer. readers: slab::Slab>, /// Each owner's reader, by its key in `readers`. @@ -108,8 +158,8 @@ impl ListingState { /// Start a reader with every listed track queued, ending `owner`'s older one. fn read(&mut self, owner: Option) -> (kio::Shared, usize) { let mut queue = Queue::default(); - for (name, entry) in &self.live { - queue.pending.insert(name.clone(), Pending::Add(entry.info.clone())); + for (key, entry) in &self.live { + queue.pending.insert(key.clone(), Pending::Add(entry.info.clone())); } if self.synced() { queue.sync = SyncPhase::Counting(queue.pending.len()); @@ -142,31 +192,32 @@ impl ListingState { } } - fn insert(&mut self, name: Arc, entry: Entry) { + fn insert(&mut self, key: Key, entry: Entry) { let info = entry.info.clone(); - self.live.insert(name.clone(), entry); - self.each(|queue| queue.add(name.clone(), info.clone())); + self.live.insert(key.clone(), entry); + self.each(|queue| queue.add(key.clone(), info.clone())); } - /// Unlist `name`, telling readers whether it `finished`. - fn remove(&mut self, name: &str, finished: bool) { - if let Some((name, _)) = self.live.remove_entry(name) { - self.each(|queue| queue.remove(&name, finished)); + /// Unlist `key`, telling readers whether it `finished`. + fn remove(&mut self, key: &Key, finished: bool) { + if let Some((key, _)) = self.live.remove_entry(key) { + self.each(|queue| queue.remove(&key, finished)); } } /// List a track the producer created, returning the token that unlists it. - pub(super) fn list_own(&mut self, name: Arc, info: track::Info) -> u64 { + pub(super) fn list_own(&mut self, name: Arc, info: Listed) -> u64 { let token = self.next_token; self.next_token += 1; - match self.live.get_mut(&name) { + let key = (info.kind(), name); + match self.live.get_mut(&key) { // The earlier track of the name has not unlisted yet, but it left the table // for this one to be created: readers see it go and the new one arrive. Some(entry) if entry.own.is_some() && !entry.answered => { - self.remove(&name, false); + self.remove(&key, false); let own = Some(token); self.insert( - name, + key, Entry { info, own, @@ -180,7 +231,7 @@ impl ListingState { None => { let own = Some(token); self.insert( - name, + key, Entry { info, own, @@ -193,8 +244,8 @@ impl ListingState { } /// Unlist a track the producer created, unless a later one took its name. - pub(super) fn unlist_own(&mut self, name: &str, token: u64, finished: bool) { - let Some(entry) = self.live.get_mut(name) else { + pub(super) fn unlist_own(&mut self, key: &Key, token: u64, finished: bool) { + let Some(entry) = self.live.get_mut(key) else { return; }; if entry.own != Some(token) { @@ -202,12 +253,13 @@ impl ListingState { } entry.own = None; if !entry.answered { - self.remove(name, finished); + self.remove(key, finished); } } - fn answer_add(&mut self, name: Arc, info: track::Info) -> Result<(), Error> { - match self.live.get_mut(&name) { + fn answer_add(&mut self, name: Arc, info: Listed) -> Result<(), Error> { + let key = (info.kind(), name); + match self.live.get_mut(&key) { Some(entry) if entry.answered => Err(Error::Duplicate), Some(entry) => { entry.answered = true; @@ -215,7 +267,7 @@ impl ListingState { } None => { self.insert( - name, + key, Entry { info, own: None, @@ -227,13 +279,13 @@ impl ListingState { } } - fn answer_remove(&mut self, name: &str, finished: bool) -> Result<(), Error> { - let Some(entry) = self.live.get_mut(name).filter(|entry| entry.answered) else { + fn answer_remove(&mut self, key: &Key, finished: bool) -> Result<(), Error> { + let Some(entry) = self.live.get_mut(key).filter(|entry| entry.answered) else { return Err(Error::NotFound); }; entry.answered = false; if entry.own.is_none() { - self.remove(name, finished); + self.remove(key, finished); } Ok(()) } @@ -247,14 +299,14 @@ impl ListingState { /// Unlist every track the handler's answer listed. fn unanswer(&mut self) { - let answered: Vec> = self + let answered: Vec = self .live .iter() .filter(|(_, entry)| entry.answered) - .map(|(name, _)| name.clone()) + .map(|(key, _)| key.clone()) .collect(); - for name in answered { - let _ = self.answer_remove(&name, false); + for key in answered { + let _ = self.answer_remove(&key, false); } self.answered = false; } @@ -266,28 +318,30 @@ impl ListingState { self.owners.clear(); } - /// The broadcast ended: so does every listing of it, first unlisting each track its - /// producer created that `finished`, as its holder dropping later would have. A handler's - /// answer of the same name does not keep it live, since the producer's track is what served it. + /// The broadcast ended: so does every listing of it, first unlisting each track of groups + /// its producer created that `finished`, as its holder dropping later would have. A + /// handler's answer of the same name does not keep it live, since the producer's track is + /// what served it. A datagram track that finished already left the listing as it did. pub(super) fn close(&mut self, finished: impl Fn(&str) -> bool) { - let done: Vec> = self + let done: Vec = self .live .iter() - .filter(|(name, entry)| entry.own.is_some() && finished(name)) - .map(|(name, _)| name.clone()) + .filter(|((kind, name), entry)| *kind == Kind::Track && entry.own.is_some() && finished(name)) + .map(|(key, _)| key.clone()) .collect(); - for name in done { - self.remove(&name, true); + for key in done { + self.remove(&key, true); } self.detach(Ok(())); } } /// Unlists a track the producer created once it leaves the track table. Held by the -/// track's teardown guard, so it drops with the last producer, or when the track aborts. +/// track's teardown guard, so it drops with the last producer, or when the track aborts; +/// by a datagram track until it ends. pub(in crate::model) struct Unlist { state: kio::Shared, - name: Arc, + key: Key, token: u64, /// Whether the track declared its end, so readers see it finish rather than vanish. finished: bool, @@ -299,20 +353,28 @@ impl Unlist { state: &kio::Shared, listing: &mut ListingState, name: Arc, - info: &track::Info, + info: Listed, ) -> Self { - let token = listing.list_own(name.clone(), info.clone()); + let kind = info.kind(); + let token = listing.list_own(name.clone(), info); Self { state: state.clone(), - name, + key: (kind, name), token, finished: false, } } /// Unlist now, as a track that `finished` or left unfinished. - pub(in crate::model) fn unlist(mut self, finished: bool) { + pub(in crate::model) fn unlist(self, finished: bool) { + drop(self.finished(finished)); + } + + /// Unlist once dropped, as a track that `finished` or left unfinished: for a caller + /// holding a lock taken under the broadcast's, which must release it first. + pub(in crate::model) fn finished(mut self, finished: bool) -> Self { self.finished = finished; + self } } @@ -321,7 +383,7 @@ impl Drop for Unlist { self.state .lock() .listing - .unlist_own(&self.name, self.token, self.finished); + .unlist_own(&self.key, self.token, self.finished); } } @@ -335,28 +397,33 @@ impl ListOnAccept { /// List the track with the info it was accepted with. Called outside the broadcast's lock. pub(in crate::model) fn list(self, info: &track::Info) -> Unlist { let mut state = self.state.lock(); - Unlist::list(&self.state, &mut state.listing, self.name.clone(), info) + Unlist::list( + &self.state, + &mut state.listing, + self.name.clone(), + Listed::Track(info.clone()), + ) } } /// A change a reader has yet to read. enum Pending { - Add(track::Info), + Add(Listed), /// The track left, having finished or not. Remove { finished: bool, }, - /// A removal of a track the reader saw, then a track of the same name listed again. + /// A removal of a track the reader saw, then a track of the same kind and name listed again. Readd { finished: bool, - info: track::Info, + info: Listed, }, } -/// One reader's pending changes, keyed by name in the order they happened. +/// One reader's pending changes, keyed by kind and name in the order they happened. #[derive(Default)] pub(super) struct Queue { - pending: LinkedHashMap, Pending>, + pending: LinkedHashMap, sync: SyncPhase, /// How the listing ended for this reader, once it did: its broadcast ended, or a newer /// reader of the same owner replaced it. @@ -377,8 +444,8 @@ enum SyncPhase { } impl Queue { - fn add(&mut self, name: Arc, info: track::Info) { - match self.pending.get_mut(&name) { + fn add(&mut self, key: Key, info: Listed) { + match self.pending.get_mut(&key) { Some(pending) => match *pending { Pending::Remove { finished } => { *pending = Pending::Readd { finished, info }; @@ -391,16 +458,16 @@ impl Queue { _ => debug_assert!(false, "a listed track was listed again"), }, None => { - self.pending.insert(name, Pending::Add(info)); + self.pending.insert(key, Pending::Add(info)); } } } - fn remove(&mut self, name: &Arc, finished: bool) { - match self.pending.get_mut(name) { + fn remove(&mut self, key: &Key, finished: bool) { + match self.pending.get_mut(key) { // Never read: the two cancel. Some(Pending::Add(_)) => { - self.pending.remove(name); + self.pending.remove(key); } // Read, then re-added unread: the reader sees only the last removal, one event fewer. Some(pending @ Pending::Readd { .. }) => { @@ -411,7 +478,7 @@ impl Queue { } Some(pending) => *pending = Pending::Remove { finished }, None => { - self.pending.insert(name.clone(), Pending::Remove { finished }); + self.pending.insert(key.clone(), Pending::Remove { finished }); } } } @@ -452,11 +519,11 @@ impl Queue { // A clean end still reports each track that left before it, and how; an add the // reader never read is dropped. Some(Ok(())) => { - while let Some((name, pending)) = self.pending.pop_front() { + while let Some((key, pending)) = self.pending.pop_front() { match pending { Pending::Add(_) => {} Pending::Remove { finished } | Pending::Readd { finished, .. } => { - return Ok(Some(removal(name, finished))); + return Ok(Some(removal(key, finished))); } } } @@ -470,26 +537,26 @@ impl Queue { self.sync = SyncPhase::Sent; return Ok(Some(TracksEvent::Synced)); } - let (name, pending) = self.pending.pop_front().expect("a ready queue has a pending change"); + let (key, pending) = self.pending.pop_front().expect("a ready queue has a pending change"); if let SyncPhase::Counting(left) = &mut self.sync { *left -= 1; } Ok(Some(match pending { - Pending::Add(info) => TracksEvent::Added { name, info }, - Pending::Remove { finished } => removal(name, finished), + Pending::Add(info) => TracksEvent::Added { name: key.1, info }, + Pending::Remove { finished } => removal(key, finished), Pending::Readd { finished, info } => { - self.pending.insert_front(name.clone(), Pending::Add(info)); - removal(name, finished) + self.pending.insert_front(key.clone(), Pending::Add(info)); + removal(key, finished) } })) } } -/// The event for `name` leaving the listing. -fn removal(name: Arc, finished: bool) -> TracksEvent { +/// The event for `key` leaving the listing. +fn removal((kind, name): Key, finished: bool) -> TracksEvent { match finished { - true => TracksEvent::Finished { name }, - false => TracksEvent::Removed { name }, + true => TracksEvent::Finished { kind, name }, + false => TracksEvent::Removed { kind, name }, } } @@ -615,33 +682,34 @@ impl Lister { self.poll_readers(waiter, false) } - /// List a track. Fails with [`Error::Duplicate`] if this answer already lists it. - pub fn add(&self, name: impl Into>, info: track::Info) -> Result<(), Error> { + /// List a track of the kind `info` is: a [`track::Info`] or a [`datagram::Info`]. Fails + /// with [`Error::Duplicate`] if this answer already lists that kind and name. + pub fn add(&self, name: impl Into>, info: impl Into) -> Result<(), Error> { let mut state = self.state.lock(); if state.closing { return Err(Error::Closed); } - state.listing.answer_add(name.into(), info) + state.listing.answer_add(name.into(), info.into()) } /// Stop listing a track that left unfinished, reported as [`TracksEvent::Removed`]. - /// Fails with [`Error::NotFound`] if this answer does not list it. - pub fn remove(&self, name: &str) -> Result<(), Error> { - self.unlist(name, false) + /// Fails with [`Error::NotFound`] if this answer does not list that kind and name. + pub fn remove(&self, kind: Kind, name: impl Into>) -> Result<(), Error> { + self.unlist((kind, name.into()), false) } /// Stop listing a track that finished, reported as [`TracksEvent::Finished`]. Fails with - /// [`Error::NotFound`] if this answer does not list it. - pub fn finish(&self, name: &str) -> Result<(), Error> { - self.unlist(name, true) + /// [`Error::NotFound`] if this answer does not list that kind and name. + pub fn finish(&self, kind: Kind, name: impl Into>) -> Result<(), Error> { + self.unlist((kind, name.into()), true) } - fn unlist(&self, name: &str, finished: bool) -> Result<(), Error> { + fn unlist(&self, key: Key, finished: bool) -> Result<(), Error> { let mut state = self.state.lock(); if state.closing { return Err(Error::Closed); } - state.listing.answer_remove(name, finished) + state.listing.answer_remove(&key, finished) } /// The answer holds everything this hop knows now; later changes are live. @@ -693,14 +761,26 @@ mod tests { use super::super::Info; use super::*; - /// The next event as `+name`, `-name`, `synced`, `end`, or `error: ..`; `None` while pending. + /// An event as `+name`, `-name`, `~name` (finished), or `synced`, a datagram track's name + /// prefixed `d:`. + fn show(event: TracksEvent) -> String { + let named = |kind: Kind, name: Arc| match kind { + Kind::Track => name.to_string(), + Kind::Datagrams => format!("d:{name}"), + }; + match event { + TracksEvent::Added { name, info } => format!("+{}", named(info.kind(), name)), + TracksEvent::Removed { kind, name } => format!("-{}", named(kind, name)), + TracksEvent::Finished { kind, name } => format!("~{}", named(kind, name)), + TracksEvent::Synced => "synced".into(), + } + } + + /// The next event as [`show`] has it, `end`, or `error: ..`; `None` while pending. fn next(tracks: &mut Tracks) -> Option { match tracks.poll_next(&kio::Waiter::noop()) { Poll::Pending => None, - Poll::Ready(Ok(Some(TracksEvent::Added { name, .. }))) => Some(format!("+{name}")), - Poll::Ready(Ok(Some(TracksEvent::Removed { name }))) => Some(format!("-{name}")), - Poll::Ready(Ok(Some(TracksEvent::Finished { name }))) => Some(format!("~{name}")), - Poll::Ready(Ok(Some(TracksEvent::Synced))) => Some("synced".into()), + Poll::Ready(Ok(Some(event))) => Some(show(event)), Poll::Ready(Ok(None)) => Some("end".into()), Poll::Ready(Err(err)) => Some(format!("error: {err}")), } @@ -728,24 +808,21 @@ mod tests { /// A removal re-added after SYNCED was owed still lets the changes queued behind it out first. #[test] fn a_readd_after_sync_keeps_synced_behind_queued_changes() { + let key = |name: &str| (Kind::Track, Arc::from(name)); + let info = || Listed::Track(track::Info::default()); let mut queue = Queue::default(); - queue.remove(&"a".into(), false); - queue.add("b".into(), track::Info::default()); + queue.remove(&key("a"), false); + queue.add(key("b"), info()); queue.sync(); // Churn coalesces in place, so it owes SYNCED nothing extra. for _ in 0..3 { - queue.add("a".into(), track::Info::default()); - queue.remove(&"a".into(), false); + queue.add(key("a"), info()); + queue.remove(&key("a"), false); } - queue.add("a".into(), track::Info::default()); + queue.add(key("a"), info()); let mut events = Vec::new(); while queue.is_ready() { - events.push(match queue.next().unwrap().unwrap() { - TracksEvent::Added { name, .. } => format!("+{name}"), - TracksEvent::Removed { name } => format!("-{name}"), - TracksEvent::Finished { name } => format!("~{name}"), - TracksEvent::Synced => "synced".into(), - }); + events.push(show(queue.next().unwrap().unwrap())); } assert_eq!(events, ["-a", "+a", "+b", "synced"]); } @@ -768,16 +845,99 @@ mod tests { assert_eq!(drain(&mut tracks), ["+a"]); } - /// TRACK_INFO can't say a track is datagrams, so a listing never carries one. + /// A datagram track the producer creates is listed with its info until it ends, finished + /// or not. #[test] - fn a_datagram_track_is_never_listed() { + fn a_datagram_track_is_listed_until_it_ends() { let broadcast = Info::new().produce(); + let early = broadcast + .create_datagrams("early", datagram::Info::default().with_priority(4)) + .unwrap(); + let mut tracks = broadcast.consume().tracks().unwrap(); + let Poll::Ready(Ok(Some(TracksEvent::Added { + info: Listed::Datagrams(info), + .. + }))) = tracks.poll_next(&kio::Waiter::noop()) + else { + panic!("expected the datagram track"); + }; + assert_eq!(info.priority, 4); + assert_eq!(drain(&mut tracks), ["synced"]); + + let late = broadcast.create_datagrams("late", Default::default()).unwrap(); + let gone = broadcast.create_datagrams("gone", Default::default()).unwrap(); + assert_eq!(drain(&mut tracks), ["+d:late", "+d:gone"]); + let clone = early.clone(); + early.finish(); + drop(clone); + late.abort(Error::Cancel); + drop(gone); + assert_eq!(drain(&mut tracks), ["~d:early", "-d:late", "-d:gone"]); + + // A name ended is free for a new track, listed afresh. let _early = broadcast.create_datagrams("early", Default::default()).unwrap(); + assert_eq!(drain(&mut tracks), ["+d:early"]); + } + + /// A track of groups and a datagram track of one name are listed apart, and each leaves + /// on its own. + #[test] + fn the_two_kinds_of_a_name_are_listed_apart() { + let broadcast = Info::new().produce(); + let track = broadcast.create_track("a", None).unwrap(); + let datagrams = broadcast.create_datagrams("a", Default::default()).unwrap(); let mut tracks = broadcast.consume().tracks().unwrap(); + assert_eq!(drain(&mut tracks), ["+a", "+d:a", "synced"]); + drop(track); + assert_eq!(drain(&mut tracks), ["-a"]); + datagrams.finish(); + assert_eq!(drain(&mut tracks), ["~d:a"]); + + let lister = broadcast.requests().lister().unwrap(); + lister.add("b", track::Info::default()).unwrap(); + lister.add("b", datagram::Info::default()).unwrap(); + assert!(matches!( + lister.add("b", datagram::Info::default()), + Err(Error::Duplicate) + )); + lister.synced(); + assert_eq!(drain(&mut tracks), ["+b", "+d:b"]); + lister.finish(Kind::Datagrams, "b").unwrap(); + assert!(matches!(lister.remove(Kind::Datagrams, "b"), Err(Error::NotFound))); + lister.remove(Kind::Track, "b").unwrap(); + assert_eq!(drain(&mut tracks), ["~d:b", "-b"]); + } + + /// A datagram track a consumer asked for and a handler served is not in the inventory, + /// as a track served on request is not. + #[test] + fn a_datagram_track_served_on_request_is_never_listed() { + let broadcast = Info::new().produce(); + let mut requests = broadcast.requests().datagrams(); + let consumer = broadcast.consume(); + let mut tracks = consumer.tracks().unwrap(); assert_eq!(drain(&mut tracks), ["synced"]); - let _late = broadcast.create_datagrams("late", Default::default()).unwrap(); - let _a = broadcast.create_track("a", None).unwrap(); - assert_eq!(drain(&mut tracks), ["+a"]); + let _reader = consumer.datagrams("x").unwrap(); + let Poll::Ready(Ok(request)) = requests.poll_requested(&kio::Waiter::noop()) else { + panic!("expected the request"); + }; + let _x = request.accept(Default::default()); + assert_eq!(drain(&mut tracks), NONE); + } + + /// Creating a datagram track a consumer already asked for serves that consumer, and lists it. + #[test] + fn a_created_datagram_track_lists_though_it_was_asked_for() { + let broadcast = Info::new().produce(); + let _requests = broadcast.requests().datagrams(); + let consumer = broadcast.consume(); + let mut tracks = consumer.tracks().unwrap(); + assert_eq!(drain(&mut tracks), ["synced"]); + let _reader = consumer.datagrams("x").unwrap(); + let x = broadcast.create_datagrams("x", Default::default()).unwrap(); + assert_eq!(drain(&mut tracks), ["+d:x"]); + drop(x); + assert_eq!(drain(&mut tracks), ["-d:x"]); } #[test] @@ -787,7 +947,11 @@ mod tests { .create_track("a", track::Info::default().with_priority(9)) .unwrap(); let mut tracks = broadcast.consume().tracks().unwrap(); - let Poll::Ready(Ok(Some(TracksEvent::Added { info, .. }))) = tracks.poll_next(&kio::Waiter::noop()) else { + let Poll::Ready(Ok(Some(TracksEvent::Added { + info: Listed::Track(info), + .. + }))) = tracks.poll_next(&kio::Waiter::noop()) + else { panic!("expected the track"); }; assert_eq!(info.priority, 9); @@ -848,10 +1012,10 @@ mod tests { lister.synced(); let mut tracks = broadcast.consume().tracks().unwrap(); assert_eq!(drain(&mut tracks), ["+up", "+gone", "synced"]); - lister.finish("up").unwrap(); - lister.remove("gone").unwrap(); + lister.finish(Kind::Track, "up").unwrap(); + lister.remove(Kind::Track, "gone").unwrap(); assert_eq!(drain(&mut tracks), ["~up", "-gone"]); - assert!(matches!(lister.finish("up"), Err(Error::NotFound))); + assert!(matches!(lister.finish(Kind::Track, "up"), Err(Error::NotFound))); } /// A clean end reports each track that left before it, and how, but not one the reader @@ -892,7 +1056,7 @@ mod tests { lister.synced(); let mut tracks = broadcast.consume().tracks().unwrap(); assert_eq!(drain(&mut tracks), ["+up", "synced"]); - lister.finish("up").unwrap(); + lister.finish(Kind::Track, "up").unwrap(); match abort { true => { lister.abort(Error::Cancel); @@ -1043,8 +1207,8 @@ mod tests { lister.synced(); assert_eq!(drain(&mut tracks), ["+up", "synced"]); - lister.remove("up").unwrap(); - assert!(matches!(lister.remove("up"), Err(Error::NotFound))); + lister.remove(Kind::Track, "up").unwrap(); + assert!(matches!(lister.remove(Kind::Track, "up"), Err(Error::NotFound))); assert_eq!(drain(&mut tracks), ["-up"]); assert!(lister.poll_unwanted(&waiter).is_pending()); @@ -1063,7 +1227,7 @@ mod tests { assert_eq!(drain(&mut tracks), ["+a", "synced"]); drop(own); assert_eq!(drain(&mut tracks), NONE, "still answered"); - lister.remove("a").unwrap(); + lister.remove(Kind::Track, "a").unwrap(); assert_eq!(drain(&mut tracks), ["-a"]); } @@ -1148,13 +1312,13 @@ mod tests { #[test] fn an_answered_name_survives_its_own_track_being_replaced() { let mut listing = ListingState::default(); - let first = listing.list_own("a".into(), track::Info::default()); - listing.answer_add("a".into(), track::Info::default()).unwrap(); + let first = listing.list_own("a".into(), track::Info::default().into()); + listing.answer_add("a".into(), track::Info::default().into()).unwrap(); let (queue, _) = listing.read(None); assert!(matches!(queue.lock().next(), Ok(Some(TracksEvent::Added { .. })))); // The new track of the name lists before the earlier one unlists. - listing.list_own("a".into(), track::Info::default()); - listing.unlist_own("a", first, false); + listing.list_own("a".into(), track::Info::default().into()); + listing.unlist_own(&(Kind::Track, "a".into()), first, false); assert!(queue.lock().pending.is_empty(), "the name never stopped being listed"); } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index eda22ae8a92..c2c33569ce8 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -4375,12 +4375,12 @@ struct FrontListing { /// The source being read. source: Option, reader: Option, - /// Every name the front lists. - listed: HashSet>, - /// Names an earlier source listed that the current one has yet to list. A source of the + /// Every track the front lists, by kind and name. + listed: HashSet<(broadcast::Kind, Arc)>, + /// Tracks an earlier source listed that the current one has yet to list. A source of the /// same instance lists the same tracks, so its readers see no churn: what it still lacks /// at its SYNCED is gone. - stale: HashSet>, + stale: HashSet<(broadcast::Kind, Arc)>, } /// A track the ended front left in flight, held until its last reader leaves. It @@ -5493,27 +5493,30 @@ impl kio::Task for FrontServe { // The lister refuses only once the broadcast ended, which ends the front too. match result { Ok(Some(broadcast::TracksEvent::Added { name, info })) => { - if !state.stale.remove(&name) && state.listed.insert(name.clone()) { - let _ = self.lister.add(name, info); + let key = (info.kind(), name); + if !state.stale.remove(&key) && state.listed.insert(key.clone()) { + let _ = self.lister.add(key.1, info); } } // Forwarded as the source reported it, finished or not. - Ok(Some(broadcast::TracksEvent::Removed { name })) => { - state.stale.remove(&name); - if state.listed.remove(&name) { - let _ = self.lister.remove(&name); + Ok(Some(broadcast::TracksEvent::Removed { kind, name })) => { + let key = (kind, name); + state.stale.remove(&key); + if state.listed.remove(&key) { + let _ = self.lister.remove(kind, key.1); } } - Ok(Some(broadcast::TracksEvent::Finished { name })) => { - state.stale.remove(&name); - if state.listed.remove(&name) { - let _ = self.lister.finish(&name); + Ok(Some(broadcast::TracksEvent::Finished { kind, name })) => { + let key = (kind, name); + state.stale.remove(&key); + if state.listed.remove(&key) { + let _ = self.lister.finish(kind, key.1); } } Ok(Some(broadcast::TracksEvent::Synced)) => { - for name in state.stale.drain() { - state.listed.remove(&name); - let _ = self.lister.remove(&name); + for (kind, name) in state.stale.drain() { + state.listed.remove(&(kind, name.clone())); + let _ = self.lister.remove(kind, name); } self.lister.synced(); } @@ -11156,12 +11159,17 @@ mod tests { assert!(first.is_clone(&second), "the newcomer joins the front"); } + /// The next event, a datagram track's name prefixed `d:`. #[cfg(feature = "async")] async fn listed(tracks: &mut broadcast::Tracks) -> String { + let named = |kind: broadcast::Kind, name: Arc| match kind { + broadcast::Kind::Track => name.to_string(), + broadcast::Kind::Datagrams => format!("d:{name}"), + }; match tracks.next().await { - Ok(Some(broadcast::TracksEvent::Added { name, .. })) => format!("+{name}"), - Ok(Some(broadcast::TracksEvent::Removed { name })) => format!("-{name}"), - Ok(Some(broadcast::TracksEvent::Finished { name })) => format!("~{name}"), + Ok(Some(broadcast::TracksEvent::Added { name, info })) => format!("+{}", named(info.kind(), name)), + Ok(Some(broadcast::TracksEvent::Removed { kind, name })) => format!("-{}", named(kind, name)), + Ok(Some(broadcast::TracksEvent::Finished { kind, name })) => format!("~{}", named(kind, name)), Ok(Some(broadcast::TracksEvent::Synced)) => "synced".into(), Ok(None) => "end".into(), Err(err) => format!("error: {err}"), @@ -11184,8 +11192,15 @@ mod tests { let _audio = source.broadcast().create_track("audio", None).unwrap(); assert_eq!(listed(&mut tracks).await, "+audio"); + let datagrams = source + .broadcast() + .create_datagrams("video", Default::default()) + .unwrap(); + assert_eq!(listed(&mut tracks).await, "+d:video"); drop(video); assert_eq!(listed(&mut tracks).await, "-video"); + datagrams.finish(); + assert_eq!(listed(&mut tracks).await, "~d:video"); drop(source); assert_eq!(listed(&mut tracks).await, "end"); diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 6886ac8b308..f18e8fce895 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -558,8 +558,8 @@ fn lite_auth_unsupported_interop() { } /// moq-lite-07 TRACKS across the Rust/JS boundary: the JS publisher answers a Rust TRACKS request -/// with a listing Rust decodes, and JS decodes Rust's listing events and re-encodes them byte for -/// byte. +/// with a listing Rust decodes, a datagram track among its tracks, and JS decodes Rust's listing +/// events of both kinds and re-encodes them byte for byte. #[test] #[ignore = "requires Bun; run by just test interop"] fn lite_tracks_interop() { @@ -579,8 +579,15 @@ fn lite_tracks_interop() { let mut r = Decoder::new(&answer, version.into()); let mut events = Vec::new(); while !r.is_empty() { + let named = |kind: crate::broadcast::Kind, name: &str| match kind { + crate::broadcast::Kind::Track => name.to_string(), + crate::broadcast::Kind::Datagrams => format!("d:{name}"), + }; events.push(match lite::TracksEvent::decode(&mut r, version).unwrap() { - lite::TracksEvent::Added { name, info } => { + lite::TracksEvent::Added { + name, + info: lite::Listed::Track(info), + } => { if name == "a" { assert_eq!(info.timescale, Some(crate::Timescale::MILLI)); assert_eq!(info.max_age, Some(std::time::Duration::from_secs(3))); @@ -589,13 +596,21 @@ fn lite_tracks_interop() { } format!("+{name}") } - lite::TracksEvent::Removed { name } => format!("-{name}"), - lite::TracksEvent::Finished { name } => format!("~{name}"), + lite::TracksEvent::Added { + name, + info: lite::Listed::Datagrams(info), + } => { + assert_eq!(info.timescale, Some(crate::Timescale::MILLI)); + assert_eq!(info.priority, 2); + format!("+d:{name}") + } + lite::TracksEvent::Removed { kind, name } => format!("-{}", named(kind, &name)), + lite::TracksEvent::Finished { kind, name } => format!("~{}", named(kind, &name)), lite::TracksEvent::Synced => "synced".to_string(), }); } // The broadcast's end is the JS publisher's FIN, after the last event. - assert_eq!(events, ["+a", "+b", "synced", "-a"]); + assert_eq!(events, ["+a", "+b", "+d:a", "synced", "-a", "~d:a"]); let info = lite::TrackInfo { refresh: Some(4), @@ -609,9 +624,23 @@ fn lite_tracks_interop() { for event in [ lite::TracksEvent::Added { name: "video".into(), - info, + info: lite::Listed::Track(info), + }, + lite::TracksEvent::Added { + name: "video".into(), + info: lite::Listed::Datagrams(lite::DatagramsInfo { + priority: -3, + timescale: Some(crate::Timescale::MILLI), + }), + }, + lite::TracksEvent::Removed { + kind: crate::broadcast::Kind::Track, + name: "video".into(), + }, + lite::TracksEvent::Finished { + kind: crate::broadcast::Kind::Datagrams, + name: "video".into(), }, - lite::TracksEvent::Removed { name: "video".into() }, lite::TracksEvent::Synced, ] { event.encode(&mut w, version).unwrap(); diff --git a/rs/moq-net/tests/integration/tracks.rs b/rs/moq-net/tests/integration/tracks.rs index 4fdfbdca865..5821ba71c21 100644 --- a/rs/moq-net/tests/integration/tracks.rs +++ b/rs/moq-net/tests/integration/tracks.rs @@ -9,7 +9,7 @@ use support::AppendNext; use std::time::Duration; -use moq_net::broadcast::TracksEvent; +use moq_net::broadcast::{Kind, Listed, TracksEvent}; use moq_net::{Version, session::Limits}; use support::harness::{MockConnectOptions, MockPair, connect_mock}; @@ -26,15 +26,20 @@ fn lite07() -> Version { "moq-lite-07-wip".parse().unwrap() } -/// The next event as `+name`, `-name`, `synced`, `end`, or `error: ..`. +/// The next event as `+name`, `-name`, `~name` (finished), `synced`, `end`, or `error: ..`, a +/// datagram track's name prefixed `d:`. async fn next(tracks: &mut moq_net::broadcast::Tracks) -> String { + let named = |kind: Kind, name: &str| match kind { + Kind::Track => name.to_string(), + Kind::Datagrams => format!("d:{name}"), + }; match kio::clock::timeout(TIMEOUT, tracks.next()) .await .expect("listing stalled") { - Ok(Some(TracksEvent::Added { name, .. })) => format!("+{name}"), - Ok(Some(TracksEvent::Removed { name })) => format!("-{name}"), - Ok(Some(TracksEvent::Finished { name })) => format!("~{name}"), + Ok(Some(TracksEvent::Added { name, info })) => format!("+{}", named(info.kind(), &name)), + Ok(Some(TracksEvent::Removed { kind, name })) => format!("-{}", named(kind, &name)), + Ok(Some(TracksEvent::Finished { kind, name })) => format!("~{}", named(kind, &name)), Ok(Some(TracksEvent::Synced)) => "synced".into(), Ok(None) => "end".into(), Err(err) => format!("error: {err}"), @@ -114,7 +119,11 @@ async fn a_listing_carries_track_info() { .await .expect("listing stalled") .unwrap(); - let Some(TracksEvent::Added { name, info }) = event else { + let Some(TracksEvent::Added { + name, + info: Listed::Track(info), + }) = event + else { panic!("expected an add, got {event:?}"); }; assert_eq!(&*name, "a"); @@ -125,6 +134,70 @@ async fn a_listing_carries_track_info() { assert_eq!(info.compression, moq_net::track::Compression::Deflate); } +/// A datagram track is listed apart from the track of its name, with its DATAGRAMS_INFO, and +/// the listed name reads its datagrams. +#[kio::test] +async fn a_session_lists_its_peers_datagram_tracks() { + let publisher = produce_origin(1); + let broadcast = publisher + .route("bcast", moq_net::origin::RouteOptions::hidden()) + .unwrap(); + let track = broadcast.broadcast().create_track("a", None).unwrap(); + let mut datagrams = broadcast + .broadcast() + .create_datagrams( + "a", + moq_net::datagram::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_priority(-2), + ) + .unwrap(); + broadcast.announce().unwrap(); + + let (subscriber, _pair) = connect(&publisher, 2, lite07()).await; + let remote = resolve(&subscriber).await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "+a"); + let event = kio::clock::timeout(TIMEOUT, tracks.next()) + .await + .expect("listing stalled") + .unwrap(); + let Some(TracksEvent::Added { + name, + info: Listed::Datagrams(info), + }) = event + else { + panic!("expected the datagram track, got {event:?}"); + }; + assert_eq!(&*name, "a"); + assert_eq!(info.timescale, Some(moq_net::Timescale::MILLI)); + assert_eq!(info.priority, -2); + assert_eq!(next(&mut tracks).await, "synced"); + + let mut reader = remote.datagrams(&name).unwrap(); + kio::clock::timeout(TIMEOUT, reader.info()).await.unwrap().unwrap(); + // Sent until one arrives: a datagram is best-effort. + let received = kio::clock::timeout(TIMEOUT, async { + loop { + datagrams + .append(moq_net::Timestamp::from_millis(0).unwrap(), b"x".as_ref()) + .unwrap(); + if let Some(Ok(datagram)) = futures::FutureExt::now_or_never(reader.recv()) { + break datagram; + } + kio::clock::sleep(Duration::from_millis(10)).await; + } + }) + .await + .expect("no datagram arrived"); + assert_eq!(received.expect("a datagram").payload, &b"x"[..]); + + datagrams.finish(); + assert_eq!(next(&mut tracks).await, "~d:a", "TRACKS_FINISH of the datagram track"); + drop(track); + assert_eq!(next(&mut tracks).await, "-a"); +} + /// A listed track is a track like any other: a SUBSCRIBE from the listing reads the /// group it already holds from the cache. #[kio::test] diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs index 368b4a3c54f..f1ef3805bf3 100644 --- a/rs/moq-net/tests/integration/tracks_ietf.rs +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -41,8 +41,8 @@ async fn next(tracks: &mut moq_net::broadcast::Tracks) -> String { .expect("listing stalled") { Ok(Some(TracksEvent::Added { name, .. })) => format!("+{name}"), - Ok(Some(TracksEvent::Removed { name })) => format!("-{name}"), - Ok(Some(TracksEvent::Finished { name })) => format!("~{name}"), + Ok(Some(TracksEvent::Removed { name, .. })) => format!("-{name}"), + Ok(Some(TracksEvent::Finished { name, .. })) => format!("~{name}"), Ok(Some(TracksEvent::Synced)) => "synced".into(), Ok(None) => "end".into(), Err(err) => format!("error: {err}"), diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 759fdc66d4d..e906d3252cf 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -986,20 +986,30 @@ fn advance( // listing that ends took its broadcast with it. while let Some(listing) = &mut node.listing { match listing.poll_next(waiter) { - Poll::Ready(Ok(Some(broadcast::TracksEvent::Added { name: listed, .. }))) => { + Poll::Ready(Ok(Some(broadcast::TracksEvent::Added { + name: listed, + info: broadcast::Listed::Track(_), + }))) => { if parse_bucket_track(&listed).is_some_and(|(bucket, _)| bucket.as_str() == name) { node.offered = Some(listed); } } Poll::Ready(Ok(Some( - broadcast::TracksEvent::Removed { name: listed } - | broadcast::TracksEvent::Finished { name: listed }, + broadcast::TracksEvent::Removed { + kind: broadcast::Kind::Track, + name: listed, + } + | broadcast::TracksEvent::Finished { + kind: broadcast::Kind::Track, + name: listed, + }, ))) => { if node.offered.as_ref() == Some(&listed) { node.offered = None; } } - Poll::Ready(Ok(Some(broadcast::TracksEvent::Synced))) => {} + // SYNCED, and datagram tracks: buckets are tracks of groups. + Poll::Ready(Ok(Some(_))) => {} Poll::Ready(result) => { if let Err(err) = result { tracing::debug!(?err, name, "stats: node listing ended"); diff --git a/rs/moq-stats/src/lib.rs b/rs/moq-stats/src/lib.rs index 3adbc41da84..b29009a21ee 100644 --- a/rs/moq-stats/src/lib.rs +++ b/rs/moq-stats/src/lib.rs @@ -219,15 +219,25 @@ pub fn parse_bucket_track(name: &str) -> Option<(Path, Epoch)> { /// list, whose subscription fails like any unlisted track's. #[cfg(test)] pub(crate) async fn listed_bucket_track(broadcast: &moq_net::broadcast::Consumer, bucket: &Path) -> String { - use moq_net::broadcast::TracksEvent; + use moq_net::broadcast::{Kind, Listed, TracksEvent}; let mut listed = None; if let Ok(mut tracks) = broadcast.tracks() { while let Ok(Some(event)) = tracks.next().await { match event { - TracksEvent::Added { name, .. } if parse_bucket_track(&name).is_some_and(|(b, _)| b == *bucket) => { + TracksEvent::Added { + name, + info: Listed::Track(_), + } if parse_bucket_track(&name).is_some_and(|(b, _)| b == *bucket) => { listed = Some(name.to_string()); } - TracksEvent::Removed { name } | TracksEvent::Finished { name } if listed.as_deref() == Some(&*name) => { + TracksEvent::Removed { + kind: Kind::Track, + name, + } + | TracksEvent::Finished { + kind: Kind::Track, + name, + } if listed.as_deref() == Some(&*name) => { listed = None; } TracksEvent::Synced => break, diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 54a597da756..338b112b538 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -3078,9 +3078,19 @@ mod tests { .expect("listing") .expect("live"); let (name, listed) = match event { - broadcast::TracksEvent::Added { name, .. } => (name, true), - broadcast::TracksEvent::Removed { name } | broadcast::TracksEvent::Finished { name } => (name, false), - broadcast::TracksEvent::Synced => continue, + broadcast::TracksEvent::Added { + name, + info: broadcast::Listed::Track(_), + } => (name, true), + broadcast::TracksEvent::Removed { + kind: broadcast::Kind::Track, + name, + } + | broadcast::TracksEvent::Finished { + kind: broadcast::Kind::Track, + name, + } => (name, false), + _ => continue, }; if let Some((bucket, _)) = crate::parse_bucket_track(&name) { return (bucket.as_str().to_string(), listed); diff --git a/test/interop/README.md b/test/interop/README.md index b6d234875ad..90e75fadd5a 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -679,9 +679,10 @@ refusal retains its meaning and both bindings emit the same bytes. `lite_tracks_interop` checks moq-lite-07's Tracks Stream both ways: `tracks.ts` answers a Rust TRACKS request with js/net's publisher, whose listing (each -TRACKS\_ADD with its TRACK\_INFO, SYNCED, a TRACKS\_REMOVE, then the FIN when -the broadcast ends) Rust decodes, and it re-encodes Rust's listing events byte for -byte. +TRACKS\_ADD with its kind and info, a datagram track's DATAGRAMS\_INFO beside a +track's TRACK\_INFO of the same name, SYNCED, a TRACKS\_REMOVE and a datagram +track's TRACKS\_FINISH, then the FIN when the broadcast ends) Rust decodes, and it +re-encodes Rust's listing events of both kinds byte for byte. `lite_varint_interop` runs next to it and does the same through moq-lite's version dispatch: `lite-varint.ts` decodes Rust's lite-06 (QUIC) and lite-07 diff --git a/test/interop/tracks.ts b/test/interop/tracks.ts index 40df6724a21..d849db089e8 100644 --- a/test/interop/tracks.ts +++ b/test/interop/tracks.ts @@ -1,6 +1,6 @@ // moq-lite-07 TRACKS both ways. `answer`: the JS publisher answers a Rust-encoded TRACKS request -// with its listing, through a removal and the broadcast's end. `echo`: JS decodes Rust-encoded -// listing events and encodes them back. +// with its listing of both kinds, through a removal, a datagram track's finish, and the broadcast's +// end. `echo`: JS decodes Rust-encoded listing events and encodes them back. import { Duration } from "@moq/clock"; import { randomHop } from "../../js/net/src/hop.ts"; import { Publisher } from "../../js/net/src/lite/publisher.ts"; @@ -27,6 +27,8 @@ if (input.mode === "answer") { const broadcast = broadcastRoute.broadcast; broadcast.createTrack("a", { timescale: Timescale.MILLI, maxAge: Duration.millis(3000), priority: 9, refresh: 4 }); broadcast.createTrack("b"); + // A namespace apart from the track of the same name. + const datagrams = broadcast.createDatagrams("a", { timescale: Timescale.MILLI, priority: 2 }); const publisher = new Publisher(createMockTransportPair().server, version, randomHop(), origin.consume()); const stream = new Stream({ @@ -41,6 +43,7 @@ if (input.mode === "answer") { // Past SYNCED before the removal, so the removal is not folded into the initial set. await settle(); broadcast.removeTrack("a"); + datagrams.finish(); await settle(); broadcast.close(); await listing; From f77a102a870c7ed1f07fb8c6f6f5775f6651e2e0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 04:24:15 -0800 Subject: [PATCH 07/26] feat(js/lite)!: lite-07 SUBSCRIBE says no max age, one inclusive time anchor, and whether the largest ended The JS side of the lite-07 SUBSCRIBE changes: - Subscriber Max Age is milliseconds plus one on lite-07, 0 for no limit. Subscribe and SubscribeUpdate carry `maxDelay: number | null`; lite-01/02 decode as null, and lite-03 to 06 send no limit as the largest safe value, as before. - Anchors are 0 none, 1 time (inclusive at both ends, full 64-bit), and 2 relative; any other type is a protocol violation. An absolute anchor goes out as a time, an end as the time before it. The JS model still keys groups by sequence, so a decoded time names that key. - SUBSCRIBE_OK's largest carries whether its group ended. The publisher answers from its track, and the subscriber records it so a relay forwards it. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.test.ts | 2 +- js/net/src/integers.test.ts | 2 +- js/net/src/integration.test.ts | 30 +++-- js/net/src/internal.ts | 22 +++- js/net/src/lite/publisher.test.ts | 186 ++++++++-------------------- js/net/src/lite/publisher.ts | 60 +++------ js/net/src/lite/subscribe.test.ts | 124 +++++++++++++------ js/net/src/lite/subscribe.ts | 196 ++++++++++++++++++------------ js/net/src/lite/subscriber.ts | 23 ++-- js/net/src/lite/tail.test.ts | 5 +- js/net/src/lite/version.ts | 17 +++ js/net/src/resume.ts | 6 + js/net/src/track.ts | 29 ++++- 13 files changed, 375 insertions(+), 327 deletions(-) diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index b55d7b1adf9..10cee294a6f 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -4292,7 +4292,7 @@ test("draft-22: reported Largest survives absent headers, older cache entries, a using clock = manual(); const fx = fixture(); const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); - hooks.reportedLargest(track, { group: 4n, frame: 3 }); + hooks.reportedLargest(track, { group: 4n, frame: 3 }, false); const { client, ok } = await runSubscribe( fx, new Subscribe({ diff --git a/js/net/src/integers.test.ts b/js/net/src/integers.test.ts index 0c9db2595fd..c249c678d75 100644 --- a/js/net/src/integers.test.ts +++ b/js/net/src/integers.test.ts @@ -196,5 +196,5 @@ test("legacy session bitrate refuses unsafe numbers", async () => { test("time anchors convert at the declared scale without losing an aligned unit", () => { expect( toWireRanges([{ start: { time: new Timestamp(4611686021000000, Timescale.NANO) } }], Timescale.MILLI), - ).toEqual([{ start: { time: 4611686021 } }]); + ).toEqual([{ start: { time: 4611686021n } }]); }); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index b1ae87bc172..6539e731ab2 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -588,8 +588,8 @@ test("integration: lite-07 keeps a covered bounded subscription open", async () } }); -// A time range goes upstream in the track's timescale, the publisher resolves its start from -// where its groups start, and the copy's reader resolves the end from the groups it receives. +// A time range goes upstream in the track's timescale, as the keys of the groups starting at +// those times, both ends inclusive. test("integration: lite-07 serves a time range", async () => { const pair = createMockTransportPair(Lite.ALPN_07_WIP); const origin = new OriginProducer(); @@ -599,26 +599,24 @@ test("integration: lite-07 serves a time range", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MICRO, maxAge: null }); - for (let sequence = 0; sequence < 10; sequence++) { - const group = producer.appendGroup(); - group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(sequence * 1000))); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); + // Keyed by start, as the wire names a group: one per second. + for (let start = 0n; start < 10_000n; start += 1000n) { + const group = producer.createGroup(start); + group.writeFrame(textFrame(`${start}`, Timestamp.fromMillis(Number(start)))); group.finish(); } const remote = wireOf(client).consume(Path.from("test")); try { - const reader = remote - .track("video") - .subscribe({ - delay: { max: null }, - order: "ascending", - ranges: [{ start: { time: Timestamp.fromMillis(2500) }, end: { time: Timestamp.fromMillis(5000) } }], - }) - .ordered(); + const reader = remote.track("video").subscribe({ + delay: { max: null }, + order: "ascending", + ranges: [{ start: { time: Timestamp.fromMillis(2000) }, end: { time: Timestamp.fromMillis(5000) } }], + }); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await reader.nextGroup())?.sequence ?? -1n); - expect(got).toEqual([2n, 3n, 4n, 5n]); + for (let i = 0; i < 4; i++) got.push((await reader.recvGroup())?.sequence ?? -1n); + expect(got.sort((a, b) => (a < b ? -1 : 1))).toEqual([2000n, 3000n, 4000n, 5000n]); reader.close(); // An untimed track refuses it. diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index de11cacebdb..19f09af226a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -37,7 +37,7 @@ import * as Varint from "./varint.ts"; import type { Resolved, Window } from "./window.ts"; import type { Advertised, Advertisements } from "./wire.ts"; -/** What a null {@link Delay.max} goes out as, in milliseconds: the largest value every peer can read, as Rust sends for `None`. */ +/** A null {@link Delay.max} in milliseconds, which the model holds as the largest value every peer can read. */ export const NO_MAX_DELAY = Varint.MAX_U53; /** A datagram track's properties as the stream track info a wire answers with: no groups, so no age, refresh, or compression. */ @@ -52,6 +52,12 @@ export function maxDelayOf(subscription: Pick): number { return max?.asMillis() ?? 0; } +/** A subscription's {@link Delay.max} in milliseconds as SUBSCRIBE carries it: null for no limit. */ +export function wireMaxDelay(subscription: Pick): number | null { + const max = maxDelayOf(subscription); + return max < NO_MAX_DELAY ? max : null; +} + /** A subscription's {@link Delay.min} in milliseconds as the wire carries it: undefined when not stated, omitted for zero. */ export function minDelayOf(subscription: Pick): number | undefined { const min = subscription.delay?.min; @@ -517,6 +523,8 @@ export interface ResumeSource { objectLargest(): Position | undefined; /** The serving copy's largest location now, and whether it can still advance. */ peekLargest(): { largest?: Position; ended: boolean }; + /** Whether `position` is the serving copy's largest and its group ended there. */ + largestFinished(position: Position): boolean; /** * The serving copy's largest location once within the reader's cursor and newer than `seen`, * or undefined once the logical track ends. @@ -705,8 +713,11 @@ export const hooks: { cachedLargest: (producer: Producer) => Position | undefined; /** The publisher priority from a demanded track's committed {@link Info}; assigned by `track.ts`. */ demandPriority: (demand: Demand) => number; - /** Seed a received track from the publisher's reported edge; assigned by `track.ts`. */ - reportedLargest: (producer: Producer, largest: Position | undefined) => void; + /** + * Seed a received track from the publisher's reported edge, and whether its group ended there; + * assigned by `track.ts`. + */ + reportedLargest: (producer: Producer, largest: Position | undefined, finished: boolean) => void; /** * Seed a received track from the publisher's reported group alone, whose frame is unknown, * so it names no object; assigned by `track.ts`. @@ -836,6 +847,8 @@ export const hooks: { mayLand: (subscriber: Subscriber, land: Land) => boolean; /** A subscriber's largest location now, and whether it can still advance. */ peekLargest: (subscriber: Subscriber) => { largest?: Position; ended: boolean }; + /** Whether `position` is a subscriber's largest and its group ended there, so no frame follows it. */ + largestFinished: (subscriber: Subscriber, position: Position) => boolean; /** Wake once a subscriber's largest location or its end may have changed; fires at most once. */ largestChanged: (subscriber: Subscriber, fn: () => void) => Dispose; /** A subscriber that reads its routes' copies through `source` instead of a buffer of its own. */ @@ -1173,6 +1186,9 @@ export const hooks: { peekLargest: () => { throw new Error("track.ts not loaded"); }, + largestFinished: () => { + throw new Error("track.ts not loaded"); + }, largestChanged: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index a4f33c9dc93..6606548275c 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -7,7 +7,7 @@ import { Producer as BroadcastProducer } from "../broadcast.ts"; import { fromTransport, ProtocolViolation, SessionCode, StreamCode, StreamError, toStreamCode } from "../error.ts"; import type { Producer as GroupProducer } from "../group.ts"; import { randomHop } from "../hop.ts"; -import { hooks, staleHole } from "../internal.ts"; +import { hooks, NO_MAX_DELAY, staleHole } from "../internal.ts"; import { createMockTransportPair, manual, settlesWithin, textFrame } from "../mock.ts"; import { lines } from "../open.ts"; import { Producer as OriginProducer } from "../origin.ts"; @@ -723,6 +723,8 @@ async function servedSubscription( reported?: bigint; // Leave the track unresolved until `accept`, as an on-demand track the SUBSCRIBE beats. pending?: boolean; + // The `Subscriber Max Age` as decoded, in place of the scheduling tests' wide one. + maxDelay?: number | null; } = {}, ) { const version = options.version ?? Version.DRAFT_05; @@ -789,6 +791,7 @@ async function servedSubscription( // than only for what reached the wire. It reports failures by tearing down, never by // rejecting. msg.ranges = options.ranges; + if (options.maxDelay !== undefined) msg.maxDelay = options.maxDelay; const serving = publisher.runSubscribe(msg, server); const opened = pair.client.incomingUnidirectionalStreams.getReader(); @@ -921,7 +924,7 @@ test("lite-07 SUBSCRIBE_START names each resolved range start", async () => { ranges: [ { start: { relative: 1n } }, // Group 1 starts at 1 ms. - { start: { time: 1 }, end: { absolute: 2n } }, + { start: { time: 1n }, end: { absolute: 2n } }, // Empty, so it starts nowhere. { start: { absolute: 3n }, end: { absolute: 3n } }, // Empty only once its start resolves to group 4. @@ -1033,84 +1036,6 @@ test("lite-07 SUBSCRIBE_STARTED reports an added range's start, which later upda } }); -// A time start resolves once too: a newer group starting before its time doesn't move it once -// an update leaves the range live. Mirrors the Rust `lite07_an_added_time_start_keeps_its_start`. -test("lite-07 keeps where an added time start resolved", async () => { - const version = Version.DRAFT_07; - const sub = await servedSubscription({ - version, - prefill: [0n, 1n, 2n, 3n, 4n], - maxAge: Duration.millis(3_600_000), - ranges: [{ start: { absolute: 0n }, end: { absolute: 1n } }], - }); - const next = async () => { - for (;;) { - const resp = await decodeSubscribeResponse(sub.client.reader, version); - if ("start" in resp || "started" in resp) return resp; - } - }; - try { - const start = await next(); - if (!("start" in start)) throw new Error("expected SUBSCRIBE_OK"); - - // 10 ms falls in group 4, the newest one starting at or before it. - await replayUpdate({ priority: 0, ranges: [{ start: { time: 10 } }] }).encode(sub.client.writer, version); - const started = await next(); - if (!("started" in started)) throw new Error("expected SUBSCRIBE_STARTED"); - expect([started.started.id, started.started.start]).toEqual([1n, 4n]); - - // Group 5 starts at 5 ms, before 10 ms, and another update leaves the range live: it - // still starts at 4. - sub.serve(5n); - await replayUpdate({ priority: 0, ranges: [{ start: { absolute: 9n } }] }).encode(sub.client.writer, version); - const pinned = await next(); - if (!("started" in pinned)) throw new Error("expected SUBSCRIBE_STARTED"); - expect(pinned.started.id).toBe(2n); - const ranges = sub.track.subscription.peek()?.ranges ?? []; - expect(ranges.some((range) => range.start?.absolute === 4n)).toBe(true); - expect(ranges.some((range) => range.start?.time !== undefined)).toBe(false); - } finally { - await sub.close(); - } -}); - -// Group 0 included: a time start that resolved to group 0 names it, so a newer group starting -// before its time doesn't move it either. -test("lite-07 keeps an added time start that resolved to group 0", async () => { - const version = Version.DRAFT_07; - const sub = await servedSubscription({ - version, - prefill: [0n], - maxAge: Duration.millis(3_600_000), - ranges: [{ start: { absolute: 0n }, end: { absolute: 1n } }], - }); - const next = async () => { - for (;;) { - const resp = await decodeSubscribeResponse(sub.client.reader, version); - if ("start" in resp || "started" in resp) return resp; - } - }; - try { - if (!("start" in (await next()))) throw new Error("expected SUBSCRIBE_OK"); - - // 10 ms falls in group 0, the only group. - await replayUpdate({ priority: 0, ranges: [{ start: { time: 10 } }] }).encode(sub.client.writer, version); - const started = await next(); - if (!("started" in started)) throw new Error("expected SUBSCRIBE_STARTED"); - expect([started.started.id, started.started.start]).toEqual([1n, 0n]); - - // Group 1 starts at 1 ms, before 10 ms; the range still starts at group 0. - sub.serve(1n); - await replayUpdate({ priority: 0, ranges: [{ start: { absolute: 9n } }] }).encode(sub.client.writer, version); - if (!("started" in (await next()))) throw new Error("expected SUBSCRIBE_STARTED"); - const ranges = sub.track.subscription.peek()?.ranges ?? []; - expect(ranges.some((range) => range.start?.time !== undefined)).toBe(false); - expect(ranges.some((range) => range.start?.absolute === 0n && range.end === undefined)).toBe(true); - } finally { - await sub.close(); - } -}); - // An edit naming a Range ID the subscription never assigned violates the protocol. test("lite-07 refuses an update retiring an unknown Range ID", async () => { const version = Version.DRAFT_07; @@ -1151,23 +1076,6 @@ test("lite-07 answers a bounded window that resolves empty and FINs in reply", a } }); -// A time anchor waits for the track's timescale. On an on-demand track that lookup is the -// subscription's own request, so the track it answers is the one served. -test("lite-07 serves a time range from the on-demand track its lookup resolved", async () => { - const sub = await servedSubscription({ - version: Version.DRAFT_07, - pending: true, - ranges: [{ start: { time: 0 } }], - }); - try { - await sub.accept(); - sub.serve(0n); - expect(await sub.servedSequence()).toBe(0n); - } finally { - await sub.close(); - } -}); - // A relay can ingest back-to-back groups micro-reordered (the upstream leg sends // newest-first). The older group is cached and in demand, so serving must still // deliver it; a sequence cursor would skip it permanently. @@ -3119,11 +3027,10 @@ test("runProbe rounds a fractional smoothedRtt instead of killing the stream", a test("a version without the latency field serves a non-dropping budget", async () => { for (const version of [Version.DRAFT_01, Version.DRAFT_02]) { - const sub = await servedSubscription({ version, maxAge: Duration.millis(Number.MAX_SAFE_INTEGER) }); + // These drafts carry no max age, which decodes as no limit. + const sub = await servedSubscription({ version, maxDelay: null }); try { - // These drafts decode the absent field as zero. The publisher must not turn - // that into a live-edge request the peer never made. - expect(sub.track.subscription.peek()?.delay?.max).toEqual(Duration.millis(Number.MAX_SAFE_INTEGER)); + expect(sub.track.subscription.peek()?.delay?.max).toEqual(Duration.millis(NO_MAX_DELAY)); } finally { await sub.close(); } @@ -3611,7 +3518,8 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti const response = await decodeSubscribeResponse(client.reader, version); if (!("start" in response)) throw new Error("expected SUBSCRIBE_OK"); expect(response.start.starts[0]).toBe(startGroup); - expect(response.start.largest).toEqual({ group: 0n, frame: 0 }); + // The group finished, so the answer says it ended. + expect(response.start.largest).toEqual({ position: { group: 0n, frame: 0 }, ended: true }); } finally { client.close(); publisher.close(); @@ -3625,40 +3533,46 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti // A relay that holds only the first group of a backlog answers with the largest its source // reported, so a live joiner downstream starts at the newest group rather than the oldest one -// the budget serves. -test("lite draft-07 reports the source's largest position past what a relay holds", async () => { - const version = Version.DRAFT_07; - const pair = createMockTransportPair(ALPN_07_WIP); - const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); - const broadcast = publish(origin, Path.from("relayed")); - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); - // The source answered with group 4 as its largest; only group 0 has landed. - hooks.reportedLargest(track, { group: 4n, frame: 0 }); - const group = track.createGroup(0n); - group.writeFrame(textFrame("oldest")); - group.finish(); - const client = await Stream.open(pair.client, { version }); - const server = await Stream.accept(pair.server, version); - if (!server) throw new Error("missing subscribe stream"); - const running = publisher.runSubscribe( - replaySubscribe({ id: 0n, broadcast: Path.from("relayed"), track: "video", priority: 0 }), - server, - ); - try { - const response = await decodeSubscribeResponse(client.reader, version); - if (!("start" in response)) throw new Error("expected SUBSCRIBE_START"); - expect([response.start.starts[0], response.start.largest]).toEqual([0n, { group: 4n, frame: 0 }]); - } finally { - client.close(); - publisher.close(); - broadcast.close(); - origin.close(); - pair.client.close(); - pair.server.close(); - await running; - } -}); +// the budget serves, and says whether the source reported that group ended. +test.each([false, true])( + "lite draft-07 reports the source's largest position past what a relay holds, ended %p", + async (ended) => { + const version = Version.DRAFT_07; + const pair = createMockTransportPair(ALPN_07_WIP); + const origin = new OriginProducer(); + const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const broadcast = publish(origin, Path.from("relayed")); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // The source answered with group 4 as its largest; only group 0 has landed. + hooks.reportedLargest(track, { group: 4n, frame: 0 }, ended); + const group = track.createGroup(0n); + group.writeFrame(textFrame("oldest")); + group.finish(); + const client = await Stream.open(pair.client, { version }); + const server = await Stream.accept(pair.server, version); + if (!server) throw new Error("missing subscribe stream"); + const running = publisher.runSubscribe( + replaySubscribe({ id: 0n, broadcast: Path.from("relayed"), track: "video", priority: 0 }), + server, + ); + try { + const response = await decodeSubscribeResponse(client.reader, version); + if (!("start" in response)) throw new Error("expected SUBSCRIBE_START"); + expect([response.start.starts[0], response.start.largest]).toEqual([ + 0n, + { position: { group: 4n, frame: 0 }, ended }, + ]); + } finally { + client.close(); + publisher.close(); + broadcast.close(); + origin.close(); + pair.client.close(); + pair.server.close(); + await running; + } + }, +); for (const version of [Version.DRAFT_03, Version.DRAFT_04, Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { test(`Report consumes PROBE targets and observes their FIN (${version})`, async () => { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 2bcc23536ed..239c2da91d2 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -65,7 +65,6 @@ import { Group as GroupMessage } from "./group.ts"; import { Probe } from "./probe.ts"; import { encodeSubscribeResponse, - hasWireTime, LiveRanges, rangesOf, requestedRanges, @@ -483,21 +482,9 @@ function waitForControl(controls: SubscriptionControls): Promise { }); } -/** - * The budget to serve a peer with, given what its wire could tell us. - * - * A version without the field decodes as `0`, which is indistinguishable from a peer - * genuinely asking for the live edge. Serving that as real time would discard backlog - * a legacy subscriber never declined, so fall back to the publisher's max age alone - * and leave enforcement to the receiver, as the IETF path does for the same reason. - */ -function servingMaxDelay(version: Version, requested: number): Duration | null { - return carriesMaxDelay(version) ? Duration.millis(requested) : null; -} - -/** Whether this version's SUBSCRIBE carries Subscriber Max Age at all. */ -function carriesMaxDelay(version: Version): boolean { - return version !== Version.DRAFT_01 && version !== Version.DRAFT_02; +/** The budget a SUBSCRIBE's `Subscriber Max Age` asks for: `null` for no limit, as lite-01/02 decode. */ +function servingMaxDelay(requested: number | null): Duration | null { + return requested === null ? null : Duration.millis(requested); } /** @@ -509,7 +496,7 @@ function carriesMaxDelay(version: Version): boolean { * Pre-06 wires are the exception: their drafts define an absent `Group Start` as the * latest group, so say so explicitly rather than letting the budget reach back. Lite-03/04/05 * carry a `Subscriber Max Age`, but there it is a staleness tolerance only; lite-01/02 additionally get - * an unbounded budget so nothing is dropped under them (see {@link servingMaxDelay}), which + * an unbounded budget so nothing is dropped under them (they carry no max age, which decodes as none), which * must not read as a request to replay the whole cache on join. */ function cursorFloor(version: Version, startGroup: bigint | undefined, latest: bigint | undefined): bigint { @@ -1083,18 +1070,14 @@ export class Publisher { priority: msg.priority, order: msg.order, delay: { - max: servingMaxDelay(this.version, msg.maxDelay), + max: servingMaxDelay(msg.maxDelay), min: msg.minDelay === undefined ? null : Duration.millis(msg.minDelay), }, ranges, }); - // A time anchor counts in the timescale this peer was told, so it waits for the info. - // Meanwhile the subscription asks for nothing but holds the track it resolves, so an - // on-demand track's request answers it, rather than one released once its info lands. - const timed = hasWireTime(msg.ranges); - let ranges: track.Range[] = []; + let ranges: track.Range[]; try { - if (!timed) ranges = requestedRanges(msg, undefined); + ranges = requestedRanges(msg); } catch (err: unknown) { stream.writer.reset(error(err)); return; @@ -1102,16 +1085,6 @@ export class Publisher { // Parked past a bounded window's end: the peer reads this stream's end as the track's. const track = hooks.parked(consumer.subscribe(subscription(ranges))); serving(track); - if (timed) { - try { - const info = await untilAborted(track.info(), left.signal); - track.update(subscription(requestedRanges(msg, info.timescale ?? undefined))); - } catch (err: unknown) { - track.close(); - stream.writer.reset(error(err)); - return; - } - } if (watch.revoked()) { track.close(); return; @@ -1193,7 +1166,7 @@ export class Publisher { // Older drafts acknowledge with SUBSCRIBE_OK and stream frames verbatim. const ok = new SubscribeOk({ priority: msg.priority, - maxDelay: msg.maxDelay, + maxDelay: msg.maxDelay ?? 0, startGroup: msg.startGroup, endGroup: msg.endGroup, }); @@ -1246,10 +1219,10 @@ export class Publisher { priority: update.priority, order: update.order, delay: { - max: servingMaxDelay(this.version, update.maxDelay), + max: servingMaxDelay(update.maxDelay), min: update.minDelay === undefined ? null : Duration.millis(update.minDelay), }, - ranges: requestedRanges(update, info.timescale ?? undefined), + ranges: requestedRanges(update), }); }, }); @@ -1466,6 +1439,9 @@ export class Publisher { // The first group and the edge seen before it was popped, held until the source // resolves where its feed starts. let first: { group: group.Consumer; largest: track.Position | undefined } | undefined; + // The largest as SUBSCRIBE_OK reports it, with whether its group ended. + const answered = (position: track.Position | undefined) => + position && { position, ended: hooks.largestFinished(track, position) }; let endSent = false; // The Range IDs of the last update taken, and those an update added whose start no // SUBSCRIBE_STARTED reported yet. Lite-07 only. @@ -1815,7 +1791,7 @@ export class Publisher { startSent = true; startSequence = bounds.startGroup; raiseFloor(bounds.startGroup); - const start = new SubscribeStart(rangeStarts(bounds.startGroup), largest); + const start = new SubscribeStart(rangeStarts(bounds.startGroup), answered(largest)); if ( !(await controls.response(encodeSubscribeResponse(stream, { start }, this.version))) ) @@ -1830,7 +1806,7 @@ export class Publisher { if (end !== undefined && hooks.servingRuns(track, 0n, end).length === 0) { startSent = true; startSequence = end; - const start = new SubscribeStart(rangeStarts(end), largest); + const start = new SubscribeStart(rangeStarts(end), answered(largest)); if ( !(await controls.response(encodeSubscribeResponse(stream, { start }, this.version))) ) @@ -1857,7 +1833,7 @@ export class Publisher { ) { startSent = true; startSequence = runs[0].start; - const start = new SubscribeStart(rangeStarts(startSequence), largest); + const start = new SubscribeStart(rangeStarts(startSequence), answered(largest)); if ( !(await controls.response(encodeSubscribeResponse(stream, { start }, this.version))) ) @@ -1890,7 +1866,7 @@ export class Publisher { if (keepsSubscribeOpen(this.version) && !startSent && boundary() > 0n) { startSent = true; startSequence = hooks.servingRuns(track, 0n, boundary())[0]?.start ?? boundary(); - const start = new SubscribeStart(rangeStarts(startSequence), largest); + const start = new SubscribeStart(rangeStarts(startSequence), answered(largest)); if (!(await controls.response(encodeSubscribeResponse(stream, { start }, this.version)))) return false; continue; @@ -1973,7 +1949,7 @@ export class Publisher { !(await controls.response( encodeSubscribeResponse( stream, - { start: new SubscribeStart(rangeStarts(startSequence), largest) }, + { start: new SubscribeStart(rangeStarts(startSequence), answered(largest)) }, this.version, ), )) diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 678dc05a089..465eab601f6 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -201,7 +201,7 @@ test("lite-07 carries the span as its only range, exclusive at the end", async ( expect([open.startGroup, open.endGroup]).toEqual([undefined, undefined]); }); -test("a lite-07 list decodes as the span covering it", async () => { +test("a lite-07 list decodes its time and relative anchors", async () => { // Priority, order, max delay, and an unstated min delay as SubscribeUpdate writes them, // then no Range ID to retire, the ranges it adds, the update number, and an absent wanted group. const head = (await encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0, ranges: [] }))).slice(1, 5); @@ -214,38 +214,53 @@ test("a lite-07 list decodes as the span covering it", async () => { return { ...got, ...spanOf(Version.DRAFT_07, got.ranges ?? []) }; }; - // Groups 2 through 4 and 7 through 9: an absolute anchor is its type and group alone. - const sparse = await update([2, 1, 2, 1, 5, 1, 7, 1, 10]); - expect([sparse.startGroup, sparse.startFrame, sparse.endGroup, sparse.endFrame]).toEqual([2n, 0, 9n, undefined]); - expect(sparse.ranges).toEqual([ - { start: { absolute: 2n }, end: { absolute: 5n } }, - { start: { absolute: 7n }, end: { absolute: 10n } }, - ]); - - // The span covering a relative start has no floor; the ranges keep it for the serving reader. - const relative = await update([2, 2, 3, 1, 5, 1, 7, 1, 9]); - expect([relative.startGroup, relative.endGroup, relative.endFrame]).toEqual([undefined, 8n, undefined]); - expect(relative.ranges).toEqual([ - { start: { relative: 3n }, end: { absolute: 5n } }, - { start: { absolute: 7n }, end: { absolute: 9n } }, - ]); - // A time anchor carries ticks of the track's timescale, which only the serving track knows. - const timed = await update([1, 3, 40, 3, 90]); - expect(timed.ranges).toEqual([{ start: { time: 40 }, end: { time: 90 } }]); + // Type 1 is a time, both ends inclusive, and type 2 counts back. A time names the group it + // keys, so the span covers it, and the model reads it as that key, the end exclusive. + const timed = await update([2, 1, 40, 1, 90, 2, 3, 0]); + expect(timed.ranges).toEqual([{ start: { time: 40n }, end: { time: 90n } }, { start: { relative: 3n } }]); expect([timed.startGroup, timed.endGroup]).toEqual([undefined, undefined]); - expect(requestedRanges(timed, Timescale.MILLI)).toEqual([ - { start: { time: Timestamp.fromMillis(40) }, end: { time: Timestamp.fromMillis(90) } }, + expect(requestedRanges(timed)).toEqual([ + { start: { absolute: 40n }, end: { absolute: 91n } }, + { start: { relative: 3n } }, ]); - expect(() => requestedRanges(timed, undefined)).toThrow(TimestampMismatch); + const bounded = await update([1, 1, 40, 1, 90]); + expect([bounded.startGroup, bounded.endGroup]).toEqual([40n, 90n]); - // No start reaches back to group 0; one ending before group 5 starts covers no group. - const oldest = await update([2, 0, 1, 3, 1, 5, 1, 4]); - expect(oldest.ranges).toEqual([{ end: { absolute: 3n } }, { start: { absolute: 5n }, end: { absolute: 5n } }]); + // One ending before its start covers no group there, and keeps its place. + const reversed = await update([1, 1, 5, 1, 3]); + expect(requestedRanges(reversed)).toEqual([{ start: { absolute: 5n }, end: { absolute: 5n } }]); + + // A time past what a JS number holds exactly reads at full width. + const far = 1n << 60n; + const wide = new SubscribeUpdate({ priority: 0, ranges: [{ start: { time: far } }] }); + const got = await SubscribeUpdate.decode( + new Reader(undefined, await encodeMessage(Version.DRAFT_07, wide), Version.DRAFT_07), + Version.DRAFT_07, + ); + expect(got.ranges).toEqual([{ start: { time: far } }]); + expect(requestedRanges({ ...got, startFrame: 0 })).toEqual([{ start: { absolute: far } }]); // An update may add no range, retiring some or none. expect((await update([0])).ranges).toEqual([]); + // Any other type is a violation. + await expect(update([1, 3, 0, 0])).rejects.toThrow(ProtocolViolation); await expect(update([1, 4, 0, 0])).rejects.toThrow(ProtocolViolation); - await expect(update([1, 0, 1, 0])).rejects.toThrow(ProtocolViolation); +}); + +test("lite-07 sends an absolute anchor as a time, an end as the time before it", async () => { + const update = new SubscribeUpdate({ + priority: 0, + ranges: [{ start: { absolute: 7n }, end: { absolute: 10n } }], + }); + const got = await SubscribeUpdate.decode( + new Reader(undefined, await encodeMessage(Version.DRAFT_07, update), Version.DRAFT_07), + Version.DRAFT_07, + ); + expect(got.ranges).toEqual([{ start: { time: 7n }, end: { time: 9n } }]); + // Nothing comes before group 0, so an end there can't go out. + await expect( + encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0, ranges: [{ end: { absolute: 0n } }] })), + ).rejects.toThrow("empty subscription range cannot be encoded"); }); test("lite-07 carries every range, relative and time anchors included, and older wires the span alone", async () => { @@ -259,7 +274,7 @@ test("lite-07 carries every range, relative and time anchors included, and older ], Timescale.MILLI, ); - expect(ranges[3]).toEqual({ start: { time: 1_500 }, end: { time: 3_000 } }); + expect(ranges[3]).toEqual({ start: { time: 1_500n }, end: { time: 3_000n } }); expect(() => toWireRanges([{ start: { time: Timestamp.fromMillis(1) } }], undefined)).toThrow(TimestampMismatch); const message = new Subscribe({ id: 1n, @@ -271,7 +286,11 @@ test("lite-07 carries every range, relative and time anchors included, and older }); const decode = async (version: Version) => Subscribe.decode(new Reader(undefined, await encodeMessage(version, message), version), version); - expect((await decode(Version.DRAFT_07)).ranges).toEqual(ranges); + // Lite-07 carries an absolute anchor as a time, an end as the time before it. + expect((await decode(Version.DRAFT_07)).ranges).toEqual([ + { start: { time: 2n }, end: { time: 4n } }, + ...ranges.slice(1), + ]); const older = await decode(Version.DRAFT_05); expect([older.ranges, older.startGroup, older.endGroup]).toEqual([undefined, 0n, undefined]); await expect(encodeMessage(Version.DRAFT_07, new Subscribe({ ...message, ranges: [] }))).rejects.toThrow( @@ -286,18 +305,22 @@ test("SubscribeStart round-trips on draft-05", async () => { expect(got.start.starts).toEqual([42n]); }); -test("SubscribeStart carries the largest position on draft-07", async () => { - // Type, length, largest group + 1, largest frame, one range start plus one. - expect(await encode(Version.DRAFT_07, { start: new SubscribeStart([4n], { group: 3n, frame: 2 }) })).toEqual( - new Uint8Array([0, 4, 4, 2, 1, 5]), +test("SubscribeStart carries the largest position and whether it ended on draft-07", async () => { + const position = { group: 3n, frame: 2 }; + // Type, length, largest group + 1, largest frame, ended, one range start plus one. + expect(await encode(Version.DRAFT_07, { start: new SubscribeStart([4n], { position, ended: true }) })).toEqual( + new Uint8Array([0, 5, 4, 2, 1, 1, 5]), ); - for (const largest of [undefined, { group: 3n, frame: 2 }]) { + for (const largest of [undefined, { position, ended: false }, { position, ended: true }]) { const got = await responseRoundtrip(Version.DRAFT_07, { start: new SubscribeStart([4n], largest) }); if (!("start" in got)) throw new Error("expected start"); expect(got.start.largest).toEqual(largest); } + // Any other ended is malformed. + const malformed = new Reader(undefined, new Uint8Array([0, 5, 4, 2, 2, 1, 5]), Version.DRAFT_07); + await expect(decodeSubscribeResponse(malformed, Version.DRAFT_07)).rejects.toThrow(ProtocolViolation); // Draft-06 has no largest position on the wire. - expect(await encode(Version.DRAFT_06, { start: new SubscribeStart([4n], { group: 3n, frame: 2 }) })).toEqual( + expect(await encode(Version.DRAFT_06, { start: new SubscribeStart([4n], { position, ended: true }) })).toEqual( new Uint8Array([0, 1, 4]), ); }); @@ -493,6 +516,35 @@ test("min delay survives lite-07 and decodes as not stated on legacy wires", asy } }); +// Lite-07 sends milliseconds plus one, 0 for no limit. Earlier wires send bare milliseconds, so +// no limit goes out as the largest value every peer reads, and lite-01/02 carry none at all. +test("max delay says no limit on lite-07, and the largest safe value before it", async () => { + // After the size, the priority, and the order. + const field = async (maxDelay: number | null) => + (await encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0, maxDelay, ranges: [] })))[3]; + expect([await field(null), await field(0), await field(5)]).toEqual([0, 1, 6]); + + for (const version of [Version.DRAFT_01, Version.DRAFT_03, Version.DRAFT_06, Version.DRAFT_07]) { + for (const maxDelay of [null, 0, 250]) { + const expected = { + [Version.DRAFT_01]: null, + [Version.DRAFT_03]: maxDelay ?? Number.MAX_SAFE_INTEGER, + [Version.DRAFT_06]: maxDelay ?? Number.MAX_SAFE_INTEGER, + [Version.DRAFT_07]: maxDelay, + }[version]; + const props = { id: 1n, broadcast: Path.from("room"), track: "video", priority: 3, maxDelay }; + const subscribe = await encodeMessage(version, new Subscribe(props)); + expect((await Subscribe.decode(new Reader(undefined, subscribe, version), version)).maxDelay).toBe( + expected, + ); + const update = await encodeMessage(version, new SubscribeUpdate({ priority: 3, maxDelay, ranges: [] })); + expect((await SubscribeUpdate.decode(new Reader(undefined, update, version), version)).maxDelay).toBe( + expected, + ); + } + } +}); + test("optional subscriber milliseconds reject unsafe budgets", async () => { for (const minDelay of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1]) { await expect( @@ -551,9 +603,9 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { // same Range IDs, as the subscriber holds. Mirrors the Rust `lite07_updates_edit_only_the_changed_ranges`. test("lite-07 updates edit only the changed ranges", async () => { const version = Version.DRAFT_07; - const a = { start: { absolute: 1n }, end: { absolute: 5n } }; + const a = { start: { time: 1n }, end: { time: 4n } }; const b = { start: { relative: 3n } }; - const c = { start: { time: 9_000 } }; + const c = { start: { time: 9_000n } }; const sent = new LiveRanges(version, [a, b]); const live = new LiveRanges(version, [a, b]); const step = async (ranges: WireRange[], remove: bigint[], add: WireRange[]) => { diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 7dd534d0680..050c7a9ba5d 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -9,7 +9,7 @@ import { import type * as Instance from "../instance.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; -import { floorAt, type Timescale, Timestamp } from "../time.ts"; +import { floorAt, type Timescale } from "../time.ts"; import type { Anchor, Order, Position, Range } from "../track.ts"; import { UNBOUNDED } from "../util/sequence.ts"; import { lengthLeadingOnes, parts, split } from "../util/varint.ts"; @@ -28,6 +28,7 @@ import { hasRanges, hasRefresh, hasSkip, + hasUnlimitedMaxDelay, resolvesStart, Version, } from "./version.ts"; @@ -145,13 +146,15 @@ interface Span { } /** - * One end of a lite-07 range as the wire carries it: a model {@link Anchor}, except that a time - * counts in the track's `Timescale` as the peer was told it. + * One end of a lite-07 range: a model {@link Anchor}, except that a time counts in the track's + * `Timescale` as the peer was told it, or bare units on a scale-less track. The wire has no + * absolute anchor: a group's start is its time, so `absolute` goes out as a time, an end as the + * time just before it, and decodes as one. */ export type WireAnchor = | { absolute: bigint; relative?: never; time?: never } | { relative: bigint; absolute?: never; time?: never } - | { time: number; absolute?: never; relative?: never }; + | { time: bigint; absolute?: never; relative?: never }; /** A lite-07 range as the wire carries it; see {@link WireAnchor}. */ export interface WireRange { @@ -167,7 +170,7 @@ export function toWireRanges(ranges: readonly Range[], timescale: Timescale | un const anchor = (anchor: Anchor | undefined): WireAnchor | undefined => { if (anchor?.time === undefined) return anchor as WireAnchor | undefined; if (timescale === undefined) throw new TimestampMismatch(); - return { time: floorAt(anchor.time, timescale) }; + return { time: BigInt(floorAt(anchor.time, timescale)) }; }; return ranges.map((range) => { const out: WireRange = {}; @@ -179,24 +182,31 @@ export function toWireRanges(ranges: readonly Range[], timescale: Timescale | un }); } -/** Whether any range starts or ends at a presentation time, which needs the track's timescale. */ -export function hasWireTime(ranges: readonly WireRange[] | undefined): boolean { - return ranges?.some((range) => range.start?.time !== undefined || range.end?.time !== undefined) ?? false; +/** + * The lite-07 type and value of a range's start or `end`, `undefined` for none. Both time ends are + * inclusive, so an absolute end, exclusive, goes out as the time just before it; one at group 0 + * holds nothing a time can say. + */ +function wireAnchor(anchor: WireAnchor | undefined, end: boolean): [number, bigint?] { + if (anchor?.absolute !== undefined) { + if (!end) return [1, anchor.absolute]; + if (anchor.absolute === 0n) throw new Error(EMPTY_RANGE); + return [1, anchor.absolute - 1n]; + } + if (anchor?.relative !== undefined) return [2, anchor.relative]; + if (anchor?.time !== undefined) return [1, anchor.time]; + return [0]; } -/** Encode one lite-07 range end, `undefined` for none: an absolute end stops before its group. */ -async function encodeAnchor(w: Writer, anchor: WireAnchor | undefined) { - if (anchor?.absolute !== undefined) { - await w.u53(1); - await w.u62(anchor.absolute); - } else if (anchor?.relative !== undefined) { - await w.u53(2); - await w.u62(anchor.relative); - } else if (anchor?.time !== undefined) { - await w.u53(3); - await w.u53(anchor.time); - } else { - await w.u53(0); +/** Encode one lite-07 range, its start then its end; see {@link wireAnchor}. */ +async function encodeRange(w: Writer, range: WireRange) { + for (const [anchor, end] of [ + [range.start, false], + [range.end, true], + ] as const) { + const [kind, value] = wireAnchor(anchor, end); + await w.u53(kind); + if (value !== undefined) await w.u62(value); } } @@ -209,10 +219,7 @@ async function encodeSpan(w: Writer, version: Version, span: Span, ranges?: read if (ranges !== undefined && hasRanges(version)) { if (ranges.length === 0) throw new Error(EMPTY_RANGE); await w.u53(ranges.length); - for (const range of ranges) { - await encodeAnchor(w, range.start); - await encodeAnchor(w, range.end); - } + for (const range of ranges) await encodeRange(w, range); return; } if (!hasRanges(version)) { @@ -229,26 +236,30 @@ async function encodeSpan(w: Writer, version: Version, span: Span, ranges?: read const range: WireRange = {}; if (span.startGroup !== undefined) range.start = { absolute: span.startGroup }; if (span.endGroup !== undefined) range.end = { absolute: span.endGroup + 1n }; - await encodeAnchor(w, range.start); - await encodeAnchor(w, range.end); + await encodeRange(w, range); } /** * The model ranges a decoded SUBSCRIBE or SUBSCRIBE_UPDATE asks for: its lite-07 list, or the one - * span an older wire carries, whole groups either way. A time anchor counts in `timescale`, the - * track's as the peer was told it, and is refused with {@link TimestampMismatch} without one. + * span an older wire carries, whole groups either way. + * + * A lite-07 time names a group by its key: the wire's group ID is its start time. The JS model + * still keys groups by sequence, so a time decodes as that absolute key, an end exclusive, on + * every track; resolving it against frame timestamps waits on the model keying groups by start. */ -export function requestedRanges(msg: Span & { ranges?: WireRange[] }, timescale: Timescale | undefined): Range[] { +export function requestedRanges(msg: Span & { ranges?: WireRange[] }): Range[] { if (msg.ranges) { - const anchor = (anchor: WireAnchor | undefined): Anchor | undefined => { + const anchor = (anchor: WireAnchor | undefined, end: boolean): Anchor | undefined => { if (anchor?.time === undefined) return anchor as Anchor | undefined; - if (timescale === undefined) throw new TimestampMismatch(); - return { time: new Timestamp(anchor.time, timescale) }; + return { absolute: end ? anchor.time + 1n : anchor.time }; }; return msg.ranges.map((range) => { const out: Range = {}; - const start = anchor(range.start); - const end = anchor(range.end); + const start = anchor(range.start, false); + let end = anchor(range.end, true); + // Ending before its start: keep its place, covering no group, as the Rust publisher does. + if (start?.absolute !== undefined && end?.absolute !== undefined && end.absolute < start.absolute) + end = { absolute: start.absolute }; if (start) out.start = start; if (end) out.end = end; return out; @@ -260,18 +271,16 @@ export function requestedRanges(msg: Span & { ranges?: WireRange[] }, timescale: return [range]; } -/** Decode one lite-07 range end, `undefined` for none. */ +/** Decode one lite-07 range end, `undefined` for none: a time, inclusive as an end, or a count back. */ async function decodeAnchor(r: Reader): Promise { const kind = await r.u53(); switch (kind) { case 0: return undefined; case 1: - return { absolute: await r.u62() }; + return { time: await r.u62() }; case 2: return { relative: await r.u62() }; - case 3: - return { time: await r.u53() }; default: throw new ProtocolViolation(`unknown range anchor: ${kind}`); } @@ -284,9 +293,6 @@ async function decodeRange(r: Reader): Promise { const range: WireRange = {}; if (start) range.start = start; if (end) range.end = end; - // Ending at or before its start: keep its place, covering no group, as the Rust publisher does. - if (start?.absolute !== undefined && end?.absolute !== undefined && end.absolute < start.absolute) - range.end = { absolute: start.absolute }; return range; } @@ -308,8 +314,9 @@ export function spanOf(version: Version, ranges: readonly WireRange[]): Span & { let floor = true; let live = false; for (const range of ranges) { - const from = range.start?.absolute; - const to = range.end?.absolute; + // A time is the key of the group it names, inclusive as an end. + const from = range.start?.absolute ?? range.start?.time; + const to = range.end?.absolute ?? (range.end?.time === undefined ? undefined : range.end.time + 1n); if (from === undefined) floor = false; else if (start === undefined || from < start) start = from; if (to === undefined) live = true; @@ -363,13 +370,13 @@ function rangeSize(range: WireRange): number { const lo = split(value); return lengthLeadingOnes(parts.hi, lo); }; - const anchor = (anchor: WireAnchor | undefined): number => { - if (anchor?.absolute !== undefined) return size(1) + size(anchor.absolute); - if (anchor?.relative !== undefined) return size(2) + size(anchor.relative); - if (anchor?.time !== undefined) return size(3) + size(anchor.time); - return size(0); + const anchor = (anchor: WireAnchor | undefined, end: boolean): number => { + // An end at group 0 can't go out, which encoding refuses; size it as the smallest. + if (end && anchor?.absolute === 0n) return size(1) + size(0); + const [kind, value] = wireAnchor(anchor, end); + return size(kind) + (value === undefined ? 0 : size(value)); }; - return anchor(range.start) + anchor(range.end); + return anchor(range.start, false) + anchor(range.end, true); } /** A range's anchors as a key, so equal ranges compare equal. */ @@ -597,6 +604,24 @@ async function encodeMinDelay(w: Writer, version: Version, minDelay: number | un await Duration.encodeOptional(w, minDelay); } +/** What lite-03 to lite-06 send for no `Subscriber Max Age` limit, which their bare milliseconds can't say. */ +const MAX_SAFE_DELAY_MS = Number.MAX_SAFE_INTEGER; + +/** + * Encode the `Subscriber Max Age`, `null` for no limit: on lite-07 milliseconds plus one, 0 for + * no limit, and before it bare milliseconds. + */ +async function encodeMaxDelay(w: Writer, version: Version, maxDelay: number | null) { + if (hasUnlimitedMaxDelay(version)) await Duration.encodeOptional(w, maxDelay ?? undefined); + else await w.u53(maxDelay ?? MAX_SAFE_DELAY_MS); +} + +/** Decode the inverse of {@link encodeMaxDelay}. */ +async function decodeMaxDelay(r: Reader, version: Version): Promise { + if (hasUnlimitedMaxDelay(version)) return (await Duration.decodeOptional(r)) ?? null; + return r.u53(); +} + /** Decode the `Subscriber Min Age`, as not stated on a wire without the field. */ async function decodeMinDelay(r: Reader, version: Version): Promise { if (!hasMinDelay(version)) return undefined; @@ -609,8 +634,11 @@ export class SubscribeUpdate { priority: number; /** See {@link Subscribe.order}. */ order: Order; - /** Subscriber max delay in milliseconds; zero skips once a newer group is available. */ - maxDelay: number; + /** + * Subscriber max delay in milliseconds, `null` for no limit beyond the publisher's; zero skips + * once a newer group is available. Lite-01/02 carry none and decode as `null`. + */ + maxDelay: number | null; /** * Subscriber min delay (`Subscriber Min Age`) in milliseconds, or undefined when not stated. * Lite-07+; earlier wires decode it as not stated and drop it on encode. @@ -636,7 +664,7 @@ export class SubscribeUpdate { priority: number; wantedGroup?: bigint; order?: Order; - maxDelay?: number; + maxDelay?: number | null; minDelay?: number; startGroup?: bigint; endGroup?: bigint; @@ -651,7 +679,7 @@ export class SubscribeUpdate { this.wantedGroup = props.wantedGroup; this.priority = props.priority; this.order = props.order ?? "descending"; - this.maxDelay = props.maxDelay ?? 0; + this.maxDelay = props.maxDelay === undefined ? 0 : props.maxDelay; this.minDelay = props.minDelay; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -671,7 +699,7 @@ export class SubscribeUpdate { default: await w.u8(toWire(this.priority)); await encodeOrder(w, version, this.order); - await w.u53(this.maxDelay); + await encodeMaxDelay(w, version, this.maxDelay); await encodeMinDelay(w, version, this.minDelay); if (hasRanges(version)) { // An edit of the live ranges, which may add none: `ranges`, or else the span as @@ -685,10 +713,7 @@ export class SubscribeUpdate { await encodeSpan(w, version, this); } else { await w.u53(this.ranges.length); - for (const range of this.ranges) { - await encodeAnchor(w, range.start); - await encodeAnchor(w, range.end); - } + for (const range of this.ranges) await encodeRange(w, range); } } else { await encodeSpan(w, version, this, this.ranges); @@ -703,11 +728,11 @@ export class SubscribeUpdate { switch (version) { case Version.DRAFT_01: case Version.DRAFT_02: - return new SubscribeUpdate({ priority: fromWire(await r.u8()) }); + return new SubscribeUpdate({ priority: fromWire(await r.u8()), maxDelay: null }); default: { const priority = fromWire(await r.u8()); const order = await decodeOrder(r, version); - const maxDelay = await r.u53(); + const maxDelay = await decodeMaxDelay(r, version); const minDelay = await decodeMinDelay(r, version); let span: Span & { ranges?: WireRange[]; remove?: bigint[] }; if (hasRanges(version)) { @@ -764,8 +789,11 @@ export class Subscribe { * cannot ask for anything else. */ order: Order; - /** Subscriber max delay in milliseconds; zero skips once a newer group is available. */ - maxDelay: number; + /** + * Subscriber max delay in milliseconds, `null` for no limit beyond the publisher's; zero skips + * once a newer group is available. Lite-01/02 carry none and decode as `null`. + */ + maxDelay: number | null; /** * Subscriber min delay (`Subscriber Min Age`) in milliseconds, or undefined when not stated. * Lite-07+; earlier wires decode it as not stated and drop it on encode. @@ -810,7 +838,7 @@ export class Subscribe { track: string; priority: number; order?: Order; - maxDelay?: number; + maxDelay?: number | null; minDelay?: number; startGroup?: bigint; endGroup?: bigint; @@ -827,7 +855,7 @@ export class Subscribe { this.track = props.track; this.priority = props.priority; this.order = props.order ?? "descending"; - this.maxDelay = props.maxDelay ?? 0; + this.maxDelay = props.maxDelay === undefined ? 0 : props.maxDelay; this.minDelay = props.minDelay; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -851,7 +879,7 @@ export class Subscribe { break; default: await encodeOrder(w, version, this.order); - await w.u53(this.maxDelay); + await encodeMaxDelay(w, version, this.maxDelay); await encodeMinDelay(w, version, this.minDelay); await encodeSpan(w, version, this, this.ranges); break; @@ -870,10 +898,10 @@ export class Subscribe { switch (version) { case Version.DRAFT_01: case Version.DRAFT_02: - return new Subscribe({ id, broadcast, track, priority }); + return new Subscribe({ id, broadcast, track, priority, maxDelay: null }); default: { const order = await decodeOrder(r, version); - const maxDelay = await r.u53(); + const maxDelay = await decodeMaxDelay(r, version); const minDelay = await decodeMinDelay(r, version); const span = await decodeSpan(r, version); const update = await decodeUpdate(r, version); @@ -993,6 +1021,14 @@ export class SubscribeOk { } } +/** The publisher's largest position, as SUBSCRIBE_OK reports it. Mirrors the Rust `Largest`. */ +export interface Largest { + /** The newest group and its last frame so far. */ + position: Position; + /** The group ended at that frame, so no frame follows it: a reader knows at once that it isn't the live one. */ + ended: boolean; +} + /** * Resolves where a Draft-05+ subscription starts. The first message the publisher sends, * once the start is known. A start above the requested one implicitly drops the groups @@ -1010,12 +1046,12 @@ export class SubscribeStart { starts: (bigint | undefined)[]; /** - * The publisher's largest (group, frame) when it answered, or `undefined` for a track - * with nothing yet. Draft-07+ only; not on the wire before, where it decodes as `undefined`. + * The publisher's largest when it answered, or `undefined` for a track with nothing yet. + * Draft-07+ only; not on the wire before, where it decodes as `undefined`. */ - largest?: Position; + largest?: Largest; - constructor(starts: (bigint | undefined)[], largest?: Position) { + constructor(starts: (bigint | undefined)[], largest?: Largest) { this.starts = starts; this.largest = largest; } @@ -1028,12 +1064,14 @@ export class SubscribeStart { if (group === undefined || rest.length > 0) throw new Error("one start group before draft-07"); return w.u62(group); } - // Group + 1, so 0 is a track with nothing yet; the frame follows only otherwise. + // Group + 1, so 0 is a track with nothing yet; the frame and whether the group ended + // follow only otherwise. if (this.largest === undefined) { await w.u53(0); } else { - await w.u62(this.largest.group + 1n); - await w.u53(this.largest.frame); + await w.u62(this.largest.position.group + 1n); + await w.u53(this.largest.position.frame); + await w.u8(this.largest.ended ? 1 : 0); } await w.u53(this.starts.length); for (const start of this.starts) await w.u62(start === undefined ? 0n : start + 1n); @@ -1044,7 +1082,13 @@ export class SubscribeStart { return Message.decode(r, async (r) => { if (!hasRanges(version)) return new SubscribeStart([await r.u62()]); const wire = await r.u62(); - const largest = wire === 0n ? undefined : { group: wire - 1n, frame: await r.u53() }; + let largest: Largest | undefined; + if (wire !== 0n) { + const position = { group: wire - 1n, frame: await r.u53() }; + const ended = await r.u8(); + if (ended > 1) throw new ProtocolViolation(`invalid Largest Ended: ${ended}`); + largest = { position, ended: ended === 1 }; + } // Not preallocated: each start costs a byte of the bounded message. const starts: (bigint | undefined)[] = []; for (let count = await r.u53(); count > 0; count--) { diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 054c2bf826f..22c534259ad 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -37,6 +37,7 @@ import { insertRun, maxDelayOf, minDelayOf, + NO_MAX_DELAY, type Run, removeRun, runGaps, @@ -44,6 +45,7 @@ import { scopeHead, scopeOverlaps, staleHole, + wireMaxDelay, } from "../internal.ts"; import type { Lister } from "../listing.ts"; import * as Mint from "../mint.ts"; @@ -230,9 +232,9 @@ interface SubscribeEntry { // The number of the latest SUBSCRIBE (0) or SUBSCRIBE_UPDATE sent: a stale drop given up under // an earlier one is no verdict on the current terms. update: bigint; - // The max delay the latest SUBSCRIBE or SUBSCRIBE_UPDATE asked for, in milliseconds: the budget - // a stale drop under it was judged by. - maxDelay?: number; + // The max delay the latest SUBSCRIBE or SUBSCRIBE_UPDATE asked for, in milliseconds, null for + // no limit: the budget a stale drop under it was judged by. + maxDelay?: number | null; // The runs `tail` accounts for by a stale drop under `update`: the next update reopens them, // since the publisher re-offers or drops them again under it. // Coalesced, so a peer repeating a drop holds one run, not one per message. @@ -2134,7 +2136,7 @@ export class Subscriber { track: name, priority: subscription.priority ?? 0, order: subscription.order, - maxDelay: maxDelayOf(subscription), + maxDelay: wireMaxDelay(subscription), minDelay: minDelayOf(subscription), startGroup: span.start, endGroup: inclusiveGroupEnd(span.end), @@ -3244,7 +3246,8 @@ export class Subscriber { // whatever an update changed since. if (hasRanges(this.version)) this.#declare(entry); else hooks.startTrack(entry.track, { start: entry.start, requested: entry.requested }); - hooks.reportedLargest(entry.track, resp.start.largest); + // Recorded whole, so a relay answers its own readers that the group ended. + hooks.reportedLargest(entry.track, resp.start.largest?.position, resp.start.largest?.ended ?? false); // The groups the SUBSCRIBE asked for below it are not waited for, whatever the // demand asks later. One that still arrives is delivered. if (entry.requested !== undefined && start !== undefined) entry.tail.account(entry.requested, start); @@ -3317,7 +3320,9 @@ export class Subscriber { // A paused group the drop names ends there: no continuation follows. this.#dropPaused(entry, start, end, error, stale ? update : undefined); // Judged under the budget this subscriber sent with that update. - const hole = stale ? staleHole(entry.maxDelay ?? 0) : { error }; + const hole = stale + ? staleHole(entry.maxDelay === null ? NO_MAX_DELAY : (entry.maxDelay ?? 0)) + : { error }; // A group whose stream finished under this update was served over a stale drop, so it // won, even once the cache evicted it. const named = stale ? entry.tail.unfinished(start, end) : [{ start, end }]; @@ -3402,7 +3407,7 @@ export class Subscriber { if (!entry.starts.has(id)) return false; const at = entry.starts.get(id); if (at === undefined) continue; - const [model] = requestedRanges({ startFrame: 0, ranges: [range] }, entry.scale); + const [model] = requestedRanges({ startFrame: 0, ranges: [range] }); owed.push({ ...model, start: { absolute: at } }); } const window = new Window(owed, entry.track.largest()?.group); @@ -3445,7 +3450,7 @@ export class Subscriber { priority: msg.priority, order: msg.order, delay: { - max: Duration.millis(msg.maxDelay), + max: msg.maxDelay === null ? null : Duration.millis(msg.maxDelay), min: msg.minDelay === undefined ? null : Duration.millis(msg.minDelay), }, ranges: entry.asked, @@ -3539,7 +3544,7 @@ export class Subscriber { wantedGroup: refresh ?? sentWanted, priority, order: current.order, - maxDelay: maxDelayOf(current), + maxDelay: wireMaxDelay(current), minDelay: minDelayOf(current), startGroup: span.start, endGroup: inclusiveGroupEnd(span.end), diff --git a/js/net/src/lite/tail.test.ts b/js/net/src/lite/tail.test.ts index eb67e1f148f..7155c73f9ae 100644 --- a/js/net/src/lite/tail.test.ts +++ b/js/net/src/lite/tail.test.ts @@ -374,7 +374,8 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver // Lite-07 retires the range and adds the lowered one, whose start SUBSCRIBE_STARTED reports. const lowered = await update(); if (hasRanges(version)) { - expect([lowered.remove, lowered.ranges]).toEqual([[0n], [{ start: { absolute: 1n } }]]); + // A group key goes out as the time it starts at. + expect([lowered.remove, lowered.ranges]).toEqual([[0n], [{ start: { time: 1n } }]]); await respond({ started: new SubscribeStarted(1n, 1n) }); } await respond({ finish: new SubscribeFinish(4n) }); @@ -504,7 +505,7 @@ test("lite-07 FIN waits for the skipped and reset final range to settle", async test("draft-07's SUBSCRIBE_START says the largest before any group arrives", async () => { const { reader, respond } = await subscribed(Version.DRAFT_07); - await respond({ start: new SubscribeStart([4n], { group: 4n, frame: 2 }) }); + await respond({ start: new SubscribeStart([4n], { position: { group: 4n, frame: 2 }, ended: false }) }); expect(await reader.largest()).toEqual({ group: 4n, frame: 2 }); reader.close(); }); diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 0d9d1e668d8..267b4190d87 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -272,6 +272,23 @@ export function hasOrder(version: Version): boolean { } } +/** Whether SUBSCRIBE and SUBSCRIBE_UPDATE's `Subscriber Max Age` is milliseconds plus one, so 0 + * says no limit. Added in lite-07; earlier wires carry bare milliseconds. */ +export function hasUnlimitedMaxDelay(version: Version): boolean { + // Explicitly list older versions so future versions keep the lite-07+ behavior. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } +} + /** Whether SUBSCRIBE and SUBSCRIBE_UPDATE carry the optional `Subscriber Min Age`. Added in * lite-07; an earlier subscription decodes it as not stated. */ export function hasMinDelay(version: Version): boolean { diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index ac9a55e89f7..4619247b6cc 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -1469,6 +1469,12 @@ class Reader implements ResumeSource { return serving ? hooks.objectLargest(serving.sub) : this.#ended?.object; } + largestFinished(position: track.Position): boolean { + this.sync(); + const serving = this.#serving(); + return serving !== undefined && hooks.largestFinished(serving.sub, position); + } + peekLargest(): { largest?: track.Position; ended: boolean } { this.sync(); const serving = this.#serving(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0ce09c6b669..6fc8d706748 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -773,6 +773,9 @@ class TrackState { first?: bigint; // Set once {@link largest} can no longer advance while the track stays open. largestEnded = new Signal(false); + // Whether {@link largest}'s group ended there: it closed cleanly, or its source said so. An + // aborted one stays open, since it can be recreated or fetched. + largestFinished = false; constructor(subscription?: Subscription) { this.update = new Signal(subscription === undefined ? undefined : subscriptionDefaults(subscription)); @@ -1131,8 +1134,6 @@ export class Producer { // has landed yet. #refresh = false; #demand: Demand; - // The largest group may still grow until it closes cleanly; an aborted one can be recreated. - #largestOpen = false; // Only real objects or upstream metadata advance this, never the head of an empty group. #objectLargest?: Position; @@ -1348,7 +1349,12 @@ export class Producer { for (const state of [producer.#state, ...producer.#sinks]) state.startChanged.update((rev) => rev + 1); }; hooks.cachedLargest = (producer) => producer.#cachedLargest(); - hooks.reportedLargest = (producer, largest) => producer.#advanceObject(largest); + hooks.reportedLargest = (producer, largest, finished) => { + producer.#advanceObject(largest); + const current = producer.#state.largest.peek(); + if (finished && current && current.group === largest?.group && current.frame === largest.frame) + producer.#finishLargest(largest.group); + }; hooks.reportedGroup = (producer, group) => producer.#advanceLargest({ group, frame: 0 }); objectLargest = (producer) => producer.#objectLargest; fillsOf = (producer) => producer.#fills; @@ -1621,6 +1627,7 @@ export class Producer { sink.largest.set(this.#state.largest.peek()); sink.first = this.#state.largest.peek()?.group; sink.largestEnded.set(this.#state.largestEnded.peek()); + sink.largestFinished = this.#state.largestFinished; sink.dropsAnchors.set(this.#state.dropsAnchors.peek()); const closed = this.#state.closed.peek(); @@ -1853,10 +1860,10 @@ export class Producer { if (!largest) return; const current = this.#state.largest.peek(); if (current && !after(largest, current)) return; - this.#largestOpen = true; for (const state of [this.#state, ...this.#sinks]) { state.first ??= largest.group; state.largest.set(largest); + state.largestFinished = false; } } @@ -2344,10 +2351,16 @@ export class Producer { // Group `sequence` holds every frame it will have: it closed cleanly, its stream finished. // A group name fixes its content, so no legal write raises the largest past it. #finishLargest(sequence: bigint): void { - if (this.#state.largest.peek()?.group === sequence) this.#largestOpen = false; + if (this.#state.largest.peek()?.group === sequence) + for (const state of [this.#state, ...this.#sinks]) state.largestFinished = true; this.#endLargest(); } + // The largest group may still grow until it closes cleanly; an aborted one can be recreated. + get #largestOpen(): boolean { + return this.#state.largest.peek() !== undefined && !this.#state.largestFinished; + } + // End the largest stream while the track stays open, once it can no longer advance: the // declared end is reached, and the largest group's content is final. Every sequence below // the end raised it already, so neither a late group below it nor a recreated copy of it @@ -4018,6 +4031,12 @@ export class Subscriber { const producer = subscriber.#state.producer; return producer && objectLargest(producer); }; + hooks.largestFinished = (subscriber, position) => { + if (subscriber.#resume) return subscriber.#resume.largestFinished(position); + const state = subscriber.#state; + const largest = state.largest.peek(); + return state.largestFinished && largest?.group === position.group && largest.frame === position.frame; + }; hooks.peekLargest = (subscriber) => { if (subscriber.#resume) return subscriber.#resume.peekLargest(); const state = subscriber.#state; From 50d86271d283ee953f8b2a918b5595d3b9837793 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 04:32:51 -0800 Subject: [PATCH 08/26] feat(lite)!: a lite-07 datagram always carries its timestamp A Track Datagram on a scale-less datagram track carries its producer's bare timestamp, which is its sequence, instead of omitting it. Lite-05/06 already stamp every datagram, so every version with datagrams now carries one: the body codec drops its untimed form and the lookup it needed to tell them apart. A subscriber reads a scale-less one as an unscaled timestamp, which the track checks against the sequence. Co-Authored-By: Claude Opus 5.5 --- js/net/bench/lite-varint.ts | 4 +- js/net/src/integers.test.ts | 3 -- js/net/src/lite/datagram-tracks.test.ts | 6 +-- js/net/src/lite/datagram.test.ts | 49 ++++++----------- js/net/src/lite/datagram.ts | 41 +++++--------- js/net/src/lite/publisher.ts | 23 +++++--- js/net/src/lite/subscriber.ts | 20 +++---- rs/moq-net/src/fuzz.rs | 22 +++----- rs/moq-net/src/lite/datagram.rs | 72 ++++++++----------------- rs/moq-net/src/lite/publisher.rs | 13 +++-- rs/moq-net/src/lite/subscriber.rs | 25 ++++----- rs/moq-net/src/test_interop.rs | 20 +------ test/interop/lite-varint.ts | 13 +---- 13 files changed, 109 insertions(+), 202 deletions(-) diff --git a/js/net/bench/lite-varint.ts b/js/net/bench/lite-varint.ts index 671512f8b6d..eb94aa713bd 100644 --- a/js/net/bench/lite-varint.ts +++ b/js/net/bench/lite-varint.ts @@ -78,8 +78,8 @@ const subscribe: Sample = { const datagram: Sample = { name: "Datagram", - encode: (w, version) => w.write(new Datagram(3n, 1_234n, 1_234_567_890, new Uint8Array()).encode(version)), - decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version, () => ({ timed: true }))), + encode: (w, version) => w.write(new Datagram(3n, 1_234n, 1_234_567_890n, new Uint8Array()).encode(version)), + decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version)), }; const hop = randomHop(); diff --git a/js/net/src/integers.test.ts b/js/net/src/integers.test.ts index c249c678d75..9cc09f4476f 100644 --- a/js/net/src/integers.test.ts +++ b/js/net/src/integers.test.ts @@ -9,7 +9,6 @@ import { Parameters } from "./ietf/parameters.ts"; import { PublishDone } from "./ietf/publish.ts"; import { RequestError } from "./ietf/request.ts"; import { Version } from "./ietf/version.ts"; -import { Datagram } from "./lite/datagram.ts"; import { Fetch } from "./lite/fetch.ts"; import { frameDecoder, Group as LiteGroup } from "./lite/group.ts"; import * as LiteMessage from "./lite/message.ts"; @@ -182,8 +181,6 @@ for (const version of [Lite.DRAFT_06, Lite.DRAFT_07]) { ); const decode = frameDecoder({ scale: Timescale.NANO }); expect(() => decode(new Cursor(fields(version, UNSAFE << 1n, 0), version))).toThrow(RangeError); - const datagram = fields(version, ...(version === Lite.DRAFT_07 ? [0] : []), 0, 0, UNSAFE); - await expect(Datagram.decode(datagram, version, () => ({ timed: true }))).rejects.toThrow(RangeError); }); } diff --git a/js/net/src/lite/datagram-tracks.test.ts b/js/net/src/lite/datagram-tracks.test.ts index 11a0851fdfd..848b3d34dfa 100644 --- a/js/net/src/lite/datagram-tracks.test.ts +++ b/js/net/src/lite/datagram-tracks.test.ts @@ -151,9 +151,9 @@ test("lite-07 bounds and prioritizes independent createWritable datagram queues" expect(pair.server.sendStreams.datagrams.find((other) => other !== queue)?.sendOrder).toBe( sendOrder({ priority: 31, publisher: 7 }), ); - // Type, Subscribe ID, and Sequence each occupy one byte on this untimed track. - datagrams.append(Timestamp.unscaled(1n), new Uint8Array(898)); - datagrams.append(Timestamp.unscaled(2n), new Uint8Array(897)); + // Type, Subscribe ID, Sequence, and the bare Timestamp each occupy one byte here. + datagrams.append(Timestamp.unscaled(1n), new Uint8Array(897)); + datagrams.append(Timestamp.unscaled(2n), new Uint8Array(896)); expect((await reader.recv())?.sequence).toBe(2n); } finally { second.close(); diff --git a/js/net/src/lite/datagram.test.ts b/js/net/src/lite/datagram.test.ts index 4ee49a61deb..0e4313b3d71 100644 --- a/js/net/src/lite/datagram.test.ts +++ b/js/net/src/lite/datagram.test.ts @@ -5,33 +5,26 @@ import { Version } from "./version.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); -test("invalid datagram types never reach a subscription", async () => { - // Type 0x1 was lite-07's padding before it left the draft. +test("invalid datagram types are refused", async () => { + // 0x0 is the only type. for (const bytes of [[], [0x80], [1, 1, 2, 3], [2, 1, 2, 3], new Uint8Array(9).fill(0xff)]) { - let lookedUp = false; - await expect( - Datagram.decode(new Uint8Array(bytes), Version.DRAFT_07, () => { - lookedUp = true; - throw new Error("invalid type must not look up a subscription"); - }), - ).rejects.toThrow(); - expect(lookedUp).toBe(false); + await expect(Datagram.decode(new Uint8Array(bytes), Version.DRAFT_07)).rejects.toThrow(); } }); test("datagram body round-trips", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { - const dg = new Datagram(1n, 42n, 1000, enc.encode("hello")); - const decoded = await Datagram.decode(dg.encode(version), version, () => ({ timed: true })); + const dg = new Datagram(1n, 42n, 1000n, enc.encode("hello")); + const decoded = await Datagram.decode(dg.encode(version), version); expect(decoded.subscribe).toBe(1n); expect(decoded.sequence).toBe(42n); - expect(decoded.timestamp).toBe(1000); + expect(decoded.timestamp).toBe(1000n); expect(dec.decode(decoded.payload)).toBe("hello"); } }); test("datagram body has no inner length prefix", () => { - const dg = new Datagram(1n, 2n, 3, enc.encode("world")); + const dg = new Datagram(1n, 2n, 3n, enc.encode("world")); const body = dg.encode(Version.DRAFT_06); // Three single-byte varints (values < 64) followed by the raw 5-byte payload. expect(body.byteLength).toBe(8); @@ -40,37 +33,25 @@ test("datagram body has no inner length prefix", () => { test("datagram body varints follow the version's encoding", () => { // 100 takes the two-byte QUIC form on lite-06 and one leading-ones byte on lite-07. - const dg = new Datagram(100n, 100n, 100, new Uint8Array()); + const dg = new Datagram(100n, 100n, 100n, new Uint8Array()); expect([...dg.encode(Version.DRAFT_06)]).toEqual([0x40, 0x64, 0x40, 0x64, 0x40, 0x64]); expect([...dg.encode(Version.DRAFT_07)]).toEqual([0, 0x64, 0x64, 0x64]); }); test("datagram body round-trips an empty payload", async () => { - const dg = new Datagram(0n, 0n, 0, new Uint8Array()); - const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07, () => ({ timed: true })); + const dg = new Datagram(0n, 0n, 0n, new Uint8Array()); + const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07); expect(decoded.payload.byteLength).toBe(0); }); -test("an untimed datagram body carries no timestamp", async () => { - const dg = new Datagram(1n, 2n, undefined, enc.encode("world")); - const body = dg.encode(Version.DRAFT_07); - expect(body.byteLength).toBe(8); - const decoded = await Datagram.decode(body, Version.DRAFT_07, (subscribe) => { - expect(subscribe).toBe(1n); - return { timed: false }; - }); - expect(decoded.sequence).toBe(2n); - expect(decoded.timestamp).toBeUndefined(); +test("a scale-less lite-07 datagram carries its bare timestamp at full width", async () => { + const far = 1n << 60n; + const dg = new Datagram(1n, far, far, enc.encode("world")); + const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07); + expect([decoded.sequence, decoded.timestamp]).toEqual([far, far]); expect(dec.decode(decoded.payload)).toBe("world"); }); -test("an untimed datagram body is refused before lite-07", () => { - const dg = new Datagram(1n, 2n, undefined, enc.encode("world")); - for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { - expect(() => dg.encode(version)).toThrow("has no untimed datagram"); - } -}); - test("lite-07 datagram requests match Rust's size-prefixed fields", async () => { const { Datagrams, DatagramsInfo, DatagramsUpdate } = await import("./datagram.ts"); const { Reader, Writer } = await import("../stream.ts"); diff --git a/js/net/src/lite/datagram.ts b/js/net/src/lite/datagram.ts index d13b33edb77..9eb86b57bd3 100644 --- a/js/net/src/lite/datagram.ts +++ b/js/net/src/lite/datagram.ts @@ -11,12 +11,11 @@ import { Timescale } from "../time.ts"; import { decodeNode, decodePin, encodeNode, encodePin } from "./instance.ts"; import * as Message from "./message.ts"; import { fromWire, toWire } from "./priority.ts"; -import { hasDatagrams, hasDatagramTracks, type Version, wireTimescale } from "./version.ts"; +import { hasDatagrams, hasDatagramTracks, type Version } from "./version.ts"; /** - * A QUIC datagram body: `subscribe (i) | sequence (i) | [timestamp (i)] | payload (b)`, with the - * timestamp present only when the subscription's track carries one (see `wireTimescale`). - * Lite-07 prefixes datagram-track bodies with type 0x0, its only datagram type. + * A QUIC datagram body: `subscribe (i) | sequence (i) | timestamp (i) | payload (b)`. Lite-07 + * prefixes datagram-track bodies with type 0x0, its only datagram type. * * The payload runs to the datagram boundary, so unlike a size-prefixed lite message there is no * inner length prefix. Mirrors the Rust `lite::Datagram`; the model counterpart is @@ -30,12 +29,15 @@ export class Datagram { subscribe: bigint; /** The datagram track's sequence, mapped to a group sequence on lite-05/06. */ sequence: bigint; - /** Absolute presentation timestamp in the track's wire timescale, or undefined on a track that carries none. */ - timestamp: number | undefined; + /** + * Absolute presentation timestamp in the track's wire timescale. A scale-less track's is the + * bare value its producer gave, which is the datagram's sequence. + */ + timestamp: bigint; /** The frame payload, delimited by the datagram boundary. */ payload: Uint8Array; - constructor(subscribe: bigint, sequence: bigint, timestamp: number | undefined, payload: Uint8Array) { + constructor(subscribe: bigint, sequence: bigint, timestamp: bigint, payload: Uint8Array) { this.subscribe = subscribe; this.sequence = sequence; this.timestamp = timestamp; @@ -45,14 +47,9 @@ export class Datagram { /** Encode the body to a single `Uint8Array` (no length prefix; the datagram boundary delimits it). */ encode(version: Version): Uint8Array { if (!hasDatagrams(version)) throw new Error("datagrams require lite-05 or newer"); - // A version that always carries a timescale has no untimed body. - if (this.timestamp === undefined && wireTimescale(version, undefined) !== undefined) { - throw new Error(`version ${version} has no untimed datagram`); - } - const subscribe = encodeVarint(this.subscribe, version); const sequence = encodeVarint(this.sequence, version); - const timestamp = this.timestamp === undefined ? new Uint8Array() : encodeVarint(this.timestamp, version); + const timestamp = encodeVarint(this.timestamp, version); const type = hasDatagramTracks(version) ? encodeVarint(0x0, version) : new Uint8Array(); const out = new Uint8Array( @@ -75,16 +72,8 @@ export class Datagram { return out; } - /** - * Decode a datagram body. `timed` reports whether the track of the given subscribe ID carries - * a timestamp, which the body itself does not say. An unknown lite-07 type throws, so the - * caller discards it. - */ - static async decode( - data: Uint8Array, - version: Version, - framing: (subscribe: bigint) => { timed: boolean }, - ): Promise { + /** Decode a datagram body. An unknown lite-07 type throws, so the caller discards it. */ + static async decode(data: Uint8Array, version: Version): Promise { if (!hasDatagrams(version)) throw new Error("datagrams require lite-05 or newer"); const r = new Reader(undefined, data, version); if (hasDatagramTracks(version)) { @@ -93,11 +82,9 @@ export class Datagram { } const subscribe = await r.u62(); const sequence = await r.u62(); - const { timed } = framing(subscribe); - const timestamp = timed ? await r.u53() : undefined; + const timestamp = await r.u62(); const payload = await r.readAll(); - const result = new Datagram(subscribe, sequence, timestamp, payload); - return result; + return new Datagram(subscribe, sequence, timestamp, payload); } } diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 239c2da91d2..1346e519d62 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -16,6 +16,7 @@ import { reason, StreamCode, StreamError, + TimestampMismatch, toStreamCode, unauthorized, } from "../error.ts"; @@ -40,7 +41,7 @@ import { readSize, sendPayload } from "../payload.ts"; import { Priority, sendOrder } from "../priority.ts"; import { rescale } from "../rescale.ts"; import { concat, encodeVarint, type Reader, type Stream, type StreamVersion, Writer } from "../stream.ts"; -import { floorAt, type Timescale, Timestamp } from "../time.ts"; +import { floorAt, keyOf, type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import type { Reported } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; @@ -162,6 +163,13 @@ function wireTime(timestamp: Timestamp, stamp: Stamp): number { return stamp.timed ? rescale(stamp.timed, timestamp).value : floorAt(Timestamp.now(), stamp.timescale); } +/** A scale-less lite-07 datagram's timestamp as it goes out: the bare value its producer gave. */ +function bareTime(timestamp: Timestamp): bigint { + const key = keyOf(timestamp); + if (key === undefined) throw new TimestampMismatch(); + return key; +} + /** * Settles once the peer acknowledged everything written before the FIN, or the stream failed. * Closing the session sooner would discard bytes still in flight. @@ -2366,13 +2374,16 @@ export class Publisher { if (!datagram) return end; end = max(end, datagram.sequence + 1n); const stamp = options.stamp; - // An old subscription uses its stream track's timescale for both kinds. + // An old subscription uses its stream track's timescale for both kinds. Without a + // stamp the track is a scale-less lite-07 one, whose timestamp goes out bare. const timestamp = stamp === undefined - ? undefined - : datagram.timestamp.scale === undefined - ? floorAt(Timestamp.now(), stamp.timescale) - : floorAt(datagram.timestamp, stamp.timescale); + ? bareTime(datagram.timestamp) + : BigInt( + datagram.timestamp.scale === undefined + ? floorAt(Timestamp.now(), stamp.timescale) + : floorAt(datagram.timestamp, stamp.timescale), + ); const body = new DatagramMessage(options.sub, datagram.sequence, timestamp, datagram.payload).encode( this.version, ); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 22c534259ad..b22d35ee763 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -57,6 +57,7 @@ import * as Time from "../time.ts"; import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { closeUnwanted } from "../util/announce.ts"; +import { toNumber } from "../util/bigint.ts"; import { Deadline } from "../util/deadline.ts"; import { isAbandoned, isUnrequested, unrequested, unwanted } from "../util/demand.ts"; import { LIMITS, type Limits, SlotMap, Slots } from "../util/limits.ts"; @@ -4030,20 +4031,15 @@ export class Subscriber { // Deliver one datagram body, returning its Subscribe ID if that subscription has no datagram // track, or, `behindHeld`, has a datagram held. async #deliverDatagram(payload: Uint8Array, behindHeld: boolean): Promise { - // Read with the entry it was decoded with: one registered while the decode awaited would - // read a datagram parsed with the defaults. - let entry: DatagramEntry | undefined; - const dg = await DatagramMessage.decode(payload, this.version, (id) => { - entry = this.#datagrams.get(id); - return { timed: entry?.timescale !== undefined }; - }); - if (!entry || this.#datagrams.get(dg.subscribe) !== entry) return dg.subscribe; + const dg = await DatagramMessage.decode(payload, this.version); + const entry = this.#datagrams.get(dg.subscribe); + if (!entry) return dg.subscribe; if (behindHeld && this.#isHeld(dg.subscribe)) return dg.subscribe; - // A scale-less datagram's timestamp is its sequence. + // A scale-less datagram's timestamp is bare, which the track checks is its sequence. const timestamp = - dg.timestamp === undefined || entry.timescale === undefined - ? Time.Timestamp.unscaled(dg.sequence) - : new Time.Timestamp(dg.timestamp, entry.timescale); + entry.timescale === undefined + ? Time.Timestamp.unscaled(dg.timestamp) + : new Time.Timestamp(toNumber(dg.timestamp), entry.timescale); entry.producer.insert({ sequence: dg.sequence, timestamp, payload: dg.payload }); return undefined; } diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 2dc07869fa8..4cef84ff886 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -359,20 +359,14 @@ fn ietf_paths(data: &[u8], version: ietf::Version) { /// [`roundtrip`] for a datagram body, which runs to the end of its buffer. fn datagram(data: &[u8], version: lite::Version) -> bool { - // The body doesn't say whether it carries a timestamp, so try both readings. - let mut any = false; - for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, |_| timed) else { - continue; - }; - any = true; - let Ok(first) = decoded.encode_bytes(version) else { - continue; - }; - let echo = lite::Datagram::decode(first, version, |_| timed).expect("could not decode our own encoding"); + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version) else { + return false; + }; + if let Ok(first) = decoded.encode_bytes(version) { + let echo = lite::Datagram::decode(first, version).expect("could not decode our own encoding"); assert_eq!(echo, decoded, "datagram did not survive a round trip"); } - any + true } /// Decode one moq-lite wire object from arbitrary bytes. @@ -1490,7 +1484,7 @@ impl LiteSample { Self::Datagram => lite::Datagram { subscribe: 3, sequence: 1_234, - timestamp: Some(1_234_567_890), + timestamp: 1_234_567_890, payload: bytes::Bytes::new(), } .encode(w, version) @@ -1523,7 +1517,7 @@ impl LiteSample { } Self::Group => lite::Group::decode(r, version).map(|_| 1).unwrap(), Self::Subscribe => lite::Subscribe::decode(r, version).map(|_| 1).unwrap(), - Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, |_| true) + Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version) .map(|_| 1) .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 658ad47c474..6dd83892631 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -1,8 +1,7 @@ //! moq-lite datagrams: QUIC datagram bodies, and lite-07's request for a datagram track. //! -//! A body is `subscribe (i) | sequence (i) | [timestamp (i)] | payload (b)`, with the -//! timestamp present only when the subscription's track carries one (see -//! [`Version::wire_timescale`]). Lite-07 prefixes it with type 0x0, its only datagram type. +//! A body is `subscribe (i) | sequence (i) | timestamp (i) | payload (b)`. Lite-07 prefixes it +//! with type 0x0, its only datagram type. //! The payload runs to the datagram boundary, so unlike a [`super::Message`] there is no //! inner length prefix. //! @@ -29,9 +28,10 @@ pub struct Datagram { pub subscribe: u64, /// The datagram's sequence: its group's on lite-05/06, the datagram track's on lite-07. pub sequence: u64, - /// Absolute presentation timestamp in the track's wire timescale, or `None` on a track - /// that carries no timestamps. - pub timestamp: Option, + /// Absolute presentation timestamp in the track's wire timescale. A scale-less track's + /// is the bare value its producer gave, which is the datagram's sequence (see + /// [`Version::wire_timescale`]). + pub timestamp: u64, /// The payload, delimited by the datagram boundary. pub payload: Bytes, } @@ -42,19 +42,12 @@ impl Encode for Datagram { return Err(EncodeError::Version); } - // A version that always carries a timescale has no untimed body. - if self.timestamp.is_none() && version.wire_timescale(None).is_some() { - return Err(EncodeError::Version); - } - if version.has_datagram_tracks() { w.varint(0x0)?; } w.varint(self.subscribe)?; w.varint(self.sequence)?; - if let Some(timestamp) = self.timestamp { - w.varint(timestamp)?; - } + w.varint(self.timestamp)?; // Payload runs to the datagram boundary: written raw, no length prefix. w.slice(&self.payload); @@ -68,9 +61,8 @@ impl Datagram { /// Decode a datagram without copying its payload. /// - /// `timed` says whether the track of the given subscribe ID carries timestamps, which - /// the body itself does not. An unknown lite-07 type is an error, so the caller discards it. - pub(crate) fn decode(buf: Bytes, version: Version, timed: impl FnOnce(u64) -> bool) -> Result { + /// An unknown lite-07 type is an error, so the caller discards it. + pub(crate) fn decode(buf: Bytes, version: Version) -> Result { if !version.has_datagrams() { return Err(DecodeError::Version); } @@ -81,10 +73,7 @@ impl Datagram { } let subscribe = r.varint()?; let sequence = r.varint()?; - let timestamp = match timed(subscribe) { - true => Some(r.varint()?), - false => None, - }; + let timestamp = r.varint()?; // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); @@ -261,14 +250,9 @@ mod test { #[test] fn invalid_types_never_reach_a_subscription() { - // Type 0x1 was lite-07's padding before it left the draft. + // 0x0 is the only type. for body in [&[][..], &[0x80][..], &[1, 1, 2, 3][..], &[2, 1, 2, 3][..], &[0xff; 9][..]] { - assert!( - Datagram::decode(Bytes::copy_from_slice(body), Version::Lite07, |_| panic!( - "invalid type must not look up a subscription" - )) - .is_err() - ); + assert!(Datagram::decode(Bytes::copy_from_slice(body), Version::Lite07).is_err()); } } @@ -277,12 +261,12 @@ mod test { let original = Datagram { subscribe: 1, sequence: 42, - timestamp: Some(1_000), + timestamp: 1_000, payload: Bytes::from_static(b"hello"), }; for version in [Version::Lite05, Version::Lite06, Version::Lite07] { let buf = original.encode_bytes(version).unwrap(); - let decoded = Datagram::decode(buf, version, |_| true).unwrap(); + let decoded = Datagram::decode(buf, version).unwrap(); assert_eq!(decoded, original); } } @@ -294,7 +278,7 @@ mod test { let dg = Datagram { subscribe: 1, sequence: 2, - timestamp: Some(3), + timestamp: 3, payload: Bytes::from_static(b"world"), }; let buf = dg.encode_bytes(Version::Lite05).unwrap(); @@ -303,29 +287,17 @@ mod test { } #[test] - fn untimed_omits_the_timestamp() { + fn a_scale_less_lite07_datagram_carries_its_bare_timestamp() { + // A scale-less track's timestamp is the producer's bare value, still on the wire. let dg = Datagram { subscribe: 1, sequence: 2, - timestamp: None, + timestamp: 2, payload: Bytes::from_static(b"world"), }; let buf = dg.encode_bytes(Version::Lite07).unwrap(); - assert_eq!(&buf[..], b"\x00\x01\x02world"); - let decoded = Datagram::decode(buf, Version::Lite07, |id| { - assert_eq!(id, 1); - false - }) - .unwrap(); - assert_eq!(decoded, dg); - - // Lite-05/06 have no untimed body. - for version in [Version::Lite05, Version::Lite06] { - assert!( - matches!(dg.encode_bytes(version), Err(EncodeError::Version)), - "{version}" - ); - } + assert_eq!(&buf[..], b"\x00\x01\x02\x02world"); + assert_eq!(Datagram::decode(buf, Version::Lite07).unwrap(), dg); } #[test] @@ -333,12 +305,12 @@ mod test { let dg = Datagram { subscribe: 1, sequence: 2, - timestamp: Some(3), + timestamp: 3, payload: Bytes::from_static(b"x"), }; assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, |_| true), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 20dbe99db24..b6df8bbbfc2 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2891,7 +2891,8 @@ struct DatagramSend { session: Transport, id: u64, version: Version, - /// How datagrams are stamped, or `None` when they carry no timestamp. + /// How datagrams are stamped, or `None` on a scale-less lite-07 track, whose datagrams + /// carry their producer's bare value. stamp: Option, /// The publisher's priority for the track, which breaks subscriber priority ties. publisher: i8, @@ -2931,8 +2932,12 @@ impl DatagramSend { /// every datagram its source produces later is at least as far, so the subscription can /// deliver no more. One the network reordered below it is lost, as any datagram may be. fn send(&self, datagram: crate::datagram::Datagram) -> Result<(), Error> { - let Ok(timestamp) = self.stamp.map(|stamp| stamp.wire(datagram.timestamp)).transpose() else { - return Ok(()); + let timestamp = match self.stamp { + Some(stamp) => match stamp.wire(datagram.timestamp) { + Ok(timestamp) => timestamp, + Err(_) => return Ok(()), + }, + None => datagram.timestamp.value(), }; let sequence = datagram.sequence; let size = datagram.payload.len(); @@ -2942,8 +2947,6 @@ impl DatagramSend { timestamp, payload: datagram.payload, }; - // The stamp is set wherever the version needs a timestamp, so this never hits a - // version guard. let body = body.encode_bytes(self.version)?; let max = self.session.max_datagram_size().min(lite::Datagram::MAX_SIZE); if body.len() > max { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 885d6d26f66..d02bedd3127 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1177,20 +1177,15 @@ impl Subscriber { if payload.len() > lite::Datagram::MAX_SIZE { return Ok(None); } - let mut target = None; - let dg = lite::Datagram::decode(payload, self.version, |id| { - target = self.datagram_target(id); - target.as_ref().is_some_and(|(_, timescale)| timescale.is_some()) - })?; - let Some((mut producer, timescale)) = target else { + let dg = lite::Datagram::decode(payload, self.version)?; + let Some((mut producer, timescale)) = self.datagram_target(dg.subscribe) else { return Ok(Some(dg.subscribe)); }; - // A scale-less datagram's time is its sequence. - let timestamp = match (dg.timestamp, timescale) { - (Some(value), Some(scale)) => { - Timestamp::new(value, scale).map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))? - } - _ => Timestamp::unscaled(dg.sequence), + // A scale-less datagram's timestamp is bare, which the track checks is its sequence. + let timestamp = match timescale { + Some(scale) => Timestamp::new(dg.timestamp, scale) + .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?, + None => Timestamp::unscaled(dg.timestamp), }; producer.insert(crate::datagram::Datagram { sequence: dg.sequence, @@ -4746,7 +4741,7 @@ mod tests { let body = lite::Datagram { subscribe, sequence: 0, - timestamp: None, + timestamp: 0, payload: bytes::Bytes::from_static(b"x"), }; peer.send_datagram(body.encode_bytes(Version::Lite07).unwrap(), Default::default()) @@ -4817,7 +4812,7 @@ mod tests { let body = lite::Datagram { subscribe: 1, sequence: key, - timestamp: None, + timestamp: key, payload: bytes::Bytes::from_static(b"x"), }; peer.send_datagram(body.encode_bytes(Version::Lite07).unwrap(), Default::default()) @@ -7365,7 +7360,7 @@ mod tests { lite::Datagram { subscribe: 1, sequence: key, - timestamp: Some(key), + timestamp: key, payload: bytes::Bytes::from(vec![0; size]), } .encode_bytes(version) diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index d71512779c3..3c24a149e10 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -291,7 +291,6 @@ struct Echo { varints: Vec, setup: Vec, datagram: Vec, - untimed_datagram: Vec, track_info: Vec, group: Vec, untimed_group: Vec, @@ -324,7 +323,7 @@ fn lite_varint_interop() { let datagram = lite::Datagram { subscribe: (1 << 40) + 1, sequence: 300, - timestamp: Some((1 << 50) + 5), + timestamp: (1 << 50) + 5, payload: bytes::Bytes::from_static(b"x"), } .encode_bytes(version) @@ -332,21 +331,6 @@ fn lite_varint_interop() { // Only lite-07 can carry an untimed track; lite-06 stamps it, so it has no untimed bytes. let untimed = version.wire_timescale(None).is_none(); - // The body doesn't say it is untimed; the subscription's track does. - let untimed_datagram = lite::Datagram { - subscribe: 9, - sequence: 1 << 30, - timestamp: None, - payload: bytes::Bytes::from_static(b"untimed"), - } - .encode_bytes(version); - let untimed_datagram = match untimed { - true => untimed_datagram.unwrap().to_vec(), - false => { - assert!(untimed_datagram.is_err(), "{version}: encoded an untimed datagram"); - Vec::new() - } - }; // An untimed track: zero on lite-07, milliseconds before it. Compressed where the // version can say so. @@ -384,7 +368,6 @@ fn lite_varint_interop() { "varints": varints, "setup": setup.to_vec(), "datagram": datagram.to_vec(), - "untimedDatagram": untimed_datagram, "trackInfo": track_info.to_vec(), "group": group, "untimedGroup": untimed_group, @@ -396,7 +379,6 @@ fn lite_varint_interop() { assert_eq!(echo.varints, varints, "{version}: JS encoded the values differently"); assert_eq!(echo.setup, setup, "{version}: SETUP"); assert_eq!(echo.datagram, datagram, "{version}: datagram"); - assert_eq!(echo.untimed_datagram, untimed_datagram, "{version}: untimed datagram"); assert_eq!(echo.track_info, track_info, "{version}: TRACK_INFO"); assert_eq!(echo.group, group, "{version}: group"); assert_eq!(echo.untimed_group, untimed_group, "{version}: untimed group"); diff --git a/test/interop/lite-varint.ts b/test/interop/lite-varint.ts index f6946a83fde..9912508cd58 100644 --- a/test/interop/lite-varint.ts +++ b/test/interop/lite-varint.ts @@ -13,7 +13,6 @@ const input: { varints: number[]; setup: number[]; datagram: number[]; - untimedDatagram: number[]; trackInfo: number[]; group: number[]; untimedGroup: number[]; @@ -64,21 +63,12 @@ if (version === Version.DRAFT_07) { const setup = await Setup.decode(reader(input.setup), version); const setupBytes = await write((w) => setup.encode(w, version)); -const datagram = await Datagram.decode(Uint8Array.from(input.datagram), version, () => ({ timed: true })); +const datagram = await Datagram.decode(Uint8Array.from(input.datagram), version); const datagramBytes = [...datagram.encode(version)]; // Only lite-07 can carry an untimed track; lite-06 stamps it, so it has no untimed bytes. const untimed = version === Version.DRAFT_07; -let untimedDatagramBytes: number[] = []; -if (untimed) { - const datagram = await Datagram.decode(Uint8Array.from(input.untimedDatagram), version, () => ({ timed: false })); - assert.equal(datagram.timestamp, undefined); - untimedDatagramBytes = [...datagram.encode(version)]; -} else { - assert.throws(() => new Datagram(9n, 1n, undefined, new Uint8Array()).encode(version)); -} - const trackInfo = await TrackInfo.decode(reader(input.trackInfo), version); assert.equal(trackInfo.timescale, version === Version.DRAFT_07 ? undefined : 1_000); const trackInfoBytes = await write((w) => trackInfo.encode(w, version)); @@ -136,7 +126,6 @@ console.log( varints, setup: setupBytes, datagram: datagramBytes, - untimedDatagram: untimedDatagramBytes, trackInfo: trackInfoBytes, group: groupBytes, untimedGroup: untimedGroupBytes, From e5b28598c3b581cd091cf3ec232c8fd59285bf49 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:07:38 -0800 Subject: [PATCH 09/26] feat(net)!: lite-07 drops and skips carry a span, and stale drops are final SUBSCRIBE_DROP on lite-07 is now Group Start, Group End, Error Code, and SUBSCRIBE_SKIP Group Start, Group End: a span [Start, End) with no count, where an End at or below the Start is a PROTOCOL_VIOLATION. The Update field leaves SUBSCRIBE, SUBSCRIBE_UPDATE, and SUBSCRIBE_DROP. A stale (OLD) drop is final on its subscription. A SUBSCRIBE_UPDATE reopens nothing: the publisher never serves or names again a group it already served or dropped, and the subscriber never owes one again. A relay records a stale drop under the narrowest budget its subscription asked, since the wire no longer says which update a drop crossed; a reader wider than that asks for the group on a request of its own. Deleted with the reopen paths: the publisher's update number, redrop and reoffered sets and stale replacement; the record's stale reports that an update reopened; the track's judged ranges, re-offers, and tail billing; the tail's finished and folded bookkeeping and its update count. The TLA+ model drops updates, the StreamWins rule and config, and NoViolation, and gains NamedOnce. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/fuzz.rs | 4 - rs/moq-net/src/ledger.rs | 78 -- rs/moq-net/src/lite/publisher.rs | 710 ++---------------- rs/moq-net/src/lite/subscribe.rs | 169 +---- rs/moq-net/src/lite/subscriber.rs | 599 +++------------ rs/moq-net/src/lite/subscriber/fills.rs | 4 +- rs/moq-net/src/lite/version.rs | 11 +- rs/moq-net/src/model/cache.rs | 5 - rs/moq-net/src/model/record.rs | 258 ++----- rs/moq-net/src/model/resume.rs | 220 +----- rs/moq-net/src/model/skipped.rs | 13 - rs/moq-net/src/model/track.rs | 613 +++------------ rs/moq-net/src/model/track/miss.rs | 60 +- rs/moq-net/src/tail.rs | 117 --- rs/moq-net/tests/integration/drop_record.rs | 104 +-- rs/moq-net/verify/subscribe/Continuation.cfg | 6 +- rs/moq-net/verify/subscribe/StreamWins.cfg | 17 - .../verify/subscribe/SubscribeAccounting.cfg | 18 +- .../verify/subscribe/SubscribeAccounting.tla | 398 +++------- 19 files changed, 531 insertions(+), 2873 deletions(-) delete mode 100644 rs/moq-net/verify/subscribe/StreamWins.cfg diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 39fb2b122e6..1c249d54b4a 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -1488,7 +1488,6 @@ impl LiteSample { max_delay: std::time::Duration::from_secs(10), min_delay: None, ranges: vec![lite::Range::OLDEST], - update: 0, } .encode(w, version) .unwrap(), @@ -1692,7 +1691,6 @@ impl Default for Messages { start: Some(lite::Anchor::Absolute(crate::track::Position::group(1_000))), end: None, }], - update: 0, }, lite_update: lite::SubscribeUpdate { wanted_group: None, @@ -1705,7 +1703,6 @@ impl Default for Messages { start: Some(lite::Anchor::Absolute(crate::track::Position::group(1_000))), end: Some(lite::Anchor::Absolute(crate::track::Position::group(2_001))), }]), - update: 0, }, lite_start: lite::SubscribeResponse::Start(lite::SubscribeStart { largest: None, @@ -1874,7 +1871,6 @@ pub fn encode_subscribe(broadcast: &Path, track: &str, ietf: bool, out: &mut Vec min_delay: None, ranges: vec![lite::Range::OLDEST], order: track::Order::Descending, - update: 0, } .encode(w, BENCH_LITE) .unwrap(), diff --git a/rs/moq-net/src/ledger.rs b/rs/moq-net/src/ledger.rs index af60e72bb5d..d18857efdad 100644 --- a/rs/moq-net/src/ledger.rs +++ b/rs/moq-net/src/ledger.rs @@ -162,52 +162,6 @@ impl Ledger { self.changes.insert(first..end); } - /// Take `groups` back out of what is accounted for, owed again from `now`: a verdict that - /// accounted for them was reversed. The gap they leave opens now, so it is waited for a - /// fresh grace, even where it joins an older gap. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub fn unaccount(&mut self, groups: Range, now: Instant) { - if groups.is_empty() { - return; - } - let overlapping: Vec = self.accounted(groups.clone()).map(|run| run.start).collect(); - if overlapping.is_empty() { - return; - } - for clipped in overlapping { - let start = self - .runs - .range(..=clipped) - .next_back() - .map(|(&start, _)| start) - .expect("an accounted run"); - let run = self.remove(start); - if start < groups.start { - self.ages.insert((run.since, start)); - self.runs.insert( - start, - Run { - end: groups.start, - since: run.since, - }, - ); - self.changes.insert(start..groups.start); - } - if groups.end < run.end { - self.ages.insert((now, groups.end)); - self.runs.insert( - groups.end, - Run { - end: run.end, - since: now, - }, - ); - self.changes.insert(groups.end..run.end); - } - } - self.demand(groups, now); - } - /// Account a live arrival, refreshing a cached incarnation even if its key was /// accounted before. Its gap ages stay unchanged, but readers must revisit a refusal. pub fn arrive(&mut self, key: u64, now: Instant) { @@ -553,38 +507,6 @@ mod tests { ledger.expire(lowered.saturating_add(GRACE)); assert!(ledger.covers(1..10)); } - /// Unaccounting reopens what a reversed verdict accounted for, as a gap waited for a fresh - /// grace, and leaves the rest of the run accounted. - #[test] - fn unaccount_reopens_a_gap_for_a_fresh_grace() { - let start = Instant::now(); - let mut ledger = Ledger::new(GRACE); - arrive(&mut ledger, 0..10, start); - ledger.unaccount(3..5, start.saturating_add(GRACE)); - assert!(ledger.covers(0..3) && ledger.covers(5..10)); - assert!(!ledger.covers(3..5)); - ledger.expire(start.saturating_add(GRACE * 3 / 2)); - assert!(!ledger.covers(3..5), "its grace runs from the reversal"); - ledger.expire(start.saturating_add(GRACE * 2)); - assert!(ledger.covers(0..10)); - } - - /// A reopened gap that joins an older one is waited for a fresh grace as a whole, rather - /// than folding with the older gap's age. - #[test] - fn unaccount_restarts_the_older_gap_it_joins() { - let start = Instant::now(); - let mut ledger = Ledger::new(GRACE); - arrive(&mut ledger, 0..2, start); - arrive(&mut ledger, 4..6, start); - let reversed = start.saturating_add(GRACE * 9 / 10); - ledger.unaccount(1..2, reversed); - ledger.expire(start.saturating_add(GRACE)); - assert!(!ledger.covers(1..2), "its grace runs from the reversal"); - ledger.expire(reversed.saturating_add(GRACE)); - assert!(ledger.covers(0..6)); - } - #[test] fn demand_can_move_an_older_gap_after_a_newer_one() { let start = Instant::now(); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f60f510f90d..90fffcac29a 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4,7 +4,7 @@ use crate::transport::poll::Session as _; use crate::model::record::Report; use crate::model::track::Hole; use crate::{SessionError, datagram, frame, group, origin, track}; -use rangemap::{RangeMap, RangeSet}; +use rangemap::RangeMap; use std::{ borrow::Cow, collections::HashMap, @@ -2567,7 +2567,6 @@ impl Request for SubscribeServe { // when an update lowers the floor to reach it. let floor = cursor_floor(shared.version, bounds.groups().start(), latest).max(bounds.frames.floor); let mut run = TrackRun::new(sub, track, bounds, floor, steer_tx); - run.update = msg.update; run.datagrams = LegacyDatagrams::join(legacy, msg.id, msg.priority, timescale); if let Some(update) = update { run.update(update); @@ -5121,17 +5120,8 @@ struct TrackRun { refused: Option, // Where delivery starts, which SUBSCRIBE_START reports. start: Start, - // The number of the SUBSCRIBE (0) or latest SUBSCRIBE_UPDATE, which a drop echoes. - update: u64, - // The expired runs an update owes a drop again, sent as ranges on the next poll. Lite-07 - // groups whose stream expired as stale are dropped again under every update's number: the - // subscriber reopens each stale drop then, and the stream already reset. - redrop: RangeSet, - // The expired groups an update re-offers, still cached and in range, each served again - // on its own stream as stream credit allows. - reoffered: std::collections::VecDeque, - // Lite-07: the paused groups by start, each continued on its own stream ahead of - // re-offers and new groups, the highest-ranked first. Credit returns with each pause, so + // Lite-07: the paused groups by start, each continued on its own stream ahead of new + // groups, the highest-ranked first. Credit returns with each pause, so // sustained congestion can pause every group in turn: one the budget or the cache gives // up while it waits is dropped then, which bounds them by what the cache holds, and a // group paused again replaces its entry. @@ -5209,9 +5199,6 @@ impl TrackRun { cap, steer_tx, start, - update: 0, - redrop: RangeSet::new(), - reoffered: Default::default(), paused: Default::default(), paused_tasks: kio::Tasks::new(), continuing: false, @@ -5244,7 +5231,6 @@ impl TrackRun { // The update moves the cursor and the bounds the track side judges against, which // notifies nothing it parked on. Idle::disarm(&mut self.idle); - self.update = upd.update; // Every update restates the wanted group. Past our largest it is a join, which // repeats the pending ask; at or below it the group already exists. if upd @@ -5332,29 +5318,6 @@ impl TrackRun { } self.bounded = bounds.ends(self.ctx.version); self.frames = bounds.frames; - // Lite-07 reopens every stale drop on any update, judged under its new terms: what was - // reported stale is offered again, and dropped again under this update's number if - // still stale. - if self.ctx.version.has_skip() { - let reopened = self.track.reoffer_stale(); - self.owe(reopened); - // A group whose stream already reset as stale is judged again under the new terms: - // one still cached, in range, and fresh under the new budget is served again. The - // rest is dropped again, by run, on the next poll. A run an earlier update left to - // drop again is judged again too, since these terms may serve it, and so is a group - // one re-offered that has not opened yet, since they may no longer admit it. - let mut expired = self.track.record_mut().expired(); - for group in std::mem::take(&mut self.reoffered) { - expired.insert(group.start..group.start + 1); - } - expired.extend(std::mem::take(&mut self.redrop).iter().cloned()); - for run in expired.iter() { - let (groups, gone) = self.track.reoffer_groups(run.clone()); - self.owe(groups.iter().map(|group| group.start..group.start + 1).collect()); - self.reoffered.extend(groups); - self.redrop.extend(gone.iter().cloned()); - } - } if self.ctx.version.has_ranges() { // A range retired before its start resolved is owed no SUBSCRIBE_STARTED. // Both list Range IDs in ascending order, since each one assigned is the next. @@ -5524,32 +5487,10 @@ impl TrackRun { self.drop_given_up_paused(waiter); let dropped = std::mem::take(&mut *self.ctx.outcomes.dropped.lock().unwrap()); if !dropped.is_empty() { + // Each was served, so its record says so already, and the drop is final: nothing + // is served or dropped over it again. for (key, err) in dropped { - // A stream expired under this subscription's budget is a stale verdict. - let hole = match err { - // The pool folded the group while its stream was open, which is final for this - // reader: no update would re-offer a stale drop on it. - StreamError::Old if self.ctx.version.has_skip() && self.track.record_mut().folded(key) => { - Hole::drop(StreamError::Evicted) - } - StreamError::Old => { - if self.ctx.version.has_skip() { - self.sent_stale(key..key + 1); - } - Hole::stale(self.track.budget()) - } - err => Hole::drop(err), - }; - writer.buffer(&self.hole(key..key + 1, &hole))?; - } - return Poll::Ready(Ok(ControlFlow::Continue(()))); - } - if !self.redrop.is_empty() { - let hole = Hole::stale(self.track.budget()); - for run in std::mem::take(&mut self.redrop).iter() { - writer.buffer(&self.hole(run.clone(), &hole))?; - // A re-offer an update owed again is given up now, so the end sweep never names it. - self.sent_stale(run.clone()); + writer.buffer(&self.hole(key..key + 1, &Hole::drop(err)))?; } return Poll::Ready(Ok(ControlFlow::Continue(()))); } @@ -5608,8 +5549,8 @@ impl TrackRun { return Poll::Ready(Ok(ControlFlow::Continue(()))); } - // A paused group takes the next stream credit, ahead of re-offers and new groups, the - // highest-ranked first. It is owed already, and the subscriber holds its group open until + // A paused group takes the next stream credit, ahead of new groups, the highest-ranked + // first. It is owed already, and the subscriber holds its group open until // it continues. A group waiting for credit it cannot make room for gives way to one that // outranks it. let order = self.ctx.steer_current().order; @@ -5626,30 +5567,6 @@ impl TrackRun { return Poll::Ready(Ok(ControlFlow::Continue(()))); } - // A group an update re-offers takes the next stream credit, ahead of new ones, unless a - // verdict sent since accounted for it. - if self.opening.is_none() - && let Some(group) = self.reoffered.pop_front() - { - let key = group.start; - // The pool folded it while it waited, which is final for this reader: tell the wire - // it is gone, since an update re-offered it. - if self.start.emits_range() && self.track.record_mut().folded(key) { - writer.buffer(&self.hole(key..key + 1, &Hole::drop(StreamError::Evicted)))?; - return Poll::Ready(Ok(ControlFlow::Continue(()))); - } - if self.start.emits_range() && self.track.record_mut().told(key) { - return Poll::Ready(Ok(ControlFlow::Continue(()))); - } - match position_group(group, &self.frames) { - Some(group) => self.serve(group), - None => { - self.drop_range(key..key + 1, &Hole::drop(StreamError::NotFound), writer)?; - } - } - return Poll::Ready(Ok(ControlFlow::Continue(()))); - } - // One cursor drives the whole subscription: poll the cap-aware arrival-order group. let emit_boundary = self.start.emits_range() && !self.end_sent; // A group waiting for credit it cannot make room for must not hold back one that could: @@ -5670,17 +5587,11 @@ impl TrackRun { match res? { Recv::Group(group) => { // Never a second stream for a key this subscription already accounted - // for (served or dropped): a group re-created after its - // DROP stays dropped, since the subscriber may settle before it arrives. A - // stale drop a lite-07 update reopened is owed again (see `Self::owe`). A - // lite-07 stale drop is no final verdict, and a Group Stream wins over it, so a - // group handed out after one is served, as one a route the front switched to - // delivers: the update that reopens the drop would never re-offer it. + // for (served or dropped, stale or not): a group re-created after its DROP, + // or handed out again by a route the front switched to, stays dropped, since + // the subscriber settled it for good. let key = group.start; - let record = self.track.record_mut(); - if self.start.emits_range() && record.told_stale(key) { - self.replace_stale(key..key + 1); - } else if self.start.emits_range() && record.told(key) { + if self.start.emits_range() && self.track.record_mut().told(key) { return Poll::Ready(Ok(ControlFlow::Continue(()))); } let Some(group) = position_group(group, &self.frames) else { @@ -5823,18 +5734,6 @@ impl TrackRun { Ok(true) } - /// Owe `reopened` again, what this subscription reported stale before an update: lite-07 - /// re-offers a group it still holds and drops again, under the new update, one it cannot - /// serve. Earlier versions' drops are final, so their cursor takes nothing back. - fn owe(&mut self, reopened: Vec>) { - if self.start.emits_range() { - let record = self.track.record_mut(); - for run in reopened { - record.untell(run); - } - } - } - /// Record `key` as served, for [`Self::drop_unserved`]. fn mark_served(&mut self, key: u64) { if self.start.emits_range() { @@ -5843,9 +5742,8 @@ impl TrackRun { } /// Forward a verdict the cursor reached on `range`, which its record already took in, - /// replacing what it goes out over: on lite-07, a skip any drop already sent, and a final - /// drop a stale one, which the next update would otherwise reopen. A reader the earlier drop - /// ended stays ended. Returns whether any was buffered. + /// replacing what it goes out over: on lite-07, a skip any drop already sent. A reader the + /// earlier drop ended stays ended. Returns whether any was buffered. fn forward_range( &mut self, range: Range, @@ -5855,7 +5753,6 @@ impl TrackRun { if !self.start.emits_range() || range.is_empty() { return Ok(false); } - self.redrop.remove(range.clone()); let report = self.report(hole); self.track.record_mut().tell(range.clone(), report); writer.buffer(&self.hole(range, hole))?; @@ -5869,40 +5766,11 @@ impl TrackRun { false => Report::Settled, true => match hole { Hole::Skip => Report::Skip, - // The wire names every OLD drop stale, which the next update reopens. One given up - // as final, such as one relayed from a version whose drops are all final, is - // dropped again by each update, as an expired stream is. - Hole::Drop { .. } if hole.error() == StreamError::Old => Report::Stale { - received: false, - expired: hole.stale_budget().is_none(), - taken: false, - }, Hole::Drop { .. } => Report::Dropped, }, } } - /// Record `run` as named stale (OLD) in a lite-07 drop that each update drops again, which - /// a later verdict or group replaces. - fn sent_stale(&mut self, run: Range) { - self.track.record_mut().tell( - run, - Report::Stale { - received: false, - expired: true, - taken: false, - }, - ); - } - - /// Forget that `run` went out as a drop: a verdict or group replaces it. A stream of this - /// subscription that expired there is no longer owed again on an update, since what - /// replaced it settles it. - fn replace_stale(&mut self, run: Range) { - self.track.record_mut().replace_drops(run.clone()); - self.redrop.remove(run); - } - /// Give up, as `hole` says, whatever part of `range` this subscription has not been /// served or given up yet. Returns whether any was buffered. fn drop_range( @@ -5930,9 +5798,7 @@ impl TrackRun { let version = self.ctx.version; match hole { Hole::Skip if version.has_skip() => lite::SubscribeResponse::Skip(lite::SubscribeSkip { groups }), - hole => { - lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(groups, &hole.error(), self.update, version)) - } + hole => lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(groups, &hole.error(), version)), } } @@ -7901,7 +7767,7 @@ mod serve_group_test { hole: &Hole, writer: &mut Writer, ) { - while let Some(gap) = run.track.record_mut().report(range.clone(), hole, false) { + while let Some(gap) = run.track.record_mut().report(range.clone(), hole) { run.forward_range(gap, hole, writer).unwrap(); } } @@ -7975,7 +7841,6 @@ mod serve_group_test { min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], order: Order::Descending, - update: 0, }; run.replace(update(Some(0))); assert_eq!(track.demand().wanted(), Some(0), "stale request is not a join"); @@ -8136,7 +8001,6 @@ mod serve_group_test { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }); { let mut poll = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); @@ -8295,7 +8159,6 @@ mod serve_group_test { min_delay: None, ranges, order: Order::Descending, - update: 0, } } @@ -8503,11 +8366,11 @@ mod serve_group_test { let _track = track.finish().unwrap(); assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); - // SUBSCRIBE_START with the range starting at 0, a DROP for group 1 with OLD (0x34) - // under update 0, which the end gives up on at once, and SUBSCRIBE_FINISH at 3. + // SUBSCRIBE_START with the range starting at 0, a DROP for groups [1, 2) with OLD + // (0x34), which the end gives up on at once, and SUBSCRIBE_FINISH at 3. assert_eq!( *log.writes.lock().unwrap(), - [0, 4, 1, 0, 1, 1, 2, 4, 1, 1, 0x34, 0, 1, 2, 3, 0] + [0, 4, 1, 0, 1, 1, 2, 3, 1, 2, 0x34, 1, 2, 3, 0] ); } @@ -8531,9 +8394,9 @@ mod serve_group_test { let _track = track.finish().unwrap(); assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); - // SUBSCRIBE_START with the range starting at 0, a SKIP for group 1, and + // SUBSCRIBE_START with the range starting at 0, a SKIP for groups [1, 2), and // SUBSCRIBE_FINISH at 3. - assert_eq!(*log.writes.lock().unwrap(), [0, 4, 1, 0, 1, 1, 3, 2, 1, 1, 1, 2, 3, 0]); + assert_eq!(*log.writes.lock().unwrap(), [0, 4, 1, 0, 1, 1, 3, 2, 1, 2, 1, 2, 3, 0]); } /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the @@ -8667,33 +8530,11 @@ mod serve_group_test { drops } - /// The SUBSCRIBE_DROP ranges a run loop's subscribe stream carried, once flushed, each as - /// its first and last group with the update it names. - async fn drop_updates( - writer: &mut Writer, - log: &Log, - version: Version, - ) -> Vec<(u64, u64, u64)> { - kio::wait(|waiter| writer.poll_flush(waiter)).await.unwrap(); - let writes = log.writes.lock().unwrap().clone(); - let mut buf = writes.as_slice(); - let mut drops = Vec::new(); - while !buf.is_empty() { - let (msg, size) = lite::SubscribeResponse::decode_slice(buf, version).unwrap(); - buf = &buf[size..]; - if let lite::SubscribeResponse::Drop(drop) = msg { - drops.push((drop.groups.start, drop.groups.end - 1, drop.update)); - } - } - drops - } - - /// A lite-07 stale (OLD) drop is no final verdict: a final drop of the same group replaces - /// it, and a group handed out after it is served, as when a front switches to a route that - /// delivers what the old route reported stale, before the update that reopens it. Earlier - /// versions' drops are final, so neither goes out there. + /// A stale (OLD) drop is final on every version: a final drop of the same group does not go + /// out over it, and a group handed out after it, as when a front switches to a route that + /// delivers what the old route reported stale, is not served. #[kio::test] - async fn a_final_drop_or_a_group_replaces_a_stale_drop_on_lite07() { + async fn a_stale_drop_is_final() { for version in [Version::Lite06, Version::Lite07] { let mut track = track::Producer::new( Arc::new(broadcast::Info::default()), @@ -8711,104 +8552,16 @@ mod serve_group_test { write_group(&mut track, 2, 2); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let (drops, opened) = match version.has_skip() { - true => (vec![(1, 2, 0), (1, 1, 0)], 2), - false => (vec![(1, 2, 0)], 1), - }; - assert_eq!(drop_updates(&mut writer, &log, version).await, drops, "{version}"); - assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), opened, "{version}"); + assert_eq!(drops(&mut writer, &log, version).await, [(1, 2)], "{version}"); + assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 1, "{version}"); } } - /// A group that wins over a lite-07 stale drop already sent retires it: the next update - /// neither sends the drop again nor reopens the served group, and the end names nothing - /// for it. Here a relay's upstream reported group 1 stale, then delivered it, as a front - /// that switched routes does. - #[kio::test] - async fn a_group_served_over_a_stale_drop_retires_it() { - let budget = Duration::from_millis(1500); - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - track.give_up(1..2, Hole::stale(budget)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(drop_updates(&mut writer, &log, Version::Lite07).await, [(1, 1, 0)]); - write_group(&mut track, 1, 1000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 2, "the group wins"); - - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 1, - max_delay: budget, - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update: 1, - }); - write_group(&mut track, 2, 2000); - let _track = track.finish().unwrap(); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - 3, - "group 1 is not served again" - ); - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(1, 1, 0)], - "no second OLD, and no NOT_FOUND at the end" - ); - } - - /// A lite-07 stream that expired as stale is a stale drop like any other: a final drop - /// the reader reaches for it later replaces it, and no update drops it again then. - #[kio::test] - async fn a_final_drop_replaces_an_expired_stream_on_lite07() { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let subscriber = track.subscribe(None); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - // Group 1's stream expired, as a blocked transport would leave it. - run.ctx.outcomes.dropped.lock().unwrap().push((1, StreamError::Old)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - forward(&mut run, 1..2, &Hole::drop(StreamError::Cancel), &mut writer); - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 1, - max_delay: Duration::from_secs(3600), - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update: 1, - }); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(1, 1, 0), (1, 1, 0)], - "the final drop replaces the OLD, and the update drops nothing again" - ); - } - - /// A stale group already named in SUBSCRIBE_DROP stays dropped before lite-07 after any - /// SUBSCRIBE_UPDATE, since those subscribers settle a drop for good. Lite-07 reopens it on - /// every update: one that widens the max age past it serves it, and one that keeps the - /// budget drops it again under the new update's number. The groups served around it are - /// never resent. + /// An update reopens no drop: a stale group already named in SUBSCRIBE_DROP stays dropped + /// whether the update widens the max age past it or keeps the budget, and so does a group + /// whose stream expired. Nothing is sent again for either. #[kio::test] - async fn any_update_reoffers_a_reported_stale_drop_on_lite07_alone() { + async fn an_update_reopens_no_drop() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { for widen in [true, false] { let mut track = track::Producer::new( @@ -8827,9 +8580,12 @@ mod serve_group_test { write_group(&mut track, key, millis); } while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + // Group 3's stream expired, as a blocked transport would leave it. + run.ctx.outcomes.dropped.lock().unwrap().push((3, StreamError::Old)); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} let case = format!("{version:?}, widen={widen}"); assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 3, "{case}"); - assert_eq!(drop_updates(&mut writer, &log, version).await, [(1, 2, 0)], "{case}"); + assert_eq!(drops(&mut writer, &log, version).await, [(1, 2), (3, 3)], "{case}"); run.update(lite::SubscribeUpdate { wanted_group: None, @@ -8838,118 +8594,23 @@ mod serve_group_test { min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, - update: 1, }); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let (opened, drops, why): (u64, &[(u64, u64, u64)], _) = match (version, widen) { - (Version::Lite07, true) => (5, &[(1, 2, 0)], "the stale groups are served, and nothing else"), - (Version::Lite07, false) => (3, &[(1, 2, 0), (1, 2, 1)], "still stale, so dropped again"), - _ => (3, &[(1, 2, 0)], "no stream and no drop again"), - }; - assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), opened, "{case}: {why}"); - assert_eq!(drop_updates(&mut writer, &log, version).await, drops, "{case}: {why}"); - } - } - } - - /// A group stale at the track's max age bound is final under any budget, yet a lite-07 - /// update still reopens its drop at the subscriber, so it is dropped again under the new - /// update rather than left owed. - #[kio::test] - async fn an_update_drops_again_what_is_stale_at_the_bound() { - for widen in [false, true] { - let budget = Duration::from_millis(1500); - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed().with_max_age(budget), - ); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - for (key, millis) in [(1, 1000), (2, 2000), (3, 3000), (4, 6000)] { - write_group(&mut track, key, millis); + assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 3, "{case}: no stream"); + assert_eq!( + drops(&mut writer, &log, version).await, + [(1, 2), (3, 3)], + "{case}: no drop again" + ); } - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(drop_updates(&mut writer, &log, Version::Lite07).await, [(1, 2, 0)]); - let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 5, - max_delay: if widen { Duration::from_secs(10) } else { budget }, - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update: 1, - }); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened, - "widen={widen}: the bound keeps them stale" - ); - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(1, 2, 0), (1, 2, 1)], - "widen={widen}: dropped again under update 1" - ); } } - /// A group whose stream expired as stale is dropped again under every later update on - /// lite-07, by run, since the subscriber reopens each stale drop and the stream already - /// reset. Earlier versions' drops are final. + /// A group whose stream wrote its FIN but goes stale before the acknowledgement resets with + /// OLD and is named in a stale drop, which is final: a later update widening the budget never + /// serves it again, though the subscriber may have read the first stream whole. #[kio::test] - async fn an_update_drops_expired_streams_again_on_lite07_alone() { - for version in [Version::Lite06, Version::Lite07] { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let subscriber = track.subscribe(None); - let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - // Two group streams expired, as a blocked transport would leave them. - run.ctx - .outcomes - .dropped - .lock() - .unwrap() - .extend([(1, StreamError::Old), (2, StreamError::Old)]); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 1, - max_delay: Duration::from_secs(3600), - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update: 1, - }); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let expected: &[(u64, u64, u64)] = match version { - Version::Lite07 => &[(1, 1, 0), (2, 2, 0), (1, 2, 1)], - _ => &[(1, 1, 0), (2, 2, 0)], - }; - assert_eq!(drop_updates(&mut writer, &log, version).await, expected, "{version:?}"); - } - } - - /// Residual, found by `rs/moq-net/verify/subscribe` (`StreamWins`): a group whose stream - /// wrote its FIN but goes stale before the acknowledgement resets with OLD and is named in - /// a stale drop under the update then in effect, and a later update serves it again. The - /// subscriber may have read that stream whole before sending the update, so the draft's - /// "having served it, neither serves it again nor names it in another drop" breaks: once - /// its copy evicted the group, it records it stale (see the subscriber's - /// `a_finished_group_wins_over_a_late_stale_drop_once_evicted`), and the publisher sends - /// the whole group a second time. - #[kio::test] - async fn residual_a_stale_unacknowledged_fin_drops_and_resends_a_served_group() { + async fn a_stale_unacknowledged_fin_is_never_served_again() { let budget = Duration::from_millis(1500); let mut track = track::Producer::new( Arc::new(broadcast::Info::default()), @@ -8959,14 +8620,13 @@ mod serve_group_test { let subscriber = track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()).with_unacked_fin(), subscriber); - let update = |update, max_delay| lite::SubscribeUpdate { + let update = |max_delay| lite::SubscribeUpdate { wanted_group: None, priority: 0, max_delay, min_delay: None, ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, - update, }; // Group 0 goes out whole: every frame and the FIN, which the peer has yet to @@ -8975,262 +8635,26 @@ mod serve_group_test { while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 1); - // The subscriber read it whole, then sent update 1, which changes nothing here. - run.update(update(1, budget)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - // Group 1 starts 1s in, and group 2 at 6s leaves group 0 past the budget while its FIN // is still unacknowledged. write_group(&mut track, 1, 1000); write_group(&mut track, 2, 6000); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(0, 0, 1)], - "the served group is named stale under update 1" + drops(&mut writer, &log, Version::Lite07).await, + [(0, 0)], + "the served group is named stale" ); - // An update that widens the budget re-offers it: a second stream for a group whose - // first one went out whole. let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - run.update(update(2, Duration::from_secs(10))); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened + 1, - "group 0 is served again" - ); - } - - /// A lite-07 group whose stream expired but that the track still caches is judged again - /// under an update: served again once the budget covers it, and dropped again under the - /// new update while it is still stale. - #[kio::test] - async fn an_update_reoffers_a_cached_expired_stream_on_lite07() { - for widen in [true, false] { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let budget = Duration::from_millis(500); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - write_group(&mut track, 1, 1000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - // Group 2 lands at 3s, so group 0's successor is 2s behind the edge, past the 500ms - // budget, and its stream expired. - write_group(&mut track, 2, 3000); - run.ctx.outcomes.dropped.lock().unwrap().push((0, StreamError::Old)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(drop_updates(&mut writer, &log, Version::Lite07).await, [(0, 0, 0)]); - - run.replace(lite::SubscribeUpdate { - wanted_group: None, - priority: 0, - max_delay: if widen { Duration::from_secs(10) } else { budget }, - min_delay: None, - ranges: vec![lite::Range::span(None, 0, None, None)], - order: Order::Descending, - update: 1, - }); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - // Group 2 is served either way. - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened + 1 + u64::from(widen), - "widen={widen}: the cached group is offered again on its own stream once fresh" - ); - let drops: &[(u64, u64, u64)] = match widen { - true => &[(0, 0, 0)], - false => &[(0, 0, 0), (0, 0, 1)], - }; - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - drops, - "widen={widen}: still stale, it is dropped again under update 1" - ); - } - } - - /// A group an update re-offers waits for stream credit, and is judged again by whatever - /// arrives meanwhile: a later update whose range no longer admits it, or a final drop the - /// reader reaches for it, leaves it unserved. - #[kio::test] - async fn a_queued_reoffer_is_judged_again_before_it_opens_on_lite07() { - for narrow in [true, false] { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let budget = Duration::from_millis(500); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - write_group(&mut track, 1, 1000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - write_group(&mut track, 2, 3000); - run.ctx.outcomes.dropped.lock().unwrap().push((0, StreamError::Old)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - let update = |id, start, update| lite::SubscribeUpdate { - wanted_group: None, - priority: 0, - max_delay: Duration::from_secs(10), - min_delay: None, - ranges: vec![(id, lite::Range::span(start, 0, None, None))], - order: Order::Descending, - update, - }; - // Widened: group 0 is fresh again, and waits its turn. - run.update(update(0, Some(0), 1)); - assert_eq!(run.reoffered.len(), 1); - match narrow { - true => run.update(update(1, Some(1), 2)), - false => { - forward(&mut run, 0..1, &Hole::drop(StreamError::Cancel), &mut writer); - } - } - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened, - "narrow={narrow}: group 0 never opens again" - ); - let drops: &[(u64, u64, u64)] = match narrow { - // Outside the range now, so it is dropped again under the narrowing update. - true => &[(0, 0, 0), (0, 0, 2)], - false => &[(0, 0, 0), (0, 0, 1)], - }; - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - drops, - "narrow={narrow}" - ); - } - } - - /// A queued re-offer that a later update drops again as stale counts as given up: the - /// track's end leaves that stale drop standing, rather than replacing it with a final one. - #[kio::test] - async fn a_redropped_reoffer_stays_stale_at_the_end_on_lite07() { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let budget = Duration::from_millis(500); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - write_group(&mut track, 1, 1000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - write_group(&mut track, 2, 3000); - run.ctx.outcomes.dropped.lock().unwrap().push((0, StreamError::Old)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - // Update 1 widens the budget, so group 0 waits its turn; update 2 restores it first. - for (update, max_delay) in [(1, Duration::from_secs(10)), (2, budget)] { - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 0, - max_delay, - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update, - }); - } - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - track.finish_at(track::Position::group(3), None).unwrap(); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(0, 0, 0), (0, 0, 2)], - "group 0 is dropped again as stale under update 2, and never named again" - ); - } - - /// A drop the cursor gave up as final with OLD, as one relayed from a lite-06 upstream is, - /// goes out as a stale drop on lite-07, which the subscriber reopens on its next update, so - /// each update drops it again rather than leave it owed. - #[kio::test] - async fn a_final_old_drop_is_dropped_again_by_each_update_on_lite07() { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let subscriber = track.subscribe(None); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - forward(&mut run, 1..2, &Hole::drop(StreamError::Old), &mut writer); - for update in [1, 2] { - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 1, - max_delay: Duration::from_secs(3600), - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update, - }); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - } - assert_eq!( - drop_updates(&mut writer, &log, Version::Lite07).await, - [(1, 1, 0), (1, 1, 1), (1, 1, 2)] - ); - } - - /// A run one update left to drop again is judged again under the next update that - /// arrives before it goes out, rather than dropped under terms that may serve it. - #[kio::test] - async fn a_pending_redrop_is_judged_again_under_a_later_update() { - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let budget = Duration::from_millis(500); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); - write_group(&mut track, 0, 0); - write_group(&mut track, 1, 1000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - write_group(&mut track, 2, 3000); - run.ctx.outcomes.dropped.lock().unwrap().push((0, StreamError::Old)); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(drop_updates(&mut writer, &log, Version::Lite07).await, [(0, 0, 0)]); - - // Update 1 keeps the budget, so group 0 is left to drop again; update 2 widens it - // before that drop goes out. - for (update, max_delay) in [(1, budget), (2, Duration::from_secs(10))] { - run.update(lite::SubscribeUpdate { - wanted_group: None, - priority: 0, - max_delay, - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - update, - }); - } + run.update(update(Duration::from_secs(10))); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} assert_eq!( run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened + 2, - "group 0 is served again under update 2, beside group 2" + opened, + "group 0 is not served again" ); - assert_eq!(drop_updates(&mut writer, &log, Version::Lite07).await, [(0, 0, 0)]); + assert_eq!(drops(&mut writer, &log, Version::Lite07).await, [(0, 0)]); } /// Lite-05 and later name every key below the end that the subscription never @@ -9416,7 +8840,6 @@ mod serve_group_test { max_delay: Duration::from_secs(60), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], - update: 0, }); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} assert_eq!(drops(&mut writer, &log, version).await, [(2, 2)]); @@ -9843,7 +9266,6 @@ mod serve_group_test { max_delay: Duration::from_secs(60), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], - update: 0, }); { let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); @@ -9885,7 +9307,6 @@ mod serve_group_test { max_delay: Duration::from_secs(1), min_delay: None, ranges: vec![lite::Range::span(Some(0), 0, None, None)], - update: 0, }); { let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); @@ -9932,7 +9353,6 @@ mod serve_group_test { max_delay: Duration::from_secs(1), min_delay: None, ranges: vec![lite::Range::span(Some(start_group), 0, None, None)], - update: 0, }; run.replace(update(5)); { @@ -9979,7 +9399,6 @@ mod serve_group_test { max_delay: Duration::from_secs(10), min_delay: None, ranges: vec![lite::Range::span(Some(start_group), 0, None, None)], - update: 0, }; run.replace(update(5)); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} @@ -10026,7 +9445,6 @@ mod serve_group_test { max_delay: Duration::from_secs(60), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }); write_group(&mut track, 5, 5); assert_eq!(settle(&mut run), 1, "served a group below the latest"); @@ -10119,7 +9537,6 @@ mod serve_group_test { max_delay: Duration::from_secs(60), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }); write_group(&mut track, 0, 0); @@ -10257,7 +9674,6 @@ mod serve_group_test { max_delay: Duration::from_secs(30), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }); relay.settle(); assert_eq!(relay.opened(), 1, "the finished group is the live edge"); @@ -10288,7 +9704,6 @@ mod serve_group_test { max_delay: Duration::from_secs(30), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }); relay.settle(); assert_eq!(relay.opened(), 3, "group 0 is cached and now in range"); @@ -10316,7 +9731,6 @@ mod serve_group_test { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(Some(7), 0, None, None)], - update: 0, }; relay.run.replace(update); relay.settle(); @@ -10454,9 +9868,8 @@ mod serve_group_test { assert!(futures::poll!(run.as_mut()).is_pending(), "group 1 is still opening"); assert_eq!( *log.writes.lock().unwrap(), - // The DROP names group 0 as a start and count, with OLD (0x34) and the SUBSCRIBE's - // update, 0. - [0, 4, 1, 0, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0], + // The DROP names groups [0, 1) with OLD (0x34). + [0, 4, 1, 0, 1, 1, 2, 3, 0, 1, 0x34, 1, 2, 2, 0], "the expired group is dropped and the end precedes stream credit" ); @@ -10468,7 +9881,7 @@ mod serve_group_test { assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); assert_eq!( *log.writes.lock().unwrap(), - [0, 4, 1, 0, 1, 1, 2, 4, 0, 1, 0x34, 0, 1, 2, 2, 0] + [0, 4, 1, 0, 1, 1, 2, 3, 0, 1, 0x34, 1, 2, 2, 0] ); } } @@ -11188,7 +10601,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }; leave_request::(version, &subscribe, wait, close).await; @@ -11253,7 +10665,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) .unwrap(); @@ -11409,7 +10820,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, } } @@ -11754,7 +11164,6 @@ mod tests { max_delay: Duration::from_secs(60), min_delay: None, ranges: vec![lite::Range::span(start, 0, None, None)], - update: 0, }; let mut serve = SubscribeServe::start(&publisher.shared, msg, "video", broadcast.broadcast().consume()) @@ -11891,7 +11300,6 @@ mod tests { min_delay: None, // A relay asks from its cached group, so the SUBSCRIBE is not a live-edge join. ranges: vec![lite::Range::span(Some(1), 0, None, None)], - update: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) .unwrap(); @@ -11919,7 +11327,6 @@ mod tests { remove: Vec::new(), add: Vec::new(), }, - update: 0, }; session.push(&update(Some(2), 3).encode_bytes(version).unwrap()); session.push(&update(Some(2), 7).encode_bytes(version).unwrap()); @@ -11982,7 +11389,6 @@ mod tests { remove: Vec::new(), add: Vec::new(), }, - update: 0, } } @@ -12024,7 +11430,6 @@ mod tests { max_delay: Duration::from_secs(3600), min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) .unwrap(); @@ -12553,7 +11958,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }; let session = ScriptedSession::new(request.encode_bytes(version).unwrap().to_vec()); let log = session.log.clone(); @@ -12670,7 +12074,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }; let session = ScriptedSession::new(request.encode_bytes(version).unwrap().to_vec()); let log = session.log.clone(); @@ -12811,7 +12214,6 @@ mod tests { max_delay: Duration::ZERO, min_delay: None, ranges: vec![lite::Range::span(None, 0, None, None)], - update: 0, }; let mut script = Vec::new(); msg.encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 7e17aa6a199..d91c63fe020 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -36,10 +36,6 @@ pub struct Subscribe<'a> { /// Which pending group to send first. Lite07+ only; earlier wires decode as /// [`Order::Descending`] and cannot ask for anything else. pub order: Order, - /// The number of the terms in effect: the SUBSCRIBE is 0 and every SUBSCRIBE_UPDATE - /// carries a larger one, which a [`SubscribeDrop`] echoes. Lite07+ only; earlier wires - /// decode as 0 and drop it on encode. - pub update: u64, } impl Subscribe<'_> { @@ -57,7 +53,6 @@ impl Subscribe<'_> { min_delay: self.min_delay, ranges: self.ranges, order: self.order, - update: self.update, } } } @@ -157,8 +152,6 @@ impl<'a> Message<'a> for Subscribe<'a> { (order, max_delay, min_delay, decode_ranges(r, version)?) } }; - let update = decode_update(r, version)?; - Ok(Self { id, broadcast, @@ -171,7 +164,6 @@ impl<'a> Message<'a> for Subscribe<'a> { min_delay, ranges, order, - update, }) } @@ -193,28 +185,11 @@ impl<'a> Message<'a> for Subscribe<'a> { encode_ranges(w, version, &self.ranges)?; } } - encode_update(w, version, self.update)?; Ok(()) } } -/// Decode the `Update` number after the ranges. A wire without the field decodes as 0. -fn decode_update(r: &mut Decoder<'_>, version: Version) -> Result { - match version.has_skip() { - true => r.varint(), - false => Ok(0), - } -} - -/// Encode the `Update` number, dropping it on a wire without the field. -fn encode_update(w: &mut Encoder<'_>, version: Version, update: u64) -> Result<(), EncodeError> { - match version.has_skip() { - true => w.varint(update), - false => Ok(()), - } -} - /// Decode the `Subscriber Min Age` after the max age: milliseconds plus one, zero meaning not /// stated. A wire without the field decodes as not stated. fn decode_min_delay(r: &mut Decoder<'_>, version: Version) -> Result, DecodeError> { @@ -713,8 +688,6 @@ pub struct SubscribeUpdate { pub ranges: R, /// See [`Subscribe::order`]. pub order: Order, - /// See [`Subscribe::update`]: larger than the subscription's previous one. - pub update: u64, } impl SubscribeUpdate { @@ -727,7 +700,6 @@ impl SubscribeUpdate { min_delay: self.min_delay, ranges, order: self.order, - update: self.update, } } } @@ -760,7 +732,6 @@ impl<'a> Message<'a> for SubscribeUpdate { } false => RangeEdit::Replace(decode_ranges(r, version)?), }; - let update = decode_update(r, version)?; let wanted_group = match version.has_refresh() { true => r.varint()?.checked_sub(1), @@ -774,7 +745,6 @@ impl<'a> Message<'a> for SubscribeUpdate { min_delay, ranges, order, - update, }) } @@ -801,7 +771,6 @@ impl<'a> Message<'a> for SubscribeUpdate { (RangeEdit::Replace(ranges), false) => encode_ranges(w, version, ranges)?, _ => return Err(EncodeError::Version), } - encode_update(w, version, self.update)?; if version.has_refresh() { w.varint_opt(self.wanted_group)?; @@ -1040,7 +1009,9 @@ impl<'a> Message<'a> for SubscribeStarted { } /// Names groups that existed but will not be delivered: aborted or reset, evicted or -/// expired with no copy left, or stale. +/// expired with no copy left, or stale. Every drop is final on its subscription, a stale +/// (OLD) one included: a subscriber that still wants a group asks for it on a request of +/// its own. /// /// Lite03+; publishers send it on Lite05 and later. Before lite-07 it also names keys /// declared skipped, which lite-07 names in [`SubscribeSkip`]. @@ -1052,18 +1023,12 @@ pub struct SubscribeDrop { /// Why the groups were given up: a stream error code on lite-07 and later, or an /// application-specific code before, where 0 means simply unavailable. pub error: u64, - - /// The number of the SUBSCRIBE or SUBSCRIBE_UPDATE in effect when the groups were - /// given up ([`Subscribe::update`]): a stale (OLD) drop under a superseded one is no - /// verdict. Lite07+ only; earlier wires decode as 0. - pub update: u64, } #[cfg(feature = "async")] impl SubscribeDrop { - /// Name `groups` given up with `err` under the terms numbered `update`, as `version` - /// carries it. - pub fn new(groups: std::ops::Range, err: &StreamError, update: u64, version: Version) -> Self { + /// Name `groups` given up with `err`, as `version` carries it. + pub fn new(groups: std::ops::Range, err: &StreamError, version: Version) -> Self { Self { groups, // Before lite-07 the code is the application's, so it says nothing of why. @@ -1071,7 +1036,6 @@ impl SubscribeDrop { true => version.encode_stream_code(err).into(), false => 0, }, - update: if version.has_skip() { update } else { 0 }, } } @@ -1088,13 +1052,13 @@ impl SubscribeDrop { } } -/// A SUBSCRIBE_DROP or SUBSCRIBE_SKIP range: `Group Start` and `Group Count` on lite-07, an -/// inclusive `Group Start` and `Group End` before. Either way it ends by the reserved -/// key `u64::MAX`, so it never names that group. +/// A SUBSCRIBE_DROP or SUBSCRIBE_SKIP range: `Group Start` and an exclusive `Group End` past +/// it on lite-07, an inclusive `Group End` before. Either way it ends by the reserved key +/// `u64::MAX`, so it never names that group. fn decode_groups(r: &mut Decoder<'_>, version: Version) -> Result, DecodeError> { let start = r.varint()?; - let end = match version.has_group_count() { - true => start.checked_add(r.varint()?), + let end = match version.has_group_span() { + true => Some(r.varint()?).filter(|end| *end > start), false => r.varint()?.checked_add(1).filter(|end| *end >= start), }; Ok(start..end.ok_or(DecodeError::InvalidValue)?) @@ -1105,8 +1069,10 @@ fn encode_groups(w: &mut Encoder<'_>, groups: &std::ops::Range, version: Ve return Err(EncodeError::InvalidState); } w.varint(groups.start)?; - match version.has_group_count() { - true => w.varint(groups.end - groups.start), + match version.has_group_span() { + // A span names at least one key. + true if groups.is_empty() => Err(EncodeError::InvalidState), + true => w.varint(groups.end), // An empty range at 0 has no inclusive end to spell. false => w.varint(groups.end.checked_sub(1).ok_or(EncodeError::InvalidState)?), } @@ -1124,8 +1090,7 @@ impl<'a> Message<'a> for SubscribeDrop { let groups = decode_groups(r, version)?; let error = r.varint()?; - let update = decode_update(r, version)?; - Ok(Self { groups, error, update }) + Ok(Self { groups, error }) } fn encode_msg(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { @@ -1138,7 +1103,6 @@ impl<'a> Message<'a> for SubscribeDrop { encode_groups(w, &self.groups, version)?; w.varint(self.error)?; - encode_update(w, version, self.update)?; Ok(()) } @@ -1278,7 +1242,6 @@ mod test { let msg = SubscribeDrop { groups: groups.clone(), error: 0, - update: 0, }; let data = msg.encode_bytes(version).unwrap(); assert_eq!(SubscribeDrop::decode_slice(&data, version).unwrap().0.groups, groups); @@ -1286,11 +1249,12 @@ mod test { } } - /// Lite-07 carries Group Start and Group Count, which reach but never pass the reserved - /// group `u64::MAX`. + /// Lite-07 carries Group Start and an exclusive Group End, which reaches but never passes + /// the reserved group `u64::MAX`. A span names at least one key: an End not past the + /// Start is malformed, and so is encoding an empty span. #[test] - fn skip_ranges_on_lite07_count_up_to_the_reserved_group() { - for groups in [0..0, 3..4, 0..u64::MAX, u64::MAX..u64::MAX] { + fn spans_on_lite07_name_at_least_one_key() { + for groups in [3..4, 0..u64::MAX, u64::MAX - 1..u64::MAX] { let msg = SubscribeSkip { groups: groups.clone() }; let data = msg.encode_bytes(Version::Lite07).unwrap(); assert_eq!( @@ -1298,23 +1262,22 @@ mod test { groups ); } - // Group Start 2^64-1, Group Count 1. - let mut data = SubscribeSkip { - groups: u64::MAX..u64::MAX, + // Group Start 3, Group End 3 and 2: empty and reversed. + for end in [3, 2] { + assert!(matches!( + SubscribeSkip::decode_slice(&[2, 3, end], Version::Lite07), + Err(DecodeError::InvalidValue) + )); + assert!(matches!( + SubscribeDrop::decode_slice(&[3, 3, end, 0], Version::Lite07), + Err(DecodeError::InvalidValue) + )); } - .encode_bytes(Version::Lite07) - .unwrap() - .to_vec(); - *data.last_mut().unwrap() = 1; - assert!(matches!( - SubscribeSkip::decode_slice(&data, Version::Lite07), - Err(DecodeError::InvalidValue) - )); + assert!(SubscribeSkip { groups: 3..3 }.encode_bytes(Version::Lite07).is_err()); for version in [Version::Lite06, Version::Lite07] { let reversed = SubscribeDrop { groups: std::ops::Range { start: 3, end: 1 }, error: 0, - update: 0, }; assert!(reversed.encode_bytes(version).is_err()); } @@ -1428,16 +1391,12 @@ mod test { #[test] fn subscribe_drop_is_restored_on_lite07() { - let resp = SubscribeResponse::Drop(SubscribeDrop { - groups: 1..4, - error: 7, - update: 0, - }); + let resp = SubscribeResponse::Drop(SubscribeDrop { groups: 1..4, error: 7 }); let mut buf = Vec::new(); resp.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) .unwrap(); - // Groups 1 to 3 as a start and count; the drop names the SUBSCRIBE's update, 0. - assert_eq!(buf, [2, 4, 1, 3, 7, 0]); + // Groups 1 to 3 as a start and an exclusive end. + assert_eq!(buf, [2, 3, 1, 4, 7]); match crate::coding::decode_buf(&mut buf.as_slice(), Version::Lite07, |r, v| { SubscribeResponse::decode(r, v) }) @@ -1448,31 +1407,12 @@ mod test { } } - /// A drop names the update it was given up under on lite-07; earlier versions carry none. - #[test] - fn a_drop_names_its_update_on_lite07() { - let msg = SubscribeDrop { - groups: 4..5, - error: 0x34, - update: 2, - }; - let buf = msg.encode_bytes(Version::Lite07).unwrap(); - assert_eq!(buf.as_ref(), [4, 4, 1, 0x34, 2]); - let (decoded, _) = SubscribeDrop::decode_slice(&buf, Version::Lite07).unwrap(); - assert_eq!(decoded, msg); - let msg = SubscribeDrop { error: 0, ..msg }; - let buf = msg.encode_bytes(Version::Lite06).unwrap(); - assert_eq!(buf.as_ref(), [3, 4, 4, 0]); - let (decoded, _) = SubscribeDrop::decode_slice(&buf, Version::Lite06).unwrap(); - assert_eq!(decoded.update, 0); - } - /// SUBSCRIBE_SKIP is type 3 on lite-07 and unknown before it. #[test] fn subscribe_skip_is_lite07_only() { let resp = SubscribeResponse::Skip(SubscribeSkip { groups: 1..4 }); let buf = resp.encode_bytes(Version::Lite07).unwrap(); - assert_eq!(buf.as_ref(), [3, 2, 1, 3]); + assert_eq!(buf.as_ref(), [3, 2, 1, 4]); match SubscribeResponse::decode_slice(&buf, Version::Lite07).unwrap().0 { SubscribeResponse::Skip(skip) => assert_eq!(skip, SubscribeSkip { groups: 1..4 }), other => panic!("expected Skip, got {other:?}"), @@ -1484,25 +1424,9 @@ mod test { )); } - /// SUBSCRIBE and SUBSCRIBE_UPDATE carry their update number on lite-07 alone. - #[test] - fn update_number_roundtrips_only_on_lite07() { - for version in [Version::Lite06, Version::Lite07] { - let mut msg = subscribe_sample(); - msg.update = 5; - let buf = encode(&msg, version).unwrap(); - let decoded = crate::coding::decode_from(&mut buf.as_slice(), version, Subscribe::decode_msg).unwrap(); - assert_eq!(decoded.update, if version.has_skip() { 5 } else { 0 }); - } - } - #[test] fn subscribe_drop_is_type_2_on_lite05() { - let resp = SubscribeResponse::Drop(SubscribeDrop { - groups: 1..4, - error: 0, - update: 0, - }); + let resp = SubscribeResponse::Drop(SubscribeDrop { groups: 1..4, error: 0 }); let mut buf = Vec::new(); resp.encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05) .unwrap(); @@ -1518,11 +1442,7 @@ mod test { #[test] fn subscribe_drop_is_type_1_on_lite04() { - let resp = SubscribeResponse::Drop(SubscribeDrop { - groups: 1..4, - error: 0, - update: 0, - }); + let resp = SubscribeResponse::Drop(SubscribeDrop { groups: 1..4, error: 0 }); let mut buf = Vec::new(); resp.encode(&mut Encoder::new(&mut buf, Version::Lite04.into()), Version::Lite04) .unwrap(); @@ -1552,7 +1472,6 @@ mod test { start: absolute(7, 0), end: absolute(10, 0), }], - update: 0, } } @@ -1755,7 +1674,6 @@ mod test { min_delay: None, ranges: sent.edit(&msg.ranges).unwrap(), order: crate::track::Order::Ascending, - update: 0, }; let buf = update.encode_bytes(Version::Lite07).unwrap(); let got = crate::coding::decode_buf(&mut buf.as_ref(), Version::Lite07, |r, v| SubscribeUpdate::decode(r, v)) @@ -1827,7 +1745,6 @@ mod test { min_delay: None, ranges: edit, order: crate::track::Order::Descending, - update: 0, }; let buf = update.encode_bytes(version).unwrap(); let got = @@ -1929,10 +1846,9 @@ mod test { msg.ranges = vec![Range::OLDEST]; let mut buf = encode(&msg, version).unwrap(); - // The list is last but for the update number: a count of one, then two anchors of - // type 0. - let at = buf.len() - 4; - assert_eq!(&buf[at..], [1, 0, 0, 0]); + // The list is last: a count of one, then two anchors of type 0. + let at = buf.len() - 3; + assert_eq!(&buf[at..], [1, 0, 0]); buf[at] = 0; buf.truncate(at + 1); assert!(matches!( @@ -1941,7 +1857,7 @@ mod test { )); let mut buf = encode(&msg, version).unwrap(); - let last = buf.len() - 2; + let last = buf.len() - 1; buf[last] = 4; assert!(matches!( crate::coding::decode_from(&mut buf.as_slice(), version, Subscribe::decode_msg), @@ -2007,7 +1923,6 @@ mod test { min_delay: None, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order: crate::track::Order::Descending, - update: 0, }; let buf = update.encode_bytes(version).unwrap(); let got = crate::coding::decode_buf(&mut buf.as_ref(), version, |r, v| SubscribeUpdate::decode(r, v)) @@ -2041,7 +1956,6 @@ mod test { min_delay, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order: crate::track::Order::Descending, - update: 0, }; let buf = update.encode_bytes(version).unwrap(); let got = crate::coding::decode_buf(&mut buf.as_ref(), version, |r, v| SubscribeUpdate::decode(r, v)) @@ -2070,7 +1984,6 @@ mod test { min_delay: None, ranges: LiveRanges::new(version, &[Range::OLDEST]).unchanged(), order, - update: 0, }; let mut buf = Vec::new(); update diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 2dcfa8c5857..7a809883903 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -20,7 +20,6 @@ use super::Version; use crate::tail::{self, Reading, Settle, Tail}; use kio::Lock; -use rangemap::RangeSet; mod fills; use fills::{FillAsk, RangeFills}; @@ -271,41 +270,21 @@ struct Yielding { verdict: YieldVerdict, } -/// A stale verdict expires on the next update; a final drop never does. A group already -/// accounted before its header stays accounted even if a later stale drop expires. +/// What a YIELDED reset of the stream leaves of its group: still owed a continuation, or +/// accounted already, by a drop that overtook the header or one that named the group since, +/// which ends it. Every drop is final, a stale one included. enum YieldVerdict { Owed, Accounted, - Stale { under: u64, error: Error }, - AccountedStale { under: u64, error: Error }, Dropped(Error), } impl YieldVerdict { - fn updated(self, updates: u64) -> Self { - match self { - Self::Stale { under, .. } if under < updates => Self::Owed, - Self::AccountedStale { under, .. } if under < updates => Self::Accounted, - verdict => verdict, - } - } - - fn drop_with(&mut self, error: Error, under: Option) { - *self = match under { - Some(_) if matches!(self, Self::Dropped(_)) => return, - Some(under) if matches!(self, Self::Accounted | Self::AccountedStale { .. }) => { - Self::AccountedStale { under, error } - } - Some(under) => Self::Stale { under, error }, - None => Self::Dropped(error), - }; - } - fn error(self) -> Option { match self { Self::Owed => None, Self::Accounted => Some(Error::Stream(crate::StreamError::Old)), - Self::Stale { error, .. } | Self::AccountedStale { error, .. } | Self::Dropped(error) => Some(error), + Self::Dropped(error) => Some(error), } } } @@ -328,9 +307,10 @@ struct Opened { reading: Reading, } -/// A group stream duplicating a copy still arriving, such as a lite-07 re-offer that -/// overtook the reset of the stream it replaces. It waits unread, which its stream credit -/// bounds, and is discarded if that copy finishes or takes the group if it fails. +/// A group stream duplicating a copy still arriving, such as a lite-07 continuation that +/// overtook the YIELDED reset of the stream it continues, or another subscription's stream +/// feeding the same copy. It waits unread, which its stream credit bounds, and is discarded +/// if that copy finishes or takes the group if it fails. struct Duplicate { /// The copy still arriving, whose readers wait while this holds it. arriving: track::Hold, @@ -385,9 +365,6 @@ impl Drop for ParkWait { impl TrackEntry { fn new(copy: Option, tail: kio::Producer) -> Self { - if let Some(copy) = © { - Self::bill_tail(&tail, copy); - } Self { copy, parked: None, @@ -422,17 +399,7 @@ impl TrackEntry { } /// Give the copy to the subscription, opening the groups of the streams parked on it. - /// Bill what the tail keeps to the copy's account. - fn bill_tail(tail: &kio::Producer, copy: &Accepted) { - // Opened before the tail's lock, which is never held across the track's. - let bill = copy.producer.bill(); - if let Ok(mut tail) = tail.write() { - tail.bill(bill); - } - } - fn accept(&mut self, copy: Accepted, version: Version, now: crate::time::Instant) { - Self::bill_tail(&self.tail, ©); self.copy = Some(copy); let Some(parked) = self.parked.clone() else { return; @@ -500,9 +467,6 @@ impl TrackEntry { return Err(Error::Cancel); }; let group_info = group::Info { start: hdr.key }; - // A stale drop that overtook this stream, which the group replaces: the next update - // supersedes that verdict, so a YIELDED reset after it pauses the group. - let stale = producer.holds_stale(hdr.key); // Stats (groups/frames/bytes) are counted in the model as the group // is written, through the tagged `track::Producer`. The track counts // it as content once its first frame lands. @@ -534,15 +498,9 @@ impl TrackEntry { } } } - let verdict = if owed { - YieldVerdict::Owed - } else if stale { - YieldVerdict::Stale { - under: self.tail.read().updates(), - error: Error::Stream(crate::StreamError::Old), - } - } else { - YieldVerdict::Accounted + let verdict = match owed { + true => YieldVerdict::Owed, + false => YieldVerdict::Accounted, }; self.place(hdr, version, received, reading, verdict) } @@ -632,25 +590,20 @@ impl TrackEntry { /// Stop tracking the stream reading `key`, returning whether a YIELDED reset pauses it. /// A stream that a later one for the same group replaced finds nothing, leaving the - /// later stream's record in place. A stale drop an update sent since superseded no - /// longer ends the group. + /// later stream's record in place. fn end_yielding(&mut self, key: u64, stream: u64) -> Option { - let mut yielding = match self.yielding.get(&key) { - Some(yielding) if yielding.stream == stream => self.yielding.remove(&key)?, - _ => return None, - }; - yielding.verdict = yielding.verdict.updated(self.tail.read().updates()); - Some(yielding) + match self.yielding.get(&key) { + Some(yielding) if yielding.stream == stream => self.yielding.remove(&key), + _ => None, + } } - /// A SUBSCRIBE_DROP named `groups` with `err`, `stale` when it is a lite-07 stale verdict: a - /// paused group ends there, and one a stream is reading ends with it if a YIELDED reset - /// would otherwise pause it, since no continuation follows, unless an update supersedes a - /// stale drop first. - fn dropped(&mut self, groups: std::ops::Range, err: &Error, stale: bool) { - let updates = stale.then(|| self.tail.read().updates()); + /// A SUBSCRIBE_DROP named `groups` with `err`: a paused group ends there, and one a stream + /// is reading ends with it if a YIELDED reset would otherwise pause it, since no + /// continuation follows. + fn dropped(&mut self, groups: std::ops::Range, err: &Error) { for (_, yielding) in self.yielding.range_mut(groups.clone()) { - yielding.verdict.drop_with(err.clone(), updates); + yielding.verdict = YieldVerdict::Dropped(err.clone()); } let Some(registry) = &self.paused else { return; @@ -1875,10 +1828,7 @@ impl GroupRecv { }); let res = match res { Ok(()) => { - // Only a lite-07 stale drop asks which groups arrived whole. - if group.finish().is_ok() && self.subscriber.version.has_skip() { - reading.finish(); - } + let _ = group.finish(); Ok(()) } Err(err @ (Error::Cancel | Error::Stream(crate::StreamError::Cancel))) => { @@ -3791,6 +3741,7 @@ mod tests { .unwrap(), id: 0, max_delay: Duration::ZERO, + stale_budget: Duration::ZERO, min_delay: None, start: None, priority: 0, @@ -3809,8 +3760,6 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }) } @@ -3953,6 +3902,7 @@ mod tests { .unwrap(), id: 0, max_delay: Duration::ZERO, + stale_budget: Duration::ZERO, min_delay: None, start: Some(floor), priority: 0, @@ -3971,8 +3921,6 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }); if update { h.serve @@ -4428,6 +4376,7 @@ mod tests { stream, id: 0, max_delay: Duration::ZERO, + stale_budget: Duration::ZERO, min_delay: None, start: Some(2), priority: 0, @@ -4446,8 +4395,6 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }; assert_eq!( sub.owed(None), @@ -4545,6 +4492,7 @@ mod tests { stream, id: 0, max_delay: Duration::ZERO, + stale_budget: Duration::ZERO, min_delay: None, start: Some(4), priority: 0, @@ -4563,8 +4511,6 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }; assert_eq!(sub.fill_range(0), None, "the demand's range is no fill"); @@ -4614,6 +4560,7 @@ mod tests { stream, id: 0, max_delay: Duration::ZERO, + stale_budget: Duration::ZERO, min_delay: None, start: Some(4), priority: 0, @@ -4632,8 +4579,6 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }; assert_eq!(sub.owed(None), Some(vec![4..10])); @@ -5994,7 +5939,7 @@ mod tests { .lock() .get_mut(&7) .unwrap() - .dropped(3..4, &Error::Stream(crate::StreamError::Old), true); + .dropped(3..4, &Error::Stream(crate::StreamError::Old)); yielded.close(Close::ResetStream(crate::StreamError::Yielded.to_code())); let res = kio::wait(|waiter| first.poll_serve(waiter)).await; assert!(res.is_ok(), "{res:?}"); @@ -6007,94 +5952,10 @@ mod tests { ); } - /// Lite-07: a stale drop that overtook the YIELDED reset of the stream it names holds only - /// under the update it names: once the subscriber sends another, the reset pauses the - /// group, which the publisher then continues or drops again. + /// Lite-07: a stale drop that overtook the header of the stream it names is final, so a + /// YIELDED reset of that stream ends the group as stale rather than pausing it. #[kio::test] - async fn a_yielded_group_pauses_once_an_update_supersedes_its_stale_drop() { - use crate::lite::test_transport::{Close, ScriptedSession}; - use crate::transport::poll::Session as _; - - let version = Version::Lite07; - let mut script = Vec::new(); - let mut encoder = crate::coding::Encoder::new(&mut script, version.into()); - lite::Group { - subscribe: 7, - key: 3, - frame_start: 0, - } - .encode(&mut encoder, version) - .unwrap(); - encoder.varint(2).unwrap(); - encoder.varint(crate::coding::varint::zigzag(300)).unwrap(); - script.push(b'x'); - let yielded = ScriptedSession::new(script); - let clock = crate::time::Deadlines::new(crate::time::Instant::now()); - let subscriber = Subscriber::new(SubscriberConfig { - runtime: clock.clone(), - session: crate::driver::Transport::new(yielded.clone()), - origin: origin::Config::new(std::num::NonZeroU64::new(1).unwrap()).produce(), - recv_bandwidth: None, - version, - peer_setup: crate::lite::PeerSetup::new(false, crate::transport::Address::Setup), - peer_hop: None, - cost: None, - going_away: Default::default(), - auth: crate::auth::Link::new(false), - }); - let track = track::Producer::new( - std::sync::Arc::new(crate::broadcast::Info::default()), - "video", - crate::track::Info::timed(), - ); - let subscription = crate::track::Subscription::default() - .with_delay(crate::track::Delay::default().with_max(std::time::Duration::from_secs(10))) - .with_range(0..); - let mut reader = track.subscribe(subscription); - let framing = lite::Framing { - timescale: Some(Timescale::MILLI), - ietf: None, - compressed: false, - length_first: true, - }; - let tail = kio::Producer::new(Tail::default()); - subscriber - .subscribes - .lock() - .insert(7, TrackEntry::accepted(track.clone(), framing, tail.clone())); - - let (_, recv) = yielded.open_bi(Default::default()).await.unwrap(); - let mut first = GroupRecv::new( - subscriber.clone(), - Reader::new(crate::transport::boxed::RecvStream::new(recv), version), - ); - assert!(first.poll_serve(&kio::Waiter::noop()).is_pending()); - let mut group = reader.assert_group(); - // The publisher gave the group up after pausing it, and its drop lands first. - subscriber - .subscribes - .lock() - .get_mut(&7) - .unwrap() - .dropped(3..4, &Error::Stream(crate::StreamError::Old), true); - // An update supersedes it, as `buffer_update` does. - tail.write().ok().expect("the tail is open").updated(); - yielded.close(Close::ResetStream(crate::StreamError::Yielded.to_code())); - let res = kio::wait(|waiter| first.poll_serve(waiter)).await; - assert!(res.is_ok(), "{res:?}"); - - let read = group.read_frame().await; - assert!(matches!(read, Ok(Some(_))), "the frame that arrived stays: {read:?}"); - let subs = subscriber.subscribes.lock(); - let paused = subs.get(&7).unwrap().paused.as_ref().unwrap().read(); - assert!(paused.groups.contains_key(&3), "the group pauses"); - } - - /// Lite-07: a stale drop that overtook the header of the stream it names holds only under - /// the update it names: once the subscriber sends another, a YIELDED reset of that stream - /// pauses the group rather than ending it as stale. - #[kio::test] - async fn a_yielded_group_pauses_once_an_update_supersedes_a_stale_drop_before_its_header() { + async fn a_yielded_group_ends_on_a_stale_drop_before_its_header() { use crate::lite::test_transport::{Close, ScriptedSession}; use crate::transport::poll::Session as _; @@ -6157,17 +6018,16 @@ mod tests { ); assert!(first.poll_serve(&kio::Waiter::noop()).is_pending()); let mut group = reader.assert_group(); - // An update supersedes it, as `buffer_update` does. - tail.write().ok().expect("the tail is open").updated(); yielded.close(Close::ResetStream(crate::StreamError::Yielded.to_code())); let res = kio::wait(|waiter| first.poll_serve(waiter)).await; assert!(res.is_ok(), "{res:?}"); let read = group.read_frame().await; - assert!(matches!(read, Ok(Some(_))), "the frame that arrived stays: {read:?}"); - let subs = subscriber.subscribes.lock(); - let paused = subs.get(&7).unwrap().paused.as_ref().unwrap().read(); - assert!(paused.groups.contains_key(&3), "the group pauses"); + assert!(matches!(read, Err(Error::Stream(crate::StreamError::Old))), "{read:?}"); + assert!( + subscriber.subscribes.lock().get(&7).unwrap().paused.is_none(), + "nothing paused" + ); } /// A SUBSCRIBE_FINISH below a group already received contradicts that group. lite-05 @@ -6426,8 +6286,8 @@ mod tests { assert!(matches!(reader.recv_group().await, Err(Error::ProtocolViolation))); } - /// A lite-07 subscription's serve loop with an active SUBSCRIBE under update 0 and the - /// max age `budget`, its broadcast, and the tail it accounts on. + /// A lite-07 subscription's serve loop with an active SUBSCRIBE under the max age `budget`, + /// its broadcast, and the tail it accounts on. async fn lite07_serving( budget: Duration, ) -> (TrackServe, ServeLoop, kio::Producer, crate::broadcast::Producer) { @@ -6467,6 +6327,7 @@ mod tests { .unwrap(), id: 0, max_delay: budget, + stale_budget: budget, min_delay: None, start: None, priority: 0, @@ -6485,16 +6346,13 @@ mod tests { wanted: None, unanswered: None, _working: crate::session::Work::default().start(), - update: 0, - stale: RangeSet::new(), }); (serve, serving, tail, broadcast) } /// A stale drop of part of a fill's run recovers that part on its own subscription, which - /// takes it out of the copy's ranges at once, though the rest of the run stays asked: left - /// in, any later update would reopen the stale drop and the publisher would serve the - /// recovered groups on both. + /// takes it out of the copy's ranges at once, though the rest of the run stays asked: the + /// subscription that dropped it never delivers it. #[kio::test] #[expect(clippy::single_range_in_vec_init, reason = "the asked runs are a list, here one")] async fn a_recovered_run_leaves_the_subscription() { @@ -6546,33 +6404,11 @@ mod tests { ); } - /// A SUBSCRIBE_DROP can only echo an update the subscriber sent: one naming a later update - /// is a protocol violation, and accounts for nothing. + /// On lite-07 an OLD drop is final, recorded as a stale verdict under the narrowest budget + /// the subscription asked: a SUBSCRIBE_UPDATE widening the budget reopens nothing, and an + /// OLD drop arriving after it may have been judged before the publisher read it. #[kio::test] - async fn a_drop_naming_an_unsent_update_is_a_protocol_violation() { - let (serve, mut serving, tail, _broadcast) = lite07_serving(Duration::from_millis(500)).await; - let drop = lite::SubscribeResponse::Drop(lite::SubscribeDrop { - groups: 1..3, - error: u64::from(crate::coding::StreamCodes::encode_stream_code( - &Version::Lite07, - &crate::StreamError::Old, - )), - update: 1, - }); - assert!(matches!( - serving.apply_response(&serve, drop), - Err(Error::ProtocolViolation) - )); - assert!(!tail.read().covers(1..3)); - } - - /// On lite-07 an OLD drop is a stale verdict judged under the budget this subscriber sent - /// with the update it names. Any SUBSCRIBE_UPDATE reopens every stale run in the tail, - /// whether or not it widens the budget, and an OLD drop naming a superseded update is no - /// verdict: still owed, and given up on no reader. Any other drop is final, whatever update - /// it names. - #[kio::test] - async fn an_update_reopens_every_stale_drop_and_supersedes_the_rest() { + async fn an_update_reopens_no_stale_drop() { let version = Version::Lite07; let budget = Duration::from_millis(500); let (serve, mut serving, tail, _broadcast) = lite07_serving(budget).await; @@ -6582,70 +6418,40 @@ mod tests { .with_ranges([crate::track::Range::groups(0..)]), ); let waiter = kio::Waiter::noop(); - let code = |err: &crate::StreamError| u64::from(crate::coding::StreamCodes::encode_stream_code(&version, err)); - let drop = |first, last: u64, err: &crate::StreamError, update| { - lite::SubscribeResponse::Drop(lite::SubscribeDrop { - groups: first..last + 1, - error: code(err), - update, - }) + let old = |groups: std::ops::Range| { + lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(groups, &crate::StreamError::Old, version)) }; let covers = |groups: std::ops::Range| tail.read().covers(groups); - serving - .apply_response(&serve, drop(1, 2, &crate::StreamError::Old, 0)) - .unwrap(); + serving.apply_response(&serve, old(1..3)).unwrap(); assert!(covers(1..3)); assert_eq!( reader.poll_drop(&waiter), - Poll::Ready((1..3, track::Hole::stale(budget))), - "judged under the budget sent with update 0" + Poll::Ready((1..3, track::Hole::stale(budget))) ); - // An update that keeps the budget and the ranges still reopens the stale run. { let Sub::Active(active) = &mut serving.sub else { unreachable!("an active subscription"); }; + active.max_delay = Duration::from_secs(5); let ranges = active.live.unchanged(); - buffer_update(active, ranges, &serving.serving, serve.subscriber.runtime.now()).unwrap(); - assert_eq!(active.update, 1); - assert!(active.stale.is_empty()); + buffer_update(active, ranges).unwrap(); } - assert!(!covers(1..3), "the publisher re-offers or drops it again"); - - // Still in flight from before the update: no verdict. - serving - .apply_response(&serve, drop(4, 4, &crate::StreamError::Old, 0)) - .unwrap(); - assert!(!covers(4..5), "still owed"); - assert!(reader.poll_drop(&waiter).is_pending(), "no reader settles on it"); - - // Any other drop is final, whatever update it names. - serving - .apply_response(&serve, drop(5, 5, &crate::StreamError::App(5), 0)) - .unwrap(); - assert!(covers(5..6)); - assert_eq!( - reader.poll_drop(&waiter), - Poll::Ready((5..6, track::Hole::drop(crate::StreamError::App(5)))) - ); + assert!(covers(1..3), "still accounted for"); + assert!(reader.poll_drop(&waiter).is_pending(), "reported once"); - // Under the current update, a stale drop is a verdict again. - serving - .apply_response(&serve, drop(6, 6, &crate::StreamError::Old, 1)) - .unwrap(); - assert!(covers(6..7)); + serving.apply_response(&serve, old(4..5)).unwrap(); + assert!(covers(4..5)); assert_eq!( reader.poll_drop(&waiter), - Poll::Ready((6..7, track::Hole::stale(budget))) + Poll::Ready((4..5, track::Hole::stale(budget))) ); } - /// A group that arrives over a lite-07 stale (OLD) drop wins over it, whichever lands first: - /// the publisher serves a group after its stale drop, as a front that switched routes does, - /// and the group's stream may overtake the drop. The next update owes it no more, and a - /// group still arriving is never aborted by the drop. + /// A group that arrives over a lite-07 stale (OLD) drop wins over it in the copy, whichever + /// lands first: the group's stream may overtake the drop, or a recovery may deliver it. A + /// group still arriving is never aborted by the drop, and an update owes none of them again. #[kio::test] async fn a_group_wins_over_its_stale_drop() { let version = Version::Lite07; @@ -6659,7 +6465,6 @@ mod tests { lite::SubscribeResponse::Drop(lite::SubscribeDrop { groups: key..key + 1, error: code, - update: 0, }) }; let frame = |mut group: crate::group::Producer| { @@ -6690,116 +6495,15 @@ mod tests { unreachable!("an active subscription"); }; let ranges = active.live.unchanged(); - buffer_update(active, ranges, &serving.serving, now()).unwrap(); + buffer_update(active, ranges).unwrap(); } - let covers = |groups: std::ops::Range| tail.read().covers(groups); - assert!(covers(1..4), "every group that arrived stays accounted for"); - assert!(!covers(4..5), "the group that never arrived is owed again"); + assert!(tail.read().covers(1..5), "every group stays accounted for"); frame(two).expect("the drop leaves a group still arriving"); frame(three).expect("the update leaves a group still arriving"); } - /// A group whose stream finished wins over a lite-07 stale drop that lands after the cache - /// evicted it: the publisher served it over that drop, so the next update owes it no more. - /// A stream that finished under an earlier update says nothing of a drop under the new one. - #[kio::test] - async fn a_finished_group_wins_over_a_late_stale_drop_once_evicted() { - let version = Version::Lite07; - let (serve, mut serving, tail, _broadcast) = lite07_serving(Duration::from_millis(500)).await; - let now = || serve.subscriber.runtime.now(); - let code = u64::from(crate::coding::StreamCodes::encode_stream_code( - &version, - &crate::StreamError::Old, - )); - let old = |key: u64, update| { - lite::SubscribeResponse::Drop(lite::SubscribeDrop { - groups: key..key + 1, - error: code, - update, - }) - }; - serve.subscriber.subscribes.lock().insert( - 0, - TrackEntry::accepted( - serving.serving.clone(), - lite::Framing { - timescale: Some(Timescale::MILLI), - ietf: None, - compressed: false, - length_first: false, - }, - tail.clone(), - ), - ); - // A group stream that arrives whole, through the path that records it, then is evicted. - let arrive = async |serving: &mut ServeLoop, key| { - use crate::transport::poll::Session as _; - - let mut script = Vec::new(); - let mut encoder = crate::coding::Encoder::new(&mut script, version.into()); - lite::Group { - subscribe: 0, - key, - frame_start: 0, - } - .encode(&mut encoder, version) - .unwrap(); - // A frame at the group's key, since starts strictly increase. - encoder.varint(crate::coding::varint::zigzag(key as i64)).unwrap(); - encoder.bytes(b"x").unwrap(); - let session = crate::lite::test_transport::ScriptedSession::eof(script); - let (_, recv) = session.open_bi(Default::default()).await.unwrap(); - let mut group = GroupRecv::new( - serve.subscriber.clone(), - Reader::new(crate::transport::boxed::RecvStream::new(recv), version), - ); - kio::wait(|waiter| group.poll_serve(waiter)).await.unwrap(); - serving.serving.evict(key); - }; - let update = |serving: &mut ServeLoop| { - let Sub::Active(active) = &mut serving.sub else { - unreachable!("an active subscription"); - }; - let ranges = active.live.unchanged(); - buffer_update(active, ranges, &serving.serving, now()).unwrap(); - }; - let covers = |groups: std::ops::Range| tail.read().covers(groups); - - arrive(&mut serving, 1).await; - serving.apply_response(&serve, old(1, 0)).unwrap(); - update(&mut serving); - assert!(covers(1..2), "the evicted group that arrived stays accounted for"); - - // Finished under the first update, then judged stale under the second. - arrive(&mut serving, 2).await; - update(&mut serving); - serving.apply_response(&serve, old(2, 2)).unwrap(); - update(&mut serving); - assert!( - !covers(2..3), - "a drop under a later update is the publisher's to re-offer" - ); - - // Under the pool's debt the tail folds what finished, gaps and all. A group in the span - // whose stream arrived before its stale drop still wins over it; a gap there the drop - // accounted first is owed again. - for key in [3, 5, 7] { - arrive(&mut serving, key).await; - } - if let Ok(mut state) = tail.write() { - assert!(state.fold()); - } - serving.apply_response(&serve, old(3, 3)).unwrap(); - serving.apply_response(&serve, old(4, 3)).unwrap(); - update(&mut serving); - assert!(covers(3..4), "the folded group that arrived stays accounted for"); - assert!(!covers(4..5), "the folded gap is the publisher's to re-offer"); - } - - /// A SKIP, or any final drop, that follows an OLD drop of the same groups replaces it: an - /// update reopens only stale verdicts, so the groups stay accounted for, and the skip - /// stays final rather than being superseded with the OLD drop. An empty range names - /// nothing. + /// A SKIP, or any final drop, that follows an OLD drop of the same groups replaces it in + /// the copy, and an update reopens none of them. An empty range names nothing. #[kio::test] async fn a_skip_or_final_drop_replaces_an_earlier_stale_one() { let version = Version::Lite07; @@ -6813,7 +6517,6 @@ mod tests { lite::SubscribeResponse::Drop(lite::SubscribeDrop { groups: first..last + 1, error: code, - update: 0, }) }; let covers = |groups: std::ops::Range| tail.read().covers(groups); @@ -6829,7 +6532,7 @@ mod tests { serving .apply_response( &serve, - lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(4..5, &crate::StreamError::App(5), 0, version)), + lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(4..5, &crate::StreamError::App(5), version)), ) .unwrap(); // Empty ranges. @@ -6846,7 +6549,7 @@ mod tests { unreachable!("an active subscription"); }; let ranges = active.live.unchanged(); - buffer_update(active, ranges, &serving.serving, serve.subscriber.runtime.now()).unwrap(); + buffer_update(active, ranges).unwrap(); } assert!(covers(1..3), "the skip is final"); assert!(covers(4..5), "the drop is final"); @@ -6867,7 +6570,7 @@ mod tests { let version = Version::Lite07; let (serve, mut serving, tail, _broadcast) = lite07_serving(Duration::from_millis(500)).await; let drop = |first, last: u64, error: &crate::StreamError| { - lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(first..last + 1, error, 0, version)) + lite::SubscribeResponse::Drop(lite::SubscribeDrop::new(first..last + 1, error, version)) }; let skip = |first, last: u64| { lite::SubscribeResponse::Skip(lite::SubscribeSkip { @@ -6933,7 +6636,6 @@ mod tests { lite::SubscribeResponse::Drop(lite::SubscribeDrop { groups: 2..3, error: code.into(), - update: 0, }), ] { resp.encode( @@ -11344,6 +11046,11 @@ struct SubStream { /// Original SUBSCRIBE params, echoed in every SUBSCRIBE_UPDATE; refreshed as the /// downstream aggregate changes. max_delay: Duration, + /// The narrowest max delay this subscription has asked, which a lite-07 stale drop is + /// recorded under: the wire does not say which update a drop crossed, so it may have been + /// judged under any budget asked before it arrived. Too narrow costs a wider reader a + /// request of its own; too wide would settle it on a group it could still get. + stale_budget: Duration, min_delay: Option, /// The lowest absolute start among the ranges, or `None` when one counts back from /// the latest group: the floor below which nothing is asked for. @@ -11393,12 +11100,6 @@ struct SubStream { /// without an instance resolves whichever one wins the path when it arrives, so one /// still unanswered once another instance takes the path may be answered by it. unanswered: Option, - /// The number of the latest SUBSCRIBE (0) or SUBSCRIBE_UPDATE sent: a stale drop given - /// up under an earlier one is no verdict on the current terms. - update: u64, - /// The runs `tail` accounts for by a stale drop under `update`: the next update reopens - /// them, since the publisher re-offers or drops them again under it. - stale: RangeSet, /// Holds the session busy for as long as the subscription is open. _working: crate::session::Working, } @@ -12016,7 +11717,7 @@ impl TrackServe { // Open an upstream SUBSCRIBE for the first subscriber. Its terms are new, so a // stale run an earlier subscription reported is no verdict on them. Sub::None => { - producer.supersede_stale(judged(&wire.ranges)); + producer.supersede_stale(); Ok(Begin::Establish(self.prepare_establish(producer, wire, &fills.groups))) } Sub::Active(active) => { @@ -12079,7 +11780,7 @@ impl TrackServe { } else if start_moved { let _ = producer.start_at(active.start); } - buffer_update(active, edit, producer, self.subscriber.runtime.now())?; + buffer_update(active, edit)?; } Ok(Begin::None) } @@ -12354,55 +12055,11 @@ fn wire_max_delay(max_delay: Option) -> std::time::Duration max_delay.unwrap_or(std::time::Duration::from_millis(super::MAX_SAFE_DELAY_MS)) } -/// Every group `ranges` name, which a stale drop under them was judged against. A bound only -/// the publisher resolves is taken at its widest: a start from group 0, an end past the live -/// edge (an exclusive end of `u64::MAX`). -fn judged<'a>(ranges: impl IntoIterator) -> Option> { - let mut judged = RangeSet::new(); - for range in ranges { - let start = match range.start { - Some(lite::Anchor::Absolute(start)) => start.group, - _ => 0, - }; - let end = match range.end { - Some(lite::Anchor::Absolute(end)) => end.group.saturating_add(u64::from(end.frame > 0)), - _ => u64::MAX, - }; - if start < end { - judged.insert(start..end); - } - } - Some(judged) -} - /// Buffer the current SUBSCRIBE parameters as the next update, with `ranges` the change to -/// the live ranges. The caller flushes. -/// -/// A stale drop given up under an earlier update may still be in flight, and this one may -/// move the range or budget it was judged against, so the runs `serving` holds as stale -/// become unknown again: a reader fills them by range rather than trust an old verdict. -/// -/// A lite-07 publisher re-offers every group it reported stale on any update, and drops -/// again under the new number what is still stale, so the tail owes every stale run again, -/// from `now`. A group that arrived since its stale drop won over it: the publisher served -/// it, so it is neither re-offered nor owed again. -fn buffer_update( - active: &mut SubStream, - ranges: lite::RangeEdit, - serving: &track::Producer, - now: crate::time::Instant, -) -> Result<(), Error> { - active.update += 1; - let held = serving.supersede_stale(judged(active.live.iter().map(|(_, range)| range))); - let recorded = std::mem::take(&mut active.stale); - if let Ok(mut tail) = active.tail.write() { - tail.updated(); - for run in recorded.iter() { - for reopened in held.overlapping(run) { - tail.unaccount(reopened.start.max(run.start)..reopened.end.min(run.end), now); - } - } - } +/// the live ranges. The caller flushes. It reopens nothing: every drop the publisher sent, +/// a stale one included, stays final on the subscription. +fn buffer_update(active: &mut SubStream, ranges: lite::RangeEdit) -> Result<(), Error> { + active.stale_budget = active.stale_budget.min(active.max_delay); active.stream.writer.buffer(&lite::SubscribeUpdate { wanted_group: active.wanted, priority: active.priority, @@ -12410,7 +12067,6 @@ fn buffer_update( min_delay: active.min_delay, ranges, order: active.order, - update: active.update, }) } @@ -12479,7 +12135,6 @@ impl Establish { min_delay: self.subscription.delay.min, ranges: self.ranges.clone(), order: self.subscription.order, - update: 0, }; stream = stream.with_stats(self.serve.subscriber.origin.stats()); stream.writer.buffer(&lite::ControlType::Subscribe)?; @@ -12521,6 +12176,7 @@ impl Establish { stream, id: self.id, max_delay: wire_max_delay(self.subscription.delay.max), + stale_budget: wire_max_delay(self.subscription.delay.max), min_delay: self.subscription.delay.min, start: self.subscription.start(), live: lite::LiveRanges::new(self.serve.subscriber.version, &self.ranges), @@ -12539,8 +12195,6 @@ impl Establish { declared: None, end: None, wanted: None, - update: 0, - stale: RangeSet::new(), _working: self.session.work().start(), } } @@ -13889,80 +13543,46 @@ impl ServeLoop { } // The publisher will never send these groups, so they // are accounted for without a stream, and a reader of - // one still arriving ends with the drop's error now. A - // lite-07 stale drop leaves a group whose stream arrived, - // since the stream wins over it. + // one still arriving ends with the drop's error now. Every + // drop is final on the subscription, a stale one included. lite::SubscribeResponse::Drop(dropped) => { - // It can only echo an update this subscriber sent, even when it names nothing. - if dropped.update > active.update { - return Err(Error::ProtocolViolation); - } let groups = dropped.groups.clone(); if groups.is_empty() { return Ok(()); } let error = dropped.error(serve.subscriber.version); - // On lite-07 an OLD drop is a stale verdict, which the next update reopens; every - // other drop is final, whatever update it names. - let stale = serve.subscriber.version.has_skip() && error == crate::StreamError::Old; - // One given up under an update since replaced says nothing of the current terms: - // the publisher re-offers it or drops it again under the new number, so it is - // still owed, and a reader that wants it fills it by range meanwhile. - if !(stale && dropped.update < active.update) { - // Asked before this drop is accounted: what a fold forgot finishing that the - // ledger already accounted may be a stream this drop overtook. - let overtaken: Vec<_> = match stale { - true => active.tail.read().overtaken(groups.clone()).collect(), - false => Vec::new(), - }; - if let Ok(mut tail) = active.tail.write() { - tail.account(groups.clone(), serve.subscriber.runtime.now()); - } - // A paused group the drop names ends there: no continuation follows. - if let Some(entry) = serve.subscriber.subscribes.lock().get_mut(&active.id) { - entry.dropped(groups.clone(), &Error::Stream(error.clone()), stale); - } - match stale { - // Judged under the budget this subscriber sent with that update. A - // key already skipped stays skipped, and one whose group arrived - // keeps it, so no update reopens either. A group a fill asked for is - // recovered on its own, so the copy does not record it given up meanwhile. - true => { - let mut given = rangemap::RangeSet::new(); - given.insert(groups.clone()); - for asked in active.fill_groups.overlapping(&groups) { - given.remove(asked.clone()); - } - // A group whose stream finished under this update was served over - // the drop, so it won, even once the cache evicted it. - for finished in active.tail.read().finished(groups.clone()) { - given.remove(finished); - } - let mut owed = rangemap::RangeSet::new(); - for given in given.iter() { - owed.extend( - self.serving - .give_up(given.clone(), track::Hole::stale(active.max_delay)), - ); - } - // Owed again by the next update, save what a stream may have won. - for overtaken in overtaken { - owed.remove(overtaken); - } - active.stale.extend(owed); + if let Ok(mut tail) = active.tail.write() { + tail.account(groups.clone(), serve.subscriber.runtime.now()); + } + // A paused group the drop names ends there: no continuation follows. + if let Some(entry) = serve.subscriber.subscribes.lock().get_mut(&active.id) { + entry.dropped(groups.clone(), &Error::Stream(error.clone())); + } + match serve.subscriber.version.has_skip() && error == crate::StreamError::Old { + // Lite-07 judged it stale, recorded under the narrowest budget it may have been + // judged under. A reader no wider settles on it; a wider one asks for the group + // on a request of its own, since this subscription never delivers it. A key already skipped stays + // skipped, and one whose group arrived keeps it. A group a fill asked for is + // recovered on its own, so the copy does not record it given up meanwhile. + true => { + let mut given = rangemap::RangeSet::new(); + given.insert(groups.clone()); + for asked in active.fill_groups.overlapping(&groups) { + given.remove(asked.clone()); } - // Final, so no update reopens it, even where it replaces a stale drop. - false => { - active.stale.remove(groups.clone()); - self.serving.give_up(groups.clone(), track::Hole::drop(error.clone())); + for given in given.iter() { + self.serving + .give_up(given.clone(), track::Hole::stale(active.stale_budget)); } } - self.range_fills.refuse(groups, error); + false => { + self.serving.give_up(groups.clone(), track::Hole::drop(error.clone())); + } } + self.range_fills.refuse(groups, error); } - // Never produced, so nothing is waited for and no reader ends. A skip is final and - // replaces any drop of the same groups, stale or final, so no update reopens them; - // a reader a drop already ended stays ended. + // Never produced, so nothing is waited for and no reader ends. A skip replaces any + // drop of the same groups, stale or final; a reader a drop already ended stays ended. lite::SubscribeResponse::Skip(skipped) => { let groups = skipped.groups.clone(); if groups.is_empty() { @@ -13971,7 +13591,6 @@ impl ServeLoop { if let Ok(mut tail) = active.tail.write() { tail.account(groups.clone(), serve.subscriber.runtime.now()); } - active.stale.remove(groups.clone()); // A fill owing them is answered: the source never had them. self.range_fills.refuse(groups.clone(), crate::StreamError::NotFound); // A group that arrived was produced after all, so the skip contradicts it: it @@ -14250,9 +13869,7 @@ impl ServeLoop { { active.wanted = Some(wanted); let ranges = active.live.unchanged(); - if let Err(err) = - buffer_update(active, ranges, &self.serving, serve.subscriber.runtime.now()) - { + if let Err(err) = buffer_update(active, ranges) { return Poll::Ready(ServeEnd::GiveBack(err)); } continue; diff --git a/rs/moq-net/src/lite/subscriber/fills.rs b/rs/moq-net/src/lite/subscriber/fills.rs index 3b1d481e8a5..c924c3f6909 100644 --- a/rs/moq-net/src/lite/subscriber/fills.rs +++ b/rs/moq-net/src/lite/subscriber/fills.rs @@ -416,8 +416,8 @@ impl RangeFills { } self.reading.retain(|key, _| draining.contains(key)); self.draining = draining; - // A run being recovered leaves the subscription, even out of a run kept whole: any later - // update reopens its stale drop there, and the publisher would serve it on both. + // A run being recovered leaves the subscription, even out of a run kept whole: the + // subscription dropped it for good, so naming it there again only costs the publisher. for run in self.recovering.iter() { groups.remove(run.clone()); } diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index ed399c5e5ff..6e1678dbf4b 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -318,9 +318,9 @@ impl Version { ) } - /// Whether SUBSCRIBE_DROP and SUBSCRIBE_SKIP carry `Group Start` and `Group Count`. - /// Added in lite-07; earlier versions carry an inclusive `Group Start` and `Group End`. - pub(crate) fn has_group_count(self) -> bool { + /// Whether SUBSCRIBE_DROP and SUBSCRIBE_SKIP carry `Group Start` and an exclusive + /// `Group End` past it. Added in lite-07; earlier versions carry an inclusive `Group End`. + pub(crate) fn has_group_span(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -328,9 +328,8 @@ impl Version { } /// Whether holes split into SUBSCRIBE_SKIP, for keys declared never produced, and - /// SUBSCRIBE_DROP, for groups that existed, which names the `Update` in effect when it was - /// given up; SUBSCRIBE and SUBSCRIBE_UPDATE carry that `Update` number. Added in lite-07; - /// earlier versions name every hole in SUBSCRIBE_DROP. + /// SUBSCRIBE_DROP, for groups that existed. Added in lite-07; earlier versions name every + /// hole in SUBSCRIBE_DROP. pub(crate) fn has_skip(self) -> bool { !matches!( self, diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index c4eb29abb92..7a08f739590 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -1386,11 +1386,6 @@ impl Reader { } } - /// Bytes currently billed. - pub(super) fn size(&self) -> u64 { - self.bytes - } - /// The debt the track's readers owe, forgiven once the pool is back within its capacity: /// nothing needs the room any more, as the track forgives its own debt. pub(super) fn debt(&self) -> u64 { diff --git a/rs/moq-net/src/model/record.rs b/rs/moq-net/src/model/record.rs index 7b7382484e4..fe4659ae396 100644 --- a/rs/moq-net/src/model/record.rs +++ b/rs/moq-net/src/model/record.rs @@ -47,8 +47,8 @@ pub(crate) struct Record { } /// A run a reader has yet to report, and whether it was copied from the track's runs, which a -/// rescan folds in afresh: one the track forgot, such as a stale run new terms superseded, -/// leaves nothing behind. +/// rescan folds in afresh: one the track forgot, such as a stale run a new upstream +/// subscription superseded, leaves nothing behind. #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) struct Pending { pub hole: Hole, @@ -62,80 +62,42 @@ impl Pending { } } -/// How a reader reported a run, and what its wire was told. +/// How a reader reported a run, and what its wire was told. Every report is final: a drop, +/// stale (OLD) or not, settles its keys for good on the wire. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum Report { - /// Served on a Group Stream, or given up on a version whose drops are all final: nothing - /// goes out over it. + /// Served on a Group Stream, or given up on a version that has no skip: nothing goes out + /// over it. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] Settled, - /// Dropped for good: no update reopens it, though a skip still goes out over it. + /// Dropped, though a skip still goes out over it. Dropped, - /// Dropped as stale (OLD), which an update reopens. - Stale { - /// An upstream's stale run decided it, which is the upstream's to judge again then. - received: bool, - /// Its Group Stream expired as stale, or it was dropped OLD for good: its publisher - /// drops it again under each update rather than this reader reopening it. - expired: bool, - /// Its group was handed out after the drop, which the group won: no update reopens it. - taken: bool, - }, /// Skipped, which replaces a drop. Skip, } impl Report { - /// How `hole` reports, as it came from upstream when `received`. - pub fn of(hole: &Hole, received: bool) -> Self { + /// How `hole` reports. + pub fn of(hole: &Hole) -> Self { match hole { Hole::Skip => Self::Skip, - hole if hole.stale_budget().is_some() => Self::Stale { - received, - expired: false, - taken: false, - }, - _ => Self::Dropped, + Hole::Drop { .. } => Self::Dropped, } } - /// Whether this report stops `hole` going out over it: a skip goes out over a drop, and - /// a final drop over a stale one, since each replaces what it goes out over. An OLD drop - /// never goes out over a stale one, which already said OLD. + /// Whether this report stops `hole` going out over it: only a skip goes out over a drop. pub fn blocks(self, hole: &Hole) -> bool { match self { Self::Settled | Self::Skip => true, - Self::Dropped | Self::Stale { taken: true, .. } => !matches!(hole, Hole::Skip), - Self::Stale { .. } => hole.error() == crate::StreamError::Old, + Self::Dropped => !matches!(hole, Hole::Skip), } } - - /// Whether it settles its run for good, so a fold may forget it: served, skipped, dropped - /// for good, or stale with its group handed out since. - fn is_final(self) -> bool { - match self { - Self::Settled | Self::Skip | Self::Dropped => true, - Self::Stale { taken, .. } => taken, - } - } - - /// Whether an update reopens it: a stale drop nothing settled since. - pub fn reopens(self) -> bool { - matches!( - self, - Self::Stale { - expired: false, - taken: false, - .. - } - ) - } } impl Record { /// Report the first part of `range` nothing already reported blocks, as `hole` says, /// replacing what it goes out over. `None` when every part is blocked. - pub fn report(&mut self, range: Range, hole: &Hole, received: bool) -> Option> { + pub fn report(&mut self, range: Range, hole: &Hole) -> Option> { let range = range.start.max(self.floor)..range.end; if range.is_empty() { return None; @@ -147,7 +109,7 @@ impl Record { .map(|(run, _)| run.clone()) .collect(); let gap = blocked.gaps(&range).next()?; - self.reported.insert(gap.clone(), Report::of(hole, received)); + self.reported.insert(gap.clone(), Report::of(hole)); Some(gap) } @@ -162,7 +124,7 @@ impl Record { .map(|(range, pending)| (range.clone(), pending.clone())) { self.pending.remove(range.clone()); - if let Some(gap) = self.report(range.clone(), &pending.hole, pending.received) { + if let Some(gap) = self.report(range.clone(), &pending.hole) { if gap.end < range.end { self.pending.insert(gap.end..range.end, pending.clone()); } @@ -171,22 +133,6 @@ impl Record { } None } - - /// Mark a stale report on `key` settled by its group being handed out. - pub fn retire(&mut self, key: u64) { - if let Some(end) = key.checked_add(1) - && let Some(Report::Stale { received, expired, .. }) = self.reported.get(&key).copied() - { - self.reported.insert( - key..end, - Report::Stale { - received, - expired, - taken: true, - }, - ); - } - } } /// What a publisher told the wire about a reader's keys. @@ -197,16 +143,6 @@ impl Record { key < self.floor || self.reported.contains_key(&key) } - /// Whether the pool folded `key` into this record's floor, final for this reader. - pub fn folded(&self, key: u64) -> bool { - key < self.floor - } - - /// Whether `key` went out as a stale drop, which a group still replaces. - pub fn told_stale(&self, key: u64) -> bool { - matches!(self.reported.get(&key), Some(Report::Stale { .. })) - } - /// The parts of `range` the wire was told nothing of. pub fn untold(&self, range: Range) -> RangeSet { let range = range.start.max(self.floor)..range.end; @@ -216,72 +152,20 @@ impl Record { } } - /// Record that the wire was told `report` of `range`. A stale report keeps the parts an - /// upstream's stale run decided, which stay the upstream's to judge again. + /// Record that the wire was told `report` of `range`. pub fn tell(&mut self, range: Range, report: Report) { - if range.is_empty() { - return; - } - let received: Vec<_> = match report { - Report::Stale { received: false, .. } => self - .reported - .overlapping(&range) - .filter(|(_, report)| matches!(report, Report::Stale { received: true, .. })) - .map(|(run, _)| run.start.max(range.start)..run.end.min(range.end)) - .collect(), - _ => Vec::new(), - }; - self.reported.insert(range, report); - if let Report::Stale { expired, taken, .. } = report { - for run in received { - self.reported.insert( - run, - Report::Stale { - received: true, - expired, - taken, - }, - ); - } + if !range.is_empty() { + self.reported.insert(range, report); } } - /// Forget what the wire was told of `range` that an update may reopen, which is owed again. + /// Forget every report of `range`, which the wire was never told: a run given up below + /// where delivery starts, which a later widening may still serve. pub fn untell(&mut self, range: Range) { - // A final report stays: nothing reopens it, and a stale verdict must never go out over it. - let reopened: Vec<_> = self - .reported - .overlapping(&range) - .filter(|(_, report)| !report.is_final()) - .map(|(run, _)| run.start.max(range.start)..run.end.min(range.end)) - .collect(); - for run in reopened { - self.reported.remove(run); + if !range.is_empty() { + self.reported.remove(range); } } - - /// Forget the drops of `range` the wire was told, which a verdict or group replaces. - pub fn replace_drops(&mut self, range: Range) { - let drops: Vec<_> = self - .reported - .overlapping(&range) - .filter(|(_, report)| matches!(report, Report::Dropped | Report::Stale { .. })) - .map(|(run, _)| run.start.max(range.start)..run.end.min(range.end)) - .collect(); - for run in drops { - self.reported.remove(run); - } - } - - /// The runs whose Group Stream expired as stale, or that went out OLD for good, which - /// each update drops again. - pub fn expired(&self) -> RangeSet { - self.reported - .iter() - .filter(|(_, report)| matches!(report, Report::Stale { expired: true, .. })) - .map(|(run, _)| run.clone()) - .collect() - } } /// Runs a reader keeps beside its record, billed with it and settled by its fold: the @@ -356,10 +240,10 @@ impl Record { } /// Raise the floor over the final prefix: each run from it up to the lowest one that is - /// not final. Final are the groups handed out, the reports nothing reopens, and this - /// reader's own stale skips, which a wider budget would offer again only while the pool - /// still held their groups. Not final are the reports an update reopens, the runs given - /// up and not reported yet, and the keys nothing settled. + /// not final. Final are the groups handed out, every report, and this reader's own stale + /// skips, which a wider budget would offer again only while the pool still held their + /// groups. Not final are the runs given up and not reported yet, and the keys nothing + /// settled. fn fold(&mut self, handed: Option) { // The runs copied from the track's drop set go first: the next scan folds in again // whatever the track still holds. @@ -378,8 +262,7 @@ impl Record { let mut floor = self.floor; loop { let next = match self.reported.get_key_value(&floor) { - Some((run, report)) if report.is_final() => run.end, - Some(_) => break, + Some((run, _)) => run.end, None if self.pending.contains_key(&floor) => break, None => { let local = [ @@ -473,7 +356,7 @@ mod test { } /// Under a debt its track could not pay, a record folds what is final into its floor: - /// handed-out groups and reports nothing reopens, however many keys a run spans. + /// handed-out groups and reports, however many keys a run spans. /// Folded keys count as handed out and reported. #[test] fn a_debt_folds_the_final_prefix() { @@ -492,7 +375,7 @@ mod test { record.told(7) && record.delivered.contains(7), "a folded drop stays dropped" ); - assert_eq!(record.report(0..u64::MAX / 2 + 2, &Hole::Skip, false), None); + assert_eq!(record.report(0..u64::MAX / 2 + 2, &Hole::Skip), None); let mut untold = RangeSet::new(); untold.insert(u64::MAX / 2 + 2..u64::MAX / 2 + 3); assert_eq!(record.untold(0..u64::MAX / 2 + 3), untold); @@ -515,42 +398,31 @@ mod test { assert!(!record.told(3), "the handed group stays to be told"); } - /// A debt that needs a run this reader was promised ends it with `TooFarBehind`: a stale - /// report an update reopens, or a run above one. What is final below it still folds. + /// A debt that needs a run this reader was promised ends it with `TooFarBehind`: one given + /// up and not reported yet, or a run above one. What is final below it still folds. #[test] fn a_debt_on_a_promise_ends_the_reader() { - for promise in [ - Report::Stale { - received: false, - expired: false, - taken: false, - }, - Report::Stale { - received: false, - expired: true, - taken: false, - }, - ] { - let (pool, track) = account(); - let mut record = Record::default(); - record.delivered.insert(0); - record.reported.insert(1..2, Report::Dropped); - record.reported.insert(2..3, promise); - // Enough runs above it that ending the reader frees more than evicting a group. - for key in (5..1_000).step_by(2) { - record.reported.insert(key..key + 1, Report::Dropped); - } - record.settle(|| track.clone(), &mut (), None).unwrap(); - owe(&track, pool.used()); - let err = record.settle(|| track.clone(), &mut (), None).unwrap_err(); - assert_eq!(StreamError::from(&err), StreamError::TooFarBehind, "{promise:?}"); - assert_eq!(pool.used(), 0, "{promise:?}: its record went with it"); - assert!(record.failed()); - assert!( - record.settle(|| track.clone(), &mut (), None).is_err(), - "{promise:?}: it stays ended" - ); + let (pool, track) = account(); + let mut record = Record::default(); + record.delivered.insert(0); + record.reported.insert(1..2, Report::Dropped); + record + .pending + .insert(2..3, Pending::own(Hole::drop(StreamError::NotFound))); + // Enough runs above it that ending the reader frees more than evicting a group. + for key in (5..1_000).step_by(2) { + record.reported.insert(key..key + 1, Report::Dropped); } + record.settle(|| track.clone(), &mut (), None).unwrap(); + owe(&track, pool.used()); + let err = record.settle(|| track.clone(), &mut (), None).unwrap_err(); + assert_eq!(StreamError::from(&err), StreamError::TooFarBehind); + assert_eq!(pool.used(), 0, "its record went with it"); + assert!(record.failed()); + assert!( + record.settle(|| track.clone(), &mut (), None).is_err(), + "it stays ended" + ); } /// A run given up and not reported yet, or a key nothing settled, is no fold's to @@ -577,16 +449,12 @@ mod test { #[test] fn a_debt_ends_only_a_reader_holding_much() { let (pool, track) = account(); - let stale = Report::Stale { - received: false, - expired: false, - taken: false, - }; + let promise = Pending::own(Hole::drop(StreamError::NotFound)); let mut small = Record::default(); - small.reported.insert(1..2, stale); + small.pending.insert(1..2, promise.clone()); let mut large = Record::default(); for key in (1..1_000).step_by(2) { - large.reported.insert(key..key + 1, stale); + large.pending.insert(key..key + 1, promise.clone()); } small.settle(|| track.clone(), &mut (), None).unwrap(); large.settle(|| track.clone(), &mut (), None).unwrap(); @@ -613,22 +481,4 @@ mod test { bill.set(5 * RUN_OVERHEAD); assert_eq!(bill.debt(), 0, "a later pressure owes nothing of it"); } - - /// Owing a run again takes back only what an update may reopen: a final report inside it - /// stays, so no stale verdict goes out over it. - #[test] - fn untelling_a_run_keeps_its_final_reports() { - let stale = Report::Stale { - received: false, - expired: false, - taken: false, - }; - let mut record = Record::default(); - record.tell(0..2, stale); - record.tell(2..3, Report::Skip); - record.tell(3..5, stale); - record.untell(0..5); - assert!(!record.told(0) && !record.told(4), "the stale runs are owed again"); - assert!(record.told(2), "the skip stays"); - } } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 666c7a21c09..3000f9c065b 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -400,7 +400,6 @@ impl Consumer { drops: RangeMap::new(), received: RangeSet::new(), received_checked: None, - reported_stale: RangeSet::new(), declared: None, declared_error: None, }) @@ -951,20 +950,6 @@ impl Subscriber { reader.window.covered_by(from, cap, accounted) } - /// Fresh reads of the groups in `run` the serving route's copy still caches and judges - /// fresh, and the runs still given up; see [`track::Subscriber::reoffer_groups`]. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(super) fn reoffer_groups(&mut self, run: std::ops::Range) -> (Vec, RangeSet) { - self.reader().reoffer_groups(run) - } - - /// Take back every stale run this reader queued or the serving route's copy reported; - /// see [`track::Subscriber::reoffer_stale`]. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(super) fn reoffer_stale(&mut self, delivered: &Delivered) -> Vec> { - self.reader().reoffer_stale(delivered) - } - /// Poll for keys the serving copy gave up that no copy may still deliver; see /// [`track::Subscriber::poll_drop`]. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] @@ -1128,15 +1113,12 @@ struct Reader { /// [`Reader::poll_drop`]. drops: RangeMap, /// The part of [`Self::drops`] that is a received stale run the serving copy held, which - /// new terms can supersede. Kept apart so a poll costs these runs, not every queued one. + /// a new upstream subscription can supersede. Kept apart so a poll costs these runs, not every queued one. received: RangeSet, /// The serving copy's [`track::Subscriber::stale_revision`] when [`Self::received`] was /// last checked against it, so a poll rechecks those runs only after one may be gone. /// `None` until the serving copy is first checked. received_checked: Option, - /// The stale runs reported since the last [`Reader::reoffer_stale`], whichever copy gave - /// them up: an update reopens each, and the copy that reported it may no longer serve. - reported_stale: RangeSet, } impl Reader { @@ -1504,11 +1486,6 @@ impl Reader { fn hand_out(&mut self, index: usize, group: group::Consumer) -> group::Consumer { let key = group.start; self.newest = self.newest.max(Some(key)); - // The group won over any stale report on it, whichever copy made it, so no update - // reopens it. - if let Some(end) = key.checked_add(1) { - self.reported_stale.remove(key..end); - } // Another copy holding the group, now or once it lands there, is where a failure // continues it, so it stays while the group is read; see [`Copy::retains`]. Recorded // even with one copy, since a later route's copy may come to hold it. @@ -1826,51 +1803,6 @@ impl Reader { } } - /// Fresh reads of the groups in `run` the serving copy still caches and judges fresh, - /// handed out as any group of that copy is, and the runs still given up: all of `run` - /// while no copy serves. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - fn reoffer_groups(&mut self, run: std::ops::Range) -> (Vec, RangeSet) { - let Poll::Ready(Some(sub)) = self.poll_serving(&kio::Waiter::noop()) else { - let mut given_up = RangeSet::new(); - given_up.insert(run); - return (Vec::new(), given_up); - }; - let (groups, given_up) = sub.reoffer_groups(run); - // The serving copy is the newest one. - let index = self.copies.len() - 1; - let groups = groups.into_iter().map(|group| self.hand_out(index, group)).collect(); - (groups, given_up) - } - - /// Take back every stale run: those queued here, those this reader reported, and those - /// the serving copy reported, which its cursor owes again. What this reader reported - /// counts whichever copy gave it up, since a route change since leaves the serving copy - /// knowing nothing of it, though the update reopened it. Only the serving copy is - /// judged again: a replaced copy may no longer deliver, so what it gave up is the new - /// route's to deliver or give up. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - fn reoffer_stale(&mut self, delivered: &Delivered) -> Vec> { - let mut runs = std::mem::take(&mut self.reported_stale); - let queued: Vec<_> = self - .drops - .iter() - .filter(|(_, hole)| hole.stale_budget().is_some()) - .map(|(run, _)| run.clone()) - .collect(); - for run in queued { - self.remove_drop(run.clone()); - // A run delivered since it queued is owed nothing; see [`Self::poll_drop`]. - if !delivered.covers(run.clone()) { - runs.insert(run); - } - } - if let Poll::Ready(Some(sub)) = self.poll_serving(&kio::Waiter::noop()) { - runs.extend(sub.reoffer_stale()); - } - runs.into_iter().collect() - } - /// The next run the serving copy gave up that `delivered` lacks and no other copy may /// still deliver. Only the serving copy's verdicts count, and a route failure is none: /// another route may still deliver the group, and a failed group it buffered continues @@ -1888,8 +1820,8 @@ impl Reader { let ready = matches!(self.poll_serving(waiter), Poll::Ready(Some(_))); // The serving copy's subscription, borrowed apart from the received runs it checks. if let Some(Sub::Ready(sub)) = self.copies.last_mut().filter(|_| ready).map(|copy| &mut copy.sub) { - // A received stale run queued here that new terms superseded since is unknown again: - // the copy no longer holds it, and its upstream re-offers or drops it again. Checked + // A received stale run queued here that a new upstream subscription superseded since + // is unknown again: the copy no longer holds it, and that subscription may deliver it. Checked // only once the copy let a stale run go, never on every poll: each poll reports one // run, so a check per poll would cost the received runs squared to drain them. let current = sub.stale_revision(); @@ -1905,7 +1837,8 @@ impl Reader { false => sub.poll_queued_drop(waiter), }; let Poll::Ready((run, hole)) = polled else { break }; - // A stale run the copy holds came from its upstream, which new terms may supersede. + // A stale run the copy holds came from its upstream, which a new upstream + // subscription may supersede. let received = hole.stale_budget().is_some() && !sub.stale_held(run.clone()).is_empty(); given_up.push((run, hole, received)); } @@ -1974,11 +1907,6 @@ impl Reader { // Reported once. As on a plain cursor, the report is not final: a miss (a fill given // up) may still land, and is handed out if it does. self.remove_drop(open.clone()); - match &err { - err if err.stale_budget().is_some() => self.reported_stale.insert(open.clone()), - // A skip or final drop is final, so no update reopens a stale report it replaced. - track::Hole::Skip | track::Hole::Drop { .. } => self.reported_stale.remove(open.clone()), - } Poll::Ready((open, err)) } @@ -4529,9 +4457,9 @@ mod test { assert_eq!(drain(&mut sub, false), Vec::::new()); } - /// A received stale run the reader held back is unknown again once new terms supersede it - /// on the serving copy: its upstream re-offers or drops it again, so it is not reported - /// meanwhile. + /// A received stale run the reader held back is unknown again once a new upstream + /// subscription supersedes it on the serving copy, which may deliver it, so it is not + /// reported meanwhile. #[kio::test] async fn a_held_back_stale_run_new_terms_supersede_is_not_reported() { let routes = Producer::new(); @@ -4551,14 +4479,14 @@ mod test { write(&b, 3); assert_eq!(drain(&mut sub, false), [3]); - // The route's subscription updates before the old copy is past the budget. - b.supersede_stale(None); + // The route resubscribes before the old copy is past the budget. + b.supersede_stale(); kio::clock::sleep(budget).await; - assert_eq!(dropped(&mut sub), [], "no verdict under the new terms"); + assert_eq!(dropped(&mut sub), [], "no verdict under the new subscription"); } /// A run the serving copy gave up as stale itself waits like any drop while a replaced copy - /// may still deliver it, then goes out: no new terms upstream supersede it. + /// may still deliver it, then goes out: no new upstream subscription supersedes it. #[kio::test] async fn a_held_back_stale_run_judged_here_is_reported() { let routes = Producer::new(); @@ -4583,130 +4511,6 @@ mod test { assert_eq!(dropped(&mut sub), [(1..3, StreamError::Old)]); } - /// A front's reader re-offers what its serving route's copy still caches and judges fresh, - /// and gives up the rest, so a relay's publisher re-serves an expired stream through it. - #[test] - fn a_resumed_reader_reoffers_a_group_its_serving_copy_still_caches() { - let routes = Producer::new(); - let logical = logical(&routes); - let a = copy(); - routes.serve(a.consume()); - let mut sub = subscribe(&logical, HOUR); - write(&a, 0); - assert_eq!(drain(&mut sub, false), [0]); - let (groups, given_up) = sub.reoffer_groups(0..3); - assert_eq!(groups.iter().map(|group| group.start).collect::>(), [0]); - assert_eq!(given_up, std::iter::once(1..3).collect::>()); - } - - /// A front's reader takes back the stale runs its serving route's copy reported, so a - /// relay's publisher re-offers them under a new update rather than keep them reported. - #[test] - fn a_resumed_reader_takes_back_its_stale_reports() { - let routes = Producer::new(); - let logical = logical(&routes); - let a = copy(); - routes.serve(a.consume()); - let mut sub = subscribe(&logical, HOUR); - write(&a, 0); - assert_eq!(drain(&mut sub, false), [0]); - a.give_up(1..3, track::Hole::stale(HOUR)); - assert_eq!(dropped(&mut sub), [(1..3, StreamError::Old)]); - assert_eq!(sub.reoffer_stale(), vec![1..3]); - assert_eq!(sub.reoffer_stale(), Vec::>::new()); - } - - /// A stale run the logical record queued and has yet to report is taken back by an update - /// too, as a plain cursor's is: the new terms judge it anew, rather than an old verdict going - /// out under the new update number. - #[kio::test] - async fn a_resumed_reader_takes_back_its_queued_stale_runs() { - let routes = Producer::new(); - let logical = logical(&routes); - let a = copy(); - routes.serve(a.consume()); - let budget = Duration::from_secs(1); - let mut sub = subscribe(&logical, budget); - write(&a, 0); - assert_eq!(drain(&mut sub, false), [0]); - a.give_up(2..3, track::Hole::stale(budget)); - assert_eq!(dropped(&mut sub), [(2..3, StreamError::Old)]); - - // The new route's stale run around the one already reported goes out in parts once the - // old route can no longer deliver it: the part below it first, with the rest queued. - let b = copy(); - routes.serve(b.consume()); - b.give_up(1..5, track::Hole::stale(budget)); - write(&b, 5); - assert_eq!(drain(&mut sub, false), [5]); - kio::clock::sleep(budget).await; - let Poll::Ready((first, _)) = sub.poll_drop(&kio::Waiter::noop()) else { - panic!("the new route's stale run goes out"); - }; - assert_eq!(first, 1..2); - assert!(sub.record_mut().pending.contains_key(&3), "the rest waits its turn"); - - let taken: RangeSet = sub.reoffer_stale().into_iter().collect(); - assert!(taken.contains(&3) && taken.contains(&4), "{taken:?}"); - assert!( - sub.record_mut().pending.is_empty(), - "nothing queued goes out under the new terms" - ); - } - - /// A stale run one route reported is still taken back once another serves: the update - /// reopened it downstream, and the new route's copy knows nothing of it, so the groups it - /// delivers there afterwards are owed rather than kept reported. - #[test] - fn a_resumed_reader_takes_back_a_replaced_routes_stale_reports() { - let routes = Producer::new(); - let logical = logical(&routes); - let a = copy(); - routes.serve(a.consume()); - let mut sub = subscribe(&logical, HOUR); - write(&a, 0); - assert_eq!(drain(&mut sub, false), [0]); - a.give_up(1..3, track::Hole::stale(HOUR)); - assert_eq!(dropped(&mut sub), [(1..3, StreamError::Old)]); - - let b = copy(); - routes.serve(b.consume()); - assert_eq!(dropped(&mut sub), []); - assert_eq!( - sub.reoffer_stale(), - vec![1..3], - "reopened, though the new route never reported it" - ); - assert_eq!(sub.reoffer_stale(), Vec::>::new()); - write(&b, 1); - write(&b, 2); - assert_eq!(drain(&mut sub, false), [1, 2]); - } - - /// A group the new route delivers over a stale run the old route reported retires that - /// report, and a final drop that follows it replaces it: only what is still stale is taken - /// back, so an update reopens no group already served. - #[test] - fn a_resumed_reader_retires_a_stale_report_its_group_or_final_drop_replaces() { - let routes = Producer::new(); - let logical = logical(&routes); - let a = copy(); - routes.serve(a.consume()); - let mut sub = subscribe(&logical, HOUR); - write(&a, 0); - assert_eq!(drain(&mut sub, false), [0]); - a.give_up(1..4, track::Hole::stale(HOUR)); - assert_eq!(dropped(&mut sub), [(1..4, StreamError::Old)]); - a.drop_groups(2..3, StreamError::App(5)); - assert_eq!(dropped(&mut sub), [(2..3, StreamError::App(5))]); - - let b = copy(); - routes.serve(b.consume()); - write(&b, 1); - assert_eq!(drain(&mut sub, false), [1]); - assert_eq!(sub.reoffer_stale(), vec![3..4], "only group 3 is still stale"); - } - /// A run a replaced route held back is dropped with that route: the route serving next /// may still deliver it. #[test] diff --git a/rs/moq-net/src/model/skipped.rs b/rs/moq-net/src/model/skipped.rs index a339eaeb961..694a738964f 100644 --- a/rs/moq-net/src/model/skipped.rs +++ b/rs/moq-net/src/model/skipped.rs @@ -86,19 +86,6 @@ impl Skipped { widened } - /// The skipped runs within `groups`, clipped to them, lowest first; each stays until its - /// group is handed out or skipped again. - pub fn within(&self, groups: RangeInclusive) -> Vec> { - let Some(skipped) = &self.0 else { - return Vec::new(); - }; - skipped - .runs - .overlapping(&groups) - .map(|(run, _)| *run.start().max(groups.start())..=*run.end().min(groups.end())) - .collect() - } - /// Whether no run is recorded. pub fn is_empty(&self) -> bool { self.0.as_ref().is_none_or(|skipped| skipped.runs.is_empty()) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index eeda631ad97..0e805c851a2 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -19,7 +19,7 @@ use std::sync::Mutex; use super::delivered::Delivered; use super::idle; -use super::record::{Pending, Record, Report}; +use super::record::{Pending, Record}; use crate::ledger::{self, Ledger}; pub(crate) use super::subscription::Resolved; @@ -701,15 +701,8 @@ pub(crate) struct TrackState { // One past the last `append_group`: every key below it arrived, was given up, or // was skipped. appended: Option, - // Every group the ranges of a received copy's current upstream terms name, which its - // stale runs were judged against; `None` when unknown, which counts as every group. - judged: Option>, - // Bumped on every insert into `drops`, and when `judged` changes, so a cursor rescans - // it only after a change. + // Bumped on every insert into `drops`, so a cursor rescans it only after a change. drops_revision: u64, - // Bumped when `judged` changes, which settles received stale runs differently, so a - // wire cursor scans the whole drop set again. - judged_revision: u64, // Bumped whenever a stale run leaves `drops` or another verdict replaces it, so a front's // reader rechecks the received stale runs it queued only after one may be gone. stale_revision: u64, @@ -4155,29 +4148,6 @@ pub struct Producer { alive: Arc, } -/// Bytes a session keeps for a track beside its cache, billed to the track's account as a -/// reader's record is, so the pool can hand it debt, and released on drop. -pub(crate) struct Bill(cache::Reader); - -#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] -impl Bill { - /// Bill `bytes` in all. - pub(crate) fn set(&mut self, bytes: u64) { - self.0.set(bytes); - } - - /// The debt the track left its readers, which this bill pays by shrinking. - pub(crate) fn debt(&self) -> u64 { - self.0.debt() - } -} - -impl std::fmt::Debug for Bill { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_tuple("Bill").field(&self.0.size()).finish() - } -} - impl Producer { /// The immutable publisher priority committed when this track was accepted. #[cfg(test)] @@ -4612,35 +4582,18 @@ impl Producer { cached } - /// Forget every run held as stale: the terms a received copy's upstream judged them - /// under were replaced, so they are unknown again, and a reader that wants one fills it. - /// `judged` is every group the new terms' ranges name, `None` when unknown. Returns the - /// runs forgotten; a group that arrived since its stale drop replaced it, so it is not - /// among them. + /// Forget every run held as stale: a new upstream subscription judges them afresh, and + /// may deliver them, so they are unknown again, and a reader that wants one fills it. + /// Returns the runs forgotten; a group that arrived since its stale drop replaced it, so + /// it is not among them. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn supersede_stale(&self, judged: Option>) -> RangeSet { + pub(crate) fn supersede_stale(&self) -> RangeSet { let Ok(mut state) = self.modify() else { return RangeSet::new(); }; - if state.judged != judged { - state.judged = judged; - state.drops_revision += 1; - state.judged_revision += 1; - } state.supersede_stale() } - /// Whether a stale drop under the current terms gave up `key`, which a group arriving - /// for it replaces and an update supersedes. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn holds_stale(&self, key: u64) -> bool { - self.state - .read() - .drops - .get(&key) - .is_some_and(|hole| hole.stale_budget().is_some()) - } - /// Record `groups` given up as `hole` describes, returning the runs recorded: a drop /// leaves a skipped key skipped, and a group a copy still serves whole, since a group /// stream wins over its drop: a stale drop leaves it still arriving or not, and a final one @@ -5172,13 +5125,6 @@ impl Producer { self.prev_subscription = seen; } - /// Open a bill against this track's account, for what a session keeps for it beside the - /// cache, such as its tail's record of finished streams. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn bill(&self) -> Bill { - Bill(self.state.read().cache.reader()) - } - /// How long a subscriber session's tail waits for a late group: `budget`, bounded by how /// long the publisher keeps one. The aggregate asked upstream is not bounded by it. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] @@ -7206,13 +7152,13 @@ struct Drift { type Coverage = Option<(Layered, Option)>; /// Whether a reader judging under `budget` with `coverage` is settled by `hole` over a run -/// from `start`, on a track whose upstream judged stale runs against ranges naming the groups -/// in `judged` (`None` for every group). Any hole but a received stale one settles every -/// reader. A stale verdict holds for a reader no wider than the budget it was judged under -/// that reads every group the upstream's ranges name above the run's start: its own successor -/// and edge are then no older than those the verdict was judged against, since a group's -/// verdict looks only above it. Any other reader treats the run as unknown, and fills it. -fn settles(budget: Duration, coverage: &Coverage, start: u64, hole: &Hole, judged: Option<&RangeSet>) -> bool { +/// from `start`. Any hole but a received stale one settles every reader. A stale verdict +/// holds for a reader no wider than the budget it was judged under that reads every group +/// above the run's start: its own successor and edge are then no older than those the +/// verdict was judged against, whatever ranges the upstream judged it under, since a group's +/// verdict looks only above it. Any other reader treats the run as unknown, and fills it on +/// a request of its own: the upstream subscription never delivers a group it dropped. +fn settles(budget: Duration, coverage: &Coverage, start: u64, hole: &Hole) -> bool { let Some(stale) = hole.stale_budget() else { return true; }; @@ -7234,19 +7180,13 @@ fn settles(budget: Duration, coverage: &Coverage, start: u64, hole: &Hole, judge false => *held.end() >= run.end - 1, }) }; - let covers = match judged { - Some(judged) => judged - .overlapping(&(above..u64::MAX)) - .all(|run| reads(run.start.max(above)..run.end)), - None => reads(above..u64::MAX), - }; - budget <= stale && covers + budget <= stale && reads(above..u64::MAX) } impl Drift { - /// Whether `hole`, over a run from `start`, settles this reader on `state`; see [`settles`]. - fn settles(&self, state: &TrackState, start: u64, hole: &Hole) -> bool { - settles(self.budget, &self.coverage, start, hole, state.judged.as_ref()) + /// Whether `hole`, over a run from `start`, settles this reader; see [`settles`]. + fn settles(&self, start: u64, hole: &Hole) -> bool { + settles(self.budget, &self.coverage, start, hole) } } @@ -8015,10 +7955,10 @@ struct Within<'a> { drift: Option<&'a Drift>, } -/// The [`TrackState::judged_revision`], span, window revision, and the budget and coverage -/// that settle received stale runs (see [`Drift::settles`]) a [`DropCursor`] last scanned -/// the whole span under; between them it folds in only the runs that changed. -type Scan = (u64, ops::Range, u64, Option<(Duration, Coverage)>); +/// The span, window revision, and the budget and coverage that settle received stale runs +/// (see [`Drift::settles`]) a [`DropCursor`] last scanned the whole span under; between them +/// it folds in only the runs that changed. +type Scan = (ops::Range, u64, Option<(Duration, Coverage)>); /// What a wire publisher's cursor gave up, found as it changes rather than by rescanning /// the cache on every poll. @@ -8050,45 +7990,6 @@ impl DropCursor { } } - /// Take back every stale run, reported or not: an update reopens their verdict, so they - /// are judged again, and reported again under the new update if still stale. Also returns - /// the part an upstream's received stale run decided. - fn take_stale(&mut self, record: &mut Record) -> (Vec>, RangeSet) { - let mut stale = RangeSet::new(); - let mut received = RangeSet::new(); - let queued: Vec<_> = record - .pending - .iter() - .filter(|(_, pending)| pending.hole.stale_budget().is_some()) - .map(|(run, pending)| (run.clone(), pending.received)) - .collect(); - for (run, from_upstream) in queued { - record.pending.remove(run.clone()); - if from_upstream { - received.insert(run.clone()); - } - stale.insert(run); - } - let reported: Vec<_> = record - .reported - .iter() - .filter_map(|(run, report)| match report { - Report::Stale { received, .. } if report.reopens() => Some((run.clone(), *received)), - _ => None, - }) - .collect(); - for (run, from_upstream) in reported { - record.reported.remove(run.clone()); - if from_upstream { - received.insert(run.clone()); - } - stale.insert(run); - } - // A received stale run is folded in again by the next scan, if the track still holds it. - self.scanned = None; - (stale.into_iter().collect(), received) - } - /// Record a run this cursor's fills gave up on as a miss, as `hole` says; a reason /// already pending, such as the track's own drop, is kept. fn give_up(record: &mut Record, run: ops::Range, hole: Hole) { @@ -8134,7 +8035,7 @@ impl DropCursor { if let Some(drift) = within.drift { self.drift = Some((drift.budget, drift.coverage.clone())); } - let scan = (state.judged_revision, span.clone(), within.revision, self.drift.clone()); + let scan = (span.clone(), within.revision, self.drift.clone()); let full = std::mem::take(&mut record.rescan) || self.scanned.as_ref() != Some(&scan); let changed: Vec> = match full { false => state.drops_changes.since(self.seen).collect(), @@ -8171,7 +8072,7 @@ impl DropCursor { let run = dropped.start.max(changed.start)..dropped.end.min(changed.end); // A received stale run that does not settle this reader is unknown to it. let settled = match &self.drift { - Some((budget, coverage)) => settles(*budget, coverage, run.start, hole, state.judged.as_ref()), + Some((budget, coverage)) => settles(*budget, coverage, run.start, hole), None => hole.stale_budget().is_none(), }; if settled { @@ -8221,7 +8122,7 @@ impl DropCursor { if clipped.end < range.end { record.pending.insert(clipped.end..range.end, pending.clone()); } - if let Some(gap) = record.report(clipped, &pending.hole, pending.received) { + if let Some(gap) = record.report(clipped, &pending.hole) { if gap.end < range.end { record.pending.insert(gap.end..range.end, pending.clone()); } @@ -8466,30 +8367,31 @@ impl Cursor { let coverage = self.coverage(); let state = self.state.read(); let budget = clamp_max_delay(self.subscription.read().budget(), state.max_age_bound()); - let accounted = - |gap: ops::Range| { - let mut left = RangeSet::new(); - left.insert(gap.clone()); - for run in self.record.written_off.overlapping(&gap) { - left.remove(run.clone()); - } - if let Some(given_up) = given_up { - for run in given_up.overlapping(&gap) { - left.remove(run.clone()); - } - } - // A received stale run that does not settle this reader is unknown to it, so it - // still wants those groups. - for (run, _) in state.drops.overlapping(&gap).filter(|(run, hole)| { - settles(budget, &coverage, run.start.max(gap.start), hole, state.judged.as_ref()) - }) { + let accounted = |gap: ops::Range| { + let mut left = RangeSet::new(); + left.insert(gap.clone()); + for run in self.record.written_off.overlapping(&gap) { + left.remove(run.clone()); + } + if let Some(given_up) = given_up { + for run in given_up.overlapping(&gap) { left.remove(run.clone()); } - for key in self.seek_pending.range(gap).map(|(key, _)| *key) { - left.remove(key..key + 1); - } - left.is_empty() - }; + } + // A received stale run that does not settle this reader is unknown to it, so it + // still wants those groups. + for (run, _) in state + .drops + .overlapping(&gap) + .filter(|(run, hole)| settles(budget, &coverage, run.start.max(gap.start), hole)) + { + left.remove(run.clone()); + } + for key in self.seek_pending.range(gap).map(|(key, _)| *key) { + left.remove(key..key + 1); + } + left.is_empty() + }; self.filter .window .runs(self.filter.window.floor().unwrap_or(0).max(from)) @@ -8681,50 +8583,6 @@ impl Cursor { } } - /// Owe again every run this cursor gave up as stale, reported or not: an update reopens - /// the verdict. A group still cached is owed as a widened skip is, a missing one is - /// missed again. Returns the runs taken back; whatever is still stale under the new - /// terms is given up and reported again. - fn reoffer_stale(&mut self) -> Vec> { - let Some(drops) = &mut self.drops else { - return Vec::new(); - }; - let (runs, received) = drops.take_stale(&mut self.record); - // What neither a skip nor a miss offers again: a group written off at the track's max - // age bound, which no budget reverses. It is still stale under the new terms. What an - // upstream's stale run decided is the upstream's to judge again: the next scan folds - // it in again if the track still holds it, and it stays owed if new terms superseded it. - let mut kept = RangeSet::new(); - for run in &runs { - kept.insert(run.clone()); - for decided in received.overlapping(run) { - kept.remove(decided.clone()); - } - if let Some(misses) = &mut self.misses { - for missed in misses.given_up().overlapping(run) { - kept.remove(missed.clone()); - } - misses.retry(run.clone()); - } - if let Some(last) = run.end.checked_sub(1) { - for skipped in self.record.skipped.within(run.start..=last) { - kept.remove(*skipped.start()..skipped.end().saturating_add(1)); - self.reowe(skipped); - } - } - } - let budget = { - let state = self.state.read(); - clamp_max_delay(self.subscription.read().budget(), state.max_age_bound()) - }; - if self.drops.is_some() { - for run in kept.iter() { - DropCursor::give_up(&mut self.record, run.clone(), Hole::stale(budget)); - } - } - runs - } - /// Owe `run` of skipped groups again, judged anew, withdrawing a stale drop of it not /// reported yet; a reported one stands. fn reowe(&mut self, run: ops::RangeInclusive) { @@ -8872,10 +8730,6 @@ impl Cursor { } self.prune_skipped(); self.record.delivered.insert(key); - // The group won over any stale report on it. - if self.drops.is_some() { - self.record.retire(key); - } let mut delivered = std::mem::take(&mut self.record.delivered); self.forget_past_budget(&mut delivered); self.record.delivered = delivered; @@ -9994,8 +9848,6 @@ impl Subscriber { } delivered.insert(key); resume.forget_past_budget(delivered); - // The group won over any stale report its publisher made on it. - logical.record.retire(key); } } } @@ -10459,34 +10311,6 @@ impl Subscriber { self } - /// Re-offer what this reader gave up as stale through [`Self::poll_drop`], as a wire - /// whose every update reopens its stale drops does: each run is judged again under the - /// new terms. Returns the runs taken back, which are owed again. A front's reader takes - /// back what it queued and what its serving route's copy reported. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn reoffer_stale(&mut self) -> Vec> { - match &mut self.inner { - Inner::Plain(cursor) => cursor.reoffer_stale(), - Inner::Resume(resume, logical) => { - let mut runs: RangeSet = resume.reoffer_stale(&logical.record.delivered).into_iter().collect(); - // A stale run the logical record queued and has yet to report is owed again too, as - // a plain cursor takes back its own: the new terms judge it anew. - let queued: Vec<_> = logical - .record - .pending - .iter() - .filter(|(_, pending)| pending.hole.stale_budget().is_some()) - .map(|(run, _)| run.clone()) - .collect(); - for run in queued { - logical.record.pending.remove(run.clone()); - runs.insert(run); - } - runs.into_iter().collect() - } - } - } - pub(crate) fn set_range(&mut self, groups: impl RangeBounds) { let (start, end) = super::subscription::key_bounds(groups); match &mut self.inner { @@ -10604,44 +10428,8 @@ impl Subscriber { } } - /// Fresh reads of the groups in `run` this subscriber's track still caches, its range - /// still admits, and its current budget no longer judges stale, each expiring against - /// that budget, and the runs still given up: no longer cached, or still stale. For a wire - /// whose update re-offers a group whose stream it gave up as stale. A front's reader asks - /// its serving route's copy. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn reoffer_groups(&mut self, run: ops::Range) -> (Vec, RangeSet) { - let cursor = match &mut self.inner { - Inner::Plain(cursor) => cursor, - Inner::Resume(resume, _) => return resume.reoffer_groups(run), - }; - let mut given_up = RangeSet::new(); - given_up.insert(run.clone()); - let budget = cursor.subscription.read().budget(); - let fresh: Vec<_> = { - let state = cursor.state.read(); - let budget = clamp_max_delay(budget, state.max_age_bound()); - let edge = state.drift_edge(&cursor.servable); - state - .lookup - .range(run) - .filter(|&(&key, slot)| slot.serves_end() && cursor.admits(key) && !state.is_stale(key, &edge, budget)) - .map(|(&key, slot)| (key, slot.serving().consume())) - .collect() - }; - let mut groups = Vec::new(); - for (key, group) in fresh { - if let Some(end) = key.checked_add(1) { - given_up.remove(key..end); - group.cache_refresh(); - groups.push(cursor.deliver(group)); - } - } - (groups, given_up) - } - /// The parts of `run` this subscriber's track still holds as a received stale run: one - /// new terms superseded is gone (see [`Producer::supersede_stale`]). + /// a new upstream subscription superseded is gone (see [`Producer::supersede_stale`]). #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub(crate) fn stale_held(&self, run: ops::Range) -> RangeSet { match &self.inner { @@ -10668,17 +10456,6 @@ impl Subscriber { } } - /// The budget this subscriber judges staleness under: its max delay, clamped to the - /// track's max age bound. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn budget(&self) -> Duration { - let budget = self.subscription().budget(); - match &self.inner { - Inner::Plain(cursor) => clamp_max_delay(budget, cursor.state.read().max_age_bound()), - Inner::Resume(..) => budget, - } - } - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub(crate) fn latest_key(&self) -> Option { match &self.inner { @@ -25078,44 +24855,11 @@ mod test { assert_eq!((fill.start().group, fill.end()), (0, 3)); } - /// A fill's OLD answer under the budget it was asked with is a stale verdict on its reader, - /// which each update reopens: a new fill is asked every time, never given up. Mirrors JS. - #[test] - #[cfg(feature = "async")] - #[expect(clippy::single_range_in_vec_init, reason = "the reopened runs are a list, here one")] - fn a_fills_old_answer_is_asked_again_after_each_update() { - let mut producer = track_producer("test", Info::timed()); - let dynamic = producer.requests(); - producer.start_at(3).unwrap(); - write_group(&producer, 3); - let terms = |secs| { - Subscription::default() - .with_delay(Delay::default().with_max(Duration::from_secs(secs))) - .with_ranges([Range::groups(0..)]) - }; - let mut subscriber = producer.subscribe(terms(60)); - let waiter = kio::Waiter::noop(); - assert_eq!(drain_groups(&mut subscriber), [3]); - for secs in [60, 120, 240] { - assert!(subscriber.poll_drop(&waiter).is_pending()); - let Poll::Ready(Ok(fill)) = dynamic.poll_requested_fill(&waiter) else { - panic!("a fill is asked under {secs}s"); - }; - assert_eq!((fill.start().group, fill.end()), (0, 3)); - fill.reject_groups(0..3, Error::Old); - let stale = Hole::stale(Duration::from_secs(secs)); - assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((0..3, stale))); - subscriber.update(terms(secs * 2)).unwrap(); - assert_eq!(subscriber.reoffer_stale(), [0..3]); - } - assert!(subscriber.poll_drop(&waiter).is_pending()); - assert!(matches!(dynamic.poll_requested_fill(&waiter), Poll::Ready(Ok(_)))); - } - /// A fill's OLD answer under the publisher's max age binds every reader, so the track holds /// it as a stale verdict under that age rather than a loss for good: the readers waiting now - /// are refused, a later reader no wider is settled without asking, and once the verdict is forgotten, as new terms or the - /// drop set's expiry window forget one, a reader asks again. Mirrors JS. + /// are refused, a later reader no wider is settled without asking, and once the verdict is + /// forgotten, as a new upstream subscription or the drop set's expiry window forgets one, a + /// reader asks again. Mirrors JS. #[test] #[cfg(feature = "async")] #[expect(clippy::single_range_in_vec_init, reason = "the forgotten runs are a set, here one")] @@ -25164,7 +24908,7 @@ mod test { "the verdict is not asked again" ); - assert_eq!(producer.supersede_stale(None), RangeSet::from_iter([0..3])); + assert_eq!(producer.supersede_stale(), RangeSet::from_iter([0..3])); let mut again = producer.subscribe(terms()); assert_eq!(drain_groups(&mut again), [3]); assert!( @@ -25173,92 +24917,45 @@ mod test { ); } - /// Every group a set of ranges names, as a received copy's upstream terms judge them. - #[cfg(feature = "async")] - fn judged(runs: impl IntoIterator) -> Option> { - Some(runs.into_iter().map(|(start, end)| start..end).collect()) - } - - /// A stale verdict settles a reader that reads every range the upstream judged it - /// against, however many there are, with no fill asked. Group 3 is received, so the - /// later range's time start names it. Mirrors JS. - #[test] - #[cfg(feature = "async")] - fn a_stale_verdict_settles_a_reader_of_every_range_it_judged() { - let producer = track_producer("test", Info::timed()); - producer.received(); - let dynamic = producer.requests(); - let budget = Duration::from_millis(500); - // The upstream judged 0..2 and 4..6 under 500ms, and gave up both of them as stale. - producer.supersede_stale(judged([(0, 2), (4, 6)])); - producer.give_up(0..2, Hole::stale(budget)); - producer.give_up(4..6, Hole::stale(budget)); - producer.create_group(3u64.into()).unwrap().close().unwrap(); - let mut subscriber = producer.subscribe( - Subscription::default() - .with_delay(Delay::default().with_max(budget)) - .with_ranges([Range::groups(0..2), Range::groups(4..6)]), - ); - let waiter = kio::Waiter::noop(); - assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((0..2, Hole::stale(budget)))); - assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((4..6, Hole::stale(budget)))); - assert!(matches!( - subscriber.poll_recv_group(&waiter), - Poll::Ready(Ok(Some(group))) if group.start == 3 - )); - assert!( - matches!(subscriber.poll_recv_group(&waiter), Poll::Ready(Ok(None))), - "nothing else is owed" - ); - assert!(dynamic.poll_requested_fill(&waiter).is_pending(), "nothing is asked"); - } - - /// A reader whose ranges only partly overlap the ones a stale verdict was judged against - /// is settled where it reads every judged group above the run, and asks a fill for the - /// rest, even with only group 3 received: no update brings it, since its ranges add - /// nothing to the upstream's terms. Mirrors JS. + /// A received stale run settles only a reader no wider than the budget it was judged under + /// that reads every group above it: a bounded reader or a wider one asks a fill for the run + /// instead, since the subscription that dropped it never delivers it. Group 3 is received, + /// so the readers have a newest group to judge against. Mirrors JS. #[test] #[cfg(feature = "async")] - fn a_stale_verdict_settles_a_partly_overlapping_reader_only_where_it_reads_above() { + fn a_received_stale_run_settles_only_a_reader_of_everything_above_it() { let producer = track_producer("test", Info::timed()); producer.received(); let dynamic = producer.requests(); let budget = Duration::from_millis(500); - producer.supersede_stale(judged([(0, 2), (4, 6)])); producer.give_up(0..2, Hole::stale(budget)); - producer.give_up(4..6, Hole::stale(budget)); - // Held, so a time start at 4 names it. producer.create_group(3u64.into()).unwrap().close().unwrap(); - let reader = |ranges: [Range; 2]| { + let reader = |max: Duration, range: Range| { producer.subscribe( Subscription::default() - .with_delay(Delay::default().with_max(budget)) - .with_ranges(ranges), + .with_delay(Delay::default().with_max(max)) + .with_ranges([range]), ) }; let waiter = kio::Waiter::noop(); - // Reads every judged group above each run, and more past them: settled. Its start at - // time 1 reaches back to the oldest group, since none held contains it. - let mut wider = reader([Range::groups(1..2), Range::groups(4..8)]); - assert_eq!(wider.poll_drop(&waiter), Poll::Ready((0..2, Hole::stale(budget)))); - assert_eq!(wider.poll_drop(&waiter), Poll::Ready((4..6, Hole::stale(budget)))); - assert!(wider.poll_drop(&waiter).is_pending()); + let mut open = reader(budget, Range::groups(0..)); + assert_eq!(open.poll_drop(&waiter), Poll::Ready((0..2, Hole::stale(budget)))); + assert_eq!(drain_groups(&mut open), [3]); assert!(dynamic.poll_requested_fill(&waiter).is_pending(), "nothing is asked"); - // Stops at 4, which the upstream judged against 5: its own newest, which no verdict - // convicts. Both runs are unknown to it, and asked for. - let mut narrower = reader([Range::groups(0..2), Range::groups(4..5)]); - assert!(matches!( - narrower.poll_recv_group(&waiter), - Poll::Ready(Ok(Some(group))) if group.start == 3 - )); - assert!(narrower.poll_recv_group(&waiter).is_pending()); - assert!(narrower.poll_drop(&waiter).is_pending()); + + let mut bounded = reader(budget, Range::groups(0..2)); + assert!( + bounded.poll_recv_group(&waiter).is_pending(), + "it still wants the groups" + ); + let mut wider = reader(Duration::from_secs(5), Range::groups(0..)); + assert_eq!(drain_groups(&mut wider), [3]); + assert!(wider.poll_drop(&waiter).is_pending(), "it still wants the groups"); let mut asked = Vec::new(); while let Poll::Ready(Ok(fill)) = dynamic.poll_requested_fill(&waiter) { asked.push((fill.start().group, fill.end())); } - asked.sort(); - assert_eq!(asked, [(0, 2), (4, 5)]); + assert_eq!(asked, [(0, 2)], "one fill, which both join"); } /// A fill taken before the last handler closed still answers an unsettled stale run: a @@ -25271,10 +24968,10 @@ mod test { producer.received(); let dynamic = producer.requests(); let budget = Duration::from_millis(500); - producer.supersede_stale(judged([(0, 2), (4, 6)])); producer.give_up(0..2, Hole::stale(budget)); producer.give_up(4..6, Hole::stale(budget)); - // Stops at 2, though the upstream judged 0..2 against 4..6 too: the run is unknown to it. + // Stops at 2, though the upstream judged 0..2 against what is above it: the run is + // unknown to it. let reader = || { producer.subscribe( Subscription::default() @@ -25604,62 +25301,10 @@ mod test { ); } - /// A subscription's tail, recording a fragmented run of finished streams between updates, - /// bills it to its track's account. Under the pool's debt it forgets them, which leaves a - /// stale drop under the update to stand as the publisher judged it, and stays within the - /// pool. - #[cfg(feature = "async")] - #[kio::test] - async fn a_tail_forgets_its_finished_streams_under_debt() { - const RUNS: u64 = 4000; - let (producer, pool) = pooled_producer(1 << 30); - producer.received(); - let tail = kio::Producer::new(crate::tail::Tail::default()); - if let Ok(mut state) = tail.write() { - state.bill(producer.bill()); - } - let now = crate::time::sim().now(); - let finish = |key: u64| crate::tail::Reading::open(&tail, Some(key), now).finish(); - for run in 0..RUNS { - finish(2 * run); - } - assert_eq!(tail.read().finished(0..2 * RUNS).count() as u64, RUNS); - assert!(pool.used() >= RUNS * 16, "the finished streams are billed"); - - // The pool shrinks, and groups written above them accrue the track's debt, which its own - // groups cannot pay: the tail pays it by forgetting what finished. - let capacity = 64 * (RUN_OVERHEAD + BORN_OVERHEAD); - pool.resize(capacity); - let mut producer = producer; - for _ in 0..64 { - finished_group(&mut producer, 16 * 1024); - } - finish(2 * RUNS); - assert!( - tail.read().finished(0..2 * RUNS + 1).count() <= 1, - "forgotten under debt" - ); - assert!(pool.used() <= capacity, "within the pool: {}", pool.used()); - // A stale drop inside what the fold forgot is owed again only where the ledger had not - // accounted for it: there a stream may have finished and overtaken the drop. - let overtaken: Vec<_> = tail.read().overtaken(0..4).collect(); - assert_eq!(overtaken, vec![0..1, 2..3], "the gap between them is still owed"); - assert_eq!( - tail.read().overtaken(2 * RUNS..2 * RUNS + 1).count(), - 0, - "the newest run stays" - ); - if let Ok(mut state) = tail.write() { - state.updated(); - } - assert_eq!(tail.read().overtaken(0..4).count(), 0, "each update starts over"); - } - /// A flood a reader reported, fragmented into runs alternating with upstream skips, /// bills its record too. Once the pool shrinks under it and its track has shed what it - /// can, the reader folds the final runs and the groups it read into its floor and stays - /// within the pool, while one holding stale reports an update would reopen ends with - /// `TooFarBehind` rather than forgo the re-offer. + /// can, the reader folds the runs, stale or not, and the groups it read into its floor and + /// stays within the pool: every report is final. #[test] fn a_reported_flood_folds_or_ends_the_reader() { const RUNS: u64 = 1000; @@ -25720,17 +25365,12 @@ mod test { } } } - match stale { - true => assert!( - matches!(read, Some(Poll::Ready(Err(Error::Lagged)))), - "the stale reports could not fold" - ), - false => { - assert!(read.is_none(), "the reader runs on"); - while let Poll::Ready((run, _)) = subscriber.poll_drop(&waiter) { - assert!(!reported.overlaps(&run), "{run:?}, folded, was reported again"); - } - } + assert!(read.is_none(), "stale={stale}: the reader runs on"); + while let Poll::Ready((run, _)) = subscriber.poll_drop(&waiter) { + assert!( + !reported.overlaps(&run), + "stale={stale}: {run:?}, folded, was reported again" + ); } assert!( pool.used() <= capacity + 2 * (16 * 1024 + cache::ENTRY_OVERHEAD), @@ -25894,7 +25534,7 @@ mod test { } /// `skip_groups` leaves a cached group alone, and replaces every drop, final or stale: the - /// skip is final, so new terms never supersede it. + /// skip is final, so a new upstream subscription never supersedes it. #[test] #[cfg(feature = "async")] fn skipping_replaces_every_drop_but_leaves_a_cached_group() { @@ -25903,7 +25543,7 @@ mod test { producer.give_up(3..4, Hole::drop(StreamError::Cancel)); producer.give_up(4..5, Hole::stale(Duration::from_secs(1))); producer.skip_groups(0..5); - producer.supersede_stale(None); + producer.supersede_stale(); let drops: Vec<_> = producer .state .read() @@ -25977,8 +25617,8 @@ mod test { assert_eq!(drain_groups(&mut subscriber), [2, 5, 3]); } - /// A received stale run superseded by new range terms is unknown again, and a group a - /// widening re-offers wins over its drop. + /// A received stale run a new upstream subscription supersedes is unknown again, and a group + /// that subscription delivers wins over its drop. #[test] #[cfg(feature = "async")] fn superseded_stale_runs_are_unknown_again() { @@ -25991,10 +25631,10 @@ mod test { ); let waiter = kio::Waiter::noop(); producer.give_up(1..2, Hole::stale(budget)); - producer.supersede_stale(None); + producer.supersede_stale(); assert!( subscriber.poll_drop(&waiter).is_pending(), - "no verdict under the new terms" + "no verdict under the new subscription" ); assert!(producer.state.read().drops.is_empty()); write_group(&producer, 1); @@ -26021,81 +25661,10 @@ mod test { ); producer.give_up(3..7, Hole::stale(budget)); assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((3..4, Hole::stale(budget)))); - producer.supersede_stale(None); + producer.supersede_stale(); assert!(subscriber.poll_drop(&waiter).is_pending(), "5 and 6 are unknown again"); } - /// A received stale run a reader reported and the relay's own update then superseded is - /// unknown again: the reader's update owes it until the upstream serves or drops it again, - /// rather than dropping it again as if the reader had judged it stale itself. - #[test] - #[cfg(feature = "async")] - #[expect(clippy::single_range_in_vec_init, reason = "the reopened runs are a list, here one")] - fn a_superseded_received_stale_report_stays_owed_after_an_update() { - let producer = track_producer("test", Info::timed()); - let budget = Duration::from_millis(500); - let mut subscriber = producer.subscribe( - Subscription::default() - .with_delay(Delay::default().with_max(budget)) - .with_ranges([Range::groups(0..)]), - ); - let waiter = kio::Waiter::noop(); - producer.give_up(1..3, Hole::stale(budget)); - assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((1..3, Hole::stale(budget)))); - producer.supersede_stale(None); - assert_eq!(subscriber.reoffer_stale(), [1..3]); - assert!( - subscriber.poll_drop(&waiter).is_pending(), - "no verdict under the new terms" - ); - // The upstream drops it again under the new terms: reported again. - producer.give_up(1..3, Hole::stale(budget)); - assert_eq!(subscriber.poll_drop(&waiter), Poll::Ready((1..3, Hole::stale(budget)))); - } - - /// A bounded reader is settled by a received stale run only when it reads every group the - /// upstream's ranges name above the run; otherwise it still wants the groups the run names. - #[test] - #[cfg(feature = "async")] - fn a_received_stale_run_settles_a_bounded_reader_only_through_the_judged_ranges() { - let producer = track_producer("test", Info::timed()); - producer.received(); - // As its serving session does, so an unsettled run is asked rather than given up. - let _dynamic = producer.requests(); - let bounded = |max: Duration| { - producer.subscribe( - Subscription::default() - .with_delay(Delay::default().with_max(max)) - .with_ranges([Range::groups(0..2)]), - ) - }; - let mut wider = bounded(Duration::from_secs(5)); - let mut matching = bounded(Duration::from_millis(500)); - let waiter = kio::Waiter::noop(); - // The upstream judged its own range of 0..2 under 500ms. - producer.supersede_stale(judged([(0, 2)])); - producer.give_up(0..2, Hole::stale(Duration::from_millis(500))); - assert!( - wider.poll_recv_group(&waiter).is_pending(), - "a wider budget still wants the groups" - ); - assert_eq!( - matching.poll_drop(&waiter), - Poll::Ready((0..2, Hole::stale(Duration::from_millis(500)))) - ); - assert!( - matches!(matching.poll_recv_group(&waiter), Poll::Ready(Ok(None))), - "nothing is owed" - ); - // Judged against an open range, a capped reader may see an older edge. - producer.supersede_stale(None); - producer.give_up(0..2, Hole::stale(Duration::from_millis(500))); - let mut capped = bounded(Duration::from_millis(500)); - assert!(capped.poll_drop(&waiter).is_pending()); - write_group(&producer, 0); - assert_eq!(drain_groups(&mut wider), [0]); - } - /// A report describes a miss, not a delivery: a late group is still handed out once. #[test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/model/track/miss.rs b/rs/moq-net/src/model/track/miss.rs index 12d9d559188..8e2ea316bef 100644 --- a/rs/moq-net/src/model/track/miss.rs +++ b/rs/moq-net/src/model/track/miss.rs @@ -94,9 +94,9 @@ pub(super) struct Misses { /// The last key of the highest received stale run above the newest group that this /// reader cannot trust, as of [`Self::unknown_at`]; see [`Self::unknown`]. unknown: Option, - /// The drops revision, judged revision, budget, and coverage [`Self::unknown`] was found - /// under: while the terms hold, only the runs changed since are looked at. - unknown_at: Option<(u64, u64, Duration, super::Coverage)>, + /// The drops revision, budget, and coverage [`Self::unknown`] was found under: while the + /// terms hold, only the runs changed since are looked at. + unknown_at: Option<(u64, Duration, super::Coverage)>, /// The [`Forgotten`] revision this reader judged again up to. forgotten: u64, } @@ -603,7 +603,7 @@ impl Misses { } Err((Error::Old, asked)) if looser(max_delay, asked) => retry.insert(groups), // Stale under the budget it was asked with, which this reader's is no wider - // than: a stale verdict an update reopens, never a refusal spent for good. + // than: a stale verdict a wider budget asks again, never a refusal spent for good. Err((Error::Old, Some(asked))) => self.give_up_stale(groups, asked, given_up), // A drop the track recorded is named by the drop cursor already. Err(_) => self.settle(&state, groups, given_up), @@ -640,14 +640,12 @@ impl Misses { /// changed since are looked at, so a drop costs each reader the runs it touches. fn unknown(&mut self, state: &TrackState, drift: &Drift) -> Option { let above = |run: &ops::Range| state.newest_produced.is_none_or(|newest| run.end - 1 > newest); - let unsettled = |run: &ops::Range, hole| above(run) && !drift.settles(state, run.start, hole); + let unsettled = |run: &ops::Range, hole| above(run) && !drift.settles(run.start, hole); let revision = state.drops_changes.revision(); let since = self .unknown_at .as_ref() - .filter(|(_, judged, budget, coverage)| { - *judged == state.judged_revision && *budget == drift.budget && *coverage == drift.coverage - }) + .filter(|(_, budget, coverage)| *budget == drift.budget && *coverage == drift.coverage) .map(|(seen, ..)| *seen) // The newest group only rises, so the run found stays the highest unless it fell // below it or changed. @@ -676,10 +674,10 @@ impl Misses { .iter() .rev() .take_while(|(run, _)| above(run)) - .find(|(run, hole)| !drift.settles(state, run.start, hole)) + .find(|(run, hole)| !drift.settles(run.start, hole)) .map(|(run, _)| run.end - 1), }; - self.unknown_at = Some((revision, state.judged_revision, drift.budget, drift.coverage.clone())); + self.unknown_at = Some((revision, drift.budget, drift.coverage.clone())); self.unknown } @@ -715,8 +713,8 @@ impl Misses { return asks; } // A received stale run this reader cannot trust is still asked for, though nothing above - // it arrived: only an update brings it back otherwise, and a reader narrower than the - // upstream's terms changes none. See `TrackState::unfed`. Only runs above the newest + // it arrived: the subscription that dropped it never delivers it, and a reader narrower + // than the upstream's budget changes none. See `TrackState::unfed`. Only runs above the newest // group need a look. let unknown = self.unknown(state, drift); let Some(newest) = state.newest_produced.max(bound).max(unknown) else { @@ -1341,7 +1339,7 @@ impl Misses { left.insert(hole.clone()); // Only what overlaps the hole, so judging every run costs each one the same. for (run, gone) in state.drops.overlapping(&hole) { - if drift.settles(state, run.start.max(hole.start), gone) { + if drift.settles(run.start.max(hole.start), gone) { left.remove(run.clone()); } } @@ -1376,15 +1374,6 @@ impl Misses { } } - /// Judge `groups` again: an update reopened the stale verdict they were given up with. - /// They are no longer judged, and the next probe judges its whole span afresh, so it - /// asks a fill for them or gives them up again. - pub(super) fn retry(&mut self, groups: ops::Range) { - self.given_up.remove(groups.clone()); - self.judged.remove(groups); - self.at = None; - } - pub(super) fn give_up(&mut self, groups: ops::Range, given_up: &mut GivenUp) { self.give_up_judged(groups, None, given_up); } @@ -1536,7 +1525,7 @@ impl TrackState { folds => awaited.push((groups, folds)), }; // The upstream accounted for a received stale run, so the feed brings none of it unless - // an update supersedes the run. + // a new upstream subscription supersedes the run. let mut fed = RangeSet::new(); fed.insert(hole.clone()); for (run, given) in self.drops.overlapping(&hole) { @@ -2046,31 +2035,6 @@ mod tests { "judged stale under the reader's budget" ); assert!(misses.deferred.runs.is_empty()); - - // An update reopens the verdict: retried, the gap is judged afresh, and a wider budget - // asks a fill for it. - misses.retry(3..4); - let wider = Drift { - budget: Duration::from_secs(3600), - bounded: false, - edge: state.drift_edge(&Servable::ALL), - coverage: None, - }; - given_up.clear(); - let asks = misses.judge( - &state, - (0, 0, None), - None, - None, - None, - |span| [span].into_iter().collect(), - &Delivered::default(), - &wider, - &mut given_up, - &waiter, - ); - assert!(asks.contains(&3), "a retried gap is asked again"); - assert!(given_up.is_empty()); } /// A grace change with nothing deferred has no deadline to move, so an unchanged probe diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index 51ff2736a26..c012fefa815 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -12,8 +12,6 @@ use std::{ops::Range, task::Poll, time::Duration}; -use rangemap::RangeSet; - pub(crate) use crate::ledger::{GRACE, grace}; use crate::{ ledger::Ledger, @@ -30,26 +28,8 @@ pub(crate) struct Tail { // The publisher's FIN ended the track, its only end before lite-05, so a session that // dies before the tail settles declares that end before aborting. ended: bool, - // Groups whose stream finished since the last update was sent. A lite-07 stale drop under - // that update names one only if it was sent before the publisher served the group, so the - // group won over it, even once the cache evicted it. - finished: RangeSet, - // The span of the finished runs a fold under the pool's debt forgot since the last update. - // A stale drop there for a group the ledger already accounted may be one its stream - // overtook, so the next update owes none of it again. - folded: Option>, - // How many updates were sent, so a stale drop can tell whether a later one superseded it. - updates: u64, - // What `finished` bills to the track's account, [`FINISHED_OVERHEAD`] per run, once the - // subscription has a copy to bill. - bill: Option, } -/// Heap `finished` keeps per run, doubled for half-full `BTreeMap` nodes as the cache's own -/// overheads are. Billed, so a publisher fragmenting the streams it finishes between updates -/// costs what the cache would hold. -const FINISHED_OVERHEAD: u64 = 2 * size_of::>() as u64; - impl Default for Tail { fn default() -> Self { Self::new(GRACE) @@ -64,56 +44,9 @@ impl Tail { streams: 0, active: 0, ended: false, - finished: RangeSet::new(), - folded: None, - updates: 0, - bill: None, } } - /// Bill what this tail keeps to `bill`, the subscription's copy's account. - pub fn bill(&mut self, bill: crate::model::track::Bill) { - self.bill = Some(bill); - self.rebill(); - } - - /// Bill what `finished` keeps, and under the pool's debt [`Self::fold`] it. - fn rebill(&mut self) { - let Some(bill) = &mut self.bill else { - return; - }; - let runs = self.finished.len() + usize::from(self.folded.is_some()); - bill.set(runs as u64 * FINISHED_OVERHEAD); - if bill.debt() > 0 - && self.fold() - && let Some(bill) = &mut self.bill - { - bill.set(2 * FINISHED_OVERHEAD); - } - } - - /// Fold all but the newest finished run into `folded`, returning whether any was: a stale - /// drop under this update then stands as the publisher judged it, but the update owes none - /// of what it names that [`Self::overtaken`] reports. The newest run stays, so streams - /// finishing in key grow nothing to charge again. - pub fn fold(&mut self) -> bool { - let (Some(first), Some(older), Some(newest)) = ( - self.finished.iter().next().cloned(), - self.finished.iter().nth_back(1).cloned(), - self.finished.iter().next_back().cloned(), - ) else { - return false; - }; - let span = match self.folded.take() { - Some(folded) => folded.start.min(first.start)..folded.end.max(older.end), - None => first.start..older.end, - }; - self.folded = Some(span); - self.finished = RangeSet::new(); - self.finished.insert(newest); - true - } - /// Record that the publisher's FIN ended the track. pub fn end(&mut self) { self.ended = true; @@ -138,12 +71,6 @@ impl Tail { self.expire(now); } - /// Owe `groups` again from `now`: a stale drop that accounted for them was reversed by a - /// widening, so the publisher serves or drops them anew. - pub fn unaccount(&mut self, groups: Range, now: Instant) { - self.ledger.unaccount(groups, now); - } - /// Restart the age of every gap reaching into `groups`, which the demand newly asks for. pub fn demand(&mut self, groups: Range, now: Instant) { self.ledger.demand(groups, now); @@ -170,37 +97,6 @@ impl Tail { self.ledger.folds_at(group, self.ledger.grace()) } - /// The runs of `groups` whose stream finished since the last update was sent. - pub fn finished(&self, groups: Range) -> impl Iterator> + '_ { - self.finished.overlapping(groups).cloned() - } - - /// The runs of `groups` inside the span a fold forgot that the ledger accounts for, asked - /// before a stale drop of `groups` is accounted: the header of each arrived, or the grace gave - /// up on it, before the drop, so the drop may be one a finished stream overtook. - pub fn overtaken(&self, groups: Range) -> impl Iterator> + '_ { - let span = self - .folded - .as_ref() - .map(|folded| groups.start.max(folded.start)..groups.end.min(folded.end)) - .filter(|span| !span.is_empty()); - span.into_iter().flat_map(|span| self.ledger.accounted(span)) - } - - /// Forget which streams finished, for an update being sent: a stale drop under an earlier - /// one is no verdict, so none needs them. - pub fn updated(&mut self) { - self.updates += 1; - self.finished = RangeSet::new(); - self.folded = None; - self.rebill(); - } - - /// How many updates were sent, each superseding the stale drops before it. - pub fn updates(&self) -> u64 { - self.updates - } - /// Whether a data stream whose header arrived is still being read. pub fn is_reading(&self) -> bool { self.active > 0 @@ -220,7 +116,6 @@ impl Tail { /// A data stream whose header arrived, holding its subscription's end open until dropped. pub(crate) struct Reading { tail: Option>, - group: Option, active: bool, } @@ -230,7 +125,6 @@ impl Reading { let Ok(mut state) = tail.write() else { return Self { tail: None, - group, active: false, }; }; @@ -241,21 +135,10 @@ impl Reading { } Self { tail: Some(tail.clone()), - group, active: true, } } - /// Record that the stream's group arrived whole, once it finished. - pub fn finish(&self) { - if let (Some(tail), Some(group)) = (&self.tail, self.group) - && let Ok(mut state) = tail.write() - { - state.finished.insert(group..group.saturating_add(1)); - state.rebill(); - } - } - /// Stop holding the end open while the stream waits on another one, which holds it /// open itself if its header arrived. pub fn park(&mut self) { diff --git a/rs/moq-net/tests/integration/drop_record.rs b/rs/moq-net/tests/integration/drop_record.rs index a1b86b05e50..130cb6ed660 100644 --- a/rs/moq-net/tests/integration/drop_record.rs +++ b/rs/moq-net/tests/integration/drop_record.rs @@ -305,8 +305,9 @@ async fn drain(subscriber: &mut track::Subscriber) -> BTreeSet { const LITE06: &str = "moq-lite-06"; /// Through a lite-06 hop, a group the publisher reported dropped stays dropped for every -/// reader, whatever budget it widens to, with no session error. Lite-07 end to end, the same -/// stale report is reopened by the widening update instead. A shrink sends no drops: what an +/// reader, whatever budget it widens to, with no session error. Lite-07 end to end, the stale +/// report stays final on its subscription, but the widened reader still gets the group, which +/// a request of the relay's own fetches from the publisher. A shrink sends no drops: what an /// update narrows away is still there for a later reader. #[kio::test] async fn a_lite06_hop_keeps_a_reported_group_dropped() { @@ -316,10 +317,10 @@ async fn a_lite06_hop_keeps_a_reported_group_dropped() { } /// [`a_lite06_hop_keeps_a_reported_group_dropped`] with the lite-06 hop upstream of a lite-07 -/// one: a lite-06 drop is final for the relay's subscription, which no update re-offers, but -/// it was judged under that subscription's budget. The relay forwards it as a stale one, the -/// viewer's widening update reopens it, and the group is fetched from the publisher, which -/// still holds it, as the relay drills' FETCH recovery requires. +/// one: a lite-06 drop is final for the relay's subscription, but it was judged under that +/// subscription's budget. The relay forwards it as a stale one, the widened viewer still wants +/// it, and the group is fetched from the publisher, which still holds it, as the relay drills' +/// FETCH recovery requires. #[kio::test] async fn a_lite06_upstream_drop_is_fetched_for_a_widened_lite07_viewer() { reported_drop_through([LITE06, LITE07]).await; @@ -345,8 +346,8 @@ async fn reported_drop_through(versions: [&str; 2]) { write(&chain.source, 7, 7000); assert_eq!(received(&mut first).await, BTreeSet::new(), "{name}"); - // A lite-07 viewer hop leaves the stale report open to a widening update, which fills - // the group from upstream; over a lite-06 viewer hop the drop is final. + // Over a lite-07 viewer hop the widened reader still wants the stale group, which a + // request of its own fills from upstream; over a lite-06 viewer hop the drop is final. let want: BTreeSet = match versions[1] == LITE06 { true => (0..GROUPS).filter(|key| *key != 7).collect(), false => (0..GROUPS).collect(), @@ -470,59 +471,6 @@ async fn an_origin_eviction_drop_is_forwarded_final() { } } -/// After a widening from max delay B1 to B2 for a group the publisher no longer holds, its -/// stale drop under B1, still in flight when the relay sends the B2 update, settles no reader; -/// the drop the publisher sends again under the B2 update settles the B2 reader, over lite-07. -#[kio::test] -async fn a_drop_under_a_superseded_budget_settles_no_reader() { - // Reaches groups 5 and up by media time. - const B1: Duration = Duration::from_millis(3500); - // Reaches every group, by media time and by the wall clock this test spends. - const B2: Duration = Duration::from_secs(60); - // The publisher reclaims an unread group well within one trip to the relay and back. - const EXPIRY: Duration = Duration::from_secs(2); - // One way between the publisher and the relay. - const LATENCY: Duration = Duration::from_secs(10); - kio::clock::timeout(TIMEOUT * 10, async { - let chain = Chain::new([LITE07, LITE07], [expiring(EXPIRY), forever(), forever()]).await; - for key in (0..GROUPS).filter(|key| *key != 7) { - write(&chain.source, key, key * 1000); - } - let mut reader = chain.subscribe(reading(B1, [Range::oldest()])).await; - assert_eq!(received(&mut reader).await, [5, 6, 8, 9].into()); - - // Group 7 lands once its successor is older than B1 by the wall clock: the publisher - // drops it as stale under B1 at once, and reclaims it soon after, unread. - kio::clock::sleep(B1 + Duration::from_secs(1)).await; - chain.upstream.client_transport.set_latency(LATENCY); - let sent = kio::clock::now(); - write(&chain.source, 7, 7000); - let _finished = chain.source.clone().finish().unwrap(); - - // The B2 update leaves the relay while the B1 drop is halfway there. - kio::clock::sleep(LATENCY / 2).await; - // Any request the relay opens upstream from now on never arrives, so only the - // subscription can settle group 7. - chain.upstream.client_transport.hold_bidis(); - reader.update(reading(B2, [Range::oldest()])).unwrap(); - let ended = kio::clock::timeout(LATENCY * 10, reader.recv_group()) - .await - .expect("the reader never settled group 7") - .unwrap() - .map(|group| group.start); - assert_eq!(ended, None, "group 7 was reclaimed"); - // The B1 drop reached the relay at one latency, the B2 update the publisher at one and - // a half, and its drop the relay at two and a half. - let elapsed = kio::clock::now() - sent; - assert!( - elapsed >= LATENCY * 5 / 2 && elapsed < LATENCY * 5 / 2 + Duration::from_secs(1), - "settled after {elapsed:?}" - ); - }) - .await - .expect("timed out"); -} - /// A run dropped before the track's first group is settled through a relay for a later /// reader whose range covers it: the reader gets the group after it and ends, as one reading the /// relay's own cache does. @@ -543,12 +491,11 @@ async fn a_run_dropped_before_the_first_group_settles_a_later_range() { assert_eq!(drain(&mut relayed).await, [2].into(), "on the relay"); } -/// Under pool pressure on the relay, a reader whose record holds only delivered runs and -/// budget-independent drops folds them into its floor and reads on, while one holding lite-07 -/// stale reports within reach of the max age bound ends rather than forgo the re-offer: with -/// `Lagged` on the relay itself, and `TooFarBehind` over the wire. +/// Under pool pressure on the relay, a reader folds the runs its record holds into its floor +/// and reads on, whether they are drops no budget changes or lite-07 stale reports: every +/// report is final. #[kio::test] -async fn relay_pool_pressure_folds_final_runs_and_ends_stale_reports() { +async fn relay_pool_pressure_folds_every_reported_run() { /// The relay's readers each record this many disjoint dropped runs. const RUNS: u64 = 200; /// The groups that land on the relay at once once its pool shrinks. @@ -593,23 +540,14 @@ async fn relay_pool_pressure_folds_final_runs_and_ends_stale_reports() { } } } - match stale { - false => { - assert!(ended.iter().all(Option::is_none), "the final runs fold: {ended:?}"); - // Under this much pressure the relay may evict a burst group before serving it, - // so only the local reader's count is exact. - assert_eq!(read[0], BURST, "the local reader reads on"); - assert!(read[1] > 0, "the remote reader reads on"); - } - true => { - let [local, remote] = ended; - assert!(matches!(local, Some(moq_net::Error::Lagged)), "local: {local:?}"); - assert!( - matches!(remote, Some(moq_net::Error::Stream(moq_net::StreamError::TooFarBehind))), - "remote: {remote:?}" - ); - } - } + assert!( + ended.iter().all(Option::is_none), + "stale={stale}: the runs fold: {ended:?}" + ); + // Under this much pressure the relay may evict a burst group before serving it, so + // only the local reader's count is exact. + assert_eq!(read[0], BURST, "stale={stale}: the local reader reads on"); + assert!(read[1] > 0, "stale={stale}: the remote reader reads on"); chain.assert_open(&format!("stale={stale}")); }) .await diff --git a/rs/moq-net/verify/subscribe/Continuation.cfg b/rs/moq-net/verify/subscribe/Continuation.cfg index 7897ec10f2f..f8ddf22d5d6 100644 --- a/rs/moq-net/verify/subscribe/Continuation.cfg +++ b/rs/moq-net/verify/subscribe/Continuation.cfg @@ -1,9 +1,7 @@ \* A group of one frame, paused up to twice, without pressure: where each continuation -\* starts against the frames the subscriber holds, and every rule but StreamWins, whose -\* finding StreamWins.cfg tracks. +\* starts against the frames the subscriber holds, and every other rule. CONSTANTS Groups = {0} - MaxUpdates = 2 MaxStreams = 4 MaxPauses = 2 Frames = 1 @@ -12,8 +10,8 @@ CONSTANTS SPECIFICATION Spec INVARIANTS - NoViolation ServedOnce + NamedOnce QuietIsSettled PausedIsOwed OneReader diff --git a/rs/moq-net/verify/subscribe/StreamWins.cfg b/rs/moq-net/verify/subscribe/StreamWins.cfg deleted file mode 100644 index 48c76e3b7b6..00000000000 --- a/rs/moq-net/verify/subscribe/StreamWins.cfg +++ /dev/null @@ -1,17 +0,0 @@ -\* Open finding: a group read whole is recorded stale. Once it is fixed, drop -\* this line. -\* Without pressure: under the pool's debt the tail forgets a finished stream by -\* design, so a stale drop it overtook still records the group stale, though the -\* next update owes it nothing again, since the ledger accounted it first. -CONSTANTS - Groups = {0} - MaxUpdates = 4 - MaxStreams = 4 - MaxPauses = 0 - Frames = 0 - Pressure = FALSE - -SPECIFICATION Spec - -INVARIANTS - StreamWins diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg index 4dfd8a3c5dc..a2f0b4f66b7 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg @@ -1,22 +1,20 @@ -\* One group, four SUBSCRIBE_UPDATEs, four Group Streams, and one YIELDED reset. -\* Groups share only the order of the Subscribe Stream, so one group holds every race -\* the model has, and a second multiplies the states without adding one. -\* StreamWins lives in StreamWins.cfg, without pressure, while its finding is open. -\* Pressure lets the pool fold what each side keeps at any point. Frames are left out: +\* Two groups, six Group Streams, and two YIELDED resets per group. With no update to +\* reopen a drop, a group gets a second stream only as a continuation, so the bounds stay +\* cheap; the second group puts both groups' drops and skips on one Subscribe Stream. +\* Pressure lets the publisher's record fold at any point. Frames are left out: \* Continuation.cfg checks where a continuation starts. CONSTANTS - Groups = {0} - MaxUpdates = 4 - MaxStreams = 4 - MaxPauses = 1 + Groups = {0, 1} + MaxStreams = 6 + MaxPauses = 2 Frames = 0 Pressure = TRUE SPECIFICATION Spec INVARIANTS - NoViolation ServedOnce + NamedOnce QuietIsSettled PausedIsOwed OneReader diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla index 29791f7929b..00ac8880cf0 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla @@ -6,28 +6,27 @@ (* `Tail` (rs/moq-net/src/tail.rs) and its copy of the track. *) (* *) (* The draft's promise: for every sequence in range the publisher sends a *) -(* Group Stream or names it in SUBSCRIBE_SKIP or SUBSCRIBE_DROP. A drop of *) -(* OLD is a stale verdict under the update it names, which the next *) -(* SUBSCRIBE_UPDATE reopens; a Group Stream wins over a stale drop, even *) -(* one it overtook. Drops and skips travel in order on the Subscribe *) -(* Stream; each Group Stream travels on its own, unordered against them, *) -(* and a reset can lose its header. *) +(* Group Stream or names it in SUBSCRIBE_SKIP or SUBSCRIBE_DROP. Every *) +(* drop is final on its subscription, a stale (OLD) one included: a *) +(* SUBSCRIBE_UPDATE reopens nothing, so updates are left out. A skip still *) +(* goes out over a drop of a group never served. Drops and skips travel in *) +(* order on the Subscribe Stream; each Group Stream travels on its own, *) +(* unordered against them, and a reset can lose its header. *) (* *) (* A publisher out of stream credit may reset a Group Stream with YIELDED, *) (* which pauses the group instead of accounting for it: the subscriber *) (* keeps the frames it read, and the publisher later continues the group *) (* on a new Group Stream from the reset stream's own Frame Start, or names *) (* it in a drop. A continuation may overtake the YIELDED reset and waits, *) -(* unread, for it. *) +(* unread, for it. It is the only second Group Stream of a group. *) (* *) (* Each step is one poll of the code that handles one event. The track *) (* cursor's verdicts (hand a group out, give it up stale or final, skip *) -(* it) and whether the cache still holds a fresh copy on an update are *) -(* free choices, standing in for the cache, the clock, and the routes. *) -(* So are when the publisher yields a stream, and whether it continues a *) -(* paused group or gives it up, standing in for stream credit and expiry. *) -(* Under `Pressure`, so is when the pool's debt folds what each side keeps *) -(* of the group: the publisher's record and the subscriber's tail. *) +(* it) are free choices, standing in for the cache, the clock, and the *) +(* routes. So are when the publisher yields a stream, and whether it *) +(* continues a paused group or gives it up, standing in for stream credit *) +(* and expiry. Under `Pressure`, so is when the pool's debt folds the *) +(* publisher's record of the group. *) (* *) (* Scope: the subscription is already answered (SUBSCRIBE_OK) and covers *) (* every group; ranges, starts, fills, and the tail's grace are left out. *) @@ -37,11 +36,10 @@ EXTENDS Integers, Sequences, FiniteSets CONSTANTS Groups, \* group sequences in range - MaxUpdates, \* SUBSCRIBE_UPDATEs the subscriber sends MaxStreams, \* Group Streams the publisher opens MaxPauses, \* YIELDED resets the publisher sends per group Frames, \* frames in each group: 0 leaves frames out - Pressure \* the cache pool may hand the readers debt, so each side folds + Pressure \* the cache pool may hand the publisher's reader debt, so its record folds \* A Group Stream: the publisher's side (`GroupState`), and the subscriber's. \* pub: "open" (serving), "fin" (FIN sent, awaiting its acknowledgement), @@ -55,8 +53,8 @@ NewStream(g, of, start) == [g |-> g, pub |-> "open", err |-> "", wasFin |-> FALSE, sub |-> "none", of |-> of, start |-> start, wrote |-> 0, read |-> 0] -DropMsg(g, err, u) == [type |-> "drop", g |-> g, err |-> err, u |-> u] -SkipMsg(g) == [type |-> "skip", g |-> g, err |-> "", u |-> 0] +DropMsg(g, err) == [type |-> "drop", g |-> g, err |-> err] +SkipMsg(g) == [type |-> "skip", g |-> g, err |-> ""] Max(a, b) == IF a > b THEN a ELSE b @@ -64,72 +62,53 @@ VARIABLES \* The publisher's track cursor: its verdict on each group. cur, \* "pending", "handed", "stale", "final", or "skip" late, \* the cursor handed the group out once more - \* The publisher's `TrackRun`. - pup, \* `update`: the number in effect - served, \* `served`: sequences served or given up - dropped, \* `dropped`: named in a drop, never served - dstale, \* `dropped_stale`: the part of `dropped` named stale - expired, \* `expired`: groups whose stream expired as stale - redrop, \* `redrop`: expired runs an update owes a drop again - reoffered, \* `reoffered`: expired groups an update serves again + \* The publisher's `TrackRun` and its reader's record. + served, \* `Record::told`: sequences served or given up + dropped, \* the part of `served` named in a drop, never served (`Report::Dropped`) outq, \* `GroupOutcomes::dropped`: failed streams not yet named - folded, \* the record folded the group into its floor (`Record::folded`) + folded, \* the record folded the group into its floor paused, \* the YIELDED stream a paused group waits to continue, or 0 pauses, \* YIELDED resets sent for the group + ndrop, \* history: drops naming the group + nskip, \* history: skips naming the group \* The wire. streams, \* every Group Stream opened, in order resp, \* the Subscribe Stream, publisher to subscriber - ctrl, \* the Subscribe Stream, subscriber to publisher: update numbers - \* The subscriber's `SubStream`, `Tail`, and copy. - sup, \* `SubStream::update`: the latest number sent + \* The subscriber's `Tail` and copy. acct, \* the tail's ledger: groups accounted for reading, \* the part of `acct` only the stream filling the copy accounts for - finished, \* `Tail::finished`: groups whose stream finished since the last update - forgot, \* `Tail::folded`: the span a fold forgot since the last update - sstale, \* `SubStream::stale`: runs accounted by a stale drop under `sup` - sdrop, \* groups a stale drop under `sup` named, recorded or not + sdrop, \* groups a drop named (`TrackEntry::dropped`) rec, \* the copy's record: "none", "stale", "final", or "skip" cached, \* the copy's group: "none", "open", "paused", "whole", "aborted", "evicted" have, \* the index after the last frame the copy holds of the group got, \* history: the subscriber read the group to its FIN - malformed, \* a continuation started past the frames the copy holds - violation \* the subscriber closed the session with a PROTOCOL_VIOLATION + malformed \* a continuation started past the frames the copy holds -pubVars == <> -subVars == <> -vars == <> +names == <> +pubVars == <> +subVars == <> +vars == <> Init == /\ cur = [g \in Groups |-> "pending"] /\ late = [g \in Groups |-> FALSE] - /\ pup = 0 - /\ served = {} /\ dropped = {} /\ dstale = {} /\ expired = {} - /\ redrop = {} /\ reoffered = {} /\ outq = <<>> /\ folded = {} + /\ served = {} /\ dropped = {} /\ outq = <<>> /\ folded = {} /\ paused = [g \in Groups |-> 0] /\ pauses = [g \in Groups |-> 0] - /\ streams = <<>> /\ resp = <<>> /\ ctrl = <<>> - /\ sup = 0 - /\ acct = {} /\ reading = {} /\ finished = {} /\ forgot = {} /\ sstale = {} /\ sdrop = {} + /\ ndrop = [g \in Groups |-> 0] + /\ nskip = [g \in Groups |-> 0] + /\ streams = <<>> /\ resp = <<>> + /\ acct = {} /\ reading = {} /\ sdrop = {} /\ rec = [g \in Groups |-> "none"] /\ cached = [g \in Groups |-> "none"] /\ have = [g \in Groups |-> 0] /\ got = {} /\ malformed = FALSE - /\ violation = FALSE ----------------------------------------------------------------------------- (* Publisher *) ----------------------------------------------------------------------------- -\* `replace_stale`: a verdict or group replaces a drop of g. -ReplaceStale(g) == - /\ dropped' = dropped \ {g} - /\ dstale' = dstale \ {g} - /\ expired' = expired \ {g} - /\ redrop' = redrop \ {g} - \* `serve`: open a Group Stream for g, which `mark_served` records. Serve(g) == /\ Len(streams) < MaxStreams @@ -138,68 +117,53 @@ Serve(g) == \* `poll_track` takes `Recv::Group`: the cursor hands g out. Once more, it may hand out a \* group it gave up: one a route the front switched to delivers after a stale verdict, or -\* one re-created after its drop. It never hands out a sequence twice. A group handed out -\* after its stale drop is served over it; any other sequence already accounted for is not. -\* `poll_step` names failed streams and drops again first, and a re-offered group takes -\* the next stream ahead of the cursor's. +\* one re-created after its drop. It never hands out a sequence twice. A sequence already +\* served or given up is not served (`Record::told`). `poll_step` names failed streams first. CursorHand(g) == - /\ outq = <<>> /\ redrop = {} /\ reoffered = {} + /\ outq = <<>> /\ g \notin folded /\ \/ cur[g] = "pending" /\ UNCHANGED late \/ cur[g] \in {"stale", "final"} /\ ~late[g] /\ late' = [late EXCEPT ![g] = TRUE] /\ cur' = [cur EXCEPT ![g] = "handed"] - /\ IF g \in dstale - THEN /\ ReplaceStale(g) - /\ Serve(g) - ELSE IF g \in served - THEN UNCHANGED <> - ELSE /\ Serve(g) - /\ UNCHANGED <> - /\ UNCHANGED <> + /\ IF g \in served + THEN UNCHANGED <> + ELSE Serve(g) + /\ UNCHANGED <> \* `poll_forward_drop`: the cursor gives g up stale ("old"), final ("evicted"), or -\* declares it skipped, after `poll_step` named failed streams and dropped again. A later -\* verdict may replace an earlier one. `forward_range` replaces what the verdict -\* overrides, then `drop_range` names g only if it is not yet served or given up. +\* declares it skipped, after `poll_step` named failed streams. A later verdict may follow +\* an earlier one. `forward_range` sends it only where the record has told nothing, or, for +\* a skip, only a drop (`Report::blocks`). CursorGiveUp(g, kind) == - /\ outq = <<>> /\ redrop = {} + /\ outq = <<>> /\ \/ cur[g] = "pending" \/ cur[g] = "stale" /\ kind \in {"evicted", "skip"} \/ cur[g] = "final" /\ kind = "skip" /\ cur' = [cur EXCEPT ![g] = IF kind = "old" THEN "stale" ELSE IF kind = "skip" THEN "skip" ELSE "final"] - /\ LET replaces == CASE kind = "skip" -> dropped - [] kind = "old" -> {} - [] OTHER -> dstale - hit == g \in replaces - s1 == IF hit THEN served \ {g} ELSE served - d1 == IF hit THEN dropped \ {g} ELSE dropped - ds1 == IF hit THEN dstale \ {g} ELSE dstale - named == g \notin s1 - IN /\ served' = s1 \cup {g} - /\ dropped' = IF ~named THEN d1 - ELSE IF kind = "skip" THEN d1 \ {g} ELSE d1 \cup {g} - /\ dstale' = IF ~named THEN ds1 - ELSE IF kind = "old" THEN ds1 \cup {g} ELSE ds1 \ {g} - /\ expired' = IF hit THEN expired \ {g} ELSE expired - /\ redrop' = IF hit THEN redrop \ {g} ELSE redrop + /\ LET named == g \notin served \/ (kind = "skip" /\ g \in dropped) + IN /\ served' = served \cup {g} + /\ dropped' = IF ~named THEN dropped + ELSE IF kind = "skip" THEN dropped \ {g} ELSE dropped \cup {g} /\ resp' = IF ~named THEN resp ELSE IF kind = "skip" THEN Append(resp, SkipMsg(g)) - ELSE Append(resp, DropMsg(g, kind, pup)) - /\ UNCHANGED <> + ELSE Append(resp, DropMsg(g, kind)) + /\ ndrop' = IF named /\ kind # "skip" THEN [ndrop EXCEPT ![g] = @ + 1] ELSE ndrop + /\ nskip' = IF named /\ kind = "skip" THEN [nskip EXCEPT ![g] = @ + 1] ELSE nskip + /\ UNCHANGED <> \* A serving stream writes its next frame. StreamWriteAt(i) == /\ streams[i].pub = "open" /\ streams[i].start + streams[i].wrote < Frames /\ streams' = [streams EXCEPT ![i].wrote = @ + 1] - /\ UNCHANGED <> + /\ UNCHANGED <> \* A serving stream writes its last frame and FINs (`GroupState::Closed`). StreamFinAt(i) == /\ streams[i].pub = "open" /\ streams[i].start + streams[i].wrote = Frames /\ streams' = [streams EXCEPT ![i].pub = "fin"] - /\ UNCHANGED <> + /\ UNCHANGED <> \* A stream fails and resets: it expires stale while serving or while its FIN awaits \* the acknowledgement, or is evicted while serving. `settle_failed` queues the outcome. @@ -209,8 +173,7 @@ StreamFailAt(i, err) == /\ streams' = [streams EXCEPT ![i].pub = "reset", ![i].err = err, ![i].wasFin = (streams[i].pub = "fin")] /\ outq' = Append(outq, <>) - /\ UNCHANGED <> + /\ UNCHANGED <> \* Out of stream credit, the publisher resets a serving stream with YIELDED. The group is \* paused, not given up: nothing names it, and the publisher owes a continuation or a drop. @@ -220,8 +183,7 @@ StreamYieldAt(i) == /\ streams' = [streams EXCEPT ![i].pub = "reset", ![i].err = "yielded"] /\ paused' = [paused EXCEPT ![streams[i].g] = i] /\ pauses' = [pauses EXCEPT ![streams[i].g] = @ + 1] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The publisher continues a paused group on a new Group Stream, from the YIELDED \* stream's own Frame Start: a reset can discard frames the transport acknowledged. @@ -231,8 +193,7 @@ PubContinue(g) == /\ LET k == paused[g] IN streams' = Append(streams, NewStream(g, k, streams[k].start)) /\ paused' = [paused EXCEPT ![g] = 0] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The publisher gives a paused group up instead, as it would the stream it yielded: \* it expires stale under the delivery budget, or is evicted. @@ -240,96 +201,35 @@ PausedGiveUp(g, err) == /\ paused[g] # 0 /\ paused' = [paused EXCEPT ![g] = 0] /\ outq' = Append(outq, <>) - /\ UNCHANGED <> + /\ UNCHANGED <> \* The peer acknowledged everything up to the FIN. StreamAckAt(i) == /\ streams[i].pub = "fin" /\ streams[i].sub \in {"fin", "dup"} /\ streams' = [streams EXCEPT ![i].pub = "acked"] - /\ UNCHANGED <> + /\ UNCHANGED <> -\* `poll_step` names the failed streams: a stale expiry is a stale drop the next -\* update judges again, anything else a final one. A stale expiry of a group the -\* record folded while its stream was open is final too: no update re-offers it. +\* `poll_step` names each failed stream in a drop with its error, final like any other: +\* the group was served, so nothing serves or names it again. PubOutcomes == /\ outq # <<>> - /\ LET g == Head(outq)[1] - err == IF Head(outq)[2] = "old" /\ g \in folded THEN "evicted" ELSE Head(outq)[2] - IN /\ outq' = Tail(outq) - /\ resp' = Append(resp, DropMsg(g, err, pup)) - /\ IF err = "old" - THEN /\ expired' = expired \cup {g} - /\ dropped' = dropped \cup {g} - /\ dstale' = dstale \cup {g} - ELSE UNCHANGED <> - /\ UNCHANGED <> - -\* `poll_step` drops again, under the new number, what an update could not re-offer. -PubRedrop == - /\ outq = <<>> - /\ redrop # {} - /\ LET g == CHOOSE x \in redrop : \A y \in redrop : x <= y - IN /\ resp' = Append(resp, DropMsg(g, "old", pup)) - /\ redrop' = redrop \ {g} - /\ expired' = expired \cup {g} - /\ dropped' = dropped \cup {g} - /\ dstale' = dstale \cup {g} - /\ served' = served \cup {g} - /\ UNCHANGED <> - -\* `poll_track` serves a re-offered group, unless a verdict since accounted for it. One -\* the record folded while it waited is named in a final drop instead. -PubReoffer == - /\ outq = <<>> /\ redrop = {} - /\ reoffered # {} - /\ LET g == CHOOSE x \in reoffered : \A y \in reoffered : x <= y - IN /\ reoffered' = reoffered \ {g} - /\ CASE g \in folded -> - /\ resp' = Append(resp, DropMsg(g, "evicted", pup)) - /\ UNCHANGED <> - [] g \in served -> UNCHANGED <> - [] OTHER -> Serve(g) /\ UNCHANGED resp - /\ UNCHANGED <> + /\ outq' = Tail(outq) + /\ resp' = Append(resp, DropMsg(Head(outq)[1], Head(outq)[2])) + /\ ndrop' = [ndrop EXCEPT ![Head(outq)[1]] = @ + 1] + /\ UNCHANGED <> \* The pool hands the reader debt and its record folds the group into its floor: a group -\* handed out or named final, once nothing about it is still to tell. The fold stops at a -\* stale report the next update may reopen and at a failed stream not yet named. +\* the cursor reached a verdict on, once no failed stream of it is still to name. Every +\* report is final, so the fold forgets which: a skip no longer goes out over a drop. PubFold(g) == /\ Pressure /\ g \notin folded - /\ cur[g] \in {"handed", "final", "skip"} - /\ g \notin dstale + /\ cur[g] # "pending" /\ \A i \in 1..Len(outq) : outq[i][1] # g /\ folded' = folded \cup {g} - /\ UNCHANGED <> - -\* `TrackRun::update` applies a SUBSCRIBE_UPDATE: the cursor's stale verdicts reopen -\* (`reoffer_stale`, then `owe`), and each expired stream is judged again: served -\* again where the cache still holds a fresh copy (`reoffer_groups`), else dropped again. -\* A paused group is still owed its continuation or drop, so the update leaves it be. -PubUpdate == - /\ ctrl # <<>> - /\ LET u == Head(ctrl) - reopened == {g \in Groups : cur[g] = "stale"} - judged == expired \cup reoffered \cup redrop - IN /\ ctrl' = Tail(ctrl) - /\ pup' = u - /\ cur' = [g \in Groups |-> IF g \in reopened THEN "pending" ELSE cur[g]] - /\ \E fresh \in SUBSET judged : - LET owed == reopened \cup fresh - IN /\ reoffered' = fresh - /\ redrop' = judged \ fresh - /\ expired' = {} - /\ served' = served \ owed - /\ dropped' = dropped \ owed - /\ dstale' = dstale \ owed - /\ UNCHANGED <> + /\ dropped' = dropped \ {g} + /\ UNCHANGED <> ----------------------------------------------------------------------------- (* Subscriber *) @@ -341,12 +241,10 @@ Held(g) == {i \in 1..Len(streams) : streams[i].g = g /\ streams[i].sub = "held"} \* A stream of g is still being read into the copy, even one a final drop aborted. Filling(g) == \E j \in 1..Len(streams) : streams[j].g = g /\ streams[j].sub = "header" -\* The ledger already accounts for g, not only through a stream still reading it, and the -\* next update does not take that back (`buffer_update` owes again only a stale run the -\* copy still records): a stream that finished it, a reset, a final drop, a skip, or a stale -\* drop a fold marked overtaken. A stream that starts filling the copy then adds nothing a -\* YIELDED reset of it could take back. -Settled(g) == g \in acct /\ g \notin reading /\ ~(g \in sstale /\ rec[g] = "stale") +\* The ledger already accounts for g, not only through a stream still reading it: a +\* stream that finished it, a reset, a drop, or a skip. A stream that starts filling the +\* copy then adds nothing a YIELDED reset of it could take back. +Settled(g) == g \in acct /\ g \notin reading \* The first of them, which takes the copy over once the filling stream ends. NextHeld(g) == {j \in Held(g) : \A k \in Held(g) : j <= k} @@ -381,7 +279,7 @@ SubHeaderAt(i) == /\ have' = [have EXCEPT ![g] = streams[i].start] /\ reading' = IF Settled(g) THEN reading ELSE reading \cup {g} /\ UNCHANGED malformed - /\ UNCHANGED <> + /\ UNCHANGED <> \* The stream filling the copy delivers its next frame, which may have arrived before a \* reset that discards the rest. The copy ignores a frame it already holds. @@ -390,12 +288,11 @@ SubFrameAt(i) == /\ streams[i].read < streams[i].wrote /\ streams' = [streams EXCEPT ![i].read = @ + 1] /\ have' = [have EXCEPT ![streams[i].g] = Max(@, streams[i].start + streams[i].read + 1)] - /\ UNCHANGED <> + /\ UNCHANGED <> -\* The stream filling the copy is read to its FIN (`Reading::finish`); once every byte -\* arrived, a reset sent after the FIN changes nothing. A held stream of the group then -\* only duplicates it, a continuation included. +\* The stream filling the copy is read to its FIN; once every byte arrived, a reset sent +\* after the FIN changes nothing. A held stream of the group then only duplicates it, a +\* continuation included. SubFinAt(i) == /\ streams[i].sub = "header" /\ streams[i].read = streams[i].wrote @@ -406,21 +303,18 @@ SubFinAt(i) == IF j = i THEN [streams[j] EXCEPT !.sub = "fin"] ELSE IF j \in Held(g) THEN [streams[j] EXCEPT !.sub = "dup"] ELSE streams[j]] - /\ finished' = finished \cup {g} /\ cached' = [cached EXCEPT ![g] = "whole"] /\ got' = got \cup {g} /\ reading' = reading \ {g} - /\ UNCHANGED <> + /\ UNCHANGED <> \* The reset of the stream filling the copy arrives. Any code but YIELDED ends the group's \* readers with its error, and the first held stream of the group opens it again as a fresh \* copy (`TrackEntry::reopen`). YIELDED keeps the frames read: the first held stream \* continues the group, or with none the copy is paused, and the tail takes back what the -\* paused stream's reading accounted, unless a drop or skip under the update in effect -\* accounts for the group. A stale drop the filling stream had won over then records the -\* group stale, as it would arriving now. A YIELDED stream whose header arrived late, after -\* another stream settled the group, accounted nothing and takes nothing back. +\* paused stream's reading accounted, unless a drop or skip accounts for the group. A +\* YIELDED stream whose header arrived late, after another stream settled the group, +\* accounted nothing and takes nothing back. SubResetAt(i) == /\ streams[i].sub = "header" /\ streams[i].pub = "reset" @@ -431,7 +325,6 @@ SubResetAt(i) == pause == yielded /\ next = {} /\ cached[g] = "open" verdict == g \in sdrop \/ rec[g] \in {"final", "skip"} mine == g \in reading - restale == pause /\ mine /\ g \in sdrop /\ rec[g] = "none" IN /\ streams' = [j \in 1..Len(streams) |-> IF j = i THEN [streams[j] EXCEPT !.sub = "reset"] ELSE IF j \in next THEN [streams[j] EXCEPT !.sub = "header"] @@ -446,103 +339,54 @@ SubResetAt(i) == /\ malformed' = (malformed \/ (next # {} /\ yielded /\ streams[n].start > have[g])) /\ acct' = IF pause /\ mine /\ ~verdict THEN acct \ {g} ELSE acct /\ reading' = IF yielded /\ next # {} THEN reading ELSE reading \ {g} - /\ rec' = IF restale THEN [rec EXCEPT ![g] = "stale"] ELSE rec - /\ sstale' = IF restale THEN sstale \cup {g} ELSE sstale - /\ UNCHANGED <> + /\ UNCHANGED <> \* A held stream's own reset arrives. SubResetHeldAt(i) == /\ streams[i].sub = "held" /\ streams[i].pub = "reset" /\ streams' = [streams EXCEPT ![i].sub = "reset"] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The copy's cache evicts a whole group. Evict(g) == /\ cached[g] = "whole" /\ cached' = [cached EXCEPT ![g] = "evicted"] - /\ UNCHANGED <> - -\* The pool hands the tail debt and `Tail::rebill` folds every finished run but the newest -\* into the span it forgot: one group stands for any of them, since a later group may have -\* finished, and the span takes in the gaps between them, so g need not have finished or -\* even arrived. -TailFold(g) == - /\ Pressure - /\ g \notin forgot - /\ finished' = finished \ {g} - /\ forgot' = forgot \cup {g} - /\ UNCHANGED <> - -\* `apply_response` for SUBSCRIBE_DROP. A stale drop under a replaced update is no -\* verdict. Otherwise the tail accounts for the group; a stale drop records it in the -\* copy unless its stream finished under this update or the copy holds it -\* (`give_up` keeps an open group, though not a paused one), and a final drop records it -\* and ends its readers unless the copy holds it whole (`give_up` keeps a group a finished -\* copy serves, the live one or a fetched head). A fetched head still filling, which this -\* model leaves out, holds the drop in its slot until it finishes ("whole" here) or dies, -\* when the drop is the slot's cut (`Slot::verdict`): never lost, never beside a group. -\* A stale drop of a group inside the span a fold forgot that the ledger already -\* accounted (`Tail::overtaken`) may be one a finished stream overtook, so the next -\* update owes it nothing again. + /\ UNCHANGED <> + +\* `apply_response` for SUBSCRIBE_DROP: the tail accounts for the group, and a paused copy +\* or a stream still reading it ends there (`TrackEntry::dropped`). A stale drop records +\* it in the copy unless the copy holds it (`give_up` keeps an open group, though not a +\* paused one), and a final drop records it and ends its readers unless the copy holds it +\* whole (`give_up` keeps a group a finished copy serves, the live one or a fetched head). +\* A fetched head still filling, which this model leaves out, holds the drop in its slot +\* until it finishes ("whole" here) or dies, when the drop is the slot's cut +\* (`Slot::verdict`): never lost, never beside a group. OnDrop(m) == LET g == m.g - stale == m.err = "old" - IN IF m.u > sup - THEN /\ violation' = TRUE - /\ UNCHANGED <> - ELSE IF stale /\ m.u < sup - THEN UNCHANGED <> - ELSE IF stale - THEN LET recorded == g \notin finished - /\ cached[g] \notin {"open", "whole"} - /\ rec[g] # "skip" - owed == recorded /\ ~(g \in forgot /\ g \in acct) - IN /\ acct' = acct \cup {g} - /\ rec' = IF recorded THEN [rec EXCEPT ![g] = "stale"] ELSE rec - /\ sstale' = IF owed THEN sstale \cup {g} ELSE sstale - /\ sdrop' = sdrop \cup {g} - /\ UNCHANGED <> - ELSE /\ acct' = acct \cup {g} - /\ sstale' = sstale \ {g} - /\ rec' = IF rec[g] = "skip" \/ cached[g] = "whole" THEN rec ELSE [rec EXCEPT ![g] = "final"] - /\ cached' = [cached EXCEPT ![g] = IF @ \in {"open", "paused"} THEN "aborted" ELSE @] - /\ UNCHANGED <> + IN /\ acct' = acct \cup {g} + /\ sdrop' = sdrop \cup {g} + /\ IF m.err = "old" + THEN /\ rec' = IF cached[g] \notin {"open", "whole"} /\ rec[g] # "skip" + THEN [rec EXCEPT ![g] = "stale"] ELSE rec + /\ cached' = [cached EXCEPT ![g] = IF @ = "paused" THEN "aborted" ELSE @] + ELSE /\ rec' = IF rec[g] = "skip" \/ cached[g] = "whole" THEN rec ELSE [rec EXCEPT ![g] = "final"] + /\ cached' = [cached EXCEPT ![g] = IF @ \in {"open", "paused"} THEN "aborted" ELSE @] \* `apply_response` for SUBSCRIBE_SKIP: final, overriding any drop, but a group that \* arrived keeps it (`skip_received`). OnSkip(m) == LET g == m.g IN /\ acct' = acct \cup {g} - /\ sstale' = sstale \ {g} /\ rec' = IF cached[g] \in {"open", "whole"} THEN rec ELSE [rec EXCEPT ![g] = "skip"] - /\ UNCHANGED <> + /\ UNCHANGED <> SubRecv == /\ resp # <<>> /\ resp' = Tail(resp) /\ LET m == Head(resp) IN IF m.type = "drop" THEN OnDrop(m) ELSE OnSkip(m) - /\ UNCHANGED <> - -\* `buffer_update`: the copy forgets every stale record (`supersede_stale`), the tail -\* owes again each stale run this subscription accounted that the copy still held, -\* and `Tail::updated` forgets which streams finished and what a fold forgot. -SubUpdate == - /\ sup < MaxUpdates - /\ ~violation - /\ LET held == {g \in Groups : rec[g] = "stale"} - IN /\ sup' = sup + 1 - /\ ctrl' = Append(ctrl, sup + 1) - /\ rec' = [g \in Groups |-> IF rec[g] = "stale" THEN "none" ELSE rec[g]] - /\ acct' = acct \ (sstale \cap held) - /\ sstale' = {} - /\ sdrop' = {} - /\ finished' = {} - /\ forgot' = {} - /\ UNCHANGED <> + /\ UNCHANGED <> ----------------------------------------------------------------------------- @@ -554,8 +398,7 @@ StreamDone(s) == \* Nothing in flight and nothing left for the publisher to do. Quiet == - /\ resp = <<>> /\ ctrl = <<>> /\ outq = <<>> - /\ redrop = {} /\ reoffered = {} + /\ resp = <<>> /\ outq = <<>> /\ \A g \in Groups : cur[g] # "pending" /\ paused[g] = 0 /\ \A i \in 1..Len(streams) : StreamDone(streams[i]) @@ -587,9 +430,6 @@ Next == \/ \E g \in Groups : PubContinue(g) \/ \E g \in Groups, err \in {"old", "evicted"} : PausedGiveUp(g, err) \/ PubOutcomes - \/ PubRedrop - \/ PubReoffer - \/ PubUpdate \/ \E g \in Groups : PubFold(g) \/ SubHeader \/ SubFrame @@ -597,9 +437,7 @@ Next == \/ SubReset \/ SubResetHeld \/ \E g \in Groups : Evict(g) - \/ \E g \in Groups : TailFold(g) \/ SubRecv - \/ SubUpdate \/ Done Spec == Init /\ [][Next]_vars @@ -611,24 +449,29 @@ Spec == Init /\ [][Next]_vars \* Once quiet, the tail accounts for every group: none is waited for until the grace. QuietIsSettled == Quiet => acct = Groups -\* A group read to its FIN is never recorded stale: the stream wins over the drop. -StreamWins == \A g \in got : rec[g] # "stale" - -\* The publisher serves a group again only to re-offer one whose stream it reset, or to -\* continue the latest stream of the group, which it reset with YIELDED. +\* The publisher opens a second Group Stream for a group only to continue the group's +\* latest stream, which it reset with YIELDED. ServedOnce == \A i, j \in 1..Len(streams) : - /\ (i < j /\ streams[i].g = streams[j].g) => streams[i].pub = "reset" + /\ (i < j /\ streams[i].g = streams[j].g) => streams[i].pub = "reset" /\ streams[j].of # 0 /\ streams[j].of = i => /\ i < j /\ streams[i].g = streams[j].g /\ streams[i].err = "yielded" /\ \A k \in i + 1..j - 1 : streams[k].g # streams[j].g +\* Every name is final: the publisher names a group in at most one drop, and in at most +\* one skip, which goes out over a drop of a group it never served and over nothing else. +NamedOnce == + \A g \in Groups : + /\ ndrop[g] <= 1 + /\ nskip[g] <= 1 + /\ nskip[g] = 1 => \A i \in 1..Len(streams) : streams[i].g # g + \* A YIELDED reset alone never accounts for a group: while the publisher owes a paused \* group its continuation or drop, the subscriber's paused copy stays owed. Only what else -\* accounts for a group excuses it: a drop or skip under the update in effect, a stream -\* read to its FIN, or one whose reset of another code arrived with its header. +\* accounts for a group excuses it: a drop or skip, a stream read to its FIN, or one whose +\* reset of another code arrived with its header. PausedIsOwed == \A g \in Groups : (/\ cached[g] = "paused" @@ -648,7 +491,4 @@ OneReader == \A g \in Groups : Cardinality({i \in 1..Len(streams) : streams[i].g = g /\ streams[i].sub = "header"}) <= 1 -\* A drop never names an update the subscriber has not sent. -NoViolation == ~violation - ============================================================================= From f04b801db065b5328bf0082059b9ffa50b323a68 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:09:50 -0800 Subject: [PATCH 10/26] test(moq-net): a socket's out-of-order message arrives within the unlimited reader's grace Lite-07 now carries no max age as 0, so a socket's unlimited reader reaches the publisher as no limit rather than as the largest safe budget. The model waits a hole out for its grace under no limit, then gives it up, so the test's late message lands inside that grace. Formatting from `just fix` rides along. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/datagram.rs | 8 +++++++- rs/moq-net/src/lite/publisher.rs | 5 ++++- rs/moq-net/src/lite/subscribe.rs | 7 +++---- rs/moq-net/src/lite/subscriber.rs | 13 +++++++------ rs/moq-net/tests/integration/socket.rs | 5 +++-- 5 files changed, 24 insertions(+), 14 deletions(-) diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index 6dd83892631..0c67be0ef61 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -251,7 +251,13 @@ mod test { #[test] fn invalid_types_never_reach_a_subscription() { // 0x0 is the only type. - for body in [&[][..], &[0x80][..], &[1, 1, 2, 3][..], &[2, 1, 2, 3][..], &[0xff; 9][..]] { + for body in [ + &[][..], + &[0x80][..], + &[1, 1, 2, 3][..], + &[2, 1, 2, 3][..], + &[0xff; 9][..], + ] { assert!(Datagram::decode(Bytes::copy_from_slice(body), Version::Lite07).is_err()); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index b6df8bbbfc2..f47128b16b8 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -8500,7 +8500,10 @@ mod serve_group_test { // SUBSCRIBE_START with group 0 ended as the largest and the range starting at 0, a // SKIP for group 1, and // SUBSCRIBE_FINISH at 3. - assert_eq!(*log.writes.lock().unwrap(), [0, 5, 1, 0, 1, 1, 1, 3, 2, 1, 1, 1, 2, 3, 0]); + assert_eq!( + *log.writes.lock().unwrap(), + [0, 5, 1, 0, 1, 1, 1, 3, 2, 1, 1, 1, 2, 3, 0] + ); } /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 279117aa298..4458a57f5f1 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -395,10 +395,9 @@ fn wire_anchor(anchor: Option, end: bool) -> Result<(u64, Option), Some(Anchor::Time(time)) => (1, Some(time)), Some(Anchor::Relative(back)) => (2, Some(back)), Some(Anchor::Absolute(position)) if position.frame != 0 => return Err(EncodeError::Version), - Some(Anchor::Absolute(position)) if end => ( - 1, - Some(position.group.checked_sub(1).ok_or(EncodeError::InvalidState)?), - ), + Some(Anchor::Absolute(position)) if end => { + (1, Some(position.group.checked_sub(1).ok_or(EncodeError::InvalidState)?)) + } Some(Anchor::Absolute(position)) => (1, Some(position.group)), }) } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d02bedd3127..559b4dde972 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1183,8 +1183,9 @@ impl Subscriber { }; // A scale-less datagram's timestamp is bare, which the track checks is its sequence. let timestamp = match timescale { - Some(scale) => Timestamp::new(dg.timestamp, scale) - .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?, + Some(scale) => { + Timestamp::new(dg.timestamp, scale).map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))? + } None => Timestamp::unscaled(dg.timestamp), }; producer.insert(crate::datagram::Datagram { @@ -13872,10 +13873,10 @@ impl ServeLoop { } let mut owed = rangemap::RangeSet::new(); for given in given.iter() { - owed.extend( - self.serving - .give_up(given.clone(), track::Hole::stale(active.max_delay.unwrap_or(Duration::MAX))), - ); + owed.extend(self.serving.give_up( + given.clone(), + track::Hole::stale(active.max_delay.unwrap_or(Duration::MAX)), + )); } // Owed again by the next update, save what a stream may have won. for overtaken in overtaken { diff --git a/rs/moq-net/tests/integration/socket.rs b/rs/moq-net/tests/integration/socket.rs index 5b91e4351c9..62b7464dc43 100644 --- a/rs/moq-net/tests/integration/socket.rs +++ b/rs/moq-net/tests/integration/socket.rs @@ -185,8 +185,9 @@ async fn track_messages_are_read_in_key() { group.close().unwrap(); }; write(1, b"second"); - // Let the later message arrive first. - assert!(kio::clock::timeout(SETTLE, reader.next_group()).await.is_err()); + // Let the later message arrive first. A reader with no delay limit waits a second for a + // missing message the publisher may still write, then gives it up, so this stays under it. + assert!(kio::clock::timeout(SETTLE / 2, reader.next_group()).await.is_err()); write(0, b"first"); assert_eq!(recv(&mut reader).await.unwrap().unwrap(), b"first"); assert_eq!(recv(&mut reader).await.unwrap().unwrap(), b"second"); From 8d59f7412377ac152149dfb4450b8750b828b19a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:21:00 -0800 Subject: [PATCH 11/26] docs(drafts): an aborted largest group has not ended Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index fd16607ec4e..2ad4a82c6d7 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1941,7 +1941,7 @@ The largest position the publisher knows of for the track when it answers: the l A subscriber takes it as where the live feed is: a relay holding groups from an earlier subscription serves them from cache only once this says they are current, which a publisher answering promptly lets it do without waiting for a frame. **Largest Ended**: -Whether the largest group has ended: 0x1 when it finished, closed, or was aborted, so no frame follows `Largest Frame`, and 0x0 when it may still grow. +Whether the largest group has ended: 0x1 when it finished or closed, so no frame follows `Largest Frame`, and 0x0 otherwise, an aborted group included. Any other value is a PROTOCOL_VIOLATION. A subscriber joining a Track whose newest group ended knows at once that the group is not the live one, without waiting for its stream to end. From c301ab5ec1196766daea2872febfb6149a3ec873 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:30:13 -0800 Subject: [PATCH 12/26] fix(net): JS records a stale drop under the narrowest budget asked Mirrors Rust: with no update number on SUBSCRIBE_DROP, a lite-07 stale drop that arrives after a widening SUBSCRIBE_UPDATE may have been judged under the budget before it, so the subscriber records it under the narrowest max delay the subscription asked. A recovery's subscription records its own. Co-Authored-By: Claude Opus 5.5 --- js/net/src/lite/subscriber.test.ts | 47 ++++++++++++++++++++++++++++-- js/net/src/lite/subscriber.ts | 21 ++++++++----- 2 files changed, 58 insertions(+), 10 deletions(-) diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index b0fe4889f14..17d7f9e1867 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1685,7 +1685,8 @@ test.each(["continued", "dropped"] as const)("a reset without its code pauses th // Lite-07: Chromium can lose the reset of a Group Stream it has not handed to the page yet, which // leaves the stream open forever. A drop accounts for its group, so the subscription's end waits // for that stream at most the grace: a stale drop before or after its header, or a final one before -// it, even once a later stale drop of the group expires, whether it came before or after the header. A final drop after it ends the read at once. +// it, even with a stale drop of the group after the final one and an update after both. A final +// drop after it ends the read at once. test.each([ ["stale", "before"], ["stale", "after"], @@ -1722,7 +1723,7 @@ test.each([ if (kind === "final then stale" && order === "before") await respond(request, version, [stale]); await respond(request, version, [{ finish: new SubscribeFinish(1n) }]); await drainReactions(); - // The update expires the stale drop, but not the final one beneath it. + // An update reopens neither drop. if (kind === "final then stale") { track.update({ priority: 1 }); await drainReactions(); @@ -3353,6 +3354,48 @@ test("a stale drop accounts for its groups for good on lite-07", async () => { } }); +// A lite-07 stale (OLD) drop is recorded under the narrowest budget the subscription asked: the wire +// does not say which update a drop crossed, so one arriving after a widening update may have been +// judged under the budget before it. Mirrors the Rust `an_update_reopens_no_stale_drop`. +test("a stale drop is recorded under the narrowest budget asked on lite-07", async () => { + const version = Version.DRAFT_07; + const { quic, streams, opened } = fakeSession(); + const subscriber = new Subscriber(quic, version, toHop(1n)); + type Entry = { staleBudget: number }; + let entry: Entry | undefined; + const internal = subscriber as unknown as { + runResponses: (stream: unknown, entry: Entry) => Promise; + }; + const runResponses = internal.runResponses.bind(internal); + const responses = spyOn(internal, "runResponses").mockImplementation((stream, captured) => { + entry = captured; + return runResponses(stream, captured); + }); + const broadcast = subscriber.consume(Path.from("room")); + const track = broadcast.track("video").subscribe({ delay: { max: Duration.millis(500) } }); + try { + await opened(0); + await answerTrackInfo(streams[0], version); + const stream = await opened(1); + await stream.reading; + await drainReactions(); + if (!entry) throw new Error("no subscription"); + expect(entry.staleBudget).toBe(500); + + track.update({ delay: { max: Duration.millis(5000) } }); + await drainReactions(); + expect(entry.staleBudget).toBe(500); + track.update({ delay: { max: Duration.millis(200) } }); + await drainReactions(); + expect(entry.staleBudget).toBe(200); + } finally { + responses.mockRestore(); + track.close(); + broadcast.close(); + subscriber.close(); + } +}); + // A SKIP, or any final drop, that follows an OLD drop of the same groups replaces it in the copy: // the groups stay accounted for through an update, and the skip stays final. Mirrors Rust. test("a skip or final drop replaces an earlier stale one on lite-07", async () => { diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 39af2986664..f6264119832 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -222,9 +222,12 @@ interface SubscribeEntry { floor?: bigint; // What `#declare` last declared, so an unchanged one is not declared again. declared?: { start?: bigint | null; requested?: bigint }; - // The max delay the latest SUBSCRIBE or SUBSCRIBE_UPDATE asked for, in milliseconds: the budget - // a stale drop is recorded under. - maxDelay?: number; + // The narrowest max delay the SUBSCRIBE and every SUBSCRIBE_UPDATE asked for, in milliseconds, + // which a lite-07 stale drop is recorded under: the wire does not say which update a drop + // crossed, so it may have been judged under any budget asked before it arrived. Too narrow + // costs a wider reader a request of its own; too wide would settle it on a group it could + // still get. + staleBudget: number; // The subscribe stream, from the setup that registered this entry to its end. stream: SubscribeStream; // How many SUBSCRIBE_UPDATEs went out, so a tail settling past SUBSCRIBE_FINISH waits a fresh @@ -2320,7 +2323,7 @@ export class Subscriber { if (resolvesStart(this.version)) hooks.startTrack(producer, { requested: msg.startGroup }); const entry: SubscribeEntry = { track: producer, - maxDelay: msg.maxDelay, + staleBudget: msg.maxDelay, ...framing, // The effective max delay is the stopgap grace: the wrong clock (it bounds // presentation-time drift), but it is how long the subscriber was willing to wait @@ -2787,6 +2790,7 @@ export class Subscriber { ); const entry: SubscribeEntry = { track: producer, + staleBudget: msg.maxDelay, compress: copy.compress, timescale: copy.timescale, tail: new Tail({ grace: () => hooks.tailGrace(producer) }), @@ -3222,10 +3226,11 @@ export class Subscriber { else entry.tail.account(start, end); // A paused group the drop names ends there: no continuation follows. this.#dropPaused(entry, start, end, error); - // On lite-07 an OLD drop is stale, judged under this subscription's budget: a reader - // wider than that does not settle on it, and asks for the group with a request of its own. + // On lite-07 an OLD drop is stale, recorded under the narrowest budget it may have been + // judged under: a reader wider than that does not settle on it, and asks for the group + // with a request of its own. const stale = hasSkip(this.version) && toStreamCode(error) === StreamCode.Old; - const hole = stale ? staleHole(entry.maxDelay ?? 0) : { error }; + const hole = stale ? staleHole(entry.staleBudget) : { error }; hooks.dropTrackGroups(entry.track, start, end, hole); entry.fills?.refuse(start, end, error); } else if ("skip" in resp) { @@ -3441,7 +3446,7 @@ export class Subscriber { ranges: edit?.add, remove: edit?.remove, }); - entry.maxDelay = update.maxDelay; + entry.staleBudget = Math.min(entry.staleBudget, update.maxDelay); // Encoded apart from the write, so a bound the wire can't carry still fails the track. const encoded = await Writer.collect(this.version, (w) => update.encode(w, this.version)); // A failed write means the publisher stopped reading, as it does once it finishes the From 00af7b7d3481bd4f03742d01320e7c280ac66317 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:41:17 -0800 Subject: [PATCH 13/26] docs(skill): verify-subscribe describes final drops and records its runs The model has no updates to reopen a drop, so the skill drops the update numbers, re-offers, StreamWins and its open finding, adds NamedOnce, and syncs the coverage table to the code. With the state space smaller, the default config now covers two groups and Continuation.cfg two frames and three YIELDED resets; both pass (about 70.8M and 840K distinct states). Co-Authored-By: Claude Opus 5.5 --- .claude/skills/verify-subscribe/SKILL.md | 41 ++++++++------------ rs/moq-net/verify/subscribe/Continuation.cfg | 8 ++-- 2 files changed, 21 insertions(+), 28 deletions(-) diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index f9462e7456c..cd370e3fece 100644 --- a/.claude/skills/verify-subscribe/SKILL.md +++ b/.claude/skills/verify-subscribe/SKILL.md @@ -1,11 +1,11 @@ --- name: verify-subscribe -description: Model-check how a lite-07 subscription accounts for each group (`rs/moq-net/src/lite/publisher.rs` `TrackRun` and `GroupServe`, `lite/subscriber.rs` `ServeLoop::apply_response` and `buffer_update`, `src/tail.rs`) with TLA+. Use when a change touches SUBSCRIBE_DROP, SUBSCRIBE_SKIP, stale (OLD) drops and their update numbers, SUBSCRIBE_UPDATE re-offers, Group Stream resets and expiry, YIELDED resets and continuations of a paused group, duplicate Group Streams, or the subscriber's tail, or when a drop or re-offer bug needs every ordering of the Subscribe Stream against the Group Streams checked. +description: Model-check how a lite-07 subscription accounts for each group (`rs/moq-net/src/lite/publisher.rs` `TrackRun` and `GroupServe`, `lite/subscriber.rs` `ServeLoop::apply_response`, `src/tail.rs`) with TLA+. Use when a change touches SUBSCRIBE_DROP, SUBSCRIBE_SKIP, stale (OLD) drops, which groups a publisher serves or names once, Group Stream resets and expiry, YIELDED resets and continuations of a paused group, duplicate Group Streams, or the subscriber's tail, or when a drop bug needs every ordering of the Subscribe Stream against the Group Streams checked. --- # Verify subscription accounting -`rs/moq-net/verify/subscribe/SubscribeAccounting.tla` models one group of one answered lite-07 subscription between the publisher's `TrackRun` and the subscriber's `TrackServe`. The draft promises that every sequence in range gets a Group Stream, a SUBSCRIBE_SKIP, or a SUBSCRIBE_DROP; that a stale (OLD) drop holds only under the update it names and the next SUBSCRIBE_UPDATE reopens it; and that a Group Stream wins over a stale drop, even one it overtook. Drops and skips travel in order on the Subscribe Stream, each Group Stream travels on its own, a reset can lose a stream's header, and a reset sent after the FIN may arrive after every byte. A publisher out of stream credit may reset a Group Stream with YIELDED, which pauses the group instead of accounting for it: the subscriber keeps the frames it read, and the publisher owes a continuation, a Group Stream that starts at the reset stream's own Frame Start, or a drop. A continuation may overtake the YIELDED reset, or even the header, of the stream it continues. Each model step is one poll of the code that handles one event. The track cursor's verdicts (hand the group out, give it up stale or final, skip it) and whether the cache still holds a fresh copy on an update are free choices, and so are when the publisher yields a stream and whether it continues a paused group or gives it up. With `Pressure`, so is when the cache pool's debt folds what each side keeps of the group: the publisher's record and the subscriber's tail. TLC checks every ordering under the bounds in the config. +`rs/moq-net/verify/subscribe/SubscribeAccounting.tla` models the groups of one answered lite-07 subscription between the publisher's `TrackRun` and the subscriber's `TrackServe`. The draft promises that every sequence in range gets a Group Stream, a SUBSCRIBE_SKIP, or a SUBSCRIBE_DROP, and that every drop is final on its subscription, a stale (OLD) one included: a SUBSCRIBE_UPDATE reopens nothing, so the model leaves updates out. A skip still goes out over a drop of a group never served. Drops and skips travel in order on the Subscribe Stream, each Group Stream travels on its own, a reset can lose a stream's header, and a reset sent after the FIN may arrive after every byte. A publisher out of stream credit may reset a Group Stream with YIELDED, which pauses the group instead of accounting for it: the subscriber keeps the frames it read, and the publisher owes a continuation, a Group Stream that starts at the reset stream's own Frame Start, or a drop. A continuation may overtake the YIELDED reset, or even the header, of the stream it continues, and is the only second Group Stream of a group. Each model step is one poll of the code that handles one event. The track cursor's verdicts (hand a group out, give it up stale or final, skip it) are free choices, and so are when the publisher yields a stream and whether it continues a paused group or gives it up. With `Pressure`, so is when the cache pool's debt folds the publisher's record of a group. TLC checks every ordering under the bounds in the config. ## Rules @@ -13,49 +13,41 @@ Each rule is an INVARIANT; the harm says why it matters. | Rule | Holds when | Harm if broken | | --- | --- | --- | -| `NoViolation` | No SUBSCRIBE_DROP names an update the subscriber has not sent. | The subscriber closes the session with a PROTOCOL_VIOLATION. | -| `ServedOnce` | The publisher opens a second Group Stream for a group only after resetting the first, and a continuation continues the group's latest stream, which it reset with YIELDED. | The group's bytes go out twice at once, or a continuation resumes a group nobody paused. | -| `QuietIsSettled` | Once nothing is in flight and the publisher has nothing left to do, the subscriber's tail accounts for the group. | The subscriber waits out its grace for a group nobody will send, and a relay holds its readers there. | -| `PausedIsOwed` | While the publisher owes a paused group, the subscriber's paused copy stays owed, unless a drop or skip under the update in effect, a stream read to its FIN, or a reset of another code that arrived with its header accounts for it. | The tail settles on a YIELDED reset alone and the subscription ends before the continuation arrives. | +| `ServedOnce` | The publisher opens a second Group Stream for a group only to continue the group's latest stream, which it reset with YIELDED. | The group's bytes go out twice, or a continuation resumes a group nobody paused. | +| `NamedOnce` | The publisher names a group in at most one drop and at most one skip, and a skip only for a group it never served. | A second name contradicts a final one: the subscriber accounts the group twice or ends a reader on a group it delivered. | +| `QuietIsSettled` | Once nothing is in flight and the publisher has nothing left to do, the subscriber's tail accounts for every group. | The subscriber waits out its grace for a group nobody will send, and a relay holds its readers there. | +| `PausedIsOwed` | While the publisher owes a paused group, the subscriber's paused copy stays owed, unless a drop or skip, a stream read to its FIN, or a reset of another code that arrived with its header accounts for it. | The tail settles on a YIELDED reset alone and the subscription ends before the continuation arrives. | | `ContinuesWithinHeld` | A continuation that takes over a paused copy starts no later than the frames the copy holds (`Continuation.cfg`). | The subscriber treats the continuation as malformed, or a frame a reset discarded is never delivered. | | `OneReader` | The subscriber reads at most one Group Stream of a group at a time; a continuation waits, unread, for the stream it continues to end. | Two streams write one group's frames at once. | -| `StreamWins` | A group the subscriber read to its FIN is never recorded stale. | The subscriber owes a group it already has; the next update reopens it, and the publisher sends the whole group again or drops it again on every update. | ## Run ```sh quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla -config rs/moq-net/verify/subscribe/Continuation.cfg -quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla -config rs/moq-net/verify/subscribe/StreamWins.cfg ``` -The first checks every rule but `StreamWins` and `ContinuesWithinHeld` under `Pressure`, with one YIELDED reset and frames left out: about 77.7M distinct states, fifteen minutes. The second gives the group one frame and two YIELDED resets, without `Pressure` and over two updates, so it also checks where each continuation starts: about 29.6M distinct states, five minutes. Both pass. The third checks `StreamWins` without `Pressure` or YIELDED and fails on the open finding below. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. One group is enough: groups share only the order of the Subscribe Stream, and a second group multiplies the states (60M and more) without adding a race. - -## Open finding: a group read whole is named in a stale drop - -`StreamWins.cfg` fails. `GroupServe` in `GroupState::Closed` has written every frame and the FIN, and resets with OLD when the group goes stale before the acknowledgement; `settle_failed` then has `TrackRun::poll_step` name it in a stale drop under the update in effect, and record it in `expired`. The subscriber may already hold every byte. It ignores that drop only while the group is in `Tail::finished`, which `buffer_update` clears through `Tail::updated`, or while its copy still caches the group (`track::Producer::give_up` keeps an open group). So with an update sent between reading the FIN and the drop's arrival, and the copy having evicted the group, the subscriber records it stale and owes it again on the next update, while that update makes the publisher serve the whole group again (`reoffer_groups`) or drop it again under every later update. The draft says the publisher, having served a group, "neither serves it again nor names it in another drop". `residual_a_stale_unacknowledged_fin_drops_and_resends_a_served_group` in `lite/publisher.rs` replays the publisher's half, and `a_finished_group_wins_over_a_late_stale_drop_once_evicted` in `lite/subscriber.rs` pins the subscriber's half. Keeping `Tail::finished` across updates passes every rule in the model without `Pressure` (about 1.9M states). Under it, `Tail::rebill` still forgets a finished run by design: the overtaken drop records the group stale, though `Tail::overtaken` keeps it out of what the next update owes, since the ledger accounted the group before the drop. Once it is fixed, flip the residual test and drop the `\* Open finding:` line from `StreamWins.cfg`, which stays without `Pressure`. +The first checks every rule but `ContinuesWithinHeld` under `Pressure`, over two groups, six Group Streams, and two YIELDED resets per group, with frames left out: about 70.8M distinct states, twenty minutes. The second gives one group two frames and three YIELDED resets, without `Pressure`, so it also checks where each continuation starts: about 840K distinct states, ten seconds. Both pass. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. ## Reading a failure -Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on the code: the publisher's half with `lite07_run`, `write_group`, `run.update`, `SinkSession::with_unacked_fin`, and `drop_updates` in `lite/publisher.rs` tests; the subscriber's half with `lite07_serving`, `apply_response`, `buffer_update`, and `GroupRecv` in `lite/subscriber.rs` tests. +Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on the code: the publisher's half with `lite07_run`, `write_group`, `forward`, `drops`, and `SinkSession::with_unacked_fin` in `lite/publisher.rs` tests; the subscriber's half with `lite07_serving`, `apply_response`, and `GroupRecv` in `lite/subscriber.rs` tests. ## Coverage -Sync commit: `6aa4f9c1cad482aa86adcf3cf26bd7779697a01a`. Run `git log 6aa4f9c1ca.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. +Sync commit: `e5b28598c3b581cd091cf3ec232c8fd59285bf49`. Run `git log e5b28598c3.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. | Code | Model | | --- | --- | -| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_track` (`Recv::Group`, the re-offer pop), `serve`, `mark_served` | `CursorHand`, `PubReoffer`, `Serve` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_track` (`Recv::Group`), `serve`, `mark_served`; `rs/moq-net/src/model/record.rs` `Record::told` | `CursorHand`, `Serve` | | `rs/moq-net/src/lite/publisher.rs` `TrackRun::give_way`, `shed` | a new group, or one shed, as `Serve`, then `StreamFail` with `old` whose header never arrives; a continuation as `StreamYield` of a stream whose header never arrives | -| `rs/moq-net/src/lite/publisher.rs` `poll_forward_drop`, `forward_range`, `drop_range`, `replace_stale`, `sent_stale`, `hole` | `CursorGiveUp`, `ReplaceStale` | -| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_step` (outcomes, `redrop`) | `PubOutcomes`, `PubRedrop` | -| `rs/moq-net/src/lite/publisher.rs` `TrackRun::update`, `owe`; `rs/moq-net/src/model/track.rs` `reoffer_stale`, `reoffer_groups` | `PubUpdate` | +| `rs/moq-net/src/lite/publisher.rs` `poll_forward_drop`, `forward_range`, `drop_range`, `report`, `hole`; `rs/moq-net/src/model/record.rs` `Record::report`, `tell`, `untold`, `Report::blocks` | `CursorGiveUp`, `dropped` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_step` (outcomes) | `PubOutcomes` | | `rs/moq-net/src/lite/publisher.rs` `GroupServe::poll_serve` (`Serve`, `Closed`), `settle_failed` | `StreamFin`, `StreamFail`, `StreamAck` | +| `rs/moq-net/src/model/record.rs` `Record::fold` | `PubFold`, `folded` | | `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::open`, `reopen`, `place`; `GroupRecv::poll_serve` (the duplicate wait) | `SubHeader`, `SubFin`, `SubReset`, `SubResetHeld` | | `rs/moq-net/src/lite/subscriber.rs` `ServeLoop::apply_response` (`Drop`, `Skip`) | `OnDrop`, `OnSkip`, `SubRecv` | -| `rs/moq-net/src/lite/subscriber.rs` `buffer_update`; `rs/moq-net/src/model/track.rs` `supersede_stale` | `SubUpdate` | -| `rs/moq-net/src/tail.rs` `Reading::open`, `Reading::finish`, `Tail::finished`, `updated`, `account`, `unaccount` | `acct`, `finished` | -| `rs/moq-net/src/tail.rs` `Tail::rebill`, `overtaken`, `updated`; `rs/moq-net/src/lite/subscriber.rs` `ServeLoop::apply_response`; `rs/moq-net/src/model/record.rs` `Record::folded` | `TailFold`, `forgot`, `PubFold`, `folded` | +| `rs/moq-net/src/tail.rs` `Reading::open`, `Tail::account`, `accounts` | `acct`, `reading` | | `rs/moq-net/src/model/track.rs` `Producer::give_up`, `skip_received` | `rec`, `cached` | | `rs/moq-net/src/lite/publisher.rs` `GroupServe::settle_failed`, `TrackRun::open`; `rs/moq-net/src/transport/boxed.rs` `SendStream::preempted` | `StreamYield`, `PubContinue`, `PausedGiveUp` | | `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::pause`, `resume`, `dropped`, `read_yielding`, `end_yielding`, `YieldVerdict`, `GroupRecv::poll_serve`, `FrameIngest::dispatch` | the YIELDED branch of `SubReset`, `SubFrame`, `reading`, `sdrop`, `paused` | @@ -64,9 +56,10 @@ What the model asks of that code, each found by TLC as a broken rule without it: - A YIELDED reset takes back only what its own stream's header added to the ledger (`reading`): `TrackEntry::open` reads whether the tail already accounted the group before the stream accounts it (`Yielding::owed`). A header that arrives once the ledger settled the group adds nothing, so a YIELDED stream whose header arrives after its continuation finished the group owes nothing again (`QuietIsSettled`). - A continuation that takes over from a held position inherits that account (`TrackEntry::resume`), so its own YIELDED reset takes it back. -- A drop under the update in effect that reached a stream still being read ends its group once the YIELDED reset arrives (`TrackEntry::dropped`). The model then records the group stale; the code aborts the group with the drop's error, which the drop already accounted, so the tail settles either way. +- A drop that reached a stream still being read ends its group once the YIELDED reset arrives (`TrackEntry::dropped`). The model leaves the copy paused and accounted; the code aborts the group with the drop's error, which the drop already accounted, so the tail settles either way. - A stream waits, held, while another stream of its group is still read, even one a final drop aborted, not only while the copy is open (`OneReader`). +- The publisher serves no sequence its record already told, served or named (`Record::told`), and a skip goes out over a drop alone (`Report::blocks`), so a cursor that hands a group out again after giving it up, as after a route switch, sends nothing (`ServedOnce`, `NamedOnce`). ## Not covered -The subscription starts answered and covers the group, so SUBSCRIBE_OK, SUBSCRIBE_STARTED, ranges and Range IDs, fills (`RangeFills`), floors, and SUBSCRIBE_FINISH with `drop_unserved` are left out. The tail's grace and the ledger's folding are left out, so a group `Tail::overtaken` reports is one whose header arrived: `QuietIsSettled` asks for the publisher's answer, never the grace. So are priority and order (`Steer`), the Subscribe Stream's FIN and cancellation, sessions closing, versions before lite-07, relays forwarding drops downstream, datagrams, and the copy's readers (`poll_drop`). A route switch appears only as the cursor handing out once more a group it gave up. FETCH is left out: one request and one response, ended by a FIN or a reset, with nothing to race. GROUP_END takeover is left out: only the YIELDED reset pauses a group, and the publisher yields only a stream still serving. A pass covers one group, four updates, four Group Streams, and one YIELDED reset, or two updates, two YIELDED resets, and one frame in `Continuation.cfg`. +The subscription starts answered and covers the groups, so SUBSCRIBE_OK, SUBSCRIBE_STARTED, ranges and Range IDs, fills (`RangeFills`) and the separate request (`Recovery`) a reader wider than a stale drop asks with, floors, SUBSCRIBE_UPDATE, and SUBSCRIBE_FINISH with `drop_unserved` are left out. The tail's grace and the ledger's folding are left out: `QuietIsSettled` asks for the publisher's answer, never the grace. So are priority and order (`Steer`), the Subscribe Stream's FIN and cancellation, sessions closing, versions before lite-07, relays forwarding drops downstream, the budget a relay records a stale drop under, datagrams, and the copy's readers (`poll_drop`). A route switch appears only as the cursor handing out once more a group it gave up. FETCH is left out: one request and one response, ended by a FIN or a reset, with nothing to race. GROUP_END takeover is left out: only the YIELDED reset pauses a group, and the publisher yields only a stream still serving. A pass covers two groups, six Group Streams, and two YIELDED resets per group, or one group of two frames with three YIELDED resets in `Continuation.cfg`. diff --git a/rs/moq-net/verify/subscribe/Continuation.cfg b/rs/moq-net/verify/subscribe/Continuation.cfg index f8ddf22d5d6..b2d45486651 100644 --- a/rs/moq-net/verify/subscribe/Continuation.cfg +++ b/rs/moq-net/verify/subscribe/Continuation.cfg @@ -1,10 +1,10 @@ -\* A group of one frame, paused up to twice, without pressure: where each continuation -\* starts against the frames the subscriber holds, and every other rule. +\* A group of two frames, paused up to three times, without pressure: where each +\* continuation starts against the frames the subscriber holds, and every other rule. CONSTANTS Groups = {0} MaxStreams = 4 - MaxPauses = 2 - Frames = 1 + MaxPauses = 3 + Frames = 2 Pressure = FALSE SPECIFICATION Spec From 35cf2cae02e32b91f91d101f639dd8b63173f5af Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 07:17:08 -0800 Subject: [PATCH 14/26] feat(net)!: lite-07 GROUP carries Previous Start and groups end with GROUP_END GROUP gains Previous Start (the previous group's start plus one, 0 unknown). The publisher derives it from the skip run directly below the group, or a group just below it, and stops sending SUBSCRIBE_SKIP for a run its GROUP passes over; the run goes out as SUBSCRIBE_SKIP ahead of a drop of that group, or once an update means the group is no longer owed. The subscriber records the passed-over starts as skipped and refuses a previous start at or above the group's own. A Group or Fetch Stream ends a finished group with GROUP_END (Payload Length 0, then End) before its FIN; a bare FIN closes the group. The receiver finishes the group at End, refusing anything after GROUP_END or an End the group refuses as a malformed track, and closes it on a bare FIN. recv::Group splits into finish(end) and close(). A group that expires after its stream opened is closed rather than reset with OLD, and needs no drop; one whose stream never opened is still dropped. A stream whose end was written is never reset for expiry. A scale-less lite-07 FRAME carries its timestamp, its group's start; any other value is a TIMESTAMP_MISMATCH. Fills answer a group the copy records skipped, as a SUBSCRIBE_SKIP would. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/fixtures/lite.json | 9 +- rs/moq-net/src/fuzz.rs | 2 + rs/moq-net/src/fuzz/ingest.rs | 36 +- rs/moq-net/src/ietf/subscriber.rs | 8 +- rs/moq-net/src/lite/group.rs | 88 ++- rs/moq-net/src/lite/publisher.rs | 737 +++++++++++++++--- rs/moq-net/src/lite/subscriber.rs | 258 +++++- rs/moq-net/src/lite/subscriber/fills.rs | 14 + rs/moq-net/src/lite/track.rs | 10 +- rs/moq-net/src/lite/version.rs | 11 + rs/moq-net/src/model/group.rs | 25 +- rs/moq-net/src/model/resume.rs | 13 + rs/moq-net/src/model/track.rs | 73 ++ rs/moq-net/src/recv.rs | 30 +- rs/moq-net/src/test_interop.rs | 1 + rs/moq-net/tests/integration/group_end.rs | 133 ++++ rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/partial_group.rs | 36 +- 18 files changed, 1280 insertions(+), 205 deletions(-) create mode 100644 rs/moq-net/tests/integration/group_end.rs diff --git a/rs/moq-net/fixtures/lite.json b/rs/moq-net/fixtures/lite.json index cfe9a585d8d..e38752ff33c 100644 --- a/rs/moq-net/fixtures/lite.json +++ b/rs/moq-net/fixtures/lite.json @@ -285,7 +285,14 @@ "name": "a group sequence at 2^64-1, the largest a u64 holds", "version": "moq-lite-07-wip", "message": "group", - "hex": "0b00ffffffffffffffffff00", + "hex": "0c00ffffffffffffffffff0000", + "expect": "decoded" + }, + { + "name": "a group naming the start just below it as the previous one, carried plus one", + "version": "moq-lite-07-wip", + "message": "group", + "hex": "1400ffffffffffffffffffffffffffffffffffff00", "expect": "decoded" }, { diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index ab12cfdd763..85ad21f9d37 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -1461,6 +1461,7 @@ impl LiteSample { Self::Group => lite::Group { subscribe: 3, key: 1_234, + previous: None, frame_start: 0, } .encode(w, version) @@ -1707,6 +1708,7 @@ impl Default for Messages { lite_group: lite::Group { subscribe: 7, key: 123_456, + previous: None, frame_start: 0, }, ietf_subscribe: ietf::Subscribe { diff --git a/rs/moq-net/src/fuzz/ingest.rs b/rs/moq-net/src/fuzz/ingest.rs index e499f4148c9..e22e716e735 100644 --- a/rs/moq-net/src/fuzz/ingest.rs +++ b/rs/moq-net/src/fuzz/ingest.rs @@ -168,8 +168,9 @@ fn check(session: Session, info: &track::Info, body: &[u8], ingested: &Ingested) Session::Lite { records, .. } => { // Timing, inflated size, and size; a record adds its code and block length. let fields = 3 + 2 * records as usize; - // The Group State, and an END_OF_GROUP record with its block length. - let trailer = (1 + 2 * records as usize) * MAX_VARINT; + // The Group State, and an END_OF_GROUP record with its block length; or a + // GROUP_END's zero length and End. + let trailer = 3 * MAX_VARINT; let blocks: usize = ingested .frames .iter() @@ -212,7 +213,7 @@ fn run(session: Session, info: &track::Info, body: &[u8], chunk: usize) -> Optio let broadcast = broadcast.produce(); let track = broadcast.create_track("ingest", info.clone()).ok()?; - let (end, group) = match session { + let (end, fin, group) = match session { Session::Lite { version, records, @@ -230,7 +231,9 @@ fn run(session: Session, info: &track::Info, body: &[u8], chunk: usize) -> Optio keep_up(&mut viewer); res }); - (end.map(|()| "fin".to_string()), (group, consumer)) + let fin = end.as_ref().ok().copied().flatten(); + let end = end.map(|end| end.map_or_else(|| "fin".to_string(), |end| format!("end {end}"))); + (end, fin, (group, consumer)) } Session::Ietf { version } => { let (header, used) = ietf::GroupHeader::decode_slice(body, version).ok()?; @@ -256,7 +259,7 @@ fn run(session: Session, info: &track::Info, body: &[u8], chunk: usize) -> Optio keep_up(&mut viewer); res }); - (end.map(|ended| format!("{ended:?}")), (group, consumer)) + (end.map(|ended| format!("{ended:?}")), None, (group, consumer)) } }; @@ -264,7 +267,7 @@ fn run(session: Session, info: &track::Info, body: &[u8], chunk: usize) -> Optio // Settle the group as the session does, so the reader below never waits. match &end { Ok(_) => { - let _ = group.finish(); + let _ = group.end(fin); } Err(err) => { let _ = group.abort(err.clone()); @@ -357,11 +360,14 @@ pub(super) fn seeds() -> Vec { }; // moq-lite: three plain frames, at every version, timed and untimed. The timing - // prefix is a zigzag delta, so 0x02 steps the clock forward by one. + // prefix is a zigzag delta, so 0x02 steps the clock forward by one; an untimed lite-07 + // frame carries one too, which keeps its group's start. Lite-07 also ends the group + // whole with a GROUP_END. for (index, version) in super::LITE_VERSIONS.iter().enumerate() { for timed in [false, true] { let mut data = vec![(index * 2) as u8, timed as u8, 3]; - let timing = version.wire_timescale(timed.then_some(Timescale::MILLI)).is_some(); + let framing = lite::Framing::new(&track_info(timed, false, None), *version); + let timing = framing.stamped(); // Lite-07 leads with the size plus one; earlier versions end the header with it. let length_first = version.has_length_first(); for (n, payload) in [&b"abc"[..], b"", b"defgh"].into_iter().enumerate() { @@ -369,13 +375,20 @@ pub(super) fn seeds() -> Vec { data.push(payload.len() as u8 + 1); } if timing { - data.push(if n == 0 { 0 } else { 2 }); + data.push(if n == 0 || !timed { 0 } else { 2 }); } if !length_first { data.push(payload.len() as u8); } data.extend_from_slice(payload); } + if version.has_group_end() { + // A zero length, then the End: past the last frame's 2ms, or the start's next + // unit when untimed. + let mut whole = data.clone(); + whole.extend_from_slice(&[0, if timed { 3 } else { 1 }]); + push(whole); + } push(data); } } @@ -385,8 +398,9 @@ pub(super) fn seeds() -> Vec { let mut data = vec![(lite07 * 2) as u8, 0x10, 2, 0]; for payload in [&b"ab"[..], b"c"] { // Object 0 is the first record's absolute ID, then each next one is a zero delta, - // and neither has a property block. The frame's size follows, plus one. - data.extend_from_slice(&[0, 0, payload.len() as u8 + 1]); + // and neither has a property block. The frame's size follows, plus one, then a zero + // timestamp delta, which keeps the untimed group's start. + data.extend_from_slice(&[0, 0, payload.len() as u8 + 1, 0]); data.extend_from_slice(payload); } push(data); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index eb1ada63d65..46f313dfa3e 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -635,7 +635,7 @@ impl RangeWriter { /// Finish the current group, with the slot already settled. fn close_group(current: &mut Option<(u64, Option)>) -> Result<(), Error> { match current.take() { - Some((_, Some(producer))) => producer.finish(), + Some((_, Some(producer))) => producer.close(), _ => Ok(()), } } @@ -6443,12 +6443,12 @@ impl RecvGroup { Ok(()) } Ok(Ended::Group) => { - let _ = producer.finish(); + let _ = producer.close(); Ok(()) } // No object past this group's last one exists, so the track ends after it. Ok(Ended::Track { object, properties }) => { - let _ = producer.finish(); + let _ = producer.close(); end_track( &mut track, track::Position { @@ -7119,7 +7119,7 @@ impl RunFill { } if current.is_none() || group.is_some_and(|group| Some(group) != current) { if let Some((_, _, producer)) = self.head.take() { - producer.finish()?; + producer.close()?; } self.skipped = None; let key = group.ok_or(Error::ProtocolViolation)?; diff --git a/rs/moq-net/src/lite/group.rs b/rs/moq-net/src/lite/group.rs index f30ff2c2da6..c62a8771dc4 100644 --- a/rs/moq-net/src/lite/group.rs +++ b/rs/moq-net/src/lite/group.rs @@ -10,6 +10,11 @@ pub struct Group { // The group key pub key: u64, + /// Lite-07: the start of the group before this one on the track, or `None` when the + /// publisher does not know it. No group starts strictly between the two, so the starts + /// between are skipped. A receiver refuses one at or above `key` as a malformed track. + pub previous: Option, + // The index of the first frame on this stream. 0 (the common case) means the stream // carries the group from its beginning; a higher value means the leading frames are // missing, either because the subscription started partway in or because the @@ -18,19 +23,39 @@ pub struct Group { } impl Group { - /// The varints the newest layout carries: Subscribe ID, Group Sequence and Frame Start. - const FIELDS: usize = 3; + /// The varints the newest layout carries: Subscribe ID, Group Start, Previous Start and + /// Frame Start. + const FIELDS: usize = 4; + + /// The starts this header passes over as skipped; see [`passed_over`]. + pub(crate) fn passed_over(&self) -> std::ops::Range { + passed_over(self.previous, self.key) + } +} + +/// The starts a GROUP for `start` passes over as skipped when its previous group starts at +/// `previous`: those strictly between. Empty when the previous group is unknown or just below. +pub(crate) fn passed_over(previous: Option, start: u64) -> std::ops::Range { + match previous { + Some(previous) => previous.saturating_add(1).min(start)..start, + None => start..start, + } } impl<'a> Message<'a> for Group { /// Every field at its longest varint, so a header still arriving holds few bytes at its /// [unidentified](crate::priority::RECV_UNIDENTIFIED) receive rank. Versions before - /// lite-07 carry no more fields, in a shorter varint form. + /// lite-07 carry fewer fields, in a shorter varint form. const MAX_SIZE: usize = Self::FIELDS * crate::coding::varint::MAX_LEN; fn decode_msg(r: &mut Decoder<'a>, version: Version) -> Result { let subscribe = r.varint()?; let key = r.varint()?; + // Plus one, so 0 says unknown. + let previous = match version.has_group_end() { + true => r.varint()?.checked_sub(1), + false => None, + }; let frame_start = match version.has_frame_bounds() { true => r.varint()?, false => 0, @@ -39,6 +64,7 @@ impl<'a> Message<'a> for Group { Ok(Self { subscribe, key, + previous, frame_start, }) } @@ -46,6 +72,13 @@ impl<'a> Message<'a> for Group { fn encode_msg(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { w.varint(self.subscribe)?; w.varint(self.key)?; + if version.has_group_end() { + let previous = match self.previous { + Some(previous) => previous.checked_add(1).ok_or(EncodeError::InvalidState)?, + None => 0, + }; + w.varint(previous)?; + } if version.has_frame_bounds() { w.varint(self.frame_start)?; @@ -68,6 +101,7 @@ mod test { let msg = Group { subscribe: 1, key: 7, + previous: None, frame_start: 4, }; let mut buf = Vec::new(); @@ -84,6 +118,7 @@ mod test { let msg = Group { subscribe: 1, key: 7, + previous: None, frame_start: 4, }; let mut buf = Vec::new(); @@ -102,6 +137,42 @@ mod test { assert_eq!(got.frame_start, 0); } + /// Lite-07 carries the previous start plus one, 0 when unknown, and passes over the starts + /// strictly between; earlier versions carry nothing, so the previous start reads unknown. + #[test] + fn previous_start_is_plus_one_on_lite07_only() { + let encode = |previous, version: Version| { + let msg = Group { + subscribe: 1, + key: 7, + previous, + frame_start: 0, + }; + let mut buf = Vec::new(); + msg.encode_msg(&mut Encoder::new(&mut buf, version.into()), version) + .unwrap(); + buf + }; + assert_eq!(encode(Some(4), Version::Lite07), [1, 7, 5, 0]); + assert_eq!(encode(None, Version::Lite07), [1, 7, 0, 0]); + assert_eq!(encode(Some(4), Version::Lite06), [1, 7, 0]); + + let decode = |wire: &[u8], version| { + crate::coding::decode_buf(&mut &wire[..], version, |r, v| Group::decode_msg(r, v)).unwrap() + }; + let got = decode(&[1, 7, 5, 0], Version::Lite07); + assert_eq!((got.previous, got.passed_over()), (Some(4), 5..7)); + let got = decode(&[1, 7, 7, 0], Version::Lite07); + assert_eq!((got.previous, got.passed_over()), (Some(6), 7..7)); + let got = decode(&[1, 7, 0, 0], Version::Lite07); + assert_eq!((got.previous, got.passed_over()), (None, 7..7)); + assert_eq!(decode(&[1, 7, 0], Version::Lite06).previous, None); + + // One at or above the group's own start passes over nothing: the receiver refuses it. + let got = decode(&[1, 7, 8, 0], Version::Lite07); + assert_eq!((got.previous, got.passed_over()), (Some(7), 7..7)); + } + /// The size cap admits the longest header every version can carry: each field at its /// form's largest value, whose minimal encoding is already that form's longest. Lite-07 /// fills the cap exactly, and one byte more is refused at the length prefix. @@ -121,10 +192,11 @@ mod test { Form::Quic => (crate::coding::varint::MAX_QUIC, 8), Form::LeadingOnes => (u64::MAX, crate::coding::varint::MAX_LEN), }; - let fields = if version.has_frame_bounds() { 3 } else { 2 }; + let fields = 2 + usize::from(version.has_frame_bounds()) + usize::from(version.has_group_end()); let msg = Group { subscribe: max, key: max, + previous: version.has_group_end().then_some(max - 1), frame_start: if version.has_frame_bounds() { max } else { 0 }, }; @@ -140,19 +212,19 @@ mod test { let (got, used) = Group::decode_slice(&wire, version).unwrap(); assert_eq!(used, wire.len(), "{version:?}"); assert_eq!( - (got.subscribe, got.key, got.frame_start), - (msg.subscribe, msg.key, msg.frame_start), + (got.subscribe, got.key, got.previous, got.frame_start), + (msg.subscribe, msg.key, msg.previous, msg.frame_start), "{version:?}" ); } - assert_eq!(::MAX_SIZE, 27); + assert_eq!(::MAX_SIZE, 36); let over = ::MAX_SIZE + 1; let mut wire = vec![over as u8]; wire.resize(1 + over, 0); assert!(matches!( Group::decode_slice(&wire, Version::Lite07), - Err(DecodeError::MessageTooLarge { size: 28, max: 27 }) + Err(DecodeError::MessageTooLarge { size: 37, max: 36 }) )); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 67c19a6da1f..d677a90ffc2 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2500,9 +2500,9 @@ impl Request for SubscribeServe { }; crate::ietf::flate::egress(track.info(), shared.version.has_compression())?; - // `None` omits the per-frame timestamp prefix: an untimed track on - // Lite07+, or any track before Lite05 (whose frames still carry - // timestamps in the model, just not on this wire). + // `None` omits the per-frame timestamp prefix: any track before Lite05, + // whose frames still carry timestamps in the model, just not on this wire. + // Lite07 stamps a scale-less track's frames with their group's start. let stamp = Stamp::new(shared.version, track.info().timescale); // Lite05+ accepts implicitly: no SUBSCRIBE_OK, the immutable properties @@ -2897,9 +2897,9 @@ struct DatagramSend { session: Transport, id: u64, version: Version, - /// How datagrams are stamped, or `None` on a scale-less lite-07 track, whose datagrams - /// carry their producer's bare value. - stamp: Option, + /// How datagrams are stamped: every version with datagrams stamps them, a scale-less + /// lite-07 track's with its producer's bare value. + stamp: Stamp, /// The publisher's priority for the track, which breaks subscriber priority ties. publisher: i8, /// The subscription's send group, or `None` on a transport without groups. @@ -2916,7 +2916,9 @@ impl DatagramSend { session, id, version: shared.version, - stamp: Stamp::new(shared.version, info.timescale), + stamp: Stamp { + timescale: shared.version.wire_timescale(info.timescale), + }, publisher: info.priority, group, stats, @@ -2938,12 +2940,8 @@ impl DatagramSend { /// every datagram its source produces later is at least as far, so the subscription can /// deliver no more. One the network reordered below it is lost, as any datagram may be. fn send(&self, datagram: crate::datagram::Datagram) -> Result<(), Error> { - let timestamp = match self.stamp { - Some(stamp) => match stamp.wire(datagram.timestamp) { - Ok(timestamp) => timestamp, - Err(_) => return Ok(()), - }, - None => datagram.timestamp.value(), + let Ok(timestamp) = self.stamp.wire(datagram.timestamp) else { + return Ok(()); }; let sequence = datagram.sequence; let size = datagram.payload.len(); @@ -3226,7 +3224,7 @@ impl Request for FetchServe { } writer.bill(group.delegate()); let capped = msg.end_frame.is_some(); - let timescale = stamp.map(|stamp| stamp.timescale); + let timescale = stamp.and_then(|stamp| stamp.timescale); let records = lite::ietf::Records::new(ietf, capped, timescale); *self = Self::Serve { @@ -3292,8 +3290,12 @@ impl Request for FetchServe { return Poll::Ready(Ok(ControlFlow::Continue(()))); } Poll::Ready(Ok(_)) => { - if let Some(records) = records { - records.end(writer, group)?; + // A finished group's end closes the response, which the FIN follows. + match records { + Some(records) => records.end(writer, group)?, + None => { + buffer_group_end(writer, shared.version, false, group)?; + } } return Poll::Ready(Ok(ControlFlow::Break(()))); } @@ -3318,8 +3320,12 @@ impl Request for FetchServe { return Poll::Ready(Ok(ControlFlow::Continue(()))); } None => { - if let Some(records) = records { - records.end(writer, group)?; + // A finished group's end closes the response, which the FIN follows. + match records { + Some(records) => records.end(writer, group)?, + None => { + buffer_group_end(writer, shared.version, false, group)?; + } } return Poll::Ready(Ok(ControlFlow::Break(()))); } @@ -4619,15 +4625,18 @@ fn buffer_frame_info( /// How a lite hop stamps a track's frames and a datagram track's datagrams. #[derive(Clone, Copy, Debug)] struct Stamp { - /// The wire timescale TRACK_INFO declared (see [`Version::wire_timescale`]). - timescale: crate::Timescale, + /// The wire timescale TRACK_INFO declared (see [`Version::wire_timescale`]), or `None` on + /// a scale-less lite-07 track, whose timestamps go out as bare numbers. + timescale: Option, } impl Stamp { - /// How `version` stamps a track with `timescale`, or `None` when it carries no timestamps. + /// How `version` stamps a track with `timescale`, or `None` when it carries no timestamps: + /// before lite-05. Lite-05/06 declare milliseconds for a scale-less track, and lite-07 + /// stamps it bare. fn new(version: Version, timescale: Option) -> Option { - Some(Self { - timescale: version.wire_timescale(timescale)?, + version.has_track_stream().then(|| Self { + timescale: version.wire_timescale(timescale), }) } @@ -4638,8 +4647,10 @@ impl Stamp { if timestamp.scale().is_none() { return Ok(timestamp.value()); } + // A timed timestamp on a track declared scale-less: the model never writes one. + let timescale = self.timescale.ok_or(Error::TimestampMismatch)?; timestamp - .convert(self.timescale) + .convert(timescale) .map(|time| time.value()) .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded)) } @@ -4960,8 +4971,9 @@ struct GroupOutcomes { #[cfg(test)] opened: std::sync::atomic::AtomicU64, unencodable: Mutex>, - /// Groups whose stream failed, with why, for the control stream to name. - dropped: Mutex>, + /// Groups whose stream failed, with why, for the control stream to name, each with the + /// skipped starts its GROUP's Previous Start passed over (see [`TrackRun::elided`]). + dropped: Mutex)>>, /// Lite-07: groups whose stream the session reset to make room, for the run loop to /// continue on a new stream. paused: Mutex>, @@ -4974,6 +4986,8 @@ struct Paused { /// discarded frames the transport acknowledged, so the continuation starts there. group: group::Consumer, frame_start: u64, + /// The previous group's start its GROUP carried, which the continuation's carries too. + previous: Option, } /// Waits for the subscription's budget or the cache to give the paused group up. Each @@ -5037,6 +5051,7 @@ impl Subscription { self.group_context(), key, frame_start, + None, false, Rank::Queue(priority), group, @@ -5148,6 +5163,14 @@ struct TrackRun { /// Lite-07: the ranges an update added whose start no SUBSCRIBE_STARTED reported yet, by /// Range ID. unstarted: Vec, + /// Lite-07: the skipped runs not sent as SUBSCRIBE_SKIP, each by the start of the cached + /// group just above it, whose GROUP's Previous Start passes over the run instead. Each + /// waits for that group to be served, when its stream carries the run, or given up, when + /// the run goes out ahead of the drop. At most one per cached group. + elided: std::collections::BTreeMap, + /// Lite-07: an update moved the ranges, so a run elided for a group they no longer name + /// goes out as SUBSCRIBE_SKIP after all. + recheck_elided: bool, } impl TrackRun { @@ -5180,6 +5203,8 @@ impl TrackRun { ids: (0..initial).collect(), initial, unstarted: Vec::new(), + elided: Default::default(), + recheck_elided: false, bounded, frames: bounds.frames, named: groups.start(), @@ -5219,6 +5244,7 @@ impl TrackRun { if let Some(datagrams) = &mut self.datagrams { datagrams.steer(upd.priority); } + self.recheck_elided = !self.elided.is_empty(); // The update moves the cursor and the bounds the track side judges against, which // notifies nothing it parked on. Idle::disarm(&mut self.idle); @@ -5438,6 +5464,10 @@ impl TrackRun { // Deliver the buffered range messages before selecting more work. ready!(writer.poll_flush(waiter))?; + if std::mem::take(&mut self.recheck_elided) && self.release_elided(writer)? { + return Poll::Ready(Ok(ControlFlow::Continue(()))); + } + // The group waiting for stream credit joins the others once it has one, or fails // without one. if let Some(opening) = &mut self.opening @@ -5479,8 +5509,12 @@ impl TrackRun { let dropped = std::mem::take(&mut *self.ctx.outcomes.dropped.lock().unwrap()); if !dropped.is_empty() { // Each was served, so its record says so already, and the drop is final: nothing - // is served or dropped over it again. - for (key, err) in dropped { + // is served or dropped over it again. The skipped starts its GROUP passed over go + // first, since that GROUP may never have arrived. + for (key, err, passed) in dropped { + if !passed.is_empty() { + writer.buffer(&self.hole(passed, &Hole::Skip))?; + } writer.buffer(&self.hole(key..key + 1, &Hole::drop(err)))?; } return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -5550,10 +5584,14 @@ impl TrackRun { && (self.opening.is_none() || stuck.is_some_and(|waiting| rank > waiting)) { let PausedKey { key, .. } = self.paused.remove(&best).expect("best is paused"); - let Paused { group, frame_start } = self.paused_tasks.remove(key).expect("a paused group waits"); + let Paused { + group, + frame_start, + previous, + } = self.paused_tasks.remove(key).expect("a paused group waits"); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, start = group.start, frame_start, "continuing paused group"); self.give_way(); - self.open(group, frame_start); + self.open(group, frame_start, previous); self.continuing = true; return Poll::Ready(Ok(ControlFlow::Continue(()))); } @@ -5746,10 +5784,71 @@ impl TrackRun { } let report = self.report(hole); self.track.record_mut().tell(range.clone(), report); + match hole { + Hole::Skip if self.elides(&range) => { + let start = self.elided.entry(range.end).or_insert(range.start); + *start = range.start.min(*start); + return Ok(false); + } + Hole::Skip => {} + Hole::Drop { .. } => { + self.send_elided(range.clone(), writer)?; + } + } writer.buffer(&self.hole(range, hole))?; Ok(true) } + /// Whether the skipped `run` goes unsent, since the GROUP of the cached group just above it + /// passes over it: lite-07, with that group still owed on this subscription, and its + /// previous start at or below the run's. + fn elides(&mut self, run: &Range) -> bool { + let above = run.end; + self.ctx.version.has_group_end() + && self.owes_group(above) + && self + .track + .previous_start(above) + .is_some_and(|previous| previous < run.start) + } + + /// Whether the cached group at `key` is still owed a stream or a drop on this subscription. + fn owes_group(&mut self, key: u64) -> bool { + self.track.holds(key) && !self.track.record_mut().told(key) && self.track.next_in_range(key) == Some(key) + } + + /// Send as SUBSCRIBE_SKIP each run elided for a group in `groups`, which is given up. + fn send_elided( + &mut self, + groups: Range, + writer: &mut Writer, + ) -> Result<(), Error> { + let above: Vec = self.elided.range(groups).map(|(above, _)| *above).collect(); + for above in above { + let start = self.elided.remove(&above).expect("collected above"); + writer.buffer(&self.hole(start..above, &Hole::Skip))?; + } + Ok(()) + } + + /// Send as SUBSCRIBE_SKIP each run elided for a group this subscription no longer owes, + /// after an update moved its ranges. Returns whether any was buffered. + fn release_elided( + &mut self, + writer: &mut Writer, + ) -> Result { + let elided: Vec<(u64, u64)> = self.elided.iter().map(|(above, start)| (*above, *start)).collect(); + let mut sent = false; + for (above, start) in elided { + if !self.owes_group(above) { + self.elided.remove(&above); + writer.buffer(&self.hole(start..above, &Hole::Skip))?; + sent = true; + } + } + Ok(sent) + } + /// What the wire is told when `hole` goes out. fn report(&self, hole: &Hole) -> Report { match self.ctx.version.has_skip() { @@ -5773,6 +5872,9 @@ impl TrackRun { if !self.start.emits_range() || range.is_empty() { return Ok(false); } + if !matches!(hole, Hole::Skip) { + self.send_elided(range.clone(), writer)?; + } let gaps = self.track.record_mut().untold(range); let report = self.report(hole); for gap in gaps.iter() { @@ -5958,8 +6060,14 @@ impl TrackRun { let frame_start = group.index(); self.mark_served(key); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, key, "serving group"); + // Its GROUP passes over the run elided below it, and a drop of it sends the run first. + self.elided.remove(&key); + let previous = match self.ctx.version.has_group_end() { + true => self.track.previous_start(key), + false => None, + }; self.give_way(); - self.open(group, frame_start); + self.open(group, frame_start, previous); } /// The rank of the group waiting for stream credit, if it cannot make room: it ranks below @@ -5994,6 +6102,7 @@ impl TrackRun { self.pause(Paused { group: waiting.group.clone(), frame_start: waiting.frame_start, + previous: waiting.previous, }); } false => waiting.settle_failed(&Error::Old), @@ -6002,9 +6111,15 @@ impl TrackRun { /// Give up a group the cursor handed out without a stream, as one expired under the /// subscription's budget is. - fn shed(&self, key: u64) { + fn shed(&mut self, key: u64) { if self.ctx.version.has_track_stream() { - self.ctx.outcomes.dropped.lock().unwrap().push((key, StreamError::Old)); + let passed = self.elided.remove(&key).map_or(key..key, |start| start..key); + self.ctx + .outcomes + .dropped + .lock() + .unwrap() + .push((key, StreamError::Old, passed)); } } @@ -6036,12 +6151,17 @@ impl TrackRun { } let mut dropped = Vec::new(); let _ = self.paused_tasks.poll_each(waiter, |paused, err| { - dropped.push((paused.group.start, StreamError::from(&err))); + let start = paused.group.start; + dropped.push(( + start, + StreamError::from(&err), + lite::passed_over(paused.previous, start), + )); }); if dropped.is_empty() { return; } - for (start, _) in &dropped { + for (start, _, _) in &dropped { self.paused.remove(start); } if self.ctx.version.has_track_stream() { @@ -6049,9 +6169,10 @@ impl TrackRun { } } - /// Open a group machine streaming `group` from `frame_start`, which waits for stream - /// credit before the cursor hands out another. - fn open(&mut self, group: group::Consumer, frame_start: u64) { + /// Open a group machine streaming `group` from `frame_start`, its GROUP naming `previous` + /// as the group before it, which waits for stream credit before the cursor hands out + /// another. + fn open(&mut self, group: group::Consumer, frame_start: u64, previous: Option) { let key = group.start; // The stream stops at the end frame, before the group may end. let capped = self.frames.end(key).is_some(); @@ -6076,6 +6197,7 @@ impl TrackRun { self.ctx.group_context(), key, frame_start, + previous, capped, rank, group, @@ -6230,6 +6352,7 @@ impl PausedBench { coverage.run.pause(Paused { group: group.consume(), frame_start: 0, + previous: None, }); groups.push(group); } @@ -6281,6 +6404,58 @@ fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option Option { + if !version.has_group_end() { + return poll_given_up(group, waiter); + } + if *ending == Ending::Group && group.poll_expired(waiter) { + *ending = Ending::Expired; + } + // The cursor of an expired group fails its own end too, which closing replaces. + if *ending == Ending::Expired { + return None; + } + match group.poll_finished(waiter) { + Poll::Ready(Err(err)) => Some(err), + _ => None, + } +} + +/// Whether a lite-07 read that failed on `group` found it expired, which closes its stream +/// at this frame boundary rather than resetting it. +fn closes_expired(version: Version, group: &group::Consumer) -> bool { + version.has_group_end() && group.is_expired() +} + +/// Buffer GROUP_END once a lite-07 stream without the `ietf` extension's object records read +/// `group` to the end of a finished group: a `Payload Length` of 0, then the group's +/// exclusive end in its track's timescale. Returns whether it did, so the FIN follows it; +/// otherwise the FIN alone says the group closed. +fn buffer_group_end( + writer: &mut Writer, + version: Version, + records: bool, + group: &group::Consumer, +) -> Result { + if !version.has_group_end() || records { + return Ok(false); + } + let Some(end) = group.end().filter(|_| group.index() >= group.frame_count() as u64) else { + return Ok(false); + }; + writer.buffer_varint(0)?; + writer.buffer_varint(end)?; + Ok(true) +} + /// Serves one group on its own unidirectional stream: the header, then every /// frame, applying queue and SUBSCRIBE_UPDATE priority changes as they land. struct GroupServe { @@ -6291,6 +6466,9 @@ struct GroupServe { group: group::Consumer, key: u64, frame_start: u64, + /// Lite-07: the start of the group before this one, which its GROUP carries so the + /// subscriber learns the starts skipped between (see [`track::Subscriber::previous_start`]). + previous: Option, /// The stream stops at a subscription's end frame, so its FIN cannot end the group. capped: bool, /// Lite-07 on a track without the `ietf` extension's object records: an unread copy of `group` at @@ -6330,22 +6508,48 @@ enum GroupState { batch_pos: usize, /// The `ietf` extension's object records, when negotiated. records: Option, + ending: Ending, }, - /// Every frame is written and the FIN sent: wait for the acknowledgement so a - /// late cancel or expiry can still reset the stream. + /// Every frame is written and the FIN sent: wait for the acknowledgement so a late + /// cancel can still reset the stream, and before lite-07 a late expiry too. Closed { writer: Writer, }, Done, } +/// How a serving Group Stream ends. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Ending { + /// With the group: a FIN once its frames run out, after a GROUP_END on lite-07 if it + /// finished whole. + Group, + /// Lite-07: the group expired, so the stream FINs at the next frame boundary without a + /// GROUP_END. The subscriber keeps what arrived, and no drop names the group. + Expired, + /// Lite-07: the GROUP_END is buffered, so the FIN follows once it flushes. + Whole, +} + impl GroupServe { /// Whether it holds a stream still sending, which a higher-ranked group may take over. fn serving(&self) -> bool { matches!(self.state, GroupState::Serve { .. }) } - fn new(ctx: GroupContext, key: u64, frame_start: u64, capped: bool, rank: Rank, group: group::Consumer) -> Self { + #[allow( + clippy::too_many_arguments, + reason = "one group stream's header fields and how it is ranked, each from its own source" + )] + fn new( + ctx: GroupContext, + key: u64, + frame_start: u64, + previous: Option, + capped: bool, + rank: Rank, + group: group::Consumer, + ) -> Self { // A lite-07 peer receives a compressed group as stored, others inflated. let mut group = match ctx.version.has_compression() { true => group.compressed(), @@ -6362,6 +6566,7 @@ impl GroupServe { group, key, frame_start, + previous, capped, prev_ts: 0, state: GroupState::Open, @@ -6428,11 +6633,16 @@ impl GroupServe { let msg = lite::Group { subscribe: self.ctx.id, key: self.key, + previous: self.previous, frame_start: self.frame_start, }; let header = writer.buffer(&lite::DataType::Group).and_then(|()| writer.buffer(&msg)); let records = match header { - Ok(()) => lite::ietf::Records::new(self.ctx.ietf, self.capped, self.ctx.stamp.map(|stamp| stamp.timescale)), + Ok(()) => lite::ietf::Records::new( + self.ctx.ietf, + self.capped, + self.ctx.stamp.and_then(|stamp| stamp.timescale), + ), Err(err) => { // The header wrote nothing, so the group-stream reset has nothing to pin // it to this subscription. The run loop reads the slot and resets the @@ -6450,6 +6660,7 @@ impl GroupServe { batch: Box::default(), batch_pos: 0, records, + ending: Ending::Group, }; Poll::Ready(Ok(())) } @@ -6512,6 +6723,7 @@ impl GroupServe { batch, batch_pos, records, + ending, } => { let outcome = 'serve: { // The stream closing first cancels the group, or fails it with the reason @@ -6529,7 +6741,7 @@ impl GroupServe { // flow control must not pin a stream that has gone stale, or one // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = poll_given_up(&mut self.group, waiter) { + if let Some(err) = poll_stopped(&mut self.group, self.ctx.version, ending, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -6555,7 +6767,9 @@ impl GroupServe { // flow control must not pin a stream that has gone stale, or one // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = poll_given_up(&mut self.group, waiter) { + if let Some(err) = + poll_stopped(&mut self.group, self.ctx.version, ending, waiter) + { break 'serve Err(err); } return Poll::Pending; @@ -6568,6 +6782,10 @@ impl GroupServe { Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => return Poll::Pending, } + } else if *ending != Ending::Group { + // At a frame boundary with everything flushed: after the GROUP_END, + // or with the expired group's frames cut off here. + break 'serve Ok(()); } else if *batch_pos < batch.len() { let index = self.group.index() - batch.len() as u64 + *batch_pos as u64; let batched = &mut batch[*batch_pos]; @@ -6616,8 +6834,22 @@ impl GroupServe { Ok(()) => continue, Err(err) => break 'serve Err(err), }, - None => break 'serve Ok(()), + None => { + match buffer_group_end(writer, self.ctx.version, self.ctx.ietf, &self.group) + { + Ok(true) => { + *ending = Ending::Whole; + continue; + } + Ok(false) => break 'serve Ok(()), + Err(err) => break 'serve Err(err), + } + } }, + Poll::Ready(Err(_)) if closes_expired(self.ctx.version, &self.group) => { + *ending = Ending::Expired; + break 'serve Ok(()); + } Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => {} } @@ -6659,8 +6891,22 @@ impl GroupServe { Ok(()) => continue, Err(err) => break 'serve Err(err), }, - None => break 'serve Ok(()), + None => { + match buffer_group_end(writer, self.ctx.version, self.ctx.ietf, &self.group) + { + Ok(true) => { + *ending = Ending::Whole; + continue; + } + Ok(false) => break 'serve Ok(()), + Err(err) => break 'serve Err(err), + } + } }, + Poll::Ready(Err(_)) if closes_expired(self.ctx.version, &self.group) => { + *ending = Ending::Expired; + break 'serve Ok(()); + } Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => return Poll::Pending, } @@ -6668,11 +6914,15 @@ impl GroupServe { } }; - let GroupState::Serve { writer, .. } = std::mem::replace(&mut self.state, GroupState::Done) else { + let GroupState::Serve { writer, ending, .. } = std::mem::replace(&mut self.state, GroupState::Done) + else { unreachable!() }; match outcome { Ok(()) => { + if ending == Ending::Expired { + tracing::debug!(key = self.key, "closing expired group"); + } let mut writer = writer; // The buffer drained before the final frame resolved, so the // FIN follows the last byte. @@ -6702,9 +6952,11 @@ impl GroupServe { // discard bytes still retransmitting. let res = match writer.poll_close(waiter) { Poll::Ready(res) => res, - // Those bytes still hold the connection until acknowledged, so a - // group gone stale meanwhile releases them like one still serving. - Poll::Pending if self.group.poll_expired(waiter) => { + // Those bytes still hold the connection until acknowledged, so before + // lite-07 a group gone stale meanwhile releases them like one still + // serving. Lite-07 already said how the group ended, which a reset + // would take back. + Poll::Pending if !self.ctx.version.has_group_end() && self.group.poll_expired(waiter) => { let GroupState::Closed { writer } = std::mem::replace(&mut self.state, GroupState::Done) else { unreachable!() @@ -6761,16 +7013,16 @@ impl GroupServe { let paused = Paused { group, frame_start: self.frame_start, + previous: self.previous, }; self.ctx.outcomes.paused.lock().unwrap().push(paused); return; } - self.ctx - .outcomes - .dropped - .lock() - .unwrap() - .push((self.key, StreamError::from(err))); + self.ctx.outcomes.dropped.lock().unwrap().push(( + self.key, + StreamError::from(err), + lite::passed_over(self.previous, self.key), + )); } } @@ -6947,19 +7199,24 @@ mod serve_group_test { } } - /// Lite-05/06 cannot encode a scale-less track, so its frames carry their group's key - /// there, never a clock, and nothing on lite-07, while a timed track carries its own - /// timestamps on every version. + /// A scale-less track's frames carry their group's key, never a clock: as milliseconds on + /// lite-05/06, which cannot encode a scale-less track, and bare on lite-07. A timed track + /// carries its own timestamps on every version, and nothing before lite-05 carries one. #[test] fn a_scale_less_track_goes_out_with_its_keys() { let stamped = Timestamp::from_millis(36_000_000).unwrap(); for version in [Version::Lite06, Version::Lite07] { let stamp = Stamp::new(version, Some(crate::Timescale::MILLI)).unwrap(); assert_eq!(stamp.wire(stamped).unwrap(), stamped.value(), "{version}"); + let stamp = Stamp::new(version, None).unwrap(); + assert_eq!(stamp.wire(Timestamp::unscaled(7)).unwrap(), 7, "{version}"); } - let stamp = Stamp::new(Version::Lite06, None).unwrap(); - assert_eq!(stamp.wire(Timestamp::unscaled(7)).unwrap(), 7); - assert!(Stamp::new(Version::Lite07, None).is_none()); + assert_eq!( + Stamp::new(Version::Lite06, None).unwrap().timescale, + Some(crate::Timescale::MILLI) + ); + assert_eq!(Stamp::new(Version::Lite07, None).unwrap().timescale, None); + assert!(Stamp::new(Version::Lite04, Some(crate::Timescale::MILLI)).is_none()); } #[kio::test] @@ -7059,6 +7316,125 @@ mod serve_group_test { assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); } + /// A lite-07 subscription on `session` stamping in milliseconds, for serving one group. + fn lite07_subscription(session: SinkSession) -> Subscription { + let steer = kio::Producer::new(Steer::default()); + Subscription { + session: crate::driver::Transport::new(session), + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + publisher: 0, + group: None, + steer: steer.consume(), + steer_seen: Steer::default(), + version: Version::Lite07, + stamp: Stamp::new(Version::Lite07, Some(crate::Timescale::MILLI)), + outcomes: Default::default(), + ietf: false, + object_records: false, + } + } + + /// What the first send stream wrote, and whether it then FINed. + fn first_stream(log: &Log) -> (Vec, bool) { + let mut bytes = Vec::new(); + let mut fin = false; + for (id, sent) in log.trail() { + match (id, sent) { + (0, Sent::Write(write)) => bytes.extend(write), + (0, Sent::Finish) => fin = true, + _ => {} + } + } + (bytes, fin) + } + + /// Lite-07 ends a finished group's stream with GROUP_END, a zero `Payload Length` then the + /// End, before the FIN; a closed group's ends with the FIN alone. + #[kio::test] + async fn lite07_ends_a_finished_group_with_group_end() { + for finished in [true, false] { + let log = Log::default(); + let subscription = lite07_subscription(SinkSession::new(log.clone())); + let track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut group = track.create_group(group::Info { start: 0 }).unwrap(); + group + .write_frame(Timestamp::from_millis(2).unwrap(), b"x".as_slice()) + .unwrap(); + match finished { + true => group.finish(5).unwrap(), + false => group.close().unwrap(), + }; + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + subscription + .serve_group(0, 0, handle, track.consume().peek_group(0).unwrap()) + .await + .unwrap(); + + let (bytes, fin) = first_stream(&log); + assert!(fin, "finished={finished}: no FIN"); + // The frame: its length plus one, the timestamp delta, and the payload. + let tail: &[u8] = match finished { + true => &[2, 4, b'x', 0, 5], + false => &[2, 4, b'x'], + }; + assert!(bytes.ends_with(tail), "finished={finished}: {bytes:?}"); + assert!(log.resets().is_empty(), "finished={finished}"); + } + } + + /// A lite-07 group expiring while its stream is open, here behind a blocked transport + /// write, closes the stream with what it sent rather than resetting it, sends none of the + /// frames written since, and needs no drop. + #[kio::test] + async fn lite07_closes_a_group_that_expires_on_its_stream() { + let gate = kio::Producer::new(false); + let session = SinkSession::gated_uni(gate.consume()); + let log = session.log.clone(); + let subscription = lite07_subscription(session); + let track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut subscriber = track.subscribe(None); + let mut old = track.append_next().unwrap(); + old.write_frame(old.key_time(), b"old".as_slice()).unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + let outcomes = subscription.outcomes.clone(); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!( + futures::poll!(serve.as_mut()).is_pending(), + "transport write is blocked" + ); + + kio::clock::sim::advance(Duration::from_secs(1)).await; + let mut edge = track.append_next().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.close().unwrap(); + assert!(futures::poll!(serve.as_mut()).is_pending(), "the frame is still owed"); + // The group goes on, but its stream sends no more of it. + old.write_frame(Timestamp::from_millis(10).unwrap(), b"more".as_slice()) + .unwrap(); + *gate.write().ok().unwrap() = true; + + serve.await.unwrap(); + assert!(log.resets().is_empty(), "reset"); + let (bytes, fin) = first_stream(&log); + assert!(fin, "no FIN"); + // Only the GROUP: the write blocked before the first frame, and none goes out after. + assert_eq!(bytes, [0, 4, 0, 0, 0, 0]); + assert!(outcomes.dropped.lock().unwrap().is_empty(), "dropped"); + } + /// Egress counts only payload the transport took: a group reset while its frames wait in /// the read-ahead batch bills none of them, and one served whole bills every byte. #[kio::test] @@ -7744,6 +8120,29 @@ mod serve_group_test { } } + /// Each Group Stream's GROUP on `log`'s session, as (Group Start, Previous Start), by start. + fn group_headers(log: &Log, version: Version) -> Vec<(u64, Option)> { + let mut streams = std::collections::BTreeMap::<_, Vec>::new(); + for (id, sent) in log.trail() { + if let Sent::Write(bytes) = sent { + streams.entry(id).or_default().extend(bytes); + } + } + let mut headers: Vec<_> = streams + .values() + .map(|bytes| { + crate::coding::decode_buf(&mut bytes.as_slice(), version, |r, v| { + assert_eq!(lite::DataType::decode(r, v)?, lite::DataType::Group); + let group = lite::Group::decode(r, v)?; + Ok((group.key, group.previous)) + }) + .unwrap() + }) + .collect(); + headers.sort(); + headers + } + fn lite_run( version: Version, session: SinkSession, @@ -7845,7 +8244,7 @@ mod serve_group_test { session, id: 0, version, - stamp: Stamp::new(version, Some(crate::Timescale::MILLI)), + stamp: Stamp::new(version, Some(crate::Timescale::MILLI)).unwrap(), publisher: 0, group, stats: crate::stats::Scope::default(), @@ -8347,8 +8746,8 @@ mod serve_group_test { ); } - /// A key the publisher declared it will never produce is accounted for by SKIP - /// rather than a stream count. + /// A key the publisher declared it will never produce is accounted for without a stream + /// count: the GROUP of the group just above it passes over it, so no SKIP goes out. #[kio::test] async fn lite07_skips_a_declared_skip() { let mut track = track::Producer::new( @@ -8357,7 +8756,8 @@ mod serve_group_test { crate::track::Info::timed(), ); let subscriber = track.subscribe(None); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + let session = Log::default(); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(session.clone()), subscriber); let mut run = std::pin::pin!(kio::wait(move |waiter| run.poll(&mut writer, waiter))); write_group(&mut track, 0, 0); @@ -8367,12 +8767,67 @@ mod serve_group_test { let _track = track.finish().unwrap(); assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); - // SUBSCRIBE_START with group 0 ended as the largest and the range starting at 0, a SKIP - // for groups [1, 2), and SUBSCRIBE_FINISH at 3. - assert_eq!( - *log.writes.lock().unwrap(), - [0, 5, 1, 0, 1, 1, 1, 3, 2, 1, 2, 1, 2, 3, 0] + // SUBSCRIBE_START with group 0 ended as the largest and the range starting at 0, and + // SUBSCRIBE_FINISH at 3. + assert_eq!(*log.writes.lock().unwrap(), [0, 5, 1, 0, 1, 1, 1, 1, 2, 3, 0]); + // Group 2's GROUP names group 0 as the one before it, passing over [1, 2). + assert_eq!(group_headers(&session, Version::Lite07), [(0, None), (2, Some(0))]); + } + + /// A skipped run below a group whose stream opened goes out as SUBSCRIBE_SKIP ahead of a + /// drop of that group, since its GROUP, which passes over the run, may never arrive. + #[kio::test] + async fn lite07_sends_an_elided_skip_ahead_of_a_drop() { + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), ); + let subscriber = track.subscribe(None); + let session = Log::default(); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(session.clone()), subscriber); + write_group(&mut track, 0, 0); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + track.skip_groups(1..3); + write_group(&mut track, 3, 3); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + assert_eq!(group_headers(&session, Version::Lite07), [(0, None), (3, Some(0))]); + assert!( + holes(&mut writer, &log).await.is_empty(), + "the GROUP passes over the run" + ); + + // Group 3's stream is given up after it opened. + run.ctx + .outcomes + .dropped + .lock() + .unwrap() + .push((3, StreamError::Cancel, 1..3)); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3), ("drop", 3..4)]); + } + + /// A skipped run below a group the subscription has not served yet is held back for its + /// GROUP, and goes out as SUBSCRIBE_SKIP once the group is given up instead. + #[kio::test] + async fn lite07_sends_a_held_skip_when_its_group_is_dropped() { + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + track.received(); + let subscriber = track.subscribe(None); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 0, 0); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + track.skip_groups(1..3); + write_group(&mut track, 3, 3); + forward(&mut run, 1..3, &Hole::Skip, &mut writer); + assert!(holes(&mut writer, &log).await.is_empty(), "held for group 3's GROUP"); + forward(&mut run, 3..4, &Hole::drop(StreamError::Cancel), &mut writer); + assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3), ("drop", 3..4)]); } /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the @@ -8418,8 +8873,9 @@ mod serve_group_test { } } - /// A huge declared skip goes out as one SUBSCRIBE_SKIP, at a cost independent of its - /// length, and the end settles over it. + /// A huge declared skip goes out at a cost independent of its length, and the end settles + /// over it: one below a group the GROUP passes over, one past the last group as one + /// SUBSCRIBE_SKIP. #[kio::test] async fn lite07_skips_a_huge_run_at_once() { const FAR: u64 = 1 << 61; @@ -8429,10 +8885,12 @@ mod serve_group_test { crate::track::Info::timed(), ); let subscriber = track.subscribe(None); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + let session = Log::default(); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(session.clone()), subscriber); write_group(&mut track, 0, 0); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} track.skip_groups(1..FAR); + track.skip_groups(FAR + 1..FAR + 5); write_group(&mut track, FAR, 1); let _track = track.finish().unwrap(); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} @@ -8450,7 +8908,8 @@ mod serve_group_test { _ => {} } } - assert_eq!((skips, drops), (vec![(1, FAR)], 0)); + assert_eq!((skips, drops), (vec![(FAR + 1, FAR + 5)], 0)); + assert_eq!(group_headers(&session, Version::Lite07), [(0, None), (FAR, Some(0))]); } /// A relay that holds only the first group of a backlog answers with the largest its @@ -8551,6 +9010,23 @@ mod serve_group_test { drops } + /// The lite-07 SUBSCRIBE_SKIP and SUBSCRIBE_DROP a run loop's subscribe stream carried, in + /// order, once flushed. + async fn holes( + writer: &mut Writer, + log: &Log, + ) -> Vec<(&'static str, Range)> { + responses(writer, log) + .await + .into_iter() + .filter_map(|msg| match msg { + lite::SubscribeResponse::Skip(skip) => Some(("skip", skip.groups)), + lite::SubscribeResponse::Drop(drop) => Some(("drop", drop.groups)), + _ => None, + }) + .collect() + } + /// A stale (OLD) drop is final on every version: a final drop of the same group does not go /// out over it, and a group handed out after it, as when a front switches to a route that /// delivers what the old route reported stale, is not served. @@ -8602,7 +9078,12 @@ mod serve_group_test { } while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} // Group 3's stream expired, as a blocked transport would leave it. - run.ctx.outcomes.dropped.lock().unwrap().push((3, StreamError::Old)); + run.ctx + .outcomes + .dropped + .lock() + .unwrap() + .push((3, StreamError::Old, 3..3)); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} let case = format!("{version:?}, widen={widen}"); assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 3, "{case}"); @@ -8627,55 +9108,65 @@ mod serve_group_test { } } - /// A group whose stream wrote its FIN but goes stale before the acknowledgement resets with - /// OLD and is named in a stale drop, which is final: a later update widening the budget never - /// serves it again, though the subscriber may have read the first stream whole. + /// A group whose stream wrote its FIN but goes stale before the acknowledgement is never + /// served again, though the subscriber may have read the first stream whole. Before lite-07 + /// the stream resets with OLD and a stale drop names it, which is final even when a later + /// update widens the budget; lite-07 leaves a stream whose end it wrote alone, and needs no + /// drop. #[kio::test] async fn a_stale_unacknowledged_fin_is_never_served_again() { - let budget = Duration::from_millis(1500); - let mut track = track::Producer::new( - Arc::new(broadcast::Info::default()), - "test", - crate::track::Info::timed(), - ); - let subscriber = - track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); - let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()).with_unacked_fin(), subscriber); - let update = |max_delay| lite::SubscribeUpdate { - wanted_group: None, - priority: 0, - max_delay: Some(max_delay), - min_delay: None, - ranges: vec![(0, lite::Range::span(None, 0, None, None))], - order: Order::Descending, - }; + for version in [Version::Lite06, Version::Lite07] { + let budget = Duration::from_millis(1500); + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let subscriber = + track.subscribe(track::Subscription::default().with_delay(track::Delay::default().with_max(budget))); + let session = Log::default(); + let (mut run, mut writer, log) = lite_run( + version, + SinkSession::new(session.clone()).with_unacked_fin(), + subscriber, + ); + let update = |max_delay| lite::SubscribeUpdate { + wanted_group: None, + priority: 0, + max_delay: Some(max_delay), + min_delay: None, + ranges: vec![(0, lite::Range::span(None, 0, None, None))], + order: Order::Descending, + }; - // Group 0 goes out whole: every frame and the FIN, which the peer has yet to - // acknowledge. - write_group(&mut track, 0, 0); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 1); + // Group 0 goes out whole: every frame and the FIN, which the peer has yet to + // acknowledge. + write_group(&mut track, 0, 0); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + assert_eq!(run.ctx.outcomes.opened.load(Ordering::Relaxed), 1, "{version}"); - // Group 1 starts 1s in, and group 2 at 6s leaves group 0 past the budget while its FIN - // is still unacknowledged. - write_group(&mut track, 1, 1000); - write_group(&mut track, 2, 6000); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - drops(&mut writer, &log, Version::Lite07).await, - [(0, 0)], - "the served group is named stale" - ); + // Group 1 starts 1s in, and group 2 at 6s leaves group 0 past the budget while its + // FIN is still unacknowledged. + write_group(&mut track, 1, 1000); + write_group(&mut track, 2, 6000); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + let (dropped, resets): (&[(u64, u64)], &[u32]) = match version.has_group_end() { + true => (&[], &[]), + false => (&[(0, 0)], &[StreamError::Old.to_code()]), + }; + assert_eq!(drops(&mut writer, &log, version).await, dropped, "{version}"); + assert_eq!(session.resets(), resets, "{version}"); - let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); - run.update(update(Duration::from_secs(10))); - while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!( - run.ctx.outcomes.opened.load(Ordering::Relaxed), - opened, - "group 0 is not served again" - ); - assert_eq!(drops(&mut writer, &log, Version::Lite07).await, [(0, 0)]); + let opened = run.ctx.outcomes.opened.load(Ordering::Relaxed); + run.update(update(Duration::from_secs(10))); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + assert_eq!( + run.ctx.outcomes.opened.load(Ordering::Relaxed), + opened, + "{version}: group 0 is not served again" + ); + assert_eq!(drops(&mut writer, &log, version).await, dropped, "{version}"); + } } /// Lite-05 and later name every key below the end that the subscription never @@ -12295,6 +12786,7 @@ mod tests { run.pause(Paused { group: bench.groups[0].consume(), frame_start: 1, + previous: None, }); assert_eq!(run.paused_tasks.len(), 1, "the earlier wait is cancelled"); assert_eq!(run.paused[&100].frame_start, 1); @@ -12304,7 +12796,7 @@ mod tests { run.drop_given_up_paused(&kio::Waiter::noop()); assert!(run.paused.is_empty() && run.paused_tasks.is_empty()); let dropped = run.ctx.outcomes.dropped.lock().unwrap(); - assert_eq!(dropped.iter().map(|(start, _)| *start).collect::>(), [100]); + assert_eq!(dropped.iter().map(|(start, _, _)| *start).collect::>(), [100]); } /// The next paused group to continue is the newest when descending, the oldest when @@ -12333,6 +12825,7 @@ mod tests { run.pause(Paused { group: empty.consume(), frame_start: 0, + previous: None, }); run.drop_given_up_paused(&kio::Waiter::noop()); assert!(run.paused.contains_key(&200), "a finished group waits to continue"); @@ -12342,6 +12835,6 @@ mod tests { assert!(!run.paused.contains_key(&200)); assert_eq!(run.paused_tasks.len(), 1, "only the released group leaves"); let dropped = run.ctx.outcomes.dropped.lock().unwrap(); - assert_eq!(dropped.iter().map(|(start, _)| *start).collect::>(), [200]); + assert_eq!(dropped.iter().map(|(start, _, _)| *start).collect::>(), [200]); } } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 35b17d58820..615f6fa0844 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -471,6 +471,24 @@ impl TrackEntry { // is written, through the tagged `track::Producer`. The track counts // it as content once its first frame lands. let received = producer.create_group_at(group_info, hdr.frame_start); + // Lite-07: the starts the header passes over were never produced, as a SUBSCRIBE_SKIP + // would say. Recorded once the group is, so a relay serving the copy sees the group + // the skip runs up to, whose own GROUP passes over it again. + let passed = hdr.passed_over(); + if !passed.is_empty() { + if let Ok(mut tail) = self.tail.write() { + tail.account(passed.clone(), now); + } + let cached = producer.skip_received(passed.clone()); + if let Some(first) = cached.iter().next() { + tracing::warn!( + group = hdr.key, + passed = ?passed, + cached = first.start, + "protocol error: GROUP passes over a group that arrived; keeping the group" + ); + } + } // Asked before this stream accounts for the group: a drop that overtook it named it. let owed = !self.tail.read().accounts(hdr.key); // The subscription's end waits until this stream is read. Counted @@ -1649,6 +1667,10 @@ impl GroupRecv { } self.reader.poll_decode::(waiter).map_ok(|hdr| (ietf, hdr)) })?; + // A previous group at or past this one's own start is no group before it. + if header.1.previous.is_some_and(|previous| previous >= header.1.key) { + return Poll::Ready(Err(Error::MalformedTrack)); + } // A SUBSCRIBE sent alongside its TRACK may be served before the TRACK_INFO that says // how to read it: the stream parks, unread, until the accept opens its group. @@ -1815,10 +1837,8 @@ impl GroupRecv { .and_then(|entry| entry.end_yielding(hdr.key, stream)) }); let res = match res { - Ok(()) => { - let _ = group.finish(); - Ok(()) - } + // Whole at a GROUP_END's end, else closed: every frame sent arrived. + Ok(end) => group.end(end), Err(err @ (Error::Cancel | Error::Stream(crate::StreamError::Cancel))) => { let _ = group.abort(err); Ok(()) @@ -1866,8 +1886,8 @@ impl GroupRecv { /// Pumps bare FRAME messages from a reader into a group producer: the wire /// format shared by GROUP streams and FETCH responses. pub(crate) struct FrameIngest { - /// A timescale decodes the lite-05 zigzag-delta timestamp prefix; none leaves frames - /// untimed (pre-lite-05). + /// Whether frames carry the zigzag-delta timestamp prefix (lite-05+), in the track's + /// timescale, or bare on a scale-less lite-07 track, where each must be its group's start. framing: lite::Framing, /// Previous frame's raw timestamp value (in `timescale` units), for the /// zigzag-delta decode. The first frame's delta is absolute (prev = 0). @@ -1914,9 +1934,13 @@ enum IngestPhase { /// The END_OF_GROUP record arrived, so only the stream end may follow. Ended, /// Lite-07: reading the `Payload Length`, the payload size plus one, which leads the - /// frame. Stream end here means the group has no more frames. + /// frame, or 0 for GROUP_END. Stream end here means the group closed incomplete. Length, - /// Reading the timestamp delta (skipped without a timescale), after the size on lite-07. + /// Lite-07: reading GROUP_END's `End`, the group's exclusive end. + GroupEnd, + /// Lite-07: GROUP_END said where the group ends, so only the stream end may follow. + Finished { end: u64 }, + /// Reading the timestamp delta (skipped when frames carry none), after the size on lite-07. /// Stream end here before lite-07 means the group has no more frames. Timing { size: Option }, /// Reading a compressed Track's inflated size (lite-07), or skipped. Stream end here @@ -1974,12 +1998,13 @@ impl FrameIngest { self.partial.take() } - /// The stream ended on a frame boundary: the group ends, unless a continuation ended - /// before completing the frame its group held cut short. - fn end(&self) -> Result<(), Error> { + /// The stream ended on a frame boundary: the group ends, whole at `end` after a GROUP_END + /// or closed without one, unless a continuation ended before completing the frame its + /// group held cut short. + fn end(&self, end: Option) -> Result, Error> { match self.partial { Some(_) => Err(Error::ProtocolViolation), - None => Ok(()), + None => Ok(end), } } @@ -2073,15 +2098,15 @@ impl FrameIngest { } } - /// `Ready(Ok(()))` once the stream FINs on a frame boundary. The caller - /// finishes or aborts the group; a frame cut short mid-payload was already - /// aborted here with the reason. + /// `Ready(Ok(end))` once the stream FINs on a frame boundary, with the group's end when a + /// GROUP_END preceded the FIN. The caller finishes, closes, or aborts the group; a frame + /// cut short mid-payload was already aborted here with the reason. pub(crate) fn poll( &mut self, reader: &mut Reader, group: &mut crate::recv::Group, waiter: &kio::Waiter, - ) -> Poll> { + ) -> Poll, Error>> { let mut budget = kio::coop::Budget::new(32); loop { match &mut self.phase { @@ -2107,7 +2132,7 @@ impl FrameIngest { } IngestPhase::Object => { let Some(code) = ready!(reader.poll_varint_maybe(waiter))? else { - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); }; let records = self.records.as_mut().expect("the Group State came first"); let (id, end) = lite::ietf::decode_object(records.prior, code)?; @@ -2154,34 +2179,54 @@ impl FrameIngest { if ready!(reader.poll_has_more(waiter))? { return Poll::Ready(Err(Error::ProtocolViolation)); } - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); } IngestPhase::Length => { let Some(length) = ready!(self.poll_header_varint(reader, true, waiter))? else { - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); }; - // 0 is reserved for GROUP_END, which no version defines yet. + // 0 is GROUP_END, where a frame would start. Under object records a record + // precedes every FRAME, and the group's end is the stream's. let Some(size) = length.checked_sub(1) else { - return Poll::Ready(Err(Error::ProtocolViolation)); + if self.records.is_some() { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + self.phase = IngestPhase::GroupEnd; + continue; }; self.phase = IngestPhase::Timing { size: Some(size) }; } + IngestPhase::GroupEnd => { + let end = ready!(reader.poll_varint(waiter))?; + self.phase = IngestPhase::Finished { end }; + } + IngestPhase::Finished { end } => { + let end = *end; + if ready!(reader.poll_has_more(waiter))? { + return Poll::Ready(Err(Error::MalformedTrack)); + } + return Poll::Ready(self.end(Some(end))); + } IngestPhase::Timing { size } => { let size = *size; - let Some(scale) = self.framing.timescale else { + if !self.framing.stamped() { self.phase = IngestPhase::Inflated { size, timestamp: None }; continue; - }; + } // Before lite-07 the timestamp delta doubles as the per-frame sentinel. let Some(zz) = ready!(self.poll_header_varint(reader, size.is_none(), waiter))? else { - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); }; let next: u64 = (self.prev_ts as i128 + crate::coding::varint::unzigzag(zz) as i128) .try_into() .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?; self.prev_ts = next; - let timestamp = Timestamp::new(next, scale) - .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?; + // A scale-less track's is a bare number, which the group checks against its start. + let timestamp = match self.framing.timescale { + Some(scale) => Timestamp::new(next, scale) + .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?, + None => Timestamp::unscaled(next), + }; self.phase = IngestPhase::Inflated { size, timestamp: Some(timestamp), @@ -2192,9 +2237,9 @@ impl FrameIngest { // Only a compressed Track carries it, and only lite-07 can mark one. let inflated = match group.compressed() { true => { - let boundary = size.is_none() && self.framing.timescale.is_none(); + let boundary = size.is_none() && !self.framing.stamped(); let Some(inflated) = ready!(self.poll_header_varint(reader, boundary, waiter))? else { - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); }; Some(inflated) } @@ -2210,9 +2255,9 @@ impl FrameIngest { } IngestPhase::Size { timestamp, inflated } => { let (timestamp, inflated) = (*timestamp, *inflated); - let boundary = self.framing.timescale.is_none() && !group.compressed(); + let boundary = !self.framing.stamped() && !group.compressed(); let Some(size) = ready!(self.poll_header_varint(reader, boundary, waiter))? else { - return Poll::Ready(self.end()); + return Poll::Ready(self.end(None)); }; let header = self.header(group, timestamp, inflated, size)?; self.phase = self.dispatch(group, header)?; @@ -4877,6 +4922,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut bytes, version.into()), version) @@ -4963,6 +5009,7 @@ mod tests { lite::Group { subscribe: 7, key, + previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -5064,27 +5111,39 @@ mod tests { async fn receive_ietf( framing: lite::Framing, body: &[u64], + ) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { + let header = lite::Group { + subscribe: 7, + key: 0, + previous: None, + frame_start: 0, + }; + receive_lite07(framing, true, header, body).await + } + + /// Receive the group `header` opens on a track `framing` describes over a lite-07 + /// session, which negotiated the `ietf` extension when `ietf`, its stream holding `body` + /// after the header. Also returns the cache pool the track charges. + async fn receive_lite07( + framing: lite::Framing, + ietf: bool, + header: lite::Group, + body: &[u64], ) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { use crate::transport::poll::Session as _; let version = Version::Lite07; let mut script = Vec::new(); let mut encoder = crate::coding::Encoder::new(&mut script, version.into()); - lite::Group { - subscribe: 7, - key: 0, - frame_start: 0, - } - .encode(&mut encoder, version) - .unwrap(); + header.encode(&mut encoder, version).unwrap(); for value in body { encoder.varint(*value).unwrap(); } let session = crate::lite::test_transport::ScriptedSession::eof(script); - let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup).offer_ietf(true); + let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup).offer_ietf(ietf); peer_setup .set(lite::Setup { - ietf: true, + ietf, ..Default::default() }) .unwrap(); @@ -5130,6 +5189,108 @@ mod tests { (res, track, pool) } + /// A lite-07 track with no extension, in `timescale`. + fn lite07(timescale: Option) -> lite::Framing { + lite::Framing { + timescale, + ietf: None, + compressed: false, + length_first: true, + } + } + + /// Group `key`'s header on subscription 7, naming `previous` as the group before it. + fn lite07_header(key: u64, previous: Option) -> lite::Group { + lite::Group { + subscribe: 7, + key, + previous, + frame_start: 0, + } + } + + /// GROUP_END finishes the group whole at its End, and a bare FIN closes it with every frame + /// sent but no end: each frame is its `Payload Length`, a timestamp delta, and the payload. + #[kio::test] + async fn group_end_finishes_and_a_bare_fin_closes() { + let x = u64::from(b'x'); + for (body, end) in [(&[2, 0, x, 0, 5][..], Some(5)), (&[2, 0, x][..], None)] { + let (res, track, _) = + receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(0, None), body).await; + res.unwrap(); + let mut group = track.consume().peek_group(0).unwrap(); + assert_eq!( + group.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, + b"x"[..] + ); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_none()); + assert_eq!(group.end(), end, "{body:?}"); + } + } + + /// Anything after GROUP_END, an End the group refuses (at or before its start), or a + /// zero length under object records, where a record would come first, is refused. + #[kio::test] + async fn group_end_refuses_what_cannot_end_a_group() { + let x = u64::from(b'x'); + for (key, body, reason) in [ + (0, &[2, 0, x, 0, 5, 0][..], "a byte after GROUP_END"), + (0, &[2, 0, x, 0, 5, 2, 0, x], "a frame after GROUP_END"), + (5, &[2, 5, x, 0, 5], "an End at the group's start"), + (5, &[2, 5, x, 0, 4], "an End before the group's start"), + (0, &[0], "a stream ending inside GROUP_END"), + ] { + let (res, track, _) = + receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(key, None), body).await; + assert!(res.is_err(), "accepted {reason}"); + if let Some(mut group) = track.consume().peek_group(key) { + while let Some(Ok(Some(_))) = group.read_frame().now_or_never() {} + assert!(group.end().is_none(), "{reason}: the group finished"); + } + } + let (res, ..) = receive_ietf(draft18(None), &[0, 0]).await; + assert!(res.is_err(), "accepted GROUP_END under object records"); + } + + /// A lite-07 FRAME on a scale-less track carries its timestamp, its group's start as a + /// bare number; any other value is a TIMESTAMP_MISMATCH. + #[kio::test] + async fn a_scale_less_frame_carries_its_groups_start() { + let x = u64::from(b'x'); + let (res, track, _) = receive_lite07(lite07(None), false, lite07_header(9, None), &[2, 18, x, 2, 0, x]).await; + res.unwrap(); + let mut group = track.consume().peek_group(9).unwrap(); + for _ in 0..2 { + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.timestamp, Timestamp::unscaled(9)); + } + + // 10, then 9 and 10 again. + for body in [&[2, 20, x][..], &[2, 18, x, 2, 2, x]] { + let (res, ..) = receive_lite07(lite07(None), false, lite07_header(9, None), body).await; + assert!(matches!(res, Err(Error::TimestampMismatch)), "{body:?}: {res:?}"); + } + } + + /// GROUP's Previous Start passes over the starts between, which the copy records skipped + /// as a SUBSCRIBE_SKIP would; one at or above the group's own start is malformed. + #[kio::test] + async fn a_groups_previous_start_skips_the_starts_between() { + let x = u64::from(b'x'); + let body = [2, 18, x]; + let (res, track, _) = receive_lite07(lite07(None), false, lite07_header(9, Some(4)), &body).await; + res.unwrap(); + let consumer = track.subscribe(None); + assert!(consumer.is_skipped(5..9)); + assert!(!consumer.is_skipped(4..5), "the previous group is not skipped"); + + for previous in [9, 10] { + let (res, track, _) = receive_lite07(lite07(None), false, lite07_header(9, Some(previous)), &body).await; + assert!(matches!(res, Err(Error::MalformedTrack)), "{previous}: {res:?}"); + assert!(track.consume().peek_group(9).is_none(), "{previous}: opened the group"); + } + } + /// Object records: `(Skip << 1) | END`, the properties block's length, then the frame. #[kio::test] async fn ietf_records_frame_a_group() { @@ -5260,6 +5421,7 @@ mod tests { lite::Group { subscribe: 7, key: 5, + previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -5422,6 +5584,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -5492,6 +5655,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -5608,6 +5772,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -5759,6 +5924,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -5848,6 +6014,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -5928,6 +6095,7 @@ mod tests { lite::Group { subscribe: 7, key: 3, + previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -7546,6 +7714,7 @@ mod tests { lite::Group { subscribe: 0, key, + previous: None, frame_start: 0, } .encode(&mut w, version) @@ -7617,6 +7786,7 @@ mod tests { let header = |key| lite::Group { subscribe: 0, key, + previous: None, frame_start: 0, }; let mut entry = TrackEntry::new(None, Default::default()); @@ -7660,7 +7830,7 @@ mod tests { let Ok(Open::Group(opened)) = entry.unpark(kept) else { panic!("the kept group"); }; - opened.group.finish().unwrap(); + opened.group.close().unwrap(); let _track = track.finish().unwrap(); // Only the kept group reaches the subscriber: the withdrawn one ended, so nothing // waits on it. @@ -10840,6 +11010,7 @@ mod tests { lite::Group { subscribe: 7, key: 0, + previous: None, frame_start: u64::MAX - 1, } .encode(&mut encoder, version) @@ -10902,6 +11073,7 @@ mod tests { lite::Group { subscribe: 7, key: 0, + previous: None, frame_start: start, } .encode(&mut encoder, version) @@ -14428,9 +14600,9 @@ impl kio::Task for FetchServeRun { unreachable!() }; match res { - Ok(()) => { - let producer = producer; - let _ = producer.finish(); + // Whole at a GROUP_END's end, else closed; an end the group refuses aborts it. + Ok(end) => { + let _ = producer.end(end); } Err(err) => { let _ = producer.abort(err); diff --git a/rs/moq-net/src/lite/subscriber/fills.rs b/rs/moq-net/src/lite/subscriber/fills.rs index c924c3f6909..e7336468c12 100644 --- a/rs/moq-net/src/lite/subscriber/fills.rs +++ b/rs/moq-net/src/lite/subscriber/fills.rs @@ -253,6 +253,20 @@ impl RangeFills { read: bool, waiter: &kio::Waiter, ) -> Result { + // What the copy records skipped is never produced, such as the starts a lite-07 GROUP's + // Previous Start passes over, which no SUBSCRIBE_SKIP names: a fill owing one is + // answered as a SUBSCRIBE_SKIP answers it, rather than asked or recovered again. + let mut skipped = Vec::new(); + for fill in &self.held { + if let Some(run) = fill.next_run() { + skipped.extend(serving.skipped(run).iter().cloned()); + } + } + for groups in skipped { + for gap in self.refused.gaps(&groups).collect::>() { + self.refused.insert(gap, Refusal::dropped(StreamError::NotFound)); + } + } // The groups the subscription already accounted for, which it never sends again, are // recovered on their own, once. if let Some(accounted) = accounted { diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 5f014d8bb9c..57fe3705639 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -132,7 +132,8 @@ impl From for crate::track::Info { /// `ietf` extension, TRACK_PROPERTIES. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub(crate) struct Framing { - /// The units of every frame Timestamp on the wire, or `None` when frames carry none. + /// The units of every frame Timestamp on the wire, or `None` when frames carry none or, + /// on lite-07, a scale-less track's bare number (see [`Self::stamped`]). pub timescale: Option, /// The draft the track's moq-transport publisher spoke, which serialized its objects' /// properties, or `None` for a moq-lite one, which carries no moq-transport state. @@ -155,6 +156,13 @@ impl Framing { length_first: version.has_length_first(), } } + + /// Whether every FRAME carries a timestamp: lite-05/06 always declare a timescale, and + /// lite-07, which leads with the length, stamps a scale-less track's frames with their + /// group's start. + pub fn stamped(&self) -> bool { + self.timescale.is_some() || self.length_first + } } impl<'a> Message<'a> for TrackInfo { diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 8ca07868443..2fd8215404e 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -298,6 +298,17 @@ impl Version { ) } + /// Whether GROUP carries the previous group's `Previous Start`, and a Group or Fetch Stream + /// ends a finished group with GROUP_END and a closed one with a bare FIN. A publisher then + /// closes an expired group's stream rather than resetting it. Added in lite-07; earlier + /// versions end every group with a bare FIN. + pub(crate) fn has_group_end(self) -> bool { + !matches!( + self, + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 + ) + } + /// Whether a Group Stream reset with YIELDED pauses its group, which a later stream /// continues. Added in lite-07; an earlier publisher out of stream credit gives the reset /// group up. diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index e36ae7a2362..1590d79868a 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2261,15 +2261,25 @@ impl Producer { /// A finished group's own end bounds how long it stays fresh, so the last group of a /// paused or finished track ages out without a successor (see /// [`track::Info::max_age`]). An `end` at or before the group's start is - /// [`Error::TimestampMismatch`]. Fails with the abort error if the group was already - /// aborted. + /// [`Error::TimestampMismatch`], which aborts the group. Fails with the abort error if the + /// group was already aborted. pub fn finish(self, end: u64) -> Result { - if end <= self.start { - return Err(Error::TimestampMismatch); + if let Err(err) = self.check_end(end) { + let _ = self.handle.close_aborted(err.clone()); + return Err(err); } self.end(Some(end)) } + /// Whether [`Self::finish`] takes `end`: [`Error::TimestampMismatch`] at or before the + /// group's start. + pub(crate) fn check_end(&self, end: u64) -> Result<()> { + match end <= self.start { + true => Err(Error::TimestampMismatch), + false => Ok(()), + } + } + /// End the group without saying where it ends, returning the [`Finished`] group: every /// frame written still reaches its readers, but they can't tell the group is whole. /// @@ -4115,6 +4125,13 @@ impl Consumer { self.poll_expiry(waiter, true) } + /// Whether the subscription this group was handed out under gave up on it as stale, as + /// [`Self::poll_expired`] or a read failing with [`Error::Old`] found. + #[cfg(feature = "async")] + pub(crate) fn is_expired(&self) -> bool { + self.expired + } + /// Apply the drift budget to a read that found nothing and is about to park, failing /// it with [`Error::Old`] once the budget gives up. /// diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 8819bc3a315..a0495ea2989 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -941,6 +941,19 @@ impl Subscriber { track::first_open(run, |key| serving.hole_end(key, false)).is_none() } + /// The start of the group before `start` the serving copy knows; see + /// [`track::Subscriber::previous_start`]. + pub(super) fn previous_start(&self, start: u64) -> Option { + let serving = self.reader().copies.last().map(|copy| copy.track.clone())?; + serving.previous_start(start) + } + + /// Whether the serving copy holds the group at `key`; see [`track::Subscriber::holds`]. + pub(super) fn holds(&self, key: u64) -> bool { + let serving = self.reader().copies.last().map(|copy| copy.track.clone()); + serving.is_some_and(|serving| serving.holds(key)) + } + /// The groups the reader's ranges name from `from` on; see /// [`track::Subscriber::runs_in_range`]. pub(super) fn runs(&self, from: u64) -> Vec> { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 1e3971afbce..8ea3dd34407 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1314,6 +1314,25 @@ impl TrackState { gone.then_some(run.end) } + /// The start of the group before `start`, as a lite-07 GROUP's Previous Start names it: + /// just below the run of starts the publisher declared skipped directly under `start`, or + /// the group just below it, and `None` when neither says. A run skipped down to 0 has no + /// group below it. See [`Subscriber::previous_start`]. + fn previous_start(&self, start: u64) -> Option { + let below = start.checked_sub(1)?; + match self.drops.get_key_value(&below) { + Some((run, hole)) if *hole == Hole::Skip => run.start.checked_sub(1), + _ => self.lookup.contains_key(&below).then_some(below), + } + } + + /// Whether the live feed's copy of the group at `key` is cached and still serves it. + fn holds_group(&self, key: u64) -> bool { + self.lookup + .get(&key) + .is_some_and(|slot| slot.visible && slot.serves_end()) + } + /// Skip what of `groups` holds no cached group, replacing any drop of it, final or stale: /// "never produced" is the most authoritative verdict on a key. A reader a drop /// already ended stays ended, and a relay forwards the skip over the drop it reported. @@ -4582,6 +4601,22 @@ impl Producer { cached } + /// The parts of `groups` recorded skipped, never to be produced: a cost in the skipped + /// runs it overlaps, not its length. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn skipped(&self, groups: ops::Range) -> RangeSet { + if groups.is_empty() { + return RangeSet::new(); + } + let state = self.state.read(); + state + .drops + .overlapping(&groups) + .filter(|(_, hole)| matches!(hole, Hole::Skip)) + .map(|(run, _)| run.start.max(groups.start)..run.end.min(groups.end)) + .collect() + } + /// Forget every run held as stale: a new upstream subscription judges them afresh, and /// may deliver them, so they are unknown again, and a reader that wants one fills it. /// Returns the runs forgotten; a group that arrived since its stale drop replaced it, so @@ -6472,6 +6507,23 @@ impl Consumer { self.with_state(|state| state?.read().hole_end(key, dropped)) } + /// The start of the group before `start`; see [`Subscriber::previous_start`]. + pub(super) fn previous_start(&self, start: u64) -> Option { + if let Some(serving) = self.serving() { + return serving.previous_start(start); + } + self.with_state(|state| state?.read().previous_start(start)) + } + + /// Whether the cache holds the group at `key`; see [`Subscriber::holds`]. + pub(super) fn holds(&self, key: u64) -> bool { + if let Some(serving) = self.serving() { + return serving.holds(key); + } + self.with_state(|state| state.map(|state| state.read().holds_group(key))) + .unwrap_or(false) + } + /// The keys of `span` the cache holds, lowest first. #[cfg(feature = "async")] pub(crate) fn cached_groups(&self, span: ops::Range) -> Vec { @@ -10131,6 +10183,27 @@ impl Subscriber { } } + /// The start of the group before `start` on the track, as a lite-07 GROUP's Previous Start + /// names it: just below the run of starts the publisher declared skipped directly under + /// `start`, else the group just below it, else `None`. No group starts between the two. + /// A copy knows only the skips its wire forwarded. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn previous_start(&self, start: u64) -> Option { + match &self.inner { + Inner::Plain(cursor) => cursor.state.read().previous_start(start), + Inner::Resume(resume, _) => resume.previous_start(start), + } + } + + /// Whether the track's cache holds the live feed's group at `key`, still serving it. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn holds(&self, key: u64) -> bool { + match &self.inner { + Inner::Plain(cursor) => cursor.state.read().holds_group(key), + Inner::Resume(resume, _) => resume.holds(key), + } + } + /// The groups from `from` up to the exclusive `end` that this subscriber's ranges and /// [`Self::with_range`] bounds name, lowest first: the groups it is owed, without the /// ones between disjoint ranges. diff --git a/rs/moq-net/src/recv.rs b/rs/moq-net/src/recv.rs index a475e6f77c2..22b15eb2c4b 100644 --- a/rs/moq-net/src/recv.rs +++ b/rs/moq-net/src/recv.rs @@ -97,13 +97,39 @@ impl Group { self.writer.take().expect("group owned until consumed") } - /// Finish receiving without running cancellation cleanup. - pub fn finish(mut self) -> Result<(), Error> { + /// Finish receiving a group closed without saying where it ends, as a bare FIN does, + /// without running cancellation cleanup. + pub fn close(mut self) -> Result<(), Error> { self.writer.take().expect("group owned until consumed").close()?; self.armed = false; Ok(()) } + /// Finish receiving a whole group that ends at `end`, as GROUP_END says, without running + /// cancellation cleanup. An `end` the group refuses (see [`group::Producer::finish`]) is + /// [`Error::MalformedTrack`], which aborts the group; one already aborted stays so. + pub fn finish(mut self, end: u64) -> Result<(), Error> { + if self.check_end(end).is_err() { + let _ = self.abort(Error::MalformedTrack); + return Err(Error::MalformedTrack); + } + let _ = self.writer.take().expect("group owned until consumed").finish(end); + self.armed = false; + Ok(()) + } + + /// Finish receiving as the stream ended: whole at a GROUP_END's `end`, else closed. Only + /// an `end` the group refuses fails (see [`Self::finish`]). + pub fn end(self, end: Option) -> Result<(), Error> { + match end { + Some(end) => self.finish(end), + None => { + let _ = self.close(); + Ok(()) + } + } + } + /// Abort with the receive error instead of cancellation. pub fn abort(mut self, err: Error) -> Result<(), Error> { self.armed = false; diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index e219b6f9ff8..a8536bb97c1 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -271,6 +271,7 @@ fn lite_group(version: lite::Version, frames: impl IntoIterator moq_net::origin::Producer { + let (producer, driver) = + moq_net::origin::Producer::new(moq_net::origin::Config::new(std::num::NonZeroU64::new(hop).unwrap())); + support::harness::spawn(driver); + producer.with_proxy(true) +} + +/// Group 0 finished at 500ms and group 1000 closed, on a live track that keeps both. +fn publish(origin: &moq_net::origin::Producer) -> (moq_net::origin::Route, moq_net::track::Producer) { + let broadcast = origin.route("room", moq_net::origin::RouteOptions::hidden()).unwrap(); + let track = broadcast + .broadcast() + .create_track( + "video", + Info::default().with_timescale(Timescale::MILLI).with_max_age(None), + ) + .unwrap(); + broadcast.announce().unwrap(); + for (start, end) in [(0, Some(500)), (1000, None)] { + let mut group = track.append_group(start).unwrap(); + group + .write_frame(Timestamp::from_millis(start).unwrap(), b"x".as_slice()) + .unwrap(); + match end { + Some(end) => group.finish(end).unwrap(), + None => group.close().unwrap(), + }; + } + (broadcast, track) +} + +/// Read `group` to its end, returning where it says it ends. +async fn read_to_end(mut group: moq_net::group::Consumer) -> Option { + while kio::clock::timeout(TIMEOUT, group.read_frame()) + .await + .expect("read timeout") + .unwrap() + .is_some() + {} + group.end() +} + +async fn round(version: &str) -> (Vec<(u64, Option)>, Option) { + let publisher = produce_origin(1); + let (_broadcast, _track) = publish(&publisher); + let client = produce_origin(2); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(client.clone()); + let _pair = connect_mock(options).await; + + let remote = kio::clock::timeout(TIMEOUT, client.consume().follow("room", None).unwrap().available()) + .await + .expect("resolve timeout") + .expect("broadcast resolves") + .unwrap(); + let mut subscriber = kio::clock::timeout( + TIMEOUT, + remote.track("video").unwrap().subscribe( + Subscription::default() + .with_delay(Delay::default().with_max(None)) + .with_ranges([Range::oldest()]), + ), + ) + .await + .expect("subscribe timeout") + .unwrap(); + let mut subscribed = Vec::new(); + while subscribed.len() < 2 { + let group = kio::clock::timeout(TIMEOUT, subscriber.recv_group()) + .await + .expect("group timeout") + .unwrap() + .expect("a group"); + let start = group.start; + subscribed.push((start, read_to_end(group).await)); + } + + // A second reader fetching group 0 from a hop that never held it. + let fetcher = produce_origin(3); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(fetcher.clone()); + let fetch_pair = connect_mock(options).await; + let remote = kio::clock::timeout(TIMEOUT, fetcher.consume().follow("room", None).unwrap().available()) + .await + .expect("resolve timeout") + .expect("broadcast resolves") + .unwrap(); + let fetched = kio::clock::timeout(TIMEOUT, remote.track("video").unwrap().fetch_group(0, None)) + .await + .expect("fetch timeout") + .unwrap(); + let fetched = read_to_end(fetched).await; + // The bidi stream type a FETCH opens with. + const FETCH: u8 = 3; + assert!( + fetch_pair.client_transport.bidi_types().contains(&FETCH), + "{version}: no FETCH" + ); + (subscribed, fetched) +} + +#[kio::test] +async fn a_finished_group_arrives_with_its_end() { + for version in VERSIONS { + let (subscribed, fetched) = round(version).await; + let whole = match *version { + "moq-lite-07-wip" => Some(500), + _ => None, + }; + assert_eq!(subscribed, [(0, whole), (1000, None)], "{version}: subscribed"); + assert_eq!(fetched, whole, "{version}: fetched"); + } +} diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index bc102f00049..32cb7bf5b40 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -37,6 +37,7 @@ mod finished_broadcast_mock; mod finite_relay; mod flights; mod goaway; +mod group_end; mod group_order; mod half_read_frame; mod history_groups; diff --git a/rs/moq-net/tests/integration/partial_group.rs b/rs/moq-net/tests/integration/partial_group.rs index 880531f9c43..20e7d04cb72 100644 --- a/rs/moq-net/tests/integration/partial_group.rs +++ b/rs/moq-net/tests/integration/partial_group.rs @@ -1,8 +1,9 @@ #![cfg(feature = "async")] //! A group the subscription's max delay gives up on before the publisher finishes it never -//! reaches the next hop as finished. The served stream resets with `Old`, so a relay does -//! not cache the frames it already has as the whole group. +//! reaches the next hop as finished, so a relay does not cache the frames it already has as +//! the whole group. Before lite-07 the served stream resets with `Old`; lite-07 closes it +//! without a GROUP_END, which the next hop keeps as a closed group with no end. use crate::support; use moq_net::track::Delay; @@ -29,10 +30,14 @@ fn produce_origin(hop: u64) -> moq_net::origin::Producer { producer.with_proxy(true) } +/// How a reader ended a group: the read's outcome, and the end the group was finished at. +type Ended = (Result, moq_net::Error>, Option); + /// Publish an unfinished group 0 that stalls past the budget after its only frame, and /// return how a reader without a budget of its own ends group 0 at the downstream hop: -/// `None` when that hop holds no copy of it, otherwise the read's outcome. -async fn round(version: &str) -> Option, moq_net::Error>> { +/// `None` when that hop holds no copy of it. +async fn round(version: &str) -> Option { + let closes = version == "moq-lite-07-wip"; let publisher = produce_origin(1); let downstream = produce_origin(2); let _pair = peer(version.parse::().unwrap(), &publisher, &downstream).await; @@ -85,7 +90,14 @@ async fn round(version: &str) -> Option, moq_net::Error>> { let tail = kio::clock::timeout(TIMEOUT, group.read_frame()) .await .expect("the stalled group never gave up"); - assert!(tail.is_err(), "{version}: the live reader saw a clean end: {tail:?}"); + match closes { + true => assert!( + matches!(tail, Ok(None)) && group.end().is_none(), + "{version}: the live reader saw {tail:?} ending at {:?}", + group.end() + ), + false => assert!(tail.is_err(), "{version}: the live reader saw a clean end: {tail:?}"), + } kio::clock::sleep(Duration::from_millis(100)).await; // A reader with no budget to apply sees only what the downstream hop cached. @@ -122,16 +134,22 @@ async fn round(version: &str) -> Option, moq_net::Error>> { } }; stalled.abort(moq_net::Error::Cancel).unwrap(); - Some(end) + Some((end, first.end())) } #[kio::test] async fn a_stalled_group_is_never_cached_downstream_as_finished() { let mut failures = Vec::new(); for version in VERSIONS { - let end = round(version).await; - if let Some(Ok(_)) = end { - failures.push(format!("{version}: the downstream hop finished group 0: {end:?}")); + let ended = round(version).await; + // Lite-07 says a group is whole with its end, which a closed one never has; earlier + // versions can't tell a closed group from a whole one, so only an error is safe. + let finished = matches!( + (&ended, version == &"moq-lite-07-wip"), + (Some((_, Some(_))), _) | (Some((Ok(_), None)), false) + ); + if finished { + failures.push(format!("{version}: the downstream hop finished group 0: {ended:?}")); } } assert!(failures.is_empty(), "{failures:#?}"); From 199d6101d57813e9146426214a7381389b39fff5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 08:46:36 -0800 Subject: [PATCH 15/26] feat(js/net)!: lite-07 GROUP carries Previous Start and groups end with GROUP_END The JS counterpart of the Rust change. - GROUP encodes and decodes Previous Start plus one on lite-07, 0 when unknown. The subscriber applies the starts it passes over as a skip, and refuses a previous start at or past the group's own as a malformed track. - A Group Stream reads a Payload Length of 0 as GROUP_END, then the group's exclusive End, then the FIN; anything after it, or an End at or before the group's start, is malformed. A bare FIN closes the group. - `Group.Producer.finish(end?)` finishes a group whole at `end`, or closes it without one, and `Group.Consumer.end` reads it back. A finished group's stream and a FETCH that reaches its end write GROUP_END. - A scale-less lite-07 track stamps each frame with its group's start, and the subscriber refuses any other value with TIMESTAMP_MISMATCH. - A lite-07 stream whose group expires after it opened is closed at the next frame boundary rather than reset, and no drop names the group. - The publisher holds a skip back for the GROUP of the cached group just above it, and sends it ahead of that group's drop, or joined to its skip, if the group is given up instead. A drop of a group whose stream opened goes out after a skip of what its GROUP passed over. Tests cover each, and the parked-expiry and copy-fill tests now tell an eviction from a stale group, which lite-07 closes. Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 3 +- js/net/src/group.ts | 27 ++++- js/net/src/integers.test.ts | 6 +- js/net/src/internal.ts | 18 +++ js/net/src/lite/copy_fill.test.ts | 6 +- js/net/src/lite/drop_record.test.ts | 9 +- js/net/src/lite/group.test.ts | 83 ++++++++++--- js/net/src/lite/group.ts | 89 +++++++++++--- js/net/src/lite/publisher.test.ts | 113 +++++++++++++++--- js/net/src/lite/publisher.ts | 175 +++++++++++++++++++++++----- js/net/src/lite/subscriber.test.ts | 19 ++- js/net/src/lite/subscriber.ts | 66 +++++++---- js/net/src/lite/version.ts | 24 +++- js/net/src/parked-expiry.test.ts | 4 +- js/net/src/track.ts | 10 ++ js/net/src/untimed.test.ts | 21 +++- test/interop/lite-varint.ts | 3 + 17 files changed, 559 insertions(+), 117 deletions(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index a4c370b6c23..10b5e8ede52 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -399,6 +399,7 @@ export namespace Group { close(): void; get closed(): Signals.GetPromise; get done(): boolean; + get end(): bigint | undefined; get frameCount(): number; get isClosed(): boolean; nextFrame(): Promise; @@ -434,7 +435,7 @@ export namespace Group { get closed(): Signals.GetPromise; consume(): Group.Consumer; createFrame(info: Frame.Info): Frame.Producer; - finish(): Group.Finished; + finish(end?: bigint): Group.Finished; get isClosed(): boolean; readonly sequence: bigint; writeFrame(frame: Group.Frame): void; diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 06707c26530..dc0a754330a 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -94,6 +94,9 @@ class GroupState { readonly sequence: bigint; frames = new Signal(new Queue()); closed = new Once(); + // Where the group ends, in its track's timescale, once its producer finished it whole: set + // before a clean `closed`, and undefined when it only closed. + end?: bigint; total = new Signal(0); // The total number of frames in the group thus far // Absolute sequence of the frame at the front of `frames`, advanced by a read: the @@ -463,6 +466,7 @@ export class Producer { if (dst.closed.peek() !== undefined) return makeConsumer(dst); const closed = this.#state.closed.peek(); if (closed !== undefined) { + dst.end = this.#state.end; dst.closed.set(closed); return makeConsumer(dst); } @@ -702,8 +706,15 @@ export class Producer { /** * Marks the group complete, returning it as {@link Finished}: no more frames will be written. * Idempotent. + * + * `end`, in the track's timescale, says the group is whole and ends there, as the Rust + * `group::Producer::finish` does; without it the group only closed, as the Rust `close` does: + * every frame written reaches its readers, but they can't tell the group is whole. An `end` at + * or before the group's start throws {@link TimestampMismatch}. */ - finish(): Finished { + finish(end?: bigint): Finished { + if (end !== undefined && end <= this.sequence) throw new TimestampMismatch(); + if (this.#state.closed.peek() === undefined) this.#state.end = end; this.#end(null); return this; } @@ -754,7 +765,10 @@ export class Producer { const outcome = this.#state.closed.peek(); if (outcome === undefined) return; for (const mirror of this.#mirrors?.keys() ?? []) { - if (mirror.closed.peek() === undefined) mirror.closed.set(outcome); + if (mirror.closed.peek() === undefined) { + if (outcome === null) mirror.end = this.#state.end; + mirror.closed.set(outcome); + } this.#unmirror(mirror); } } @@ -991,6 +1005,14 @@ export class Consumer { return this.#arrived ?? this.#state.arrived; } + /** + * Where the group ends in its track's timescale, once its producer finished it whole with + * {@link Producer.finish}'s `end`: undefined while it is open, or when it only closed. + */ + get end(): bigint | undefined { + return this.#state.closed.peek() === null ? this.#state.end : undefined; + } + /** * Settles when this consumer reaches a terminal state: `null` after a clean close has no * unread or in-flight frames, or the terminal {@link Error}. @@ -1098,6 +1120,7 @@ export class Consumer { group.#expiry = expiry; }; hooks.groupFailed = (group) => group.#failed(); + hooks.groupExpired = (group) => group.#expiry?.expired() === true; hooks.recoverGroup = (group, recover) => { group.#recover = recover; // A front serving another front attaches its recovery after the inner one handed the diff --git a/js/net/src/integers.test.ts b/js/net/src/integers.test.ts index 9cc09f4476f..55d8ad55e9d 100644 --- a/js/net/src/integers.test.ts +++ b/js/net/src/integers.test.ts @@ -148,9 +148,9 @@ for (const version of [Lite.DRAFT_06, Lite.DRAFT_07]) { await Writer.collect(version, (w) => LiteMessage.encode(w, (w) => w.write(body))), version, ); - await expect(LiteGroup.decode(await framed(fields(version, 0, 0, UNSAFE)), version)).rejects.toThrow( - RangeError, - ); + // Lite-07 carries the Previous Start ahead of the Frame Start. + const group = version === Lite.DRAFT_07 ? fields(version, 0, 0, 0, UNSAFE) : fields(version, 0, 0, UNSAFE); + await expect(LiteGroup.decode(await framed(group), version)).rejects.toThrow(RangeError); if (version === Lite.DRAFT_07) await expect(SubscribeStart.decode(await framed(fields(version, 1, UNSAFE)), version)).rejects.toThrow( RangeError, diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 930b228484d..19fbc1d8a19 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -816,6 +816,13 @@ export const hooks: { cachedGroup: (subscriber: Subscriber, sequence: bigint, from?: number) => GroupConsumer | undefined; /** Whether {@link cachedGroup} would find the group, without making a read handle. */ holdsGroup: (subscriber: Subscriber, sequence: bigint) => boolean; + /** + * The start of the group before `start` on the subscriber's track, as a lite-07 GROUP's + * Previous Start names it: just below the run of starts declared skipped directly under + * `start`, else `start - 1` when a group starts there, else undefined. Mirrors the Rust + * crate-private `track::Subscriber::previous_start`. + */ + previousStart: (subscriber: Subscriber, start: bigint) => bigint | undefined; /** The error the subscriber's track gave `sequence` up with, if it did, and what changes it. */ givenUp: (subscriber: Subscriber, sequence: bigint) => { error?: Error; changed: Getter[] }; /** @@ -929,6 +936,11 @@ export const hooks: { expireGroup: (group: GroupConsumer, expiry: Expiry) => void; /** The failure that ends a group's reader, as its `closed` would settle, without building that handle. */ groupFailed: (group: GroupConsumer) => Error | undefined; + /** + * Whether the subscription's budget gave the group up, rather than its copy failing or the + * cache evicting it. Mirrors the Rust crate-private `group::Consumer::is_expired`. + */ + groupExpired: (group: GroupConsumer) => boolean; /** * Carry a group across its logical track's route changes. Attached before the group is handed * out, so its `closed` never settles on a failure the recovery continues past. @@ -1155,6 +1167,9 @@ export const hooks: { holdsGroup: () => { throw new Error("track.ts not loaded"); }, + previousStart: () => { + throw new Error("track.ts not loaded"); + }, staleHeld: () => { throw new Error("track.ts not loaded"); }, @@ -1302,6 +1317,9 @@ export const hooks: { groupFailed: () => { throw new Error("group.ts not loaded"); }, + groupExpired: () => { + throw new Error("group.ts not loaded"); + }, recoverGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/copy_fill.test.ts b/js/net/src/lite/copy_fill.test.ts index 38dede13033..c92468752f7 100644 --- a/js/net/src/lite/copy_fill.test.ts +++ b/js/net/src/lite/copy_fill.test.ts @@ -348,7 +348,9 @@ test("copy fill: a filled group nobody holds any more stops downloading", async // The history reader leaves mid-group, and the live one reads past it: nobody holds the // group any more, so the copy cancels its FETCH and aborts the truncated group rather - // than keep downloading it. + // than keep downloading it. The publisher may close the group's stream first, once the + // narrower budget left it stale, which leaves the copy a closed group: either way the + // source loses its last reader. group?.close(); history.close(); write(track.createGroup(2n), 2n, "live"); @@ -357,7 +359,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async timeout( Duration.millis(2000), (async () => { - while (hooks.holdsGroup(reader, 0n)) await sleep(Duration.millis(10)); + while (source.demand().wanted.peek()) await sleep(Duration.millis(10)); })(), ), ); diff --git a/js/net/src/lite/drop_record.test.ts b/js/net/src/lite/drop_record.test.ts index 25ff74d2001..5fb9ebc0c08 100644 --- a/js/net/src/lite/drop_record.test.ts +++ b/js/net/src/lite/drop_record.test.ts @@ -559,12 +559,9 @@ test("a run of billions of sequences is settled by each reader in one step, drop ["group", 1n + 2n * BILLIONS], ]); } - for (const hop of ["up", "down"] as const) { - expect(wire.on(hop)).toEqual([ - ["drop", 1n, 1n + BILLIONS, StreamCode.Cancel], - ["skip", 1n + BILLIONS, 1n + 2n * BILLIONS, undefined], - ]); - } + // The skip rides the GROUP above it, whose Previous Start passes over the run. + for (const hop of ["up", "down"] as const) + expect(wire.on(hop)).toEqual([["drop", 1n, 1n + BILLIONS, StreamCode.Cancel]]); expect(chained.fetches()).toEqual(before); for (const reader of [narrow, wide]) reader.close(); diff --git a/js/net/src/lite/group.test.ts b/js/net/src/lite/group.test.ts index 3edd11d2aac..661cf95e6e4 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -1,12 +1,12 @@ import { expect, test } from "bun:test"; -import { ProtocolViolation, StreamCode, StreamError } from "../error.ts"; +import { ProtocolViolation, StreamCode, StreamError, TimestampMismatch } from "../error.ts"; import { Producer } from "../group.ts"; import { hooks } from "../internal.ts"; -import { concat, encodeVarint, Reader } from "../stream.ts"; +import { concat, encodeVarint, Reader, Writer } from "../stream.ts"; import { Timestamp } from "../time.ts"; import { SEGMENT_BYTES } from "../util/limits.ts"; import * as Varint from "../varint.ts"; -import { frameDecoder, readFrames } from "./group.ts"; +import { frameDecoder, Group, readFrames, type WireFrame } from "./group.ts"; import { frameHeader } from "./publisher.ts"; import { hasLengthFirst, Version } from "./version.ts"; @@ -137,31 +137,84 @@ test.each([Version.DRAFT_06, Version.DRAFT_07])("a FRAME round-trips on %s", asy // A compressed track's inflated size follows the timestamp delta, and the size still leads. const compressed = concat([frameHeader(version, 7n, 9, 2, lengthFirst), new Uint8Array([5, 6])]); - const decoded = await streamOf([compressed], version).decode( + const decoded = (await streamOf([compressed], version).decode( frameDecoder({ scale: SCALE, compress: true, lengthFirst }), - ); + )) as WireFrame; expect(decoded.size).toBe(2); expect(decoded.inflated).toBe(9); expect(decoded.timestamp?.value).toBe(7); expect(decoded.payload).toEqual(new Uint8Array([5, 6])); }); -// A lite-07 Payload Length of 0 is reserved for GROUP_END, which no version defines yet. A malformed -// FRAME ends only its stream, so it is a stream error rather than a session's protocol violation. -test("a lite-07 FRAME with a Payload Length of 0 is malformed", async () => { - const producer = new Producer(0n); - const bytes = concat([encodeVarint(0, Version.DRAFT_07), encodeVarint(0, Version.DRAFT_07)]); - const err = await readFrames(streamOf([bytes], Version.DRAFT_07), producer, { - scale: SCALE, - lengthFirst: true, - }).then( - () => undefined, +// Lite-07 varints, as a Group Stream after its header carries them. +function lite07(...values: (number | bigint)[]): Uint8Array { + return concat(values.map((value) => encodeVarint(value, Version.DRAFT_07))); +} + +// What reading `bytes` as group `start`'s lite-07 frames resolves with, or the error it throws. +async function readLite07(bytes: Uint8Array, start = 0n, scale = SCALE): Promise { + const producer = new Producer(start); + return readFrames(streamOf([bytes], Version.DRAFT_07), producer, { scale, lengthFirst: true }).catch( (err: unknown) => err, ); +} + +// A lite-07 GROUP_END, a Payload Length of 0 then the End, says where a whole group ends; a stream +// ending without one only closes it. +test("a lite-07 GROUP_END says where the group ends", async () => { + const frame = [2, 0, 7]; + expect(await readLite07(lite07(...frame, 0, 500))).toBe(500n); + expect(await readLite07(lite07(...frame))).toBeUndefined(); +}); + +// An End at or before the group's start, or anything after GROUP_END, is malformed. A malformed +// FRAME ends only its stream, so it is a stream error rather than a session's protocol violation. +test.each([ + ["an End at the group's start", lite07(0, 5), 5n], + ["an End before the group's start", lite07(0, 4), 5n], + ["a byte after GROUP_END", lite07(0, 9, 0), 5n], + ["a frame after GROUP_END", lite07(0, 9, 2, 0, 7), 5n], +])("a lite-07 GROUP_END with %s is malformed", async (_, bytes, start) => { + const err = await readLite07(bytes, start); expect(err).toBeInstanceOf(StreamError); expect((err as StreamError).code).toBe(StreamCode.MalformedTrack); }); +// A lite-07 FRAME on a scale-less track carries its timestamp, its group's start as a bare number; +// any other value is a TIMESTAMP_MISMATCH. The frame keeps the group's key as its time. +test("a scale-less lite-07 FRAME carries its group's start", async () => { + const producer = new Producer(9n); + const consumer = producer.consume(); + await readFrames(streamOf([lite07(2, 18, 7, 2, 0, 8)], Version.DRAFT_07), producer, { + scale: 0, + lengthFirst: true, + }); + for (const payload of [7, 8]) { + const frame = await consumer.readFrame(); + expect(frame?.payload).toEqual(new Uint8Array([payload])); + expect(frame?.timestamp).toEqual(Timestamp.unscaled(9n)); + } + for (const bytes of [lite07(2, 20, 7), lite07(2, 18, 7, 2, 2, 8)]) + expect(await readLite07(bytes, 9n, 0)).toBeInstanceOf(TimestampMismatch); +}); + +// GROUP carries the previous group's start plus one on lite-07, 0 when unknown, and passes over the +// starts strictly between; earlier versions carry nothing. +test("a lite-07 GROUP carries its Previous Start plus one", async () => { + const encode = (previous: bigint | undefined, version: Version) => + Writer.collect(version, (w) => new Group({ subscribe: 1n, sequence: 7n, previous }).encode(w, version)); + expect(Array.from(await encode(4n, Version.DRAFT_07))).toEqual([4, 1, 7, 5, 0]); + expect(Array.from(await encode(undefined, Version.DRAFT_07))).toEqual([4, 1, 7, 0, 0]); + expect(Array.from(await encode(4n, Version.DRAFT_06))).toEqual([3, 1, 7, 0]); + + const decode = (bytes: number[], version: Version) => + Group.decode(streamOf([new Uint8Array(bytes)], version), version); + const group = await decode([4, 1, 7, 5, 0], Version.DRAFT_07); + expect([group.previous, group.passedOver()]).toEqual([4n, { start: 5n, end: 7n }]); + expect((await decode([4, 1, 7, 0, 0], Version.DRAFT_07)).passedOver()).toEqual({ start: 7n, end: 7n }); + expect((await decode([3, 1, 7, 0], Version.DRAFT_06)).previous).toBeUndefined(); +}); + // One macrotask, so every reaction queued before it has run. function nextTask(): Promise { return new Promise((resolve) => { diff --git a/js/net/src/lite/group.ts b/js/net/src/lite/group.ts index d22e9a1de1c..7b3cd396a6f 100644 --- a/js/net/src/lite/group.ts +++ b/js/net/src/lite/group.ts @@ -1,5 +1,5 @@ import { race } from "@moq/signals"; -import { FrameTooLarge, StreamCode, StreamError } from "../error.ts"; +import { FrameTooLarge, StreamCode, StreamError, TimestampMismatch } from "../error.ts"; import type { Producer as FrameProducer } from "../frame.ts"; import type * as netGroup from "../group.ts"; import { hooks } from "../internal.ts"; @@ -9,12 +9,19 @@ import * as Time from "../time.ts"; import { toNumber } from "../util/bigint.ts"; import { MAX_FRAME_BYTES } from "../util/limits.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, type Version } from "./version.ts"; +import { hasFrameBounds, hasGroupEnd, type Version } from "./version.ts"; export class Group { subscribe: bigint; sequence: bigint; + /** + * Lite-07: the start of the group before this one on the track, or undefined when the + * publisher does not know it. No group starts strictly between the two, so the starts between + * are skipped. A receiver refuses one at or above `sequence` as a malformed track. + */ + previous?: bigint; + /** * The index of the first frame on this stream within the group. * @@ -28,20 +35,33 @@ export class Group { constructor({ subscribe, sequence, + previous, frameStart = 0, }: { subscribe: bigint; sequence: bigint; + previous?: bigint; frameStart?: number; }) { this.subscribe = subscribe; this.sequence = sequence; + this.previous = previous; this.frameStart = frameStart; } + /** + * The starts this header passes over as skipped, `[start, end)`: those strictly between the + * previous group and this one, empty when the previous group is unknown or just below. + */ + passedOver(): { start: bigint; end: bigint } { + return passedOver(this.previous, this.sequence); + } + async #encode(w: Writer, version: Version) { await w.u62(this.subscribe); await w.u62(this.sequence); + // Plus one, so 0 says unknown. + if (hasGroupEnd(version)) await w.u62(this.previous === undefined ? 0n : this.previous + 1n); if (hasFrameBounds(version)) { await w.u53(this.frameStart); } else if (this.frameStart !== 0) { @@ -53,8 +73,10 @@ export class Group { static async #decode(r: Reader, version: Version): Promise { const subscribe = await r.u62(); const sequence = await r.u62(); + const plusOne = hasGroupEnd(version) ? await r.u62() : 0n; + const previous = plusOne === 0n ? undefined : plusOne - 1n; const frameStart = hasFrameBounds(version) ? await r.u53() : 0; - return new Group({ subscribe, sequence, frameStart }); + return new Group({ subscribe, sequence, previous, frameStart }); } async encode(w: Writer, version: Version): Promise { @@ -70,6 +92,16 @@ export class Group { } } +/** + * The starts a GROUP for `start` passes over as skipped when its previous group starts at + * `previous`: those strictly between, `[start, end)`. Empty when the previous group is unknown or + * just below. Mirrors the Rust `lite::passed_over`. + */ +export function passedOver(previous: bigint | undefined, start: bigint): { start: bigint; end: bigint } { + const from = previous === undefined ? start : previous + 1n; + return { start: from < start ? from : start, end: start }; +} + /** * A malformed FRAME on a Group Stream, which ends only that stream while the session and its other * streams go on (lite-07). Mirrors the Rust `UniState::Group`, which aborts only the stream. @@ -89,10 +121,20 @@ export interface WireFrame extends WirePayload { inflated?: number; } +/** Lite-07 GROUP_END: the group is whole, ending at `end` in the track's timescale. */ +export interface GroupEnd { + end: bigint; +} + /** How {@link frameDecoder} reads each frame's optional fields. */ export interface FrameFormat { - /** The wire timescale; non-zero means every frame carries a zigzag-delta timestamp. */ + /** + * The wire timescale; non-zero means every frame carries a zigzag-delta timestamp. A lite-07 + * frame carries one on a scale-less track too, which must be its group's `start`. + */ scale: number; + /** The group's start, which every frame on a scale-less lite-07 track is stamped with. */ + start?: bigint; /** Whether every frame declares its plain size ahead of a stored slice. */ compress?: boolean; /** @@ -103,22 +145,29 @@ export interface FrameFormat { } /** - * Decode one frame, with timestamp deltas when scaled and declared plain sizes when compressed. - * Lite-07 leads with the size plus one, where stream end ends the group; before it the size ends - * the header, and stream end at the frame's first field ends the group. + * Decode one frame, with timestamp deltas when stamped and declared plain sizes when compressed, + * or a lite-07 GROUP_END. Lite-07 leads with the size plus one, 0 for GROUP_END, where stream end + * closes the group; before it the size ends the header, and stream end at the frame's first field + * ends the group. */ -export function frameDecoder({ scale, compress = false, lengthFirst = false }: FrameFormat): (c: Cursor) => WireFrame { +export function frameDecoder({ + scale, + start, + compress = false, + lengthFirst = false, +}: FrameFormat): (c: Cursor) => WireFrame | GroupEnd { const timescale = scale === 0 ? undefined : Time.Timescale(scale); + // Lite-07 stamps a scale-less track's frames too, with their group's start. + const stamped = timescale !== undefined || lengthFirst; let prevTs = 0n; return (c) => { let size = 0; if (lengthFirst) { const length = c.u53(); - // 0 is reserved for GROUP_END, which no version defines yet. - if (length === 0) throw malformed("FRAME payload length of 0"); + if (length === 0) return { end: c.u62() }; size = length - 1; } - const delta = timescale === undefined ? 0n : unzigzag(c.u62()); + const delta = stamped ? unzigzag(c.u62()) : 0n; const inflated = compress ? c.u53() : undefined; if (!lengthFirst) size = c.u53(); // A compressed frame is stored whole; a plain one past a segment streams in after this. @@ -126,6 +175,8 @@ export function frameDecoder({ scale, compress = false, lengthFirst = false }: F const payload = compress ? c.read(size) : decodePayload(c, size); // Commit the delta only after the last read: an incomplete decode gets retried. prevTs += delta; + // A scale-less frame's timestamp is its group's start, which the group passes on. + if (timescale === undefined && stamped && prevTs !== start) throw new TimestampMismatch(); const timestamp = timescale === undefined ? undefined : new Time.Timestamp(toNumber(prevTs), timescale); return { size, payload, inflated, timestamp }; }; @@ -150,6 +201,9 @@ export interface Ingest { /** * Write a group stream's frames into `producer` until the stream ends or the producer closes. + * Resolves with where a lite-07 GROUP_END said the group ends, or undefined when the stream ended + * without one: the caller finishes the group at that end, and a bare FIN only closes it. Anything + * after GROUP_END, or an End the group refuses (at or before its start), is malformed. * * With `ingest`, a stream continuing a paused group skips the frames the group holds, and * completes the one a YIELDED reset cut short; ending before completing it is malformed. @@ -159,8 +213,8 @@ export async function readFrames( producer: netGroup.Producer, format: FrameFormat, ingest?: Ingest, -): Promise { - const decode = frameDecoder(format); +): Promise { + const decode = frameDecoder({ ...format, start: producer.sequence }); for (;;) { // Every frame already buffered is written without an await, so the reader wakes once @@ -169,7 +223,14 @@ export async function readFrames( const frame = stream.tryDecode(decode) ?? (await race([stream.decodeMaybe(decode), producer.closed])); if (frame === undefined && ingest?.partial) throw malformed("a continuation ended before completing the frame it resumed"); - if (!frame || frame instanceof Error) return; + if (!frame || frame instanceof Error) return undefined; + if ("end" in frame) { + if (ingest?.partial) throw malformed("GROUP_END before completing the frame a continuation resumed"); + if (frame.end <= producer.sequence) + throw malformed(`GROUP_END at ${frame.end}, not past the group's start`); + if (!(await stream.done())) throw malformed("bytes after GROUP_END"); + return frame.end; + } if (ingest) { const index = ingest.index++; const held = hooks.groupFrameCount(producer); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 90ba7b69500..c527398c1b7 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -833,8 +833,9 @@ async function servedSubscription( group.finish(); }, // Makes the next group stream withhold its FIN from the client, the way a stream the - // browser never finishes sending looks; resolves with the reason the publisher resets it. - stall(): Promise { + // browser never finishes sending looks, unless `fin`; resolves with the reason the + // publisher resets it. + stall(fin = false): Promise { const open = pair.server.createUnidirectionalStream.bind(pair.server); return new Promise((resolve) => { pair.server.createUnidirectionalStream = async (options) => { @@ -850,7 +851,7 @@ async function servedSubscription( }); }, write: (chunk) => writer.write(chunk), - close: () => new Promise(() => undefined), + close: () => (fin ? writer.close() : new Promise(() => undefined)), }); }; }); @@ -879,16 +880,27 @@ async function servedSubscription( const header = await GroupMessage.decode(reader, version); const payloads: string[] = []; + let end: bigint | undefined; while (!(await reader.done())) { // Each frame is a zigzag timestamp delta, then a length-prefixed payload. Lite-07 - // leads with the size plus one instead. + // leads with the size plus one instead, where 0 is GROUP_END and its End. const lengthFirst = hasLengthFirst(version); const length = lengthFirst ? (await reader.u53()) - 1 : undefined; + if (length === -1) { + end = await reader.u62(); + continue; + } await reader.u62(); const size = length ?? (await reader.u53()); payloads.push(new TextDecoder().decode(await reader.read(size))); } - return { sequence: header.sequence, frameStart: header.frameStart, payloads }; + return { + sequence: header.sequence, + frameStart: header.frameStart, + payloads, + previous: header.previous, + end, + }; }, // Stop the next group stream the publisher opened with `code`, before reading any of it, // as a subscriber that discards a stream unread does. @@ -1299,6 +1311,76 @@ for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { } } +// The SUBSCRIBE_SKIP and SUBSCRIBE_DROP ranges a lite-07 subscribe stream carried, in order, up to +// SUBSCRIBE_FINISH, or the first `count` of them. +async function holesToFinish(reader: Reader, count = Number.POSITIVE_INFINITY): Promise<[string, bigint, bigint][]> { + const holes: [string, bigint, bigint][] = []; + for (;;) { + if (holes.length >= count) return holes; + const resp = await decodeSubscribeResponseMaybe(reader, Version.DRAFT_07); + if (!resp || "finish" in resp) return holes; + if ("skip" in resp) holes.push(["skip", resp.skip.start, resp.skip.end]); + if ("drop" in resp) holes.push(["drop", resp.drop.start, resp.drop.end]); + } +} + +// Lite-07 ends a finished group's stream with GROUP_END, naming where the group ends, and a closed +// one's with a bare FIN. Mirrors the Rust `lite07_ends_a_finished_group_with_group_end`. +test("lite-07 ends a finished group with GROUP_END and a closed one with a bare FIN", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + const whole = sub.track.createGroup(0n); + whole.writeFrame(textFrame("x", Timestamp.fromMillis(0))); + whole.finish(500n); + expect(await sub.servedGroup()).toMatchObject({ sequence: 0n, payloads: ["x"], end: 500n }); + sub.serve(1000n); + const closed = await sub.servedGroup(); + expect([closed?.sequence, closed?.payloads, closed?.end]).toEqual([1000n, ["hello"], undefined]); + } finally { + await sub.close(); + } +}); + +// A lite-07 GROUP names the previous group's start, so a skipped run just below a group it serves +// goes out in that GROUP rather than as a SUBSCRIBE_SKIP. Mirrors the Rust +// `lite07_skips_a_declared_skip`. +test("lite-07 passes over a skipped run in the GROUP above it", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + sub.serve(0n); + expect(await sub.servedGroup()).toMatchObject({ sequence: 0n, previous: undefined }); + sub.serve(3n); + sub.track.skipGroups(1n, 3n); + expect(await sub.servedGroup()).toMatchObject({ sequence: 3n, previous: 0n }); + sub.track.finish(); + sub.track.close(); + expect(await holesToFinish(sub.client.reader)).toEqual([]); + } finally { + await sub.close(); + } +}); + +// A skipped run a GROUP passed over goes out as SUBSCRIBE_SKIP ahead of a drop of that group, since +// the GROUP may never have arrived. Mirrors the Rust `lite07_sends_an_elided_skip_ahead_of_a_drop`. +test("lite-07 sends a passed-over skip ahead of a drop of the group above it", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + sub.serve(0n); + expect(await sub.servedSequence()).toBe(0n); + // Left open, so only the stop ends its stream. + const above = sub.track.createGroup(3n); + above.writeFrame(textFrame("hello", Timestamp.fromMillis(3))); + sub.track.skipGroups(1n, 3n); + await sub.stopServed(StreamCode.Cancel); + expect(await holesToFinish(sub.client.reader, 2)).toEqual([ + ["skip", 1n, 3n], + ["drop", 3n, 4n], + ]); + } finally { + await sub.close(); + } +}); + // A huge declared skip goes out as one SUBSCRIBE_SKIP, at a cost independent of its length. // Mirrors Rust. test("lite-07 skips a huge run at once", async () => { @@ -1408,9 +1490,10 @@ async function holesToEnd(reader: Reader): Promise { } } -// A lite-07 stream that expired as stale is dropped for good: a final drop the reader reaches for it -// later does not go out over it (one still arriving, as a relay's copy from upstream, is cut by -// it), and a widening that admits it again does not re-offer it (one cached whole). +// A lite-07 stream that expired as stale is closed rather than reset, and accounts for its group, so +// no drop names it: a final drop the reader reaches for it later does not go out over it (one still +// arriving, as a relay's copy from upstream, is cut by it), and a widening that admits it again does +// not re-offer it (one cached whole, whose FIN went out first). test.each([ ["still arriving", true], ["cached whole", false], @@ -1432,7 +1515,10 @@ test.each([ // The restated range resolves at once. expect("started" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); - const reset = sub.stall(); + let reset = false; + void sub.stall(true).then(() => { + reset = true; + }); if (arriving) sub.track.createGroup(1n).writeFrame(textFrame("hello", Timestamp.fromMillis(1))); else sub.serve(1n); expect(await sub.servedHeader()).toBe(1n); @@ -1441,10 +1527,8 @@ test.each([ sub.serve(2n); expect(await sub.servedSequence()).toBe(2n); await clock.advance(Duration.millis(budget)); - expect(toStreamCode(fromTransport(await reset))).toBe(StreamCode.Old); - const first = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07); - if (!("drop" in first)) throw new Error("expected SUBSCRIBE_DROP"); - expect([first.drop.start, first.drop.end, first.drop.error]).toEqual([1n, 2n, StreamCode.Old]); + await flush(); + expect(reset).toBe(false); hooks.dropTrackGroups(sub.track, 1n, 2n, { error: new StreamError(StreamCode(70), { message: "cut" }) }); await update(budget * 100, 1n); @@ -1455,6 +1539,7 @@ test.each([ sub.track.finish(); sub.track.close(); expect(await holesToEnd(sub.client.reader)).toEqual([]); + expect(reset).toBe(false); } finally { await sub.close(); installed.close(); @@ -2454,7 +2539,7 @@ test("blocked DROP responses stop opening later groups", async () => { }); /** One group stream the publisher put on the wire. */ -type Served = { sequence: bigint; frameStart: number; payloads: string[] }; +type Served = { sequence: bigint; frameStart: number; payloads: string[]; previous?: bigint; end?: bigint }; /** * Serves `groups` (frame payloads per group, keyed by sequence) under `bounds`, and diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index f6ce05c8ef6..35db47590e0 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -62,7 +62,7 @@ import { import { Datagram as DatagramMessage, type Datagrams, DatagramsInfo, DatagramsUpdate } from "./datagram.ts"; import { closeViolation } from "./error.ts"; import type { Fetch } from "./fetch.ts"; -import { Group as GroupMessage } from "./group.ts"; +import { Group as GroupMessage, passedOver } from "./group.ts"; import { Probe } from "./probe.ts"; import { encodeSubscribeResponse, @@ -90,6 +90,7 @@ import { hasDatagrams, hasDatagramTracks, hasEndError, + hasGroupEnd, hasLargest, hasLengthFirst, hasProbeRtt, @@ -138,10 +139,21 @@ export function frameHeader( return concat(parts); } +/** + * Lite-07 GROUP_END, after a finished group's last frame: a zero `Payload Length`, where a frame + * would start, then the group's exclusive `end` in the track's timescale. + */ +function groupEnd(version: StreamVersion, end: bigint): Uint8Array { + return concat([encodeVarint(0, version), encodeVarint(end, version)]); +} + /** How a lite hop stamps a track's frames and datagrams. */ interface Stamp { - /** The wire timescale TRACK_INFO declared (see `wireTimescale`). */ - timescale: Timescale; + /** + * The wire timescale TRACK_INFO declared (see `wireTimescale`), or undefined on a scale-less + * lite-07 track, whose timestamps go out as bare numbers: a frame's its group's start. + */ + timescale?: Timescale; /** * The timed track whose frames' own timestamps go out, at its timescale, which the wire's * equals. Lite-05/06 cannot encode a scale-less track, so a scale-less one carries its send @@ -150,17 +162,24 @@ interface Stamp { timed?: { timescale?: Timescale | null }; } -/** How `version` stamps a track with `info`, or undefined when it carries no timestamps. */ +/** + * How `version` stamps a track with `info`, or undefined when it carries no timestamps: before + * lite-05. Lite-05/06 declare milliseconds for a scale-less track, and lite-07 stamps it bare. + */ function stamping(version: Version, info: { timescale?: Timescale | null }): Stamp | undefined { const timescale = info.timescale ?? undefined; const wire = wireTimescale(version, timescale); - if (wire === undefined) return undefined; + if (wire === undefined) return hasLengthFirst(version) ? {} : undefined; return timescale === undefined ? { timescale: wire } : { timescale: wire, timed: info }; } -/** A frame or datagram's `timestamp` as its raw wire value, or its send time when the track goes out scale-less. */ -function wireTime(timestamp: Timestamp, stamp: Stamp): number { - return stamp.timed ? rescale(stamp.timed, timestamp).value : floorAt(Timestamp.now(), stamp.timescale); +/** + * A frame or datagram's `timestamp` as its raw wire value: bare on a scale-less lite-07 track, or + * its send time when a lite-05/06 track goes out scale-less. + */ +function wireTime(timestamp: Timestamp, stamp: Stamp): bigint { + if (stamp.timescale === undefined) return bareTime(timestamp); + return BigInt(stamp.timed ? rescale(stamp.timed, timestamp).value : floorAt(Timestamp.now(), stamp.timescale)); } /** A scale-less lite-07 datagram's timestamp as it goes out: the bare value its producer gave. */ @@ -238,6 +257,9 @@ interface RunGroup { /** Last frame to send (inclusive), or undefined for the rest of the group. */ end?: number; + + /** Lite-07: the previous group's start the GROUP names, undefined when unknown. */ + previous?: bigint; } /** @@ -1519,10 +1541,44 @@ export class Publisher { return { kind: hole.skip ? "skip" : "dropped" }; }; + // Lite-07: the skipped runs not sent as SUBSCRIBE_SKIP, each by the start of the cached group + // just above it, whose GROUP's Previous Start passes over the run instead. Each waits for that + // group to be served, when its stream carries the run, or given up, when the run goes out + // ahead of the drop. At most one per cached group. Mirrors the Rust `TrackRun::elided`. + const elided = new Map(); + // Whether the cached group `key` is still owed a stream or a drop on this subscription. + const owesGroup = (key: bigint): boolean => + hooks.holdsGroup(track, key) && !record?.told(key) && hooks.servingRuns(track, key, key + 1n).length > 0; + // Whether the skipped `[start, end)` goes unsent, since the GROUP of the cached group just + // above it passes over it: that group is still owed, and its previous start is below the run. + const elides = (start: bigint, end: bigint): boolean => { + if (!hasGroupEnd(this.version) || !owesGroup(end)) return false; + const previous = hooks.previousStart(track, end); + return previous !== undefined && previous < start; + }; + const skip = (start: bigint, end: bigint) => + controls.response( + encodeSubscribeResponse(stream, { skip: new SubscribeSkip({ start, end }) }, this.version), + ); + // Send as SUBSCRIBE_SKIP each run elided for a group in `[start, end)`, which is given up, + // or, with no range, for each group no longer owed, after an update moved the ranges. + const sendElided = async (start?: bigint, end?: bigint): Promise => { + for (const [above, from] of [...elided]) { + const given = + start === undefined || end === undefined ? !owesGroup(above) : above >= start && above < end; + if (!given) continue; + elided.delete(above); + if (!(await skip(from, above))) return false; + } + return true; + }; + // Give up, as `hole` says, whatever part of `[start, end)` this subscription has not been // served or given up yet. const drop = async (start: bigint, end: bigint, hole: Hole): Promise => { if (!record) return true; + // A run elided for a group given up goes out ahead of its drop. + if (!(await sendElided(start, end))) return false; const report = reportOf(hole); for (const gap of record.untold(start, end)) { record.tell(gap.start, gap.end, report); @@ -1534,12 +1590,26 @@ export class Publisher { // Forward a verdict the reader reached on `[start, end)`, which its record already took in, // replacing what it goes out over: on lite-07, a skip any drop already sent. A reader the - // earlier drop ended stays ended. + // earlier drop ended stays ended. A run elided for a group in the range goes out ahead of a + // drop, or joins a skip, since no GROUP passes over it now. const forward = async (start: bigint, end: bigint, hole: Hole): Promise => { if (!record || start >= end) return true; record.tell(start, end, reportOf(hole)); - const msg = holeMessage(start, end, hole); - return controls.response(encodeSubscribeResponse(stream, msg, this.version)); + if (!hole.skip) { + if (!(await sendElided(start, end))) return false; + return controls.response(encodeSubscribeResponse(stream, holeMessage(start, end, hole), this.version)); + } + let from = start; + for (const [above, below] of [...elided]) { + if (above < start || above >= end) continue; + elided.delete(above); + from = min(from, below); + } + if (elides(from, end)) { + elided.set(end, min(elided.get(end) ?? from, from)); + return true; + } + return controls.response(encodeSubscribeResponse(stream, holeMessage(from, end, hole), this.version)); }; // The track's exclusive final boundary. A Rust subscriber feeds SUBSCRIBE_FINISH @@ -1589,8 +1659,10 @@ export class Publisher { // Every group this subscription started serving, until its stream finishes or resets. const groups = new Set>(); const drops = new Signal(0); - // Groups whose stream failed, with why, for the control stream to name, as runs. - const pendingDrops: { start: bigint; end: bigint; error: Error }[] = []; + // Groups whose stream failed, with why, for the control stream to name, as runs, each with the + // skipped starts its GROUP passed over, which go out first since that GROUP may never have + // arrived. + const pendingDrops: { start: bigint; end: bigint; error: Error; passed: { start: bigint; end: bigint } }[] = []; // Lite-07: a fresh read of the group `serving` served, whose stream the session reset to make // room, for a new stream to continue it at the same frames; undefined once the subscription's // budget or the cache gave it up. The Rust publisher keeps an unread clone of the reset @@ -1627,7 +1699,8 @@ export class Publisher { skipped.length = 0; } if (pendingDrops.length > 0) { - for (const { start, end, error } of pendingDrops.splice(0)) { + for (const { start, end, error, passed } of pendingDrops.splice(0)) { + if (passed.start < passed.end && !(await skip(passed.start, passed.end))) return false; record?.tell(start, end, reportOf({ error })); const msg = SubscribeDrop.given(start, end, error, this.version); if (!(await controls.response(encodeSubscribeResponse(stream, { drop: msg }, this.version)))) @@ -1690,6 +1763,8 @@ export class Publisher { bounds.endGroup = update.endGroup; bounds.endFrame = update.endFrame; moveCursor(); + // A run elided for a group the ranges no longer name goes out after all. + if (!(await sendElided())) return false; // A microtask is too short: decoding one framed update crosses several // awaits, each of which can requeue behind the serving continuation. A // task boundary usually lets the decoder finish whatever the transport @@ -1898,6 +1973,9 @@ export class Publisher { return false; } record?.tell(group.sequence, group.sequence + 1n, { kind: "settled" }); + // Its GROUP passes over the run elided below it, and a drop of it sends the run first. + elided.delete(group.sequence); + const previous = hasGroupEnd(this.version) ? hooks.previousStart(track, group.sequence) : undefined; const options: RunGroup = { sub, @@ -1909,6 +1987,7 @@ export class Publisher { unsubscribed, start: range.start, end: range.end, + previous, }; // The FIN waits for every stream to finish or reset, including one that has not opened yet, // and a paused group's continuation. @@ -1944,7 +2023,12 @@ export class Publisher { failed = fate instanceof Error ? fate : new StreamError(StreamCode.Old); } if (emitRange) { - pendingDrops.push({ start: group.sequence, end: group.sequence + 1n, error: failed }); + pendingDrops.push({ + start: group.sequence, + end: group.sequence + 1n, + error: failed, + passed: passedOver(serving.previous, group.sequence), + }); drops.update((revision) => revision + 1); } return; @@ -2300,16 +2384,16 @@ export class Publisher { const datagram = await track.recv(); if (!datagram) return end; end = max(end, datagram.sequence + 1n); - const stamp = options.stamp; - // An old subscription uses its stream track's timescale for both kinds. Without a - // stamp the track is a scale-less lite-07 one, whose timestamp goes out bare. + // An old subscription uses its stream track's timescale for both kinds. Without one + // the track is a scale-less lite-07 one, whose timestamp goes out bare. + const timescale = options.stamp?.timescale; const timestamp = - stamp === undefined + timescale === undefined ? bareTime(datagram.timestamp) : BigInt( datagram.timestamp.scale === undefined - ? floorAt(Timestamp.now(), stamp.timescale) - : floorAt(datagram.timestamp, stamp.timescale), + ? floorAt(Timestamp.now(), timescale) + : floorAt(datagram.timestamp, timescale), ); const body = new DatagramMessage(options.sub, datagram.sequence, timestamp, datagram.payload).encode( this.version, @@ -2364,7 +2448,7 @@ export class Publisher { let delta: bigint | undefined; if (stamp !== undefined) { - const ts = BigInt(wireTime(frame.timestamp, stamp)); + const ts = wireTime(frame.timestamp, stamp); delta = ts - prevTs; prevTs = ts; } @@ -2375,6 +2459,10 @@ export class Publisher { if (read.chunks) await sendPayload(read.chunks, (chunk) => stream.write(chunk), stream.closed); else if (frame.payload.length > 0) await stream.write(frame.payload); } + // Lite-07: a response that reached a finished group's end says so before the FIN. + const end = group.end; + if (hasGroupEnd(this.version) && end !== undefined && hooks.groupIndex(group) >= group.frameCount) + await stream.write(groupEnd(stream.version, end)); } /** @@ -2432,13 +2520,23 @@ export class Publisher { * @internal */ async #serveGroup(stream: Writer, options: RunGroup) { - const { sub, group, givenUp, stamp, compress, priority, start: startFrame, end: endFrame } = options; + const { sub, group, givenUp, stamp, compress, priority, previous, start: startFrame, end: endFrame } = options; // The header names the requested position, so a copy missing it must be refused. - const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, frameStart: startFrame }); + const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, previous, frameStart: startFrame }); + // Lite-07 ends a finished group with GROUP_END and closes, rather than resets, the stream of + // a group that expires on it: the stream accounts for the group, so no drop names it. + const closes = hasGroupEnd(this.version); + // The write under way, which an expiry close lets complete, so the stream ends on a frame. + let writing: Promise | undefined; + // Whether the stream's end went out, after which it is never reset for expiry on lite-07. + let ended = false; // The subscription's budget, or an eviction of what is left to read, may give up on the // group mid-write, which abandons the stream. A group already given up never starts the write. const write = async (op: () => Promise) => { - const stop = await givenUp.write(op); + const stop = await givenUp.write(() => { + writing = op(); + return writing; + }); if (stop) throw stop; }; // Everything past this point runs inside the cleanup scope, so a failure never leaves @@ -2458,6 +2556,8 @@ export class Publisher { // Whether the cursor ever reached the requested start, which decides how the // end of the group is read below. A received tail may already begin there. let reached = hooks.groupIndex(group) === startFrame; + // Whether every frame went out, which a finished group's GROUP_END then claims. + let whole = false; for (;;) { const read = await race([hooks.readGroupFrame(group, compress), stream.closed]); @@ -2467,6 +2567,7 @@ export class Publisher { // would claim an empty group under that index; reset so it reads // as the gap it is. if (!reached) throw new Error(`group ended before frame ${startFrame}`); + whole = true; break; } @@ -2480,7 +2581,7 @@ export class Publisher { let delta: bigint | undefined; if (stamp !== undefined) { // Convert each frame to the track's wire timescale. - const ts = BigInt(wireTime(read.frame.timestamp, stamp)); + const ts = wireTime(read.frame.timestamp, stamp); delta = ts - prevTs; prevTs = ts; } @@ -2502,15 +2603,31 @@ export class Publisher { }); } + const end = closes && whole ? group.end : undefined; + if (end !== undefined) await write(() => stream.write(groupEnd(stream.version, end))); stream.close(); + ended = true; group.close(); // A stream that fails after its FIN may have lost its header, so report it for a DROP. - // Its bytes still hold the connection until acknowledged, so a group gone stale - // meanwhile is reset like one still serving, as the Rust `GroupServe` does. - await write(() => stream.closed); + // Its bytes still hold the connection until acknowledged, so before lite-07 a group gone + // stale meanwhile is reset like one still serving, as the Rust `GroupServe` does. + if (closes) await stream.closed; + else await write(() => stream.closed); return undefined; } catch (err: unknown) { const e = error(err); + if (closes && !ended && hooks.groupExpired(group)) { + // Expired on its stream: what went out stands as a closed group, and the frame + // being written completes first. Mirrors the Rust `GroupServe`'s expiry close. + console.debug(`closing expired group: subscribe=${sub} sequence=${group.sequence}`); + await writing?.catch(() => {}); + stream.close(); + group.close(); + return await stream.closed.then( + () => undefined, + (err: unknown) => error(err), + ); + } stream.reset(e); // A reset that pauses the group leaves the reader to the caller, which reads its fate // first. A reset stream is never preempted after, so the caller sees the same flag. diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 17d7f9e1867..7bb4e4d8705 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1962,9 +1962,9 @@ test("a duplicate stream waiting out its copy holds the end", async () => { }); // Lite-07: a malformed FRAME on a Group Stream ends only that stream and its group, never the -// session: a Payload Length of 0, or a continuation that resends the cut frame at another size, ends +// session: bytes after GROUP_END, or a continuation that resends the cut frame at another size, ends // before completing it, or starts past the frames held. Mirrors the Rust `UniState::Group`. -test.each(["zero length", "resized", "unfinished", "past held"] as const)( +test.each(["after GROUP_END", "resized", "unfinished", "past held"] as const)( "a malformed lite-07 group stream ends only its group (%s)", async (fault) => { const version = Version.DRAFT_07; @@ -1985,13 +1985,22 @@ test.each(["zero length", "resized", "unfinished", "past held"] as const)( const header = new Group({ subscribe: 0n, sequence: 3n, frameStart: 0 }); const first = handStream(version); first.write(await liteFrame(300, zero)); - if (fault === "zero length") first.write(await Writer.collect(version, (w) => w.u53(0))); - else first.write(await liteFrame(10, cut, SEGMENT_BYTES / 2)); + if (fault === "after GROUP_END") { + // A zero Payload Length, the End, then a byte where only the FIN may follow. + first.write( + await Writer.collect(version, async (w) => { + await w.u53(0); + await w.u62(1000n); + await w.u53(0); + }), + ); + first.finish(); + } else first.write(await liteFrame(10, cut, SEGMENT_BYTES / 2)); let running = subscriber.runGroup(header, first.reader); const group = await track.recvGroup(); expect((await group?.readFrame())?.payload).toEqual(zero); - if (fault !== "zero length") { + if (fault !== "after GROUP_END") { first.reset(StreamCode.Yielded); await running; await drainReactions(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index d77cde17d48..3f626924c01 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -2685,7 +2685,7 @@ export class Subscriber { try { // One guard covers both header waits and a stalled payload. Abandonment aborts // the group before resetting the stream, releasing the shared frame pump too. - await untilAbandoned( + const end = await untilAbandoned( group, readFrames(stream.reader, group, { scale: info.timescale ?? 0, @@ -2694,7 +2694,8 @@ export class Subscriber { }), ); - group.finish(); + // Whole at a GROUP_END's end, else closed: every frame sent arrived. + group.finish(end); stream.close(); } catch (err: unknown) { const e = error(err); @@ -3030,7 +3031,7 @@ export class Subscriber { try { // Once no reader holds the group or waits to pick it up, cancel upstream and abort the // truncated group rather than cache it whole, as the Rust fetch's ingest does. - await untilAbandoned( + const end = await untilAbandoned( group, readFrames(stream.reader, group, { scale: framing.timescale, @@ -3038,7 +3039,8 @@ export class Subscriber { lengthFirst: hasLengthFirst(this.version), }), ); - group.finish(); + // Whole at a GROUP_END's end, else closed: every frame sent arrived. + group.finish(end); stream.close(); } catch (err: unknown) { const e = error(err); @@ -3247,24 +3249,29 @@ export class Subscriber { hooks.dropTrackGroups(entry.track, start, end, hole); entry.fills?.refuse(start, end, error); } else if ("skip" in resp) { - // Never produced, so nothing is waited for and no reader ends. A skip replaces any drop of - // the same groups; a reader a drop already ended stays ended. const { start, end } = resp.skip; - entry.tail.account(start, end); - // A fill owing them is answered: the source never had them. - entry.fills?.refuse(start, end, new NotFound(`group ${start}`)); - // A group that arrived was produced after all, so the skip contradicts it: it keeps - // the group, and the session goes on, since the draft requires no more. - const [cached] = hooks.skipTrackGroups(entry.track, start, end); - if (cached) { - console.warn( - `protocol error: SUBSCRIBE_SKIP [${start}, ${end}) names group ${cached.start}, which arrived; keeping it`, - ); - } + this.#skipped(entry, start, end, "SUBSCRIBE_SKIP"); } } } + // The publisher never produced `[start, end)`, as `by` (a SUBSCRIBE_SKIP, or a GROUP's Previous + // Start) says, so nothing is waited for and no reader ends. A skip replaces any drop of the same + // groups; a reader a drop already ended stays ended. + #skipped(entry: SubscribeEntry, start: bigint, end: bigint, by: string): void { + entry.tail.account(start, end); + // A fill owing them is answered: the source never had them. + entry.fills?.refuse(start, end, new NotFound(`group ${start}`)); + // A group that arrived was produced after all, so the skip contradicts it: it keeps the + // group, and the session goes on, since the draft requires no more. + const [cached] = hooks.skipTrackGroups(entry.track, start, end); + if (cached) { + console.warn( + `protocol error: ${by} skips [${start}, ${end}), which holds group ${cached.start}, which arrived; keeping it`, + ); + } + } + // Settle a lite-07 tail past SUBSCRIBE_FINISH, then FIN. An update sent meanwhile asks for more, // which waits a fresh grace rather than one that may have passed while a stream was read. async #finishTail(stream: Stream, entry: SubscribeEntry): Promise { @@ -3552,6 +3559,16 @@ export class Subscriber { } const { track, timescale, tail } = entry; + // The group before it must start below it, or the header contradicts itself: only this + // stream ends, as a malformed FRAME does. + if (group.previous !== undefined && group.previous >= group.sequence) { + stream.stop( + new StreamError(StreamCode.MalformedTrack, { + message: `group ${group.sequence} names group ${group.previous} as the one before it`, + }), + ); + return; + } // Lite-07: a YIELDED reset pauses the group, for a later stream to continue. const yields = hasYield(this.version); // Asked before this stream accounts for the group: a drop that overtook it named it. @@ -3616,6 +3633,11 @@ export class Subscriber { start: group.frameStart, fill: entry.filling, }); + // Lite-07: the starts the header passes over were never produced, as a SUBSCRIBE_SKIP + // would say. Recorded once the group is, so a relay serving the copy sees the group the + // skip runs up to, whose own GROUP passes over it again. + const passed = group.passedOver(); + if (passed.start < passed.end) this.#skipped(entry, passed.start, passed.end, `GROUP ${group.sequence}`); // Released once this copy took the group, so the failed copy's readers find it. arriving?.release(); let superseded: Promise | undefined; @@ -3639,8 +3661,11 @@ export class Subscriber { const format = { scale: timescale, compress: entry.compress, lengthFirst: hasLengthFirst(this.version) }; const reading = readFrames(stream, producer, format, ingest); const reads = entry.filling ? untilAbandoned(producer, reading) : reading; - if (!superseded) await reads; - else if ((await race([reads, superseded.then(() => SUPERSEDED)])) === SUPERSEDED) { + const end = + superseded !== undefined + ? await race([reads, superseded.then((): typeof SUPERSEDED => SUPERSEDED)]) + : await reads; + if (end === SUPERSEDED) { // Stopping makes the read end at the next frame boundary as if finished, so wait it out // and treat the stream as the YIELDED reset it was: the later stream starts no later. stream.stop(new StreamError(StreamCode.Cancel)); @@ -3648,7 +3673,8 @@ export class Subscriber { throw new StreamError(StreamCode.Yielded, { message: "continued on a later stream" }); } - producer.finish(); + // Whole at a GROUP_END's end, else closed: every frame sent arrived. + producer.finish(end); stream.stop(StreamCode.Cancel); } catch (err: unknown) { // A violation ends the session, which the connection does once it escapes; anything diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 97dd9d60fa9..ab386d9c4f9 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -755,8 +755,8 @@ export function hasImplementation(version: Version): boolean { } /** - * Whether FRAME leads with its `Payload Length`, the payload size plus one, leaving 0 for a - * future GROUP_END. Added in lite-07; an earlier FRAME ends its header with the payload size. + * Whether FRAME leads with its `Payload Length`, the payload size plus one, leaving 0 for + * GROUP_END. Added in lite-07; an earlier FRAME ends its header with the payload size. */ export function hasLengthFirst(version: Version): boolean { switch (version) { @@ -772,6 +772,26 @@ export function hasLengthFirst(version: Version): boolean { } } +/** + * Whether GROUP carries the previous group's `Previous Start`, and a Group or Fetch Stream ends a + * finished group with GROUP_END and a closed one with a bare FIN. A publisher then closes an + * expired group's stream rather than resetting it. Added in lite-07; earlier versions end every + * group with a bare FIN. + */ +export function hasGroupEnd(version: Version): boolean { + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } +} + /** * Whether a Group Stream reset with YIELDED pauses its group, which a later stream continues. * Added in lite-07; an earlier publisher out of stream credit gives the reset group up. diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index 7421e66aa0f..e19be86dd57 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -154,7 +154,9 @@ for (const protocol of protocols) { const origin = new Origin(); const broadcastRoute = origin.route(Path.from("parked")); const broadcast = broadcastRoute.broadcast; - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // No publisher limit, so the eviction rather than a stale verdict gives the group up: lite-07 + // closes the stream of a group gone stale instead of resetting it. + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const write = (sequence: bigint, frames: number) => { const group = track.createGroup(sequence); for (let frame = 0; frame < frames; frame++) { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 2a6b7a91a8e..c7f1dc2f742 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -3770,6 +3770,16 @@ export class Subscriber { const producer = subscriber.#state.producer; return producer !== undefined && cachedHolds(producer, sequence); }; + hooks.previousStart = (subscriber, start) => { + // A reader following route copies knows only what the serving copy holds, which this + // one does not: unknown, so the skips below go out on their own. + if (subscriber.#resume || start === 0n) return undefined; + const below = start - 1n; + const run = subscriber.#state.drops.at(below); + if (run?.skip) return run.start > 0n ? run.start - 1n : undefined; + const producer = subscriber.#state.producer; + return producer !== undefined && cachedIn(producer, below, start).length > 0 ? below : undefined; + }; hooks.staleHeld = (subscriber, start, end) => { const held: Run[] = []; for (const run of subscriber.#state.drops.overlapping(start, end)) { diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index ad256feafe7..15b481c1057 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -35,8 +35,11 @@ const WIRES: Wire[] = [ { name: "ietf-22", protocol: Ietf.ALPN.DRAFT_22, declares: true, sends: false }, ]; -/** Serve one group of `timestamps` on a track with `timescale`, and read it back over `wire`. */ -async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamps: Timestamp[]) { +/** + * Serve one group of `timestamps` on a track with `timescale`, starting at `sequence` (the next + * one by default), and read it back over `wire`. + */ +async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamps: Timestamp[], sequence?: bigint) { const pair = createMockTransportPair(wire.protocol); const origin = new OriginProducer(); const [client, server] = await Promise.all([ @@ -51,7 +54,8 @@ async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamp for (;;) { const request = await wireOf(broadcast).requested(); if (!request) break; - const group = request.accept({ timescale }).appendGroup(); + const track = request.accept({ timescale }); + const group = sequence === undefined ? track.appendGroup() : track.createGroup(sequence); for (const [i, timestamp] of timestamps.entries()) { group.writeFrame({ payload: new Uint8Array([i]), timestamp }); } @@ -165,6 +169,17 @@ for (const wire of WIRES) { for (const frame of frames) expect(frame.timestamp.scale !== undefined).toBe(wire.sends); }); + // Lite-07 stamps each scale-less frame with its group's start as a bare number, which the + // subscriber checks against the GROUP, so a start past 0 tells it apart from no stamp at all. + if (wire.name === "lite-07-wip") { + test(`${wire.name}: an untimed group past 0 arrives stamped with its start`, async () => { + const key = Timestamp.unscaled(9n); + const { frames } = await roundTrip(wire, undefined, [key, key], 9n); + expect(frames.map((frame) => frame.payload[0])).toEqual([0, 1]); + for (const frame of frames) expect(frame.timestamp).toEqual(key); + }); + } + test(`${wire.name}: a timed track keeps its timestamps only where the wire delivers them`, async () => { const { info, frames } = await roundTrip(wire, Timescale.MICRO, [ Timestamp.fromMicros(1_000), diff --git a/test/interop/lite-varint.ts b/test/interop/lite-varint.ts index 9912508cd58..6240888baec 100644 --- a/test/interop/lite-varint.ts +++ b/test/interop/lite-varint.ts @@ -81,6 +81,8 @@ const frames: { timestamp: bigint; payload: Uint8Array }[] = []; for (;;) { const frame = await g.decodeMaybe(decode); if (!frame) break; + // Only a length-first frame can be a GROUP_END, and the fixture's frames are not. + if ("end" in frame) throw new Error("a fixture frame decoded as GROUP_END"); if (!frame.timestamp) throw new Error("a lite-05+ frame decoded without its timestamp"); // The fixture's frames fit one segment, so each payload decodes with its header. if (!frame.payload) throw new Error("a fixture frame streamed past its header"); @@ -107,6 +109,7 @@ if (untimed) { for (;;) { const frame = await u.decodeMaybe(frameDecoder({ scale: 0 })); if (!frame) break; + if ("end" in frame) throw new Error("a fixture frame decoded as GROUP_END"); assert.equal(frame.timestamp, undefined); if (!frame.payload) throw new Error("a fixture frame streamed past its header"); untimedFrames.push(frame.payload); From 157042024b139ef0153e1ab71ea40dfdf5e08993 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 08:46:43 -0800 Subject: [PATCH 16/26] fix(net): a skipped group takes the run held back for its GROUP A skip held back for the GROUP of the group above it stayed held forever once that group was skipped too: no GROUP would pass over it, and only a drop sent it. A skip of that group now joins the held run, and a drop of it sends the run first, as before. Also catches up the tests that hand-build lite-07 bytes: the moq-tokio receive credit GROUP headers carry a Previous Start, and the lite varint interop GROUP names one, so both languages encode it alike. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 71 +++++++++++++------ rs/moq-net/src/test_interop.rs | 5 +- .../tests/integration/receive_credit.rs | 2 + 3 files changed, 55 insertions(+), 23 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index d677a90ffc2..6ae42f78810 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -5772,7 +5772,9 @@ impl TrackRun { /// Forward a verdict the cursor reached on `range`, which its record already took in, /// replacing what it goes out over: on lite-07, a skip any drop already sent. A reader the - /// earlier drop ended stays ended. Returns whether any was buffered. + /// earlier drop ended stays ended. A run elided for a group in `range` goes out ahead of + /// a drop, or joins a skip, since no GROUP passes over it now. Returns whether any was + /// buffered. fn forward_range( &mut self, range: Range, @@ -5784,18 +5786,23 @@ impl TrackRun { } let report = self.report(hole); self.track.record_mut().tell(range.clone(), report); - match hole { - Hole::Skip if self.elides(&range) => { - let start = self.elided.entry(range.end).or_insert(range.start); - *start = range.start.min(*start); - return Ok(false); - } - Hole::Skip => {} - Hole::Drop { .. } => { - self.send_elided(range.clone(), writer)?; - } + if !matches!(hole, Hole::Skip) { + self.send_elided(range.clone(), writer)?; + writer.buffer(&self.hole(range, hole))?; + return Ok(true); + } + let mut run = range; + let covered: Vec = self.elided.range(run.clone()).map(|(above, _)| *above).collect(); + for above in covered { + let start = self.elided.remove(&above).expect("collected above"); + run.start = run.start.min(start); + } + if self.elides(&run) { + let start = self.elided.entry(run.end).or_insert(run.start); + *start = run.start.min(*start); + return Ok(false); } - writer.buffer(&self.hole(range, hole))?; + writer.buffer(&self.hole(run, hole))?; Ok(true) } @@ -5818,17 +5825,18 @@ impl TrackRun { } /// Send as SUBSCRIBE_SKIP each run elided for a group in `groups`, which is given up. + /// Returns whether any was buffered. fn send_elided( &mut self, groups: Range, writer: &mut Writer, - ) -> Result<(), Error> { + ) -> Result { let above: Vec = self.elided.range(groups).map(|(above, _)| *above).collect(); - for above in above { - let start = self.elided.remove(&above).expect("collected above"); - writer.buffer(&self.hole(start..above, &Hole::Skip))?; + for above in &above { + let start = self.elided.remove(above).expect("collected above"); + writer.buffer(&self.hole(start..*above, &Hole::Skip))?; } - Ok(()) + Ok(!above.is_empty()) } /// Send as SUBSCRIBE_SKIP each run elided for a group this subscription no longer owes, @@ -5872,9 +5880,8 @@ impl TrackRun { if !self.start.emits_range() || range.is_empty() { return Ok(false); } - if !matches!(hole, Hole::Skip) { - self.send_elided(range.clone(), writer)?; - } + // A run elided for a group given up goes out ahead of its drop. + let elided = self.send_elided(range.clone(), writer)?; let gaps = self.track.record_mut().untold(range); let report = self.report(hole); for gap in gaps.iter() { @@ -5882,7 +5889,7 @@ impl TrackRun { let msg = self.hole(gap.clone(), hole); writer.buffer(&msg)?; } - Ok(!gaps.is_empty()) + Ok(elided || !gaps.is_empty()) } /// The message naming `groups` given up as `hole`: lite-07 skips what was never @@ -8830,6 +8837,28 @@ mod serve_group_test { assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3), ("drop", 3..4)]); } + /// A skipped run held back for a group that is then skipped too joins that group's skip, + /// since no GROUP will pass over it. + #[kio::test] + async fn lite07_a_held_skip_joins_its_groups_skip() { + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + track.received(); + let subscriber = track.subscribe(None); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 0, 0); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + track.skip_groups(1..3); + write_group(&mut track, 3, 3); + forward(&mut run, 1..3, &Hole::Skip, &mut writer); + assert!(holes(&mut writer, &log).await.is_empty(), "held for group 3's GROUP"); + forward(&mut run, 3..4, &Hole::Skip, &mut writer); + assert_eq!(holes(&mut writer, &log).await, [("skip", 1..4)]); + } + /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the /// skip replaces it; lite-06, which names a skip as a drop, sends nothing more. #[kio::test] diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index a8536bb97c1..f581c7d0876 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -264,14 +264,15 @@ fn lite_values() -> Vec { } /// One GROUP header and its frames, as a publisher writes them: a zigzag timestamp delta on -/// a timed track, the payload size, then the payload. +/// a timed track, the payload size, then the payload. The header names a previous start, +/// which only lite-07 carries. fn lite_group(version: lite::Version, frames: impl IntoIterator, usize)>) -> Vec { let mut buf = Vec::new(); let w = &mut Encoder::new(&mut buf, version.into()); let header = lite::Group { subscribe: 5, key: 1 << 20, - previous: None, + previous: Some((1 << 20) - 3), frame_start: 200, }; header.encode(w, version).unwrap(); diff --git a/rs/moq-tokio/tests/integration/receive_credit.rs b/rs/moq-tokio/tests/integration/receive_credit.rs index 05682f7b3e8..123a1471a61 100644 --- a/rs/moq-tokio/tests/integration/receive_credit.rs +++ b/rs/moq-tokio/tests/integration/receive_credit.rs @@ -621,6 +621,8 @@ fn group_stream(subscribe: u64, sequence: u64, size: usize) -> Vec { let mut header = Vec::new(); varint(&mut header, subscribe); varint(&mut header, sequence); + // No previous start: 0 says unknown, since the field carries it plus one. + varint(&mut header, 0); // The first frame. varint(&mut header, 0); From 1d8530077f315ac65c9afa44a052d3f137c8f9bf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 08:47:08 -0800 Subject: [PATCH 17/26] docs(verify): the subscription model closes expired streams and passes over skips SubscribeAccounting now describes lite-07 as the code runs it: - A serving Group Stream whose group expires closes with a FIN and no drop (`StreamClose`). Only a stream that never opened is still given up with OLD, and nothing resets a stream once its FIN went out. - Each GROUP passes over the skipped run directly below it. The publisher holds a skip back for the GROUP of a group it still owes (`held`), and sends it ahead of that group's drop or joined to its skip. A drop of a group whose stream opened repeats what its GROUP passed over first (`nahead`), which NamedOnce allows once. Groups start at 1 in SubscribeAccounting.cfg, so a skip of 1 can be held for 2. Both configs pass: 15.9M distinct states in four minutes, and 493K in five seconds for Continuation.cfg. Mutations dropping the join, the skip ahead of a held group's drop, or the skip ahead of a served group's drop each break QuietIsSettled. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/verify-subscribe/SKILL.md | 25 ++- .../verify/subscribe/SubscribeAccounting.cfg | 2 +- .../verify/subscribe/SubscribeAccounting.tla | 201 ++++++++++++------ 3 files changed, 154 insertions(+), 74 deletions(-) diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index cd370e3fece..eb0465619c5 100644 --- a/.claude/skills/verify-subscribe/SKILL.md +++ b/.claude/skills/verify-subscribe/SKILL.md @@ -1,11 +1,11 @@ --- name: verify-subscribe -description: Model-check how a lite-07 subscription accounts for each group (`rs/moq-net/src/lite/publisher.rs` `TrackRun` and `GroupServe`, `lite/subscriber.rs` `ServeLoop::apply_response`, `src/tail.rs`) with TLA+. Use when a change touches SUBSCRIBE_DROP, SUBSCRIBE_SKIP, stale (OLD) drops, which groups a publisher serves or names once, Group Stream resets and expiry, YIELDED resets and continuations of a paused group, duplicate Group Streams, or the subscriber's tail, or when a drop bug needs every ordering of the Subscribe Stream against the Group Streams checked. +description: Model-check how a lite-07 subscription accounts for each group (`rs/moq-net/src/lite/publisher.rs` `TrackRun` and `GroupServe`, `lite/subscriber.rs` `ServeLoop::apply_response`, `src/tail.rs`) with TLA+. Use when a change touches SUBSCRIBE_DROP, SUBSCRIBE_SKIP, stale (OLD) drops, which groups a publisher serves or names once, Group Stream resets and expiry (a lite-07 stream closed when its group expires), a GROUP's Previous Start and the skips it passes over or the publisher holds back for it, YIELDED resets and continuations of a paused group, duplicate Group Streams, or the subscriber's tail, or when a drop bug needs every ordering of the Subscribe Stream against the Group Streams checked. --- # Verify subscription accounting -`rs/moq-net/verify/subscribe/SubscribeAccounting.tla` models the groups of one answered lite-07 subscription between the publisher's `TrackRun` and the subscriber's `TrackServe`. The draft promises that every sequence in range gets a Group Stream, a SUBSCRIBE_SKIP, or a SUBSCRIBE_DROP, and that every drop is final on its subscription, a stale (OLD) one included: a SUBSCRIBE_UPDATE reopens nothing, so the model leaves updates out. A skip still goes out over a drop of a group never served. Drops and skips travel in order on the Subscribe Stream, each Group Stream travels on its own, a reset can lose a stream's header, and a reset sent after the FIN may arrive after every byte. A publisher out of stream credit may reset a Group Stream with YIELDED, which pauses the group instead of accounting for it: the subscriber keeps the frames it read, and the publisher owes a continuation, a Group Stream that starts at the reset stream's own Frame Start, or a drop. A continuation may overtake the YIELDED reset, or even the header, of the stream it continues, and is the only second Group Stream of a group. Each model step is one poll of the code that handles one event. The track cursor's verdicts (hand a group out, give it up stale or final, skip it) are free choices, and so are when the publisher yields a stream and whether it continues a paused group or gives it up. With `Pressure`, so is when the cache pool's debt folds the publisher's record of a group. TLC checks every ordering under the bounds in the config. +`rs/moq-net/verify/subscribe/SubscribeAccounting.tla` models the groups of one answered lite-07 subscription between the publisher's `TrackRun` and the subscriber's `TrackServe`. The draft promises that every sequence in range gets a Group Stream, a SUBSCRIBE_SKIP, or a SUBSCRIBE_DROP, and that every drop is final on its subscription, a stale (OLD) one included: a SUBSCRIBE_UPDATE reopens nothing, so the model leaves updates out. A skip still goes out over a drop of a group never served. Drops and skips travel in order on the Subscribe Stream, each Group Stream travels on its own, and a reset can lose a stream's header. A Group Stream whose group expires stale is closed, not reset: a FIN without GROUP_END, so the subscriber keeps what arrived as a closed group and no drop names it. A stream that never opened is still given up with a drop, and one whose FIN went out is never reset for expiry. Each GROUP's Previous Start passes over the skipped run directly below it as a SUBSCRIBE_SKIP would, so the publisher holds such a skip back for the GROUP of a group it still owes, and sends it after all, ahead of the drop or joined to the skip, if it gives that group up instead. A drop of a group whose stream opened goes out after a skip of what its GROUP passed over, since the GROUP may never have arrived. A publisher out of stream credit may reset a Group Stream with YIELDED, which pauses the group instead of accounting for it: the subscriber keeps the frames it read, and the publisher owes a continuation, a Group Stream that starts at the reset stream's own Frame Start, or a drop. A continuation may overtake the YIELDED reset, or even the header, of the stream it continues, and is the only second Group Stream of a group. Each model step is one poll of the code that handles one event. The track cursor's verdicts (hand a group out, give it up stale or final, skip it) are free choices, and so are when the publisher yields a stream, whether it continues a paused group or gives it up, and whether the cache holds the group above a skip, which decides whether the skip is held back. With `Pressure`, so is when the cache pool's debt folds the publisher's record of a group. TLC checks every ordering under the bounds in the config. ## Rules @@ -14,8 +14,8 @@ Each rule is an INVARIANT; the harm says why it matters. | Rule | Holds when | Harm if broken | | --- | --- | --- | | `ServedOnce` | The publisher opens a second Group Stream for a group only to continue the group's latest stream, which it reset with YIELDED. | The group's bytes go out twice, or a continuation resumes a group nobody paused. | -| `NamedOnce` | The publisher names a group in at most one drop and at most one skip, and a skip only for a group it never served. | A second name contradicts a final one: the subscriber accounts the group twice or ends a reader on a group it delivered. | -| `QuietIsSettled` | Once nothing is in flight and the publisher has nothing left to do, the subscriber's tail accounts for every group. | The subscriber waits out its grace for a group nobody will send, and a relay holds its readers there. | +| `NamedOnce` | The publisher names a group in at most one drop and at most one skip, and a skip only for a group it never served. The one exception repeats a skip a GROUP passed over, once, ahead of that group's drop. | A second name contradicts a final one: the subscriber accounts the group twice or ends a reader on a group it delivered. | +| `QuietIsSettled` | Once nothing is in flight and the publisher has nothing left to do, the subscriber's tail accounts for every group, a skip held back for a GROUP included. | The subscriber waits out its grace for a group nobody will send, and a relay holds its readers there. | | `PausedIsOwed` | While the publisher owes a paused group, the subscriber's paused copy stays owed, unless a drop or skip, a stream read to its FIN, or a reset of another code that arrived with its header accounts for it. | The tail settles on a YIELDED reset alone and the subscription ends before the continuation arrives. | | `ContinuesWithinHeld` | A continuation that takes over a paused copy starts no later than the frames the copy holds (`Continuation.cfg`). | The subscriber treats the continuation as malformed, or a frame a reset discarded is never delivered. | | `OneReader` | The subscriber reads at most one Group Stream of a group at a time; a continuation waits, unread, for the stream it continues to end. | Two streams write one group's frames at once. | @@ -27,7 +27,7 @@ quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla -config rs/moq-net/verify/subscribe/Continuation.cfg ``` -The first checks every rule but `ContinuesWithinHeld` under `Pressure`, over two groups, six Group Streams, and two YIELDED resets per group, with frames left out: about 70.8M distinct states, twenty minutes. The second gives one group two frames and three YIELDED resets, without `Pressure`, so it also checks where each continuation starts: about 840K distinct states, ten seconds. Both pass. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. +The first checks every rule but `ContinuesWithinHeld` under `Pressure`, over two groups, 1 and 2 so a skip of 1 can be held back for 2's GROUP, six Group Streams, and two YIELDED resets per group, with frames left out: about 15.9M distinct states, four minutes. The second gives one group two frames and three YIELDED resets, without `Pressure`, so it also checks where each continuation starts and where an expired stream closes: about 493K distinct states, five seconds. Both pass. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. ## Reading a failure @@ -35,17 +35,18 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th ## Coverage -Sync commit: `e5b28598c3b581cd091cf3ec232c8fd59285bf49`. Run `git log e5b28598c3.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. +Sync commit: `157042024b139ef0153e1ab71ea40dfdf5e08993`. Run `git log 157042024b.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. | Code | Model | | --- | --- | -| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_track` (`Recv::Group`), `serve`, `mark_served`; `rs/moq-net/src/model/record.rs` `Record::told` | `CursorHand`, `Serve` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_track` (`Recv::Group`), `serve`, `mark_served`; `rs/moq-net/src/model/record.rs` `Record::told`; `rs/moq-net/src/model/track.rs` `TrackState::previous_start` | `CursorHand`, `Serve`, `SkippedBelow` | | `rs/moq-net/src/lite/publisher.rs` `TrackRun::give_way`, `shed` | a new group, or one shed, as `Serve`, then `StreamFail` with `old` whose header never arrives; a continuation as `StreamYield` of a stream whose header never arrives | | `rs/moq-net/src/lite/publisher.rs` `poll_forward_drop`, `forward_range`, `drop_range`, `report`, `hole`; `rs/moq-net/src/model/record.rs` `Record::report`, `tell`, `untold`, `Report::blocks` | `CursorGiveUp`, `dropped` | -| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_step` (outcomes) | `PubOutcomes` | -| `rs/moq-net/src/lite/publisher.rs` `GroupServe::poll_serve` (`Serve`, `Closed`), `settle_failed` | `StreamFin`, `StreamFail`, `StreamAck` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::elides`, `owes_group`, `send_elided` | `held`, the `hold` choice of `CursorGiveUp` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_step` (outcomes) | `PubOutcomes`, `nahead` | +| `rs/moq-net/src/lite/publisher.rs` `GroupServe::poll_serve` (`Serve`, `Closed`), `settle_failed`, `poll_stopped`, `closes_expired`, `Ending` | `StreamFin`, `StreamClose`, `StreamFail`, `StreamAck` | | `rs/moq-net/src/model/record.rs` `Record::fold` | `PubFold`, `folded` | -| `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::open`, `reopen`, `place`; `GroupRecv::poll_serve` (the duplicate wait) | `SubHeader`, `SubFin`, `SubReset`, `SubResetHeld` | +| `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::open` (with the passed-over skip), `reopen`, `place`; `GroupRecv::poll_serve` (the duplicate wait) | `SubHeader`, `SubFin`, `SubReset`, `SubResetHeld` | | `rs/moq-net/src/lite/subscriber.rs` `ServeLoop::apply_response` (`Drop`, `Skip`) | `OnDrop`, `OnSkip`, `SubRecv` | | `rs/moq-net/src/tail.rs` `Reading::open`, `Tail::account`, `accounts` | `acct`, `reading` | | `rs/moq-net/src/model/track.rs` `Producer::give_up`, `skip_received` | `rec`, `cached` | @@ -59,7 +60,9 @@ What the model asks of that code, each found by TLC as a broken rule without it: - A drop that reached a stream still being read ends its group once the YIELDED reset arrives (`TrackEntry::dropped`). The model leaves the copy paused and accounted; the code aborts the group with the drop's error, which the drop already accounted, so the tail settles either way. - A stream waits, held, while another stream of its group is still read, even one a final drop aborted, not only while the copy is open (`OneReader`). - The publisher serves no sequence its record already told, served or named (`Record::told`), and a skip goes out over a drop alone (`Report::blocks`), so a cursor that hands a group out again after giving it up, as after a route switch, sends nothing (`ServedOnce`, `NamedOnce`). +- A skip held back for a group's GROUP goes out once that group is given up instead: ahead of its drop (`drop_range`, `forward_range`), and joined to its skip, since no GROUP passes over it then (`forward_range`). A skip of the group above that kept the run held would leave it unsent for good (`QuietIsSettled`). +- A drop of a group whose stream opened, or that waited paused, goes out after a skip of what its GROUP passed over (`GroupOutcomes::dropped`), since a reset can lose the GROUP (`QuietIsSettled`). ## Not covered -The subscription starts answered and covers the groups, so SUBSCRIBE_OK, SUBSCRIBE_STARTED, ranges and Range IDs, fills (`RangeFills`) and the separate request (`Recovery`) a reader wider than a stale drop asks with, floors, SUBSCRIBE_UPDATE, and SUBSCRIBE_FINISH with `drop_unserved` are left out. The tail's grace and the ledger's folding are left out: `QuietIsSettled` asks for the publisher's answer, never the grace. So are priority and order (`Steer`), the Subscribe Stream's FIN and cancellation, sessions closing, versions before lite-07, relays forwarding drops downstream, the budget a relay records a stale drop under, datagrams, and the copy's readers (`poll_drop`). A route switch appears only as the cursor handing out once more a group it gave up. FETCH is left out: one request and one response, ended by a FIN or a reset, with nothing to race. GROUP_END takeover is left out: only the YIELDED reset pauses a group, and the publisher yields only a stream still serving. A pass covers two groups, six Group Streams, and two YIELDED resets per group, or one group of two frames with three YIELDED resets in `Continuation.cfg`. +The subscription starts answered and covers the groups, so SUBSCRIBE_OK, SUBSCRIBE_STARTED, ranges and Range IDs, fills (`RangeFills`) and the separate request (`Recovery`) a reader wider than a stale drop asks with, floors, SUBSCRIBE_UPDATE, and SUBSCRIBE_FINISH with `drop_unserved` are left out. The tail's grace and the ledger's folding are left out: `QuietIsSettled` asks for the publisher's answer, never the grace. So are priority and order (`Steer`), the Subscribe Stream's FIN and cancellation, sessions closing, versions before lite-07, relays forwarding drops downstream, the budget a relay records a stale drop under, datagrams, and the copy's readers (`poll_drop`). A route switch appears only as the cursor handing out once more a group it gave up. FETCH is left out: one request and one response, ended by a FIN or a reset, with nothing to race. GROUP_END takeover is left out: only the YIELDED reset pauses a group, and the publisher yields only a stream still serving. So is how much of a group an expired stream closes on, beyond `Continuation.cfg`'s two frames, and GROUP_END's End, which only says where a whole group ends. A GROUP's Previous Start is modeled as the skipped run directly below it; one naming a known group below, or nothing, passes over nothing, and a run released by an update (`release_elided`) is left out with updates. Runs are as long as the two groups allow, so a held run never grows past one group. A pass covers two groups, six Group Streams, and two YIELDED resets per group, or one group of two frames with three YIELDED resets in `Continuation.cfg`. diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg index a2f0b4f66b7..9b0f2461929 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg @@ -4,7 +4,7 @@ \* Pressure lets the publisher's record fold at any point. Frames are left out: \* Continuation.cfg checks where a continuation starts. CONSTANTS - Groups = {0, 1} + Groups = {1, 2} MaxStreams = 6 MaxPauses = 2 Frames = 0 diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla index 00ac8880cf0..160b5ffac13 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla @@ -13,6 +13,18 @@ (* order on the Subscribe Stream; each Group Stream travels on its own, *) (* unordered against them, and a reset can lose its header. *) (* *) +(* A lite-07 Group Stream whose group expires stale is closed, not reset: *) +(* FIN without GROUP_END, so the subscriber keeps what arrived as a closed *) +(* group, and no drop names it. A stream that never opened is still given *) +(* up with a drop, and a stream whose FIN went out is never reset for it. *) +(* *) +(* Each GROUP carries the previous group's start, passing over the *) +(* skipped starts directly below it as a SUBSCRIBE_SKIP would. The *) +(* publisher holds such a skip back for the GROUP of a group it still *) +(* owes, and sends it after all, ahead of the drop, if it gives that group *) +(* up instead. A drop of a group whose stream opened goes out after a *) +(* skip of what its GROUP passed over, since the GROUP may never arrive. *) +(* *) (* A publisher out of stream credit may reset a Group Stream with YIELDED, *) (* which pauses the group instead of accounting for it: the subscriber *) (* keeps the frames it read, and the publisher later continues the group *) @@ -25,11 +37,14 @@ (* it) are free choices, standing in for the cache, the clock, and the *) (* routes. So are when the publisher yields a stream, and whether it *) (* continues a paused group or gives it up, standing in for stream credit *) -(* and expiry. Under `Pressure`, so is when the pool's debt folds the *) -(* publisher's record of the group. *) +(* and expiry, and whether the cache holds the group above a skip, which *) +(* decides whether the skip is held back for its GROUP. Under `Pressure`, *) +(* so is when the pool's debt folds the publisher's record of the group. *) (* *) (* Scope: the subscription is already answered (SUBSCRIBE_OK) and covers *) (* every group; ranges, starts, fills, and the tail's grace are left out. *) +(* Group sequences start at 1 in `SubscribeAccounting.cfg`: a GROUP passes *) +(* over a run only above start 0, the previous start it then names. *) (* GROUP_END takeover is left out: only the YIELDED reset pauses a group. *) (***************************************************************************) EXTENDS Integers, Sequences, FiniteSets @@ -44,17 +59,20 @@ CONSTANTS \* A Group Stream: the publisher's side (`GroupState`), and the subscriber's. \* pub: "open" (serving), "fin" (FIN sent, awaiting its acknowledgement), \* "acked", or "reset" with `err` ("old", "evicted", or "yielded") -\* sub: "none" (no header yet, or lost with a reset), "header" (filling the copy), -\* "held" (waiting on the stream filling the copy), "fin", "reset", or "dup" +\* sub: "none" (no header yet, or lost with a reset), "never" (never opened, so +\* nothing reached the wire), "header" (filling the copy), "held" (waiting on +\* the stream filling the copy), "fin", "reset", or "dup" \* of: the stream this one continues, or 0 for a fresh one \* start: its Frame Start; wrote: frames the publisher wrote on it; read: frames the \* subscriber read from it -NewStream(g, of, start) == - [g |-> g, pub |-> "open", err |-> "", wasFin |-> FALSE, sub |-> "none", - of |-> of, start |-> start, wrote |-> 0, read |-> 0] +\* passes: the skipped groups its GROUP's Previous Start passes over +NewStream(g, of, start, passes) == + [g |-> g, pub |-> "open", err |-> "", sub |-> "none", of |-> of, + start |-> start, wrote |-> 0, read |-> 0, passes |-> passes] -DropMsg(g, err) == [type |-> "drop", g |-> g, err |-> err] -SkipMsg(g) == [type |-> "skip", g |-> g, err |-> ""] +\* A drop names one group; a skip names a run of them. +DropMsg(g, err) == [type |-> "drop", gs |-> {g}, err |-> err] +SkipMsg(gs) == [type |-> "skip", gs |-> gs, err |-> ""] Max(a, b) == IF a > b THEN a ELSE b @@ -65,12 +83,15 @@ VARIABLES \* The publisher's `TrackRun` and its reader's record. served, \* `Record::told`: sequences served or given up dropped, \* the part of `served` named in a drop, never served (`Report::Dropped`) - outq, \* `GroupOutcomes::dropped`: failed streams not yet named + outq, \* `GroupOutcomes::dropped`: failed streams not yet named, each with the + \* skipped groups its GROUP passed over + held, \* `TrackRun::elided`: per group, the skipped run held back for its GROUP folded, \* the record folded the group into its floor paused, \* the YIELDED stream a paused group waits to continue, or 0 pauses, \* YIELDED resets sent for the group ndrop, \* history: drops naming the group - nskip, \* history: skips naming the group + nskip, \* history: skips naming the group on their own + nahead, \* history: skips naming the group again, ahead of a drop of the group above \* The wire. streams, \* every Group Stream opened, in order resp, \* the Subscribe Stream, publisher to subscriber @@ -84,8 +105,8 @@ VARIABLES got, \* history: the subscriber read the group to its FIN malformed \* a continuation started past the frames the copy holds -names == <> -pubVars == <> +names == <> +pubVars == <> subVars == <> vars == <> @@ -93,10 +114,12 @@ Init == /\ cur = [g \in Groups |-> "pending"] /\ late = [g \in Groups |-> FALSE] /\ served = {} /\ dropped = {} /\ outq = <<>> /\ folded = {} + /\ held = [g \in Groups |-> {}] /\ paused = [g \in Groups |-> 0] /\ pauses = [g \in Groups |-> 0] /\ ndrop = [g \in Groups |-> 0] /\ nskip = [g \in Groups |-> 0] + /\ nahead = [g \in Groups |-> 0] /\ streams = <<>> /\ resp = <<>> /\ acct = {} /\ reading = {} /\ sdrop = {} /\ rec = [g \in Groups |-> "none"] @@ -109,11 +132,19 @@ Init == (* Publisher *) ----------------------------------------------------------------------------- -\* `serve`: open a Group Stream for g, which `mark_served` records. +\* The skipped run directly below g, which g's GROUP passes over (`previous_start`): its +\* Previous Start names the start below the run, so the run starts above 0. +SkippedBelow(g) == + LET below == {x \in Groups : x < g /\ \A y \in x..g - 1 : y \in Groups /\ cur[y] = "skip"} + IN IF 0 \in below THEN {} ELSE below + +\* `serve`: open a Group Stream for g, which `mark_served` records. Its GROUP passes over +\* the skipped run below it, the one held back for it included. Serve(g) == /\ Len(streams) < MaxStreams - /\ streams' = Append(streams, NewStream(g, 0, 0)) + /\ streams' = Append(streams, NewStream(g, 0, 0, SkippedBelow(g))) /\ served' = served \cup {g} + /\ held' = [held EXCEPT ![g] = {}] \* `poll_track` takes `Recv::Group`: the cursor hands g out. Once more, it may hand out a \* group it gave up: one a route the front switched to delivers after a stale verdict, or @@ -126,30 +157,46 @@ CursorHand(g) == \/ cur[g] \in {"stale", "final"} /\ ~late[g] /\ late' = [late EXCEPT ![g] = TRUE] /\ cur' = [cur EXCEPT ![g] = "handed"] /\ IF g \in served - THEN UNCHANGED <> + THEN UNCHANGED <> ELSE Serve(g) /\ UNCHANGED <> +\* Count each group of `gs` named once more in `n`. +Named(n, gs) == [x \in Groups |-> IF x \in gs THEN n[x] + 1 ELSE n[x]] + \* `poll_forward_drop`: the cursor gives g up stale ("old"), final ("evicted"), or \* declares it skipped, after `poll_step` named failed streams. A later verdict may follow \* an earlier one. `forward_range` sends it only where the record has told nothing, or, for -\* a skip, only a drop (`Report::blocks`). -CursorGiveUp(g, kind) == +\* a skip, only a drop (`Report::blocks`). A run held back for g's GROUP goes out ahead of +\* g's drop, or joins g's skip. That skip is held back in turn for the GROUP of the group +\* above, if the subscription still owes it (`elides`): `hold` stands in for whether the +\* cache holds that group. +CursorGiveUp(g, kind, hold) == /\ outq = <<>> /\ \/ cur[g] = "pending" \/ cur[g] = "stale" /\ kind \in {"evicted", "skip"} \/ cur[g] = "final" /\ kind = "skip" /\ cur' = [cur EXCEPT ![g] = IF kind = "old" THEN "stale" ELSE IF kind = "skip" THEN "skip" ELSE "final"] /\ LET named == g \notin served \/ (kind = "skip" /\ g \in dropped) - IN /\ served' = served \cup {g} + run == held[g] \cup {g} + above == g + 1 + elides == kind = "skip" /\ above \in Groups /\ above \notin served /\ 0 \notin run + IN /\ hold => named /\ elides + /\ served' = served \cup {g} /\ dropped' = IF ~named THEN dropped ELSE IF kind = "skip" THEN dropped \ {g} ELSE dropped \cup {g} - /\ resp' = IF ~named THEN resp - ELSE IF kind = "skip" THEN Append(resp, SkipMsg(g)) - ELSE Append(resp, DropMsg(g, kind)) + /\ held' = CASE ~named -> held + [] hold -> [held EXCEPT ![g] = {}, ![above] = @ \cup run] + [] OTHER -> [held EXCEPT ![g] = {}] + /\ resp' = CASE ~named \/ hold -> resp + [] kind = "skip" -> Append(resp, SkipMsg(run)) + [] held[g] # {} -> resp \o <> + [] OTHER -> Append(resp, DropMsg(g, kind)) /\ ndrop' = IF named /\ kind # "skip" THEN [ndrop EXCEPT ![g] = @ + 1] ELSE ndrop - /\ nskip' = IF named /\ kind = "skip" THEN [nskip EXCEPT ![g] = @ + 1] ELSE nskip - /\ UNCHANGED <> + /\ nskip' = CASE ~named \/ hold -> nskip + [] kind = "skip" -> Named(nskip, run) + [] OTHER -> Named(nskip, held[g]) + /\ UNCHANGED <> \* A serving stream writes its next frame. StreamWriteAt(i) == @@ -165,15 +212,25 @@ StreamFinAt(i) == /\ streams' = [streams EXCEPT ![i].pub = "fin"] /\ UNCHANGED <> -\* A stream fails and resets: it expires stale while serving or while its FIN awaits -\* the acknowledgement, or is evicted while serving. `settle_failed` queues the outcome. +\* A serving stream's group expires stale (`Ending::Expired`): the stream FINs at the next +\* frame boundary without a GROUP_END, and what it wrote stands as a closed group. Nothing +\* names the group. With frames left out, this is `StreamFin`. +StreamCloseAt(i) == + /\ streams[i].pub = "open" + /\ streams[i].start + streams[i].wrote < Frames + /\ streams' = [streams EXCEPT ![i].pub = "fin"] + /\ UNCHANGED <> + +\* A stream fails and resets: it is evicted while serving, or expires stale before it +\* opened, waiting for stream credit (`give_way`, `shed`), so nothing of it reached the +\* wire. `settle_failed` queues the outcome, with what its GROUP passed over. StreamFailAt(i, err) == - /\ \/ streams[i].pub = "open" - \/ streams[i].pub = "fin" /\ err = "old" + /\ streams[i].pub = "open" + /\ err = "old" => streams[i].sub = "none" /\ streams[i].wrote = 0 /\ streams' = [streams EXCEPT ![i].pub = "reset", ![i].err = err, - ![i].wasFin = (streams[i].pub = "fin")] - /\ outq' = Append(outq, <>) - /\ UNCHANGED <> + ![i].sub = IF err = "old" THEN "never" ELSE @] + /\ outq' = Append(outq, <>) + /\ UNCHANGED <> \* Out of stream credit, the publisher resets a serving stream with YIELDED. The group is \* paused, not given up: nothing names it, and the publisher owes a continuation or a drop. @@ -183,25 +240,26 @@ StreamYieldAt(i) == /\ streams' = [streams EXCEPT ![i].pub = "reset", ![i].err = "yielded"] /\ paused' = [paused EXCEPT ![streams[i].g] = i] /\ pauses' = [pauses EXCEPT ![streams[i].g] = @ + 1] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The publisher continues a paused group on a new Group Stream, from the YIELDED -\* stream's own Frame Start: a reset can discard frames the transport acknowledged. +\* stream's own Frame Start: a reset can discard frames the transport acknowledged. Its +\* GROUP carries the same Previous Start. PubContinue(g) == /\ paused[g] # 0 /\ Len(streams) < MaxStreams /\ LET k == paused[g] - IN streams' = Append(streams, NewStream(g, k, streams[k].start)) + IN streams' = Append(streams, NewStream(g, k, streams[k].start, streams[k].passes)) /\ paused' = [paused EXCEPT ![g] = 0] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The publisher gives a paused group up instead, as it would the stream it yielded: \* it expires stale under the delivery budget, or is evicted. PausedGiveUp(g, err) == /\ paused[g] # 0 /\ paused' = [paused EXCEPT ![g] = 0] - /\ outq' = Append(outq, <>) - /\ UNCHANGED <> + /\ outq' = Append(outq, <>) + /\ UNCHANGED <> \* The peer acknowledged everything up to the FIN. StreamAckAt(i) == @@ -211,13 +269,19 @@ StreamAckAt(i) == /\ UNCHANGED <> \* `poll_step` names each failed stream in a drop with its error, final like any other: -\* the group was served, so nothing serves or names it again. +\* the group was served, so nothing serves or names it again. A skip of what its GROUP +\* passed over goes first, since the GROUP may never have arrived, even where a skip +\* already named it. PubOutcomes == /\ outq # <<>> /\ outq' = Tail(outq) - /\ resp' = Append(resp, DropMsg(Head(outq)[1], Head(outq)[2])) - /\ ndrop' = [ndrop EXCEPT ![Head(outq)[1]] = @ + 1] - /\ UNCHANGED <> + /\ LET g == Head(outq)[1] + drop == DropMsg(g, Head(outq)[2]) + passes == Head(outq)[3] + IN /\ resp' = IF passes = {} THEN Append(resp, drop) ELSE resp \o <> + /\ ndrop' = [ndrop EXCEPT ![g] = @ + 1] + /\ nahead' = Named(nahead, passes) + /\ UNCHANGED <> \* The pool hands the reader debt and its record folds the group into its floor: a group \* the cursor reached a verdict on, once no failed stream of it is still to name. Every @@ -229,7 +293,7 @@ PubFold(g) == /\ \A i \in 1..Len(outq) : outq[i][1] # g /\ folded' = folded \cup {g} /\ dropped' = dropped \ {g} - /\ UNCHANGED <> + /\ UNCHANGED <> ----------------------------------------------------------------------------- (* Subscriber *) @@ -249,33 +313,43 @@ Settled(g) == g \in acct /\ g \notin reading \* The first of them, which takes the copy over once the filling stream ends. NextHeld(g) == {j \in Held(g) : \A k \in Held(g) : j <= k} +\* The copy's record `r` once a skip names `gs`: a group that arrived keeps it +\* (`skip_received`). +SkipRec(r, gs) == [x \in Groups |-> IF x \in gs /\ cached[x] \notin {"open", "whole"} THEN "skip" ELSE r[x]] + \* A Group Stream's header arrives (`TrackEntry::open`, `Reading::open`): the tail \* accounts for the group. It fills the copy and replaces a stale record of it, unless \* another stream of it is still read (`Open::Duplicate`, held until that one settles) \* or the copy holds the group whole (`Error::Duplicate`). Into a paused copy it -\* continues the group: the copy ignores the frames it holds and appends the rest. +\* continues the group: the copy ignores the frames it holds and appends the rest. Every +\* GROUP's Previous Start skips what it passes over, as a SUBSCRIBE_SKIP would; a +\* continuation's repeats its paused stream's, which already did. SubHeaderAt(i) == /\ streams[i].sub = "none" /\ streams[i].pub \in {"open", "fin", "reset"} /\ LET g == streams[i].g - IN /\ acct' = acct \cup {g} + passes == streams[i].passes + unstale == [rec EXCEPT ![g] = IF @ = "stale" THEN "none" ELSE @] + IN /\ acct' = acct \cup {g} \cup passes /\ CASE Filling(g) \/ cached[g] = "open" -> /\ streams' = [streams EXCEPT ![i].sub = "held"] - /\ UNCHANGED <> + /\ rec' = SkipRec(rec, passes) + /\ UNCHANGED <> [] cached[g] = "whole" -> /\ streams' = [streams EXCEPT ![i].sub = "dup"] - /\ UNCHANGED <> + /\ rec' = SkipRec(rec, passes) + /\ UNCHANGED <> [] cached[g] = "paused" -> /\ streams' = [streams EXCEPT ![i].sub = "header"] /\ cached' = [cached EXCEPT ![g] = "open"] - /\ rec' = [rec EXCEPT ![g] = IF @ = "stale" THEN "none" ELSE @] + /\ rec' = SkipRec(unstale, passes) /\ malformed' = (malformed \/ streams[i].start > have[g]) /\ reading' = IF Settled(g) THEN reading ELSE reading \cup {g} /\ UNCHANGED have [] OTHER -> /\ streams' = [streams EXCEPT ![i].sub = "header"] /\ cached' = [cached EXCEPT ![g] = "open"] - /\ rec' = [rec EXCEPT ![g] = IF @ = "stale" THEN "none" ELSE @] + /\ rec' = SkipRec(unstale, passes) /\ have' = [have EXCEPT ![g] = streams[i].start] /\ reading' = IF Settled(g) THEN reading ELSE reading \cup {g} /\ UNCHANGED malformed @@ -290,14 +364,13 @@ SubFrameAt(i) == /\ have' = [have EXCEPT ![streams[i].g] = Max(@, streams[i].start + streams[i].read + 1)] /\ UNCHANGED <> -\* The stream filling the copy is read to its FIN; once every byte arrived, a reset sent -\* after the FIN changes nothing. A held stream of the group then only duplicates it, a -\* continuation included. +\* The stream filling the copy is read to its FIN: the group is whole after a GROUP_END, +\* or closed where an expired one stopped, which the copy keeps alike ("whole"). A held +\* stream of the group then only duplicates it, a continuation included. SubFinAt(i) == /\ streams[i].sub = "header" /\ streams[i].read = streams[i].wrote - /\ \/ streams[i].pub \in {"fin", "acked"} - \/ streams[i].pub = "reset" /\ streams[i].wasFin + /\ streams[i].pub \in {"fin", "acked"} /\ LET g == streams[i].g IN /\ streams' = [j \in 1..Len(streams) |-> IF j = i THEN [streams[j] EXCEPT !.sub = "fin"] @@ -363,7 +436,7 @@ Evict(g) == \* until it finishes ("whole" here) or dies, when the drop is the slot's cut \* (`Slot::verdict`): never lost, never beside a group. OnDrop(m) == - LET g == m.g + LET g == CHOOSE g \in m.gs : TRUE IN /\ acct' = acct \cup {g} /\ sdrop' = sdrop \cup {g} /\ IF m.err = "old" @@ -376,10 +449,9 @@ OnDrop(m) == \* `apply_response` for SUBSCRIBE_SKIP: final, overriding any drop, but a group that \* arrived keeps it (`skip_received`). OnSkip(m) == - LET g == m.g - IN /\ acct' = acct \cup {g} - /\ rec' = IF cached[g] \in {"open", "whole"} THEN rec ELSE [rec EXCEPT ![g] = "skip"] - /\ UNCHANGED <> + /\ acct' = acct \cup m.gs + /\ rec' = SkipRec(rec, m.gs) + /\ UNCHANGED <> SubRecv == /\ resp # <<>> @@ -391,10 +463,10 @@ SubRecv == ----------------------------------------------------------------------------- \* A stream is done once both sides stopped: acknowledged, or reset with the header -\* read to the reset or lost. +\* read to the reset, lost, or never sent. StreamDone(s) == \/ s.pub = "acked" - \/ s.pub = "reset" /\ s.sub \in {"none", "fin", "reset", "dup"} + \/ s.pub = "reset" /\ s.sub \in {"none", "never", "fin", "reset", "dup"} \* Nothing in flight and nothing left for the publisher to do. Quiet == @@ -410,6 +482,7 @@ Done == \* Each action over the streams, named so a trace says which one ran. StreamWrite == \E i \in 1..Len(streams) : StreamWriteAt(i) StreamFin == \E i \in 1..Len(streams) : StreamFinAt(i) +StreamClose == \E i \in 1..Len(streams) : StreamCloseAt(i) StreamFail == \E i \in 1..Len(streams), err \in {"old", "evicted"} : StreamFailAt(i, err) StreamYield == \E i \in 1..Len(streams) : StreamYieldAt(i) StreamAck == \E i \in 1..Len(streams) : StreamAckAt(i) @@ -421,9 +494,10 @@ SubResetHeld == \E i \in 1..Len(streams) : SubResetHeldAt(i) Next == \/ \E g \in Groups : CursorHand(g) - \/ \E g \in Groups, kind \in {"old", "evicted", "skip"} : CursorGiveUp(g, kind) + \/ \E g \in Groups, kind \in {"old", "evicted", "skip"}, hold \in BOOLEAN : CursorGiveUp(g, kind, hold) \/ StreamWrite \/ StreamFin + \/ StreamClose \/ StreamFail \/ StreamYield \/ StreamAck @@ -462,11 +536,14 @@ ServedOnce == \* Every name is final: the publisher names a group in at most one drop, and in at most \* one skip, which goes out over a drop of a group it never served and over nothing else. +\* The one exception is a skip of a run a GROUP passed over, repeated once ahead of that +\* group's drop. Neither ever names a group that has a Group Stream. NamedOnce == \A g \in Groups : /\ ndrop[g] <= 1 /\ nskip[g] <= 1 - /\ nskip[g] = 1 => \A i \in 1..Len(streams) : streams[i].g # g + /\ nahead[g] <= 1 + /\ nskip[g] + nahead[g] > 0 => \A i \in 1..Len(streams) : streams[i].g # g \* A YIELDED reset alone never accounts for a group: while the publisher owes a paused \* group its continuation or drop, the subscriber's paused copy stays owed. Only what else From ba6a5576a23bef8c07efb0f47c676a1c28765951 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:10:35 -0800 Subject: [PATCH 18/26] quest: lite-07 addresses groups by start is done Deletes the quest and its links, and moves GROUP's Frame Start and the model's YIELDED half to the YIELDED deferral, which still owns them. Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 4 +- quest/m2/README.md | 2 +- quest/m2/group-drops.md | 8 +- quest/m2/lite07-finalize.md | 12 +- quest/m2/min-age-join.md | 1 - quest/m2/refresh-interval.md | 10 +- quest/m2/time-addressing/consumers.md | 1 - quest/m2/time-addressing/js.md | 6 +- quest/m2/time-addressing/lite07.md | 193 -------------------------- quest/m2/unused-api/js.md | 4 +- quest/m2/yield-defer.md | 24 ++-- quest/m3/e2ee-format.md | 3 +- quest/m3/group-takeover.md | 3 +- quest/m3/time-addressing-guide.md | 6 +- quest/m5/e2ee/README.md | 2 +- quest/m5/probe-padding.md | 2 +- 16 files changed, 33 insertions(+), 248 deletions(-) delete mode 100644 quest/m2/time-addressing/lite07.md diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 49b48c89f3b..39666614b36 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -295,7 +295,9 @@ Ranges are both a request and a filter. A subscriber reads only the groups its own ranges cover, resolved again whenever it replaces them, even when another subscriber of the same track asked for more. Widening them, including lowering the start, also serves the cached groups they newly cover, never one already -served. A reader that has accounted for every group its bounded ranges cover +served or reported. A report is final: raising max delay afterwards does not +bring back a group reported `OLD`, though a relay whose own reader allows more +asks upstream for it again. A reader that has accounted for every group its bounded ranges cover ends, and repeated reads end immediately too. Widening the ranges resumes reading. A moq-lite-07 publisher ends a bounded subscription once it covered it, and the copy stays cached for the same ranges until an update asks for groups it did not diff --git a/quest/m2/README.md b/quest/m2/README.md index 42df4d4cfa6..1923be8abc4 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -25,7 +25,7 @@ removal, a rename, or a wire, catalog, or format change that is free until costs nothing on a moq-lite track; [the path escape](/quest/m2/path-escape.md) is finished; [Subscriber Min Age](/quest/m2/min-age-join.md) stays and gains its reader, reversing 2026-11-14; and - [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries the + [lite-07 by start](https://github.com/moq-dev/moq/pull/8908) carries the smaller wire fixes. [Refresh](/quest/m2/refresh-interval.md) and [group drops](/quest/m2/group-drops.md) took simpler contracts. [moq-transport time addressing](/quest/m2/ietf-time-addressing.md) diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 69d44aa0fe5..cc62806cda2 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -61,10 +61,9 @@ wire at every hop for a number few readers use. A reader that needs a count measures what it lost in time, which the span gives, or counts the groups it did receive. So "count losses" in the Goal means account for every span: the receive-windows benchmark's overcommitted cells finish when delivered -groups plus reported spans cover everything sent. At HEAD -`SubscribeDrop`'s `Group Count` (`rs/moq-net/src/lite/subscribe.rs`) is a -count of keys, which [the wire rewrite](/quest/m2/time-addressing/lite07.md) -turns into the span's end. +groups plus reported spans cover everything sent. Since +[the wire rewrite](https://github.com/moq-dev/moq/pull/8908) `SubscribeDrop` +(`rs/moq-net/src/lite/subscribe.rs`) carries the span's exclusive end. Public API: breaking for `track::Ordered` only. Its one read, `poll_next_group` (and its async wrapper), returns @@ -79,5 +78,4 @@ Wire: none. ## Related -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - SUBSCRIBE_DROP names the time spans `Gap` reports - [The receive-windows benchmark](/quest/m3/receive-windows-evicted.md) - its overcommitted cells wait on this (skipped by [moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838) until it lands) diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index 3646a454881..706adc51f71 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -116,7 +116,7 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): Required names every quest that may still change lite-07 bytes. The explicit `Oldest` anchor rides [time addressing's model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md), -whose lite-07 encoding [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries. +whose lite-07 encoding [lite-07 by start](https://github.com/moq-dev/moq/pull/8908) carries. Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about moq-net): ✅ the cut waits for the symbolic model of the Route Key Parameter @@ -184,10 +184,11 @@ audited the lite-07 draft for what it could lose): negotiating with today's behaviour; the hidden `.` path prefix; and the route plan of [cache-aware multicast](/quest/m2/multicast/README.md) (rejected: routing as a separately versioned SETUP extension). -- The smaller wire fixes ride [lite-07 by start](/quest/m2/time-addressing/lite07.md), - which rewrites the same messages: Max Age as value plus one, no GROUP - `Frame Start`, no Padding stream or datagram type, a kind in the track - listing, and drops as spans with no count. +- The smaller wire fixes rode [lite-07 by start](https://github.com/moq-dev/moq/pull/8908): + Max Age as value plus one, no Padding stream or datagram type, a kind in + the track listing, and drops as spans with no count. GROUP `Frame Start` + leaves with [YIELDED deferred](/quest/m2/yield-defer.md), since a + continuation still sets it. - Not reopened: AUTH_ERROR's retry codes (2026-11-14) and AUTH_OK's rate fields, which wait for lite-08 ([rate grant](/quest/m5/rate-grant.md)). @@ -203,7 +204,6 @@ the version that ships them. - [Min Age join](/quest/m2/min-age-join.md) - makes Subscriber Min Age normative - [Cache-aware multicast](/quest/m2/multicast/README.md) - lite-07 carries the redesigned route layer: routes to forwarding nodes, no holds or doubt, claims crossing trust boundaries by a chain, and no Route Key - [Routes and announces](/quest/m2/cluster-routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the native hop list gone (only the temporary lite-06 compatibility chain remains) -- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire ## Related diff --git a/quest/m2/min-age-join.md b/quest/m2/min-age-join.md index 69e76eed1ea..1805276f31d 100644 --- a/quest/m2/min-age-join.md +++ b/quest/m2/min-age-join.md @@ -85,5 +85,4 @@ the aggregate rule changes if the recommendation is taken. ## Related -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - rewrites the same SUBSCRIBE fields, and gives the group starts this measures by - [Refresh a track by interval](/quest/m2/refresh-interval.md) - the other thing a live join does: it may ask for a new group diff --git a/quest/m2/refresh-interval.md b/quest/m2/refresh-interval.md index 00b77de809f..cb17e4bb8a6 100644 --- a/quest/m2/refresh-interval.md +++ b/quest/m2/refresh-interval.md @@ -48,7 +48,7 @@ Decided 2026-11-13: Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - ✅ `refresh()` takes no argument and raises `Wanted Group`, which - [time addressing](/quest/m2/time-addressing/lite07.md) makes a start + [time addressing](https://github.com/moq-dev/moq/pull/8908) makes a start time: the node asks for a group that starts after the newest it holds (rejected: a request counter riding SUBSCRIBE_UPDATE's update number, with every group tagged by the highest update its publisher had seen, @@ -123,8 +123,8 @@ Recommendations for the PR: - Update the lite draft (TRACK_INFO's interval, `Wanted Group`'s text, and the changelog), `doc/concept/moq-lite.md`, and the matching JS. Run `just test interop --all`. -- Land after [time addressing](/quest/m2/time-addressing/lite07.md), so - `Wanted Group` is written once, as a time. +- `Wanted Group` is `Wanted Start` since [time addressing](https://github.com/moq-dev/moq/pull/8908): + the wanted group's start plus one. Tests: a relay chain where many readers join and call `refresh()` on a one-frame track produces one group per interval at the publisher, with time @@ -137,10 +137,6 @@ the bindings; additive otherwise (`refresh()`, the interval on `Info`). Wire: lite-07-wip TRACK_INFO gains the interval; SUBSCRIBE_UPDATE keeps `Wanted Group` and gains nothing. -## Required - -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - `Wanted Group` becomes the start time this requests by - ## Related - [Hang thumbnails](/quest/m4/hang-thumbnail.md) - the one-frame track this refreshes diff --git a/quest/m2/time-addressing/consumers.md b/quest/m2/time-addressing/consumers.md index 3634505149a..a2e1aa42112 100644 --- a/quest/m2/time-addressing/consumers.md +++ b/quest/m2/time-addressing/consumers.md @@ -135,7 +135,6 @@ them. ## Required - [@moq/net by start](/quest/m2/time-addressing/js.md) - the JS API these consume -- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - GROUP_END carries the end the duration marker did ## Related diff --git a/quest/m2/time-addressing/js.md b/quest/m2/time-addressing/js.md index 6a60cc8dcf6..77e89d25b0c 100644 --- a/quest/m2/time-addressing/js.md +++ b/quest/m2/time-addressing/js.md @@ -8,7 +8,7 @@ model, lite-07 wire, and legacy mapping, with the same names. ## Plan Mirror [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) and -[the lite-07 wire](/quest/m2/time-addressing/lite07.md), including strictly +[the lite-07 wire](https://github.com/moq-dev/moq/pull/8908), including strictly increasing starts, the three group ends, reach from a group's own end, and `Relative(n)` counting groups. The gap machinery that assumes `sequence + 1` (`delivered.ts`, `ledger.ts`, `track.ts`, `resume.ts`) follows @@ -47,7 +47,3 @@ inside the class (`js/net/src/time.ts:53`, `:128`) with one caller, key stays as decided 2026-11-08. Public API: breaking, mirroring Rust's. Wire: as the lite-07 quest. - -## Required - -- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - the wire this speaks diff --git a/quest/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md deleted file mode 100644 index 0f03820d24d..00000000000 --- a/quest/m2/time-addressing/lite07.md +++ /dev/null @@ -1,193 +0,0 @@ -# [L] The lite-07 wire addresses groups by start - -## Goal - -moq-lite-07 carries no group sequence numbers: a GROUP names its start and -its predecessor's start, GROUP_END says where a whole group ends, and every -subscription bound and drop is a time. Datagrams keep a sequence of their own on their own track kind. Rust speaks it, the lite -draft specifies it, and lite-01..06 are unchanged. - -The same rewrite carries the smaller lite-07 fixes the pre-cut audit decided -on 2026-11-16, listed in the Plan: an encoding for "no limit" in -`Subscriber Max Age`, GROUP without `Frame Start`, no Padding stream or -datagram, and a track listing that says each track's kind. - -## Plan - -Decided 2026-10-25 (maintainer), from the spike: - -- **GROUP** carries the start and the previous group's start, absent for the - first group of an epoch, so a cache or reader sees a hole without a round - trip. -- **GROUP_END** carries the group's exclusive end timestamp, meaning the - group is whole. A bare FIN means an incomplete group whose frames all - arrived, and a reset aborts. A relay closes an expired or partial group - instead of resetting it, which changes the draft's reset rule for those - groups (around line 760). -- SUBSCRIBE and SUBSCRIBE_UPDATE bounds, SUBSCRIBE_OK's largest and its Range - Starts, SUBSCRIBE_STARTED, SUBSCRIBE_FINISH, SUBSCRIBE_SKIP, and SUBSCRIBE_DROP - address by start. Datagrams keep their own sequence (maintainer, 2026-11-01). Drops - name time spans with no group to deliver, not sequence ranges. `Relative(n)` - stays a group count. -- Positions stay (start, frame index), preserving transport frame offsets. -- SUBSCRIBE_UPDATE's `Wanted Group` (a sequence plus one) and SUBSCRIBE_OK's - `Group` and `Largest Group` are sequences too, and change with the rest. -- `Timescale` 0 stays and means scale-less: keys and frame timestamps are - bare numbers, and a scale-less frame carries its group's key (decided - 2026-11-03, maintainer: ingested legacy tracks with bare keys still cross - lite-07; see [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md)). FRAME and - datagrams always carry a timestamp. The untimed cases of - TIMESTAMP_MISMATCH, Time anchors, and arrival-age-only expiry become the - scale-less cases. The rule that a Group's frame - 0 not start before a lower-sequence Group's becomes the strictly - increasing start. - -SUBSCRIBE_OK also says whether the newest group it reports has already ended -(finished or closed), so a reader joining a cached track knows at once -whether that group is the live one. Added 2026-11-04 (maintainer) from -Kixel's T3 readers, which today infer it by waiting a moment for the group's end after -its last frame, because the end only follows the last frame. It rides this -quest's SUBSCRIBE_OK change instead of a later wire bump. - -Update `drafts/draft-lcurley-moq-lite.md` (fields, the group-end rules, and the -lite-07 changelog) and `doc/concept/moq-lite.md`, and run `just drafts check` -and `just test interop --all`. - -Also reword `drafts/draft-lcurley-moq-e2ee.md`, which still calls the nonce's -group input a sequence (its group-allocation rule, about line 268): it is the -group's start, strictly increasing. The nonce bytes don't change, since both -the Rust and JS cores already feed it the group's wire ID, which -[the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) makes the start. Folded in -2026-11-14 from the removed E2EE nonce quest (the m2 triage before the cut, -under /quest-afk, for the maintainer's review), since this PR's rename -outdates that wording. - -Decided 2026-11-05 (maintainer, /quest-audit): ✅ this waits for -Lite-07 FETCH is single-group only ([moq-dev/moq#8616](https://github.com/moq-dev/moq/pull/8616)), -which rewrites the same lite-07 draft sections (`Range`, Positions, -SUBSCRIBE anchors). - -Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): -reopening stale (OLD) drops is overbuilt for what it serves. Every -SUBSCRIBE_UPDATE reopens every OLD drop, and a relay settles a received stale -drop only for readers within budget and range; it took 27 recorded decisions -in [moq-dev/moq#7670](https://github.com/moq-dev/moq/pull/7670), then -[moq-dev/moq#8546](https://github.com/moq-dev/moq/pull/8546), -[moq-dev/moq#8551](https://github.com/moq-dev/moq/pull/8551), and -[moq-dev/moq#8584](https://github.com/moq-dev/moq/pull/8584), and still has -an open model finding (`StreamWins.cfg`, which the finished-across-updates -quest owned until it was deleted on 2026-11-16: its premise was this -reopen). The case it serves is a relay reader whose budget widens after the upstream -dropped a group as OLD. Since this quest rewrites SUBSCRIBE_DROP, -SUBSCRIBE_UPDATE, and SUBSCRIBE_SKIP anyway, it can make OLD final on its -subscription: the widening reader asks with a SUBSCRIBE of its own, as the -draft already requires for delivered or finally dropped groups, and the -`Update` numbers, re-offers, reopen rules, and their model configs go. Also -check whether GROUP's previous-start link makes SUBSCRIBE_SKIP redundant. -The review wrote that YIELDED continuations would keep their hold; on -2026-11-16 they left lite-07 too ([YIELDED deferred](/quest/m2/yield-defer.md)), -so after both PRs a group has a second stream on one subscription only as -a duplicate, and no "held unread until the earlier stream ends" rule -remains for this rewrite to preserve. - -Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) OLD drops are final on their subscription: this rewrite deletes `Update`, the reopen and re-offer paths, and their model configs (rejected: (b) keep reopening and finish the finished-across-updates quest, deleted 2026-11-16). - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit). These -ride this PR because it already rewrites the messages they touch, and each -is free only until lite-07 freezes: - -- ✅ SUBSCRIBE and SUBSCRIBE_UPDATE encode `Subscriber Max Age` as - milliseconds plus one, 0 meaning no limit (rejected: write 2^53 - 1 into - the draft as "no limit"; leave it). FETCH's field of the same name and - TRACK_INFO's `Publisher Max Age` already do. Today Rust sends - `MAX_SAFE_DELAY_MS = 2^53 - 1` for `Delay::max == None` - (`rs/moq-net/src/lite/publisher.rs:119`, `lite/subscriber.rs:12354`) and - JS sends `NO_MAX_DELAY = Varint.MAX_U53` and reads it back by comparison - (`js/net/src/internal.ts:41`, `js/net/src/fill.ts:626`). The draft never - names that value, and a third implementation that picks a larger - "forever" is refused by JS's 53-bit read. Both constants go on lite-07. -- ✅ GROUP loses `Frame Start` (rejected: keep it and state the one case - that sets it). A subscription delivers whole groups, FETCH has no GROUP - header, and the last case that set it, a continuation, leaves with - [YIELDED](/quest/m2/yield-defer.md). The Rust publisher says "A lite-07 - range covers whole groups, so it has none", and JS sets `frameStart` only - from a lite-06 SUBSCRIBE's bound. Before deleting it, grep both - publishers for a lite-07 path that opens a Group Stream past frame 0; if - yield-defer has not landed, the continuation is one, and the field goes - with whichever PR lands second. lite-06 keeps its field. -- ✅ The Padding Stream (0x2) and Padding Datagram (0x1) types are removed; - the datagram `Type` stays (rejected: keep the datagram one, as the - 2026-10-30 decision preferred; keep both). Both are received and - discarded, nothing sends either outside a test and a benchmark, and their - one planned sender is parked with no named consumer - ([probe padding](/quest/m5/probe-padding.md), which would add its type - back in a later version or an extension). An unknown - stream type is reset and an unknown datagram type discarded, so adding - either back later touches no message a lite-07 peer parses. -- ✅ The track listing carries each track's kind, so a datagram track can be - listed (rejected: datagram tracks move to an extension draft; listings - never show them). Datagram tracks stay in core with everything they have - today, including the lite-05/06 group-datagram bridge and the bindings: a - named consumer wants them. Today "TRACK_INFO does not say which kind a - Track is", so `a_datagram_track_is_never_listed` - (`rs/moq-net/src/model/listing.rs`). Recommended shape: TRACKS_ADD gains a - `Kind` before its info, which is then a TRACK_INFO or a DATAGRAMS_INFO; - the model's listing entry, `@moq/net`, and the bindings' listing report - the kind, which is additive there. - -- ✅ SUBSCRIBE_DROP names a span and carries no group count (rejected: a - count, which would also have let SUBSCRIBE_SKIP become a drop with a - count of 0). Today's `Group Count` is a count of keys, so it becomes the - span's end. [Group drops](/quest/m2/group-drops.md) reports the span. - -Recommendations for the same PR, not decided: - -- GROUP_END takes the value FRAME reserves, a `Payload Length` of 0, - followed by the end timestamp. [Takeover](/quest/m3/group-takeover.md) - planned a marker with the same name and the same reserved value that - pauses a group instead; it now designs its own marker in lite-08. -- Anchor types 1 (Absolute) and 3 (Time) are aliases once a group's key is - its start: the publisher maps both to `Anchor::Time`, and the model - already has only `Oldest`, `Relative`, and `Time`. Keep one type with one - end rule (today type 1's end is exclusive and type 3's inclusive), and - read it with the full 2^61 width in JS, which decodes a Time anchor with - `u53()` today. -- GROUP's previous start is optional: encode it plus one with 0 for none, - as the draft's other optional integers are. -- SUBSCRIBE_SKIP stays for spans a subscriber can't infer, such as the tail - of a bounded Range where starts are sparse, and GROUP's previous-start - link carries the gap between two delivered groups, so the Subscribe - Stream no longer carries one SKIP per group (`append_group` skips the - keys between appends, and lite-07 forwards each today). With no count - on a drop, a skip and a drop stay two messages. -- Delete the draft's binding 5 (Qmux over RTCDataChannel): its table row, - its two paragraphs, its changelog line, and the DTLS clause in Security - Considerations. [moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771) - removed the implementation with peer-to-peer. -- At the rename to `moq-lite-07`, delete what describes earlier versions' - encodings in the body and in the lite-07 changelog, which itself says - "Removed rules for mapping onto earlier versions": the changelog lines - about what moq-lite-05 and moq-lite-06 do with a `Timescale` of 0 and - with SUBSCRIBE_DROP bounds. The 2^61 timestamp bound stays, and its - "so every version can carry it" is its only reason. - -Kept as they are, so this rewrite leaves them alone: every lite version -from 01 to 06 keeps negotiating with today's behaviour, and a path segment -starting with `.` still hides a claim, with no typed flag (both decided -2026-11-16; AGENTS.md records the dot as the exception to its -reserved-prefix rule). Not reopened by the audit: AUTH_ERROR's retry codes -(the 2026-11-14 pick stands), and AUTH_OK's rate fields, which wait for -lite-08 with [the rate grant](/quest/m5/rate-grant.md). - -Public API: none beyond [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). -`@moq/net` and the bindings' track listing gain a kind. Wire: lite-07-wip -GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, -SUBSCRIBE_STARTED, SUBSCRIBE_FINISH, SUBSCRIBE_SKIP, SUBSCRIBE_DROP, and -TRACKS_ADD change, and the Padding stream and datagram types go. - -## Related - -- [YIELDED deferred](/quest/m2/yield-defer.md) - removes continuations, the last use of GROUP's `Frame Start` -- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - reads the spans SUBSCRIBE_DROP names -- [Refresh a track](/quest/m2/refresh-interval.md) - raises the `Wanted Group` this turns into a start time -- [A cold join reaches back](/quest/m2/min-age-join.md) - gives SUBSCRIBE's `Subscriber Min Age` its reader diff --git a/quest/m2/unused-api/js.md b/quest/m2/unused-api/js.md index ce0c6613ffa..84d1e020586 100644 --- a/quest/m2/unused-api/js.md +++ b/quest/m2/unused-api/js.md @@ -86,8 +86,8 @@ Rust, and the interop clients use them. Not here: sockets leave `@moq/net` with [the socket move](/quest/m2/sockets/README.md), and the `NO_MAX_DELAY` -sentinel (`js/net/src/internal.ts`) goes with the Max Age change in -[the lite-07 wire](/quest/m2/time-addressing/lite07.md). The browser media +sentinel (`js/net/src/internal.ts`) stays: it left the wire with +[the lite-07 wire](https://github.com/moq-dev/moq/pull/8908), but still means no limit inside the package. The browser media packages' leftovers are [their own sweep](/quest/m2/unused-api/media.md). For the PR: regenerate `js/net/api/index.api.md` and check that every diff --git a/quest/m2/yield-defer.md b/quest/m2/yield-defer.md index 2acfc71aa2c..df36175ebd3 100644 --- a/quest/m2/yield-defer.md +++ b/quest/m2/yield-defer.md @@ -54,14 +54,14 @@ Facts found by the audit: `lite/publisher.rs` and 264 in `lite/subscriber.rs`, plus `tests/integration/stream_credit.rs` (857 lines), the `test/stream-credit` browser harness, `Continuation.cfg`, and three of the seven rules in - `rs/moq-net/verify/subscribe/SubscribeAccounting.tla`. The other four - rules cover reopened OLD drops, which - [time addressing](/quest/m2/time-addressing/lite07.md) deletes. + `rs/moq-net/verify/subscribe/SubscribeAccounting.tla`. The rules for + reopened OLD drops left with [time addressing](https://github.com/moq-dev/moq/pull/8908). What goes: -- Draft: the Yield section, the YIELDED row (0x3C), the paused clauses in - SUBSCRIBE_DROP's accounting rule, the continuation exception to the +- Draft: the Yield section, the YIELDED row (0x3C), GROUP's `Frame Start` + (a continuation is its last sender on a subscription; lite-06 keeps its + field), the paused clauses in SUBSCRIBE_DROP's accounting rule, the continuation exception to the duplicate-stream rule with its "held unread" and "MAY end the earlier stream" rules, the `ietf` extension's never-yields sentence, and both changelog lines. The reset rule reads as lite-06's: the publisher resets @@ -76,18 +76,13 @@ What goes: - JS: the same in `js/net/src/lite/{publisher,subscriber}.ts`, `open.ts`, and `error.ts`, including the paths that infer a pause from a reset without a code or from a later stream for the same group. -- `verify/subscribe`: with this and OLD-final, none of the seven rules - describes shipped behaviour. Re-derive the model around what remains - (final drops, duplicate streams, the tail) or delete it with its skill - (`.claude/skills/verify-subscribe`) and nightly job; recommended: - re-derive, since tail accounting stays. Whichever PR lands second, this - or time addressing's, does it. +- `verify/subscribe`: [time addressing](https://github.com/moq-dev/moq/pull/8908) re-derived the + model around final drops, expiry closes, and `Previous Start`; remove its + YIELDED half (`Continuation.cfg`, the paused rules, and the continuation + steps) and rerun the rest. Guidance for the PR: -- Land after or with [time addressing](/quest/m2/time-addressing/lite07.md) - if both are open, since both rewrite SUBSCRIBE_DROP's accounting text; - neither blocks the other. - Keep `test/stream-credit` and `stream_credit.rs`, rewritten to the new contract: more live tracks than the cap, the highest-priority groups get the streams, every group the reader misses is named in a drop, and a @@ -104,6 +99,5 @@ are unchanged. ## Related -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - rewrites the same SUBSCRIBE_DROP accounting text and deletes the model's other four rules - [Takeover](/quest/m3/group-takeover.md) - designs paused groups and continuations again, with takeover, for lite-08 - [Browser reset reports](/quest/m4/browser-reset-reports.md) - the browser bugs that made the pause depend on a lost signal diff --git a/quest/m3/e2ee-format.md b/quest/m3/e2ee-format.md index 526f7cf12b8..3991ae76a25 100644 --- a/quest/m3/e2ee-format.md +++ b/quest/m3/e2ee-format.md @@ -114,7 +114,7 @@ types, and the vectors regenerate once): Instance and tracks under the same credential, and correct the draft's sentence. - Per-group keys: add the group's wire ID (its start, after - [lite-07 addresses groups by start](/quest/m2/time-addressing/lite07.md)) + [lite-07 addresses groups by start](https://github.com/moq-dev/moq/pull/8908)) to `key_info`. For datagram tracks recommend the sequence's high bits as the key index, so one HKDF-Expand covers a run of datagrams; settle the split in the PR and bench it with `benches/protect.rs`. Then delete @@ -165,7 +165,6 @@ and moq-lite: none. ## Required - [End-to-end encryption is its own unpublished crate again](/quest/m2/e2ee-crate.md) - the `moq-e2ee` crate this changes and publishes -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - the group identity the per-group key and the nonce bind ## Related diff --git a/quest/m3/group-takeover.md b/quest/m3/group-takeover.md index 766dfd50a5d..acf020f92c1 100644 --- a/quest/m3/group-takeover.md +++ b/quest/m3/group-takeover.md @@ -27,7 +27,7 @@ version" read as lite-08: pauses the group. lite-07 now freezes a GROUP_END with that name on that reserved value meaning the opposite: the group is whole, and here is its exclusive end timestamp - ([time addressing](/quest/m2/time-addressing/lite07.md)). Recommended: a + ([time addressing](https://github.com/moq-dev/moq/pull/8908)). Recommended: a distinct marker (say GROUP_PAUSE), laid out so one zero `Payload Length` leads to either; lite-08 is a new version, so it may re-lay what follows the zero. @@ -129,5 +129,4 @@ marker, and multi-group streams. - [YIELDED deferred](/quest/m2/yield-defer.md) - removes paused groups and continuations from lite-07 - [YIELDED reset](https://github.com/moq-dev/moq/pull/8545) - the lite-07-wip design this starts from -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - freezes the GROUP_END this must not collide with - [Finalize lite-07](/quest/m2/lite07-finalize.md) - freezes lite-07 without takeover or continuations diff --git a/quest/m3/time-addressing-guide.md b/quest/m3/time-addressing-guide.md index b9372e69ba4..268ca9575bc 100644 --- a/quest/m3/time-addressing-guide.md +++ b/quest/m3/time-addressing-guide.md @@ -20,12 +20,8 @@ Moved to m1 2026-11-12 (maintainer, /quest-audit): a docs page breaks nothing, s Decided 2026-10-25 (maintainer): a separate page, not only inline doc updates. Write it against the design [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) -and [lite-07](/quest/m2/time-addressing/lite07.md) quests record, including +and [lite-07](https://github.com/moq-dev/moq/pull/8908) quests record, including that a released relay fills a hole with one FETCH per ID, so a mixed-version deployment upgrades its relays together. Link it from `doc/concept/moq-lite.md` and from the identity and recovery guide (`doc/concept/identity.md`), which covers epochs and restarts. - -## Required - -- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - the wire this page describes diff --git a/quest/m5/e2ee/README.md b/quest/m5/e2ee/README.md index 65fc5610fba..24239b97052 100644 --- a/quest/m5/e2ee/README.md +++ b/quest/m5/e2ee/README.md @@ -25,7 +25,7 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro - An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). Two producers handed one epoch would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. - The epoch is untrusted and unauthenticated. A wrong epoch fails authentication and a withheld one denies service; neither can make a nonce repeat, because only the publisher instance chooses what it encrypts under. This is the same trust a cache needs to serve the right instance. First-party plaintext publishers already mint the same route epoch. - Nothing in the path says the bytes are encrypted. The format after decryption (`meeting.hang`) is inside the opaque name; a plaintext player, exporter, or matcher that opens a protected broadcast finds no catalog it can read and fails with its usual typed refusal, the same as for any format it does not support. -- One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains, and from `moq-e2ee-01` for each group, with the semantic broadcast name bound into every derivation (decided 2026-11-16). A grouped frame uses a 96-bit nonce of a 64-bit group identity and `uint32_be(frame)`. `group` is the group's wire ID, which is its start once [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) keys groups by start, so the nonce input needs no change; [lite-07 by start](/quest/m2/time-addressing/lite07.md) updates the draft's wording. A datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. +- One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains, and from `moq-e2ee-01` for each group, with the semantic broadcast name bound into every derivation (decided 2026-11-16). A grouped frame uses a 96-bit nonce of a 64-bit group identity and `uint32_be(frame)`. `group` is the group's wire ID, which is its start once [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) keys groups by start, so the nonce input needs no change; [lite-07 by start](https://github.com/moq-dev/moq/pull/8908) updates the draft's wording. A datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. - Within an instance, group and datagram sequences are allocated monotonically and frames are numbered in write order, which is the whole reuse rule. There is no ciphertext retention or retransmission API: relays forward bytes unchanged, and an application that needs to resend encrypts nothing twice because it never gets the same identity twice. - Superseded 2026-11-16 by [one key per group](/quest/m3/e2ee-format.md), which makes the limits unreachable and deletes the accounting: per-key limits were `2^24` AEAD invocations (failed opens included) and `2^36` plaintext bytes, owned by the generation handle (maintainer, 2026-10-24), which forced a whole-broadcast restart after 19 hours at 8 Mb/s. Datagram plaintext is capped at `1200 - 28 - 16` bytes against the widest moq-lite header; a publisher cannot see the Subscribe ID each hop encodes, so the library does not pretend to budget it. diff --git a/quest/m5/probe-padding.md b/quest/m5/probe-padding.md index 4afebe006a4..64727415f6d 100644 --- a/quest/m5/probe-padding.md +++ b/quest/m5/probe-padding.md @@ -16,7 +16,7 @@ probe to the larger of their send target and the peer's PROBE target. Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ lite-07 freezes without the Padding Stream (0x2) and Padding Datagram (0x1) types, -removed by [the time-addressing rewrite](/quest/m2/time-addressing/lite07.md) +removed by [the time-addressing rewrite](https://github.com/moq-dev/moq/pull/8908) (rejected: keep the receive-only types for this quest). Nothing sent either. If the rethink below still lands on padding, it adds its stream type in a later lite version or a SETUP extension: an unaware peer resets an unknown From 03d0b702e38c2050be118b6d449bab2a05158432 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:38:30 -0800 Subject: [PATCH 19/26] fix(js/net): a GROUP_END waiting for its FIN still ends with its group The JS model resolving a lite-07 Time start to its containing group is recorded in the quest that rekeys the JS model by start. Co-Authored-By: Claude Opus 5.5 --- js/net/src/lite/group.test.ts | 21 +++++++++++++++++++++ js/net/src/lite/group.ts | 6 +++++- quest/m2/time-addressing/js.md | 7 +++++++ 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/js/net/src/lite/group.test.ts b/js/net/src/lite/group.test.ts index 661cf95e6e4..a04608071e2 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -167,6 +167,27 @@ test("a lite-07 GROUP_END says where the group ends", async () => { expect(await readLite07(lite07(...frame))).toBeUndefined(); }); +// A publisher that stalls between GROUP_END and its FIN can't hold the read open: the group's own +// close, such as an abort or eviction, still ends it. +test("a lite-07 GROUP_END still waiting for its FIN stops once the group closes", async () => { + const producer = new Producer(0n); + const stream = new Reader( + new ReadableStream({ + start(controller) { + controller.enqueue(lite07(2, 0, 7, 0, 500)); + }, + }), + undefined, + Version.DRAFT_07, + ); + const consumer = producer.consume(); + const done = readFrames(stream, producer, { scale: SCALE, lengthFirst: true }); + // The frame and GROUP_END arrive together, so once the frame is read the FIN is all that's left. + expect((await consumer.readFrame())?.payload).toEqual(new Uint8Array([7])); + producer.abort(new Error("evicted")); + expect(await done).toBeUndefined(); +}); + // An End at or before the group's start, or anything after GROUP_END, is malformed. A malformed // FRAME ends only its stream, so it is a stream error rather than a session's protocol violation. test.each([ diff --git a/js/net/src/lite/group.ts b/js/net/src/lite/group.ts index 7b3cd396a6f..42596c6b1a2 100644 --- a/js/net/src/lite/group.ts +++ b/js/net/src/lite/group.ts @@ -228,7 +228,11 @@ export async function readFrames( if (ingest?.partial) throw malformed("GROUP_END before completing the frame a continuation resumed"); if (frame.end <= producer.sequence) throw malformed(`GROUP_END at ${frame.end}, not past the group's start`); - if (!(await stream.done())) throw malformed("bytes after GROUP_END"); + // The FIN may never come, so the group's own close, such as an abort or eviction, still + // ends the wait. + const done = await race([stream.done(), producer.closed]); + if (done === false) throw malformed("bytes after GROUP_END"); + if (done !== true) return undefined; return frame.end; } if (ingest) { diff --git a/quest/m2/time-addressing/js.md b/quest/m2/time-addressing/js.md index 77e89d25b0c..9cd6d816e39 100644 --- a/quest/m2/time-addressing/js.md +++ b/quest/m2/time-addressing/js.md @@ -18,6 +18,13 @@ so they are carried past 2^53 (decided 2026-11-03, maintainer). types PR, to keep frames allocation-free); revisit it here if a start must compare exactly with a timestamp past 2^53 ticks. +Until this lands the lite-07 wire's one Time anchor reaches the JS model as +a group key (`requestedRanges`, `js/net/src/lite/subscribe.ts`): a start +`t` is a floor at key `t`, not the group containing `t`, so a JS publisher +holding sparse keys skips the group a seek between two starts falls in. +Resolve a Time start to the containing group here, as Rust's +`track::Anchor::Time` does. + The spike found no sparse-ID breakage in direct `@moq/net` sessions over lite-06 and lite-07; its relay fills follow Rust's once JavaScript received copies fill. JS ranges From 6210b170f86f875993717b743fb6621c65caecd1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 01:17:59 -0800 Subject: [PATCH 20/26] chore(net): regenerate the JS API report for Group.Producer.finishAt Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index c95db64c710..0e70b289a21 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -436,7 +436,8 @@ export namespace Group { get closed(): Signals.GetPromise; consume(): Group.Consumer; createFrame(info: Frame.Info): Frame.Producer; - finish(end?: bigint): Group.Finished; + finish(): Group.Finished; + finishAt(end: bigint): Group.Finished; get isClosed(): boolean; readonly sequence: bigint; writeFrame(frame: Group.Frame): void; From b10adfa6a96bfe557739ffa6bad38f20beb11d76 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 01:53:49 -0800 Subject: [PATCH 21/26] chore(verify): the subscribe model's sync commit moves to the main merge Main's changes since touch no function the model covers, and both configs pass there. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/verify-subscribe/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index eb0465619c5..78b0e315197 100644 --- a/.claude/skills/verify-subscribe/SKILL.md +++ b/.claude/skills/verify-subscribe/SKILL.md @@ -35,7 +35,7 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th ## Coverage -Sync commit: `157042024b139ef0153e1ab71ea40dfdf5e08993`. Run `git log 157042024b.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. +Sync commit: `ff1bb32733c8938bd8f5ab5736e1db08c6dbcf83`. Run `git log ff1bb32733.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. | Code | Model | | --- | --- | From bbf6c39a33fc57aa83a68b53e45a8459a934f615 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:34:28 -0800 Subject: [PATCH 22/26] fix(net): a held skip outlives the cache forgetting it, and an expiry close never cuts a frame A GROUP whose skip run was held back passes over that run even once the cache's expiry or debt forgot the skip, in Rust and JS and the subscribe model. A JS lite-07 stream that expires mid-frame resets with the frame's failure instead of closing over a truncated frame, as Rust's GroupServe already does. Co-Authored-By: Claude Opus 5.5 --- js/net/src/lite/publisher.test.ts | 46 +++++++++++++++++++ js/net/src/lite/publisher.ts | 32 +++++++++---- rs/moq-net/src/lite/publisher.rs | 35 +++++++++++++- rs/moq-net/src/model/track.rs | 6 +++ .../verify/subscribe/SubscribeAccounting.tla | 4 +- 5 files changed, 110 insertions(+), 13 deletions(-) diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 6eec954c628..77ffacfc7ba 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -1536,6 +1536,52 @@ test.each([ } }); +// A lite-07 stream whose group expires mid-frame waits for that frame before it closes, and resets +// with the frame's failure when the frame fails instead: a FIN would cut the frame short. Mirrors the +// Rust `GroupServe`, which closes an expired stream only at a frame boundary. +test("lite draft-07: an expired stream resets when its frame in flight fails", async () => { + const clock = new Manual(); + const installed = clock.install(); + const budget = 1_000; + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + sub.serve(0n); + expect(await sub.servedSequence()).toBe(0n); + expect("start" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); + await new SubscribeUpdate({ + priority: 1, + startGroup: 0n, + maxDelay: budget, + ...restate(Version.DRAFT_07, 0n), + }).encode(sub.client.writer, Version.DRAFT_07); + expect("started" in (await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_07))).toBe(true); + + let reset: unknown; + void sub.stall(true).then((reason) => { + reset = reason; + }); + const group = sub.track.createGroup(1n); + const frame = group.createFrame({ size: 10, timestamp: Timestamp.fromMillis(1) }); + frame.write(new Uint8Array(5)); + expect(await sub.servedHeader()).toBe(1n); + await flush(); + await clock.advance(Duration.millis(budget * 10)); + sub.serve(2n); + expect(await sub.servedSequence()).toBe(2n); + await clock.advance(Duration.millis(budget)); + await flush(); + expect(reset).toBeUndefined(); + + const cut = new Error("frame cut"); + frame.abort(cut); + await flush(); + expect(reset).toBe(cut); + } finally { + await sub.close(); + installed.close(); + } +}); + // An update that lowers the start below SUBSCRIBE_START asks for those groups too, so the // end sweep drops them, as the Rust publisher does. test("lite draft-06: an update lowering the start is swept at the end", async () => { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 6e39b3ec5a8..78a047a7beb 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -1825,8 +1825,15 @@ export class Publisher { } record?.tell(group.sequence, group.sequence + 1n, { kind: "settled" }); // Its GROUP passes over the run elided below it, and a drop of it sends the run first. + // The run is taken as it was elided, since the cache may have forgotten the skip since. + const from = elided.get(group.sequence); elided.delete(group.sequence); - const previous = hasGroupEnd(this.version) ? hooks.previousStart(track, group.sequence) : undefined; + let previous: bigint | undefined; + if (hasGroupEnd(this.version)) { + const cached = hooks.previousStart(track, group.sequence); + const run = from !== undefined && from > 0n ? from - 1n : undefined; + previous = cached === undefined || run === undefined ? (cached ?? run) : min(cached, run); + } const options: RunGroup = { sub, @@ -2466,18 +2473,25 @@ export class Publisher { else await write(() => stream.closed); return undefined; } catch (err: unknown) { - const e = error(err); + let e = error(err); if (closes && !ended && hooks.groupExpired(group)) { - // Expired on its stream: what went out stands as a closed group, and the frame - // being written completes first. Mirrors the Rust `GroupServe`'s expiry close. - console.debug(`closing expired group: subscribe=${sub} sequence=${group.sequence}`); - await writing?.catch(() => {}); - stream.close(); - group.close(); - return await stream.closed.then( + // Expired on its stream: what went out stands as a closed group, once the frame being + // written completes. One that fails resets the stream with its failure instead, since a + // FIN would cut it short. Mirrors the Rust `GroupServe`'s expiry close. + const failed = await writing?.then( () => undefined, (err: unknown) => error(err), ); + if (failed === undefined) { + console.debug(`closing expired group: subscribe=${sub} sequence=${group.sequence}`); + stream.close(); + group.close(); + return await stream.closed.then( + () => undefined, + (err: unknown) => error(err), + ); + } + e = failed; } stream.reset(e); // A reset that pauses the group leaves the reader to the caller, which reads its fate diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f00511bb3c5..8176f464610 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -5907,9 +5907,13 @@ impl TrackRun { self.mark_served(key); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, key, "serving group"); // Its GROUP passes over the run elided below it, and a drop of it sends the run first. - self.elided.remove(&key); + // The run is taken as it was elided, since the cache may have forgotten the skip since. + let elided = self.elided.remove(&key).and_then(|start| start.checked_sub(1)); let previous = match self.ctx.version.has_group_end() { - true => self.track.previous_start(key), + true => match (elided, self.track.previous_start(key)) { + (Some(elided), Some(cached)) => Some(elided.min(cached)), + (elided, cached) => elided.or(cached), + }, false => None, }; self.give_way(); @@ -8676,6 +8680,33 @@ mod serve_group_test { assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3), ("drop", 3..4)]); } + /// A skipped run held back for a group's GROUP still passes over the run once the cache + /// forgot the skip, as its pool's expiry or debt may before the group gets stream credit. + #[kio::test] + async fn lite07_a_held_skip_outlives_the_cache_forgetting_it() { + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + track.received(); + let subscriber = track.subscribe(None); + let session = Log::default(); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(session.clone()), subscriber); + write_group(&mut track, 0, 0); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + track.skip_groups(1..3); + write_group(&mut track, 3, 3); + forward(&mut run, 1..3, &Hole::Skip, &mut writer); + track.forget_drops(1..3); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + assert!( + holes(&mut writer, &log).await.is_empty(), + "the GROUP passes over the run" + ); + assert_eq!(group_headers(&session, Version::Lite07), [(0, None), (3, Some(0))]); + } + /// A skipped run held back for a group that is then skipped too joins that group's skip, /// since no GROUP will pass over it. #[kio::test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 3f06e5391e8..3153aec9cb4 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -4706,6 +4706,12 @@ impl Producer { state.supersede_stale() } + /// Forget what was given up in `groups`, as the cache pool's expiry or debt does. + #[cfg(test)] + pub(crate) fn forget_drops(&self, groups: ops::Range) { + self.modify().unwrap().forget_drops(groups); + } + /// Record `groups` given up as `hole` describes, returning the runs recorded: a drop /// leaves a skipped key skipped, and a group a copy still serves whole, since a group /// stream wins over its drop: a stale drop leaves it still arriving or not, and a final one diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla index 160b5ffac13..14e307ff8d4 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla @@ -139,10 +139,10 @@ SkippedBelow(g) == IN IF 0 \in below THEN {} ELSE below \* `serve`: open a Group Stream for g, which `mark_served` records. Its GROUP passes over -\* the skipped run below it, the one held back for it included. +\* the skipped run below it and the one held back for it, which the cache may have forgotten. Serve(g) == /\ Len(streams) < MaxStreams - /\ streams' = Append(streams, NewStream(g, 0, 0, SkippedBelow(g))) + /\ streams' = Append(streams, NewStream(g, 0, 0, SkippedBelow(g) \cup held[g])) /\ served' = served \cup {g} /\ held' = [held EXCEPT ![g] = {}] From 7091c0a959804b260316e0ba4e5e293df65ebb86 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:34:36 -0800 Subject: [PATCH 23/26] chore(verify): the subscribe model's sync commit moves past the held-skip fix Co-Authored-By: Claude Opus 5.5 --- .claude/skills/verify-subscribe/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index 78b0e315197..07a7bb17eff 100644 --- a/.claude/skills/verify-subscribe/SKILL.md +++ b/.claude/skills/verify-subscribe/SKILL.md @@ -35,7 +35,7 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th ## Coverage -Sync commit: `ff1bb32733c8938bd8f5ab5736e1db08c6dbcf83`. Run `git log ff1bb32733.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. +Sync commit: `bbf6c39a33fc57aa83a68b53e45a8459a934f615`. Run `git log bbf6c39a33.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. | Code | Model | | --- | --- | From 097b2b6e6f38951bef9d05310f95dd74cc58258d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:42:30 -0800 Subject: [PATCH 24/26] fix(net): the test-only forget_drops builds only with async Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 3153aec9cb4..446726daf77 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -4707,7 +4707,7 @@ impl Producer { } /// Forget what was given up in `groups`, as the cache pool's expiry or debt does. - #[cfg(test)] + #[cfg(all(test, feature = "async"))] pub(crate) fn forget_drops(&self, groups: ops::Range) { self.modify().unwrap().forget_drops(groups); } From a4ed9aaae04ea91b2d772861233238671882960f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 03:01:54 -0800 Subject: [PATCH 25/26] style(net): rustfmt the merged publisher Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index c53c16f55f5..cfa75e56c13 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -6680,8 +6680,12 @@ impl GroupServe { Err(err) => break 'serve Err(err), }, None => { - match buffer_group_end(writer, self.ctx.version, self.ctx.object_records, &self.group) - { + match buffer_group_end( + writer, + self.ctx.version, + self.ctx.object_records, + &self.group, + ) { Ok(true) => { *ending = Ending::Whole; continue; @@ -6737,8 +6741,12 @@ impl GroupServe { Err(err) => break 'serve Err(err), }, None => { - match buffer_group_end(writer, self.ctx.version, self.ctx.object_records, &self.group) - { + match buffer_group_end( + writer, + self.ctx.version, + self.ctx.object_records, + &self.group, + ) { Ok(true) => { *ending = Ending::Whole; continue; From 2d80a9d1894a704030b72db73901a1f0b8ab15ef Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 03:30:02 -0800 Subject: [PATCH 26/26] chore(verify): the subscribe model's sync commit moves to the second main merge Main's changes since touch only ietf records and the ordered reader, which the model leaves out; both configs pass on the merge. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/verify-subscribe/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index 07a7bb17eff..be5f3971b78 100644 --- a/.claude/skills/verify-subscribe/SKILL.md +++ b/.claude/skills/verify-subscribe/SKILL.md @@ -35,7 +35,7 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th ## Coverage -Sync commit: `bbf6c39a33fc57aa83a68b53e45a8459a934f615`. Run `git log bbf6c39a33.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. +Sync commit: `79379ee3ae7a154c007322afe2c5a4178816793f`. Run `git log 79379ee3ae.. -- rs/moq-net/src/lite/publisher.rs rs/moq-net/src/lite/subscriber.rs rs/moq-net/src/tail.rs rs/moq-net/src/model/track.rs rs/moq-net/src/model/record.rs` to see what changed since. Follow Coverage in `rs/moq-net/verify/README.md` after a change to a covered function. | Code | Model | | --- | --- |