diff --git a/.claude/skills/verify-subscribe/SKILL.md b/.claude/skills/verify-subscribe/SKILL.md index 9f8422b48e..cbf4a34ba9 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, preemption, and expiry (a stream reset with OLD when its group expires, even after its FIN), a GROUP's Previous Start and the skips it passes over or the publisher holds back for it, 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, preemption, and expiry (a stream reset with OLD when its group expires, even after its FIN), a whole group's span (its GROUP_END's End, which accounts for the starts inside it, and the drop that names it), 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, and a reset can lose a stream's header. A Group Stream whose group expires stale resets with OLD and is named in a stale drop, whether it never opened, is serving, or already sent its FIN and awaits the acknowledgement, so stale bytes never hold the send window; a subscriber that read it whole before the reset keeps the group. A stream reset while serving, evicted or preempted with TOO_FAR_BEHIND for a group that outranks it, is named in a final drop. 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. 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 a stream fails 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, and reports a deadlock for any state short of quiet where nothing can happen. +`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 resets with OLD and is named in a stale drop, whether it never opened, is serving, or already sent its FIN and awaits the acknowledgement, so stale bytes never hold the send window; a subscriber that read it whole before the reset keeps the group. A stream reset while serving, evicted or preempted with TOO_FAR_BEHIND for a group that outranks it, is named in a final drop. A group may finish whole at an End, and no other group starts strictly inside its span. Its GROUP_END accounts for those starts, which the publisher then records as told, a drop of the group names the span once it is whole, and the track records the starts inside skipped, which the cursor skips where nothing told them yet. 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 a stream fails and when a group finishes whole and where it ends. 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, and reports a deadlock for any state short of quiet where nothing can happen. ## 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 at most one Group Stream for a group. | The group's bytes go out twice, and the subscriber reads two streams of one group. | -| `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 drop may follow the group's own Group Stream, even one sent whole, once it resets. The one exception to one skip 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. | +| `NamedOnce` | The publisher names a group in at most one drop and a start in at most one skip, and a skip only for a group it never served. A drop may follow the group's own Group Stream, even one sent whole, once it resets. No Group Stream opens for a start inside a whole group's span. | 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 start, the ones inside a whole group's span included. | The subscriber waits out its grace for a group nobody will send, and a relay holds its readers there. | ## Run @@ -23,7 +23,7 @@ Each rule is an INVARIANT; the harm says why it matters. quest gate just rs tla moq-net/verify/subscribe/SubscribeAccounting.tla ``` -It checks every rule under `Pressure` over three groups, 1 to 3, so a skip of 1 can be held back for 2's GROUP and a run of 1 and 2 for 3's: about 11.1M distinct states, two minutes. It passes. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. +It checks every rule under `Pressure` over three starts, 1 to 3, where group 1 may end at 2, 3, or 4, so its span holds none, one, or both of the starts above it: about 75.7M distinct states, nine minutes. It passes. Nightly runs every config here and fails if a config with an `\* Open finding:` line passes. ## Reading a failure @@ -31,29 +31,30 @@ Follow Reading a failure in `rs/moq-net/verify/README.md`. Replay the path on th ## Coverage -Sync commit: `3016af623807e939c2e99571a3ec02beb2493579`. Run `git log 3016af6238.. -- 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: `bf3f3b26f23df3dec51a48d4b36e67445d84ea98`. Run `git log bf3f3b26f2.. -- 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`; `rs/moq-net/src/model/track.rs` `TrackState::previous_start` | `CursorHand`, `Serve`, `SkippedBelow` | +| `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` | +| `rs/moq-net/src/model/group.rs` `Producer::finish_at`; `rs/moq-net/src/model/track.rs` `TrackState::appended`, `TrackState::span_end` | `Finish`, `ends`, `CursorHole` | | `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 | -| `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::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_given_up`; `rs/moq-net/src/transport/boxed.rs` `ListedState::preempted` | `StreamFin`, `StreamFail`, `StreamAck` | +| `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`, `Span` | +| `rs/moq-net/src/lite/publisher.rs` `TrackRun::poll_step` (outcomes, `GroupOutcomes::whole`) | `PubOutcomes` | +| `rs/moq-net/src/lite/publisher.rs` `GroupServe::poll_serve` (`Serve`, `Closed`), `buffer_group_end`, `settle_failed`, `poll_given_up`; `rs/moq-net/src/transport/boxed.rs` `ListedState::preempted` | `StreamFin`, `StreamFail`, `StreamAck` | | `rs/moq-net/src/model/record.rs` `Record::fold` | `PubFold`, `folded` | -| `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::open` (with the passed-over skip), `reopen`, `place`; `GroupRecv::poll_serve` | `SubHeader`, `SubFin`, `SubReset` | +| `rs/moq-net/src/lite/subscriber.rs` `TrackEntry::open`, `reopen`, `place`; `GroupRecv::poll_serve` (a GROUP_END's span) | `SubHeader`, `SubFin`, `SubReset` | | `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` | `acct` | +| `rs/moq-net/src/tail.rs` `Reading::open`, `Reading::account`, `Tail::account` | `acct` | | `rs/moq-net/src/model/track.rs` `Producer::give_up`, `skip_received` | `rec`, `cached` | What the model asks of that code, each found by TLC as a broken rule without it: - 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 goes out after a skip of what its GROUP passed over (`GroupOutcomes::dropped`), since a reset can lose the GROUP (`QuietIsSettled`). +- A drop of a group held whole names its span (`forward_range`, `settle_failed`), since a reset can lose its GROUP_END (`QuietIsSettled`). +- A GROUP_END buffered records the starts inside the span as told (`GroupOutcomes::whole`), so the track's end does not name them again (`NamedOnce`). +- The starts inside a span whose group's stream was dropped before it finished whole are skipped where nothing told them (`QuietIsSettled`). - A stream reset for expiry after its FIN is still named in a drop (`settle_failed` from `GroupState::Closed`), since the reset can discard the header before it is read (`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`), which stream a preempt picks, 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, and so are frames and GROUP_END's End, which only says where a whole group ends. With one Group Stream per group, the subscriber's wait for a duplicate stream (`Open::Duplicate`) is never reached. 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. A pass covers three groups. +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`), which stream a preempt picks, 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, and so are frames: an End is at most one past the highest start, so a span may run past the range, and its delta coding is left to the codec tests. With one Group Stream per group, the subscriber's wait for a duplicate stream (`Open::Duplicate`) is never reached. A pass covers three starts. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 7ac614a257..e2f9ee89a0 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -352,9 +352,11 @@ 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. +a paused track still ages out. Groups never overlap: a group runs from its +lowest timestamp to its end. Over the work-in-progress moq-lite 07 the time +between one group's end and the next group's start belongs to no group and is +reported as skipped, so a reader sees a gap at once; older versions and +moq-transport carry no end. 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 diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 0d1681d20b..6051c2cf6c 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -176,7 +176,9 @@ A Group is an ordered stream of Frames within a Track. Each group consists of an append-only list of Frames. 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 Group's span runs from its lowest frame timestamp to its End (see [GROUP_END](#group-end)). +Spans never overlap: every frame of a lower Group presents before every frame of a higher one, though frames within a Group may reorder, and no Group starts after a whole Group's start and before its End. +A span between one Group's End and the next Group's start is a discontinuity that no Group contains, which the publisher names with [SUBSCRIBE_SKIP](#subscribe-skip). 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. @@ -201,10 +203,10 @@ 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) message's `Frame Start`, or a Fetch Stream's FETCH `Frame Start`. -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. +Each frame has 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 Group starts are bare numbers in no known unit, and its frames carry no timestamp, each taking 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 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. +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. 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. @@ -353,7 +355,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 starts a Group at or before one with a lower start, or differs from its Group's start on a scale-less track. | +| 0x39 | TIMESTAMP_MISMATCH | A frame's timestamp does not fit its track: it starts a Group at or before one with a lower start. | | ------- | ------------- | ----------- | | 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. | | ------- | ------------- | ----------- | @@ -618,7 +620,7 @@ The subscriber needs the track's TRACK_INFO (notably its timescale) to interpret 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 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. +The subscriber judges a Range complete from what it observed: the Groups it received and the starts their GROUP_END accounts for, 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. @@ -627,7 +629,7 @@ A publisher never sends a Group twice on one subscription, so a Group the subscr 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 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. +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 accounted for by a [GROUP_END](#group-end), 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. @@ -1938,13 +1940,14 @@ Every drop is final on its subscription: no SUBSCRIBE_UPDATE reopens it, and a s 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 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 later [SUBSCRIBE_SKIP](#subscribe-skip) of 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 starts changes nothing. -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. +For every start in the subscription's range, the publisher MUST send a Group Stream, account for it with a [GROUP_END](#group-end), 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 GROUP_END accounts for the starts strictly between its Group Start and End. +A drop of a Group the publisher holds whole names its span, with a `Group End` of its End or its start plus one, whichever is higher, since the GROUP_END 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 answers a STOP_SENDING. The publisher SHOULD name a start as soon as it gives it up, without waiting for SUBSCRIBE_FINISH. @@ -1973,8 +1976,8 @@ A skip never overrides a Group that arrived, since that Group was produced; a su 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)). +A publisher SHOULD send the skip as soon as it declares it. +A relay forwards a skip it received 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. @@ -2171,7 +2174,6 @@ GROUP Message { Message Length (i) Subscribe ID (i) Group Start (i) - Previous Start (i) Frame Start (i) } ~~~ @@ -2184,12 +2186,6 @@ This ID is used to distinguish between multiple subscriptions for the same track 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)). 0 means the stream carries the group from its beginning; a publisher sends a higher value only for a Range starting at that Position. @@ -2201,7 +2197,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) } @@ -2212,14 +2208,15 @@ The size of the payload on the wire, plus one. 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 `Timescale`, or in bare units on a scale-less Track. +A signed delta from the previous FRAME's timestamp on this stream, in the Track's `Timescale`. +Absent on a scale-less Track. +The first FRAME on a stream counts from the Group Start, the GROUP's on a Group Stream and the FETCH's on a Fetch Stream, so frame 0's delta is 0. Encoded as a zigzag-mapped variable-length integer: - Encode: `unsigned = (signed << 1) ^ (signed >> 63)` (arithmetic right shift). - Decode: `signed = (unsigned >> 1) ^ -(unsigned & 1)`. Zigzag interleaves non-negative and negative values so small magnitudes of either sign fit in a 1-byte varint. -The first frame after each GROUP message is delta-encoded from `0`, so its `Timestamp Delta` is the zigzag encoding of the absolute timestamp. **Inflated Size**: The size of the payload once inflated. @@ -2236,13 +2233,13 @@ It shares FRAME's leading field, reserving the `Payload Length` value 0 that a F ~~~ GROUP_END Message { Payload Length (i) = 0 - End (i) + End Delta (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. +**End Delta**: +The Group's exclusive End, the timestamp where it stops presenting, as a non-negative delta from the highest frame timestamp carried on this stream, or from the Group Start when the stream carries no FRAME or the Track is scale-less. +End is never below any frame timestamp of the Group, and no greater than the next Group's start. 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. @@ -2325,7 +2322,7 @@ A stream that FINs without a GROUP_END carries a closed Group, which may have he - Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit. - Added TRACK_INFO `Refresh` and `Refresh Interval`, and SUBSCRIBE_UPDATE `Wanted Start`, carrying refresh requests through relays: a live-edge join judged by the byte ratio, or a reader's explicit request, either one waiting out the interval. - 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. -- 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 `Timescale` of 0 in TRACK_INFO declares a scale-less Track, whose Group starts are bare numbers; its frames carry no timestamp, each taking its Group's start. - 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. @@ -2362,9 +2359,10 @@ A stream that FINs without a GROUP_END carries a closed Group, which may have he - 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, 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`, 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. +- FRAME carries a `Timestamp Delta` only on a Track with a `Timescale`, and the first FRAME on a stream counts it from the Group Start, so frame 0's is 0. Datagrams always carry a timestamp, a bare number on a scale-less Track. +- Replaced GROUP's `Group Sequence` with `Group Start`. +- Added GROUP_END, a `Payload Length` of 0 followed by the Group's exclusive End, as a non-negative delta from the highest frame timestamp on the stream, or from the Group Start: 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. +- A Group's span runs from its lowest frame timestamp to its End, and spans never overlap. The publisher names the starts between one Group's End and the next Group's start with SUBSCRIBE_SKIP. A GROUP_END accounts for the starts strictly between its Group Start and End, and a drop of a Group the publisher holds whole names its span. - Expiration also measures a group's arrival age, the time since its successor arrived at this hop. - A relay closes a Group it holds only the start of, without a GROUP_END. A publisher resets the Group Stream of a group that expires with OLD, even one whose GROUP_END it sent but is not yet acknowledged, and names the group in a SUBSCRIBE_DROP with OLD. - FRAME leads with `Payload Length`, the payload size plus one, in place of the trailing `Message Length`; 0 is malformed. diff --git a/js/hang/src/container/legacy.test.ts b/js/hang/src/container/legacy.test.ts index 9066510086..320cc42185 100644 --- a/js/hang/src/container/legacy.test.ts +++ b/js/hang/src/container/legacy.test.ts @@ -64,8 +64,9 @@ test("Legacy Producer keys groups in a nanosecond track's timescale", async () = expect(await groups(subscriber)).toEqual([ { start: 1_000_000n, end: 2_000_000n, frames: [1_000, 2_000] }, - // Its end marker at 3ms, then whole at the marker one nanosecond before it. - { start: 2_000_000n, end: 2_999_999n, frames: [2_000, 3_000] }, + // Its end marker at 3ms lies past the marker group one nanosecond before it, and a group + // never ends below a frame of its own, so it closes without an end. + { start: 2_000_000n, end: undefined, frames: [2_000, 3_000] }, { start: 2_999_999n, end: undefined, frames: [2_999] }, ]); }); diff --git a/js/hang/src/container/legacy.ts b/js/hang/src/container/legacy.ts index 64d8e2faed..cd392c18ac 100644 --- a/js/hang/src/container/legacy.ts +++ b/js/hang/src/container/legacy.ts @@ -281,10 +281,14 @@ export class Producer { // A presentation endpoint cannot bound the decode-order tail after reordering. const bound = this.#reordered ? undefined : end; this.#format.finishGroup(this.#group, bound === undefined ? undefined : Duration.micros(bound)); - // A group ends whole where its content stops, which bounds its reach without a successor. + // A group ends whole where its content stops, which bounds its reach without a successor. It + // never ends below a frame of its own, here the newest written or the endpoint marker, so one + // whose end falls below either closes without one. const at = whole !== undefined ? BigInt(whole.value) : bound === undefined ? undefined : keyOf(this.#track, bound); - if (at !== undefined && at > this.#group.start) this.#group.finishAt(at); + const newest = Math.max(this.#end ?? Number.NEGATIVE_INFINITY, bound ?? Number.NEGATIVE_INFINITY); + const floor = Number.isFinite(newest) ? keyOf(this.#track, newest) : this.#group.start; + if (at !== undefined && at > this.#group.start && at >= floor) this.#group.finishAt(at); else this.#group.finish(); this.#group = undefined; if (this.#end !== undefined) { diff --git a/js/net/src/group.ts b/js/net/src/group.ts index a64a3ad1d6..1cc21c4100 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -26,7 +26,7 @@ import { import { type Expiry, type GroupRecover, hooks, type ReadGroupFrame, type Replacement } from "./internal.ts"; import { Queue } from "./queue.ts"; import { rescaleIn } from "./rescale.ts"; -import type { Timestamp } from "./time.ts"; +import { floorAt, type Timestamp } from "./time.ts"; import type { Info as TrackInfo } from "./track.ts"; import { checkKey, RESERVED } from "./util/key.ts"; import { MAX_FRAME_BYTES } from "./util/limits.ts"; @@ -312,6 +312,7 @@ export class Producer { if (state.closed.peek() !== undefined) flate.finish(); }; hooks.groupOffset = (group) => group.#state.offset; + hooks.groupWholeEnd = (group) => (group.#state.closed.peek() === null ? group.#state.end : undefined); hooks.groupHeadless = (group) => group.#state.index > 0 || headShed(group.#state.frames.peek().first); hooks.holdGroup = (group) => { group.#holds++; @@ -720,15 +721,25 @@ export class Producer { /** * Ends the group whole at `end`, the exclusive end of its presentation in the track's * timescale, returning it as {@link Finished}, as the Rust `group::Producer::finish_at`. An - * `end` at or before the group's start throws {@link TimestampMismatch}. + * `end` below the group's start, or below its highest frame timestamp, throws + * {@link TimestampMismatch}; one equal to either is accepted. */ finishAt(end: bigint): Finished { - if (end <= this.start) throw new TimestampMismatch(); + if (end < this.start || end < this.#highest()) throw new TimestampMismatch(); if (this.#state.closed.peek() === undefined) this.#state.end = end; this.#end(null); return this; } + // The highest frame timestamp in the track's timescale, or the start when there is none to + // compare: no frame is timed, or no track says which timescale `end` is in. + #highest(): bigint { + const { latest, track } = this.#state; + if (latest === undefined || track?.timescale == null) return this.start; + // A streamed frame keeps the timestamp it was created with, in any scale. + return BigInt(floorAt(latest, track.timescale)); + } + /** * Ends the group with `error`, which readers that have not drained it see. A no-op once the * group finished or aborted: the outcome is already settled. diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index bb00350854..3400022a3a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -950,12 +950,15 @@ export const hooks: { */ landed: (subscriber: Subscriber, start: bigint, end: bigint) => Instant | undefined; /** - * 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`. + * Where the group the subscriber's track holds at `key` ends, once it finished whole: its span + * is `[key, end)`. Undefined for a group not held, still open, or ended without one. */ - previousStart: (subscriber: Subscriber, start: bigint) => bigint | undefined; + wholeEnd: (subscriber: Subscriber, key: bigint) => bigint | undefined; + /** + * The span of the group the subscriber's track holds finished whole that holds `key` strictly + * past its start, which no other group starts inside; undefined when none does. + */ + wholeAround: (subscriber: Subscriber, key: bigint) => Run | undefined; /** * Where the run of keys from `key` that no group can arrive at on the subscriber's track ends: * a skip, or with `dropped` a drop given up for good. Mirrors the Rust crate-private @@ -1016,6 +1019,8 @@ export const hooks: { groupOffset: (group: GroupProducer) => number; /** Whether this source copy can no longer serve frame 0: it began past it, or shed it. */ groupHeadless: (group: GroupProducer) => boolean; + /** Where a source copy finished whole ends, undefined while it is open or ended without one. */ + groupWholeEnd: (group: GroupProducer) => bigint | undefined; writeGroupFrame: (group: GroupProducer, frame: Frame, inflated?: number) => void; /** Payload footprint including a shared inflated copy, for measurements. */ groupCacheBytes: (group: GroupProducer) => number; @@ -1350,7 +1355,10 @@ export const hooks: { landed: () => { throw new Error("track.ts not loaded"); }, - previousStart: () => { + wholeEnd: () => { + throw new Error("track.ts not loaded"); + }, + wholeAround: () => { throw new Error("track.ts not loaded"); }, holeEnd: () => { @@ -1425,6 +1433,9 @@ export const hooks: { groupHeadless: () => { throw new Error("group.ts not loaded"); }, + groupWholeEnd: () => { + throw new Error("group.ts not loaded"); + }, startGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/drop_record.test.ts b/js/net/src/lite/drop_record.test.ts index d7e079e0ab..d2d6a98ec4 100644 --- a/js/net/src/lite/drop_record.test.ts +++ b/js/net/src/lite/drop_record.test.ts @@ -572,9 +572,12 @@ test("a run of billions of sequences is settled by each reader in one step, drop ["group", 1n + 2n * BILLIONS], ]); } - // The skip rides the GROUP above it, whose Previous Start passes over the run. + // Each run goes out as it was learned, as one message. for (const hop of ["up", "down"] as const) - expect(wire.on(hop)).toEqual([["drop", 1n, 1n + BILLIONS, StreamCode.Cancel]]); + expect(wire.on(hop)).toEqual([ + ["drop", 1n, 1n + BILLIONS, StreamCode.Cancel], + ["skip", 1n + BILLIONS, 1n + 2n * BILLIONS, undefined], + ]); 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 9b010d9623..d98b0f1dc3 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -1,9 +1,10 @@ import { expect, test } from "bun:test"; -import { ProtocolViolation, StreamCode, StreamError, TimestampMismatch } from "../error.ts"; +import { ProtocolViolation, StreamCode, StreamError } from "../error.ts"; import { Producer } from "../group.ts"; import { hooks } from "../internal.ts"; import { concat, encodeVarint, Reader, Writer } from "../stream.ts"; import { Timestamp } from "../time.ts"; +import { RESERVED } from "../util/key.ts"; import * as Varint from "../varint.ts"; import { frameDecoder, Group, readFrames, type WireFrame } from "./group.ts"; import { frameHeader } from "./publisher.ts"; @@ -187,11 +188,10 @@ test("a lite-07 GROUP_END still waiting for its FIN stops once the group closes" 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. +// An End past the largest group end, 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], + ["an End past 2^64-1", lite07(0, 2), RESERVED - 1n], ["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) => { @@ -200,12 +200,76 @@ test.each([ 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 () => { +// A lite-07 GROUP_END's End is a delta from the highest timestamp the stream carried, or from the +// group's start when it carried none: 0 ends the group there. +test("a lite-07 GROUP_END counts from the stream's highest timestamp", async () => { + expect(await readLite07(lite07(0, 0), 5n)).toBe(5n); + expect(await readLite07(lite07(0, 3), 5n)).toBe(8n); + // Frame 0 at the start (delta 0), then one 40 later: End is 40 + 20 past the start. + expect(await readLite07(lite07(2, 0, 7, 2, 80, 8, 0, 20), 1000n)).toBe(1060n); +}); + +// The first lite-07 FRAME on a stream counts its delta from the Group Start, so frame 0 carries 0; +// later ones count from the frame before. Before lite-07 the first delta counts from 0. +test("a lite-07 stream's first delta counts from the group's start", async () => { + const producer = new Producer(1000n); + const consumer = producer.consume(); + await readFrames(streamOf([lite07(2, 0, 7, 2, 66, 8)], Version.DRAFT_07), producer, { + scale: SCALE, + lengthFirst: true, + }); + expect((await consumer.readFrame())?.timestamp?.value).toBe(1000); + expect((await consumer.readFrame())?.timestamp?.value).toBe(1033); + + const older = new Producer(1000n); + const read = older.consume(); + await readFrames(streamOf([encode([{ delta: 1000, payload: [7] }])]), older, { scale: SCALE }); + expect((await read.readFrame())?.timestamp?.value).toBe(1000); +}); + +// A resumed stream (Frame Start above 0) has no frame 0, and still counts its first delta from the +// group's start, as does a Fetch Stream, which decodes with the fetched group's start. +test("a resumed lite-07 stream counts its first delta from the group's start", async () => { + const producer = new Producer(1000n); + hooks.startGroup(producer, 3); + const consumer = producer.consume(); + // Frame 3 sits 99 past the start, and the group ends 33 past it. + const end = await readFrames(streamOf([lite07(2, 198, 7, 0, 33)], Version.DRAFT_07), producer, { + scale: SCALE, + lengthFirst: true, + }); + expect(end).toBe(1132n); + const frame = await consumer.readFrame(); + expect(frame?.payload).toEqual(new Uint8Array([7])); + expect(frame?.timestamp?.value).toBe(1099); + + // A FETCH response's decoder is handed the fetched group's start the same way. + const decode = frameDecoder({ scale: SCALE, start: 2000n, lengthFirst: true }); + const fetched = streamOf([lite07(2, 0, 7, 0, 10)], Version.DRAFT_07); + expect(((await fetched.decode(decode)) as WireFrame).timestamp?.value).toBe(2000); + expect(await fetched.decode(decode)).toEqual({ end: 2010n }); +}); + +// B-frames send timestamps backwards within a group, so GROUP_END counts from the highest one, not +// the last. +test("a lite-07 group with B-frames ends at a delta from its highest frame", async () => { + const producer = new Producer(0n); + const consumer = producer.consume(); + // Presentation order 0, 100, 33, 66: the highest is 100, and the group ends at 133. + const bytes = lite07(2, 0, 1, 2, 200, 2, 2, 133, 3, 2, 66, 4, 0, 33); + const end = await readFrames(streamOf([bytes], Version.DRAFT_07), producer, { scale: SCALE, lengthFirst: true }); + expect(end).toBe(133n); + const times = []; + for (let i = 0; i < 4; i++) times.push((await consumer.readFrame())?.timestamp?.value); + expect(times).toEqual([0, 100, 33, 66]); + producer.finishAt(end as bigint); +}); + +// A lite-07 FRAME on a scale-less track carries no Timestamp Delta: its time is its group's start. +test("a scale-less lite-07 FRAME carries no timestamp", async () => { const producer = new Producer(9n); const consumer = producer.consume(); - await readFrames(streamOf([lite07(2, 18, 7, 2, 0, 8)], Version.DRAFT_07), producer, { + const end = await readFrames(streamOf([lite07(2, 7, 2, 8, 0, 3)], Version.DRAFT_07), producer, { scale: 0, lengthFirst: true, }); @@ -214,31 +278,29 @@ test("a scale-less lite-07 FRAME carries its group's start", async () => { 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); + // With no timestamps the End counts from the group's start. + expect(end).toBe(12n); + // The publisher writes no delta either. + const header = frameHeader(Version.DRAFT_07, undefined, undefined, 1, true); + expect(Array.from(header)).toEqual([2]); }); -// 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. Lite-06 on carries a Frame Start. -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, key: 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 partial = (version: Version) => - Writer.collect(version, (w) => new Group({ subscribe: 1n, key: 7n, frameStart: 4 }).encode(w, version)); - expect(Array.from(await partial(Version.DRAFT_06))).toEqual([3, 1, 7, 4]); - expect(Array.from(await partial(Version.DRAFT_07))).toEqual([4, 1, 7, 0, 4]); - await expect(partial(Version.DRAFT_05)).rejects.toThrow(); +// Lite-07 GROUP drops the Previous Start it once carried: Subscribe ID, Group Start, Frame Start. +// Lite-06 on carries the Frame Start. +test("a lite-07 GROUP carries its start and frame start", async () => { + const encode = (version: Version, frameStart = 0) => + Writer.collect(version, (w) => new Group({ subscribe: 1n, key: 7n, frameStart }).encode(w, version)); + expect(Array.from(await encode(Version.DRAFT_07))).toEqual([3, 1, 7, 0]); + expect(Array.from(await encode(Version.DRAFT_06))).toEqual([3, 1, 7, 0]); + expect(Array.from(await encode(Version.DRAFT_06, 4))).toEqual([3, 1, 7, 4]); + expect(Array.from(await encode(Version.DRAFT_07, 4))).toEqual([3, 1, 7, 4]); + await expect(encode(Version.DRAFT_05, 4)).rejects.toThrow(); 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(), group.frameStart]).toEqual([4n, { start: 5n, end: 7n }, 0]); - expect((await decode([4, 1, 7, 0, 2], Version.DRAFT_07)).frameStart).toBe(2); - 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(); + const group = await decode([3, 1, 7, 2], Version.DRAFT_07); + expect([group.subscribe, group.key, group.frameStart]).toEqual([1n, 7n, 2]); + expect((await decode([3, 1, 7, 0], Version.DRAFT_06)).frameStart).toBe(0); }); // Stream end at the Payload Length ends a lite-07 group; within the rest of the header, it cut a frame. diff --git a/js/net/src/lite/group.ts b/js/net/src/lite/group.ts index 8bfbf07e85..326567808f 100644 --- a/js/net/src/lite/group.ts +++ b/js/net/src/lite/group.ts @@ -1,26 +1,20 @@ import { race } from "@moq/signals"; -import { FrameTooLarge, StreamCode, StreamError, TimestampMismatch } from "../error.ts"; +import { FrameTooLarge, StreamCode, StreamError } from "../error.ts"; import type * as netGroup from "../group.ts"; import { hooks } from "../internal.ts"; import { decodePayload, receiveFrame, type WirePayload } from "../payload.ts"; import type { Cursor, Reader, Writer } from "../stream.ts"; import * as Time from "../time.ts"; import { toNumber } from "../util/bigint.ts"; +import { RESERVED } from "../util/key.ts"; import { MAX_FRAME_BYTES } from "../util/limits.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, hasGroupEnd, type Version } from "./version.ts"; +import { hasFrameBounds, type Version } from "./version.ts"; export class Group { subscribe: bigint; key: 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 `key` as a malformed track. - */ - previous?: bigint; - /** * The index of the first frame on this stream within the group. * @@ -33,33 +27,20 @@ export class Group { constructor({ subscribe, key: sequence, - previous, frameStart = 0, }: { subscribe: bigint; key: bigint; - previous?: bigint; frameStart?: number; }) { this.subscribe = subscribe; this.key = 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.key); - } - async #encode(w: Writer, version: Version) { await w.u62(this.subscribe); await w.u62(this.key); - // 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) { @@ -71,10 +52,8 @@ export class Group { static async #decode(r: Reader, version: Version): Promise { const subscribe = await r.u62(); const key = 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, key: key, previous, frameStart }); + return new Group({ subscribe, key: key, frameStart }); } async encode(w: Writer, version: Version): Promise { @@ -90,16 +69,6 @@ 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. @@ -126,12 +95,13 @@ export interface GroupEnd { /** 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. */ + scale: number; /** - * 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`. + * The group's start, which a lite-07 stream's first timestamp delta counts from and a + * GROUP_END's End counts from when the stream carries no timestamp. Before lite-07 the first + * delta counts from 0. */ - 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; @@ -147,36 +117,43 @@ export interface FrameFormat { * 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. + * + * On lite-07 the first delta counts from the group's `start`, whatever frame the stream starts at, + * and GROUP_END's End counts from the highest timestamp the stream carried (B-frames go + * backwards), or from `start` when it carried none. Mirrors the Rust `FrameIngest`. */ export function frameDecoder({ scale, - start, + start = 0n, 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; + let prevTs = lengthFirst ? start : 0n; + // The highest timestamp decoded so far, which a GROUP_END's End counts from. + let highest: bigint | undefined; return (c) => { let size = 0; if (lengthFirst) { const length = c.u53(); - if (length === 0) return { end: c.u62() }; + if (length === 0) { + const end = (highest ?? start) + c.u62(); + if (end > RESERVED) throw malformed(`GROUP_END at ${end}, past the largest group end`); + return { end }; + } size = length - 1; } - const delta = stamped ? unzigzag(c.u62()) : 0n; + const delta = timescale !== undefined ? 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. if (compress && (size > MAX_FRAME_BYTES || (inflated ?? 0) > MAX_FRAME_BYTES)) throw new FrameTooLarge(); const payload = compress ? c.read(size) : decodePayload(c, size); // Commit the delta only after the last read: an incomplete decode gets retried. + if (timescale === undefined) return { size, payload, inflated }; 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 }; + if (highest === undefined || prevTs > highest) highest = prevTs; + return { size, payload, inflated, timestamp: new Time.Timestamp(toNumber(prevTs), timescale) }; }; } @@ -184,7 +161,7 @@ export function frameDecoder({ * 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. + * after GROUP_END is malformed. */ export async function readFrames( stream: Reader, @@ -200,7 +177,6 @@ export async function readFrames( const frame = stream.tryDecode(decode) ?? (await race([stream.decodeMaybe(decode), producer.closed])); if (!frame || frame instanceof Error) return undefined; if ("end" in frame) { - if (frame.end <= producer.start) throw malformed(`GROUP_END at ${frame.end}, not past the group's start`); // 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]); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 3a34664dc6..9891237c3c 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -873,27 +873,31 @@ async function servedSubscription( const header = await GroupMessage.decode(reader, version); const payloads: string[] = []; + const times: bigint[] = []; let end: bigint | undefined; + let endDelta: bigint | undefined; + // Lite-07 counts the first delta from the group's start, and GROUP_END from the highest. + const lengthFirst = hasLengthFirst(version); + let ts = lengthFirst ? header.key : 0n; + let highest: 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, where 0 is GROUP_END and its End. - const lengthFirst = hasLengthFirst(version); + // leads with the size plus one instead, where 0 is GROUP_END and its End delta. const length = lengthFirst ? (await reader.u53()) - 1 : undefined; if (length === -1) { - end = await reader.u62(); + endDelta = await reader.u62(); + end = (highest ?? header.key) + endDelta; continue; } - await reader.u62(); + const zigzag = await reader.u62(); + ts += (zigzag >> 1n) ^ -(zigzag & 1n); + times.push(ts); + if (highest === undefined || ts > highest) highest = ts; const size = length ?? (await reader.u53()); payloads.push(new TextDecoder().decode(await reader.read(size))); } - return { - key: header.key, - frameStart: header.frameStart, - payloads, - previous: header.previous, - end, - }; + const served = { key: header.key, frameStart: header.frameStart, payloads }; + return lengthFirst ? { ...served, times, end, endDelta } : served; }, // Stop the next group stream the publisher opened with `code`, before reading any of it, // as a subscriber that discards a stream unread does. @@ -1317,28 +1321,131 @@ test("lite-07 ends a finished group with GROUP_END and a closed one with a bare } }); -// 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 () => { +// A lite-07 GROUP_END's End is a delta from the highest frame timestamp the stream carried: B-frames +// send timestamps backwards, so the highest is not the last. +test("lite-07 GROUP_END counts from the highest frame of a group with B-frames", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + const group = sub.track.createGroup(1000n); + for (const ms of [1000, 1100, 1033, 1066]) group.writeFrame(textFrame("x", Timestamp.fromMillis(ms))); + group.finishAt(1133n); + expect(await sub.servedGroup()).toMatchObject({ + key: 1000n, + times: [1000n, 1100n, 1033n, 1066n], + endDelta: 33n, + end: 1133n, + }); + } finally { + await sub.close(); + } +}); + +// A group may end at its highest frame (delta 0), and one with no frame at its start. +test("lite-07 GROUP_END may end a group at its highest frame or its start", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + const group = sub.track.createGroup(1000n); + group.writeFrame(textFrame("x", Timestamp.fromMillis(1040))); + group.finishAt(1040n); + expect(await sub.servedGroup()).toMatchObject({ key: 1000n, times: [1040n], endDelta: 0n, end: 1040n }); + const empty = sub.track.createGroup(2000n); + empty.finishAt(2000n); + expect(await sub.servedGroup()).toMatchObject({ key: 2000n, times: [], endDelta: 0n, end: 2000n }); + } finally { + await sub.close(); + } +}); + +// A subscription starting partway into a group gets a stream with Frame Start above 0, whose first +// delta still counts from the group's start: it carries no frame 0 to count from. +test("lite-07 counts a resumed stream's first delta from the group's start", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 1000n, startFrame: 1 }); + try { + const group = sub.track.createGroup(1000n); + for (const ms of [1000, 1033, 1066]) group.writeFrame(textFrame("x", Timestamp.fromMillis(ms))); + group.finishAt(1100n); + expect(await sub.servedGroup()).toMatchObject({ + key: 1000n, + frameStart: 1, + times: [1033n, 1066n], + end: 1100n, + }); + } finally { + await sub.close(); + } +}); + +// A declared skip goes out as SUBSCRIBE_SKIP as soon as the publisher learns of it, even below a +// group it serves. Mirrors the Rust `lite07_skips_a_declared_skip`. +test("lite-07 sends a declared skip below a served group as SUBSCRIBE_SKIP", async () => { const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); try { sub.serve(0n); - expect(await sub.servedGroup()).toMatchObject({ key: 0n, previous: undefined }); + expect(await sub.servedSequence()).toBe(0n); sub.serve(3n); sub.track.skipGroups(1n, 3n); - expect(await sub.servedGroup()).toMatchObject({ key: 3n, previous: 0n }); + expect(await sub.servedSequence()).toBe(3n); + sub.track.finish(); + sub.track.close(); + expect(await holesToFinish(sub.client.reader)).toEqual([["skip", 1n, 3n]]); + } finally { + await sub.close(); + } +}); + +// Appending names the starts between one group's End and the next group's start with +// SUBSCRIBE_SKIP: a pause, or a sparse data track's gaps. Contiguous groups, each starting at the +// previous End, skip nothing, and the starts inside each span are accounted for by its GROUP_END. +test("lite-07 skips a pause and a sparse track's gaps, but nothing between contiguous groups", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + const append = (start: number, end: number) => { + const group = sub.track.appendGroup(Timestamp.fromMillis(start)); + group.writeFrame(textFrame("x", Timestamp.fromMillis(start))); + group.finishAt(BigInt(end)); + }; + // Contiguous: each starts at the previous End. + append(0, 500); + expect(await sub.servedGroup()).toMatchObject({ key: 0n, end: 500n }); + append(500, 1000); + expect(await sub.servedGroup()).toMatchObject({ key: 500n, end: 1000n }); + // A pause: [1000, 1700) is named. + append(1700, 2000); + expect(await sub.servedGroup()).toMatchObject({ key: 1700n, end: 2000n }); + // A sparse track whose groups end at their start: each skip starts just past it. + append(2100, 2100); + expect(await sub.servedGroup()).toMatchObject({ key: 2100n, endDelta: 0n, end: 2100n }); + append(2200, 2200); + expect(await sub.servedGroup()).toMatchObject({ key: 2200n, end: 2200n }); sub.track.finish(); sub.track.close(); - expect(await holesToFinish(sub.client.reader)).toEqual([]); + expect(await holesToFinish(sub.client.reader)).toEqual([ + ["skip", 1000n, 1700n], + ["skip", 2000n, 2100n], + ["skip", 2101n, 2200n], + ]); + } finally { + await sub.close(); + } +}); + +// A drop of a group held whole names its span, so the subscriber accounts for the starts inside it. +test("lite-07 drops a whole group's span", async () => { + const sub = await servedSubscription({ version: Version.DRAFT_07, startGroup: 0n }); + try { + const group = sub.track.createGroup(0n); + group.writeFrame(textFrame("x", Timestamp.fromMillis(0))); + group.finishAt(500n); + await sub.stopServed(StreamCode.Cancel); + expect(await holesToFinish(sub.client.reader, 1)).toEqual([["drop", 0n, 500n]]); } 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 () => { +// A skipped run goes out as SUBSCRIBE_SKIP ahead of a drop of the group above it. Mirrors the Rust +// `lite07_sends_a_skip_ahead_of_a_drop`. +test("lite-07 sends a 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); @@ -2654,7 +2761,14 @@ test("blocked DROP responses stop opening later groups", async () => { }); /** One group stream the publisher put on the wire. */ -type Served = { key: bigint; frameStart: number; payloads: string[]; previous?: bigint; end?: bigint }; +type Served = { + key: bigint; + frameStart: number; + payloads: string[]; + times?: bigint[]; + end?: bigint; + endDelta?: 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 da9f002725..6d2a940831 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -58,7 +58,7 @@ import { Answer } from "./answer.ts"; 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, passedOver } from "./group.ts"; +import { Group as GroupMessage } from "./group.ts"; import { Probe } from "./probe.ts"; import { type Applied, @@ -140,19 +140,18 @@ export function frameHeader( /** * 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. + * would start, then the group's exclusive `end` as a delta from `base`: the highest timestamp the + * stream carried, or the group's start when it carried none. A finished group's end is at or + * above both, so the delta is never negative. */ -function groupEnd(version: StreamVersion, end: bigint): Uint8Array { - return concat([encodeVarint(0, version), encodeVarint(end, version)]); +function groupEnd(version: StreamVersion, end: bigint, base: bigint): Uint8Array { + return concat([encodeVarint(0, version), encodeVarint(end - base, version)]); } /** How a lite hop stamps a track's frames and datagrams. */ interface Stamp { - /** - * 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 wire timescale TRACK_INFO declared (see `wireTimescale`). */ + 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 @@ -162,22 +161,22 @@ interface Stamp { } /** - * 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. + * How `version` stamps a track with `info`, or undefined when its frames carry no timestamps: + * before lite-05, and on a scale-less lite-07 track, whose frame's time is its group's start (its + * datagrams go out bare). Lite-05/06 declare milliseconds for a scale-less track. */ function stamping(version: Version, info: { timescale?: Timescale | null }): Stamp | undefined { const timescale = info.timescale ?? undefined; const wire = wireTimescale(version, timescale); - if (wire === undefined) return hasLengthFirst(version) ? {} : undefined; + if (wire === undefined) return undefined; return timescale === undefined ? { timescale: wire } : { timescale: wire, timed: info }; } /** - * 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. + * A frame's `timestamp` as its raw wire value: 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)); } @@ -258,8 +257,11 @@ 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; + /** + * Lite-07: called as the stream buffers GROUP_END with the group's end, so the starts inside + * the group's span are accounted for. + */ + ended?: (end: bigint) => void; } /** @@ -1606,48 +1608,23 @@ 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; - }; + // A drop of a group held whole names its span, `[start, max(End, start + 1))`, so the + // subscriber accounts for the starts inside it too: no other group starts there. + const reach = (end: bigint): bigint => max(end, hooks.wholeEnd(track, end - 1n) ?? end); // 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); - const msg = holeMessage(gap.start, gap.end, hole); + // The starts inside a group served whole are its GROUP_END's to account for, which may + // still be on its way, or its drop's, which names its span. + const around = hooks.wholeAround(track, gap.start); + const from = around && record.told(around.start) ? min(around.end, gap.end) : gap.start; + if (from >= gap.end) continue; + record.tell(from, gap.end, report); + const msg = holeMessage(from, gap.end, hole); if (!(await controls.response(encodeSubscribeResponse(stream, msg, this.version)))) return false; } return true; @@ -1655,26 +1632,12 @@ 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. 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. + // earlier drop ended stays ended. A drop of a group held whole names its span. const forward = async (start: bigint, end: bigint, hole: Hole): Promise => { if (!record || start >= end) return true; + if (!hole.skip) end = reach(end); record.tell(start, end, reportOf(hole)); - 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)); + return controls.response(encodeSubscribeResponse(stream, holeMessage(start, end, hole), this.version)); }; // The track's exclusive final boundary. A Rust subscriber feeds SUBSCRIBE_FINISH @@ -1724,10 +1687,9 @@ 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, 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 } }[] = []; + // Groups whose stream failed, with why, for the control stream to name, as runs: a group held + // whole names its span. + const pendingDrops: { start: bigint; end: bigint; error: Error }[] = []; // Cancels groups still queued for a stream slot. Only the subscriber leaving counts: // a track that ran out of groups still has to flush the ones already queued, and the @@ -1754,8 +1716,7 @@ export class Publisher { skipped.length = 0; } if (pendingDrops.length > 0) { - for (const { start, end, error, passed } of pendingDrops.splice(0)) { - if (passed.start < passed.end && !(await skip(passed.start, passed.end))) return false; + for (const { start, end, error } of pendingDrops.splice(0)) { 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)))) @@ -1817,8 +1778,6 @@ export class Publisher { bounds.endFrame = update.endFrame; bounds.starts = bounds.startsAfter.get(update) ?? new Map(); 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 @@ -2026,16 +1985,6 @@ export class Publisher { return false; } record?.tell(group.start, group.start + 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.start); - elided.delete(group.start); - let previous: bigint | undefined; - if (hasGroupEnd(this.version)) { - const cached = hooks.previousStart(track, group.start); - const run = from !== undefined && from > 0n ? from - 1n : undefined; - previous = cached === undefined || run === undefined ? (cached ?? run) : min(cached, run); - } const options: RunGroup = { sub, @@ -2047,7 +1996,11 @@ export class Publisher { unsubscribed, start: range.start, end: range.end, - previous, + // The starts inside a group sent whole are accounted for by its GROUP_END, so the + // end-of-track scan never drops them. + ended: (end) => { + if (end > group.start + 1n) record?.tell(group.start + 1n, end, { kind: "settled" }); + }, }; // The FIN waits for every stream to finish or reset, including one that has not opened yet. // A stream reset to make room fails the group like any other reset, so it is dropped. @@ -2060,12 +2013,8 @@ export class Publisher { options.givenUp.close(); } if (failed && emitRange) { - pendingDrops.push({ - start: group.start, - end: group.start + 1n, - error: failed, - passed: passedOver(options.previous, group.start), - }); + const end = max(group.end ?? group.start, group.start + 1n); + pendingDrops.push({ start: group.start, end, error: failed }); drops.update((revision) => revision + 1); } })(); @@ -2481,7 +2430,9 @@ export class Publisher { } } - let prevTs = 0n; + // Lite-07 counts the first delta from the group's start, and GROUP_END from the highest. + let prevTs = hasGroupEnd(this.version) ? group.start : 0n; + let highest: bigint | undefined; for (let index = startFrame; endFrame === undefined || index <= endFrame; index++) { const read = await race([hooks.readGroupFrame(group, compress), stream.closed]); if (!read) break; @@ -2492,6 +2443,7 @@ export class Publisher { const ts = wireTime(frame.timestamp, stamp); delta = ts - prevTs; prevTs = ts; + highest = max(highest ?? ts, ts); } const header = frameHeader( @@ -2512,7 +2464,7 @@ export class Publisher { // 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 write(() => stream.write(groupEnd(stream.version, end))); + await write(() => stream.write(groupEnd(stream.version, end, highest ?? group.start))); } /** @@ -2568,9 +2520,9 @@ export class Publisher { * @internal */ async #serveGroup(stream: Writer, options: RunGroup) { - const { sub, group, givenUp, stamp, compress, priority, previous, start: startFrame, end: endFrame } = options; + const { sub, group, givenUp, stamp, compress, priority, 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, key: group.start, previous, frameStart: startFrame }); + const msg = new GroupMessage({ subscribe: sub, key: group.start, frameStart: startFrame }); // 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) => { @@ -2590,7 +2542,10 @@ export class Publisher { await msg.encode(stream, this.version); }); - let prevTs = 0n; + // Lite-07 counts the first delta from the group's start, whatever frame the stream starts + // at, and GROUP_END from the highest timestamp sent, since B-frames go backwards. + let prevTs = hasGroupEnd(this.version) ? group.start : 0n; + let highest: bigint | undefined; // 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; @@ -2622,6 +2577,7 @@ export class Publisher { const ts = wireTime(read.frame.timestamp, stamp); delta = ts - prevTs; prevTs = ts; + highest = max(highest ?? ts, ts); } const header = frameHeader( @@ -2643,7 +2599,10 @@ export class Publisher { // Lite-07 ends a finished group with GROUP_END. const end = hasGroupEnd(this.version) && whole ? group.end : undefined; - if (end !== undefined) await write(() => stream.write(groupEnd(stream.version, end))); + if (end !== undefined) { + options.ended?.(end); + await write(() => stream.write(groupEnd(stream.version, end, highest ?? group.start))); + } stream.close(); group.close(); // A stream that fails after its FIN may have lost its header, so report it for a DROP. diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index b5397d0c60..2eb29f4e5b 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1883,6 +1883,56 @@ test("a malformed lite-07 group stream ends only its group", async () => { } }); +// Lite-07: a GROUP_END accounts for the starts inside the group's span, `(start, End)`, in the +// subscription's tail as the group itself is, and the copy records them skipped, ending at End. +test("a lite-07 GROUP_END accounts for the starts inside its group's span", async () => { + const version = Version.DRAFT_07; + const { quic, streams, opened } = fakeSession(); + const subscriber = new Subscriber(quic, version, toHop(1n)); + type Entry = { tail: { covers(start: bigint, end: bigint): 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 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); + await (await opened(1)).reading; + + const stream = handStream(version); + // Frame 0 at the group's start, delta 0, then the End 500 past it. + stream.write(await liteFrame(0, new Uint8Array([1]))); + stream.write( + await Writer.collect(version, async (w) => { + await w.u53(0); + await w.u62(500n); + }), + ); + stream.finish(); + await subscriber.runGroup(new Group({ subscribe: 0n, key: 1000n }), stream.reader); + const group = await track.recvGroup(); + expect((await group?.readFrame())?.timestamp?.value).toBe(1000); + expect(group?.end).toBe(1500n); + if (!entry) throw new Error("no subscription"); + expect(entry.tail.covers(1000n, 1500n)).toBe(true); + expect(entry.tail.covers(1500n, 1501n)).toBe(false); + expect(hooks.holeEnd(track, 1200n, false)).toBe(1500n); + } finally { + responses.mockRestore(); + track.close(); + subscriber.close(); + } +}); + // A TRACK reset while its SUBSCRIBE is live fails the subscription, so the origin can try another // route, and resets the SUBSCRIBE. test("a reset track rejects the subscription and resets its subscribe", async () => { diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 34e1d0f362..82f2916e3c 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -2614,15 +2614,15 @@ export class Subscriber { entry.fills?.refuse(start, end, error); } else if ("skip" in resp) { const { start, end } = resp.skip; - this.#skipped(entry, start, end, "SUBSCRIBE_SKIP"); + this.#skipped(entry, start, end); } } } - // 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 { + // The publisher never produced `[start, end)`, as a SUBSCRIBE_SKIP 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): 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}`)); @@ -2631,7 +2631,7 @@ export class Subscriber { 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`, + `protocol error: SUBSCRIBE_SKIP skips [${start}, ${end}), which holds group ${cached.start}, which arrived; keeping it`, ); } } @@ -2965,16 +2965,6 @@ 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.key) { - stream.stop( - new StreamError(StreamCode.MalformedTrack, { - message: `group ${group.key} names group ${group.previous} as the one before it`, - }), - ); - return; - } // Asked before this stream accounts for the group: a drop that overtook it named it. let owed = !tail.covers(group.key, group.key + 1n); // A drop that overtook this stream, rather than a gap the grace gave up on. @@ -3023,11 +3013,6 @@ export class Subscriber { offset: 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.key}`); // Released once this copy took the group, so the failed copy's readers find it. arriving?.release(); // A drop that overtook the header already accounts for the group; a copy served again is @@ -3040,7 +3025,15 @@ export class Subscriber { // Whole at a GROUP_END's end, else without one: every frame sent arrived. if (end === undefined) producer.finish(); - else producer.finishAt(end); + else { + producer.finishAt(end); + // No other group starts inside the span, which the tail counts as it counts the + // group, and the track records skipped, as its own publisher's append did. + if (end > group.key + 1n) { + tail.account(group.key + 1n, end); + hooks.skipTrackGroups(track, group.key + 1n, 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 c05f4a219b..e6391c9457 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -723,9 +723,9 @@ 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. Added in lite-07; earlier - * versions end every group with a bare FIN. + * Whether a Group or Fetch Stream ends a finished group with GROUP_END and a closed one with a bare + * FIN, and counts its first FRAME's timestamp delta from the group's start. Added in lite-07; + * earlier versions end every group with a bare FIN and count the first delta from 0. */ export function hasGroupEnd(version: Version): boolean { switch (version) { diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 579a6c8b30..2c2aec75d1 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -5468,6 +5468,29 @@ test("an append skips the holes created groups left below it", () => { expect(hooks.tryRecvGroup(late, true)).toEqual({ kind: "idle" }); }); +// A group's end may equal its start or its highest frame timestamp, and no lower: B-frames send +// timestamps backwards, so the highest is not the last. Mirrors the Rust `finish_at`. +test("a group's end is at or above its start and its highest frame", () => { + const producer = new TrackProducer("test"); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + const write = (start: number, frames: number[]) => { + const group = producer.createGroup(BigInt(start)); + for (const ms of frames) group.writeFrame(textFrame("x", Timestamp.fromMillis(ms))); + return group; + }; + expect(() => write(1000, []).finishAt(999n)).toThrow(TimestampMismatch); + expect(write(2000, []).finishAt(2000n).consume().end).toBe(2000n); + expect(() => write(3000, [3000, 3100, 3033]).finishAt(3099n)).toThrow(TimestampMismatch); + expect(write(4000, [4000, 4100, 4033]).finishAt(4100n).consume().end).toBe(4100n); + // A streamed frame keeps its own scale, which the end is compared in the track's. + const streamed = producer.createGroup(5000n); + const frame = streamed.createFrame({ size: 1, timestamp: Timestamp.fromMicros(5_100_000) }); + frame.write(new Uint8Array([1])); + frame.finish(); + expect(() => streamed.finishAt(5099n)).toThrow(TimestampMismatch); + expect(streamed.finishAt(5100n).consume().end).toBe(5100n); +}); + // A late group created out of order reaches a reader, since creating a group skips nothing. test("a late local group reaches a reader, since creating out of order skips nothing", () => { const producer = new TrackProducer("test"); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 040caf533b..3429154356 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1006,6 +1006,11 @@ let fillFloor: (producer: Producer, named: bigint | undefined) => bigint | undef // The keys of the groups the producer caches, sorted: what relative and time anchors resolve // against, as the Rust `TrackState::lookup` keys; assigned in its static block. let keysOf: (producer: Producer) => readonly bigint[]; +// The span of the held group finished whole that holds `key` strictly past its start, undefined +// when none does; assigned in its static block. +let wholeAround: (producer: Producer, key: bigint) => Run | undefined; +// Where the held group at `key` ends, once finished whole; assigned in its static block. +let wholeAt: (producer: Producer, key: bigint) => bigint | undefined; // How a received copy resolves its readers' time anchors, as its wire tells it; assigned in the // producer's static block. See `hooks.startsAtKeys` and `hooks.timeStarts`. let timeAnchors: (producer: Producer) => { @@ -1596,6 +1601,18 @@ export class Producer { sourceStart = (producer) => producer.#wire?.served && producer.#feedStart(); fillFloor = (producer, named) => producer.#fillFloor(named); keysOf = (producer) => producer.#keys; + wholeAt = (producer, key) => { + const entry = producer.#cached.get(key); + return entry && hooks.groupWholeEnd(entry.group); + }; + wholeAround = (producer, key) => { + const keys = producer.#keys; + const index = keyIndex(keys, key); + if (index === 0 || keys[index] === key) return undefined; + const start = keys[index - 1]; + const end = wholeAt(producer, start); + return end !== undefined && key < end ? { start, end } : undefined; + }; timeAnchors = (producer) => ({ atKeys: producer.#startsAtKeys, starts: producer.#timeStarts, @@ -2480,7 +2497,13 @@ export class Producer { group.closed.then((closed) => { // An aborted live edge is no longer protected, so it may expire like any other. if (closed instanceof Error) this.#account.demote(entry); - if (!(closed instanceof Error)) return; + if (closed === null) { + // A group the feed delivered whole accounts for its span: no other group starts + // strictly inside it, so a pending tail owes none of them. + const end = hooks.groupWholeEnd(group); + if (!fetched && end !== undefined && end > group.start + 1n) this.#arrive(group.start + 1n, end); + return; + } // A re-created group already replaced this one. const current = this.#cached.get(group.start); if (current && current.group !== group) return; @@ -4657,15 +4680,16 @@ export class Subscriber { return producer !== undefined && cachedHolds(producer, key); }; hooks.holeEnd = (subscriber, key, dropped) => holeEnd(subscriber.#state.drops, key, dropped); - 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; + hooks.wholeEnd = (subscriber, key) => { + // A reader following route copies knows only what the serving copy holds. + if (subscriber.#resume) return undefined; + const producer = subscriber.#state.producer; + return producer && wholeAt(producer, key); + }; + hooks.wholeAround = (subscriber, key) => { + if (subscriber.#resume) return undefined; const producer = subscriber.#state.producer; - return producer !== undefined && cachedIn(producer, below, start).length > 0 ? below : undefined; + return producer && wholeAround(producer, key); }; hooks.staleHeld = (subscriber, start, end) => { const held: Run[] = []; diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index 5170612361..042141871d 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -213,8 +213,8 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato ends.set(arrival.group, i); }); // A publisher keying groups by timestamp never produces the keys between two groups whose media - // is back to back, and each GROUP's Previous Start tells the subscriber so as it lands. Keys - // between media that is not are owed, since a group there went missing. + // is back to back, and the GROUP_END of the group below tells the subscriber so: its span reaches + // the next start. Keys between media that is not are owed, since a group there went missing. const spans = new Map(); for (const { group, timestamp, duration } of trace) { const span = spans.get(group); diff --git a/quest/m2/README.md b/quest/m2/README.md index 1f35dbe04d..74a41b1dc6 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -48,8 +48,7 @@ removal, a rename, or a wire, catalog, or format change that is free until - **Catalog, drafts, and formats.** hang-04 (done: the `sync` section, a version per entry, no video `warmup`, the TS passthrough under `mpegts`, one strict rule); declared ends, back from m3, which became a whole marker on 2026-11-19 - and [an end again](/quest/m2/time-addressing/group-times.md) on - 2026-11-20. + and an end again on 2026-11-20 ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)). - **Native media and gateways.** [Upstream str0m](https://github.com/moq-dev/moq/pull/8963), which reverses the 2026-10-30 vendoring. - **Bindings.** The C API as `libmoq` (done), reversing 2026-10-25. @@ -69,8 +68,10 @@ the same whichever relay or reader serves it: [no relative anchors](/quest/m2/time-addressing/no-relative-anchors.md), with Min Age placing a live join; [scale-less tracks aging by arrival](/quest/m2/time-addressing/scale-less-arrival.md); -[Group Streams carrying each time once](/quest/m2/time-addressing/group-times.md), -with GROUP_END's end back as a delta. +Group Streams carrying each time once ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)), +with GROUP_END's end back as a delta; +[time anchors landing by group spans](/quest/m2/time-addressing/span-time-anchors.md); +and [first-party producers keeping those spans apart](/quest/m2/producer-spans.md). [moq-dev/moq#9198](https://github.com/moq-dev/moq/pull/9198) and [moq-dev/moq#9221](https://github.com/moq-dev/moq/pull/9221) closed, since relative starts and the bare GROUP_END are gone. diff --git a/quest/m2/groups-never-overlap.md b/quest/m2/groups-never-overlap.md index b36a043b73..39ac9b718c 100644 --- a/quest/m2/groups-never-overlap.md +++ b/quest/m2/groups-never-overlap.md @@ -9,7 +9,7 @@ still reorder (B-frames, open-GOP leading pictures). Sources that overlap today, such as a TS content join, publish without ending the broadcast and without rewriting a timestamp. The hang draft states the rule, and the producers and every importer keep it, in Rust and JS. -[Group times](/quest/m2/time-addressing/group-times.md) puts it in the moq-lite +Group times ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)) put it in the moq-lite draft, as spans from a group's lowest frame to its End that never overlap. ## Plan @@ -78,6 +78,13 @@ them too. The hang draft's "a group MAY start at the same timestamp as the previous group" goes too. +Group times ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)) +found one more overlap this fixes: a keyframe below the open group's newest +frame cuts it at an estimated End past the keyframe (moq-mux +`Producer::prepare`), so the next group starts inside that span, which a +lite-07 copy refuses. Continuing the group, as decided above, fixes it. The +spans' other cases are [producer spans](/quest/m2/producer-spans.md)'s. + Tests: the producer test above becomes one where the overlapping keyframe continues the group, and a TS import across a content join, including leading pictures, publishes groups whose frames all precede every frame of the next @@ -87,6 +94,7 @@ Public API: none expected. Wire: none; the hang draft's group rule tightens. ## Related -- [Group Streams carry each time once](/quest/m2/time-addressing/group-times.md) - states the rule in the moq-lite draft, with GROUP_END's End closing each span +- [A time anchor lands by group spans](/quest/m2/time-addressing/span-time-anchors.md) - resolves a time against the spans this rule keeps apart +- [First-party producers keep lite-07 group spans apart](/quest/m2/producer-spans.md) - the guards, the discontinuity marker, and the leading pictures' End, which this leaves - [An incomplete group expires by the lowest timestamp of a higher group](/quest/m3/expire-by-higher-min.md) - the expiry bound this rule makes safe - [An fMP4 group start never rewinds the decode timeline](/quest/m3/fmp4-group-start-tfdt.md) - a keyframe repeating its predecessor's timestamp would now continue the group; check which of its cases remain diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index b808267733..37663a1281 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -221,7 +221,7 @@ Decided 2026-11-20 (maintainer, /quest-plan auditing the cache, timestamp, and switching rules in `rs/moq-net/AGENTS.md` before the cut): - ✅ The cut waits for [groups never overlap](/quest/m2/groups-never-overlap.md) - (rejected: after the cut). [Group times](/quest/m2/time-addressing/group-times.md) + (rejected: after the cut). Group times ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)) puts the strong rule in the draft as a publisher MUST: a group's span, from its lowest frame to its End, never overlaps another's. Expiry relies on it, and first-party producers break it today. @@ -237,8 +237,9 @@ and switching rules in `rs/moq-net/AGENTS.md` before the cut): ## Required - [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) - SUBSCRIBE's anchors lose Relative, and Min Age places a live join -- [Group Streams carry each time once](/quest/m2/time-addressing/group-times.md) - GROUP loses Previous Start, FRAME's first delta counts from the start, and GROUP_END carries an end +- [A time anchor lands by group spans](/quest/m2/time-addressing/span-time-anchors.md) - the draft's Time Anchor rule resolves a time inside a skipped span or a whole group's span - [Groups never overlap](/quest/m2/groups-never-overlap.md) - first-party producers and importers keep the no-overlap MUST the cut publishes +- [First-party producers keep lite-07 group spans apart](/quest/m2/producer-spans.md) - no group starts or presents inside a span a lower group's End closed - [A lite-07 claim is shown no broader than the grants it crossed](/quest/m2/lite07-claim-reach-routes.md) - a peer is never shown a claim at a path no route of it can serve, through any number of relays (maintainer, 2026-11-20) ## Related diff --git a/quest/m2/producer-spans.md b/quest/m2/producer-spans.md new file mode 100644 index 0000000000..10ecdc789c --- /dev/null +++ b/quest/m2/producer-spans.md @@ -0,0 +1,82 @@ +# [M] First-party producers keep lite-07 group spans apart + +## Goal + +moq-mux's `container::Producer` and hang's legacy `Producer`, in Rust and JS, +keep the lite-07 draft's publisher MUST: a group's span never overlaps +another's, and no group starts after a whole group's start and before its +End. Neither producer closes a group without the End it meant to write. A +lite-07 copy then never refuses a group a first-party producer published. + +## Plan + +Left from group times +([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)), which put the +span rule in the draft and made `group::Producer::finish_at` refuse an End +below a group's highest frame. [Groups never overlap](/quest/m2/groups-never-overlap.md) +([moq-dev/moq#9264](https://github.com/moq-dev/moq/pull/9264)) keeps every +frame of a group after every frame of a lower one, but not the End. Three +cases remain: + +- **The guards.** moq-mux's `close_group` (`rs/moq-mux/src/container/producer.rs`) + and hang's legacy `#close` (`js/hang/src/container/legacy.ts`) close a group + without an End when theirs would fall below the newest frame or the duration + marker. Before #9264, a keyframe below the newest frame hit them + (`h264_join_below_a_p_frame_publishes` and the TS export's unmarked-step + tests fail without the Rust guard). With #9264 merged, every moq-mux test + passes without it (checked on 2026-11-20); only a caller's `cut(Some(end))` + below a frame it wrote still reaches it, for audio, data, or reordered + video, which `close` doesn't refuse. Recommended: delete both guards and + refuse that cut with `InvalidEnd` for every kind, as ordered video already + is. +- **The discontinuity marker.** A discontinuity after `cut(end)` stamps its + marker group one unit below `end`, inside the span of the group `cut` just + ended whole there (moq-mux `Producer::discontinuity`, hang's legacy + `discontinuity`). A lite-07 copy records that span skipped once its + GROUP_END arrives, so it refuses the marker if it arrives second. + `container::ts::recovery_test::a_lost_discontinuity_marker_still_breaks_the_clock` + exercises it locally. Recommended: when the closing group ended whole, + stamp the marker at its End and key the next group strictly after it, as a + seek's marker already does (`crate::start::next`). +- **Open-GOP leading pictures.** `container::Producer` finishes a group whole + at the next keyframe's timestamp, above that keyframe's leading pictures, so + the next group's lowest frame falls inside the span when the span runs from + the lowest frame, as the draft says. The next group's lowest frame isn't + known when its keyframe cuts, since leading pictures follow it in decode + order. Moq-net's accounting already uses [Group Start, End): a GROUP_END + accounts only the starts strictly inside it. + +Tests: a cut below a written frame is refused for audio and reordered video; +a discontinuity after `cut(end)` publishes a marker a lite-07 copy accepts in +either arrival order; an open-GOP stream publishes groups whose spans hold no +other group's frame or start. Run `/verify-subscribe` if the draft's span +wording changes. + +Public API: `cut(Some(end))` below a written frame returns `InvalidEnd` for +every kind. Wire: none, unless the span wording changes in the lite-07-wip +draft, which is unpublished. + +## Waiting + +- Maintainer: where a group's span starts, given open-GOP leading pictures. + Options: (a) from Group Start, so the draft's span becomes [Group Start, + End) and the strong frame rule stays a separate sentence; nothing in the + producers changes, and a time between a leading picture and its keyframe + resolves to the lower group, which a RASL picture needs anyway to decode; + (b) from the lowest frame, as decided for group times on 2026-11-20, with + the producer ending a group where its own content stops (its duration + marker) and naming the rest up to the keyframe with SUBSCRIBE_SKIP, though + the leading pictures then present inside a span the draft calls a + discontinuity no group contains; (c) from the lowest frame, holding a + group's GROUP_END until the next group's lowest frame is known, which + delays every whole group by the reorder depth. Recommended: (a), since it + matches what moq-net already accounts and needs no producer change. An + agent can't take it because it reverses a maintainer decision. + +## Required + +- [Groups never overlap](/quest/m2/groups-never-overlap.md) - the producers keep every frame of a group after every frame of a lower one, which leaves the guards only a caller's bad cut + +## Related + +- [A time anchor lands by group spans](/quest/m2/time-addressing/span-time-anchors.md) - resolves a time against the spans this keeps apart, including a leading picture's diff --git a/quest/m2/time-addressing/group-times.md b/quest/m2/time-addressing/group-times.md deleted file mode 100644 index d713ca4d9e..0000000000 --- a/quest/m2/time-addressing/group-times.md +++ /dev/null @@ -1,116 +0,0 @@ -# [L] lite-07 Group Streams carry each time once, and GROUP_END the group's end - -## Goal - -On lite-07-wip, a Group Stream carries each time once: - -- GROUP keeps `Group Start` and loses `Previous Start`. -- The first FRAME's `Timestamp Delta` counts from the Group Start (on a Fetch - Stream, from the fetched group's start), so frame 0's delta is 0. -- A FRAME on a scale-less track has no `Timestamp Delta`; its time is its - group's start. -- GROUP_END carries the group's `End` as a delta from its highest frame - timestamp. - -A group's span runs from its lowest frame timestamp to its End and never -overlaps another group's span. The publisher names any span between one -group's End and the next group's start with SUBSCRIBE_SKIP: a discontinuity -that no group contains. Rust, `@moq/net`, the moq-lite draft, and the -subscribe model change together. - -## Plan - -Decided 2026-11-20 (maintainer, /quest-plan of a pre-cut audit of the lite-07 -and hang-04 wire changes). This reverses the 2026-11-19 decisions, made on -closed [moq-dev/moq#9192](https://github.com/moq-dev/moq/pull/9192), that made -GROUP_END a bare whole marker and aged a group with no successor from its -frames; [moq-dev/moq#9221](https://github.com/moq-dev/moq/pull/9221), which -implemented them, is closed. - -- ✅ GROUP_END keeps an end, as a delta from the group's highest frame - timestamp, 0 or more, or from Group Start in a group with no frame - (rejected: a bare whole marker; main's absolute End with its rule relaxed to - "at or above"; a delta from the last frame). The end lets a relay prove a - time falls inside a held whole group without its successor. It also ages a - group exactly when its successor is dropped. - - The base is the highest frame, not the last, because B-frames already send - timestamps backwards within a group (FRAME's delta is signed). A group's - duration is its End minus its lowest frame timestamp. - - A delta of 0 or more also fixes main's rule that End exceed every frame - timestamp. moq-mux broke that rule by writing hang's end marker at T and - finishing the group at T (`container/producer.rs` `close_group`). -- ✅ Previous Start goes, and gaps are covered by End (rejected: a Previous - Gap, as moq-transport's Prior Group ID Gap; a producer finishing a group at - its successor's start). For continuous audio and video, each successor - starts at the previous End and nothing is left to account for. - - ✅ The publisher always names a shortfall, [End, next start), with - SUBSCRIBE_SKIP when it creates the next group, as a discontinuity. In the - maintainer's words, that is "more correct than implying the previous group - contained those timestamps". The cases are a pause, a sparse-keyed data - track (one small SKIP per group), and a group closed without GROUP_END, - where the starts after its own up to the next are skipped. - - `track::Producer::append_group` already records that span as skipped. - The publisher's elision of skips that a GROUP's Previous Start passed over - (`lite/publisher.rs` `TrackRun::elided`) goes. -- ✅ GROUP keeps Group Start, and the first FRAME's delta counts from it. The - maintainer left this to whatever reads better (rejected: frame 0 carrying - the start, since a resumed stream with Frame Start above 0, and an unsent - group, have no frame 0; counting from the previous group's last frame, since - each stream must decode alone). It costs one byte per group over a GROUP - with no start. -- ✅ A scale-less FRAME carries no Timestamp Delta, as an uncompressed track's - carries no Inflated Size (rejected: its own timestamp, which nothing reads, - and which moq-archive's untimed format and libmoq would have to store; a - delta that must be 0). TIMESTAMP_MISMATCH's scale-less case goes. - - moq-transport Object IDs don't ride as frame timestamps. Group and object - numbers are separate spaces there, and an untimed track's Group IDs are - dense, so the `ietf` extension's Object Record keeps `Skip`. - -Recommended, for review: - -- A time inside a skipped span belongs to no group. A time start there begins - at the next group, and a time end there stops after the previous one. - Today's Time Anchor rule ("the group whose start is the highest at or below - it") changes to match. -- A cache proves a time inside a held whole group's span from that group - alone. -- Aging: a whole group's reach is its own End, and any other group's is - bounded by its successor's start, as today. -- With open-GOP leading pictures, a group's lowest frame sits below its - start. Check the Time Anchor rule against spans there, alongside - [groups never overlap](/quest/m2/groups-never-overlap.md). -- `group::Producer::finish_at(end)` and `group::Consumer::end()` stay, since - the end is what GROUP_END encodes. - -Where it lives: - -- Rust wire: `lite/publisher.rs` (`buffer_group_end`, GROUP encoding, - `Stamp`, `TrackRun::elided`, `previous_start`), `lite/subscriber.rs` - (`FrameIngest`, the GROUP decode, `IngestPhase::GroupEnd`), and - `lite/version.rs` (`has_group_end`, which also gates Previous Start). -- JS wire: `js/net/src/lite/group.ts` (`frameDecoder`, `readFrames`), - `js/net/src/lite/publisher.ts` (`groupEnd`, `wireTime`, the elided runs), - and `js/net/src/lite/subscriber.ts`. -- Aging: Rust `model/track.rs` (`reach`, `own_end`, `ended_at`) and JS - `js/net/src/track.ts` (`#endedAt`). -- Draft `drafts/draft-lcurley-moq-lite.md`: Frame, Group, Expiration (reach), - the Time Anchor, GROUP, FRAME, GROUP_END, SUBSCRIBE_SKIP, and the changelog. -- The subscribe model, `rs/moq-net/verify/subscribe/SubscribeAccounting.tla`, - models GROUP's Previous Start passing over skipped runs. Update it and run - `/verify-subscribe`. - -Tests: GROUP, FRAME, and GROUP_END codec round trips and fuzz; a resumed -stream (Frame Start above 0) and a Fetch Stream decode their first delta from -the group's start; a group with B-frames ends at a delta from its highest -frame; a pause and a sparse data track are named in SUBSCRIBE_SKIP while -contiguous groups send none; a group whose successor is dropped ages from its -own End. Run `just test interop --all`. - -Public API: none expected beyond moq-net internals. Wire: lite-07-wip only, -which is unpublished. - -## Related - -- [lite-07 has no relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) - its live join resolves as a time start, which this changes inside a skipped span -- [A scale-less track ages by arrival](/quest/m2/time-addressing/scale-less-arrival.md) - lite-05/06 still stamp a scale-less frame, with its group's start -- [Groups never overlap](/quest/m2/groups-never-overlap.md) - enforces the non-overlap rule in hang's producers and importers diff --git a/quest/m2/time-addressing/no-relative-anchors.md b/quest/m2/time-addressing/no-relative-anchors.md index 1ac3a464d2..b7d9daa287 100644 --- a/quest/m2/time-addressing/no-relative-anchors.md +++ b/quest/m2/time-addressing/no-relative-anchors.md @@ -91,4 +91,4 @@ Wire: lite-07-wip only. ## Related - [Latest readers join live by their Min Age](/quest/m4/readers-range-live.md) - the readers that floor at the largest group move to this join -- [lite-07 Group Streams carry each time once](/quest/m2/time-addressing/group-times.md) - a time inside a skipped span belongs to no group, which changes where a time start lands +- [A time anchor lands by group spans](/quest/m2/time-addressing/span-time-anchors.md) - a time inside a skipped span belongs to no group, which changes where a time start lands diff --git a/quest/m2/time-addressing/scale-less-arrival.md b/quest/m2/time-addressing/scale-less-arrival.md index 5e2efda74c..cf71bd9d46 100644 --- a/quest/m2/time-addressing/scale-less-arrival.md +++ b/quest/m2/time-addressing/scale-less-arrival.md @@ -48,7 +48,3 @@ lite-06 bytes of a scale-less frame match the shared fixture in Rust and JS. Public API: none; a behavior change. Wire: no byte change; lite-07-wip expiry semantics, and a scale-less frame's lite-05/06 timestamp in JS. - -## Related - -- [lite-07 Group Streams carry each time once](/quest/m2/time-addressing/group-times.md) - a scale-less FRAME stops carrying a timestamp on lite-07; lite-05/06 still need this one diff --git a/quest/m2/time-addressing/span-time-anchors.md b/quest/m2/time-addressing/span-time-anchors.md new file mode 100644 index 0000000000..72f4b25de9 --- /dev/null +++ b/quest/m2/time-addressing/span-time-anchors.md @@ -0,0 +1,45 @@ +# [M] A time anchor lands by group spans, and a cache proves a time from a whole group + +## Goal + +On lite-07, a time anchor resolves against group spans, in Rust, `@moq/net`, +and the moq-lite draft. A time inside a skipped span belongs to no group: a +time start there begins at the next group, and a time end there stops after +the previous one. A time inside a held whole group's span resolves to that +group, and a relay's cache answers it from that group alone, without its +successor. Today's Time Anchor rule ("the group whose start is the highest at +or below it") changes to match. + +## Plan + +Left from [moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263), which +made GROUP_END carry a whole group's End and has the publisher name a +shortfall, [End, next start), with SUBSCRIBE_SKIP. The maintainer recommended +both rules for review on 2026-11-20; neither is decided. + +- A copy records the starts strictly inside a whole group's span as skipped + when its GROUP_END arrives (`lite/subscriber.rs`, JS `runGroup`), and a + publisher's append records them the same way, so the track model already + tells a span from a pause. A pause past End is a skip run whose start is + some group's End: the anchor needs to tell "inside a span" from "inside a + pause", which only the End says. +- The cache proof is AGENTS.md's Required rule: answer only what upstream + would answer. A held whole group proves every time in [start, End). +- Check the rule against open-GOP leading pictures, whose lowest frame sits + below the group's start, with + [producer spans](/quest/m2/producer-spans.md), which decides where a span + starts. +- It overlaps [no relative anchors](/quest/m2/time-addressing/no-relative-anchors.md), + whose live join resolves as a time start, and + [moq-dev/moq#9172](https://github.com/moq-dev/moq/pull/9172). + +Where it lives: Rust `model/track.rs` (time starts, `find_landable`, +`outside_spans`), `model/resume.rs`, `lite/publisher.rs` (pinning a time +anchor), JS `js/net/src/track.ts`, and the draft's Time Anchor text. + +Public API: none expected. Wire: none; the draft's Time Anchor rule changes. + +## Related + +- [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) - its live join resolves as a time start, which this changes inside a skipped span +- [First-party producers keep lite-07 group spans apart](/quest/m2/producer-spans.md) - the non-overlap rule this resolution relies on, and where a span starts diff --git a/quest/m3/expire-by-higher-min.md b/quest/m3/expire-by-higher-min.md index 5e5c4605a0..2d7f31ac01 100644 --- a/quest/m3/expire-by-higher-min.md +++ b/quest/m3/expire-by-higher-min.md @@ -24,7 +24,7 @@ hold connection credit other broadcasts need. span; and closed [moq-dev/moq#9221](https://github.com/moq-dev/moq/pull/9221)'s estimate of a mean frame interval). -[Group times](/quest/m2/time-addressing/group-times.md) gives a whole group its +Group times ([moq-dev/moq#9263](https://github.com/moq-dev/moq/pull/9263)) gave a whole group its End and recommends bounding any other group by its successor's start, as `reach` (`rs/moq-net/src/model/track.rs`) and `#reach` (`js/net/src/track.ts`) do today. This quest tightens the second half once producers keep the strong @@ -47,4 +47,3 @@ which only lets a publisher expire sooner. ## Required - [Every frame of a group presents before every frame of a higher group](/quest/m2/groups-never-overlap.md) - first-party producers keep the rule that makes a higher group's lowest timestamp an upper bound -- [Group Streams carry each time once](/quest/m2/time-addressing/group-times.md) - GROUP_END's End, the whole group's bound, and the draft's no-overlap MUST diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index dd077aeee8..65d570b1bf 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -804,6 +804,13 @@ where if let Some(group) = self.group.as_mut() { self.container.finish_group(group, tail_end)?; } + // A group never ends below a frame of its own, here the newest written or the endpoint + // marker, so one whose bound falls below either closes without an end. + let floor = match (self.newest, tail_end) { + (Some(newest), Some(marker)) => Some(super::later(newest, marker)), + (newest, marker) => newest.or(marker), + }; + let bound = bound.filter(|bound| floor.is_none_or(|floor| !timestamp_lt(*bound, floor))); if let Some(group) = self.group.take() { match bound.and_then(|bound| crate::start::end(&self.inner, group.start, bound)) { Some(end) => group.finish_at(end)?, diff --git a/rs/moq-net/fixtures/lite.json b/rs/moq-net/fixtures/lite.json index 53baf85e43..c0bb6553b5 100644 --- a/rs/moq-net/fixtures/lite.json +++ b/rs/moq-net/fixtures/lite.json @@ -341,21 +341,14 @@ "name": "a group sequence at 2^64-1, the largest a u64 holds", "version": "moq-lite-07-wip", "message": "group", - "hex": "0c00ffffffffffffffffff0000", + "hex": "0b00ffffffffffffffffff00", "expect": "decoded" }, { "name": "a lite-07 group starting partway through, at a Frame Start", "version": "moq-lite-07-wip", "message": "group", - "hex": "0401070004", - "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", + "hex": "03010704", "expect": "decoded" }, { diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index dbb0c24132..73a262a91e 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -1186,7 +1186,6 @@ impl LiteSample { Self::Group => lite::Group { subscribe: 3, key: 1_234, - previous: None, frame_start: 0, } .encode(w, version) @@ -1431,7 +1430,6 @@ 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 cd8d9fc71e..35b985a466 100644 --- a/rs/moq-net/src/fuzz/ingest.rs +++ b/rs/moq-net/src/fuzz/ingest.rs @@ -224,11 +224,12 @@ fn run(session: Session, info: &track::Info, body: &[u8], chunk: usize) -> Optio } => { let mut reader = reader(Bytes::copy_from_slice(body), chunk, version); let producer = track.append_next().ok()?; + let clock = lite::Clock::new(version, producer.start); let consumer = producer.consume(); let mut viewer = stored(producer.consume(), info.compressed()); let mut group = crate::recv::Group::new(producer); let framing = lite::Framing::new(info, version); - let mut ingest = lite::FrameIngest::new(framing, records, frame_start); + let mut ingest = lite::FrameIngest::new(framing, records, frame_start, clock); let end = drive(body.len(), |waiter| { let res = ingest.poll(&mut reader, &mut group, waiter); keep_up(&mut viewer); @@ -364,8 +365,7 @@ 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; 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. + // frame carries none. 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]; @@ -386,10 +386,9 @@ pub(super) fn seeds() -> Vec { 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. + // A zero length, then the End, one past the highest frame (or the start, untimed). let mut whole = data.clone(); - whole.extend_from_slice(&[0, if timed { 3 } else { 1 }]); + whole.extend_from_slice(&[0, 1]); push(whole); } push(data); @@ -402,9 +401,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, then a zero - // timestamp delta, which keeps the untimed group's start. - data.extend_from_slice(&[0, 0, payload.len() as u8 + 1, 0]); + // and neither has a property block. The frame's size follows, plus one, and no + // timestamp, since the track is untimed. + data.extend_from_slice(&[0, 0, payload.len() as u8 + 1]); data.extend_from_slice(payload); } push(data); diff --git a/rs/moq-net/src/lite/group.rs b/rs/moq-net/src/lite/group.rs index 829eb68b11..35f3001cf3 100644 --- a/rs/moq-net/src/lite/group.rs +++ b/rs/moq-net/src/lite/group.rs @@ -10,11 +10,6 @@ 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, because the subscription started partway in. Lite06+ only; older versions @@ -23,22 +18,73 @@ pub struct Group { } impl Group { - /// The varints the newest layout carries: Subscribe ID, Group Start, Previous Start and - /// Frame Start. - const FIELDS: usize = 4; + /// The varints the newest layout carries: Subscribe ID, Group Start and Frame Start. + const FIELDS: usize = 3; +} - /// 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 times one Group or Fetch Stream carries: what each FRAME's `Timestamp Delta` counts +/// from, and what GROUP_END's `End` counts from, as raw wire values. +#[derive(Clone, Copy, Debug)] +pub(crate) struct Clock { + /// The group's start, which GROUP_END counts from on a stream that carried no timestamp. + start: u64, + /// The previous FRAME's timestamp, or what the first counts from. + prev: u64, + /// The highest timestamp a FRAME on this stream carried, which GROUP_END counts from. + highest: Option, } -/// 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 Clock { + /// A stream of the group starting at `start`. Lite-07 counts the first FRAME's delta from + /// that start, so frame 0's is 0; earlier versions count it from 0. + pub fn new(version: Version, start: u64) -> Self { + let prev = match version.has_group_end() { + true => start, + false => 0, + }; + Self { + start, + prev, + highest: None, + } + } + + /// The `Timestamp Delta` of the next FRAME, at `timestamp`, which it advances to; `None` + /// when the delta doesn't fit. + pub fn delta(&mut self, timestamp: u64) -> Option { + let delta = (timestamp as i128 - self.prev as i128).try_into().ok()?; + self.advance(timestamp); + Some(delta) + } + + /// The timestamp of the next FRAME, which carries `delta`, and advances to it; `None` when + /// it falls outside 64 bits. + pub fn timestamp(&mut self, delta: i64) -> Option { + let timestamp = (self.prev as i128 + delta as i128).try_into().ok()?; + self.advance(timestamp); + Some(timestamp) + } + + fn advance(&mut self, timestamp: u64) { + self.prev = timestamp; + self.highest = Some(self.highest.map_or(timestamp, |highest| highest.max(timestamp))); + } + + /// What GROUP_END's `End` counts from: the highest timestamp on the stream, or the group's + /// start when none was carried, such as on a scale-less track. + fn base(&self) -> u64 { + self.highest.unwrap_or(self.start) + } + + /// GROUP_END's delta for a group ending at `end`; `None` when `end` is below the base, which + /// a group never is (see [`crate::group::Producer::finish_at`]). + pub fn end_delta(&self, end: u64) -> Option { + end.checked_sub(self.base()) + } + + /// Where a group ends whose GROUP_END carries `delta`; `None` past 64 bits. + pub fn end(&self, delta: u64) -> Option { + self.base().checked_add(delta) } } @@ -51,11 +97,6 @@ impl<'a> Message<'a> for Group { 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, @@ -64,7 +105,6 @@ impl<'a> Message<'a> for Group { Ok(Self { subscribe, key, - previous, frame_start, }) } @@ -72,14 +112,6 @@ 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)?; } else if self.frame_start != 0 { @@ -101,7 +133,6 @@ mod test { let msg = Group { subscribe: 1, key: 7, - previous: None, frame_start: 4, }; for version in [Version::Lite06, Version::Lite07] { @@ -119,7 +150,6 @@ mod test { let msg = Group { subscribe: 1, key: 7, - previous: None, frame_start: 4, }; let mut buf = Vec::new(); @@ -138,42 +168,6 @@ 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. @@ -193,11 +187,10 @@ mod test { Form::Quic => (crate::coding::varint::MAX_QUIC, 8), Form::LeadingOnes => (u64::MAX, crate::coding::varint::MAX_LEN), }; - let fields = 2 + usize::from(version.has_frame_bounds()) + usize::from(version.has_group_end()); + let fields = 2 + usize::from(version.has_frame_bounds()); 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 }, }; @@ -213,19 +206,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.previous, got.frame_start), - (msg.subscribe, msg.key, msg.previous, msg.frame_start), + (got.subscribe, got.key, got.frame_start), + (msg.subscribe, msg.key, msg.frame_start), "{version:?}" ); } - assert_eq!(::MAX_SIZE, 36); + assert_eq!(::MAX_SIZE, 27); 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: 37, max: 36 }) + Err(DecodeError::MessageTooLarge { size: 28, max: 27 }) )); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index c6f670ef39..58403ebe77 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -3100,13 +3100,12 @@ enum FetchServe { msg: lite::Fetch<'static>, fetching: track::Fetching, }, - /// Streaming the group's frames in order. The delta-timestamp baseline - /// resets to 0, so the first served frame's delta is its absolute timestamp - /// (the subscriber decodes against the same baseline). + /// Streaming the group's frames in order, their times counted from the group's start on + /// lite-07, as the FETCH names it, and from 0 before. Serve { group: group::Consumer, stamp: Option, - prev_ts: u64, + clock: lite::Clock, frame: Option, chunk: Option, batch: Box, @@ -3219,10 +3218,11 @@ impl Request for FetchServe { // Only a track a moq-transport publisher made carries records. let records = (ietf && group.ietf().is_some()).then(|| lite::ietf::Records::new(capped)); + let clock = lite::Clock::new(shared.version, group.start); *self = Self::Serve { group, stamp, - prev_ts: 0, + clock, frame: None, chunk: None, batch: Box::default(), @@ -3233,7 +3233,7 @@ impl Request for FetchServe { Self::Serve { group, stamp, - prev_ts, + clock, frame, chunk, batch, @@ -3275,7 +3275,7 @@ impl Request for FetchServe { batched.inflated, batched.frame.payload.len() as u64, *stamp, - prev_ts, + clock, )?; let payload = std::mem::take(&mut batched.frame.payload); if !payload.is_empty() { @@ -3294,7 +3294,7 @@ impl Request for FetchServe { match records { Some(records) => records.end(writer, group)?, None => { - buffer_group_end(writer, shared.version, false, group)?; + buffer_group_end(writer, shared.version, false, group, clock)?; } } return Poll::Ready(Ok(ControlFlow::Break(()))); @@ -3314,7 +3314,7 @@ impl Request for FetchServe { next.inflated, next.size, *stamp, - prev_ts, + clock, )?; *frame = Some(next); return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -3324,7 +3324,7 @@ impl Request for FetchServe { match records { Some(records) => records.end(writer, group)?, None => { - buffer_group_end(writer, shared.version, false, group)?; + buffer_group_end(writer, shared.version, false, group, clock)?; } } return Poll::Ready(Ok(ControlFlow::Break(()))); @@ -4650,7 +4650,7 @@ mod announce_test { /// omitted entirely, saving the bytes on tracks where timing isn't meaningful /// (catalogs, control channels, IETF transport). /// -/// `prev_ts` carries the running baseline, so the first frame deltas against 0. The +/// `clock` carries the running baseline: the group's start on lite-07, else 0. The /// model layer (`group::Producer::create_frame`) already converted a timed frame into /// the track timescale, so its raw value goes straight onto the wire. Mirrors the /// decode in the subscriber's `run_group`. @@ -4665,7 +4665,7 @@ fn buffer_frame_info( inflated: Option, size: u64, stamp: Option, - prev_ts: &mut u64, + clock: &mut lite::Clock, ) -> Result<(), Error> { // Lite-07 leads with the size plus one, leaving 0 for GROUP_END. let length_first = version.has_length_first(); @@ -4676,7 +4676,10 @@ fn buffer_frame_info( writer.buffer_varint(length)?; } if let Some(stamp) = stamp { - buffer_zigzag_delta(writer, stamp.wire(timestamp)?, prev_ts)?; + let delta = clock + .delta(stamp.wire(timestamp)?) + .ok_or(Error::BoundsExceeded(crate::coding::BoundsExceeded))?; + writer.buffer_varint(crate::coding::varint::zigzag(delta))?; } // Only a compressed group read in its stored form has one, and only on lite-07. if let Some(inflated) = inflated { @@ -4698,13 +4701,16 @@ struct Stamp { } impl Stamp { - /// 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. + /// How `version` stamps a track's frames with `timescale`, or `None` when they carry no + /// timestamps: before lite-05, and on a scale-less lite-07 track, whose frames each take + /// their group's start. Lite-05/06 declare milliseconds for a scale-less track. fn new(version: Version, timescale: Option) -> Option { - version.has_track_stream().then(|| Self { - timescale: version.wire_timescale(timescale), - }) + match version.has_track_stream() { + true => version.wire_timescale(timescale).map(|timescale| Self { + timescale: Some(timescale), + }), + false => None, + } } /// A frame or datagram's `timestamp` as its raw wire value. A scale-less track's is its @@ -4723,21 +4729,6 @@ impl Stamp { } } -/// Buffer `curr` as a zigzag-mapped varint delta against `*prev`, then advance -/// `*prev` to `curr`. -fn buffer_zigzag_delta( - writer: &mut Writer, - curr: u64, - prev: &mut u64, -) -> Result<(), Error> { - let delta: i64 = (curr as i128 - *prev as i128) - .try_into() - .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?; - writer.buffer_varint(crate::coding::varint::zigzag(delta))?; - *prev = curr; - Ok(()) -} - /// What [`recv_next`] pulled from the one subscriber: the next group to serve, the track /// declaring its exclusive final key, or the track finishing (the live edge having /// reached that boundary). @@ -5185,9 +5176,25 @@ struct GroupOutcomes { #[cfg(test)] opened: std::sync::atomic::AtomicU64, unencodable: 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)>>, + /// Groups whose stream failed, with why, for the control stream to name: each one's span + /// (see [`span`]). + dropped: Mutex, StreamError)>>, + /// The spans of the groups whose GROUP_END went out, which their stream accounts for. + whole: Mutex>>, +} + +impl GroupOutcomes { + /// Record that the GROUP_END of the group at `key`, ending at `end`, went out. + fn whole(&self, key: u64, end: u64) { + self.whole.lock().unwrap().push(span(key, Some(end))); + } +} + +/// The starts a group at `key` accounts for: through its `end` once it finished whole, since no +/// other group starts inside a whole group's span, and otherwise its own. +fn span(key: u64, end: Option) -> Range { + let next = key.saturating_add(1); + key..end.map_or(next, |end| end.max(next)) } impl Subscription { @@ -5228,7 +5235,6 @@ impl Subscription { self.group_context(), key, frame_start, - None, false, Rank::Queue(priority), group, @@ -5334,14 +5340,6 @@ struct TrackRun { /// Lite-07: the ranges whose relative or time anchors may still resolve; see /// [`Self::pin`]. unpinned: Unpinned, - /// 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, } /// Lite-07 ranges whose relative or time anchors may still resolve, by Range ID, each due @@ -5430,8 +5428,6 @@ impl TrackRun { initial, unstarted: Default::default(), unpinned, - elided: Default::default(), - recheck_elided: false, bounded, requested: Requested::new((0..).zip(bounds.ranges.iter().copied())), frames: bounds.frames, @@ -5469,7 +5465,6 @@ 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); @@ -5793,10 +5788,6 @@ 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 @@ -5825,16 +5816,18 @@ impl TrackRun { return Poll::Ready(Err(err)); } + // The starts inside a whole group's span went out with its GROUP_END, so the end of the + // track names none of them. + let whole = std::mem::take(&mut *self.ctx.outcomes.whole.lock().unwrap()); + for span in whole { + self.mark_served(span); + } 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. 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)))?; + // is served or dropped over it again. + for (span, err) in dropped { + writer.buffer(&self.hole(span, &Hole::drop(err)))?; } return Poll::Ready(Ok(ControlFlow::Continue(()))); } @@ -5941,8 +5934,8 @@ impl TrackRun { && crate::priority::in_group(key, 0, order) < crate::priority::in_group(waiting.key, 0, order) { tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, key, "shedding a group ranked below one waiting for credit"); - self.mark_served(key); - self.shed(key); + self.mark_served(key..key + 1); + self.shed(&group); return Poll::Ready(Ok(ControlFlow::Continue(()))); } match &mut self.start { @@ -6062,18 +6055,18 @@ impl TrackRun { Ok(true) } - /// Record `key` as served, for [`Self::drop_unserved`]. - fn mark_served(&mut self, key: u64) { + /// Record `groups` as served, for [`Self::drop_unserved`]: a group's own start, or the + /// span a whole group's GROUP_END accounted for. + fn mark_served(&mut self, groups: Range) { if self.start.emits_range() { - self.track.record_mut().tell(key..key + 1, Report::Settled); + self.track.record_mut().tell(groups, Report::Settled); } } /// 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. 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. + /// earlier drop ended stays ended. A drop takes in the rest of a whole group's span it + /// reaches into. Returns whether any was buffered. fn forward_range( &mut self, range: Range, @@ -6083,79 +6076,16 @@ impl TrackRun { if !self.start.emits_range() || range.is_empty() { return Ok(false); } + let range = match hole { + Hole::Skip => range, + Hole::Drop { .. } => range.start..self.track.span_end(range.end), + }; let report = self.report(hole); self.track.record_mut().tell(range.clone(), report); - 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(run, hole))?; + 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. - /// Returns whether any was buffered. - fn send_elided( - &mut self, - groups: Range, - writer: &mut Writer, - ) -> 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))?; - } - Ok(!above.is_empty()) - } - - /// 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() { @@ -6179,8 +6109,6 @@ impl TrackRun { if !self.start.emits_range() || range.is_empty() { return Ok(false); } - // 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() { @@ -6188,7 +6116,7 @@ impl TrackRun { let msg = self.hole(gap.clone(), hole); writer.buffer(&msg)?; } - Ok(elided || !gaps.is_empty()) + Ok(!gaps.is_empty()) } /// The message naming `groups` given up as `hole`: lite-07 skips what was never @@ -6394,20 +6322,10 @@ impl TrackRun { fn serve(&mut self, group: group::Consumer) { let key = group.start; let frame_start = group.index(); - self.mark_served(key); + self.mark_served(key..key + 1); 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. - // 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 => 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(); - self.open(group, frame_start, previous); + self.open(group, frame_start); } /// The rank of the group waiting for stream credit, if it cannot make room: it ranks below @@ -6441,22 +6359,16 @@ impl TrackRun { /// Give up a group the cursor handed out without a stream, as one expired under the /// subscription's budget is. - fn shed(&mut self, key: u64) { + fn shed(&mut self, group: &group::Consumer) { if self.ctx.version.has_track_stream() { - let passed = self.elided.remove(&key).map_or(key..key, |start| start..key); - self.ctx - .outcomes - .dropped - .lock() - .unwrap() - .push((key, StreamError::Old, passed)); + let span = span(group.start, group.end()); + self.ctx.outcomes.dropped.lock().unwrap().push((span, StreamError::Old)); } } - /// 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) { + /// 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) { let key = group.start; // The stream stops at the end frame, before the group may end. let capped = self.frames.end(key).is_some(); @@ -6481,7 +6393,6 @@ impl TrackRun { self.ctx.group_context(), key, frame_start, - previous, capped, rank, group, @@ -6804,23 +6715,26 @@ fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option( writer: &mut Writer, version: Version, records: bool, group: &group::Consumer, -) -> Result { + clock: &lite::Clock, +) -> Result, Error> { if !version.has_group_end() || records { - return Ok(false); + return Ok(None); } let Some(end) = group.end().filter(|_| group.index() >= group.frame_count() as u64) else { - return Ok(false); + return Ok(None); }; + // A group never ends below a frame of its own (see `group::Producer::finish_at`). + let delta = clock.end_delta(end).ok_or(Error::TimestampMismatch)?; writer.buffer_varint(0)?; - writer.buffer_varint(end)?; - Ok(true) + writer.buffer_varint(delta)?; + Ok(Some(end)) } /// Serves one group on its own unidirectional stream: the header, then every @@ -6833,15 +6747,10 @@ 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, - // Lite05+ delta-encodes per-frame timestamps within the group. The first - // frame's delta is absolute (against an implicit prev value of 0), every - // subsequent delta is signed against the previous frame. - prev_ts: u64, + /// The times the stream carried, which each FRAME's delta and GROUP_END count from. + clock: lite::Clock, state: GroupState, // A long cached group drains a slice per poll, so its siblings still run. budget: kio::coop::Budget, @@ -6899,31 +6808,23 @@ impl GroupServe { 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 { + fn new(ctx: GroupContext, key: u64, frame_start: u64, 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(), false => group, }; let meter = group.delegate(); + let clock = lite::Clock::new(ctx.version, key); Self { ctx, rank, open: Default::default(), group, + clock, key, frame_start, - previous, capped, - prev_ts: 0, state: GroupState::Open, budget: kio::coop::Budget::new(32), meter, @@ -6983,7 +6884,6 @@ 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)); @@ -7153,7 +7053,7 @@ impl GroupServe { batched.inflated, batched.frame.payload.len() as u64, self.ctx.stamp, - &mut self.prev_ts, + &mut self.clock, ) }); if let Err(err) = buffered { @@ -7183,12 +7083,14 @@ impl GroupServe { self.ctx.version, self.ctx.object_records, &self.group, + &self.clock, ) { - Ok(true) => { + Ok(Some(end)) => { + self.ctx.outcomes.whole(self.key, end); *ending = Ending::Whole; continue; } - Ok(false) => break 'serve Ok(()), + Ok(None) => break 'serve Ok(()), Err(err) => break 'serve Err(err), } } @@ -7221,7 +7123,7 @@ impl GroupServe { next.inflated, next.size, self.ctx.stamp, - &mut self.prev_ts, + &mut self.clock, ) }); if let Err(err) = buffered { @@ -7240,12 +7142,14 @@ impl GroupServe { self.ctx.version, self.ctx.object_records, &self.group, + &self.clock, ) { - Ok(true) => { + Ok(Some(end)) => { + self.ctx.outcomes.whole(self.key, end); *ending = Ending::Whole; continue; } - Ok(false) => break 'serve Ok(()), + Ok(None) => break 'serve Ok(()), Err(err) => break 'serve Err(err), } } @@ -7327,11 +7231,13 @@ impl GroupServe { if !self.ctx.version.has_track_stream() { return; } - self.ctx.outcomes.dropped.lock().unwrap().push(( - self.key, - StreamError::from(err), - lite::passed_over(self.previous, self.key), - )); + let span = span(self.key, self.group.end()); + self.ctx + .outcomes + .dropped + .lock() + .unwrap() + .push((span, StreamError::from(err))); } } @@ -7595,23 +7501,21 @@ mod serve_group_test { } } - /// 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. + /// 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 nothing on lite-07, where each + /// frame takes its group's start. A timed track carries its own timestamps on every version + /// from lite-05, 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}"); } - assert_eq!( - Stamp::new(Version::Lite06, None).unwrap().timescale, - Some(crate::Timescale::MILLI) - ); - assert_eq!(Stamp::new(Version::Lite07, None).unwrap().timescale, None); + let stamp = Stamp::new(Version::Lite06, None).unwrap(); + assert_eq!(stamp.wire(Timestamp::unscaled(7)).unwrap(), 7); + assert_eq!(stamp.timescale, Some(crate::Timescale::MILLI)); + assert!(Stamp::new(Version::Lite07, None).is_none()); assert!(Stamp::new(Version::Lite04, Some(crate::Timescale::MILLI)).is_none()); } @@ -7771,9 +7675,10 @@ mod serve_group_test { let (bytes, fin) = first_stream(&log); assert!(fin, "finished={finished}: no FIN"); - // The frame: its length plus one, the timestamp delta, and the payload. + // The frame: its length plus one, the timestamp delta from the group's start, and the + // payload; then GROUP_END, its End 3 past the frame at 2. let tail: &[u8] = match finished { - true => &[2, 4, b'x', 0, 5], + true => &[2, 4, b'x', 0, 3], false => &[2, 4, b'x'], }; assert!(bytes.ends_with(tail), "finished={finished}: {bytes:?}"); @@ -8505,8 +8410,8 @@ 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)> { + /// Each Group Stream's Group Start on `log`'s session, in order. + fn group_headers(log: &Log, version: Version) -> Vec { let mut streams = std::collections::BTreeMap::<_, Vec>::new(); for (id, sent) in log.trail() { if let Sent::Write(bytes) = sent { @@ -8519,7 +8424,7 @@ mod serve_group_test { 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)) + Ok(group.key) }) .unwrap() }) @@ -9085,10 +8990,7 @@ mod serve_group_test { )); assert_eq!(run.floor, 4000); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let served: Vec = group_headers(&session, Version::Lite07) - .into_iter() - .map(|(start, _)| start) - .collect(); + let served: Vec = group_headers(&session, Version::Lite07); assert!(served.contains(&4000), "served {served:?}"); } @@ -9229,10 +9131,7 @@ mod serve_group_test { )); assert_eq!(run.floor, 4000); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - let served: Vec = group_headers(&session, Version::Lite07) - .into_iter() - .map(|(start, _)| start) - .collect(); + let served: Vec = group_headers(&session, Version::Lite07); assert!(served.contains(&4000), "served {served:?}"); } @@ -9388,10 +9287,10 @@ mod serve_group_test { ); } - /// 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. + /// A key the publisher declared it will never produce goes out as SUBSCRIBE_SKIP, with no + /// stream, even below a group whose stream opens. #[kio::test] - async fn lite07_skips_a_declared_skip() { + async fn lite07_sends_a_declared_skip() { let mut track = track::Producer::new( Arc::new(broadcast::Info::default()), "test", @@ -9400,27 +9299,21 @@ mod serve_group_test { let subscriber = track.subscribe(None); 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); - assert!(futures::poll!(run.as_mut()).is_pending()); - write_group(&mut track, 2, 2); - track.skip_groups(1..2); - 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, 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))]); + 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, 3]); + assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3)]); } - /// 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. + /// Appending skips the starts between groups, but a whole group's GROUP_END names those in + /// its span first, so the SKIP names only the pause from its end to the next start, and + /// contiguous groups send none, even when each finishes as the next is appended. #[kio::test] - async fn lite07_sends_an_elided_skip_ahead_of_a_drop() { - let mut track = track::Producer::new( + async fn lite07_skips_only_past_a_whole_groups_end() { + let track = track::Producer::new( Arc::new(broadcast::Info::default()), "test", crate::track::Info::timed(), @@ -9428,32 +9321,32 @@ mod serve_group_test { 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); + let open = |start: u64| { + let mut group = track.append_group(Timestamp::from_millis(start).unwrap()).unwrap(); + group + .write_frame(Timestamp::from_millis(start).unwrap(), b"x".as_slice()) + .unwrap(); + group + }; + // Each group finishes as the next is appended, before the publisher runs again. + let group = open(0); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - track.skip_groups(1..3); - write_group(&mut track, 3, 3); + group.finish_at(4).unwrap(); + let group = open(4); 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)); + group.finish_at(6).unwrap(); + let group = open(10); + while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} + group.finish_at(12).unwrap(); while run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready() {} - assert_eq!(holes(&mut writer, &log).await, [("skip", 1..3), ("drop", 3..4)]); + assert_eq!(group_headers(&session, Version::Lite07), [0, 4, 10]); + assert_eq!(holes(&mut writer, &log).await, [("skip", 6..10)]); } - /// 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. + /// A drop of a group held whole names its span, which no other group starts inside, so the + /// subscriber accounts for those starts too. #[kio::test] - async fn lite07_sends_a_held_skip_when_its_group_is_dropped() { + async fn lite07_a_whole_groups_drop_names_its_span() { let mut track = track::Producer::new( Arc::new(broadcast::Info::default()), "test", @@ -9464,61 +9357,52 @@ mod serve_group_test { 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"); + let mut group = track.create_group(group::Info { start: 3 }).unwrap(); + group + .write_frame(Timestamp::from_millis(3).unwrap(), b"x".as_slice()) + .unwrap(); + group.finish_at(6).unwrap(); 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 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); + assert_eq!(holes(&mut writer, &log).await, [("drop", 3..6)]); + // A skip names only the starts it covers. 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))]); + assert_eq!(holes(&mut writer, &log).await, [("drop", 3..6), ("skip", 1..3)]); } - /// 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. + /// A whole group's span holds no other start, so the end of the track names none of them, + /// while the gap past its end that nothing declared is dropped as any other. #[kio::test] - async fn lite07_a_held_skip_joins_its_groups_skip() { + async fn lite07_a_whole_groups_span_is_not_dropped_at_the_end() { 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)]); + let mut run = std::pin::pin!(kio::wait(move |waiter| run.poll(&mut writer, waiter))); + + let mut group = track.create_group(group::Info { start: 0 }).unwrap(); + group + .write_frame(Timestamp::from_millis(0).unwrap(), b"x".as_slice()) + .unwrap(); + group.finish_at(4).unwrap(); + assert!(futures::poll!(run.as_mut()).is_pending()); + write_group(&mut track, 6, 6); + let _track = track.finish().unwrap(); + assert!(futures::poll!(run.as_mut()).is_pending(), "the stream stays open"); + + let writes = log.writes.lock().unwrap().clone(); + let mut buf = writes.as_slice(); + let mut holes = Vec::new(); + while !buf.is_empty() { + let (msg, size) = lite::SubscribeResponse::decode_slice(buf, Version::Lite07).unwrap(); + buf = &buf[size..]; + if let lite::SubscribeResponse::Drop(drop) = msg { + holes.push(drop.groups); + } + } + assert_eq!(holes, vec![4..6]); } /// A relay forwards a SKIP over a DROP it already forwarded for the same groups, since the @@ -9564,9 +9448,8 @@ mod serve_group_test { } } - /// 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. + /// A huge declared skip goes out at a cost independent of its length, as one SUBSCRIBE_SKIP, + /// and the end settles over it. #[kio::test] async fn lite07_skips_a_huge_run_at_once() { const FAR: u64 = 1 << 61; @@ -9599,8 +9482,8 @@ mod serve_group_test { _ => {} } } - assert_eq!((skips, drops), (vec![(FAR + 1, FAR + 5)], 0)); - assert_eq!(group_headers(&session, Version::Lite07), [(0, None), (FAR, Some(0))]); + assert_eq!((skips, drops), (vec![(1, FAR), (FAR + 1, FAR + 5)], 0)); + assert_eq!(group_headers(&session, Version::Lite07), [0, FAR]); } /// A relay that holds only the first group of a backlog answers with the largest its @@ -9769,12 +9652,7 @@ 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, 3..3)); + run.ctx.outcomes.dropped.lock().unwrap().push((3..4, 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}"); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 395a812143..2302d8222c 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -393,24 +393,6 @@ 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" - ); - } - } // The subscription's end waits until this stream is read. Counted // whatever the cache said, since the publisher counts every stream it // opens (a resubscribe resends a cached group), and only after the @@ -1413,11 +1395,6 @@ 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. let parked: Option<(kio::Consumer, u64)> = { @@ -1528,7 +1505,8 @@ impl GroupRecv { // Guarded: dropping this machine mid-group is a cancellation, not a clean end. let group: crate::recv::Group = group; let track: track::Producer = track; - let mut ingest: FrameIngest = FrameIngest::new(framing, records, hdr.frame_start); + let clock = lite::Clock::new(self.subscriber.version, hdr.key); + let mut ingest: FrameIngest = FrameIngest::new(framing, records, hdr.frame_start, clock); let reading: Reading = reading; // Filling the group, bailing if the track or group dies first. The track or group @@ -1544,8 +1522,21 @@ impl GroupRecv { }); let res = match res { - // Whole at a GROUP_END's end, else closed: every frame sent arrived. - Ok(end) => group.end(end), + // Whole at a GROUP_END's end, else closed: every frame sent arrived. A whole group's + // span holds no other start, so its stream accounts for those starts too, and the + // track records them skipped, as its own publisher's append did. + Ok(end) => { + if let Some(end) = end { + reading.account(hdr.key..end, self.subscriber.runtime.now()); + } + let ended = group.end(end); + if ended.is_ok() + && let Some(end) = end + { + track.skip_groups(hdr.key.saturating_add(1)..end); + } + ended + } Err(err @ (Error::Cancel | Error::Stream(crate::StreamError::Cancel))) => { let _ = group.abort(err); Ok(()) @@ -1566,12 +1557,11 @@ 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 { - /// 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. + /// Whether frames carry the zigzag-delta timestamp prefix, in the track's timescale: + /// lite-05+, except a scale-less lite-07 track, whose frames each take their 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). - prev_ts: u64, + /// The times the stream carried, which each FRAME's delta and GROUP_END count from. + clock: lite::Clock, phase: IngestPhase, /// Where the stream's frames start, the first Object ID until a record names it. frame_start: u64, @@ -1608,7 +1598,8 @@ enum IngestPhase { /// Lite-07: reading the `Payload Length`, the payload size plus one, which leads the /// frame, or 0 for GROUP_END. Stream end here means the group closed incomplete. Length, - /// Lite-07: reading GROUP_END's `End`, the group's exclusive end. + /// Lite-07: reading GROUP_END's `End`, the group's exclusive end as a delta from the + /// stream's highest timestamp. GroupEnd, /// Lite-07: GROUP_END said where the group ends, so only the stream end may follow. Finished { end: u64 }, @@ -1635,11 +1626,12 @@ enum IngestPhase { impl FrameIngest { /// `records` when the session negotiated the `ietf` extension and a moq-transport - /// publisher made the track, so the stream starts with a Group State. - pub(crate) fn new(framing: lite::Framing, records: bool, frame_start: u64) -> Self { + /// publisher made the track, so the stream starts with a Group State. `clock` counts the + /// stream's times from its group's start. + pub(crate) fn new(framing: lite::Framing, records: bool, frame_start: u64, clock: lite::Clock) -> Self { Self { framing, - prev_ts: 0, + clock, phase: match records { true => IngestPhase::State, false => Self::first_field(framing), @@ -1807,7 +1799,11 @@ impl FrameIngest { self.phase = IngestPhase::Timing { size: Some(size) }; } IngestPhase::GroupEnd => { - let end = ready!(reader.poll_varint(waiter))?; + let delta = ready!(reader.poll_varint(waiter))?; + let end = self + .clock + .end(delta) + .ok_or(Error::BoundsExceeded(crate::coding::BoundsExceeded))?; self.phase = IngestPhase::Finished { end }; } IngestPhase::Finished { end } => { @@ -1827,16 +1823,13 @@ impl FrameIngest { let Some(zz) = ready!(self.poll_header_varint(reader, size.is_none(), waiter))? else { return Poll::Ready(Ok(None)); }; - let next: u64 = (self.prev_ts as i128 + crate::coding::varint::unzigzag(zz) as i128) - .try_into() + let next = self + .clock + .timestamp(crate::coding::varint::unzigzag(zz)) + .ok_or(Error::BoundsExceeded(crate::coding::BoundsExceeded))?; + let scale = self.framing.timescale.expect("only a timed track is stamped"); + let timestamp = Timestamp::new(next, scale) .map_err(|_| Error::BoundsExceeded(crate::coding::BoundsExceeded))?; - self.prev_ts = next; - // 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), @@ -4398,7 +4391,6 @@ mod tests { lite::Group { subscribe: 7, key: 3, - previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut bytes, version.into()), version) @@ -4485,7 +4477,6 @@ mod tests { lite::Group { subscribe: 7, key, - previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -4591,7 +4582,6 @@ mod tests { let header = lite::Group { subscribe: 7, key: 0, - previous: None, frame_start: 0, }; receive_lite07(framing, true, header, body).await @@ -4675,24 +4665,23 @@ mod tests { } } - /// Group `key`'s header on subscription 7, naming `previous` as the group before it. - fn lite07_header(key: u64, previous: Option) -> lite::Group { + /// Group `key`'s header on subscription 7. + fn lite07_header(key: u64) -> 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. + /// sent but no end: each frame is its `Payload Length`, a timestamp delta from the group's + /// start, 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; + let (res, track, _) = receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(0), body).await; res.unwrap(); let mut group = track.consume().peek_group(0).unwrap(); assert_eq!( @@ -4704,20 +4693,18 @@ mod tests { } } - /// 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. + /// Anything after GROUP_END, an End past 64 bits, 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"), + (5, &[2, 4, x, 0, u64::MAX], "an End past 64 bits"), (0, &[0], "a stream ending inside GROUP_END"), ] { - let (res, track, _) = - receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(key, None), body).await; + let (res, track, _) = receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(key), 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() {} @@ -4728,43 +4715,41 @@ mod tests { 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. + /// A lite-07 FRAME on a scale-less track carries no timestamp: its time is its group's + /// start, and GROUP_END counts from that start. #[kio::test] - async fn a_scale_less_frame_carries_its_groups_start() { + async fn a_scale_less_frame_takes_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; + let (res, track, _) = receive_lite07(lite07(None), false, lite07_header(9), &[2, x, 2, x, 0, 3]).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:?}"); - } + assert_eq!(group.end(), Some(12)); } - /// 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. + /// The first FRAME counts from the group's start, later ones from the frame before, and + /// GROUP_END from the highest frame, not the last, since B-frames go back in time. The + /// whole group's span holds no other start, so a reader waits for none there. #[kio::test] - async fn a_groups_previous_start_skips_the_starts_between() { + async fn group_end_counts_from_the_highest_frame() { 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; + let zigzag = crate::coding::varint::zigzag; + // Frames at 10, 12 and 10, then an End 3 past 12. + let body = [2, zigzag(0), x, 2, zigzag(2), x, 2, zigzag(-2), x, 0, 3]; + let (res, track, _) = receive_lite07(lite07(Some(Timescale::MILLI)), false, lite07_header(10), &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"); + let mut group = track.consume().peek_group(10).unwrap(); + for millis in [10, 12, 10] { + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.timestamp, Timestamp::from_millis(millis).unwrap()); } + assert_eq!(group.end(), Some(15)); + let consumer = track.subscribe(None); + assert!(consumer.is_skipped(11..15), "no group starts inside the span"); + assert!(!consumer.is_skipped(15..16), "the next group may start at the end"); } /// Object records: `(Skip << 1) | END`, the properties block's length, then the frame. @@ -4895,14 +4880,18 @@ mod tests { lite::Group { subscribe: 7, key: 5, - previous: None, frame_start: 0, } .encode(&mut encoder, version) .unwrap(); - // The first delta is absolute. - for delta in deltas { - encoder.varint(crate::coding::varint::zigzag(*delta)).unwrap(); + // The first delta counts from the group's start on lite-07, and from 0 before. + let base = match version.has_group_end() { + true => 5, + false => 0, + }; + for (index, delta) in deltas.iter().enumerate() { + let delta = if index == 0 { delta - base } else { *delta }; + encoder.varint(crate::coding::varint::zigzag(delta)).unwrap(); encoder.bytes(b"frame").unwrap(); } let session = crate::lite::test_transport::ScriptedSession::eof(script); @@ -5058,7 +5047,6 @@ mod tests { lite::Group { subscribe: 7, key: 3, - previous: None, frame_start: 0, } .encode(&mut crate::coding::Encoder::new(&mut script, version.into()), version) @@ -5129,7 +5117,6 @@ mod tests { lite::Group { subscribe: 7, key: 3, - previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -5244,7 +5231,6 @@ mod tests { lite::Group { subscribe: 7, key: 3, - previous: None, frame_start: 0, } .encode(&mut encoder, version) @@ -6857,7 +6843,6 @@ mod tests { lite::Group { subscribe: 0, key, - previous: None, frame_start: 0, } .encode(&mut w, version) @@ -6934,7 +6919,6 @@ mod tests { lite::Group { subscribe: 0, key, - previous: None, frame_start: 0, } .encode(&mut w, version) @@ -6990,7 +6974,6 @@ mod tests { let header = |key| lite::Group { subscribe: 0, key, - previous: None, frame_start: 0, }; let mut entry = TrackEntry::new(None, Default::default()); @@ -10083,7 +10066,6 @@ mod tests { lite::Group { subscribe: 7, key: 0, - previous: None, frame_start: start, } .encode(&mut encoder, version) @@ -13698,8 +13680,10 @@ impl kio::Task for FetchServeRun { producer: Box::new(crate::recv::Group::new(producer)), readers, ingest: Box::new({ - let framing = lite::Framing::new(&info, self.serve.subscriber.version); - FrameIngest::new(framing, ietf && framing.ietf.is_some(), frame_start) + let version = self.serve.subscriber.version; + let framing = lite::Framing::new(&info, version); + let clock = lite::Clock::new(version, self.group); + FrameIngest::new(framing, ietf && framing.ietf.is_some(), frame_start, clock) }), }; } diff --git a/rs/moq-net/src/lite/subscriber/fills.rs b/rs/moq-net/src/lite/subscriber/fills.rs index ebe71857b2..8d955b333b 100644 --- a/rs/moq-net/src/lite/subscriber/fills.rs +++ b/rs/moq-net/src/lite/subscriber/fills.rs @@ -255,9 +255,9 @@ 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. + // What the copy records skipped is never produced, such as the starts inside a whole + // group's span, which its GROUP_END names rather than a SUBSCRIBE_SKIP: 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() { diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index fe5f7630bd..653b939293 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -127,8 +127,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 or, - /// on lite-07, a scale-less track's bare number (see [`Self::stamped`]). + /// The units of every frame Timestamp on the wire, or `None` when frames carry none: before + /// lite-05, and on a scale-less lite-07 track. 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. @@ -152,11 +152,10 @@ impl Framing { } } - /// 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. + /// Whether every FRAME carries a timestamp: lite-05/06 always declare a timescale, and a + /// scale-less lite-07 track's frames carry none, since each one's time is its group's start. pub fn stamped(&self) -> bool { - self.timescale.is_some() || self.length_first + self.timescale.is_some() } } diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 03ca6b6ff3..0995601f79 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -289,9 +289,10 @@ 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. Added in lite-07; - /// earlier versions end every group with a bare FIN. + /// Whether a Group or Fetch Stream ends a finished group with GROUP_END, its end counted + /// from the stream's highest timestamp, and a closed one with a bare FIN, and counts its + /// first FRAME's timestamp from the group's start. Added in lite-07; earlier versions end + /// every group with a bare FIN and count the first timestamp from 0. pub(crate) fn has_group_end(self) -> bool { !matches!( self, diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 40c06bf6cc..ce0c5786b0 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2287,9 +2287,11 @@ 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`], which aborts the group. Fails with the abort error if the - /// group was already aborted. + /// [`track::Info::max_age`]). Its span, from its start to `end`, holds no other group's + /// start, so no successor may start before `end`. An `end` below the group's start or + /// below any of its frames' timestamps is [`Error::TimestampMismatch`], which aborts the + /// group; one equal to either is a group that presents no further. Fails with the abort + /// error if the group was already aborted. pub fn finish_at(self, end: u64) -> Result { if let Err(err) = self.check_end(end) { let _ = self.handle.close_aborted(err.clone()); @@ -2298,10 +2300,14 @@ impl Producer { self.end(Some(end)) } - /// Whether [`Self::finish_at`] takes `end`: [`Error::TimestampMismatch`] at or before the - /// group's start. + /// Whether [`Self::finish_at`] takes `end`: [`Error::TimestampMismatch`] below the + /// group's start or below its highest frame timestamp, in its track's timescale. pub(crate) fn check_end(&self, end: u64) -> Result<()> { - match end <= self.start { + let highest = match self.handle.state.read().timeline { + Timeline::Timed { latest, .. } => latest.value(), + Timeline::Empty | Timeline::Untimed => 0, + }; + match end < self.start.max(highest) { true => Err(Error::TimestampMismatch), false => Ok(()), } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 167e8967bb..1481c3913b 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1315,11 +1315,11 @@ 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) + /// Where a run of starts up to `end` ends with the span the serving copy knows it reaches + /// into; see [`track::Subscriber::span_end`]. + pub(super) fn span_end(&self, end: u64) -> u64 { + let serving = self.reader().copies.last().map(|copy| copy.track.clone()); + serving.map_or(end, |serving| serving.span_end(end)) } /// When the latest group any copy caches at `keys` landed: a group a replaced copy @@ -1329,12 +1329,6 @@ impl Subscriber { copies.iter().filter_map(|track| track.landed(keys.clone())).max() } - /// 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> { @@ -5746,9 +5740,6 @@ mod test { routes.serve(b.consume()); assert_eq!(sub.reader().copies.len(), 2, "the read follows the route to b"); - assert!(sub.holds(5)); - assert!(!sub.holds(2), "only the replaced copy holds 2"); - assert_eq!(sub.previous_start(5), Some(4), "the replaced copy would name 2"); assert_eq!(sub.skipped_below(5), 2, "the replaced copy knows 3 and 4 were skipped"); assert!(sub.is_skipped(std::iter::once(6..=7))); assert!( diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 3525776a07..4e9acabe19 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1792,15 +1792,39 @@ 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), + /// The runs of `keys` outside every whole group's span, where a group may still start: + /// none starts inside one (see [`Self::span_end`]). + fn outside_spans(&self, keys: ops::Range) -> Vec> { + let mut runs = Vec::new(); + let mut at = keys.start; + while at < keys.end { + // A whole group's span may run past the rest of `keys`. + at = self.span_end(at).max(at); + if at >= keys.end { + break; + } + // The next span starts just past the next group held whole. + let next = self + .lookup + .range(at..keys.end) + .find_map(|(key, slot)| slot.group.end().filter(|end| *end > key + 1).map(|_| key + 1)) + .unwrap_or(keys.end); + if at < next { + runs.push(at..next); + } + at = next; + } + runs + } + + /// Where a run of starts up to the exclusive `end` ends once it takes in the rest of the + /// span of the group it reaches into: no other group starts inside a whole group's span, + /// from its start to its end (see [`group::Producer::finish_at`]). `end` itself when the + /// group starting below it is not held whole. + fn span_end(&self, end: u64) -> u64 { + match self.lookup.range(..end).next_back() { + Some((_, slot)) => slot.group.end().map_or(end, |whole| whole.max(end)), + None => end, } } @@ -1809,13 +1833,6 @@ impl TrackState { self.lookup.range(keys).map(|(_, slot)| slot.arrived).max() } - /// 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. @@ -3583,8 +3600,13 @@ impl TrackState { if folds.is_some_and(|folds| now >= folds) { continue; } - if let Some(found) = self.drops.gaps(&gap).find_map(|open| f(open, folds)) { - return Some(found); + let found = self + .drops + .gaps(&gap) + .flat_map(|open| self.outside_spans(open)) + .find_map(|open| f(open, folds)); + if found.is_some() { + return found; } } None @@ -7349,12 +7371,14 @@ 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 { + /// Where a run of starts up to `end` ends with the span it reaches into; see + /// [`Subscriber::span_end`]. + pub(super) fn span_end(&self, end: u64) -> u64 { if let Some(serving) = self.serving() { - return serving.previous_start(start); + return serving.span_end(end); } - self.with_state(|state| state?.read().previous_start(start)) + self.with_state(|state| state.map(|state| state.read().span_end(end))) + .unwrap_or(end) } /// When the latest group cached at `keys` landed; see [`Subscriber::landed`]. @@ -7365,15 +7389,6 @@ impl Consumer { self.with_state(|state| state.and_then(|state| state.read().landed(keys))) } - /// 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 { @@ -9514,7 +9529,7 @@ impl Cursor { /// /// An `ordered` read of the track's own publisher also passes a key below a group that /// publisher created (see [`Self::passes`]). A received copy never does: only what its - /// feed proved, such as a GROUP's Previous Start, accounts for a key there. + /// feed proved, such as a whole group's GROUP_END, accounts for a key there. fn is_exhausted(&self, logical: &[&Delivered], from: u64, ordered: bool) -> bool { let taken: Vec<&Delivered> = std::iter::once(&self.record.delivered) .chain(logical.iter().copied()) @@ -11576,15 +11591,15 @@ 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. + /// Where a run of starts up to the exclusive `end` ends once it takes in the rest of the + /// span of the group it reaches into, the one starting just below `end`, when the cache + /// holds that group whole: no other group starts inside a whole group's span, so the run + /// names those starts with it. `end` itself otherwise. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn previous_start(&self, start: u64) -> Option { + pub(crate) fn span_end(&self, end: u64) -> u64 { match &self.inner { - Inner::Plain(cursor) => cursor.state.read().previous_start(start), - Inner::Resume(resume, _) => resume.previous_start(start), + Inner::Plain(cursor) => cursor.state.read().span_end(end), + Inner::Resume(resume, _) => resume.span_end(end), } } @@ -11597,15 +11612,6 @@ impl Subscriber { } } - /// 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. @@ -13043,6 +13049,21 @@ mod test { Producer::new(Arc::new(broadcast::Info::default()), name, info) } + /// The runs of a range outside every whole group's span: a span that reaches past the + /// range's end leaves nothing of it, rather than a range read backwards. + #[test] + fn outside_spans_stops_at_a_span_past_the_range() { + let producer = Producer::new(Arc::new(broadcast::Info::default()), "test", Info::timed()); + let mut group = producer.create_group(group::Info { start: 10 }).unwrap(); + group + .write_frame(Timestamp::from_millis(10).unwrap(), b"x".as_slice()) + .unwrap(); + group.finish_at(20).unwrap(); + let state = producer.state.read(); + assert_eq!(state.outside_spans(15..16), Vec::>::new()); + assert_eq!(state.outside_spans(0..25), vec![0..11, 20..25]); + } + #[test] fn drop_changes_follow_split_coalesced_and_recreated_runs() { let producer = track_producer("test", Info::default()); diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index d79a99f98c..72d2c2ac01 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -167,6 +167,15 @@ impl Reading { } } + /// Record `groups` as accounted for by this stream, such as the span its GROUP_END closed. + pub fn account(&self, groups: Range, now: Instant) { + if let Some(tail) = &self.tail + && let Ok(mut state) = tail.write() + { + state.account(groups, now); + } + } + /// 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/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 3a605de382..2adaef921a 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -272,15 +272,14 @@ 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. The header names a previous start, -/// which only lite-07 carries, and a frame start, which lite-06 and later carry. +/// a timed track, the payload size, then the payload. The header names a frame start, which +/// lite-06 and later carry. 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: Some((1 << 20) - 3), frame_start: if version.has_frame_bounds() { 200 } else { 0 }, }; header.encode(w, version).unwrap(); diff --git a/rs/moq-net/tests/integration/range_anchors.rs b/rs/moq-net/tests/integration/range_anchors.rs index 43d8eded0b..57273c9686 100644 --- a/rs/moq-net/tests/integration/range_anchors.rs +++ b/rs/moq-net/tests/integration/range_anchors.rs @@ -360,7 +360,7 @@ async fn a_sparse_request_counts_its_relative_start_back_as_the_publisher_did() /// A time end between two groups ends an ordered read once the publisher created a group past /// it: handing that group out would have passed the starts between. Through the publisher's own /// origin that is its own state. A lite-07 copy ends there only on what its wire proves, the -/// starts between skipped, which a GROUP's Previous Start says of an appending publisher. A +/// starts between skipped, which an appending publisher's SUBSCRIBE_SKIP and GROUP_END say. A /// publisher creating groups out of order says nothing, so the copy, and any arrival read of a /// track created that way, waits for a group that may still come. A group created below the /// end after an ordered read ended is late, as for any key the read passed. diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg index 7217a8cc09..bb8d9d25c6 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.cfg @@ -1,7 +1,7 @@ -\* Three groups, each served on at most one Group Stream. With no update to reopen a drop -\* and no second stream of a group, the bounds stay cheap enough for a third group: a skip -\* of 1 can be held back for 2's GROUP, and a run of 1 and 2 for 3's. Pressure lets the -\* publisher's record fold at any point. +\* Three starts, each served on at most one Group Stream. With no update to reopen a drop +\* and no second stream of a group, the bounds stay cheap enough for a third start: group 1 +\* may end at 2, 3, or 4, so its span covers none, one, or both of the starts above it. +\* Pressure lets the publisher's record fold at any point. CONSTANTS Groups = {1, 2, 3} Pressure = TRUE diff --git a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla index ac02ad41c3..f6c0f24f14 100644 --- a/rs/moq-net/verify/subscribe/SubscribeAccounting.tla +++ b/rs/moq-net/verify/subscribe/SubscribeAccounting.tla @@ -5,13 +5,14 @@ (* subscriber's `TrackServe` (rs/moq-net/src/lite/subscriber.rs) with its *) (* `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. 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. *) +(* The draft's promise: for every start in range the publisher sends a *) +(* Group Stream, accounts for it with a GROUP_END, 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 Group Stream whose group expires stale resets with OLD and is named *) (* in a stale drop, whether it never opened, is serving, or already sent *) @@ -21,83 +22,87 @@ (* with TOO_FAR_BEHIND for a group that outranks it, is named in a final *) (* drop. *) (* *) -(* 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 whole group's span runs from its start to its End, and no group *) +(* starts strictly inside it. Its GROUP_END accounts for the starts *) +(* strictly inside the span, which the publisher then records as told, and *) +(* a drop of a group the publisher holds whole names the span. Every skip *) +(* goes out as a SUBSCRIBE_SKIP. The track records a start inside a whole *) +(* group's span skipped (`append_group`, or a copy's GROUP_END), and the *) +(* cursor skips it where nothing told it yet, as when the group's stream *) +(* was dropped before the group finished. *) (* *) (* 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) are free choices, standing in for the cache, the clock, and the *) (* routes. So are when a stream fails, standing in for stream credit, *) -(* expiry, eviction, and preemption, 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 *) +(* expiry, eviction, and preemption, and when a group finishes whole and *) +(* where it ends. 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, frames, 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. *) +(* every start in `Groups`; ranges, fills, frames, and the tail's grace *) +(* are left out. An End is at most one past the highest start, so a span *) +(* may run past the range. GROUP_END takeover is left out. *) (***************************************************************************) EXTENDS Integers, Sequences, FiniteSets CONSTANTS - Groups, \* group sequences in range + Groups, \* starts in range Pressure \* the cache pool may hand the publisher's reader debt, so its record folds +\* The highest End a group may finish at: one past the highest start. +MaxEnd == 1 + CHOOSE m \in Groups : \A x \in Groups : x <= m + +\* The starts strictly inside the span of a group starting at g and ending at e. +Inner(g, e) == {x \in Groups : g < x /\ x < e} + \* 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" or "evicted") \* fin: the FIN went out before any reset, so every byte may arrive first +\* ended: the FIN followed a GROUP_END, accounting for the starts in `inner` \* sub: "none" (no header yet, or lost with a reset, or never sent), "header" \* (filling the copy), "fin", or "reset" -\* passes: the skipped groups its GROUP's Previous Start passes over -NewStream(g, passes) == - [g |-> g, pub |-> "open", fin |-> FALSE, err |-> "", sub |-> "none", passes |-> passes] +NewStream(g) == + [g |-> g, pub |-> "open", fin |-> FALSE, ended |-> FALSE, inner |-> {}, err |-> "", sub |-> "none"] -\* A drop names one group; a skip names a run of them. -DropMsg(g, err) == [type |-> "drop", gs |-> {g}, err |-> err] +\* A drop names a group, with its span once whole; a skip names one start. +DropMsg(gs, err) == [type |-> "drop", gs |-> gs, err |-> err] SkipMsg(gs) == [type |-> "skip", gs |-> gs, err |-> ""] VARIABLES - \* The publisher's track cursor: its verdict on each group. - cur, \* "pending", "handed", "stale", "final", or "skip" + \* The publisher's track cursor: its verdict on each start. + cur, \* "pending", "handed", "stale", "final", "skip", or "inner" (inside a + \* whole group's span) late, \* the cursor handed the group out once more + ends, \* the group's End once it finished whole, else 0 (`finish_at`) \* The publisher's `TrackRun` and its reader's record. - served, \* `Record::told`: sequences served or given up + served, \* `Record::told`: starts served, accounted, or given up dropped, \* the part of `served` named in a drop, never served (`Report::Dropped`) - 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 + outq, \* `GroupOutcomes::dropped`: failed streams not yet named folded, \* the record folded the group into its floor - ndrop, \* history: drops 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 + ndrop, \* history: drops naming the group, not counting the span above it + nskip, \* history: skips naming the start \* The wire. streams, \* every Group Stream opened, in order resp, \* the Subscribe Stream, publisher to subscriber \* The subscriber's `Tail` and copy. - acct, \* the tail's ledger: groups accounted for + acct, \* the tail's ledger: starts accounted for rec, \* the copy's record: "none", "stale", "final", or "skip" cached \* the copy's group: "none", "open", "whole", "aborted", "evicted" -names == <> -pubVars == <> +names == <> +pubVars == <> subVars == <> vars == <> Init == /\ cur = [g \in Groups |-> "pending"] /\ late = [g \in Groups |-> FALSE] + /\ ends = [g \in Groups |-> 0] /\ served = {} /\ dropped = {} /\ outq = <<>> /\ folded = {} - /\ held = [g \in Groups |-> {}] /\ ndrop = [g \in Groups |-> 0] /\ nskip = [g \in Groups |-> 0] - /\ nahead = [g \in Groups |-> 0] /\ streams = <<>> /\ resp = <<>> /\ acct = {} /\ rec = [g \in Groups |-> "none"] @@ -107,23 +112,30 @@ Init == (* Publisher *) ----------------------------------------------------------------------------- -\* 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 +\* The starts a drop of g names: its span once it finished whole, else g alone. +Span(g) == {g} \cup (IF ends[g] = 0 THEN {} ELSE Inner(g, ends[g])) + +\* Count each start of `gs` named once more in `n`. +Named(n, gs) == [x \in Groups |-> IF x \in gs THEN n[x] + 1 ELSE n[x]] -\* `serve`: open a Group Stream for g, which `mark_served` records. Its GROUP passes over -\* the skipped run below it and the one held back for it, which the cache may have forgotten. -Serve(g) == - /\ streams' = Append(streams, NewStream(g, SkippedBelow(g) \cup held[g])) - /\ served' = served \cup {g} - /\ held' = [held EXCEPT ![g] = {}] +\* The group at g finishes whole at End e (`finish_at`). No group starts strictly inside +\* its span: those starts hold no group and none is handed or given up there, though one +\* may already be skipped, as when a later group was appended first. A group closed +\* without a GROUP_END (a FIN alone) never finishes. +Finish(g, e) == + /\ ends[g] = 0 + /\ cur[g] \notin {"skip", "inner"} + /\ \A i \in 1..Len(streams) : streams[i].g = g => ~(streams[i].fin /\ ~streams[i].ended) + /\ \A x \in Inner(g, e) : cur[x] \in {"pending", "skip"} + /\ ends' = [ends EXCEPT ![g] = e] + /\ cur' = [x \in Groups |-> IF x \in Inner(g, e) /\ cur[x] = "pending" THEN "inner" ELSE cur[x]] + /\ UNCHANGED <> \* `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 sequence already -\* served or given up is not served (`Record::told`). `poll_step` names failed streams first. +\* one re-created after its drop. It never hands out a start twice. A start already +\* served or given up is not served (`Record::told`); `serve` opens a Group Stream for +\* the rest, which `mark_served` records. `poll_step` names failed streams first. CursorHand(g) == /\ outq = <<>> /\ g \notin folded @@ -131,66 +143,71 @@ 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 <> - 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]] + THEN UNCHANGED <> + ELSE /\ streams' = Append(streams, NewStream(g)) + /\ served' = served \cup {g} + /\ UNCHANGED <> \* `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`). 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) == +\* an earlier one. A group that finished whole exists, so it is never skipped. +\* `forward_range` sends it only where the record has told nothing, or, for a skip, only a +\* drop (`Report::blocks`). A drop of a group held whole names its span. +CursorGiveUp(g, kind) == /\ outq = <<>> /\ \/ cur[g] = "pending" \/ cur[g] = "stale" /\ kind \in {"evicted", "skip"} \/ cur[g] = "final" /\ kind = "skip" + /\ kind = "skip" => ends[g] = 0 /\ 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) - 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} + gs == IF kind = "skip" THEN {g} ELSE Span(g) + IN /\ served' = served \cup (IF named THEN gs ELSE {g}) /\ dropped' = IF ~named THEN dropped ELSE IF kind = "skip" THEN dropped \ {g} ELSE dropped \cup {g} - /\ 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' = CASE ~named \/ hold -> nskip - [] kind = "skip" -> Named(nskip, run) - [] OTHER -> Named(nskip, held[g]) - /\ UNCHANGED <> - -\* A serving stream FINs after its last frame (`GroupState::Closed`), after a GROUP_END -\* if its group finished. Nothing names the group unless the stream resets later. + /\ resp' = CASE ~named -> resp + [] kind = "skip" -> Append(resp, SkipMsg(gs)) + [] OTHER -> Append(resp, DropMsg(gs, kind)) + /\ ndrop' = IF named /\ kind # "skip" THEN Named(ndrop, {g}) ELSE ndrop + /\ nskip' = IF named /\ kind = "skip" THEN Named(nskip, gs) ELSE nskip + /\ UNCHANGED <> + +\* The cursor reaches a start inside a whole group's span, which the track records +\* skipped (`append_group`, or a copy's GROUP_END), and skips it where nothing told it yet. +CursorHole(x) == + /\ outq = <<>> + /\ cur[x] = "inner" + /\ x \notin served + /\ served' = served \cup {x} + /\ resp' = Append(resp, SkipMsg({x})) + /\ nskip' = Named(nskip, {x}) + /\ UNCHANGED <> + +\* A serving stream FINs after its last frame (`GroupState::Closed`). Once its group +\* finished whole, a GROUP_END goes first, and `buffer_group_end` records the starts +\* strictly inside the span as told. Otherwise the group is closed. Nothing names the +\* group unless the stream resets later. StreamFinAt(i) == /\ streams[i].pub = "open" - /\ streams' = [streams EXCEPT ![i].pub = "fin", ![i].fin = TRUE] - /\ UNCHANGED <> + /\ LET g == streams[i].g + ended == ends[g] # 0 + inner == IF ended THEN Inner(g, ends[g]) ELSE {} + IN /\ streams' = [streams EXCEPT ![i].pub = "fin", ![i].fin = TRUE, + ![i].ended = ended, ![i].inner = inner] + /\ served' = served \cup inner + /\ UNCHANGED <> \* A stream fails and resets. It expires stale ("old", `poll_given_up`): before it opened, \* waiting for stream credit (`give_way`, `shed`), so nothing of it reached the wire; while \* serving; or after its FIN, before the acknowledgement (`GroupState::Closed`). Or it is \* reset while serving, evicted or preempted with TOO_FAR_BEHIND for a group that outranks -\* it, both final ("evicted"). `settle_failed` queues the outcome, with what its GROUP -\* passed over. +\* it, both final ("evicted"). `settle_failed` queues the outcome. StreamFailAt(i, err) == /\ \/ streams[i].pub = "open" \/ streams[i].pub = "fin" /\ err = "old" /\ streams' = [streams EXCEPT ![i].pub = "reset", ![i].err = err] - /\ outq' = Append(outq, <>) - /\ UNCHANGED <> + /\ outq' = Append(outq, <>) + /\ UNCHANGED <> \* The peer acknowledged everything up to the FIN. StreamAckAt(i) == @@ -200,22 +217,20 @@ 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. A skip of what its GROUP -\* passed over goes first, since the GROUP may never have arrived, even where a skip -\* already named it. +\* the group was served, so nothing serves or names it again. A group held whole is named +\* with its span, since the reset can lose its GROUP_END. PubOutcomes == /\ outq # <<>> /\ outq' = Tail(outq) /\ 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 + gs == Span(g) + IN /\ resp' = Append(resp, DropMsg(gs, Head(outq)[2])) + /\ served' = served \cup gs + /\ ndrop' = Named(ndrop, {g}) + /\ UNCHANGED <> + +\* The pool hands the reader debt and its record folds the start into its floor: one 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 @@ -224,40 +239,35 @@ PubFold(g) == /\ \A i \in 1..Len(outq) : outq[i][1] # g /\ folded' = folded \cup {g} /\ dropped' = dropped \ {g} - /\ UNCHANGED <> + /\ UNCHANGED <> ----------------------------------------------------------------------------- (* Subscriber *) ----------------------------------------------------------------------------- -\* 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, and the stream fills the copy, replacing a stale record of it. -\* Its GROUP's Previous Start skips what it passes over, as a SUBSCRIBE_SKIP would. SubHeaderAt(i) == /\ streams[i].sub = "none" /\ streams[i].pub \in {"open", "fin", "reset"} /\ LET g == streams[i].g - passes == streams[i].passes - unstale == [rec EXCEPT ![g] = IF @ = "stale" THEN "none" ELSE @] - IN /\ acct' = acct \cup {g} \cup passes + IN /\ acct' = acct \cup {g} /\ streams' = [streams EXCEPT ![i].sub = "header"] /\ cached' = [cached EXCEPT ![g] = "open"] - /\ rec' = SkipRec(unstale, passes) + /\ rec' = [rec EXCEPT ![g] = IF @ = "stale" THEN "none" ELSE @] /\ UNCHANGED <> \* The stream filling the copy is read to its FIN, the group whole after a GROUP_END or -\* closed without one, which the copy keeps alike ("whole"). A reset sent after the FIN -\* may arrive too late to cut it. +\* closed without one, which the copy keeps alike ("whole"). A GROUP_END accounts for the +\* starts strictly inside the span, which the copy derives from the whole group and +\* records nothing else for. A reset sent after the FIN may arrive too late to cut it. SubFinAt(i) == /\ streams[i].sub = "header" /\ streams[i].fin /\ streams' = [streams EXCEPT ![i].sub = "fin"] + /\ acct' = acct \cup streams[i].inner /\ cached' = [cached EXCEPT ![streams[i].g] = "whole"] - /\ UNCHANGED <> + /\ UNCHANGED <> \* The reset of the stream filling the copy arrives and ends the group's readers with its \* error. The header already accounted for the group, and the drop naming it follows. @@ -274,28 +284,31 @@ Evict(g) == /\ cached' = [cached EXCEPT ![g] = "evicted"] /\ UNCHANGED <> -\* `apply_response` for SUBSCRIBE_DROP: the tail accounts for the group. A stale drop -\* records it in the copy unless the copy holds it (`give_up` keeps an open group), 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. +\* `apply_response` for SUBSCRIBE_DROP: the tail accounts for each start it names. A +\* stale drop records it in the copy unless the copy holds it (`give_up` keeps an open +\* group), 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 drop after a skip of the same +\* start changes nothing. OnDrop(m) == - LET g == CHOOSE g \in m.gs : TRUE - IN /\ acct' = acct \cup {g} - /\ IF m.err = "old" - THEN /\ rec' = IF cached[g] \notin {"open", "whole"} /\ rec[g] # "skip" - THEN [rec EXCEPT ![g] = "stale"] ELSE rec - /\ UNCHANGED cached - ELSE /\ rec' = IF rec[g] = "skip" \/ cached[g] = "whole" THEN rec ELSE [rec EXCEPT ![g] = "final"] - /\ cached' = [cached EXCEPT ![g] = IF @ = "open" THEN "aborted" ELSE @] + /\ acct' = acct \cup m.gs + /\ IF m.err = "old" + THEN /\ rec' = [x \in Groups |-> + IF x \in m.gs /\ cached[x] \notin {"open", "whole"} /\ rec[x] # "skip" + THEN "stale" ELSE rec[x]] + /\ UNCHANGED cached + ELSE /\ rec' = [x \in Groups |-> + IF x \in m.gs /\ rec[x] # "skip" /\ cached[x] # "whole" + THEN "final" ELSE rec[x]] + /\ cached' = [x \in Groups |-> IF x \in m.gs /\ cached[x] = "open" THEN "aborted" ELSE cached[x]] \* `apply_response` for SUBSCRIBE_SKIP: final, overriding any drop, but a group that \* arrived keeps it (`skip_received`). OnSkip(m) == /\ acct' = acct \cup m.gs - /\ rec' = SkipRec(rec, m.gs) + /\ rec' = [x \in Groups |-> IF x \in m.gs /\ cached[x] \notin {"open", "whole"} THEN "skip" ELSE rec[x]] /\ UNCHANGED cached SubRecv == @@ -313,10 +326,11 @@ StreamDone(s) == \/ s.pub = "acked" \/ s.pub = "reset" /\ s.sub \in {"none", "reset", "fin"} -\* Nothing in flight and nothing left for the publisher to do. +\* Nothing in flight and nothing left for the publisher to do: every start has a verdict, +\* and every start inside a whole group's span is told. Quiet == /\ resp = <<>> /\ outq = <<>> - /\ \A g \in Groups : cur[g] # "pending" + /\ \A g \in Groups : cur[g] # "pending" /\ (cur[g] = "inner" => g \in served) /\ \A i \in 1..Len(streams) : StreamDone(streams[i]) \* The end. Any other state where nothing can happen is a deadlock TLC reports. @@ -333,8 +347,10 @@ SubFin == \E i \in 1..Len(streams) : SubFinAt(i) SubReset == \E i \in 1..Len(streams) : SubResetAt(i) Next == + \/ \E g \in Groups, e \in 1..MaxEnd : g < e /\ Finish(g, e) \/ \E g \in Groups : CursorHand(g) - \/ \E g \in Groups, kind \in {"old", "evicted", "skip"}, hold \in BOOLEAN : CursorGiveUp(g, kind, hold) + \/ \E g \in Groups, kind \in {"old", "evicted", "skip"} : CursorGiveUp(g, kind) + \/ \E g \in Groups : CursorHole(g) \/ StreamFin \/ StreamFail \/ StreamAck @@ -353,7 +369,7 @@ Spec == Init /\ [][Next]_vars (* Rules *) ----------------------------------------------------------------------------- -\* Once quiet, the tail accounts for every group: none is waited for until the grace. +\* Once quiet, the tail accounts for every start: none is waited for until the grace. QuietIsSettled == Quiet => acct = Groups \* The publisher opens at most one Group Stream for a group, so the subscriber never reads @@ -361,15 +377,18 @@ QuietIsSettled == Quiet => acct = Groups ServedOnce == \A i, j \in 1..Len(streams) : i # j => streams[i].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. -\* 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. +\* Every name is final: the publisher names a group in at most one drop, and a start in at +\* most one skip, which goes out over a drop of a group it never served and over nothing +\* else. A drop of a whole group names its span too, which may name again a start inside +\* it that was skipped or dropped before the group finished: the subscriber changes +\* nothing for it. No skip names a start that has a Group Stream, and no whole group's +\* span holds one. NamedOnce == - \A g \in Groups : + /\ \A g \in Groups : /\ ndrop[g] <= 1 /\ nskip[g] <= 1 - /\ nahead[g] <= 1 - /\ nskip[g] + nahead[g] > 0 => \A i \in 1..Len(streams) : streams[i].g # g + /\ nskip[g] > 0 => \A i \in 1..Len(streams) : streams[i].g # g + /\ \A g \in Groups : ends[g] # 0 => + \A i \in 1..Len(streams) : streams[i].g \notin Inner(g, ends[g]) ============================================================================= diff --git a/rs/moq-tokio/tests/integration/receive_credit.rs b/rs/moq-tokio/tests/integration/receive_credit.rs index 0d0782872f..806da887f9 100644 --- a/rs/moq-tokio/tests/integration/receive_credit.rs +++ b/rs/moq-tokio/tests/integration/receive_credit.rs @@ -626,8 +626,6 @@ 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); // Frame Start: the stream carries the group from its first frame. varint(&mut header, 0); @@ -636,9 +634,9 @@ fn group_stream(subscribe: u64, sequence: u64, size: usize) -> Vec { varint(&mut bytes, header.len() as u64); bytes.extend_from_slice(&header); // The frame's size plus one, the zigzag timestamp delta, then the payload. The first - // frame's delta is absolute, and it starts its group, so it is the group's key. + // frame's delta counts from the group's start, and it starts its group, so it is 0. varint(&mut bytes, size as u64 + 1); - varint(&mut bytes, sequence * 2); + varint(&mut bytes, 0); bytes.resize(bytes.len() + size, 5); bytes }