From 4331d748b5cd6a92ce326e2ca454f834b489941f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:52:11 -0700 Subject: [PATCH 1/7] feat(net): carry broadcast epochs over moq-transport Adds the MoQ Epoch extension (draft-lcurley-moq-epoch): a SETUP option and an EPOCH parameter on PUBLISH_NAMESPACE, NAMESPACE, SUBSCRIBE, FETCH, and TRACK_STATUS, negotiated on drafts 17-22 in Rust and JS. Paths are unchanged and epochless peers keep their wire. Co-Authored-By: Claude Opus 5.5 --- doc/bin/cli.md | 14 +- doc/bin/gstreamer.md | 2 +- doc/bin/relay/cluster.md | 7 +- doc/bin/relay/config.md | 4 +- doc/concept/moq-lite.md | 18 +- doc/concept/standard.md | 6 +- drafts/draft-lcurley-moq-cluster.md | 10 +- drafts/draft-lcurley-moq-epoch.md | 189 ++++++ js/net/src/connection/accept.ts | 3 +- js/net/src/connection/connect.ts | 3 +- js/net/src/connection/extensions.test.ts | 21 +- js/net/src/connection/extensions.ts | 11 +- js/net/src/connection/handshake.ts | 10 +- js/net/src/ietf/aliases.test.ts | 8 + js/net/src/ietf/aliases.ts | 7 +- js/net/src/ietf/cluster.test.ts | 37 +- js/net/src/ietf/cluster.ts | 29 - js/net/src/ietf/connection.ts | 18 +- js/net/src/ietf/epoch.test.ts | 222 ++++++++ js/net/src/ietf/epoch.ts | 34 ++ js/net/src/ietf/fetch.ts | 14 +- js/net/src/ietf/index.ts | 1 + js/net/src/ietf/parameters.ts | 41 +- js/net/src/ietf/publish_namespace.ts | 103 +++- js/net/src/ietf/publisher.test.ts | 165 +++++- js/net/src/ietf/publisher.ts | 46 +- js/net/src/ietf/subscribe.ts | 14 + js/net/src/ietf/subscribe_namespace.ts | 45 +- js/net/src/ietf/subscriber.test.ts | 133 ++++- js/net/src/ietf/subscriber.ts | 205 ++++--- js/net/src/ietf/track.ts | 19 +- quest/m0/broadcast-epoch/README.md | 2 +- .../m0/broadcast-epoch/catalog-references.md | 2 +- quest/m1/README.md | 1 - quest/m1/claim-answer-epochs.md | 4 +- quest/m1/ietf-epochs.md | 84 --- quest/m1/ietf-takeover.md | 1 - quest/m3/ietf-cluster-peers.md | 1 - rs/moq-net/src/fuzz.rs | 2 + rs/moq-net/src/ietf/adapter.rs | 2 +- rs/moq-net/src/ietf/epoch.rs | 109 ++++ rs/moq-net/src/ietf/fetch.rs | 30 +- rs/moq-net/src/ietf/mod.rs | 1 + rs/moq-net/src/ietf/parameters.rs | 2 + rs/moq-net/src/ietf/peer.rs | 47 +- rs/moq-net/src/ietf/publish_namespace.rs | 141 +++-- rs/moq-net/src/ietf/publisher.rs | 308 ++++++++-- rs/moq-net/src/ietf/session.rs | 31 +- rs/moq-net/src/ietf/subscribe.rs | 20 + rs/moq-net/src/ietf/subscribe_namespace.rs | 192 +++++-- rs/moq-net/src/ietf/subscriber.rs | 538 ++++++++++++------ rs/moq-net/src/ietf/track.rs | 15 +- rs/moq-net/src/ietf/version.rs | 3 + rs/moq-net/src/setup.rs | 6 +- rs/moq-net/src/test_interop.rs | 1 + .../tests/integration/catalog_acquisition.rs | 17 +- rs/moq-net/tests/integration/extensions.rs | 73 +++ rs/moq-net/tests/integration/multi_cdn.rs | 43 +- rs/moq-net/tests/integration/replacement.rs | 20 + rs/moq-net/tests/integration/restart.rs | 4 +- rs/moq-net/tests/integration/route_change.rs | 15 +- 61 files changed, 2485 insertions(+), 669 deletions(-) create mode 100644 drafts/draft-lcurley-moq-epoch.md create mode 100644 js/net/src/ietf/epoch.test.ts create mode 100644 js/net/src/ietf/epoch.ts delete mode 100644 quest/m1/ietf-epochs.md create mode 100644 rs/moq-net/src/ietf/epoch.rs diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 703e4e07b0b..6179091db8e 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -326,12 +326,12 @@ rtsp` one per RTSP session, and `import ts --program all` one per program. A restarted process takes the name at once: viewers see the broadcast restart, and their next subscribe reaches the new run instead of waiting for its group numbers to catch up. Epochs cross a connection only on moq-lite 07, which is -opt-in, and order by the host's clock there, so a host whose clock runs behind -the old run's waits for it to close. Older versions and moq-transport carry no -epoch, so a restart from another session is the newest route at an equal cost, -or a better one. +opt-in, and on moq-transport draft 17 and later, and order by the host's clock +there, so a host whose clock runs behind the old run's waits for it to close. +Other versions carry no epoch, so a restart from another session is the newest +route at an equal cost, or a better one. -On moq-lite 07, two processes that pass the same `--epoch` (a UUIDv7, such as +On a version that carries epochs, two processes that pass the same `--epoch` (a UUIDv7, such as `uuidgen -7` prints) are one publisher: relays fail over between them mid-group, so they must produce identical tracks with aligned groups. Each derives its catalog clock from the epoch's wall time, so fed one stream they @@ -441,8 +441,8 @@ the break. `--linger` also bounds a mid-stream stitch from the replacement announcement through its first catalog snapshot; expiry exits 1. The default `--linger 0s` follows only a replacement whose catalog is already available. Without `--stitch` the export stays on the old publisher while it is -up. Only lite-07 sessions carry epochs, so on the default version every return -is a replacement. An export that fails while the broadcast stays up, such as on +up. Only lite-07 and moq-transport draft 17+ sessions carry epochs, so on the +default version every return is a replacement. An export that fails while the broadcast stays up, such as on a codec TS cannot carry, exits 1 without lingering. Only `ts` can mark a break, so the other formats refuse `--linger`. diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index 036b92980a2..25523181484 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -68,7 +68,7 @@ Each `sink_%u` request pad is one track. Pad properties: `track` names it reports `failed` on an answer redialing can't change, such as a rejected token. Each run from `READY` publishes under a fresh [publisher epoch](/concept/moq-lite#publisher-epochs), so on moq-lite 07 (opt-in) -viewers switch to a restarted pipeline at once instead of stalling on the old +or moq-transport draft 17 and later, viewers switch to a restarted pipeline at once instead of stalling on the old one; reconnects within a run keep it. The first catalog waits for a timed buffer to place the shared wall clock and for every requested pad to negotiate its rendition, including any codec config carried in its first buffers. A linked pad diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index e7c1cf058c0..1e7a95eb933 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -37,9 +37,10 @@ publishes under a new epoch, which replaces the old broadcast instead of resuming it; the RTMP, SRT, and WHIP ingests mint one per connection. Epochs order by creation time, so a reconnect to a different gateway assumes the two gateways' clocks roughly agree. Seamless failover needs a publisher that -announces an epoch and moq-lite 07 on every link the route crosses. A route -without an epoch, including every route on moq-lite 06 and older or -moq-transport, keeps its subscriptions until it goes or a track fails +announces an epoch and, on every link the route crosses, moq-lite 07 or +moq-transport draft 17 or later with the [epoch extension](/draft/moq-epoch). A route +without an epoch, including every route on moq-lite 06 and older or a +moq-transport link without the extension, keeps its subscriptions until it goes or a track fails upstream, and any other route winning it is announced as a restart. Viewers re-request on a restart, and a relay drops its copy of the old instance, including every path beneath a prefix claim when one of them moves to another diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 70d96a50846..302cf75093d 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -37,6 +37,7 @@ allow.uid = [1001] [listen.extensions] # moq-transport SETUP extensions to offer, each on by default. auth = false # Decline MoQ Auth (draft 17+). solicit = false # Decline MoQ Solicit, so peers may announce unasked. +epoch = false # Decline MoQ Epoch, so routes over moq-transport carry no epoch (draft 17+). ``` `timeout` bounds the whole handshake, transport through MoQ SETUP, so a peer @@ -275,7 +276,8 @@ tls.key = "relay.key" goaway.redirect = "same-host" # How far to trust a draining peer's redirect URI. goaway.handover = "10s" # Cap on how long the drained upstream keeps serving. extensions.auth = false # Decline MoQ Auth on outbound moq-transport sessions. -extensions.solicit = false # Decline MoQ Solicit. Both default to on, as in [listen.extensions]. +extensions.solicit = false # Decline MoQ Solicit. +extensions.epoch = false # Decline MoQ Epoch. All default to on, as in [listen.extensions]. ``` A draining upstream may name a replacement URI. `same-host` follows it only diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 4a207f14975..b0b4d5ad671 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -107,10 +107,14 @@ authorization and hidden names work exactly as without one. of the old instance, so a new subscriber never sees its cached groups. The epoch and the restart message travel on moq-lite 07, which is opt-in. -Older moq-lite versions and moq-transport carry neither, so their routes have -no epoch and a restart reaches them as an end then a start of the path. Without -an epoch, any other route winning is a restart, even a reconnect over the same -path, since nothing says it serves the same bytes. +moq-transport carries the epoch from draft 17 when both sides offer the +[epoch extension](/draft/moq-epoch), on by default, and a restart reaches it as +an end then a start of the path. Older moq-lite versions, older moq-transport +drafts, and a side that declines the extension carry no epoch. Without an +epoch, any other route winning is a restart, even a reconnect over the same +path, since nothing says it serves the same bytes. A peer that ignores the end +and start may keep cached objects of the old run under the same names, so an +end and a start is not a cache flush. `moq` and `moqsink` mint a fresh epoch per run, kept across reconnects, and the RTMP, SRT, and WHIP ingests mint one per connection. Replicas share one by @@ -127,9 +131,9 @@ compared. A subscription uses the preferred link that has a route and moves to t next when that route goes; a publisher pushes the same broadcast to every CDN. The move resumes without a seam only between routes with the same epoch, which -needs moq-lite 07 on both links. A CDN speaking moq-transport carries no epoch, so -moving onto it, or back off it, is a restart and the player requests the path -again. +needs moq-lite 07, or moq-transport draft 17 or later with the epoch extension, +on both links. A CDN link that carries no epoch makes moving onto it, or back +off it, a restart, and the player requests the path again. ### Hidden broadcasts diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 8e926905673..726be1642e3 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -42,11 +42,13 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, [hidden](/draft/moq-hidden) to keep `.`-named namespaces out of discovery, [auth](/draft/moq-auth) to tell each peer what it may publish and subscribe to, [active-count](/draft/moq-active-count) to count the `NAMESPACE` messages -before a `SUBSCRIBE_NAMESPACE` is synced, and +before a `SUBSCRIBE_NAMESPACE` is synced, +[epoch](/draft/moq-epoch) to carry [publisher epochs](/concept/moq-lite#publisher-epochs) +without changing a path, and [probe](/draft/moq-probe) for bandwidth estimation. Rust sessions request PROBE only while an owned `recv_bandwidth()` consumer is held. Read estimates through its `peek()` or `changed()` methods; session statistics do not request PROBE. -Both libraries offer solicit and auth (draft 17 and later) unless a side's +Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side's `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 91f1b13ed23..abbca0f4593 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -144,8 +144,9 @@ NAMESPACE Message (Cluster) { ~~~ The added fields are encoded exactly as in PUBLISH_NAMESPACE. -Negotiating this extension enables the block on every NAMESPACE, with a parameter count of 0 when it is empty; when another extension defines the same block an endpoint appends one block holding the parameters of both, not two blocks. -An endpoint MUST NOT append the block when nothing negotiated it, and MUST NOT include HOP_PATH or ROUTE_COST unless this extension is. +Other extensions, such as MoQ Epoch (draft-lcurley-moq-epoch), carry their NAMESPACE parameters in the same block. +A session appends exactly one block to every NAMESPACE when it negotiated any extension that uses the block, holding the parameters of all of them in any order, with a count of 0 when none applies; it appends none when it negotiated none. +An endpoint MUST NOT include HOP_PATH or ROUTE_COST unless this extension is negotiated. NAMESPACE_DONE ({{moqt}} Section 10.17) carries no state from this extension. @@ -226,6 +227,7 @@ An advertisement lives as long as its stream, so an update on a new stream would An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived, even when the first HOP_PATH entry changed: the namespace still names the same content ({{publishers}}). +An update never changes an advertisement's instance; under MoQ Epoch another instance is a new advertisement. The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. @@ -261,6 +263,9 @@ Under this extension an advertisement is a path, so a session advertises a names A namespace names one broadcast whichever publisher serves it, so several publishers of it are redundant copies: their groups are one sequence, and a subscription moves between them without a gap. A publisher MUST NOT reuse a namespace for different content, and publishes a new instance under a new namespace instead. + +A session that negotiated MoQ Epoch names the instance instead: the namespace and EPOCH together name the content, so only advertisements with the same EPOCH are redundant copies, and a publisher MAY reuse the namespace for a new instance under a new EPOCH. +A receiver MUST NOT move a subscription between advertisements with different EPOCHs, or between advertisements without one. A refusal never moves to another publisher ({{selection}}). A relay that moves to another publisher MUST update its advertisement to the new path ({{updating}}). @@ -311,6 +316,7 @@ The Key-Value-Pair parity is load-bearing: HOP_PATH is odd, so its value is a le # Appendix A: Changelog ## moq-cluster-02 +- Exactly one NAMESPACE parameter block is appended when any extension that uses it is negotiated, holding the parameters of all of them. Under MoQ Epoch, only advertisements with the same EPOCH are redundant copies, and an update never changes the instance. - A namespace names one broadcast whichever publisher serves it, and a publisher MUST NOT reuse one for different content. A receiver MAY fail a subscription over between any of its advertisements, continuing from the first object the subscriber lacks instead of at a group boundary. Replaces the first-Hop-ID publisher identity. - Defined request resolution against the longest covering prefix; every refusal is terminal, including between several publishers of one namespace, and capacity is signaled only by withdrawing or re-pricing the advertisement. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. diff --git a/drafts/draft-lcurley-moq-epoch.md b/drafts/draft-lcurley-moq-epoch.md new file mode 100644 index 00000000000..f996c594996 --- /dev/null +++ b/drafts/draft-lcurley-moq-epoch.md @@ -0,0 +1,189 @@ +--- +title: "MoQ Epoch Extension" +abbrev: "moq-epoch" +category: info + +docname: draft-lcurley-moq-epoch-latest +submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" +number: +date: +v: 3 +area: wit +workgroup: moq + +author: + - + fullname: Luke Curley + email: kixelated@gmail.com + +normative: + moqt: I-D.ietf-moq-transport + cluster: I-D.lcurley-moq-cluster + RFC9562: + +informative: + moql: I-D.lcurley-moq-lite + +--- abstract + +This document defines an extension for MoQ Transport {{moqt}} that names the publisher instance behind a namespace. +Peers that negotiate it carry an EPOCH, a UUIDv7 the publisher mints when it starts, on namespace advertisements and on the requests that resolve through them. +A relay can then move a subscription between redundant paths of one instance, and refuse to serve a request from a replacement instance that reused the same names. + +--- note_Note_to_Readers + +This document was generated by an AI model from the implementation at [github.com/moq-dev/moq](https://github.com/moq-dev/moq) and is maintained alongside it. +Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.com/moq-dev/moq/pulls) if this spec sucks and you want to fix anything. + +--- middle + +# Conventions and Definitions +{::boilerplate bcp14-tagged} + +An endpoint **advertises** a namespace by sending PUBLISH_NAMESPACE, or NAMESPACE in response to a SUBSCRIBE_NAMESPACE. + +An **instance** is one run of a publisher of a namespace: the content it produces between starting and stopping. +A namespace and an EPOCH name one instance. + + +# Introduction +{{moqt}} names an object by its namespace, track, group, and object ID, and those names say nothing about which run of a publisher produced it. +A publisher that restarts and counts its groups from zero again reuses names for different content, and a relay holding both runs cannot tell them apart. +A relay with several paths to one namespace also cannot tell whether they serve the same bytes, so it cannot move a subscription between them without risking a gap or a mix of two runs. + +This extension carries the instance identity that {{moql}} carries in its Epoch field, without changing any name. +The namespace a subscriber asks for is the same with or without it. + + +# Setup Negotiation + +An endpoint offers this extension with the following Setup Option ({{moqt}} Section 10.3): + +~~~ +EPOCH Setup Option { + Option Key (vi64) = 0x40B68 + Option Value (vi64) = 1 +} +~~~ + +A receiver MUST ignore the value. +The extension is negotiated when both endpoints sent the option. +It relies on Setup Options and Key-Value-Pair parameters, so an endpoint MUST NOT send the option, and MUST ignore it, on a version of {{moqt}} earlier than draft-17. + +An endpoint MUST NOT send the EPOCH parameter ({{parameter}}) on a session that did not negotiate this extension. +A receiver treats one received on such a session as any unknown parameter, which closes the session. + + +# EPOCH Parameter {#parameter} + +~~~ +EPOCH Parameter { + Type (vi64) = 0x40B69, + Length (vi64) = 16, + Epoch (128), +} +~~~ + +**Epoch**: +A UUIDv7 ({{RFC9562}} Section 5.7) in network byte order. +A receiver MUST close the session with a PROTOCOL_VIOLATION when the value is not exactly 16 bytes, or not a UUID with version 7 and the variant of {{RFC9562}}. + +EPOCH may appear in PUBLISH_NAMESPACE, NAMESPACE, SUBSCRIBE, TRACK_STATUS, and a FETCH that names its track (a Standalone FETCH, or one with a filter). +NAMESPACE carries it in the parameter block defined by {{cluster}}, which a session that negotiated this extension appends to every NAMESPACE; when both extensions are negotiated the one block holds the parameters of both. +A receiver MUST close the session with a PROTOCOL_VIOLATION on an EPOCH in a joining FETCH, which is served by the subscription it joins, or in REQUEST_UPDATE. + +Epochs compare as their 16 bytes, which for a UUIDv7 orders them by creation time. + + +# Identity {#identity} + +A publisher mints a new Epoch each time it starts an instance, and MUST NOT serve different content under one namespace and Epoch. +Publishers serving identical content, such as replicas of one encoder, MAY share an Epoch. + +Two advertisements of a namespace with the same EPOCH serve the same instance: a receiver MAY move a subscription between them, continuing from the first object the subscriber lacks. +A receiver MUST NOT move a subscription between advertisements with different EPOCHs, or between advertisements without one: it stays on its path and ends with it. +An advertisement without EPOCH names no instance, so nothing says another advertisement serves the same bytes. + + +# Advertising {#advertising} + +A publisher includes the EPOCH of the instance it serves in each advertisement to a peer that negotiated this extension. +A relay forwards the EPOCH it received unchanged, and MUST NOT include one for an advertisement that arrived without one. + +An advertisement's EPOCH is fixed for as long as it stands. +An endpoint replacing the instance behind an advertisement withdraws it (PUBLISH_NAMESPACE_DONE, cancelling the PUBLISH_NAMESPACE, or NAMESPACE_DONE) and advertises again with the new EPOCH. +A receiver MUST close the session with a PROTOCOL_VIOLATION on a NAMESPACE that repeats a live suffix with a different EPOCH, or adds or drops one, without a NAMESPACE_DONE between them. + +A withdrawal and the advertisement replacing it can travel on different streams and arrive in either order. +A receiver holding several live advertisements of one namespace from a peer treats the one received last as current, so the late withdrawal or update of an older one does not restore the instance it named. + +When several instances of a namespace are advertised, a receiver SHOULD resolve new requests to the newest EPOCH, ranking an advertisement without one last, before any other selection rule such as those of {{cluster}}. + + +# Requests {#requests} + +A subscriber includes in SUBSCRIBE, FETCH, and TRACK_STATUS the EPOCH of the advertisement it resolved the request through, when that advertisement carried one. +A request without EPOCH resolves as in {{moqt}}. + +A publisher MUST serve a request that carries EPOCH only from that instance. +When the namespace now resolves to another instance, or to an advertisement without EPOCH, it MUST refuse the request with the error it sends for a namespace that does not exist, rather than serve another instance's objects. +A relay forwarding the request upstream includes the EPOCH of the path it chose, which is the same instance. + + +# Caching {#caching} + +A relay keeps the objects of different instances apart. +It MUST NOT answer a request for one instance with an object cached from another, nor with one cached from an advertisement without EPOCH unless the request resolved through that same advertisement. +The same separation applies to a joining FETCH, to subscriptions to an old and a new instance held at once, and to the track aliases and responses of each. + + +# Peers Without This Extension {#downgrade} + +A relay serves a peer that did not negotiate this extension with the names that peer already uses. +It replaces an instance it advertised to such a peer by withdrawing the advertisement and sending a new one, keeps that peer's established subscriptions on the instance they started on until it ends, and resolves new requests to the current instance. +A relay MAY hide a move between advertisements of the same instance from such a peer. + +This is how a relay behaves, not a cache invalidation mechanism. +{{moqt}} identifies an object by its namespace, track, group, and object ID, and a withdrawal does not invalidate that identity. +A relay or client without this extension that keeps objects across a withdrawal can serve one instance's objects for another's names, so a publisher that needs reused names to be safe through such endpoints MUST NOT reuse them. + + +# Security Considerations + +An EPOCH is not authentication. +Any publisher authorized for a namespace can claim any EPOCH, including one another publisher minted, and so splice its objects into subscriptions to that instance. +A relay MUST authorize advertisements and requests by namespace exactly as it would without this extension. + +A UUIDv7 reveals when its instance started, to millisecond precision. + + +# IANA Considerations + +This document requests the following registrations. +High, distinctive values are requested to avoid the low ranges reserved by {{moqt}} and to minimize collisions with provisional registrations by other extensions. + +## MOQT Setup Options + +This document requests one registration in the "MOQT Setup Options" registry ({{moqt}} Section 15.4), whose policy is Specification Required. + +| Value | Name | Reference | +|:--------|:------|:--------------| +| 0x40B68 | EPOCH | This Document | + +## MOQT Message Parameters + +This document requests one registration in the "MOQT Message Parameters" registry ({{moqt}} Section 15.7). + +| Value | Name | Carried In | Reference | +|:--------|:------|:---------------------------------------------------------|:--------------| +| 0x40B69 | EPOCH | PUBLISH_NAMESPACE, NAMESPACE, SUBSCRIBE, FETCH, TRACK_STATUS | This Document | + +The Setup Option is even, so its value is a bare varint; the parameter is odd, so its value is a length-prefixed byte string. + + +--- back + +# Acknowledgments +{:numbered="false"} + +This document was drafted with the assistance of Claude, an AI assistant by Anthropic. diff --git a/js/net/src/connection/accept.ts b/js/net/src/connection/accept.ts index 4b2edaa8300..eb9fe2240e4 100644 --- a/js/net/src/connection/accept.ts +++ b/js/net/src/connection/accept.ts @@ -118,7 +118,7 @@ async function acceptAlpn( version: Ietf.IetfVersion, wiring: SessionProps, ): Promise { - const { control, early, solicit, hidden, activeCount, cluster, auth } = await exchangeSetup( + const { control, early, solicit, hidden, activeCount, cluster, auth, epoch } = await exchangeSetup( transport, version, "moq-lite-js", @@ -137,6 +137,7 @@ async function acceptAlpn( activeCount, cluster, auth, + epoch, // v17+ uses NativeSession which manages its own request IDs; maxRequestId is unused. maxRequestId: 0n, version, diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 5a73415146b..f4bd24e71c7 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -370,7 +370,7 @@ async function handshakeAlpn( version: Ietf.IetfVersion, wiring: SessionProps, ): Promise { - const { control, early, solicit, hidden, activeCount, cluster, auth } = await exchangeSetup( + const { control, early, solicit, hidden, activeCount, cluster, auth, epoch } = await exchangeSetup( session, version, "moq-lite-js", @@ -389,6 +389,7 @@ async function handshakeAlpn( activeCount, cluster, auth, + epoch, // v17+ uses NativeSession which manages its own request IDs; maxRequestId is unused. maxRequestId: 0n, version, diff --git a/js/net/src/connection/extensions.test.ts b/js/net/src/connection/extensions.test.ts index 25194b13dc1..84897c4aac1 100644 --- a/js/net/src/connection/extensions.test.ts +++ b/js/net/src/connection/extensions.test.ts @@ -35,8 +35,8 @@ async function acceptWith(extensions: Extensions) { } test("every extension is offered by default", () => { - expect(offered()).toEqual({ auth: true, solicit: true }); - expect(offered({ solicit: false })).toEqual({ auth: true, solicit: false }); + expect(offered()).toEqual({ auth: true, solicit: true, epoch: true }); + expect(offered({ solicit: false })).toEqual({ auth: true, solicit: false, epoch: true }); }); test("a declined extension stays out of SETUP", async () => { @@ -54,6 +54,21 @@ test("a declined extension stays out of SETUP", async () => { expect(none.dialed.solicit).toBe(true); }); +test("MoQ Epoch is negotiated only when both sides offer it", async () => { + const all = await handshake({}, {}); + expect(all.dialed.epoch).toBe(true); + expect(all.accepted.epoch).toBe(true); + + for (const [client, server] of [ + [{ epoch: false }, {}], + [{}, { epoch: false }], + ]) { + const declined = await handshake(client, server); + expect(declined.dialed.epoch).toBe(false); + expect(declined.accepted.epoch).toBe(false); + } +}); + test("an AUTH to a side that declined it closes the session", async () => { // Control: offered by both, the connection credential is granted. const offering = await acceptWith({}); @@ -82,7 +97,7 @@ test("a side that declined solicit takes an unsolicited announce", async () => { await new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("room"), - cluster: { hops: [session.peer.cluster.self], cost: 0n }, + params: { cluster: { hops: [session.peer.cluster.self], cost: 0n } }, }).encode(stream.writer, VERSION); return stream; }; diff --git a/js/net/src/connection/extensions.ts b/js/net/src/connection/extensions.ts index e029f37b473..f53e2fc1504 100644 --- a/js/net/src/connection/extensions.ts +++ b/js/net/src/connection/extensions.ts @@ -2,7 +2,7 @@ import * as Ietf from "../ietf/index.ts"; /** * The moq-transport extensions a session offers in its SETUP, each on unless set to `false`. - * Turning one off connects as a peer that does not speak it. moq-lite carries both in its + * Turning one off connects as a peer that does not speak it. moq-lite carries them in its * core, so this only changes moq-transport sessions. */ export interface Extensions { @@ -10,6 +10,8 @@ export interface Extensions { auth?: boolean; /** The MoQ Solicit extension: the peer answers our SUBSCRIBE_NAMESPACE rather than announcing unasked. */ solicit?: boolean; + /** The MoQ Epoch extension: announcements and requests carry the publisher's epoch, as moq-lite does (draft-17+). */ + epoch?: boolean; } /** Every extension resolved to whether it is offered. */ @@ -17,11 +19,16 @@ export type Offered = Required; /** Resolve each unset extension to offered. */ export function offered(extensions?: Extensions): Offered { - return { auth: extensions?.auth ?? true, solicit: extensions?.solicit ?? true }; + return { + auth: extensions?.auth ?? true, + solicit: extensions?.solicit ?? true, + epoch: extensions?.epoch ?? true, + }; } /** Write the options for the offered extensions into a SETUP. */ export function intoSetup(params: Ietf.SetupOptions, extensions: Offered, version: Ietf.IetfVersion) { if (extensions.solicit) Ietf.solicitIntoSetup(params); if (extensions.auth) Ietf.Auth.intoSetup(params, version); + if (extensions.epoch) Ietf.Epoch.intoSetup(params, version); } diff --git a/js/net/src/connection/handshake.ts b/js/net/src/connection/handshake.ts index 218ee518e45..08a1f6628b8 100644 --- a/js/net/src/connection/handshake.ts +++ b/js/net/src/connection/handshake.ts @@ -13,9 +13,9 @@ import * as Extensions from "./extensions.ts"; * Returns the control stream, the uni streams that arrived before it (see * {@link receiveSetup}), plus what the peer's SETUP declared: whether it requires * solicitation, which decides whether we announce namespaces unprompted (see the MoQ Solicit - * extension), its Hop ID (see the MoQ Cluster extension), and whether MoQ Auth is negotiated. - * We declare our Hop ID on every session, and Solicit and Auth unless `extensions` declines - * them: we send SUBSCRIBE_NAMESPACE for each prefix we want, so an unsolicited advertisement + * extension), its Hop ID (see the MoQ Cluster extension), and whether MoQ Auth and MoQ Epoch + * are negotiated. We declare our Hop ID on every session, and Solicit, Auth, and Epoch unless + * `extensions` declines them: we send SUBSCRIBE_NAMESPACE for each prefix we want, so an unsolicited advertisement * can tell us nothing we won't have asked for, and a peer that knows our Hop ID can withhold * the advertisements that already flowed through us. */ @@ -32,6 +32,7 @@ export async function exchangeSetup( activeCount: boolean; cluster: Ietf.Cluster.Hops; auth: boolean; + epoch: boolean; }> { const encoder = new TextEncoder(); const params = new Ietf.SetupOptions(); @@ -70,6 +71,7 @@ export async function exchangeSetup( cluster: { self, peer: received.cluster }, // Negotiated only when both sides offer it. auth: received.auth && extensions.auth, + epoch: received.epoch && extensions.epoch, }; } @@ -100,6 +102,7 @@ async function receiveSetup( activeCount: boolean; cluster: Hop | undefined; auth: boolean; + epoch: boolean; }> { const uniReader = transport.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream @@ -154,5 +157,6 @@ async function receiveSetup( activeCount: Ietf.activeCountFromSetup(setup.parameters, version), cluster: Ietf.Cluster.fromSetup(setup.parameters, version), auth: Ietf.Auth.fromSetup(setup.parameters, version) === true, + epoch: Ietf.Epoch.fromSetup(setup.parameters, version), }; } diff --git a/js/net/src/ietf/aliases.test.ts b/js/net/src/ietf/aliases.test.ts index 54d70fc2fe7..783af4a9f4b 100644 --- a/js/net/src/ietf/aliases.test.ts +++ b/js/net/src/ietf/aliases.test.ts @@ -48,6 +48,14 @@ test("sharing an alias across subscriptions to one track is not fatal", () => { expect(() => aliases.set(7n, {}, { broadcast: "cam", name: "video" })).toThrow(SharedTrackAlias); }); +// Another publisher instance is other content under the same name (MoQ Epoch). +test("one alias for two epochs of a track is a collision", () => { + const aliases = new TrackAliases(); + aliases.set(7n, {}, { broadcast: "cam", name: "video", epoch: "a" }); + + expect(() => aliases.set(7n, {}, { broadcast: "cam", name: "video", epoch: "b" })).toThrow(DuplicateTrackAlias); +}); + // Metadata keyed by an alias (the track's timescale) must only be torn down by whoever // still owns the binding, so retirement reports ownership rather than returning void. test("retire reports whether the caller still owned the alias", () => { diff --git a/js/net/src/ietf/aliases.ts b/js/net/src/ietf/aliases.ts index 5e4eba90039..3a2b55389ba 100644 --- a/js/net/src/ietf/aliases.ts +++ b/js/net/src/ietf/aliases.ts @@ -22,13 +22,14 @@ type Resolver = PromiseWithResolvers["resolve"]; * * Kept as two components rather than one joined string: a track name may contain the same * separator a broadcast path uses, so `a` + `b/c` and `a/b` + `c` would otherwise compare - * equal and turn a genuine collision into apparent sharing. + * equal and turn a genuine collision into apparent sharing. The publisher instance a + * subscription names (MoQ Epoch) is part of it: another instance is other content. * @internal */ -export type TrackIdentity = { broadcast: string; name: string }; +export type TrackIdentity = { broadcast: string; name: string; epoch?: string }; function sameTrack(a: TrackIdentity, b: TrackIdentity): boolean { - return a.broadcast === b.broadcast && a.name === b.name; + return a.broadcast === b.broadcast && a.name === b.name && a.epoch === b.epoch; } /** diff --git a/js/net/src/ietf/cluster.test.ts b/js/net/src/ietf/cluster.test.ts index 80cf431fa15..4e57148b180 100644 --- a/js/net/src/ietf/cluster.test.ts +++ b/js/net/src/ietf/cluster.test.ts @@ -14,6 +14,9 @@ import { type IetfVersion, Version } from "./version.ts"; const VERSION = Version.DRAFT_19; +/** A session that negotiated MoQ Cluster alone. */ +const CLUSTER = { cluster: true, epoch: false }; + function origin(id: bigint): Hop { return HopSchema.parse(id); } @@ -215,21 +218,27 @@ test("Cluster: a loop is detected by any non-zero id", () => { test("Cluster: PUBLISH_NAMESPACE carries the parameters only once negotiated", async () => { const advert = { hops: hops(7n, 9n), cost: 5n }; - const msg = new PublishNamespace({ requestId: 1n, trackNamespace: Path.from("alice.hang"), cluster: advert }); + const msg = new PublishNamespace({ + requestId: 1n, + trackNamespace: Path.from("alice.hang"), + params: { cluster: advert }, + }); const encoded = await encode(msg); - const decoded = await PublishNamespace.decode(reader(encoded), VERSION, true); + const decoded = await PublishNamespace.decode(reader(encoded), VERSION, CLUSTER); expect(decoded.trackNamespace).toBe(Path.from("alice.hang")); - expect(decoded.cluster).toEqual(advert); + expect(decoded.params.cluster).toEqual(advert); // The message always has a Parameters field, so a session that negotiated nothing // reads the same bytes and ignores what it did not ask for. - expect((await PublishNamespace.decode(reader(encoded), VERSION)).cluster).toBeUndefined(); + expect((await PublishNamespace.decode(reader(encoded), VERSION)).params.cluster).toBeUndefined(); // A negotiated session that omits HOP_PATH is a protocol violation, which the session // dispatch closes over rather than losing only the stream. const bare = new PublishNamespace({ requestId: 1n, trackNamespace: Path.from("alice.hang") }); - await expect(PublishNamespace.decode(reader(await encode(bare)), VERSION, true)).rejects.toThrow(ProtocolViolation); + await expect(PublishNamespace.decode(reader(await encode(bare)), VERSION, CLUSTER)).rejects.toThrow( + ProtocolViolation, + ); }); test("Cluster: a negotiated PUBLISH_NAMESPACE may carry AUTHORIZATION_TOKEN", async () => { @@ -248,8 +257,8 @@ test("Cluster: a negotiated PUBLISH_NAMESPACE may carry AUTHORIZATION_TOKEN", as }, }; - const decoded = await PublishNamespace.decode(reader(await encode(withToken)), VERSION, true); - expect(decoded.cluster).toEqual(advert); + const decoded = await PublishNamespace.decode(reader(await encode(withToken)), VERSION, CLUSTER); + expect(decoded.params.cluster).toEqual(advert); }); test("Cluster: a repeated AUTHORIZATION_TOKEN refuses only the advertisement", async () => { @@ -258,7 +267,7 @@ test("Cluster: a repeated AUTHORIZATION_TOKEN refuses only the advertisement", a const frame = (body: number[]) => new Uint8Array([0, body.length, ...body]); // Request ID 1 for namespace "a". The repeat is refused before the missing HOP_PATH is. - const advert = PublishNamespace.decode(reader(frame([1, 1, 1, 0x61, ...tokens])), VERSION, true); + const advert = PublishNamespace.decode(reader(frame([1, 1, 1, 0x61, ...tokens])), VERSION, CLUSTER); await expect(advert).rejects.toThrow(MalformedAuthToken); await expect(advert).rejects.toMatchObject({ requestId: 1n }); @@ -341,17 +350,19 @@ test("Cluster: a transport ending while decoding an update stays transport-local test("Cluster: NAMESPACE grows a parameters field only once negotiated", async () => { const advert = { hops: hops(7n), cost: 0n }; - const extended = await encode(new SubscribeNamespaceEntry({ suffix: Path.from("alice.hang"), cluster: advert })); + const extended = await encode( + new SubscribeNamespaceEntry({ suffix: Path.from("alice.hang"), params: { cluster: advert } }), + ); const base = await encode(new SubscribeNamespaceEntry({ suffix: Path.from("alice.hang") })); // The base form has no Parameters field at all, so it is strictly shorter. expect(base.length).toBeLessThan(extended.length); - const decoded = await SubscribeNamespaceEntry.decode(reader(extended), VERSION, true); + const decoded = await SubscribeNamespaceEntry.decode(reader(extended), VERSION, CLUSTER); expect(decoded.suffix).toBe(Path.from("alice.hang")); - expect(decoded.cluster).toEqual(advert); + expect(decoded.params?.cluster).toEqual(advert); - expect((await SubscribeNamespaceEntry.decode(reader(base), VERSION)).cluster).toBeUndefined(); + expect((await SubscribeNamespaceEntry.decode(reader(base), VERSION)).params).toBeUndefined(); // Reading the extended form as the base one leaves the parameters behind rather than // silently absorbing them. @@ -359,5 +370,5 @@ test("Cluster: NAMESPACE grows a parameters field only once negotiated", async ( // The base form on a negotiated session ends before the parameters the peer owed us, // which is the same violation as sending them without a HOP_PATH. - await expect(SubscribeNamespaceEntry.decode(reader(base), VERSION, true)).rejects.toThrow(ProtocolViolation); + await expect(SubscribeNamespaceEntry.decode(reader(base), VERSION, CLUSTER)).rejects.toThrow(ProtocolViolation); }); diff --git a/js/net/src/ietf/cluster.ts b/js/net/src/ietf/cluster.ts index 3d9e400a269..092264f3c87 100644 --- a/js/net/src/ietf/cluster.ts +++ b/js/net/src/ietf/cluster.ts @@ -26,10 +26,8 @@ import { ProtocolViolation, reason } from "../error.ts"; import { type Hop, HopSchema, MAX_HOPS, UNKNOWN_HOP } from "../hop.ts"; -import type { Reader } from "../stream.ts"; import * as Varint from "../varint.ts"; import { Parameters, SetupOption, type SetupOptions } from "./parameters.ts"; -import { MalformedAuthToken } from "./token.ts"; import { type IetfVersion, Version } from "./version.ts"; /** @@ -204,33 +202,6 @@ function encodeHops(hops: Hop[]): Uint8Array { return value; } -/** - * Read the parameters a negotiated session puts on every advertisement, checked against - * the list of the message that carries them (PUBLISH_NAMESPACE also allows a token). - * - * The parameter block is mandatory there, so a message that ends before it (the base form) - * or one whose block does not parse is the peer's violation, same as a block that parses but - * carries no HOP_PATH. - * - * @internal - */ -export async function decodeParams( - r: Reader, - version: IetfVersion, - message: "namespace" | "publish-namespace", -): Promise { - let params: Parameters; - try { - params = await Parameters.decode(r, version, message); - } catch (err) { - // Keep a violation's own code, such as a request token's, and a refusal of the request alone. - if (err instanceof ProtocolViolation || err instanceof MalformedAuthToken) throw err; - throw new ProtocolViolation(reason(err), { cause: err }); - } - - return fromParams(params); -} - /** * Read an advertisement out of a decoded parameter block. * diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index 27efad21c18..fe4a73dc4d9 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -94,6 +94,9 @@ export class Connection implements Established { // The Hop IDs this session declared; see {@link Cluster}. #cluster?: Cluster.Hops; + // Whether both SETUPs offered MoQ Epoch, so advertisements and requests may carry EPOCH. + #epoch: boolean; + // The peer's GOAWAY: read here on v17+, by the control stream adapter before that. #goaway: Once; @@ -126,6 +129,7 @@ export class Connection implements Established { activeCount = false, cluster, auth = false, + epoch = false, early = [], requestWindow, extensions, @@ -155,6 +159,8 @@ export class Connection implements Established { cluster?: Cluster.Hops; /** Whether MoQ Auth is negotiated (draft-17+): offered by both SETUPs. */ auth?: boolean; + /** Whether MoQ Epoch is negotiated (draft-17+): offered by both SETUPs. */ + epoch?: boolean; /** Uni streams that arrived before the peer's SETUP, type unread (v17+). */ early?: Reader[]; /** Requests the peer may hold open on drafts 14 to 16, the window our SETUP advertised (default `REQUEST_WINDOW`). */ @@ -215,6 +221,7 @@ export class Connection implements Established { hidden, activeCount, cluster, + epoch, grant: this.#auth.grant, auth: this.#auth, ready: this.#auth.setupAnswered(), @@ -222,10 +229,12 @@ export class Connection implements Established { this.#solicit = solicit; this.#declaredSolicit = extensions?.solicit ?? true; this.#cluster = cluster; + this.#epoch = epoch; this.#subscriber = new Subscriber({ session: this.#session, quic, cluster, + epoch, hidden, activeCount, solicit, @@ -441,11 +450,10 @@ export class Connection implements Established { // Subscriber handles incoming notifications case BigInt(PublishNamespace.id): { - const decoded = PublishNamespace.decode( - stream.reader, - this.#session.version, - Cluster.negotiated(this.#cluster), - ); + const decoded = PublishNamespace.decode(stream.reader, this.#session.version, { + cluster: Cluster.negotiated(this.#cluster), + epoch: this.#epoch, + }); const msg = await this.#request(stream, "publish_namespace", decoded); if (!msg) break; diff --git a/js/net/src/ietf/epoch.test.ts b/js/net/src/ietf/epoch.test.ts new file mode 100644 index 00000000000..9af26ceff0d --- /dev/null +++ b/js/net/src/ietf/epoch.test.ts @@ -0,0 +1,222 @@ +import { expect, test } from "bun:test"; +import * as Epoch from "../epoch.ts"; +import { ProtocolViolation } from "../error.ts"; +import { HopSchema } from "../hop.ts"; +import * as Path from "../path.ts"; +import { Reader, Writer } from "../stream.ts"; +import type * as Cluster from "./cluster.ts"; +import * as EpochExt from "./epoch.ts"; +import { Fetch } from "./fetch.ts"; +import * as Message from "./message.ts"; +import { Parameters, SetupOption, SetupOptions } from "./parameters.ts"; +import { type AdvertParams, PublishNamespace } from "./publish_namespace.ts"; +import { Subscribe } from "./subscribe.ts"; +import { SubscribeNamespaceEntry } from "./subscribe_namespace.ts"; +import { TrackStatusRequest } from "./track.ts"; +import { type IetfVersion, Version } from "./version.ts"; + +const VERSION = Version.DRAFT_19; +const EPOCH_PARAM = 0x40b69n; +const EPOCH = Epoch.mint(); + +const LEGACY = [Version.DRAFT_14, Version.DRAFT_15, Version.DRAFT_16] as const; +const NEGOTIATING = [ + Version.DRAFT_17, + Version.DRAFT_18, + Version.DRAFT_19, + Version.DRAFT_20, + Version.DRAFT_21, + Version.DRAFT_22, +] as const; + +async function encode( + message: { encode(w: Writer, v: IetfVersion): Promise }, + version: IetfVersion = VERSION, +): Promise { + const chunks: Uint8Array[] = []; + const writer = new Writer( + new WritableStream({ + write(chunk) { + chunks.push(new Uint8Array(chunk)); + }, + }), + version, + ); + await message.encode(writer, version); + writer.close(); + await writer.closed; + + const out = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.byteLength, 0)); + let offset = 0; + for (const chunk of chunks) { + out.set(chunk, offset); + offset += chunk.byteLength; + } + return out; +} + +function reader(bytes: Uint8Array, version: IetfVersion = VERSION): Reader { + return new Reader(undefined, bytes, version); +} + +/** A parameter block carrying `value` under the EPOCH key, valid or not. */ +function epochParam(value: Uint8Array): Parameters { + const params = new Parameters(); + params.bytes.set(EPOCH_PARAM, value); + return params; +} + +test("Epoch: the registry code points and their parity", () => { + // Odd values are length-prefixed byte strings, even ones bare varints. + expect(SetupOption.Epoch).toBe(0x40b68n); + expect(SetupOption.Epoch % 2n).toBe(0n); + expect(EPOCH_PARAM % 2n).toBe(1n); +}); + +test("Epoch: SETUP declares it on draft-17 and later only", async () => { + for (const version of LEGACY) { + const params = new SetupOptions(); + EpochExt.intoSetup(params, version); + expect(params.getVarint(SetupOption.Epoch)).toBeUndefined(); + + // Even one that arrived anyway reads as "not negotiated" there. + params.setVarint(SetupOption.Epoch, 1n); + expect(EpochExt.fromSetup(params, version)).toBe(false); + } + + for (const version of NEGOTIATING) { + const params = new SetupOptions(); + expect(EpochExt.fromSetup(params, version)).toBe(false); + EpochExt.intoSetup(params, version); + const decoded = await SetupOptions.decode(reader(await encode(params, version), version), version); + expect(EpochExt.fromSetup(decoded, version)).toBe(true); + } +}); + +test("Epoch: the parameter is the UUID's 16 bytes, length-prefixed", async () => { + const params = new Parameters(); + params.epoch = EPOCH; + expect(Array.from(await encode(params))).toEqual([ + 0x01, // parameter count + 0xc4, + 0x0b, + 0x69, // EPOCH (0x40b69), delta encoded from 0 + 0x10, // value length + ...Epoch.toBytes(EPOCH), + ]); + + const decoded = await Parameters.decode(reader(await encode(params)), VERSION, "subscribe"); + expect(decoded.epoch).toBe(EPOCH); +}); + +test("Epoch: anything but a UUIDv7's 16 bytes is a protocol violation", async () => { + const v4 = Epoch.toBytes(EPOCH); + v4[6] = (v4[6] & 0x0f) | 0x40; + + for (const value of [new Uint8Array(), Epoch.toBytes(EPOCH).slice(0, 15), v4]) { + const encoded = await encode(epochParam(value)); + await expect(Parameters.decode(reader(encoded), VERSION, "subscribe")).rejects.toThrow(ProtocolViolation); + } +}); + +test("Epoch: a REQUEST_UPDATE never carries one", async () => { + const encoded = await encode(epochParam(Epoch.toBytes(EPOCH))); + for (const message of ["request-update", "subscribe-update"] as const) { + await expect(Parameters.decode(reader(encoded), VERSION, message)).rejects.toThrow(ProtocolViolation); + } +}); + +test("Epoch: SUBSCRIBE and TRACK_STATUS carry it on draft-17 and later only", async () => { + const trackNamespace = Path.from("alice"); + for (const version of [...LEGACY, ...NEGOTIATING]) { + const expected = EpochExt.supported(version) ? EPOCH : undefined; + + const subscribe = new Subscribe({ + requestId: 0n, + trackNamespace, + trackName: "video", + subscriberPriority: 0, + epoch: EPOCH, + }); + expect((await Subscribe.decode(reader(await encode(subscribe, version), version), version)).epoch).toBe( + expected, + ); + + const status = new TrackStatusRequest({ requestId: 0n, trackNamespace, trackName: "video", epoch: EPOCH }); + expect((await TrackStatusRequest.decode(reader(await encode(status, version), version), version)).epoch).toBe( + expected, + ); + } +}); + +test("Epoch: a joining FETCH that names one is malformed", async () => { + const joining = (params: Parameters) => ({ + encode: (w: Writer, version: IetfVersion) => + Message.encode(w, async (mw) => { + await mw.u62(0n); // request id + await mw.u53(0x2); // relative joining + await mw.u62(0n); // joining request id + await mw.u62(0n); // group offset + await params.encode(mw, version); + }), + }); + + // Control: the same FETCH without it decodes. + expect((await Fetch.decode(reader(await encode(joining(new Parameters()))), VERSION)).epoch).toBeUndefined(); + + const named = new Parameters(); + named.epoch = EPOCH; + await expect(Fetch.decode(reader(await encode(joining(named))), VERSION)).rejects.toThrow( + "EPOCH is not allowed on a joining FETCH", + ); +}); + +test("Epoch: PUBLISH_NAMESPACE carries it only once negotiated", async () => { + const encoded = await encode( + new PublishNamespace({ requestId: 1n, trackNamespace: Path.from("alice"), params: { epoch: EPOCH } }), + ); + + const decoded = await PublishNamespace.decode(reader(encoded), VERSION, { cluster: false, epoch: true }); + expect(decoded.params).toEqual({ cluster: undefined, epoch: EPOCH }); + + // A session that did not negotiate it was never sent one. + await expect(PublishNamespace.decode(reader(encoded), VERSION)).rejects.toThrow(ProtocolViolation); + + // An advertisement may lack one: the route had no epoch to carry. + const bare = await encode(new PublishNamespace({ requestId: 1n, trackNamespace: Path.from("alice") })); + expect( + (await PublishNamespace.decode(reader(bare), VERSION, { cluster: false, epoch: true })).params.epoch, + ).toBeUndefined(); +}); + +test.each([ + ["neither", false, false], + ["cluster only", true, false], + ["epoch only", false, true], + ["both", true, true], +] as const)("Epoch: NAMESPACE framing with %s negotiated", async (_name, cluster, epoch) => { + const negotiated = { cluster, epoch }; + const advert: Cluster.Advert = { hops: [HopSchema.parse(7n)], cost: 0n }; + const params: AdvertParams = { cluster: cluster ? advert : undefined, epoch: epoch ? EPOCH : undefined }; + const extended = cluster || epoch; + + const entry = new SubscribeNamespaceEntry({ suffix: Path.from("alice"), params: extended ? params : undefined }); + const encoded = await encode(entry); + const decoded = await SubscribeNamespaceEntry.decode(reader(encoded), VERSION, negotiated); + expect(decoded.suffix).toBe(Path.from("alice")); + expect(decoded.params).toEqual(extended ? params : undefined); + + // The block is present iff either extension is, so the base form is strictly shorter. + const base = await encode(new SubscribeNamespaceEntry({ suffix: Path.from("alice") })); + expect(base.length < encoded.length).toBe(extended); +}); + +test("Epoch: a NAMESPACE carrying one without MoQ Epoch is a protocol violation", async () => { + const advert: Cluster.Advert = { hops: [HopSchema.parse(7n)], cost: 0n }; + const encoded = await encode( + new SubscribeNamespaceEntry({ suffix: Path.from("alice"), params: { cluster: advert, epoch: EPOCH } }), + ); + await expect( + SubscribeNamespaceEntry.decode(reader(encoded), VERSION, { cluster: true, epoch: false }), + ).rejects.toThrow(ProtocolViolation); +}); diff --git a/js/net/src/ietf/epoch.ts b/js/net/src/ietf/epoch.ts new file mode 100644 index 00000000000..eb774415766 --- /dev/null +++ b/js/net/src/ietf/epoch.ts @@ -0,0 +1,34 @@ +import { SetupOption, type SetupOptions } from "./parameters.ts"; +import { type IetfVersion, Version } from "./version.ts"; + +/** + * The MoQ Epoch extension (draft-lcurley-moq-epoch-00). + * + * moq-transport names content by namespace alone, so a publisher that restarts at the same + * namespace looks like the same broadcast to every relay. This extension carries the + * publisher instance, the epoch moq-lite 07 puts on its routes and requests, as an EPOCH + * parameter: on each advertisement (PUBLISH_NAMESPACE and NAMESPACE), and on each request + * that resolves one (SUBSCRIBE, FETCH, and TRACK_STATUS). A namespace and an EPOCH name one + * broadcast; a request carrying one is refused rather than served by another instance. + * + * Negotiated on draft-17+ only, where SETUP is a Key-Value-Pair block, and only when both + * endpoints declare the option. + * + * @module + * @internal + */ + +/** Whether a version negotiates the extension: draft-17+, like MoQ Cluster. @internal */ +export function supported(version: IetfVersion): boolean { + return version !== Version.DRAFT_14 && version !== Version.DRAFT_15 && version !== Version.DRAFT_16; +} + +/** Whether the peer declared the option. @internal */ +export function fromSetup(params: SetupOptions, version: IetfVersion): boolean { + return supported(version) && params.getVarint(SetupOption.Epoch) !== undefined; +} + +/** Declare that we understand the EPOCH parameter, on the versions that negotiate it. @internal */ +export function intoSetup(params: SetupOptions, version: IetfVersion) { + if (supported(version)) params.setVarint(SetupOption.Epoch, 1n); +} diff --git a/js/net/src/ietf/fetch.ts b/js/net/src/ietf/fetch.ts index c49d8f6506b..43989fa3ac9 100644 --- a/js/net/src/ietf/fetch.ts +++ b/js/net/src/ietf/fetch.ts @@ -1,3 +1,4 @@ +import type * as Epoch from "../epoch.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import { hasRangeFilters, isDraft20 } from "./filter.ts"; @@ -44,15 +45,19 @@ export class Fetch { rangeFilters: boolean; /** The decoded standalone namespace, absent for a joining fetch. */ trackNamespace?: Path.Valid; + /** The publisher instance the requester expects (EPOCH, MoQ Epoch), never on a joining fetch. */ + epoch?: Epoch.Valid; constructor({ requestId, rangeFilters = false, trackNamespace, - }: { requestId: bigint; rangeFilters?: boolean; trackNamespace?: Path.Valid }) { + epoch, + }: { requestId: bigint; rangeFilters?: boolean; trackNamespace?: Path.Valid; epoch?: Epoch.Valid }) { this.requestId = requestId; this.rangeFilters = rangeFilters; this.trackNamespace = trackNamespace; + this.epoch = epoch; } async #encode(_w: Writer): Promise { @@ -106,8 +111,13 @@ export class Fetch { if (params.trackPropertyFilter) { throw new Error("TRACK_PROPERTY_FILTER is not allowed on FETCH"); } + // A joining FETCH is served by its subscription's instance, so naming one is malformed. + const epoch = params.epoch; + if (epoch !== undefined && trackNamespace === undefined) { + throw new Error("EPOCH is not allowed on a joining FETCH"); + } - return new Fetch({ requestId, rangeFilters: params.rangeFilters, trackNamespace }); + return new Fetch({ requestId, rangeFilters: params.rangeFilters, trackNamespace, epoch }); } } diff --git a/js/net/src/ietf/index.ts b/js/net/src/ietf/index.ts index 784a064100d..14ad7738bd5 100644 --- a/js/net/src/ietf/index.ts +++ b/js/net/src/ietf/index.ts @@ -4,6 +4,7 @@ export * as Auth from "./auth.ts"; export * as Cluster from "./cluster.ts"; export * from "./connection.ts"; export * from "./datagram.ts"; +export * as Epoch from "./epoch.ts"; export * from "./fetch.ts"; export * from "./goaway.ts"; export * from "./hidden.ts"; diff --git a/js/net/src/ietf/parameters.ts b/js/net/src/ietf/parameters.ts index 5b022be2d17..5ace084454a 100644 --- a/js/net/src/ietf/parameters.ts +++ b/js/net/src/ietf/parameters.ts @@ -1,4 +1,5 @@ -import { ProtocolViolation } from "../error.ts"; +import * as Epoch from "../epoch.ts"; +import { ProtocolViolation, reason } from "../error.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import * as Varint from "../varint.ts"; @@ -27,6 +28,8 @@ export const SetupOption = { Auth: 0x40b60n, /** ACTIVE_COUNT, from the MoQ Active Count extension. See `active_count.ts`. */ ActiveCount: 0x40b64n, + /** EPOCH, from the MoQ Epoch extension. See `epoch.ts`. */ + Epoch: 0x40b68n, } as const; // Unknown SETUP options may repeat, including GREASE (draft-21 section 9.1). @@ -236,6 +239,8 @@ const MSG_PARAM_FILL_PARAMETERS = 0x23n; const MSG_PARAM_HOP_PATH = 0x40b57n; /// ACTIVE_COUNT, from the MoQ Active Count extension. const MSG_PARAM_ACTIVE_COUNT = 0x40b66n; +/// EPOCH, from the MoQ Epoch extension: a UUIDv7's 16 bytes. See `epoch.ts`. +const MSG_PARAM_EPOCH = 0x40b69n; /// Message parameter ids defined in draft-16. A known id on the wrong message is ignored. const DRAFT16_MESSAGE_PARAMS: readonly bigint[] = [0x02n, 0x03n, 0x08n, 0x09n, 0x10n, 0x20n, 0x21n, 0x22n, 0x32n]; @@ -283,6 +288,7 @@ function allows(message: ControlMessage, version: IetfVersion, id: bigint): bool const fill = id === MSG_PARAM_FILL_PARAMETERS && draft20(version); const include = id === MSG_PARAM_INCLUDE_PROPERTIES && draft20(version); const newGroup = id === MSG_PARAM_NEW_GROUP_REQUEST && from16; + const epoch = id === MSG_PARAM_EPOCH && from17; switch (message) { case "subscribe": @@ -298,7 +304,8 @@ function allows(message: ControlMessage, version: IetfVersion, id: bigint): bool fill || range || newGroup || - include + include || + epoch ); case "subscribe-ok": // Draft-14 defines only MAX_CACHE_DURATION here. @@ -335,7 +342,7 @@ function allows(message: ControlMessage, version: IetfVersion, id: bigint): bool (order && (d15 || draft20(version))) ); case "publish-namespace": - return auth || id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST; + return auth || id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST || epoch; case "fetch": return ( auth || @@ -344,12 +351,13 @@ function allows(message: ControlMessage, version: IetfVersion, id: bigint): bool (filter && draft20(version)) || order || range || - include + include || + epoch ); case "request-ok": return expires || largest || id === MSG_PARAM_ACTIVE_COUNT; case "namespace": - return id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST; + return id === MSG_PARAM_HOP_PATH || id === MSG_PARAM_ROUTE_COST || epoch; } } @@ -406,6 +414,7 @@ function getMessageParamKind(id: bigint): MessageParamKind { case MSG_PARAM_AUTHORIZATION_TOKEN: case MSG_PARAM_FILL_PARAMETERS: case MSG_PARAM_HOP_PATH: + case MSG_PARAM_EPOCH: return "bytes"; default: if (MSG_PARAM_REPEATABLE.includes(id)) return "bytes"; @@ -630,6 +639,17 @@ export class Parameters { this.vars.set(MSG_PARAM_ROUTE_COST, v); } + /** EPOCH (MoQ Epoch): the publisher instance an advertisement or request names. */ + get epoch(): Epoch.Valid | undefined { + const value = this.bytes.get(MSG_PARAM_EPOCH); + return value === undefined ? undefined : Epoch.fromBytes(value); + } + + set epoch(v: Epoch.Valid | undefined) { + if (v === undefined) this.bytes.delete(MSG_PARAM_EPOCH); + else this.bytes.set(MSG_PARAM_EPOCH, Epoch.toBytes(v)); + } + /** Encode the block, leaving out the varints in `omit`, which the message carries as fixed fields. */ async encode(w: Writer, version: IetfVersion, omit: readonly bigint[] = []) { const filter = this.#filter; @@ -879,7 +899,16 @@ export class Parameters { break; case "bytes": { const size = await r.u53(); - params.bytes.set(id, await r.read(size)); + const value = await r.read(size); + // Anything but a UUIDv7's 16 bytes is malformed, so refuse it here rather than on first read. + if (id === MSG_PARAM_EPOCH) { + try { + Epoch.fromBytes(value); + } catch (err) { + throw new ProtocolViolation(`malformed EPOCH: ${reason(err)}`, { cause: err }); + } + } + params.bytes.set(id, value); break; } } diff --git a/js/net/src/ietf/publish_namespace.ts b/js/net/src/ietf/publish_namespace.ts index 19b80017b73..3595759544c 100644 --- a/js/net/src/ietf/publish_namespace.ts +++ b/js/net/src/ietf/publish_namespace.ts @@ -1,3 +1,4 @@ +import type * as Epoch from "../epoch.ts"; import { ProtocolViolation, reason, SessionError, StreamError } from "../error.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; @@ -8,6 +9,69 @@ import { Parameters } from "./parameters.ts"; import { MalformedAuthToken, tokenIntoRequest } from "./token.ts"; import { type IetfVersion, Version } from "./version.ts"; +/** + * Which advertisement extensions a session negotiated: what its PUBLISH_NAMESPACE and + * NAMESPACE messages carry. + */ +export interface Negotiated { + /** MoQ Cluster: every advertisement carries HOP_PATH, and may carry ROUTE_COST. */ + cluster: boolean; + /** MoQ Epoch: an advertisement may carry EPOCH. */ + epoch: boolean; +} + +/** A session that negotiated neither advertisement extension. */ +export const NEGOTIATED_NONE: Negotiated = { cluster: false, epoch: false }; + +/** Whether NAMESPACE takes the extended form, with a Parameters field. */ +export function extended(negotiated: Negotiated): boolean { + return negotiated.cluster || negotiated.epoch; +} + +/** The extension parameters one advertisement carries. */ +export interface AdvertParams { + /** The MoQ Cluster parameters (see {@link Cluster}), set exactly on a session that negotiated it. */ + cluster?: Cluster.Advert; + /** The MoQ Epoch parameter: the publisher instance the route serves, if it names one. */ + epoch?: Epoch.Valid; +} + +/** Write an advertisement's extension parameters into a fresh block. */ +export function advertIntoParams(advert: AdvertParams): Parameters { + const params = advert.cluster ? Cluster.intoParams(advert.cluster) : new Parameters(); + params.epoch = advert.epoch; + return params; +} + +/** + * Read an advertisement's Parameters field, checked against the list of the message that + * carries it (PUBLISH_NAMESPACE also allows a token), expecting what the session negotiated. + * + * Every way this fails is one to close the session over: a block that does not parse, a + * negotiated cluster session that omits HOP_PATH, or an EPOCH on a session that did not + * negotiate MoQ Epoch. A request token's own refusal keeps its type. + */ +export async function decodeAdvert( + r: Reader, + version: IetfVersion, + message: "namespace" | "publish-namespace", + negotiated: Negotiated, +): Promise { + let params: Parameters; + try { + params = await Parameters.decode(r, version, message); + } catch (err) { + // Keep a violation's own code, such as a request token's, and a refusal of the request alone. + if (err instanceof ProtocolViolation || err instanceof MalformedAuthToken) throw err; + throw new ProtocolViolation(reason(err), { cause: err }); + } + + const epoch = params.epoch; + // An unknown parameter to a session that never offered the extension. + if (epoch !== undefined && !negotiated.epoch) throw new ProtocolViolation("EPOCH without MoQ Epoch"); + return { cluster: negotiated.cluster ? Cluster.fromParams(params) : undefined, epoch }; +} + // In draft-14, ANNOUNCE is renamed to PUBLISH_NAMESPACE export class PublishNamespace { static id = 0x06; @@ -15,10 +79,8 @@ export class PublishNamespace { requestId: bigint; trackNamespace: Path.Valid; - /** The MoQ Cluster parameters (see {@link Cluster}). Set on a session that negotiated - * the extension and `undefined` on one that did not, which is what decides whether they - * appear on the wire at all. */ - cluster?: Cluster.Advert; + /** The extension parameters, which a session that negotiated none leaves empty. */ + params: AdvertParams; /** The AUTHORIZATION TOKEN to send, a value agreed out of band. Decoding leaves it unset. */ token?: Uint8Array; @@ -26,12 +88,12 @@ export class PublishNamespace { constructor({ requestId, trackNamespace, - cluster, + params = {}, token, - }: { requestId: bigint; trackNamespace: Path.Valid; cluster?: Cluster.Advert; token?: Uint8Array }) { + }: { requestId: bigint; trackNamespace: Path.Valid; params?: AdvertParams; token?: Uint8Array }) { this.requestId = requestId; this.trackNamespace = trackNamespace; - this.cluster = cluster; + this.params = params; this.token = token; } @@ -41,7 +103,7 @@ export class PublishNamespace { await w.u62(0n); // required_request_id_delta: only 0 supported until stream-per-request } await Namespace.encode(w, this.trackNamespace); - const params = this.cluster ? Cluster.intoParams(this.cluster) : new Parameters(); + const params = advertIntoParams(this.params); if (this.token) tokenIntoRequest(params, this.token, version); await params.encode(w, version); } @@ -51,30 +113,27 @@ export class PublishNamespace { } /** - * Decode the message, expecting the cluster parameters when the session negotiated the - * extension. + * Decode the message, expecting the parameters of the extensions the session negotiated. * * The negotiation is session state rather than anything in the message, so the caller - * supplies it. A negotiated session that omits HOP_PATH is a protocol violation, which - * surfaces here as a throw. + * supplies it. See {@link decodeAdvert} for what it refuses. */ - static async decode(r: Reader, version: IetfVersion, negotiated = false): Promise { + static async decode( + r: Reader, + version: IetfVersion, + negotiated: Negotiated = NEGOTIATED_NONE, + ): Promise { return Message.decode(r, (rd) => PublishNamespace.#decode(rd, version, negotiated)); } - static async #decode(r: Reader, version: IetfVersion, negotiated: boolean): Promise { + static async #decode(r: Reader, version: IetfVersion, negotiated: Negotiated): Promise { const requestId = await r.u62(); if (version === Version.DRAFT_17) { await r.u62(); // required_request_id_delta } const trackNamespace = await Namespace.decode(r); - if (negotiated) { - const cluster = await Cluster.decodeParams(r, version, "publish-namespace"); - return new PublishNamespace({ requestId, trackNamespace, cluster }); - } - - await Parameters.decode(r, version, "publish-namespace"); - return new PublishNamespace({ requestId, trackNamespace }); + const params = await decodeAdvert(r, version, "publish-namespace", negotiated); + return new PublishNamespace({ requestId, trackNamespace, params }); } } @@ -172,6 +231,8 @@ export class PublishNamespaceUpdate { await r.u62(); // required_request_id_delta (draft-17 only, removed in draft-18 per #1615) } const params = await Parameters.decode(r, version, "publish-namespace"); + // An epoch is fixed for the life of an advertisement, so no update carries one. + if (params.epoch !== undefined) throw new ProtocolViolation("EPOCH on a PUBLISH_NAMESPACE update"); return new PublishNamespaceUpdate({ requestId, namespaceRequestId, update: Cluster.updateFromParams(params) }); } } diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 94bf76e8296..85262a0c32b 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -45,6 +45,9 @@ function publish(origin: OriginProducer, path: Path.Valid) { const VERSION = Version.DRAFT_19; +/** A session that negotiated MoQ Cluster alone. */ +const CLUSTER = { cluster: true, epoch: false }; + /** How long to wait for a stream before calling it absent, which is how a regression reports. */ const STREAM_WAIT = 1000; @@ -130,6 +133,7 @@ function publisher( grant, activeCount, auth, + epoch, }: { requiresSolicitation?: boolean; session?: Session; @@ -137,6 +141,7 @@ function publisher( grant?: Signal; activeCount?: boolean; auth?: Tokens; + epoch?: boolean; } = {}, ): { pub: Publisher; origin: OriginProducer } { const origin = new OriginProducer(); @@ -151,6 +156,7 @@ function publisher( grant, activeCount, auth, + epoch, }), origin, }; @@ -1178,13 +1184,13 @@ test("an advertisement carries our hop id once the peer declared one", async () if (peer === undefined) { // Nothing negotiated, so the parameters are absent: reading the message as a // negotiated one finds no HOP_PATH and rejects. - await expect(PublishNamespace.decode(stream.reader, VERSION, true)).rejects.toThrow(); + await expect(PublishNamespace.decode(stream.reader, VERSION, CLUSTER)).rejects.toThrow(); } else { // Our own Hop ID is the last entry, and we originate everything we advertise, // so it is the only one. The cost is 0: we are already producing the content. - const msg = await PublishNamespace.decode(stream.reader, VERSION, true); + const msg = await PublishNamespace.decode(stream.reader, VERSION, CLUSTER); expect(msg.trackNamespace).toBe(Path.from("mine")); - expect(msg.cluster).toEqual({ hops: [self], cost: 0n }); + expect(msg.params.cluster).toEqual({ hops: [self], cost: 0n }); await acceptPublishNamespace(stream); } @@ -1192,6 +1198,137 @@ test("an advertisement carries our hop id once the peer declared one", async () } }); +/** A session that negotiated MoQ Epoch alone. */ +const EPOCH = { cluster: false, epoch: true }; + +/** + * An advertisement names the publisher instance once the peer declared MoQ Epoch. A peer + * that did not has not read the parameter, so sending it would be a protocol violation. + */ +test("an advertisement carries its epoch only once negotiated", async () => { + for (const negotiated of [true, false]) { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server, { epoch: negotiated }); + const epoch = Epoch.mint(); + origin.createBroadcast(Path.from("mine")).announce({ epoch }); + void pub.runPublishNamespaces(); + + const stream = await nextStream(pair.client); + if (!stream) throw new Error("no PUBLISH_NAMESPACE for the broadcast"); + expect(await stream.reader.u53()).toBe(PublishNamespace.id); + const msg = await PublishNamespace.decode(stream.reader, VERSION, EPOCH); + expect(msg.params.epoch).toBe(negotiated ? epoch : undefined); + await acceptPublishNamespace(stream); + + origin.close(); + } +}); + +/** A new instance at a path is other content, so it is a withdrawal and a fresh advertisement. */ +test("an epoch change withdraws and advertises the new epoch", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server, { epoch: true }); + const streams = accepted(pair.client); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + const first = Epoch.mint(); + broadcast.announce({ epoch: first }); + void pub.runPublishNamespaces(); + + const old = await take(streams); + expect(await old.reader.u53()).toBe(PublishNamespace.id); + expect((await PublishNamespace.decode(old.reader, VERSION, EPOCH)).params.epoch).toBe(first); + await acceptPublishNamespace(old); + + const second = Epoch.mint(); + broadcast.announce({ ...broadcast.route, epoch: second }); + + expect(await old.reader.done().catch(error)).toMatchObject({ code: StreamCode.Cancel }); + const next = await take(streams); + expect(await next.reader.u53()).toBe(PublishNamespace.id); + expect((await PublishNamespace.decode(next.reader, VERSION, EPOCH)).params.epoch).toBe(second); + } finally { + origin.close(); + } +}); + +/** A request that names an instance is served by that one alone, or refused as gone. */ +test("a request pinned to another epoch is refused DOES_NOT_EXIST", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const { pub, origin } = publisher(pair.server, { session, epoch: true }); + const epoch = Epoch.mint(); + const broadcast = origin.createBroadcast(Path.from("room")); + broadcast.announce({ epoch }); + broadcast.createTrack("video"); + origin.createBroadcast(Path.from("epochless")).announce(); + + const status = async (namespace: string, pinned: Epoch.Valid | undefined) => { + const { stream, wire } = requestStream(VERSION); + const request = new TrackStatusRequest({ + requestId: 7n, + trackNamespace: Path.from(namespace), + trackName: "video", + epoch: pinned, + }); + await pub.runTrackStatusRequest(request, stream); + return wire(); + }; + + // Control: the named instance, or none at all, is served. + expect(await (await status("room", epoch)).u53()).toBe(TrackStatusOk.id(VERSION)); + expect(await (await status("room", undefined)).u53()).toBe(TrackStatusOk.id(VERSION)); + + const missing = toRequestCode("does_not_exist", "track_status", VERSION); + expect(await refusalCode(await status("room", Epoch.mint()), VERSION)).toBe(missing); + expect(await refusalCode(await status("epochless", epoch), VERSION)).toBe(missing); + + const subscribe = requestStream(VERSION); + await pub.runSubscribe( + new Subscribe({ + requestId: 7n, + trackNamespace: Path.from("room"), + trackName: "video", + subscriberPriority: 0, + epoch: Epoch.mint(), + }), + subscribe.stream, + ); + const r = subscribe.wire(); + expect(await r.u53()).toBe(RequestError.id); + expect((await RequestError.decode(r, VERSION)).errorCode).toBe( + toRequestCode("does_not_exist", "subscribe", VERSION), + ); + + origin.close(); +}); + +/** Only a session that negotiated MoQ Epoch may name an instance. */ +test("EPOCH on a request without MoQ Epoch is a protocol violation", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + const epoch = Epoch.mint(); + const trackNamespace = Path.from("room"); + + await expect( + pub.runSubscribe( + new Subscribe({ requestId: 7n, trackNamespace, trackName: "video", subscriberPriority: 0, epoch }), + requestStream(VERSION).stream, + ), + ).rejects.toThrow(ProtocolViolation); + await expect( + pub.runTrackStatusRequest( + new TrackStatusRequest({ requestId: 7n, trackNamespace, trackName: "video", epoch }), + requestStream(VERSION).stream, + ), + ).rejects.toThrow(ProtocolViolation); + await expect( + pub.runFetch(new Fetch({ requestId: 7n, trackNamespace, epoch }), requestStream(VERSION).stream), + ).rejects.toThrow(ProtocolViolation); + + origin.close(); +}); + /** Let every pending promise chain run without letting a faked timer fire. */ async function flush() { for (let i = 0; i < 20; i++) await new Promise((resolve) => setImmediate(resolve)); @@ -1257,9 +1394,9 @@ async function take(queue: Stream[]): Promise { /** Read one PUBLISH_NAMESPACE and its cluster parameters, then accept it. */ async function acceptClustered(stream: Stream): Promise { expect(await stream.reader.u53()).toBe(PublishNamespace.id); - const msg = await PublishNamespace.decode(stream.reader, VERSION, true); + const msg = await PublishNamespace.decode(stream.reader, VERSION, CLUSTER); await acceptPublishNamespace(stream); - return msg.cluster; + return msg.params.cluster; } /** Read one REQUEST_UPDATE off a PUBLISH_NAMESPACE stream. */ @@ -1363,15 +1500,21 @@ test.each([ const entry = async () => { expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); - return await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + return await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, CLUSTER); }; expect(await subscription.reader.u53()).toBe(RequestOk.id); await RequestOk.decode(subscription.reader, VERSION); - expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [VIA, self], cost: 4n } }); + expect(await entry()).toMatchObject({ + suffix: Path.from("mine"), + params: { cluster: { hops: [VIA, self], cost: 4n } }, + }); broadcast.announce({ hops: [...hops], cost }); - expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [...hops, self], cost } }); + expect(await entry()).toMatchObject({ + suffix: Path.from("mine"), + params: { cluster: { hops: [...hops, self], cost } }, + }); const more = watch(subscription.reader.u53()); await flush(); @@ -1600,14 +1743,14 @@ test("a republish withdraws the solicited NAMESPACE and sends it again", async ( expect(await subscription.reader.u53()).toBe(RequestOk.id); await RequestOk.decode(subscription.reader, VERSION); expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); - await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, CLUSTER); republish(origin, broadcast); expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntryDone.id); expect((await SubscribeNamespaceEntryDone.decode(subscription.reader, VERSION)).suffix).toBe(Path.from("mine")); expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); - expect((await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true)).suffix).toBe( + expect((await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, CLUSTER)).suffix).toBe( Path.from("mine"), ); subscription.close(); @@ -1780,7 +1923,7 @@ test.each([ const stream = await nextStream(pair.client); if (!stream) throw new Error("no PUBLISH_NAMESPACE for the broadcast"); expect(await stream.reader.u53()).toBe(PublishNamespace.id); - const msg = await PublishNamespace.decode(stream.reader, VERSION, peer !== undefined); + const msg = await PublishNamespace.decode(stream.reader, VERSION, { cluster: peer !== undefined, epoch: false }); expect(msg.trackNamespace).toBe(Path.from("mine")); await acceptPublishNamespace(stream); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 54a049c7ace..584b631effb 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -6,6 +6,7 @@ import { enforceGrant } from "../auth_session.ts"; import type * as broadcast from "../broadcast.ts"; import { Withdrawal } from "../connection/withdrawal.ts"; import * as DatagramStream from "../datagram_stream.ts"; +import type * as Epoch from "../epoch.ts"; import { controlTimeout, error, @@ -48,6 +49,7 @@ import { fromWire, toWire } from "./priority.ts"; import * as Properties from "./properties.ts"; import { PublishDone, PublishDoneStatus } from "./publish.ts"; import { + type AdvertParams, PublishNamespace, PublishNamespaceDone, PublishNamespaceOk, @@ -305,6 +307,10 @@ export class Publisher { // back came from us. `undefined` when nothing negotiated it. #advert?: Cluster.Advert; + // Whether both SETUPs offered MoQ Epoch: every advertisement names its route's epoch, and + // a request may name the one it expects. + #epoch: boolean; + // Our grant (MoQ Auth): only what it lets us publish is advertised and served, and a // shrink withdraws what it no longer covers. Undefined until the peer answers, which // allows everything. @@ -332,6 +338,7 @@ export class Publisher { hidden = false, activeCount = false, cluster, + epoch = false, grant = new Signal(undefined), auth, ready = Promise.resolve(), @@ -351,6 +358,8 @@ export class Publisher { activeCount?: boolean; /** The Hop IDs the SETUP exchange settled (MoQ Cluster). */ cluster?: Cluster.Hops; + /** Whether both SETUPs offered MoQ Epoch. */ + epoch?: boolean; /** The union of our tokens' grants (MoQ Auth), which bounds what we publish. */ grant?: Getter; /** This session's tokens, which a route names for its request to carry. */ @@ -375,6 +384,7 @@ export class Publisher { this.#hidden = hidden; this.#activeCount = activeCount; this.#advert = Cluster.advertise(cluster); + this.#epoch = epoch; this.#datagramWriter = DatagramStream.datagramWriter(quic); } @@ -396,6 +406,7 @@ export class Publisher { * @internal */ async runSubscribe(msg: Subscribe, stream: Stream) { + this.#pinned(msg.epoch); if (Namespace.reserved(msg.trackNamespace, this.#session.version)) { await refuseReserved(stream, this.#session.version); return; @@ -448,7 +459,7 @@ export class Publisher { refusal = { errorCode: toRequestCode("unauthorized", "subscribe", version), reasonPhrase: "not granted" }; } else { try { - broadcast = await this.#resolve(name, left.signal); + broadcast = await this.#resolve(name, left.signal, msg.epoch); } catch (err: unknown) { // Nobody is left to refuse. if (left.signal.aborted) { @@ -1258,8 +1269,9 @@ export class Publisher { // be declined. const namespace = async (suffix: Path.Valid, snap: Advertised): Promise => { await stream.writer.u53(SubscribeNamespaceEntry.id); - const cluster = clusterFor(this.#advert, snap.route); - await new SubscribeNamespaceEntry({ suffix, cluster }).encode(stream.writer, version); + // Either extension puts the Parameters field on NAMESPACE, even an empty one. + const params = this.#advert !== undefined || this.#epoch ? this.#params(snap.route) : undefined; + await new SubscribeNamespaceEntry({ suffix, params }).encode(stream.writer, version); return "held"; }; const target: Target = legacy @@ -1651,13 +1663,21 @@ export class Publisher { : Instant.add(now(), Nano.fromMilli(Milli(Number(err.retryInterval)))); } + /** + * The extension parameters an advertisement of `route` carries. The epoch is forwarded + * as the route names it, and never invented for one without. + */ + #params(route: Route): AdvertParams { + return { cluster: clusterFor(this.#advert, route), epoch: this.#epoch ? route.epoch : undefined }; + } + /** * Advertise one namespace on its own PUBLISH_NAMESPACE request. A declined request * is logged and skipped: a peer that wants none of this rejects each one and stays * connected. */ async #advertise(path: Path.Valid, requests: Requests, route: Route): Promise { - const cluster = clusterFor(this.#advert, route); + const params = this.#params(route); const auth = this.#carry(route.auth); const requestId = await this.#session.nextRequestId(); if (requestId === undefined) return "dropped"; @@ -1675,7 +1695,7 @@ export class Publisher { const stream = request; await stream.writer.u53(PublishNamespace.id); const token = this.#auth?.carried(auth); - const msg = new PublishNamespace({ requestId, trackNamespace: path, cluster, token }); + const msg = new PublishNamespace({ requestId, trackNamespace: path, params, token }); await msg.encode(stream.writer, this.#session.version); // Read response (RequestOk and PublishNamespaceOk share 0x07) @@ -1842,6 +1862,7 @@ export class Publisher { * @internal */ async runTrackStatusRequest(msg: TrackStatusRequest, stream: Stream) { + this.#pinned(msg.epoch); if (Namespace.reserved(msg.trackNamespace, this.#session.version)) { await refuseReserved(stream, this.#session.version); return; @@ -1877,7 +1898,7 @@ export class Publisher { try { let answer: TrackStatusOk; try { - const broadcast = await this.#resolve(name, hold.signal); + const broadcast = await this.#resolve(name, hold.signal, msg.epoch); const info = await wireOf(broadcast).resolveTrackInfo(msg.trackName, hold.signal); const largest = wireOf(broadcast).largest(msg.trackName); answer = new TrackStatusOk({ @@ -1958,6 +1979,7 @@ export class Publisher { * @internal */ async runFetch(msg: Fetch, stream: Stream) { + this.#pinned(msg.epoch); this.#fetches.acquire(); try { if (msg.trackNamespace !== undefined && Namespace.reserved(msg.trackNamespace, this.#session.version)) { @@ -2024,14 +2046,22 @@ export class Publisher { /** * Resolve the broadcast a request names for serving: a local publish, or else the * origin's routes and dynamic handlers. Rejects with the abort once `signal` aborts. + * + * A request naming an `epoch` is served only by that instance: one now serving another + * epoch, or none, refuses it as gone rather than answering with other content. */ - async #resolve(name: Path.Valid, signal: AbortSignal): Promise { + async #resolve(name: Path.Valid, signal: AbortSignal, epoch: Epoch.Valid | undefined): Promise { const broadcast = this.#publish && - (wireOf(this.#publish).local(name) ?? (await wireOf(this.#publish).demand(name, undefined, signal))); + (wireOf(this.#publish).local(name, epoch) ?? (await wireOf(this.#publish).demand(name, epoch, signal))); if (!broadcast) throw new NotFound(`broadcast ${name}`); return broadcast; } + + /** Break a session whose peer names an epoch it was never told about: MoQ Epoch was not negotiated. */ + #pinned(epoch: Epoch.Valid | undefined) { + if (epoch !== undefined && !this.#epoch) throw new ProtocolViolation("EPOCH without MoQ Epoch"); + } } /** A request's refusal: its code on this draft, and why. */ diff --git a/js/net/src/ietf/subscribe.ts b/js/net/src/ietf/subscribe.ts index 52dbddb6dfc..ff2f8f62bcb 100644 --- a/js/net/src/ietf/subscribe.ts +++ b/js/net/src/ietf/subscribe.ts @@ -1,6 +1,8 @@ +import type * as Epoch from "../epoch.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import type { Order } from "../track.ts"; +import { supported as epochSupported } from "./epoch.ts"; import * as Filter from "./filter.ts"; import * as Message from "./message.ts"; import * as Namespace from "./namespace.ts"; @@ -84,6 +86,12 @@ export class Subscribe { /** Whether RENDEZVOUS_TIMEOUT requested a wait; never encoded. */ rendezvous: boolean; + /** + * The publisher instance the subscriber expects (EPOCH, MoQ Epoch, draft-17+). Only a + * session that negotiated the extension names one; the session refuses one otherwise. + */ + epoch?: Epoch.Valid; + constructor({ requestId, trackNamespace, @@ -96,6 +104,7 @@ export class Subscribe { forward, rangeFilters, rendezvous, + epoch, }: { requestId: bigint; trackNamespace: Path.Valid; @@ -108,6 +117,7 @@ export class Subscribe { forward?: boolean; rangeFilters?: boolean; rendezvous?: boolean; + epoch?: Epoch.Valid; }) { this.requestId = requestId; this.trackNamespace = trackNamespace; @@ -120,6 +130,7 @@ export class Subscribe { this.forward = forward ?? true; this.rangeFilters = rangeFilters ?? false; this.rendezvous = rendezvous ?? false; + this.epoch = epoch; } async #encode(w: Writer, version: IetfVersion): Promise { @@ -156,6 +167,8 @@ export class Subscribe { params.includeProperties = false; } } + // The same for EPOCH, which exists from draft-17. + if (epochSupported(version)) params.epoch = this.epoch; await params.encode(w, version); } @@ -234,6 +247,7 @@ export class Subscribe { forward: params.forward ?? true, rangeFilters: params.rangeFilters, rendezvous: (params.vars.get(0x04n) ?? 0n) > 0n, + epoch: params.epoch, }); } } diff --git a/js/net/src/ietf/subscribe_namespace.ts b/js/net/src/ietf/subscribe_namespace.ts index b20fcef7cff..341a565bbf4 100644 --- a/js/net/src/ietf/subscribe_namespace.ts +++ b/js/net/src/ietf/subscribe_namespace.ts @@ -1,10 +1,17 @@ import { ProtocolViolation } from "../error.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; -import * as Cluster from "./cluster.ts"; import * as Message from "./message.ts"; import * as Namespace from "./namespace.ts"; import { Parameters } from "./parameters.ts"; +import { + type AdvertParams, + advertIntoParams, + decodeAdvert, + extended, + NEGOTIATED_NONE, + type Negotiated, +} from "./publish_namespace.ts"; import { type IetfVersion, Version } from "./version.ts"; // True for the drafts that use the legacy 0x11 SUBSCRIBE_NAMESPACE message. @@ -276,9 +283,10 @@ export class UnsubscribeNamespace { /** * NAMESPACE message (0x08), v16+, sent on the SUBSCRIBE_NAMESPACE bidi stream. * - * The base message carries only the suffix. A session that negotiated the MoQ Cluster - * extension uses the extended form instead, which appends a Parameters field so the - * advertisement can carry its HOP_PATH and ROUTE_COST (see `cluster.ts`). + * The base message carries only the suffix. A session that negotiated the MoQ Cluster or + * MoQ Epoch extension uses the extended form instead, which appends one Parameters field + * for both, so the advertisement can carry its HOP_PATH and ROUTE_COST (see `cluster.ts`) + * and its EPOCH (see `epoch.ts`). */ export class SubscribeNamespaceEntry { static id = 0x08; @@ -286,20 +294,20 @@ export class SubscribeNamespaceEntry { suffix: Path.Valid; /** - * The MoQ Cluster parameters. Set selects the extended form, `undefined` the base one. - * An endpoint must not append them on a session that did not negotiate. + * The extension parameters. Set selects the extended form, `undefined` the base one. + * An endpoint must not append them on a session that negotiated neither extension. */ - cluster?: Cluster.Advert; + params?: AdvertParams; - constructor({ suffix, cluster }: { suffix: Path.Valid; cluster?: Cluster.Advert }) { + constructor({ suffix, params }: { suffix: Path.Valid; params?: AdvertParams }) { this.suffix = suffix; - this.cluster = cluster; + this.params = params; } async #encode(w: Writer, version: IetfVersion): Promise { await Namespace.encode(w, this.suffix); // The base form has no Parameters field at all, so there is nothing to write. - if (this.cluster) await Cluster.intoParams(this.cluster).encode(w, version); + if (this.params) await advertIntoParams(this.params).encode(w, version); } async encode(w: Writer, version: IetfVersion): Promise { @@ -307,18 +315,23 @@ export class SubscribeNamespaceEntry { } /** - * Decode the message, expecting the extended form when the session negotiated the MoQ - * Cluster extension. See {@link PublishNamespace.decode}. + * Decode the message, expecting the extended form when the session negotiated an + * extension that defines it. See {@link PublishNamespace.decode}. */ - static async decode(r: Reader, version: IetfVersion, negotiated = false): Promise { + static async decode( + r: Reader, + version: IetfVersion, + negotiated: Negotiated = NEGOTIATED_NONE, + ): Promise { return Message.decode(r, (rd) => SubscribeNamespaceEntry.#decode(rd, version, negotiated)); } - static async #decode(r: Reader, version: IetfVersion, negotiated: boolean): Promise { + static async #decode(r: Reader, version: IetfVersion, negotiated: Negotiated): Promise { const suffix = await Namespace.decode(r); - if (!negotiated) return new SubscribeNamespaceEntry({ suffix }); + // The base form has no Parameters field at all, so there is nothing to read. + if (!extended(negotiated)) return new SubscribeNamespaceEntry({ suffix }); - return new SubscribeNamespaceEntry({ suffix, cluster: await Cluster.decodeParams(r, version, "namespace") }); + return new SubscribeNamespaceEntry({ suffix, params: await decodeAdvert(r, version, "namespace", negotiated) }); } } diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 2c9ce400b7b..c70a3f9e4d5 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -2,6 +2,7 @@ import { expect, jest, onTestFinished, spyOn, test } from "bun:test"; import { Milli } from "@moq/clock"; import { Once } from "@moq/signals"; import type * as announce from "../announced.ts"; +import * as Epoch from "../epoch.ts"; import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; import { hooks } from "../internal.ts"; @@ -241,7 +242,7 @@ async function acceptSubscribeNamespace(transport: WebTransport): Promise { await stream.writer.u53(SubscribeNamespaceEntry.id); - await new SubscribeNamespaceEntry({ suffix: path, cluster }).encode(stream.writer, VERSION); + await new SubscribeNamespaceEntry({ suffix: path, params: cluster && { cluster } }).encode(stream.writer, VERSION); } /** @@ -548,7 +549,7 @@ test("a PUBLISH_NAMESPACE that looped back through us is refused", async () => { new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("mine"), - cluster: { hops: [SELF, PEER], cost: 0n }, + params: { cluster: { hops: [SELF, PEER], cost: 0n } }, }), request, ); @@ -607,7 +608,7 @@ test("a malformed PUBLISH_NAMESPACE update closes the session", async () => { await new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("theirs"), - cluster: { hops: [PEER], cost: 0n }, + params: { cluster: { hops: [PEER], cost: 0n } }, }).encode(request.writer, VERSION); expect(await request.reader.u53()).toBe(RequestOk.id); @@ -649,7 +650,7 @@ test("a PUBLISH_NAMESPACE update that starts looping back is detached", async () new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("theirs"), - cluster: { hops: [publisher, PEER], cost: 0n }, + params: { cluster: { hops: [publisher, PEER], cost: 0n } }, }), request, ); @@ -782,7 +783,7 @@ test("a PUBLISH_NAMESPACE repricing is acknowledged in place", async () => { new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("theirs"), - cluster: { hops: [PEER], cost: 4n }, + params: { cluster: { hops: [PEER], cost: 4n } }, }), request, ); @@ -831,7 +832,7 @@ test("a PUBLISH_NAMESPACE update that changes the publisher applies in place", a new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("theirs"), - cluster: { hops: [HopSchema.parse(11n), PEER], cost: 0n }, + params: { cluster: { hops: [HopSchema.parse(11n), PEER], cost: 0n } }, }), request, ); @@ -880,7 +881,7 @@ test("a repeated PUBLISH_NAMESPACE is a protocol violation", async () => { const advert = new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("theirs"), - cluster: { hops: [PEER], cost: 0n }, + params: { cluster: { hops: [PEER], cost: 0n } }, }); const request = await Stream.open(pair.server, { version: VERSION }); const handler = subscriber.runPublishNamespace(advert, request); @@ -2265,3 +2266,121 @@ test.each(["done", "fin"] as const)("a counted set cut short by %s closes the se await violationClosed(pair); } }); + +/** Advertise `path` inline under `epoch`, on a session that negotiated MoQ Epoch alone. */ +async function inlineEpoch(stream: Stream, path: Path.Valid, epoch: Epoch.Valid): Promise { + await stream.writer.u53(SubscribeNamespaceEntry.id); + await new SubscribeNamespaceEntry({ suffix: path, params: { epoch } }).encode(stream.writer, VERSION); +} + +/** Open a PUBLISH_NAMESPACE for `path` under `epoch`, returning the handler and the peer's end. */ +async function publishEpoch( + pair: ReturnType, + subscriber: Subscriber, + path: Path.Valid, + epoch: Epoch.Valid, +): Promise<{ handler: Promise; peer: Stream }> { + const stream = await Stream.open(pair.server, { version: VERSION }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: path, params: { epoch } }), + stream, + ); + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream"); + expect(await peer.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(peer.reader, VERSION); + return { handler, peer }; +} + +/** The route names the advertised instance, and so does every SUBSCRIBE sent for it. */ +test("an advertised epoch reaches the route and the SUBSCRIBE", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true), epoch: true }); + const announced = subscriber.announced(); + await acceptSubscribeNamespace(pair.client); + + const epoch = Epoch.mint(); + await publishEpoch(pair, subscriber, Path.from("room"), epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "start", route: { epoch } }); + + const track = subscriber.consume(Path.from("room")).track("video").subscribe(); + onTestFinished(() => track.close()); + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no SUBSCRIBE stream"); + expect(await peer.reader.u53()).toBe(Subscribe.id); + expect((await Subscribe.decode(peer.reader, VERSION)).epoch).toBe(epoch); + announced.close(); +}); + +test("an inline NAMESPACE route carries its epoch", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true), epoch: true }); + const announced = subscriber.announced(); + const subscription = await acceptSubscribeNamespace(pair.client); + + const epoch = Epoch.mint(); + await inlineEpoch(subscription, Path.from("room"), epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "start", route: { epoch } }); + announced.close(); +}); + +/** + * A NAMESPACE names its instance until its NAMESPACE_DONE, so a repeat under another one + * means the peer skipped the withdrawal. + */ +test("a NAMESPACE repeated under another epoch closes the session", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber({ session, quic: pair.server, epoch: true }); + const warn = spyOn(console, "warn").mockImplementation(() => void 0); + onTestFinished(() => warn.mockRestore()); + const announced = subscriber.announced(); + const subscription = await acceptSubscribeNamespace(pair.client); + + const epoch = Epoch.mint(); + await inlineEpoch(subscription, Path.from("room"), epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + + // Control: a repeat under the same instance is a reprice, not a violation. + await inlineEpoch(subscription, Path.from("room"), epoch); + await inlineEpoch(subscription, Path.from("sentinel"), epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("sentinel"), kind: "start" }); + + await inlineEpoch(subscription, Path.from("room"), Epoch.mint()); + await violationClosed(pair); +}); + +/** + * Two PUBLISH_NAMESPACE requests travel on independent streams, so a restarted publisher's + * new advertisement can land before its old one's withdrawal. The newest stands throughout. + */ +test("a stale instance's withdrawal arriving last keeps the newer epoch", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true), epoch: true }); + const announced = subscriber.announced(); + await acceptSubscribeNamespace(pair.client); + + const path = Path.from("room"); + const first = Epoch.mint(); + const old = await publishEpoch(pair, subscriber, path, first); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: { epoch: first } }); + + const second = Epoch.mint(); + await publishEpoch(pair, subscriber, path, second); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "restart", route: { epoch: second } }); + + old.peer.close(); + await old.handler; + + const next = await Promise.race([ + announced.next(), + new Promise<"nothing">((resolve) => setTimeout(() => resolve("nothing"), 250)), + ]); + expect(next).toBe("nothing"); + + // A fresh reader hears the newer instance as the one standing. + const fresh = subscriber.announced(); + expect(await fresh.next()).toMatchObject({ prefix: path, kind: "start", route: { epoch: second } }); + fresh.close(); + announced.close(); +}); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 99dc5daa2a5..03313b2a534 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -6,6 +6,7 @@ import * as broadcast from "../broadcast.ts"; import type { Drain } from "../connection/goaway.ts"; import { BroadcastCache } from "../consume.ts"; import * as DatagramStream from "../datagram_stream.ts"; +import type * as Epoch from "../epoch.ts"; import { closeError, error, @@ -45,6 +46,7 @@ import { import { fromWire, toWire } from "./priority.ts"; import { type Publish, PublishDone, PublishDoneStatus, PublishError, publishDoneClean } from "./publish.ts"; import { + type AdvertParams, type PublishNamespace, PublishNamespaceCancel, PublishNamespaceDone, @@ -109,6 +111,9 @@ type SubscribeSetupState = { rejected?: boolean; }; +/** An announced path: each live advertisement referencing it, oldest first, and the route it holds. */ +type Announced = { adverts: { id: number; route: Route }[]; route: Route }; + /** A local announce reader's filter: its scope, the prefix it asked for, and its hidden opt-in. */ type Filter = { scope: Path.Pattern; prefix: Path.Valid; hidden: boolean }; @@ -136,6 +141,9 @@ export class Subscriber { // to us contains. #cluster?: Cluster.Hops; + // Whether both SETUPs offered MoQ Epoch, so advertisements may name their instance. + #epoch: boolean; + // Publisher-chosen aliases used by incoming group streams. #aliases = new TrackAliases(); @@ -152,15 +160,21 @@ export class Subscriber { // got past the duplicate check before either attached would both take one. #legacyRequests = new Set(); - // Every announced path, counted by how many live advertisements reference it. + // Every announced path, with the live advertisements that reference it. // // A peer may advertise one namespace twice on a session: an unsolicited // PUBLISH_NAMESPACE and an inline NAMESPACE answering our own SUBSCRIBE_NAMESPACE are // two messages about one source, which the MoQ Solicit draft requires us to tolerate. - // Counting them is what keeps the second from duplicating the announce and the first - // to end from retracting what the other still holds. Each path holds one of the - // session's announce slots, however many advertisements reference it. - #announced: SlotMap; + // Tracking each is what keeps the second from duplicating the announce and the first + // to end from retracting what the other still holds. A publisher replacing its instance + // (MoQ Epoch) withdraws one advertisement and makes another, on separate streams that + // can arrive in either order, so the newest stands until it goes and an update to an + // older one changes nothing. Each path holds one of the session's announce slots, + // however many advertisements reference it. + #announced: SlotMap; + + // Names each advertisement the peer makes, so a later update or withdrawal finds its own. + #nextAdvert = 0; // Any consumers that want each new announcement, keyed by their local filter. #announcedConsumers = new Map(); @@ -195,6 +209,7 @@ export class Subscriber { session, quic, cluster, + epoch = false, hidden = false, activeCount = false, solicit, @@ -208,6 +223,8 @@ export class Subscriber { quic?: WebTransport; /** The Hop IDs the SETUP exchange settled (MoQ Cluster). */ cluster?: Cluster.Hops; + /** Whether both SETUPs offered MoQ Epoch. */ + epoch?: boolean; /** Whether the peer understands the HIDDEN parameter (MoQ Hidden). */ hidden?: boolean; /** Whether both SETUPs declared MoQ Active Count. */ @@ -225,6 +242,7 @@ export class Subscriber { this.#quic = quic; this.#announced = new SlotMap(new Slots(limits.announces, { quic, reason: "too many announcements" })); this.#cluster = cluster; + this.#epoch = epoch; this.#hidden = hidden; this.#activeCount = activeCount; this.#solicit = solicit; @@ -252,7 +270,7 @@ export class Subscriber { // Reprice every live advertisement. Idempotent, since the signal stays set. #drainAnnounced(): void { for (const [path, info] of this.#announced) { - this.#updateAnnounce(path, info.route); + this.#settleAnnounce(path, info); } } @@ -274,10 +292,13 @@ export class Subscriber { return advert !== undefined && this.#cluster !== undefined && Cluster.loops(advert, this.#cluster.self); } - /** The route an advertisement carries; one without a path is anonymous and free. */ - #route(advert: Cluster.Advert | undefined): Route { - if (advert === undefined) return { hops: [UNKNOWN_HOP], cost: Cost.zero }; - return { hops: advert.hops, cost: advert.cost }; + /** + * The route an advertisement carries; one without a path is anonymous and free. Its + * epoch is taken as given, and absent when the advertisement names none. + */ + #route({ cluster, epoch }: AdvertParams): Route { + const route = cluster === undefined ? { hops: [UNKNOWN_HOP], cost: Cost.zero } : { ...cluster }; + return epoch === undefined ? route : { ...route, epoch }; } /** @@ -320,58 +341,74 @@ export class Subscriber { } /** - * Record one more advertisement for a path, telling consumers only when it is the - * first. A second one is the same namespace said twice, not news. + * Record one more advertisement for a path, returning the id that names it. Consumers + * hear `start` for the first; a later one stands as the newest (see `#settleAnnounce`). */ - #attachAnnounce(path: Path.Valid, route: Route) { - route = this.#priced(route); + #attachAnnounce(path: Path.Valid, route: Route): number { + const id = this.#nextAdvert++; const existing = this.#announced.get(path); if (existing) { - existing.count += 1; - // A second advertisement after GOAWAY still must not win selection. - if (this.#goingAway()) this.#updateAnnounce(path, existing.route); - return; + existing.adverts.push({ id, route }); + this.#settleAnnounce(path, existing); + return id; } - const entry = { count: 1, route }; + route = this.#priced(route); + const entry: Announced = { adverts: [{ id, route }], route }; this.#announced.set(path, entry); this.#consumes.announce(path, entry, route); - console.debug(`announced: broadcast=${path} active=true`); + console.debug(`announced: broadcast=${path} active=true epoch=${route.epoch}`); for (const [consumer, filter] of this.#announcedConsumers) { if (!sees(filter, path)) continue; const scope = filter.scope; consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind: "start", route }); } + return id; + } + + /** Replace the route of advertisement `id`, which moves the path only while it is the newest. */ + #updateAnnounce(path: Path.Valid, id: number, route: Route) { + const existing = this.#announced.get(path); + const advert = existing?.adverts.find((advert) => advert.id === id); + if (existing === undefined || advert === undefined) return; + advert.route = route; + this.#settleAnnounce(path, existing); } /** - * Replace the stored route for a path that is already announced. A no-op when the - * hops and cost did not change; otherwise consumers hear `update` so a forwarder - * can reprice without retracting. The path still names the same broadcast, whatever - * the first hop now says, so the shared consume stays. + * Route a path by its newest live advertisement. A no-op when that changed nothing. + * Otherwise consumers hear `update` for new hops or cost, so a forwarder can reprice + * without retracting and the shared consume stays, or `restart` for another publisher + * instance (MoQ Epoch), so the next consume subscribes afresh. */ - #updateAnnounce(path: Path.Valid, route: Route) { - route = this.#priced(route); - const existing = this.#announced.get(path); - if (existing === undefined || routesEqual(existing.route, route)) return; + #settleAnnounce(path: Path.Valid, existing: Announced) { + const newest = existing.adverts.at(-1); + if (newest === undefined) return; + const route = this.#priced(newest.route); + if (routesEqual(existing.route, route)) return; + const restart = existing.route.epoch !== route.epoch; existing.route = route; - this.#consumes.announce(path, existing, route); - console.debug(`announced: broadcast=${path} rerouted`); + this.#consumes.announce(path, existing, route, restart); + console.debug(`announced: broadcast=${path} ${restart ? `restart=true epoch=${route.epoch}` : "rerouted"}`); + const kind = restart ? "restart" : "update"; for (const [consumer, filter] of this.#announcedConsumers) { if (!sees(filter, path)) continue; const scope = filter.scope; - consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind: "update", route }); + consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind, route }); } } /** - * Drop one advertisement for a path, retracting it only once the last one goes. + * Drop advertisement `id` for a path, retracting it only once the last one goes. */ - #detachAnnounce(path: Path.Valid) { + #detachAnnounce(path: Path.Valid, id: number) { const existing = this.#announced.get(path); - if (existing === undefined) return; - if (existing.count > 1) { - existing.count -= 1; + const index = existing?.adverts.findIndex((advert) => advert.id === id) ?? -1; + if (existing === undefined || index === -1) return; + existing.adverts.splice(index, 1); + if (existing.adverts.length > 0) { + // The newest went while an older one stands: that one is what remains. + this.#settleAnnounce(path, existing); return; } @@ -428,9 +465,9 @@ export class Subscriber { return; } - // Suffixes live on this stream, so a repeat is recognized as an update to the - // advertisement rather than a second one, which would leak the count. - const live = new Set(); + // Suffixes live on this stream, with the advertisement each holds and the epoch it named, + // so a repeat is recognized as an update to it rather than a second one, which would leak. + const live = new Map(); // Set once the teardown below has given back everything this stream held. The read // loop is not awaited when the local consumer closes first, and closing the stream @@ -551,42 +588,54 @@ export class Subscriber { throw new ProtocolViolation(`message 0x${msgType.toString(16)} inside the initial set`); } if (msgType === SubscribeNamespaceEntry.id) { - const entry = await SubscribeNamespaceEntry.decode( - stream.reader, - version, - Cluster.negotiated(this.#cluster), - ); + const entry = await SubscribeNamespaceEntry.decode(stream.reader, version, { + cluster: Cluster.negotiated(this.#cluster), + epoch: this.#epoch, + }); // Counted even when discarded below. if (initial > 0) initial -= 1; if (released) break; const path = Path.join(prefix, entry.suffix); + const params = entry.params ?? {}; + const held = live.get(path); + + // The epoch names the advertisement's instance for as long as it + // stands: a replacement is a NAMESPACE_DONE and a fresh NAMESPACE, + // never a repeat. + if (held !== undefined && held.epoch !== params.epoch) { + throw new ProtocolViolation(`NAMESPACE repeated under another epoch: ${path}`); + } // A repeat updates the advertisement in place, so one that now // loops back through us has taken a route we can't subscribe // over: the path is gone even though the message says active. - if (this.#reflected(entry.cluster)) { + if (this.#reflected(params.cluster)) { console.debug(`dropping reflected namespace: broadcast=${path}`); - if (live.delete(path)) this.#detachAnnounce(path); + if (held !== undefined) { + live.delete(path); + this.#detachAnnounce(path, held.id); + } continue; } // A repeat replaces the advertisement in place: HOP_PATH / ROUTE_COST // can change without a NAMESPACE_DONE. Only the first is a new path. - const route = this.#route(entry.cluster); - if (live.has(path)) { - this.#updateAnnounce(path, route); + const route = this.#route(params); + if (held !== undefined) { + this.#updateAnnounce(path, held.id, route); } else { - this.#attachAnnounce(path, route); - live.add(path); + live.set(path, { id: this.#attachAnnounce(path, route), epoch: params.epoch }); } } else if (msgType === SubscribeNamespaceEntryDone.id) { const entry = await SubscribeNamespaceEntryDone.decode(stream.reader, version); if (released) break; const path = Path.join(prefix, entry.suffix); - if (live.delete(path)) { - this.#detachAnnounce(path); + const held = live.get(path); + if (held !== undefined) { + live.delete(path); + this.#detachAnnounce(path, held.id); } } else if (msgType === PublishBlocked.id && version === Version.DRAFT_17) { const blocked = await PublishBlocked.decode(stream.reader, version); @@ -636,8 +685,8 @@ export class Subscriber { // each namespace keeps its count and the source never detaches, which would // pin the path for the session even after the other source withdrew. released = true; - for (const path of live) { - this.#detachAnnounce(path); + for (const [path, held] of live) { + this.#detachAnnounce(path, held.id); } live.clear(); } @@ -662,7 +711,9 @@ export class Subscriber { for (;;) { const request = await wireOf(consumer).requested(); if (!request) break; - void this.#runSubscribe(path, request, instance.validity?.signal); + // Every request names the instance the consume resolved, so the peer refuses + // rather than answers from another. + void this.#runSubscribe(path, request, instance.validity?.signal, instance.route.epoch); } })(); return this.#consumes.insert(path, instance, consumer); @@ -680,7 +731,7 @@ export class Subscriber { ]); } - async #runSubscribe(broadcast: Path.Valid, request: track.Request, valid?: AbortSignal) { + async #runSubscribe(broadcast: Path.Valid, request: track.Request, valid?: AbortSignal, epoch?: Epoch.Valid) { const refused = unauthorized(broadcast); if (this.#denied(broadcast)) { request.reject(refused); @@ -715,7 +766,7 @@ export class Subscriber { // and any registration if setup eventually finishes. const state: SubscribeSetupState = {}; const deadline = new Deadline(); - const setup = this.#openSubscribe(state, broadcast, request, subscription, requestId, deadline); + const setup = this.#openSubscribe(state, broadcast, request, subscription, requestId, deadline, epoch); // The publisher can be serving before it answers, so waiting only on the response // would miss the local side going away and leave it serving a track nobody reads. @@ -933,6 +984,7 @@ export class Subscriber { subscription: Subscription, requestId: bigint, deadline: Deadline, + epoch: Epoch.Valid | undefined, ): Promise<{ stream: Stream; alias: bigint }> { const version = this.#session.version; @@ -966,6 +1018,7 @@ export class Subscriber { // object, and that mid-group stream is dropped, degrading the join to the next // group boundary. filter: joinFilter(version), + epoch, }); await msg.encode(state.stream.writer, version); state.sent = true; @@ -1017,7 +1070,7 @@ export class Subscriber { } try { - this.#aliases.set(ok.trackAlias, subscription, { broadcast, name: request.name }); + this.#aliases.set(ok.trackAlias, subscription, { broadcast, name: request.name, epoch }); const timescale = ok.properties.timescale; if (timescale !== undefined) { this.#timescales.set(ok.trackAlias, timescale); @@ -1050,7 +1103,7 @@ export class Subscriber { // A path that already ran through us looped back. Refuse it rather than holding an // advertisement we could never subscribe through. The peer knows our Hop ID, so a // conforming one never offers it; 0 as the retry interval says not to come back. - if (this.#reflected(msg.cluster)) { + if (this.#reflected(msg.params.cluster)) { console.debug(`dropping reflected publish_namespace: broadcast=${path}`); await stream.writer.u53(RequestError.id); await new RequestError({ @@ -1094,11 +1147,13 @@ export class Subscriber { } // Everywhere else a path this session already knows is not refused: the same - // namespace can reach us twice, and the count is what tells the second apart from - // news. This request owns exactly one of those references and gives it back when - // the stream ends. + // namespace can reach us twice, and each advertisement is tracked apart from news. + // This request owns exactly one of those references, named by its id while + // attached, and gives it back when the stream ends. if (legacy) this.#legacyRequests.add(path); - let attached = false; + let attached: number | undefined; + // Fixed for the advertisement's life: no REQUEST_UPDATE carries one. + const epoch = msg.params.epoch; try { // Send OK first. This must complete before notifying consumers, @@ -1118,14 +1173,13 @@ export class Subscriber { // Only now is the advertisement ours to announce, for the reason above: a // consumer reacting with a SUBSCRIBE must not interleave with that OK. - this.#attachAnnounce(path, this.#route(msg.cluster)); - attached = true; + attached = this.#attachAnnounce(path, this.#route(msg.params)); // An advertisement is updated in place with REQUEST_UPDATE on the stream that // already carries it, so read until the stream ends rather than waiting on the // close. Nothing else would deliver a re-parented route. What the peer holds // is kept current, since an update carries only what changed. - let held = msg.cluster; + let held = msg.params.cluster; const done = version === Version.DRAFT_16 || legacy; const stopped = !done ? stream.writer.closed.then( @@ -1217,17 +1271,16 @@ export class Subscriber { // advertisement's only channel, so a later clean path arrives here or // nowhere. if (this.#reflected(held)) { - if (attached) { - attached = false; + if (attached !== undefined) { console.debug(`publish_namespace now loops back, detaching: broadcast=${path}`); - this.#detachAnnounce(path); + this.#detachAnnounce(path, attached); + attached = undefined; } - } else if (!attached) { + } else if (attached === undefined) { // Re-attach: a clean path replaced the reflected one we detached from. - attached = true; - this.#attachAnnounce(path, this.#route(held)); + attached = this.#attachAnnounce(path, this.#route({ cluster: held, epoch })); } else { - this.#updateAnnounce(path, this.#route(held)); + this.#updateAnnounce(path, attached, this.#route({ cluster: held, epoch })); } // Nothing here can fail to apply, so every update is acknowledged. A leaf @@ -1241,8 +1294,8 @@ export class Subscriber { // Give back exactly what was taken: a request that never got its OK out never // referenced the path, and retracting there would drop someone else's count. - if (attached) { - this.#detachAnnounce(path); + if (attached !== undefined) { + this.#detachAnnounce(path, attached); } } } diff --git a/js/net/src/ietf/track.ts b/js/net/src/ietf/track.ts index 779c2551021..0b2ec1267fe 100644 --- a/js/net/src/ietf/track.ts +++ b/js/net/src/ietf/track.ts @@ -1,5 +1,7 @@ +import type * as Epoch from "../epoch.ts"; import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; +import { supported as epochSupported } from "./epoch.ts"; import * as Filter from "./filter.ts"; import * as Message from "./message.ts"; import * as Namespace from "./namespace.ts"; @@ -23,17 +25,27 @@ export class TrackStatusRequest { trackName: string; /** Whether the requester wants Track Properties on the answer (INCLUDE_PROPERTIES, draft-20). */ propertiesWanted: boolean; + /** The publisher instance the requester expects (EPOCH, MoQ Epoch, draft-17+). */ + epoch?: Epoch.Valid; constructor({ requestId, trackNamespace, trackName, propertiesWanted = true, - }: { requestId: bigint; trackNamespace: Path.Valid; trackName: string; propertiesWanted?: boolean }) { + epoch, + }: { + requestId: bigint; + trackNamespace: Path.Valid; + trackName: string; + propertiesWanted?: boolean; + epoch?: Epoch.Valid; + }) { this.requestId = requestId; this.trackNamespace = trackNamespace; this.trackName = trackName; this.propertiesWanted = propertiesWanted; + this.epoch = epoch; } async #encode(w: Writer, version: IetfVersion): Promise { @@ -55,6 +67,7 @@ export class TrackStatusRequest { // read INCLUDE_PROPERTIES as unknown, which is a protocol violation. const params = new Parameters(); if (!this.propertiesWanted && Filter.isDraft20(version)) params.includeProperties = false; + if (epochSupported(version)) params.epoch = this.epoch; await params.encode(w, version); } } @@ -69,8 +82,8 @@ export class TrackStatusRequest { * subscription for it to configure. */ static async decode(r: Reader, version: IetfVersion): Promise { - const { requestId, trackNamespace, trackName, propertiesWanted } = await Subscribe.decode(r, version); - return new TrackStatusRequest({ requestId, trackNamespace, trackName, propertiesWanted }); + const { requestId, trackNamespace, trackName, propertiesWanted, epoch } = await Subscribe.decode(r, version); + return new TrackStatusRequest({ requestId, trackNamespace, trackName, propertiesWanted, epoch }); } } diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 93883bdba61..fc5dbe82abd 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -30,7 +30,7 @@ unchanged paths and End+Start on replacement. The relay retains the explicit identity internally; fresh requests cannot join its old cached instance. This does not promise cache invalidation in arbitrary older IETF relays or clients that retain objects across broadcasts. The negotiated -[IETF extension](/quest/m1/ietf-epochs.md) follows in m1, independently of +[IETF extension](/drafts/draft-lcurley-moq-epoch.md) landed in m1, independently of this release gate; seamless JS handover stays in m1 too. Non-goals: pooling, which needs nothing here; a redundant pair shares an diff --git a/quest/m0/broadcast-epoch/catalog-references.md b/quest/m0/broadcast-epoch/catalog-references.md index 4e6a259a6da..a62a6081e51 100644 --- a/quest/m0/broadcast-epoch/catalog-references.md +++ b/quest/m0/broadcast-epoch/catalog-references.md @@ -91,4 +91,4 @@ guarantee and the selected legacy best-effort behavior. - [JS consume identity](https://github.com/moq-dev/moq/pull/5254) - JS resolves the actual serving identity - [Retired requests](https://github.com/moq-dev/moq/pull/5294) - held handles cannot emit unpinned requests after retirement - [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - the same for the Rust publishers -- [IETF epochs](/quest/m1/ietf-epochs.md) - verified catalog identity over negotiated IETF sessions +- [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md) - verified catalog identity over negotiated IETF sessions diff --git a/quest/m1/README.md b/quest/m1/README.md index 5175484ae10..c30147e501c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -82,7 +82,6 @@ lands before the cut. - [One hang catalog consumer](/quest/m1/catalog-consumer-fold.md) - `moq-mux` reads hang catalogs through `hang`'s consumer - [Broadcast archives](/quest/m1/archive/README.md) - SUBSCRIBE_ALL records every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish -- [IETF epochs](/quest/m1/ietf-epochs.md) - negotiate explicit broadcast identity on drafts 17-22, retaining unchanged paths and epochless clients on updated relays - [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire - [IETF takeover](/quest/m1/ietf-takeover.md) - carry the shared takeover contract through the negotiated IETF epoch extension - [Identity and recovery guide](/quest/m1/identity-guide.md) - explain pinned catalogs, lazy jobs, takeover, restart and version compatibility diff --git a/quest/m1/claim-answer-epochs.md b/quest/m1/claim-answer-epochs.md index 59ad093c5a8..955cc00bf00 100644 --- a/quest/m1/claim-answer-epochs.md +++ b/quest/m1/claim-answer-epochs.md @@ -86,7 +86,7 @@ and behind an edge relay of ours, on lite-05, 06, 07 and moq-transport 14, group, and sibling paths keep their readers. On the wires without an epoch that rests on our relays retiring a copy on End then Start, as `tests/integration/restart.rs` shows; arbitrary older caching relays are out of scope, as -in [IETF epochs](/quest/m1/ietf-epochs.md), since base IETF object identity +in [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md), since base IETF object identity survives a withdrawal. A same-epoch lagging replica still resumes, checked on lite-07 only, the one wire here that carries the epoch. JS mirrors the tests. `just test interop --all`. @@ -105,5 +105,5 @@ the broader C API still waits for the generated replacement. ## Related - [Announcement takeover](/quest/m1/announce-takeover.md) - its claim-to-route operation is `Request::prepare` then `publish`; TAKEOVER then removes the cold-start reset -- [IETF epochs](/quest/m1/ietf-epochs.md) - carries the answer epoch over moq-transport, so same-epoch resume and replacement can be told apart there +- [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md) - carries the answer epoch over moq-transport, so same-epoch resume and replacement can be told apart there - [#5057](https://github.com/moq-dev/moq/pull/5057) - the relay-side check this replaces diff --git a/quest/m1/ietf-epochs.md b/quest/m1/ietf-epochs.md deleted file mode 100644 index a59017af587..00000000000 --- a/quest/m1/ietf-epochs.md +++ /dev/null @@ -1,84 +0,0 @@ -# [L] Negotiate broadcast epochs on IETF connections - -## Goal - -Rust and JS carry broadcast epochs over a negotiated moq-transport extension -on drafts 17 through 22 without changing the broadcast path. Matching -explicit epochs permit stitching; a different epoch or a different -epochless source is a new broadcast. Epochless clients remain supported on -updated relays. - -## Plan - -Decided 2026-10-10 in the epoch audit interview: - -- This is m1, after the m0 identity correctness fixes. Do not make the - extension or seamless JS handover a release blocker. -- Preserve the path. The previous `@` suffix changed the name older - clients subscribe to; rejected in favor of negotiated metadata. -- Use a standalone SETUP-negotiated extension on drafts 17-22, where the - existing extension infrastructure applies, rather than draft 22 only. - Drafts 14-16 and peers that do not negotiate it retain their existing wire. - Integrate with the shared extension configuration in Rust and JS instead - of inventing another configuration mechanism. -- Reuse lite-07's epoch representation and identity semantics. A relay - preserves an explicit epoch, never invents continuity for an epochless - source, and refuses malformed or mismatched identities. -- Carry identity through announcements and the requests that resolve, - subscribe to, or fetch a broadcast. Pin a request to its chosen instance; - a replacement must not substitute new content into an old request. - Separate object and negative caches by identity, including joining FETCH - and concurrent old/new subscriptions. Track aliases and response handling - must preserve that separation too. This changes identity semantics, not - merely advisory announcement metadata. -- Epoch and cluster extensions negotiate independently. The cluster draft - already describes a shared negotiated NAMESPACE parameter block; make its - framing unambiguous with either extension, both, or neither. Reconcile its - namespace-only redundant-publisher semantics with explicit epoch opt-in. -- Support epochless clients on updated relays: preserve their paths and - wire framing, translate replacements into withdrawal and reannouncement, - and resolve fresh subscriptions to the current instance. Keep the relay's - internal epoch and caches separated. A same-epoch upstream route handoff - may remain invisible downstream. Existing subscriptions stay sticky; - announcement-aware players reset and resubscribe on End+Start. A player - that ignores these signals is not promised automatic recovery. -- Arbitrary older caching relays are out of scope. Base IETF object identity - is namespace, track, group, and object ID, and withdrawal does not invalidate - it. Do not claim that removing the epoch makes reused object names safe - through those relays or through clients retaining caches across broadcasts. - Immutable wire names plus discovery/translation would be separate work. -- Independent announcement takeover is a separate follow-up, sharing the - lite-07 model. An epoch-bound request requires a matching advertised epoch; - response metadata alone cannot make an epochless claim eligible. Do not - block this base extension on takeover. - -Add a feature-specific IETF extension draft in the implementation PR, with -negotiation, identity, cache, request, downgrade, and malformed-input rules. -Update the cluster draft and existing identity/compatibility concept docs -inline. The dedicated [identity guide](/quest/m1/identity-guide.md) follows -separately and does not replace those updates. The new draft must distinguish -our legacy-client behavior from base IETF's immutable-name guarantee; an -End+Start is not a general cache invalidation mechanism. - -Verify Rust and JS with matching, different, and absent epochs; exact and -covering announcements; old subscriptions held across replacement; stale -SUBSCRIBE/FETCH refusals; and no stale catalog or media on new requests. -Exercise both directions across drafts 17-22, mixed lite-07/IETF relay -chains, and epochless clients. Cover independent epoch/cluster negotiation, -declining the extension on either side, and unchanged legacy framing. -Tests belong in existing CI lanes. Run `just check`, `just drafts check`, -and `just test interop --all`; benchmark any changed routing/cache fanout. - -Public API: expose negotiation through the existing extension configuration -and reuse the epoch model in Rust and JS. Wire: an opt-in IETF identity -extension; no changes to unnegotiated published versions or broadcast paths. - -## Related - -- [#5106](https://github.com/moq-dev/moq/pull/5106) - landed the common configuration for offering extensions -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - current lite-07 identity and legacy restart behavior -- [Announcement takeover](/quest/m1/announce-takeover.md) - shared continuity model and lite-07 operation -- [IETF takeover](/quest/m1/ietf-takeover.md) - independently advertised continuation of a claim-served instance -- [JS track handover](/quest/m1/js-group-handover.md) - stable JS readers across same-epoch route changes -- [Catalog references](/quest/m0/broadcast-epoch/catalog-references.md) - optional requested epochs become verifiable on this negotiated transport; epochless fallback remains best effort -- [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native wait-budget support is separate from epoch negotiation and adds no age extension diff --git a/quest/m1/ietf-takeover.md b/quest/m1/ietf-takeover.md index d5e3c475653..725a62b608b 100644 --- a/quest/m1/ietf-takeover.md +++ b/quest/m1/ietf-takeover.md @@ -38,5 +38,4 @@ IETF takeover support only; paths and unnegotiated versions stay unchanged. ## Required -- [IETF epochs](/quest/m1/ietf-epochs.md) - negotiated announcement/request identity - [Announcement takeover](/quest/m1/announce-takeover.md) - shared semantics, model and lite-07 proof diff --git a/quest/m3/ietf-cluster-peers.md b/quest/m3/ietf-cluster-peers.md index 8a79f824d2c..c7d8088b4cd 100644 --- a/quest/m3/ietf-cluster-peers.md +++ b/quest/m3/ietf-cluster-peers.md @@ -24,4 +24,3 @@ Wire: extends `draft-lcurley-moq-cluster`, updated in the same PR. ## Required - [Cluster routing](/quest/m1/cluster-routing/README.md) - settles what a cluster link carries -- [IETF epochs](/quest/m1/ietf-epochs.md) - explicit identity for the seamless-resume guarantee diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index be45262c4c6..f09355199e6 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -647,6 +647,7 @@ impl Default for Messages { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }, // Draft-17+ carries the request id in the control message framing instead. ietf_ok: ietf::SubscribeOk { @@ -972,6 +973,7 @@ pub fn seeds() -> Vec { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; fetch.encode_bytes(*version).ok() }) else { diff --git a/rs/moq-net/src/ietf/adapter.rs b/rs/moq-net/src/ietf/adapter.rs index 2bf51eac65b..30aa757bddc 100644 --- a/rs/moq-net/src/ietf/adapter.rs +++ b/rs/moq-net/src/ietf/adapter.rs @@ -1597,7 +1597,7 @@ mod tests { ietf::PublishNamespace { request_id, track_namespace: crate::Path::new(namespace), - cluster: None, + params: Default::default(), authorization_token: None, } } diff --git a/rs/moq-net/src/ietf/epoch.rs b/rs/moq-net/src/ietf/epoch.rs new file mode 100644 index 00000000000..d3083e8d848 --- /dev/null +++ b/rs/moq-net/src/ietf/epoch.rs @@ -0,0 +1,109 @@ +//! The MoQ Epoch extension (draft-lcurley-moq-epoch-00). +//! +//! moq-transport names content by namespace alone, so a publisher that restarts at the +//! same namespace looks like the same broadcast to every relay. This extension carries +//! the publisher instance, the [`crate::Epoch`] moq-lite 07 puts on its routes and +//! requests, as an EPOCH parameter: on each advertisement (PUBLISH_NAMESPACE and +//! NAMESPACE), and on each request that resolves one (SUBSCRIBE, FETCH, and +//! TRACK_STATUS). A namespace and an EPOCH name one broadcast; a request carrying one +//! is refused rather than served by another instance. +//! +//! Negotiated on draft-17+ only, where SETUP is a Key-Value-Pair block, and only when +//! both endpoints declare the option. + +use crate::Epoch; +use crate::coding::{DecodeError, Decoder, EncodeError, Encoder}; + +use super::{Param, Version}; + +/// EPOCH Setup Option: the sender understands the EPOCH parameter. Even, so the value +/// is a bare varint. +pub const EPOCH: u64 = 0x40B68; + +/// EPOCH message parameter: the publisher instance, as a UUIDv7's 16 bytes. Odd, so the +/// value is length-prefixed. +pub const EPOCH_PARAM: u64 = 0x40B69; + +/// Whether a version negotiates this extension: draft-17+, like MoQ Cluster. +pub fn supported(version: Version) -> bool { + !matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) +} + +/// Whether the peer declared the option. +pub fn from_setup(params: &super::Parameters, version: Version) -> bool { + supported(version) && params.get_varint(super::ParameterVarInt::Epoch).is_some() +} + +/// Declare that we understand the EPOCH parameter. +pub fn into_setup(params: &mut super::Parameters, version: Version) { + if supported(version) { + params.set_varint(super::ParameterVarInt::Epoch, 1); + } +} + +impl Param for Epoch { + fn param_encode(&self, w: &mut Encoder<'_>, _version: Version) -> Result<(), EncodeError> { + w.bytes(&self.to_bytes()) + } + + /// Anything but a UUIDv7's 16 bytes is malformed. + fn param_decode(r: &mut Decoder<'_>, _version: Version) -> Result { + Epoch::from_bytes(r.bytes()?).map_err(|_| DecodeError::InvalidValue) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const VERSION: Version = Version::Draft19; + + #[test] + fn code_points() { + // The parity is load-bearing: odd values are length-prefixed, even ones bare varints. + assert_eq!(EPOCH, 0x40B68); + assert_eq!(EPOCH_PARAM, 0x40B69); + assert_eq!(EPOCH % 2, 0); + assert_eq!(EPOCH_PARAM % 2, 1); + } + + #[test] + fn only_draft17_and_later_negotiate() { + for version in [Version::Draft14, Version::Draft16, Version::Draft17, Version::Draft22] { + let mut params = super::super::Parameters::default(); + assert!(!from_setup(¶ms, version)); + into_setup(&mut params, version); + assert_eq!(from_setup(¶ms, version), supported(version), "{version:?}"); + } + } + + #[test] + fn round_trips_and_refuses_anything_but_a_uuidv7() { + let epoch = Epoch::mint(); + let mut buf = Vec::new(); + epoch + .param_encode(&mut Encoder::new(&mut buf, VERSION.into()), VERSION) + .unwrap(); + assert_eq!(buf.len(), 17, "a length byte, then the 16 bytes"); + let mut bytes = bytes::Bytes::from(buf); + let decoded = crate::coding::decode_buf(&mut bytes, VERSION, Epoch::param_decode).unwrap(); + assert_eq!(decoded, epoch); + + for value in [ + Vec::new(), + epoch.to_bytes()[..15].to_vec(), + uuid::Builder::from_random_bytes([7; 16]) + .into_uuid() + .as_bytes() + .to_vec(), + ] { + let mut buf = Vec::new(); + Encoder::new(&mut buf, VERSION.into()).bytes(&value).unwrap(); + let mut bytes = bytes::Bytes::from(buf); + assert!( + crate::coding::decode_buf(&mut bytes, VERSION, Epoch::param_decode).is_err(), + "{value:?}" + ); + } + } +} diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index 9c54c7591e8..aff3d5cb227 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -11,6 +11,7 @@ use crate::{ }; use super::Message; +use super::epoch; use super::Version; @@ -136,6 +137,9 @@ pub struct Fetch<'a> { /// Whether the requester wants Track Properties in FETCH_OK (INCLUDE_PROPERTIES, /// draft-20+). Always `true` before draft-20, which has no way to opt out. pub properties_wanted: bool, + /// The publisher instance the requester expects (MoQ Epoch, draft-17+). Only on a + /// request that names its track: a joining FETCH takes its subscription's. + pub epoch: Option, } impl Message for Fetch<'_> { @@ -160,9 +164,11 @@ impl Message for Fetch<'_> { } Version::Draft15 | Version::Draft16 | Version::Draft17 | Version::Draft18 | Version::Draft19 => { self.fetch_type.encode(w, version)?; + let epoch = self.epoch.clone().filter(|_| epoch::supported(version)); encode_params!(w, version, 0x20 => self.subscriber_priority, 0x22 => group_order, + epoch::EPOCH_PARAM => epoch, ); } _ => { @@ -184,6 +190,7 @@ impl Message for Fetch<'_> { 0x21 => *filter, 0x22 => group_order, 0x35 => include_properties, + epoch::EPOCH_PARAM => self.epoch.clone(), ); } } @@ -197,7 +204,7 @@ impl Message for Fetch<'_> { } // The token decodes but grants nothing: the session's grant is what authorizes the request. - let (fetch_type, subscriber_priority, group_order, range_filters, fill_timeout, properties_wanted) = + let (fetch_type, subscriber_priority, group_order, range_filters, fill_timeout, properties_wanted, epoch) = match version { Version::Draft14 => { let subscriber_priority = buf.u8()?; @@ -211,6 +218,7 @@ impl Message for Fetch<'_> { false, false, true, + None, ) } Version::Draft15 | Version::Draft16 | Version::Draft17 | Version::Draft18 | Version::Draft19 => { @@ -224,6 +232,7 @@ impl Message for Fetch<'_> { 0x26 => object_id_filter: Vec where has_range_filters(version), 0x27 => priority_filter: Vec where has_range_filters(version), 0x28 => object_property_filter: Vec where has_range_filters(version), + epoch::EPOCH_PARAM => epoch: Option where epoch::supported(version), ); super::token::single(authorization_token)?; let range_filters = [ @@ -242,6 +251,7 @@ impl Message for Fetch<'_> { range_filters, fill_timeout.is_some(), true, + epoch, ) } // Draft-20 names the track up front and moves the range into LOCATION_FILTER. @@ -259,6 +269,7 @@ impl Message for Fetch<'_> { 0x27 => priority_filter: Vec, 0x28 => object_property_filter: Vec, 0x35 => include_properties: Option, + epoch::EPOCH_PARAM => epoch: Option, ); super::token::single(authorization_token)?; let range_filters = [ @@ -284,10 +295,20 @@ impl Message for Fetch<'_> { fill_timeout.is_some(), // Defaults to 1, so an absent parameter means the requester wants them. include_properties.unwrap_or(true), + epoch, ) } }; + // A joining FETCH is served by its subscription's instance; naming one is malformed. + if epoch.is_some() + && matches!( + fetch_type, + FetchType::RelativeJoining { .. } | FetchType::AbsoluteJoining { .. } + ) { + return Err(DecodeError::InvalidValue); + } + Ok(Self { request_id, subscriber_priority: subscriber_priority.unwrap_or(128), @@ -297,6 +318,7 @@ impl Message for Fetch<'_> { range_filters, fill_timeout, properties_wanted, + epoch, }) } } @@ -699,6 +721,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -723,6 +746,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft15); @@ -765,6 +789,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft16); @@ -789,6 +814,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft17); @@ -867,6 +893,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft18); @@ -991,6 +1018,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }; #[rustfmt::skip] diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index 47abf6a4bd8..45d57db99f9 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -17,6 +17,7 @@ pub mod cluster; #[cfg(feature = "async")] mod control; mod datagram; +pub(crate) mod epoch; pub(crate) mod error; mod fetch; mod filter; diff --git a/rs/moq-net/src/ietf/parameters.rs b/rs/moq-net/src/ietf/parameters.rs index 500395eb8d3..fcbfba381fa 100644 --- a/rs/moq-net/src/ietf/parameters.rs +++ b/rs/moq-net/src/ietf/parameters.rs @@ -31,6 +31,8 @@ pub enum ParameterVarInt { Auth = super::auth::AUTH, /// ACTIVE_COUNT, from the MoQ Active Count extension. ActiveCount = super::active_count::ACTIVE_COUNT, + /// EPOCH, from the MoQ Epoch extension. + Epoch = super::epoch::EPOCH, #[num_enum(catch_all)] Unknown(u64), } diff --git a/rs/moq-net/src/ietf/peer.rs b/rs/moq-net/src/ietf/peer.rs index 3f0e920789c..f580642b375 100644 --- a/rs/moq-net/src/ietf/peer.rs +++ b/rs/moq-net/src/ietf/peer.rs @@ -26,6 +26,10 @@ pub(crate) struct Peer { /// MoQ Active Count: whether the REQUEST_OK answering SUBSCRIBE_NAMESPACE counts the /// NAMESPACE messages before the subscription is synced, in both directions. pub active_count: bool, + + /// MoQ Epoch: whether both sides offered it, so advertisements and requests carry the + /// publisher's epoch in both directions. + pub epoch: bool, } /// Shared slot for [`Peer`], filled when the peer's SETUP is read. @@ -35,9 +39,21 @@ pub(crate) struct Peer { /// Solicit), so nothing can go out until it arrives. Cheap to clone; every handle /// shares the same slot. #[derive(Clone, Default)] -pub(crate) struct PeerSetup(kio::Shared>); +pub(crate) struct PeerSetup { + slot: kio::Shared>, + /// What we offered, which an extension negotiated by both sides needs as well. + declined_epoch: bool, +} impl PeerSetup { + /// A slot for a session that offered `offered`. + pub fn new(offered: crate::setup::Extensions) -> Self { + Self { + slot: Default::default(), + declined_epoch: !offered.epoch, + } + } + /// Record what the peer declared. A SETUP carrying no options records the default /// (no extension negotiated, no requirements), which is what unblocks a waiter. /// @@ -45,8 +61,9 @@ impl PeerSetup { /// lifetime while subscription serving re-reads it, so letting a later SETUP /// overwrite the identity would advertise under one exclusion and serve under /// another, which is how a routing loop gets back in. - pub fn set(&self, peer: Peer) { - let mut slot = self.0.lock(); + pub fn set(&self, mut peer: Peer) { + peer.epoch &= !self.declined_epoch; + let mut slot = self.slot.lock(); if slot.is_none() { *slot = Some(peer); } @@ -60,7 +77,7 @@ impl PeerSetup { #[cfg(feature = "async")] pub async fn get(&self) -> Peer { let slot = self - .0 + .slot .wait(|peer| match peer.is_some() { true => std::task::Poll::Ready(()), false => std::task::Poll::Pending, @@ -88,6 +105,7 @@ mod tests { hidden: false, auth: false, active_count: false, + epoch: false, }; let slot = PeerSetup::default(); @@ -101,8 +119,29 @@ mod tests { hidden: true, auth: true, active_count: true, + epoch: true, }); assert_eq!(slot.get().await, first); } + + /// MoQ Epoch needs both sides: a peer declaring it to a side that declined leaves it off. + #[moq_clock::test] + async fn epoch_needs_our_offer_too() { + let declared = Peer { + epoch: true, + ..Default::default() + }; + + let offered = PeerSetup::new(crate::setup::Extensions::default()); + offered.set(declared); + assert!(offered.get().await.epoch); + + let declined = PeerSetup::new(crate::setup::Extensions { + epoch: false, + ..Default::default() + }); + declined.set(declared); + assert!(!declined.get().await.epoch); + } } diff --git a/rs/moq-net/src/ietf/publish_namespace.rs b/rs/moq-net/src/ietf/publish_namespace.rs index a4e69cec6d9..d0e6ffa3996 100644 --- a/rs/moq-net/src/ietf/publish_namespace.rs +++ b/rs/moq-net/src/ietf/publish_namespace.rs @@ -2,15 +2,44 @@ use std::borrow::Cow; -use crate::{Path, coding::*, ietf::RequestId}; +use crate::{Epoch, Path, coding::*, ietf::RequestId}; use super::Message; -use super::cluster; use super::namespace::{decode_namespace, encode_namespace}; use super::token::RequestToken; +use super::{cluster, epoch}; use super::Version; +/// Which advertisement extensions a session negotiated: what its PUBLISH_NAMESPACE and +/// NAMESPACE messages carry. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct Negotiated { + /// MoQ Cluster: every advertisement carries HOP_PATH, and may carry ROUTE_COST. + pub cluster: bool, + /// MoQ Epoch: an advertisement may carry EPOCH. + pub epoch: bool, +} + +impl Negotiated { + /// Whether NAMESPACE takes the extended form, with a Parameters field. + pub fn extended(&self) -> bool { + self.cluster || self.epoch + } +} + +/// The extension parameters one advertisement carries. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct AdvertParams { + /// The MoQ Cluster parameters (see [`cluster`]). `Some` exactly on a session that + /// negotiated the extension. + pub cluster: Option, + + /// The MoQ Epoch parameter: the publisher instance the route serves, if it names one. + /// Only on a session that negotiated the extension. + pub epoch: Option, +} + /// PublishNamespace message (0x06) /// Sent by the publisher to announce the availability of a namespace. #[derive(Clone, Debug)] @@ -18,10 +47,8 @@ pub struct PublishNamespace<'a> { pub request_id: RequestId, pub track_namespace: Path<'a>, - /// The MoQ Cluster parameters (see [`cluster`]). `Some` on a session that - /// negotiated the extension and `None` on one that did not, which is what decides - /// whether they appear on the wire at all. - pub cluster: Option, + /// The extension parameters, which a session that negotiated none leaves empty. + pub params: AdvertParams, /// The `AUTHORIZATION TOKEN` (0x03) this request presents. At most one is /// accepted: decoding refuses a repeated or second token. @@ -29,13 +56,14 @@ pub struct PublishNamespace<'a> { } impl PublishNamespace<'_> { - /// Decode the message body, expecting the cluster parameters when the session - /// negotiated the extension. + /// Decode the message body, expecting the parameters of the extensions the session + /// negotiated. /// /// The negotiation is session state rather than anything in the message, so the - /// caller supplies it. A negotiated session that omits HOP_PATH is a protocol - /// violation, which surfaces here as [`DecodeError::InvalidValue`]. - pub fn decode_body(r: &mut Decoder<'_>, version: Version, negotiated: bool) -> Result { + /// caller supplies it. A negotiated cluster session that omits HOP_PATH, or a + /// parameter of an extension the session did not negotiate, is a protocol violation, + /// which surfaces here as [`DecodeError::InvalidValue`]. + pub fn decode_body(r: &mut Decoder<'_>, version: Version, negotiated: Negotiated) -> Result { let request_id = RequestId::decode(r, version)?; if version == Version::Draft17 { let _required_request_id_delta = r.varint()?; @@ -46,16 +74,11 @@ impl PublishNamespace<'_> { 0x03 => authorization_token: Vec, cluster::HOP_PATH => hops: Option, cluster::ROUTE_COST => cost: Option, + epoch::EPOCH_PARAM => epoch: Option where negotiated.epoch, ); - let cluster = match negotiated { - true => Some(cluster::Advert { - hops: hops.ok_or(DecodeError::InvalidValue)?, - cost: cost.unwrap_or(0), - }), - // An endpoint must not append these on a session that did not negotiate the - // extension, so either is a violation. - false if hops.is_some() || cost.is_some() => return Err(DecodeError::InvalidValue), - false => None, + let params = AdvertParams { + cluster: cluster_params(negotiated.cluster, hops, cost)?, + epoch, }; // Last, so a malformed field closes the session before a token refusal. let authorization_token = super::token::single(authorization_token)?; @@ -63,7 +86,7 @@ impl PublishNamespace<'_> { Ok(Self { request_id, track_namespace, - cluster, + params, authorization_token, }) } @@ -79,8 +102,9 @@ impl Message for PublishNamespace<'_> { } encode_namespace(w, &self.track_namespace)?; // ROUTE_COST is optional and absent means 0, so a free path sends nothing. - let hops = self.cluster.as_ref().map(|advert| advert.hops.clone()); + let hops = self.params.cluster.as_ref().map(|advert| advert.hops.clone()); let cost = self + .params .cluster .as_ref() .and_then(|advert| (advert.cost != 0).then_some(advert.cost)); @@ -88,12 +112,32 @@ impl Message for PublishNamespace<'_> { 0x03 => self.authorization_token.clone(), cluster::HOP_PATH => hops, cluster::ROUTE_COST => cost, + epoch::EPOCH_PARAM => self.params.epoch.clone(), ); Ok(()) } fn decode_msg(r: &mut Decoder<'_>, version: Version) -> Result { - Self::decode_body(r, version, false) + Self::decode_body(r, version, Negotiated::default()) + } +} + +/// The MoQ Cluster parameters of an advertisement, given what arrived. +/// +/// A negotiated session requires HOP_PATH, and ROUTE_COST absent means 0. An endpoint +/// must not send either on a session that did not negotiate, so either is a violation. +fn cluster_params( + negotiated: bool, + hops: Option, + cost: Option, +) -> Result, DecodeError> { + match negotiated { + true => Ok(Some(cluster::Advert { + hops: hops.ok_or(DecodeError::InvalidValue)?, + cost: cost.unwrap_or(0), + })), + false if hops.is_some() || cost.is_some() => Err(DecodeError::InvalidValue), + false => Ok(None), } } @@ -193,39 +237,42 @@ impl Message for PublishNamespaceUpdate { } } -/// Write the Parameters field of an advertisement. +/// Write the Parameters field of an extended NAMESPACE. /// -/// On a session that negotiated the MoQ Cluster extension every advertisement carries -/// HOP_PATH; ROUTE_COST is optional and absent means 0, so a free path sends nothing. -pub(super) fn encode_cluster_params( +/// ROUTE_COST is optional and absent means 0, so a free path sends nothing. +pub(super) fn encode_advert_params( w: &mut Encoder<'_>, version: Version, - advert: Option<&cluster::Advert>, + params: &AdvertParams, ) -> Result<(), EncodeError> { - match advert { - Some(advert) => { - let cost = (advert.cost != 0).then_some(advert.cost); - encode_params!(w, version, - cluster::HOP_PATH => advert.hops, - cluster::ROUTE_COST => cost, - ); - } - None => encode_params!(w, version,), - } + let hops = params.cluster.as_ref().map(|advert| advert.hops.clone()); + let cost = params + .cluster + .as_ref() + .and_then(|advert| (advert.cost != 0).then_some(advert.cost)); + encode_params!(w, version, + cluster::HOP_PATH => hops, + cluster::ROUTE_COST => cost, + epoch::EPOCH_PARAM => params.epoch.clone(), + ); Ok(()) } -/// Read the Parameters field of a NAMESPACE on a session that negotiated the extension. -/// See [`encode_cluster_params`]. -pub(super) fn decode_cluster_params(r: &mut Decoder<'_>, version: Version) -> Result { +/// Read the Parameters field of an extended NAMESPACE. See [`encode_advert_params`]. +pub(super) fn decode_advert_params( + r: &mut Decoder<'_>, + version: Version, + negotiated: Negotiated, +) -> Result { decode_params!(r, version, cluster::HOP_PATH => hops: Option, cluster::ROUTE_COST => cost: Option, + epoch::EPOCH_PARAM => epoch: Option where negotiated.epoch, ); - Ok(cluster::Advert { - hops: hops.ok_or(DecodeError::InvalidValue)?, - cost: cost.unwrap_or(0), + Ok(AdvertParams { + cluster: cluster_params(negotiated.cluster, hops, cost)?, + epoch, }) } @@ -405,7 +452,7 @@ mod tests { let msg = PublishNamespace { request_id: RequestId(1), track_namespace: Path::new("test/broadcast"), - cluster: None, + params: Default::default(), authorization_token: None, }; @@ -495,7 +542,7 @@ mod tests { let msg = PublishNamespace { request_id: RequestId(5), track_namespace: Path::new("v17/broadcast"), - cluster: None, + params: Default::default(), authorization_token: None, }; @@ -511,7 +558,7 @@ mod tests { let msg = PublishNamespace { request_id: RequestId(5), track_namespace: Path::new("v18/broadcast"), - cluster: None, + params: Default::default(), authorization_token: None, }; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index a1cbb283cc6..6eb0261d2e9 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -310,11 +310,10 @@ enum Advert { /// Nothing: every route loops through the peer or us, or none is announced. #[default] None, - /// The namespace, with no routing information: the peer did not negotiate the MoQ - /// Cluster extension, so there is nowhere to put a path or a cost. - Plain, - /// The namespace, with the path it traversed and that path's accumulated cost. - Cluster(cluster::Advert), + /// The namespace, with the parameters of the extensions the peer negotiated: the path + /// it traversed and that path's accumulated cost (MoQ Cluster), and the instance it + /// serves (MoQ Epoch). Empty when the peer negotiated neither. + Some(ietf::AdvertParams), } impl Advert { @@ -324,10 +323,10 @@ impl Advert { } /// The parameters to put on the wire, as the message structs carry them. - fn params(&self) -> Option { + fn params(&self) -> ietf::AdvertParams { match self { - Self::Cluster(advert) => Some(advert.clone()), - _ => None, + Self::Some(params) => params.clone(), + Self::None => Default::default(), } } } @@ -455,6 +454,9 @@ struct Namespaces { epoch: u64, /// Whether this discovery cursor includes hidden namespaces. hidden: bool, + /// Whether the peer negotiated MoQ Epoch, so an advertisement names its route's + /// instance. + epochs: bool, } impl Namespaces { @@ -471,6 +473,15 @@ impl Namespaces { gate: None, epoch: 0, hidden: false, + epochs: false, + } + } + + /// What the peer negotiated for an advertisement's parameters. + fn negotiated(&self) -> ietf::Negotiated { + ietf::Negotiated { + cluster: self.peer.negotiated(), + epoch: self.epochs, } } @@ -762,32 +773,42 @@ where /// /// The origin's announce cursor already filters routes through the peer /// (control-plane split horizon); this only shapes what the wire can carry. - fn select(&self, route: &crate::origin::Route, peer: &cluster::Peer) -> Advert { + /// `epochs` says the peer negotiated MoQ Epoch, so the route's instance travels too. + fn select(&self, route: &crate::origin::Route, peer: &cluster::Peer, epochs: bool) -> Advert { // A route that already passed through us is a reflection. The origin // filters these on receive, so this is defensive. if self.self_origin != crate::Hop::UNKNOWN && route.hops.contains(&self.self_origin) { return Advert::None; } + // Forwarded unchanged, and never invented for a route that arrived without one. + let epoch = route.epoch.clone().filter(|_| epochs); if !peer.negotiated() { - return Advert::Plain; + return Advert::Some(ietf::AdvertParams { cluster: None, epoch }); } let cost = route.cost.value(); // Our own Hop ID is always the last entry, so the peer reconstructs the full // path. A chain with no room left is a loop in all but name. match cluster::Advert::forward(&route.hops, cost, self.self_origin) { - Ok(advert) => Advert::Cluster(advert), + Ok(advert) => Advert::Some(ietf::AdvertParams { + cluster: Some(advert), + epoch, + }), Err(_) => Advert::None, } } /// Handle an incoming bidi stream dispatched by the session. + /// + /// `epochs` says both sides negotiated MoQ Epoch: a request naming an instance on a + /// session that did not breaks the session. pub fn handle_stream( &self, id: u64, body: ietf::Body, stream: Stream, + epochs: bool, ) -> Result, Error> { let this = self.clone(); let mut data = body.decoder(this.version); @@ -811,6 +832,9 @@ where if !data.is_empty() { return Err(Error::WrongSize); } + if msg.epoch.is_some() && !epochs { + return Err(Error::ProtocolViolation); + } tracing::debug!(message = ?msg, "received subscribe"); let gate = crate::auth::Gate::new( this.auth.clone(), @@ -840,6 +864,9 @@ where if !data.is_empty() { return Err(Error::WrongSize); } + if msg.epoch.is_some() && !epochs { + return Err(Error::ProtocolViolation); + } tracing::debug!(message = ?msg, "received fetch"); let gate = this.fetch_gate(&msg); async move { @@ -952,6 +979,9 @@ where if !data.is_empty() { return Err(Error::WrongSize); } + if msg.epoch.is_some() && !epochs { + return Err(Error::ProtocolViolation); + } tracing::debug!(message = ?msg, "received track_status"); let gate = crate::auth::Gate::new( this.auth.clone(), @@ -1140,10 +1170,11 @@ where // We just received a subscribe for this exact namespace, so the peer must have // already seen the announcement. `request_broadcast` resolves it immediately, or // falls back to the route covering it (an `origin::Dynamic`), if any. + // Pinned to the instance it names, if any: another is refused, never served. let broadcast = match self .serving_origin() .await - .request_broadcast(&msg.track_namespace, None) + .request_broadcast(&msg.track_namespace, msg.epoch.clone()) .await { Ok(broadcast) => broadcast, @@ -2180,6 +2211,9 @@ where .await; } + // Pinned to the instance it names, if any: another is refused, never served. + let epoch = msg.epoch.clone(); + // Draft-20's LOCATION_FILTER is answered as the standalone range it spells. let fetch_type = match msg.fetch_type { FetchType::Filtered { @@ -2257,7 +2291,7 @@ where // The peer must have seen the announcement to name this namespace, so this // resolves like a SUBSCRIBE does. let broadcast = match gate - .guard(async { self.serving_origin().await.request_broadcast(&namespace, None).await }) + .guard(async { self.serving_origin().await.request_broadcast(&namespace, epoch).await }) .await { Ok(broadcast) => broadcast, @@ -2700,9 +2734,10 @@ where } let broadcast = match gate .guard(async { + // Pinned to the instance it names, if any: another is refused, never served. self.serving_origin() .await - .request_broadcast(&msg.track_namespace, None) + .request_broadcast(&msg.track_namespace, msg.epoch.clone()) .await }) .await @@ -2911,6 +2946,7 @@ where let Some((advert, auth)) = self.offer(ns, suffix, path) else { return Ok(()); }; + let negotiated = ns.negotiated(); let Namespaces { target, watched, @@ -2927,13 +2963,18 @@ where let request = requests.get_mut(suffix); let held_auth = request.as_ref().and_then(|request| request.auth.clone()); let unchanged = advert == watch.sent && auth == held_auth; + // The epoch names the advertisement's instance for as long as it stands, so another + // one withdraws it and advertises afresh (MoQ Epoch). A restart arrives as an end and + // a start, so this only guards a change that skipped one. + let renamed = wanted && held && advert.params().epoch != watch.sent.params().epoch; // moq-transport renames a request's auth with REQUEST_UPDATE, but cannot name one on // a request that had none, nor drop one, and before draft-17 cannot update a // namespace at all: those withdraw the request and make it again. - let restart = held_auth != auth - && (held_auth.is_none() - || auth.is_none() - || matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16)); + let restart = renamed + || held_auth != auth + && (held_auth.is_none() + || auth.is_none() + || matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16)); // An update already waiting or in flight carries whatever is current once it goes // out, and its answer brings the loop back here for anything after that. @@ -2979,7 +3020,7 @@ where self.withdraw_namespace(target, requests, suffix.clone()).await?; } (true, Some(_)) => { - tracing::debug!(broadcast = %absolute, "publish_namespace restart for its auth"); + tracing::debug!(broadcast = %absolute, renamed, "publish_namespace restart"); self.withdraw_namespace(target, requests, suffix.clone()).await?; refused = self .advertise_namespace(requests, path, suffix.clone(), advert.params(), auth) @@ -3003,13 +3044,23 @@ where Target::Inline(stream) => { match (advert.wanted(), held) { (true, _) => { + if renamed { + tracing::debug!(broadcast = %absolute, "namespace_done for another epoch"); + stream.writer.varint(ietf::NamespaceDone::ID).await?; + stream + .writer + .encode(&ietf::NamespaceDone { + suffix: suffix.as_path(), + }) + .await?; + } tracing::debug!(broadcast = %absolute, "namespace"); stream.writer.varint(ietf::Namespace::ID).await?; stream .writer .encode(&ietf::Namespace { suffix: suffix.as_path(), - cluster: advert.params(), + params: negotiated.extended().then(|| advert.params()), }) .await?; } @@ -3050,7 +3101,7 @@ where requests: &mut HashMap>, path: &crate::PathOwned, suffix: crate::PathOwned, - cluster: Option, + params: ietf::AdvertParams, auth: Option, ) -> Result { let request_id = self.control.next_request_id(&self.runtime).await?; @@ -3070,7 +3121,7 @@ where .encode(&ietf::PublishNamespace { request_id, track_namespace: path.as_path(), - cluster, + params, authorization_token: auth.as_ref().and_then(|auth| self.request_token(auth)), }) .await?; @@ -3144,7 +3195,7 @@ where ) -> Option<(Advert, Option)> { let watch = ns.watched.get(suffix)?; let advert = match ns.permitted(path) { - true => self.select(&watch.route, &ns.peer), + true => self.select(&watch.route, &ns.peer, ns.epochs), false => Advert::None, }; let auth = match (&ns.target, advert.wanted()) { @@ -3214,7 +3265,7 @@ where return Ok(()); }; request.queued = false; - let mut update = match (advert.params(), watch.sent.params()) { + let mut update = match (advert.params().cluster, watch.sent.params().cluster) { (Some(next), Some(held)) => ietf::PublishNamespaceUpdate::between(request_id, &held, &next), _ => ietf::PublishNamespaceUpdate { request_id, @@ -3530,7 +3581,8 @@ where .excluding(&peer) .discovery(!self.peer_setup.get().await.hidden || self.origin.includes_hidden()); - let ns = Namespaces::new(peer, Target::Requests(None)); + let mut ns = Namespaces::new(peer, Target::Requests(None)); + ns.epochs = self.peer_setup.get().await.epoch; self.run_namespaces(origin.announced(), crate::Path::empty().to_owned(), ns, Vec::new()) .await } @@ -3630,7 +3682,7 @@ where let count = initial .iter() .filter(|update| permit.matches(prefix.join(&update.prefix).as_str())) - .filter(|update| self.select(&update.route, &peer).wanted()) + .filter(|update| self.select(&update.route, &peer, declared.epoch).wanted()) .count(); (initial, Some(count as u64)) } @@ -3680,6 +3732,7 @@ where let mut ns = Namespaces::new(peer, target); ns.gate = Some(gate); ns.hidden = !declared.hidden || msg.hidden || self.origin.includes_hidden(); + ns.epochs = declared.epoch; self.run_namespaces(announced, prefix, ns, initial).await } @@ -6047,8 +6100,13 @@ mod serve_tests { /// The same, with the track described by `info`. fn serve_track(version: Version, info: crate::track::Info) -> Serve { + serve_route(version, info, crate::origin::Route::default()) + } + + /// The same, with the broadcast announced on `route`. + fn serve_route(version: Version, info: crate::track::Info, route: crate::origin::Route) -> Serve { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); - let broadcast = origin.publish("room", crate::origin::Route::default()).unwrap(); + let broadcast = origin.publish("room", route).unwrap(); let track = broadcast.create_track("video", info).unwrap(); let session = ScriptedSession::per_stream(vec![Vec::new()]); @@ -6184,6 +6242,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, } .encode_msg(&mut Encoder::new(&mut fetch_body, version.into()), version) .unwrap(); @@ -6193,7 +6252,10 @@ mod serve_tests { (ietf::Fetch::ID, bytes::Bytes::from(fetch_body)), ] { let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); - let task = h.publisher.handle_stream(id, ietf::Body(body.clone()), stream).unwrap(); + let task = h + .publisher + .handle_stream(id, ietf::Body(body.clone()), stream, false) + .unwrap(); assert_eq!(h.publisher.owed.load(Ordering::Relaxed), 1, "count before polling"); drop(task); assert_eq!(h.publisher.owed.load(Ordering::Relaxed), 0, "release a cancelled task"); @@ -6201,14 +6263,17 @@ mod serve_tests { let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); assert!( h.publisher - .handle_stream(id, ietf::Body(bytes::Bytes::new()), stream) + .handle_stream(id, ietf::Body(bytes::Bytes::new()), stream, false) .is_err() ); assert_eq!(h.publisher.owed.load(Ordering::Relaxed), 0, "release malformed input"); if id == ietf::Fetch::ID { let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); - h.publisher.handle_stream(id, ietf::Body(body), stream).unwrap().await; + h.publisher + .handle_stream(id, ietf::Body(body), stream, false) + .unwrap() + .await; assert_eq!(h.publisher.owed.load(Ordering::Relaxed), 0, "release a completed fetch"); } } @@ -7059,7 +7124,12 @@ mod serve_tests { let closed = h .publisher .clone() - .handle_stream(ietf::TrackStatus::ID, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream( + ietf::TrackStatus::ID, + ietf::Body(bytes::Bytes::from(body)), + stream, + false, + ) .err(); assert!(matches!(closed, Some(Error::WrongSize)), "{version}: {closed:?}"); } @@ -7355,6 +7425,7 @@ mod serve_tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, } } @@ -7463,6 +7534,128 @@ mod serve_tests { } } + /// The refusal of request [`REQUEST_ID`] as gone, as draft-17 and later frame it. + async fn unroutable(version: Version) -> Vec { + let log = crate::lite::test_transport::Log::default(); + let mut writer = crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), version); + writer.varint(ietf::RequestError::ID).await.unwrap(); + writer + .encode(&ietf::RequestError { + request_id: None, + error_code: 0x10, + reason_phrase: Error::Unroutable.to_string().into(), + retry_interval: 0, + }) + .await + .unwrap(); + log.writes.lock().unwrap().clone() + } + + /// Each request MoQ Epoch pins to an instance, naming `epoch`, encoded for `version`. + fn pinned_requests(version: Version, epoch: &crate::Epoch) -> [(u64, Vec); 3] { + let mut subscribe = subscribe(Filter::NextObject, None); + subscribe.epoch = Some(epoch.clone()); + let fetch = ietf::Fetch { + request_id: RequestId(REQUEST_ID), + subscriber_priority: 128, + group_order: GroupOrder::Ascending, + fetch_type: fetch_range( + version, + "video", + Location { group: 0, object: 0 }, + Location { group: 0, object: 1 }, + ), + range_filters: false, + fill_timeout: false, + properties_wanted: true, + epoch: Some(epoch.clone()), + }; + let status = ietf::TrackStatus { + request_id: RequestId(REQUEST_ID), + track_namespace: crate::Path::new("room"), + track_name: "video".into(), + properties_wanted: true, + epoch: Some(epoch.clone()), + }; + let mut bodies: [Vec; 3] = Default::default(); + subscribe + .encode_msg(&mut Encoder::new(&mut bodies[0], version.into()), version) + .unwrap(); + fetch + .encode_msg(&mut Encoder::new(&mut bodies[1], version.into()), version) + .unwrap(); + status + .encode_msg(&mut Encoder::new(&mut bodies[2], version.into()), version) + .unwrap(); + let [subscribe, fetch, status] = bodies; + [ + (ietf::Subscribe::ID, subscribe), + (ietf::Fetch::ID, fetch), + (ietf::TrackStatus::ID, status), + ] + } + + /// MoQ Epoch pins SUBSCRIBE, FETCH and TRACK_STATUS to the instance they name: the + /// broadcast under the path now being another instance, or one with no epoch at all, + /// refuses them as gone instead of serving another instance's content. + #[moq_clock::test] + async fn a_request_for_another_instance_is_refused() { + for version in [Version::Draft17, Version::Draft20, Version::Draft22] { + let served = crate::Epoch::mint(); + let stale = crate::Epoch::mint(); + let pinned = crate::origin::Route::default().with_epoch(served.clone()); + for (name, route, named, refused) in [ + ("another epoch", pinned.clone(), &stale, true), + ("no epoch", crate::origin::Route::default(), &stale, true), + ("its epoch", pinned, &served, false), + ] { + let mut h = serve_route(version, crate::track::Info::timed(), route.clone()); + publish_groups(&mut h, 0); + settle().await; + let expected = unroutable(version).await; + for (id, body) in pinned_requests(version, named) { + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut task = h + .publisher + .clone() + .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream, true) + .unwrap(); + // A served SUBSCRIBE parks at the live edge, so poll rather than await. + for _ in 0..50 { + if futures::poll!(task.as_mut()).is_ready() { + break; + } + settle().await; + } + let wire = h.log.writes.lock().unwrap()[mark..].to_vec(); + let found = wire.windows(expected.len()).any(|window| window == expected.as_slice()); + assert_eq!(found, refused, "{version} {name}: request {id:#x}"); + } + } + } + } + + /// An EPOCH on a request breaks a session that did not negotiate MoQ Epoch: the peer + /// cannot have learned an instance it was never told about. + #[moq_clock::test] + async fn an_epoch_without_the_extension_is_a_violation() { + for version in [Version::Draft17, Version::Draft22] { + let h = serve(version); + for (id, body) in pinned_requests(version, &crate::Epoch::mint()) { + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let result = h + .publisher + .clone() + .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream, false); + assert!( + matches!(result, Err(Error::ProtocolViolation)), + "{version}: request {id:#x}" + ); + } + } + } + const ALL_VERSIONS: [Version; 9] = [ Version::Draft14, Version::Draft15, @@ -7481,6 +7674,7 @@ mod serve_tests { track_namespace: crate::Path::new(namespace), track_name: "video".into(), properties_wanted: wanted, + epoch: None, }; let mut body = Vec::new(); msg.encode_msg(&mut Encoder::new(&mut body, version.into()), version) @@ -7505,7 +7699,12 @@ mod serve_tests { let body = track_status("room", wanted, version); h.publisher .clone() - .handle_stream(ietf::TrackStatus::ID, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream( + ietf::TrackStatus::ID, + ietf::Body(bytes::Bytes::from(body)), + stream, + false, + ) .unwrap() .await; assert!(h.log.resets().is_empty(), "{version}: the answer was reset"); @@ -7585,7 +7784,12 @@ mod serve_tests { let mut answer = std::pin::pin!( h.publisher .clone() - .handle_stream(ietf::TrackStatus::ID, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream( + ietf::TrackStatus::ID, + ietf::Body(bytes::Bytes::from(body)), + stream, + false + ) .unwrap() ); assert!(futures::poll!(answer.as_mut()).is_pending(), "{version}"); @@ -7669,6 +7873,7 @@ mod serve_tests { track_namespace: crate::Path::new("room"), track_name: "video".into(), properties_wanted: true, + epoch: None, }, )); for _ in 0..100 { @@ -7706,7 +7911,12 @@ mod serve_tests { let mark = h.log.writes.lock().unwrap().len(); h.publisher .clone() - .handle_stream(ietf::TrackStatus::ID, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream( + ietf::TrackStatus::ID, + ietf::Body(bytes::Bytes::from(body)), + stream, + false, + ) .unwrap() .await; refusal_code(&h.log.writes.lock().unwrap()[mark..], version) @@ -7780,7 +7990,7 @@ mod serve_tests { let mark = h.log.writes.lock().unwrap().len(); h.publisher .clone() - .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream, false) .unwrap_or_else(|e| panic!("{version}: the request closed the session: {e}")) .await; assert!(h.log.resets().is_empty(), "{version}: refusal was reset"); @@ -7833,6 +8043,7 @@ mod serve_tests { properties_wanted: true, range_filters: true, fill_timeout: false, + epoch: None, }, ) .await @@ -7895,7 +8106,7 @@ mod serve_tests { let mut serving = std::pin::pin!( h.publisher .clone() - .handle_stream(ietf::TrackStatus::ID, ietf::Body(body.into()), stream) + .handle_stream(ietf::TrackStatus::ID, ietf::Body(body.into()), stream, false) .unwrap() ); let done = futures::poll!(serving.as_mut()); @@ -7923,7 +8134,7 @@ mod serve_tests { .unwrap(); h.publisher .clone() - .handle_stream(ietf::Subscribe::ID, ietf::Body(body.into()), stream) + .handle_stream(ietf::Subscribe::ID, ietf::Body(body.into()), stream, false) .unwrap_or_else(|e| panic!("{version}: the request was not started: {e}")) .await; assert_eq!( @@ -8069,7 +8280,7 @@ mod serve_tests { let task = h .publisher .clone() - .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream) + .handle_stream(id, ietf::Body(bytes::Bytes::from(body)), stream, false) .unwrap_or_else(|e| panic!("{version}: the request closed the session: {e}")); let mut task = std::pin::pin!(task); let mut done = false; @@ -8123,7 +8334,7 @@ mod serve_tests { assert!( h.publisher .clone() - .handle_stream(ietf::SubscribeNamespaceLegacy::ID, body, stream) + .handle_stream(ietf::SubscribeNamespaceLegacy::ID, body, stream, false) .is_err(), "{version}: Subscribe Options 0x03 kept the session open" ); @@ -8475,6 +8686,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, ) .await?; @@ -8644,7 +8856,7 @@ mod serve_tests { .unwrap(); let mut serving = h .publisher - .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream) + .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream, false) .unwrap(); let mut fetching = Box::pin(joining_fetch(&h, 0)); assert!( @@ -8679,7 +8891,7 @@ mod serve_tests { .unwrap(); let mut serving = h .publisher - .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream) + .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream, false) .unwrap(); match futures::future::select(&mut fetching, &mut serving).await { futures::future::Either::Left((response, _)) => { @@ -8702,7 +8914,7 @@ mod serve_tests { .unwrap(); let serving = h .publisher - .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream) + .handle_stream(ietf::Subscribe::ID, ietf::Body(bytes::Bytes::from(data)), stream, false) .unwrap(); let mut fetching = Box::pin(joining_fetch(&h, 0)); assert!(futures::poll!(fetching.as_mut()).is_pending()); @@ -8989,6 +9201,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted, + epoch: None, }, ) .await @@ -9656,6 +9869,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, )); // Driven until FETCH_OK is out, so the fetch is parked on uni stream credit. @@ -9757,6 +9971,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, )); // Driven until FETCH_OK is out, so the fetch is parked on uni stream credit. @@ -9880,6 +10095,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, )); for _ in 0..100 { @@ -10130,6 +10346,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, ) .await @@ -10174,6 +10391,7 @@ mod serve_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, ) .await @@ -12121,7 +12339,7 @@ mod tests { let local = announced.assert_next_active("from/us"); announced.assert_next_wait(); - assert_eq!(publisher.select(&local, &peer), Advert::Plain); + assert_eq!(publisher.select(&local, &peer, false), Advert::Some(Default::default())); } /// An anonymous chain received from an identified peer keeps the 0 on the wire @@ -13246,6 +13464,7 @@ mod tests { hidden: false, auth: false, active_count: false, + epoch: false, }); slot } @@ -14161,6 +14380,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }, ) .await @@ -14187,6 +14407,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, }, ) .await @@ -14516,6 +14737,7 @@ mod range_tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, } } diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index dab78786fa1..abbae7f402e 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -10,7 +10,7 @@ use crate::{ use super::{ Control, Message, Publisher, Subscriber, Version, active_count, adapter::ControlStreamAdapter, - auth, cluster, hidden, peer, request_update, solicit, + auth, cluster, epoch, hidden, peer, request_update, solicit, subscriber::{is_protocol_violation, subscribe_prefixes}, }; @@ -177,7 +177,7 @@ where // What the peer declared in its SETUP. Seeded now when that stream was already // read (the legacy handshake, or a gated server accept), and filled by the uni // loop otherwise. - let peer_setup = peer::PeerSetup::default(); + let peer_setup = peer::PeerSetup::new(extensions); let setup_read = peer_declared.is_some(); match peer_declared { Some(declared) => peer_setup.set(declared), @@ -768,6 +768,7 @@ fn peer_from_params(params: &ietf::Parameters, version: Version) -> Result( auth::into_setup(&mut parameters, version); } active_count::into_setup(&mut parameters, version); + if extensions.epoch { + epoch::into_setup(&mut parameters, version); + } request_update::into_setup(&mut parameters, version); let parameters = parameters.encode_bytes(version)?; @@ -1185,10 +1189,13 @@ where // An AUTH without MoQ Auth negotiated, offered by both sides, is an unknown request, // which falls through to the protocol violation in `Bidi::serve`. - let serve = match peer_setup.get().await.auth { + let declared_setup = peer_setup.get().await; + let serve = match declared_setup.auth { true => serve, false => None, }; + // Whether requests and PUBLISH_NAMESPACE may carry EPOCH (MoQ Epoch). + let epoch = declared_setup.epoch; // From the same slot, so this costs nothing extra: it decides whether an unsolicited // advertisement is the peer ignoring our own SETUP (MoQ Solicit). @@ -1205,6 +1212,7 @@ where publisher, subscriber, peer, + epoch, declared, serve, version, @@ -1258,6 +1266,8 @@ struct Bidi { publisher: Publisher, subscriber: Subscriber, peer: cluster::Peer, + /// Whether both sides negotiated MoQ Epoch. + epoch: bool, declared: Option, serve: Option, version: Version, @@ -1269,6 +1279,7 @@ impl Clone for Bidi { publisher: self.publisher.clone(), subscriber: self.subscriber.clone(), peer: self.peer, + epoch: self.epoch, declared: self.declared, serve: self.serve.clone(), version: self.version, @@ -1283,6 +1294,7 @@ impl Bidi { publisher, mut subscriber, peer, + epoch, declared, serve, version, @@ -1330,7 +1342,7 @@ impl Bidi { ietf::SubscribeNamespaceLegacy::ID if version == Version::Draft16 => { let request_id = RequestId::decode(&mut crate::coding::Decoder::new(&data.0, version.into()), version)?; let permit = publisher.control.accept(request_id)?; - let task = publisher.handle_stream(id, data, stream)?; + let task = publisher.handle_stream(id, data, stream, epoch)?; let _permit = permit; task.await; } @@ -1342,11 +1354,11 @@ impl Bidi { | ietf::SubscribeNamespaceLegacy::ID | ietf::SUBSCRIBE_TRACKS_ID | ietf::TrackStatus::ID => { - publisher.handle_stream(id, data, stream)?.await; + publisher.handle_stream(id, data, stream, epoch)?.await; } // Subscriber handles: Publish, PublishNamespace ietf::Publish::ID | ietf::PublishNamespace::ID => { - subscriber.handle_stream(id, data, stream, peer, declared)?.await; + subscriber.handle_stream(id, data, stream, peer, epoch, declared)?.await; } auth::Auth::ID if let Some(serve) = serve => { let mut data = data.decoder(version); @@ -1514,6 +1526,7 @@ mod tests { track_namespace: crate::Path::from("test"), track_name: "video".into(), properties_wanted: true, + epoch: None, } .encode_msg(&mut encoder, version) .unwrap(); @@ -1699,7 +1712,7 @@ mod tests { writer .encode(&ietf::Namespace { suffix: crate::Path::new("cam"), - cluster: None, + params: None, }) .await .unwrap(); @@ -2579,6 +2592,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, } .encode(&mut encoder, VERSION) .unwrap(); @@ -2885,7 +2899,7 @@ mod tests { .encode(&ietf::PublishNamespace { request_id: RequestId(1), track_namespace: crate::Path::new("room/host"), - cluster: None, + params: Default::default(), authorization_token: None, }) .await @@ -2999,6 +3013,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let mut body = Vec::new(); let mut w = crate::coding::Encoder::new(&mut body, version.into()); diff --git a/rs/moq-net/src/ietf/subscribe.rs b/rs/moq-net/src/ietf/subscribe.rs index ffe783bc9e4..867de49a8c2 100644 --- a/rs/moq-net/src/ietf/subscribe.rs +++ b/rs/moq-net/src/ietf/subscribe.rs @@ -11,6 +11,7 @@ use crate::{ use super::token::RequestToken; use super::Message; +use super::epoch; use super::namespace::{decode_track, encode_namespace}; use super::Version; @@ -45,6 +46,9 @@ pub struct Subscribe<'a> { /// NEW_GROUP_REQUEST (0x32, draft-15+): the subscriber's largest known Group ID plus /// one, or 0 when it knows none. Never encoded where the draft has no such parameter. pub new_group: Option, + /// The publisher instance the subscriber expects (MoQ Epoch, draft-17+). Only on a + /// session that negotiated it; the session refuses one that arrives otherwise. + pub epoch: Option, } /// NEW_GROUP_REQUEST (0x32) and DYNAMIC_GROUPS (0x30) arrived in draft-15. @@ -96,6 +100,7 @@ impl Message for Subscribe<'_> { range_filters: false, authorization_token, new_group: None, + epoch: None, }) } _ => { @@ -117,6 +122,7 @@ impl Message for Subscribe<'_> { 0x28 => object_property_filter: Vec where has_range_filters(version), 0x32 => new_group: Option where has_new_group_request(version), 0x35 => include_properties: Option where Filter::is_draft20(version), + epoch::EPOCH_PARAM => epoch: Option where epoch::supported(version), ); let authorization_token = super::token::single(authorization_token)?; @@ -155,6 +161,7 @@ impl Message for Subscribe<'_> { range_filters, authorization_token, new_group, + epoch, }) } } @@ -190,6 +197,8 @@ impl Message for Subscribe<'_> { // parameter, which is a protocol violation. let include_properties = (!self.properties_wanted && Filter::is_draft20(version)).then_some(false); let new_group = self.new_group.filter(|_| has_new_group_request(version)); + // Only a session that negotiated MoQ Epoch names one, and it exists from draft-17. + let epoch = self.epoch.clone().filter(|_| epoch::supported(version)); encode_params!(w, version, 0x03 => self.authorization_token.clone(), @@ -200,6 +209,7 @@ impl Message for Subscribe<'_> { 0x23 => fill, 0x32 => new_group, 0x35 => include_properties, + epoch::EPOCH_PARAM => epoch, ); } } @@ -588,6 +598,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -615,6 +626,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft15); @@ -659,6 +671,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let decoded: Subscribe = decode_message(&encode_message(&subscribe, version), version).unwrap(); assert_eq!(decoded.new_group, expected, "{version}: SUBSCRIBE"); @@ -765,6 +778,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; for version in [Version::Draft17, Version::Draft18, Version::Draft19, Version::Draft20] { @@ -799,6 +813,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -988,6 +1003,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, version); @@ -1139,6 +1155,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft17); @@ -1205,6 +1222,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft18); @@ -1524,6 +1542,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; #[rustfmt::skip] @@ -1588,6 +1607,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let decoded: Subscribe = decode_message(&encode_message(&msg, version), version).unwrap(); assert!(!decoded.forward, "{version}"); diff --git a/rs/moq-net/src/ietf/subscribe_namespace.rs b/rs/moq-net/src/ietf/subscribe_namespace.rs index bc03dd8b5bb..a0c99ee282a 100644 --- a/rs/moq-net/src/ietf/subscribe_namespace.rs +++ b/rs/moq-net/src/ietf/subscribe_namespace.rs @@ -5,9 +5,9 @@ use std::borrow::Cow; use crate::{Path, coding::*, ietf::RequestId}; use super::Message; -use super::cluster; use super::hidden::HIDDEN_PARAM; use super::namespace::{decode_namespace, encode_namespace}; +use super::publish_namespace::{AdvertParams, Negotiated}; use super::Version; @@ -271,31 +271,32 @@ impl Message for UnsubscribeNamespace { /// Indicates a namespace suffix matching the subscribed prefix is active. /// /// The base message carries only the suffix. A session that negotiated the MoQ Cluster -/// extension uses the extended form instead, which appends a Parameters field so the -/// advertisement can carry its HOP_PATH and ROUTE_COST (see [`cluster`]). +/// or MoQ Epoch extension uses the extended form instead, which appends one Parameters +/// field for both, so the advertisement can carry its HOP_PATH and ROUTE_COST (see +/// [`super::cluster`]) and its EPOCH (see [`super::epoch`]). #[derive(Clone, Debug)] pub struct Namespace<'a> { pub suffix: Path<'a>, - /// The MoQ Cluster parameters. `Some` selects the extended form; `None` the base - /// one. An endpoint must not append them on a session that did not negotiate. - pub cluster: Option, + /// The extension parameters. `Some` selects the extended form; `None` the base one. + /// An endpoint must not append them on a session that negotiated neither extension. + pub params: Option, } impl Namespace<'_> { /// Decode the message body, expecting the extended form when the session negotiated - /// the MoQ Cluster extension. See [`super::PublishNamespace::decode_body`]. - pub fn decode_body(r: &mut Decoder<'_>, version: Version, negotiated: bool) -> Result { + /// an extension that defines it. See [`super::PublishNamespace::decode_body`]. + pub fn decode_body(r: &mut Decoder<'_>, version: Version, negotiated: Negotiated) -> Result { let suffix = decode_namespace(r)?; // The base form has no Parameters field at all, so there is nothing to read - // (and nothing to reject) unless the extension is on. - let cluster = match negotiated { - true => Some(super::publish_namespace::decode_cluster_params(r, version)?), + // (and nothing to reject) unless an extension is on. + let params = match negotiated.extended() { + true => Some(super::publish_namespace::decode_advert_params(r, version, negotiated)?), false => None, }; - Ok(Self { suffix, cluster }) + Ok(Self { suffix, params }) } } @@ -304,14 +305,14 @@ impl Message for Namespace<'_> { fn encode_msg(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { encode_namespace(w, &self.suffix)?; - match &self.cluster { - Some(advert) => super::publish_namespace::encode_cluster_params(w, version, Some(advert)), + match &self.params { + Some(params) => super::publish_namespace::encode_advert_params(w, version, params), None => Ok(()), } } fn decode_msg(r: &mut Decoder<'_>, version: Version) -> Result { - Self::decode_body(r, version, false) + Self::decode_body(r, version, Negotiated::default()) } } @@ -367,6 +368,7 @@ impl Message for NamespaceDone<'_> { #[cfg(test)] mod tests { + use super::super::cluster; use super::*; fn body(msg: &M, version: Version) -> Vec { @@ -381,6 +383,39 @@ mod tests { cluster::HopPath::new(crate::Hops::try_from(hops).unwrap()) } + const CLUSTER: Negotiated = Negotiated { + cluster: true, + epoch: false, + }; + const EPOCH: Negotiated = Negotiated { + cluster: false, + epoch: true, + }; + const BOTH: Negotiated = Negotiated { + cluster: true, + epoch: true, + }; + + fn decode( + bytes: Vec, + version: Version, + negotiated: Negotiated, + ) -> Result<(Namespace<'static>, bool), DecodeError> { + let mut buf = bytes::Bytes::from(bytes); + let decoded = crate::coding::decode_buf(&mut buf, version, |r, v| Namespace::decode_body(r, v, negotiated))?; + Ok((decoded, buf.is_empty())) + } + + fn clustered(hops: &[u64], cost: u64) -> Option { + Some(AdvertParams { + cluster: Some(cluster::Advert { + hops: hop_path(hops), + cost, + }), + epoch: None, + }) + } + /// The extended NAMESPACE appends a Parameters field carrying the path and cost; /// the base one has no such field at all. #[test] @@ -388,32 +423,27 @@ mod tests { let version = Version::Draft19; let msg = Namespace { suffix: Path::new("alice.hang"), - cluster: Some(cluster::Advert { - hops: hop_path(&[7, 9]), - cost: 5, - }), + params: clustered(&[7, 9], 5), }; let encoded = body(&msg, version); - let mut buf = bytes::Bytes::from(encoded.clone()); - let decoded = crate::coding::decode_buf(&mut buf, version, |r, v| Namespace::decode_body(r, v, true)).unwrap(); - assert!(buf.is_empty()); + let (decoded, consumed) = decode(encoded.clone(), version, CLUSTER).unwrap(); + assert!(consumed); assert_eq!(decoded.suffix.as_str(), "alice.hang"); - assert_eq!(decoded.cluster, msg.cluster); + assert_eq!(decoded.params, msg.params); // The base form is strictly shorter, and reading the extended bytes as base // leaves the parameters behind rather than silently absorbing them. let base = Namespace { suffix: Path::new("alice.hang"), - cluster: None, + params: None, }; let base_encoded = body(&base, version); assert!(base_encoded.len() < encoded.len()); - let mut buf = bytes::Bytes::from(encoded); - let decoded = crate::coding::decode_buf(&mut buf, version, |r, v| Namespace::decode_body(r, v, false)).unwrap(); - assert!(decoded.cluster.is_none()); - assert!(!buf.is_empty(), "the parameters were not consumed"); + let (decoded, consumed) = decode(encoded, version, Negotiated::default()).unwrap(); + assert!(decoded.params.is_none()); + assert!(!consumed, "the parameters were not consumed"); } /// ROUTE_COST is optional and absent means 0, so a free path sends nothing. @@ -422,23 +452,90 @@ mod tests { let version = Version::Draft19; let free = Namespace { suffix: Path::new("a"), - cluster: Some(cluster::Advert { - hops: hop_path(&[7]), - cost: 0, - }), + params: clustered(&[7], 0), }; let priced = Namespace { suffix: Path::new("a"), - cluster: Some(cluster::Advert { - hops: hop_path(&[7]), - cost: 1, - }), + params: clustered(&[7], 1), }; assert!(body(&free, version).len() < body(&priced, version).len()); - let mut buf = bytes::Bytes::from(body(&free, version)); - let decoded = crate::coding::decode_buf(&mut buf, version, |r, v| Namespace::decode_body(r, v, true)).unwrap(); - assert_eq!(decoded.cluster.unwrap().cost, 0); + let (decoded, _) = decode(body(&free, version), version, CLUSTER).unwrap(); + assert_eq!(decoded.params.unwrap().cluster.unwrap().cost, 0); + } + + /// MoQ Epoch alone extends NAMESPACE too: the block is present, empty for a route + /// without an epoch, and carries EPOCH for one with. + #[test] + fn epoch_namespace_round_trips() { + let version = Version::Draft22; + let epoch = crate::Epoch::mint(); + for epoch in [None, Some(epoch)] { + let msg = Namespace { + suffix: Path::new("a"), + params: Some(AdvertParams { + cluster: None, + epoch: epoch.clone(), + }), + }; + let (decoded, consumed) = decode(body(&msg, version), version, EPOCH).unwrap(); + assert!(consumed); + assert_eq!(decoded.params, msg.params, "{epoch:?}"); + } + } + + /// With both extensions, one block holds the parameters of both. + #[test] + fn both_extensions_share_one_block() { + let version = Version::Draft22; + let mut params = clustered(&[7], 3).unwrap(); + params.epoch = Some(crate::Epoch::mint()); + let msg = Namespace { + suffix: Path::new("a"), + params: Some(params), + }; + let encoded = body(&msg, version); + let (decoded, consumed) = decode(encoded.clone(), version, BOTH).unwrap(); + assert!(consumed); + assert_eq!(decoded.params, msg.params); + + // Read as the base form, a single block is all that is left over. + let mut suffix = Vec::new(); + encode_namespace(&mut Encoder::new(&mut suffix, version.into()), &Path::new("a")).unwrap(); + let mut block = Vec::new(); + super::super::publish_namespace::encode_advert_params( + &mut Encoder::new(&mut block, version.into()), + version, + msg.params.as_ref().unwrap(), + ) + .unwrap(); + assert_eq!(encoded, [suffix, block].concat()); + } + + /// EPOCH on a session that did not negotiate MoQ Epoch is an unknown parameter, and so + /// is a malformed one on a session that did. + #[test] + fn epoch_refused_unless_negotiated_and_well_formed() { + let version = Version::Draft22; + let msg = Namespace { + suffix: Path::new("a"), + params: Some(AdvertParams { + cluster: clustered(&[7], 0).unwrap().cluster, + epoch: Some(crate::Epoch::mint()), + }), + }; + assert!(matches!( + decode(body(&msg, version), version, CLUSTER), + Err(DecodeError::InvalidValue) + )); + + let mut buf = Vec::new(); + encode_namespace(&mut Encoder::new(&mut buf, version.into()), &Path::new("a")).unwrap(); + let w = &mut Encoder::new(&mut buf, version.into()); + w.varint(1).unwrap(); + w.varint(super::super::epoch::EPOCH_PARAM).unwrap(); + w.bytes(&[0; 16]).unwrap(); + assert!(matches!(decode(buf, version, EPOCH), Err(DecodeError::InvalidValue))); } /// A negotiated session that omits HOP_PATH is a protocol violation. @@ -452,7 +549,7 @@ mod tests { let mut bytes = bytes::Bytes::from(buf); assert!(matches!( - crate::coding::decode_buf(&mut bytes, version, |r, v| Namespace::decode_body(r, v, true)), + crate::coding::decode_buf(&mut bytes, version, |r, v| Namespace::decode_body(r, v, CLUSTER)), Err(DecodeError::InvalidValue) )); } @@ -465,10 +562,13 @@ mod tests { let msg = super::super::PublishNamespace { request_id: RequestId(1), track_namespace: Path::new("a"), - cluster: Some(cluster::Advert { - hops: hop_path(&[7]), - cost: 0, - }), + params: AdvertParams { + cluster: Some(cluster::Advert { + hops: hop_path(&[7]), + cost: 0, + }), + epoch: None, + }, authorization_token: None, }; @@ -478,7 +578,9 @@ mod tests { let mut bytes = bytes::Bytes::from(buf); assert!( crate::coding::decode_buf(&mut bytes, version, |r, v| super::super::PublishNamespace::decode_body( - r, v, false + r, + v, + Negotiated::default() )) .is_err() ); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 43ce2d39ce1..3a50588e2b0 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -158,6 +158,10 @@ struct State { // Each broadcast created by a PUBLISH_NAMESPACE message. broadcasts: HashMap, + // Names each advertisement the peer makes, so one that a newer advertisement of the + // same namespace replaced cannot overwrite it. + next_advert: u64, + // Copies nobody subscribes to, kept for the linger with no subscription upstream: // a session ending ends them too. lingering: HashMap, @@ -458,13 +462,12 @@ impl Target { /// The model's info for a track the publisher described (SUBSCRIBE_OK or TRACK_STATUS_OK). /// -/// The copy keeps microsecond timestamps whatever units the publisher declared: each -/// object converts on receipt. +/// The copy keeps the units the publisher declared, so it matches a copy of the same +/// instance that arrived over another route: resuming across routes refuses one whose +/// metadata differs. fn accepted_info(properties: &ietf::Properties) -> track::Info { - // Normalized to microseconds, but only for a track that declared a timescale: an - // untimed one must not gain a timeline downstream. let mut info = track::Info::default() - .with_timescale(properties.timescale.map(|_| Timescale::MICRO)) + .with_timescale(properties.timescale) .with_max_age(properties.max_cache_duration) .with_priority(super::priority::from_wire(properties.priority.unwrap_or(128))); // This session carries NEW_GROUP_REQUEST back to the original publisher. @@ -498,10 +501,12 @@ struct TrackState { // stream and the subgroup stream carrying the rest of the group. fill: kio::Producer, - // The broadcast this track was subscribed from. With the track name it forms the full - // track name, which is what decides whether a repeated alias is the fatal collision - // (one alias, two tracks) or the legal sharing of an alias across subscriptions. + // The broadcast this track was subscribed from. With the track name and the instance + // it names, it forms the full track name, which is what decides whether a repeated + // alias is the fatal collision (one alias, two tracks) or the legal sharing of an alias + // across subscriptions. broadcast: PathOwned, + epoch: Option, // Units for this track's object Timestamps, from the TIMESCALE Track Property in // SUBSCRIBE_OK. `None` until it arrives, and for a track that declares none: its @@ -546,6 +551,7 @@ impl TrackState { name, alias: None, broadcast, + epoch: None, timescale: None, fill, largest: None, @@ -558,9 +564,16 @@ impl TrackState { } struct BroadcastState { - // The route announced into our origin for this namespace, post-charge. + // The route announced into our origin for this namespace, post-charge: the newest + // live advertisement's. route: crate::origin::Route, + // Each live advertisement of the namespace with the route it describes, oldest first. + // A publisher replacing its instance withdraws one advertisement and makes another, on + // separate streams that can arrive in either order: the newest stands until it goes, + // and an update to an older one changes nothing. + adverts: Vec<(u64, crate::origin::Route)>, + // The served route: dropping it (and the serve task's clone) retracts the // route and rejects its queued requests. `None` while the session's limit holds // it back, though the peer still advertises it. @@ -570,9 +583,6 @@ struct BroadcastState { // took the route away and gave it back ends rather than serve beside the new one. generation: u64, - // active number of PUBLISH_NAMESPACE messages. - count: usize, - // How many of them their own request token authorized. While any is live the // namespace is exempt from the session's limit. tokens: usize, @@ -621,6 +631,31 @@ struct Advertised { route: crate::origin::Route, } +impl Advertised { + /// The publisher instance the advertisement named (MoQ Epoch), taken as given. + fn with_epoch(mut self, epoch: Option) -> Self { + self.route.epoch = epoch; + self + } +} + +/// One NAMESPACE a SUBSCRIBE_NAMESPACE stream holds. +struct Advertisement { + /// Names it to [`Subscriber::stop_announce`] and [`Subscriber::update_announce`]. + id: u64, + /// The publisher instance it named, which a repeat must not change. + epoch: Option, +} + +/// What a PUBLISH_NAMESPACE stream advertises, kept current across its updates. +struct Held { + /// The MoQ Cluster parameters, which a REQUEST_UPDATE carries only when they change. + cluster: Option, + /// The MoQ Epoch instance, fixed for the advertisement's life: REQUEST_UPDATE cannot + /// carry one. + epoch: Option, +} + /// A joining request may be abandoned before it takes an ID. Once allocated, its /// header must still reach the peer so drafts 14/15 never see a missing ID. struct JoiningTask { @@ -665,6 +700,10 @@ impl Drop for JoiningTask { pub(super) struct Subscriber { // Scoped to a minted source on the clone that serves its requests. validity: crate::model::broadcast::RequestValidity, + // The publisher instance the minted source was resolved under (MoQ Epoch), named on + // every request for it, so the peer refuses rather than answer from another. Scoped + // like `validity`, and only ever set on a session that negotiated the extension. + epoch: Option, // Arms the track-alias and request-id timeouts. runtime: crate::time::Deadlines, session: S, @@ -799,6 +838,7 @@ where frames: Default::default(), announces: Default::default(), validity: Default::default(), + epoch: None, } } @@ -989,7 +1029,7 @@ where return false; }; - held.broadcast == new.broadcast && held.name == new.name + held.broadcast == new.broadcast && held.epoch == new.epoch && held.name == new.name } /// Take the origin request back out of a subscription that is still setting up. @@ -1116,13 +1156,18 @@ where let initial = count.unwrap_or(0); let snapshot = (initial > 0).then_some(snapshot); - // The extension changes the NAMESPACE encoding, so we can't parse one until - // the peer's SETUP says whether it negotiated. + // The extensions change the NAMESPACE encoding, so we can't parse one until + // the peer's SETUP says whether it negotiated them. let peer = self.peer().await; + let negotiated = ietf::Negotiated { + cluster: peer.negotiated(), + epoch: declared.epoch, + }; - // Suffixes live on this stream, so a repeat is recognized as an update to the - // advertisement rather than a second one (which would leak the refcount). - let mut live: std::collections::HashSet = std::collections::HashSet::new(); + // Suffixes live on this stream, with the advertisement each one holds, so a repeat + // is recognized as an update to it rather than a second one (which would leak the + // refcount). + let mut live: HashMap = HashMap::new(); // The stream owns every advertisement it carried, so release them however it // ends: a clean close, a decode error, or the peer resetting it. Without this @@ -1131,10 +1176,17 @@ where // This is what moq-lite already does, where the equivalent map is a local whose // guards drop. let res = self - .run_namespace_entries(&mut stream, &prefix, &peer, &mut live, Initial { initial, snapshot }) + .run_namespace_entries( + &mut stream, + &prefix, + &peer, + negotiated, + &mut live, + Initial { initial, snapshot }, + ) .await; - for path in live { - let _ = self.stop_announce(path, false); + for (path, advert) in live { + let _ = self.stop_announce(path, advert.id, false); } res } @@ -1149,7 +1201,8 @@ where stream: &mut Stream, prefix: &PathOwned, peer: &cluster::Peer, - live: &mut std::collections::HashSet, + negotiated: ietf::Negotiated, + live: &mut HashMap, mut initial: Initial, ) -> Result<(), Error> { loop { @@ -1171,13 +1224,22 @@ where // relative to our root -- so the join is too, which is what everything // below wants (`create_broadcast` joins the root itself). ietf::Namespace::ID => { - let msg = ietf::Namespace::decode_body(&mut data, self.version, peer.negotiated())?; + let msg = ietf::Namespace::decode_body(&mut data, self.version, negotiated)?; if !data.is_empty() { return Err(Error::WrongSize); } initial.initial = initial.initial.saturating_sub(1); let path = prefix.join(&msg.suffix); - let Some(advert) = self.route(msg.cluster.as_ref(), peer) else { + let params = msg.params.unwrap_or_default(); + // The epoch names the advertisement's instance for as long as it stands: a + // replacement is a NAMESPACE_DONE and a fresh NAMESPACE, never a repeat. + if let Some(held) = live.get(&path) + && held.epoch != params.epoch + { + tracing::warn!(%path, "namespace repeated under another epoch"); + return Err(Error::ProtocolViolation); + } + let Some(advert) = self.route(params.cluster.as_ref(), peer) else { // Looped back through us: forwarding it would extend the loop and // subscribing through it would route us back to ourselves. // @@ -1185,21 +1247,28 @@ where // replacement retracts the route we were holding. Keeping it would // leave subscriptions on a path the peer no longer offers. tracing::debug!(%path, "dropping reflected namespace"); - if live.remove(&path) { - let _ = self.stop_announce(path, false); + if let Some(held) = live.remove(&path) { + let _ = self.stop_announce(path, held.id, false); } continue; }; + let advert = advert.with_epoch(params.epoch.clone()); - tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, "namespace"); - if live.contains(&path) { + tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, epoch = ?params.epoch, "namespace"); + if let Some(held) = live.get(&path) { // A repeat replaces the advertisement atomically; nothing is torn // down merely because an update arrived. - self.update_announce(path, advert)?; + self.update_announce(path, held.id, advert)?; } else { match self.start_announce(path.clone(), advert, Admit::Session) { - Ok(()) => { - live.insert(path); + Ok(id) => { + live.insert( + path, + Advertisement { + id, + epoch: params.epoch, + }, + ); } // The interest names a pattern's literal head, so the peer // legitimately advertises namespaces beneath it that the @@ -1217,8 +1286,8 @@ where let msg = ietf::NamespaceDone::decode_msg(&mut data, self.version)?; let path = prefix.join(&msg.suffix); tracing::debug!(%path, "namespace_done"); - if live.remove(&path) { - let _ = self.stop_announce(path, false); + if let Some(held) = live.remove(&path) { + let _ = self.stop_announce(path, held.id, false); } } _ => { @@ -1243,6 +1312,7 @@ where body: ietf::Body, stream: Stream, peer: cluster::Peer, + epoch: bool, declared: Option, ) -> Result, Error> { let mut this = self.clone(); @@ -1273,7 +1343,11 @@ where ietf::PublishNamespace::ID => { // A negotiated session that omits HOP_PATH fails the decode here, which // the dispatcher turns into the protocol violation the draft requires. - let msg = match ietf::PublishNamespace::decode_body(&mut data, this.version, peer.negotiated()) { + let negotiated = ietf::Negotiated { + cluster: peer.negotiated(), + epoch, + }; + let msg = match ietf::PublishNamespace::decode_body(&mut data, this.version, negotiated) { Err(err) if super::token::refuses_request(&err) => { // Junk after the fields is fatal, which a token refusal must not hide. if !data.is_empty() { @@ -1422,7 +1496,8 @@ where // A path that already contains our own Hop ID looped back. Reject it rather // than attaching a source we would then have to route around. - let Some(advert) = self.route(msg.cluster.as_ref(), &peer) else { + let epoch = msg.params.epoch.clone(); + let Some(advert) = self.route(msg.params.cluster.as_ref(), &peer) else { tracing::debug!(%path, "dropping reflected publish_namespace"); self.write_error( &mut stream, @@ -1434,6 +1509,7 @@ where let _ = stream.writer.close().await; return Ok(()); }; + let advert = advert.with_epoch(epoch.clone()); // Our authorization of the peer (the limit) admits an announce without a token, and // holds back one it does not cover until it does. An AUTHORIZATION TOKEN on the @@ -1494,13 +1570,13 @@ where // Everything the advertisement does once admitted runs under its grant: one that ends // at any await, the first answer included, drops it right there. `attached` says the // route is up, and `acked` that the OK went out, which decides how the peer is told. - let mut attached = false; + let mut attached = None; let mut acked = false; let lived = crate::auth::RequestGrant::guard(token_grant.as_ref(), async { - if let Err(err) = self.start_announce(path.clone(), advert, admit) { - return Ok(Withdraw::Reject(request_id, err.into())); + match self.start_announce(path.clone(), advert, admit) { + Ok(id) => attached = Some(id), + Err(err) => return Ok(Withdraw::Reject(request_id, err.into())), } - attached = true; // Buffered whole before its first await, so however this is dropped from here, the // advertisement can still end on the wire. acked = true; @@ -1512,7 +1588,10 @@ where self.run_publish_namespace_updates( &mut stream, &path, - msg.cluster, + Held { + cluster: msg.params.cluster, + epoch, + }, peer, &mut attached, token_grant.clone(), @@ -1589,11 +1668,15 @@ where &mut self, stream: &mut Stream, path: &PathOwned, - mut held: Option, + held: Held, peer: cluster::Peer, - attached: &mut bool, + attached: &mut Option, token_grant: Option, ) -> Result { + let Held { + cluster: mut held, + epoch, + } = held; // A REQUEST_UPDATE carrying a fresh token refreshes the announce's request grant (MoQ // request-token); its verify is raced against the stream in the loop's single wait // (never a bare await), so a peer ending the announce ends it whatever the acceptor @@ -1812,25 +1895,27 @@ where let applied: Result<(), Error> = match carries_cluster { true => match self.route(held.as_ref(), &peer) { None => { - if std::mem::take(attached) { + if let Some(id) = attached.take() { tracing::debug!(%path, "publish_namespace now loops back; detaching"); - let _ = self.stop_announce(path.clone(), token_grant.is_some()); + let _ = self.stop_announce(path.clone(), id, token_grant.is_some()); } Ok(()) } Some(advert) => { + // The epoch is the advertisement's for as long as it stands. + let advert = advert.with_epoch(epoch.clone()); tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, "publish_namespace update"); match *attached { - true => self.update_announce(path.clone(), advert), + Some(id) => self.update_announce(path.clone(), id, advert), // Re-attach: a clean path replaced the reflected one we detached from. - false => { + None => { // The grant still holds the slot it was admitted with, so reuse it. let admit = match &token_grant { Some(grant) => Admit::Token(grant.hold()), None => Admit::Session, }; self.start_announce(path.clone(), advert, admit) - .map(|()| *attached = true) + .map(|id| *attached = Some(id)) } } } @@ -1876,9 +1961,9 @@ where /// Retract an advertisement's route ahead of a withdrawal that waits on the peer, so a peer /// that stops reading cannot keep it routed. `attached` makes it once only. - fn release_announce(&mut self, path: &PathOwned, attached: &mut bool, token: bool) -> Result<(), Error> { - if std::mem::take(attached) { - self.stop_announce(path.clone(), token)?; + fn release_announce(&mut self, path: &PathOwned, attached: &mut Option, token: bool) -> Result<(), Error> { + if let Some(id) = attached.take() { + self.stop_announce(path.clone(), id, token)?; } Ok(()) } @@ -2097,37 +2182,37 @@ where Ok(()) } - /// Attach the route for one newly advertised namespace, bumping its refcount. + /// Attach the route for one newly advertised namespace, returning the id that names + /// this advertisement. /// /// Pair with [`Self::stop_announce`]. - fn start_announce(&mut self, path: PathOwned, advert: Advertised, admit: Admit) -> Result<(), Error> { + fn start_announce(&mut self, path: PathOwned, advert: Advertised, admit: Admit) -> Result { let mut state = self.state.lock(); let (token, slot) = match admit { Admit::Session => (false, None), Admit::Token(slot) => (true, slot), }; + let id = state.next_advert; + state.next_advert += 1; let existing = state.broadcasts.contains_key(&path); - self.attach(&mut state, path.clone(), advert, slot, token)?; + self.attach(&mut state, path.clone(), id, advert, slot, token)?; if !existing { - return Ok(()); + return Ok(id); } let Some(entry) = state.broadcasts.get_mut(&path) else { - return Ok(()); + return Ok(id); }; // A token stands in for the limit, so a namespace the limit withheld attaches now. let attached = match token { true => self.reattach(&path, entry)?, false => None, }; - // The path was already attached, so this is one more advertisement for it; only a - // freshly created entry starts at one and skips this. - entry.count += 1; entry.tokens += usize::from(token); drop(state); if let Some(generation) = attached { self.serve_route(path, generation); } - Ok(()) + Ok(id) } /// Attach the route of a namespace the limit withheld, returning the generation @@ -2146,21 +2231,21 @@ where Ok(Some(entry.generation)) } - /// Apply a changed advertisement to a namespace that is already attached. + /// Apply a changed advertisement `id` to a namespace that is already attached. /// /// An update replaces the advertisement atomically: the refcount does not move, /// and no subscription is torn down merely because one arrived. - fn update_announce(&mut self, path: PathOwned, advert: Advertised) -> Result<(), Error> { + fn update_announce(&mut self, path: PathOwned, id: u64, advert: Advertised) -> Result<(), Error> { let mut state = self.state.lock(); if !state.broadcasts.contains_key(&path) { return Err(Error::NotFound); } - self.attach(&mut state, path, advert, None, false)?; + self.attach(&mut state, path, id, advert, None, false)?; Ok(()) } - /// Create or update the announced route for one namespace, leaving the - /// refcount to the caller. + /// Create the announced route for one namespace, or record advertisement `id` against + /// one that exists: added when new, replaced when it repeats. /// /// This is the semantic heart of the mapping: a moq-transport namespace IS a /// prefix route, so a PUBLISH_NAMESPACE advertises the whole prefix and paths @@ -2172,6 +2257,7 @@ where &self, state: &mut State, path: PathOwned, + id: u64, advert: Advertised, slot: Option, token: bool, @@ -2186,12 +2272,20 @@ where match state.broadcasts.entry(path.clone()) { Entry::Occupied(entry) => { - // A repeat is a repricing: update the route in place. In-flight - // tracks keep flowing. let entry = entry.into_mut(); - entry.route = route.clone(); - if let Some(dynamic) = &entry.dynamic { - dynamic.update(route)?; + match entry.adverts.iter_mut().find(|(advert, _)| *advert == id) { + Some((_, held)) => *held = route, + None => entry.adverts.push((id, route)), + } + // The newest advertisement stands, and an update to an older one changes + // nothing. A repeat of the same instance re-prices in place and in-flight + // tracks keep flowing; another epoch restarts it. + let (newest, route) = entry.adverts.last().expect("just recorded"); + if *newest == id { + entry.route = route.clone(); + if let Some(dynamic) = &entry.dynamic { + dynamic.update(entry.route.clone())?; + } } Ok(()) } @@ -2206,10 +2300,10 @@ where if !token && !self.auth.within_limit(crate::auth::Direction::Subscribe, path.as_str()) { tracing::debug!(route = %self.origin.absolute(&path), "withholding announce outside the limit"); entry.insert(BroadcastState { - route, + route: route.clone(), + adverts: vec![(id, route)], dynamic: None, generation: 0, - count: 1, tokens: usize::from(token), live: Default::default(), _slot: slot, @@ -2220,10 +2314,10 @@ where let dynamic = self.origin.dynamic(&path, route.clone())?; entry.insert(BroadcastState { - route, + route: route.clone(), + adverts: vec![(id, route)], dynamic: Some(dynamic), generation: 0, - count: 1, tokens: usize::from(token), live: Default::default(), _slot: slot, @@ -2247,22 +2341,35 @@ where }) } - /// Release one advertisement of `path`, closing its sources when it was the last. + /// Release advertisement `id` of `path`, closing its sources when it was the last. /// `token` says its own request token authorized it. - fn stop_announce(&mut self, path: PathOwned, token: bool) -> Result<(), Error> { + fn stop_announce(&mut self, path: PathOwned, id: u64, token: bool) -> Result<(), Error> { let mut state = self.state.lock(); match state.broadcasts.entry(path.clone()) { Entry::Occupied(mut entry) => { let state = entry.get_mut(); - state.count -= 1; + let Some(index) = state.adverts.iter().position(|(advert, _)| *advert == id) else { + return Err(Error::NotFound); + }; + state.adverts.remove(index); state.tokens -= usize::from(token); - if state.count == 0 { + if state.adverts.is_empty() { tracing::debug!(route = %self.origin.absolute(&path), "unannounced"); // Dropping the entry retracts the route (its announcement drops) and // closes its sources (its token closes). entry.remove(); - } else if state.tokens == 0 + return Ok(()); + } + // The newest went while an older one stands: that one is what remains. + let (_, newest) = state.adverts.last().expect("not empty"); + if *newest != state.route { + state.route = newest.clone(); + if let Some(dynamic) = &state.dynamic { + dynamic.update(state.route.clone())?; + } + } + if state.tokens == 0 && state.dynamic.is_some() && !self.auth.within_limit(crate::auth::Direction::Subscribe, path.as_str()) { @@ -2369,17 +2476,22 @@ where // The handler exists before the requester sees the source, so a track it asks // for before `run_broadcast` first polls queues instead of failing `NotFound`. let dynamic = source.dynamic(); - let validity = self - .state - .lock() - .broadcasts - .get(&path) - .filter(|entry| entry.generation == generation) - .and_then(|entry| entry.dynamic.as_ref()) - .map(|route| crate::model::broadcast::RequestValidity::for_source(route, request.path())) - .unwrap_or_else(|| { - crate::model::broadcast::RequestValidity::token(Some(kio::Producer::new(()).consume())) - }); + // The source serves the instance the route names now: every request for it names + // that epoch, so the peer refuses one that would reach another instance. + let (validity, epoch) = { + let state = self.state.lock(); + let entry = state + .broadcasts + .get(&path) + .filter(|entry| entry.generation == generation); + let validity = entry + .and_then(|entry| entry.dynamic.as_ref()) + .map(|route| crate::model::broadcast::RequestValidity::for_source(route, request.path())) + .unwrap_or_else(|| { + crate::model::broadcast::RequestValidity::token(Some(kio::Producer::new(()).consume())) + }); + (validity, entry.and_then(|entry| entry.route.epoch.clone())) + }; request.accept(&*source); // The namespace's token closes the source as it is retracted. If it was @@ -2398,6 +2510,7 @@ where let mut this = self.clone(); this.validity = validity; + this.epoch = epoch; broadcasts.push(async move { if let Err(err) = this.run_broadcast(requested.borrow(), source, dynamic, route).await { tracing::debug!(%err, "error running broadcast"); @@ -2418,6 +2531,9 @@ where return; } entry.route.cost = crate::origin::Cost::DRAIN; + for (_, route) in &mut entry.adverts { + route.cost = crate::origin::Cost::DRAIN; + } if let Some(dynamic) = &entry.dynamic { let _ = dynamic.update(entry.route.clone()); } @@ -2624,6 +2740,7 @@ where .filter(|start| start.frame != 0), // A resumed copy is the session's to abort from here on. producer: target.producer().cloned(), + epoch: self.epoch.clone(), ..TrackState::pending(track_name.to_owned(), broadcast_path.to_owned(), fill.clone(), joining) }, ); @@ -2658,6 +2775,7 @@ where rendezvous: false, range_filters: false, authorization_token: None, + epoch: self.epoch.clone(), }) .await } @@ -3411,6 +3529,8 @@ where range_filters: false, fill_timeout: false, properties_wanted: true, + // Served by the subscription it joins, which named the instance. + epoch: None, }) .await?; Ok::<(), Error>(()) @@ -3577,6 +3697,7 @@ where track_namespace: broadcast_path.to_owned(), track_name: track_name.into(), properties_wanted: true, + epoch: self.epoch.clone(), }) .await } @@ -4696,6 +4817,7 @@ where // The copy learned the track before any fetch, from SUBSCRIBE_OK or // TRACK_STATUS_OK, so a FETCH_OK repeating it is waste. properties_wanted: false, + epoch: self.epoch.clone(), }) .await?; Ok::<_, Error>(()) @@ -5787,7 +5909,7 @@ mod tests { writer .encode(&ietf::Namespace { suffix: crate::Path::new(suffix), - cluster: None, + params: None, }) .await .unwrap(); @@ -5944,7 +6066,7 @@ mod tests { writer .encode(&ietf::Namespace { suffix: crate::Path::new(entry), - cluster: None, + params: None, }) .await .unwrap(); @@ -7282,8 +7404,8 @@ mod tests { advert(&subscriber), advert(&subscriber), ); - subscriber.start_announce(a.clone(), first, Admit::Session).unwrap(); - subscriber.start_announce(a.clone(), repeat, Admit::Session).unwrap(); + let first = subscriber.start_announce(a.clone(), first, Admit::Session).unwrap(); + let repeat = subscriber.start_announce(a.clone(), repeat, Admit::Session).unwrap(); assert!(matches!( subscriber.start_announce(b.clone(), over, Admit::Session), Err(Error::TooManyRequests) @@ -7296,8 +7418,8 @@ mod tests { )] ); - subscriber.stop_announce(a.clone(), false).unwrap(); - subscriber.stop_announce(a, false).unwrap(); + subscriber.stop_announce(a.clone(), first, false).unwrap(); + subscriber.stop_announce(a, repeat, false).unwrap(); subscriber.start_announce(b, last, Admit::Session).unwrap(); } @@ -7659,9 +7781,12 @@ mod tests { writer .encode(&ietf::Namespace { suffix: crate::Path::new("x.hang"), - cluster: Some(cluster::Advert { - hops: hop_path(&[7, 9]), - cost, + params: Some(ietf::AdvertParams { + cluster: Some(cluster::Advert { + hops: hop_path(&[7, 9]), + cost, + }), + epoch: None, }), }) .await @@ -7726,10 +7851,10 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let advert = subscriber.route(None, &cluster::Peer::default()).expect("route"); - subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); + let id = subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); settle().await; - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, id, false).unwrap(); assert!( routed_now(&consumer, "room/host").is_none(), "an explicit NAMESPACE_DONE must retract the route", @@ -7765,7 +7890,7 @@ mod tests { let msg = ietf::PublishNamespace { request_id: RequestId(0), track_namespace: crate::Path::new("room/host"), - cluster: None, + params: Default::default(), authorization_token: None, }; let mut run = std::pin::pin!(subscriber.run_publish_namespace_stream( @@ -7828,7 +7953,7 @@ mod tests { let msg = ietf::PublishNamespace { request_id: RequestId(0), track_namespace: path.borrow(), - cluster: None, + params: Default::default(), authorization_token: None, }; subscriber @@ -7892,7 +8017,7 @@ mod tests { let msg = ietf::PublishNamespace { request_id: RequestId(0), track_namespace: path.borrow(), - cluster: None, + params: Default::default(), authorization_token: None, }; subscriber @@ -7960,7 +8085,7 @@ mod tests { let msg = ietf::PublishNamespace { request_id: RequestId(0), track_namespace: path.borrow(), - cluster: None, + params: Default::default(), authorization_token: None, }; subscriber @@ -7991,14 +8116,15 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let peer = cluster::Peer::default(); + let mut ids = Vec::new(); for _ in 0..2 { let advert = subscriber.route(None, &peer).expect("route"); - subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); + ids.push(subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap()); } settle().await; // One advertisement's stream dies: the other still holds the source. - subscriber.stop_announce(path.clone(), false).unwrap(); + subscriber.stop_announce(path.clone(), ids[0], false).unwrap(); settle().await; assert!( routed_now(&consumer, "room/host").is_some(), @@ -8006,7 +8132,7 @@ mod tests { ); // The last owner retracts: the broadcast closes with it. - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, ids[1], false).unwrap(); settle().await; assert!( routed_now(&consumer, "room/host").is_none(), @@ -8087,7 +8213,7 @@ mod tests { .with_hops(hop_path(&[7, 9]).hops().clone()) .with_cost(4), }; - subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); + let id = subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); // A new chain and cost: the route updates in place. @@ -8096,7 +8222,7 @@ mod tests { .with_hops(hop_path(&[7, 11]).hops().clone()) .with_cost(2), }; - subscriber.update_announce(path.clone(), rerouted).unwrap(); + subscriber.update_announce(path.clone(), id, rerouted).unwrap(); let route = routed_now(&consumer, "room/host").expect("routed"); let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); @@ -8105,7 +8231,7 @@ mod tests { // One advertisement, so one unannounce detaches it. If the update had bumped the // refcount, this would leave the route stranded. - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, id, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_none()); } @@ -8138,7 +8264,7 @@ mod tests { &peer, ) .expect("route"); - subscriber + let id = subscriber .start_announce(path.clone(), advertised, Admit::Session) .unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); @@ -8147,7 +8273,7 @@ mod tests { let repriced = subscriber .route(Some(&cluster::Advert { hops, cost: 1 }), &peer) .expect("route"); - subscriber.update_announce(path.clone(), repriced).unwrap(); + subscriber.update_announce(path.clone(), id, repriced).unwrap(); let route = routed_now(&consumer, "room/host").expect("still routed"); assert_eq!( @@ -8157,10 +8283,55 @@ mod tests { ); // One advertisement, so one unannounce detaches it. - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, id, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_none()); } + /// MoQ Epoch: a publisher replacing its instance withdraws one advertisement and makes + /// another, on separate streams that arrive in either order. The newest advertisement + /// stands, so neither the old one's late update nor its withdrawal reverts the route + /// to the instance it named. + #[moq_clock::test] + async fn a_reordered_replacement_keeps_the_new_instance() { + let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); + let consumer = origin.consume(); + let path = crate::Path::new("room/host").to_owned(); + let peer = cluster::Peer::default(); + let (old, new) = (crate::Epoch::mint(), crate::Epoch::mint()); + let advert = |subscriber: &Subscriber<_>, epoch: &crate::Epoch| { + subscriber + .route(None, &peer) + .expect("route") + .with_epoch(Some(epoch.clone())) + }; + let epoch_now = || routed_now(&consumer, "room/host").and_then(|route| route.epoch); + + let first = advert(&subscriber, &old); + let first = subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); + assert_eq!(epoch_now(), Some(old.clone())); + + // The replacement's PUBLISH_NAMESPACE beats the old one's PUBLISH_NAMESPACE_DONE. + let second = advert(&subscriber, &new); + let second = subscriber.start_announce(path.clone(), second, Admit::Session).unwrap(); + assert_eq!(epoch_now(), Some(new.clone())); + + // A late update to the old advertisement changes nothing. + let stale = advert(&subscriber, &old); + subscriber.update_announce(path.clone(), first, stale).unwrap(); + assert_eq!(epoch_now(), Some(new.clone()), "a stale update reverted the instance"); + + // Its withdrawal, arriving last, leaves the new instance standing. + subscriber.stop_announce(path.clone(), first, false).unwrap(); + assert_eq!( + epoch_now(), + Some(new.clone()), + "the old withdrawal retracted the new instance" + ); + + subscriber.stop_announce(path, second, false).unwrap(); + assert_eq!(routed_now(&consumer, "room/host"), None); + } + /// Two *separate* advertisements for one namespace refcount a single route: /// it takes both retractions to retract it. #[moq_clock::test] @@ -8178,17 +8349,17 @@ mod tests { let advert = cluster::Advert { hops, cost: 0 }; let first = subscriber.route(Some(&advert), &peer).expect("route"); - subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); + let first = subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); let second = subscriber.route(Some(&advert), &peer).expect("route"); - subscriber.start_announce(path.clone(), second, Admit::Session).unwrap(); + let second = subscriber.start_announce(path.clone(), second, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); // Two advertisements, so it takes two unannounces to retract. - subscriber.stop_announce(path.clone(), false).unwrap(); + subscriber.stop_announce(path.clone(), first, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, second, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_none()); } @@ -8206,18 +8377,18 @@ mod tests { // What a PUBLISH_NAMESPACE with no cluster parameters resolves to. let first = subscriber.route(None, &peer).expect("route"); - subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); + let first = subscriber.start_announce(path.clone(), first, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); // The NAMESPACE for the same namespace arrives second. let second = subscriber.route(None, &peer).expect("route"); - subscriber.start_announce(path.clone(), second, Admit::Session).unwrap(); + let second = subscriber.start_announce(path.clone(), second, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); // Two advertisements, so it takes two unannounces to retract. - subscriber.stop_announce(path.clone(), false).unwrap(); + subscriber.stop_announce(path.clone(), first, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, second, false).unwrap(); assert!(routed_now(&consumer, "room/host").is_none()); } @@ -8240,7 +8411,7 @@ mod tests { cost: 0, }; let advert = subscriber.route(Some(&clean), &peer).expect("route"); - subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); + let id = subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); assert!(routed_now(&consumer, "room/host").is_some()); // The peer re-advertises the namespace over a path that now flows through us. @@ -8254,7 +8425,7 @@ mod tests { ); // That supersedes the advertisement it repeats, so the old route is retired. - subscriber.stop_announce(path, false).unwrap(); + subscriber.stop_announce(path, id, false).unwrap(); assert!( routed_now(&consumer, "room/host").is_none(), "the superseded route must not stay attached" @@ -8324,7 +8495,8 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let advert = subscriber.route(Some(attached), peer).expect("route"); - subscriber.start_announce(path, advert, Admit::Session).unwrap(); + let id = subscriber.start_announce(path, advert, Admit::Session).unwrap(); + assert_eq!(id, 0, "the harness advertisement is the first"); assert!(routed_now(&consumer, "room/host").is_some(), "attached to start with"); let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); @@ -8401,12 +8573,15 @@ mod tests { let log = subscriber.session.log.clone(); // The initial request is already retired; its ID remains permanently spent. assert!(subscriber.control.accept(RequestId(3)).unwrap().is_none()); - let mut attached = true; + let mut attached = Some(0); let err = subscriber .run_publish_namespace_updates( &mut stream, &crate::Path::new("room/host"), - Some(clean), + Held { + cluster: Some(clean), + epoch: None, + }, peer, &mut attached, None, @@ -8432,12 +8607,15 @@ mod tests { let log = subscriber.session.log.clone(); let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8459,7 +8637,7 @@ mod tests { routed_now(&consumer, "room/host").is_none(), "an unusable path must not stay attached" ); - assert!(!attached, "the caller must not release it a second time"); + assert!(attached.is_none(), "the caller must not release it a second time"); assert_eq!( replies(&log, ietf::RequestOk::ID), 1, @@ -8479,12 +8657,15 @@ mod tests { reflected_harness(self_origin, &peer, &clean, &[looped, clean.clone()]).await; let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8500,7 +8681,7 @@ mod tests { } } - assert!(attached, "the clean path must re-attach"); + assert!(attached.is_some(), "the clean path must re-attach"); assert!( routed_now(&consumer, "room/host").is_some(), "the namespace is routable again", @@ -8564,12 +8745,15 @@ mod tests { .unwrap(); let mut stream = Stream::open(&mut session.clone(), Version::Draft19).await.unwrap(); - let mut attached = true; + let mut attached = Some(0); { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, Some(grant), @@ -8583,7 +8767,7 @@ mod tests { } } - assert!(attached, "the clean path must re-attach"); + assert!(attached.is_some(), "the clean path must re-attach"); assert!( routed_now(&consumer, "room/host").is_some(), "the namespace is routable again" @@ -8633,12 +8817,15 @@ mod tests { assert_eq!(routed_now(&consumer, "room/host").expect("routed").cost.value(), 4); let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(held.clone()), + Held { + cluster: Some(held.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8653,7 +8840,7 @@ mod tests { assert_eq!(route.cost.value(), 0, "the explicit 0 replaced the held cost"); let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); assert_eq!(hops, vec![7, 9], "the omitted path kept its value"); - assert!(attached, "a repricing is not a retraction"); + assert!(attached.is_some(), "a repricing is not a retraction"); assert_eq!(replies(&log, ietf::RequestOk::ID), 1); assert_eq!(replies(&log, ietf::RequestError::ID), 0); } @@ -8681,13 +8868,16 @@ mod tests { drop(driver); let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); let mut result = None; { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8705,7 +8895,7 @@ mod tests { matches!(result, Some(Ok(Withdraw::Reject(..)))), "a refused update ends the stream cleanly, got {result:?}" ); - assert!(attached, "the caller releases the route it attached"); + assert!(attached.is_some(), "the caller releases the route it attached"); assert_eq!( replies(&log, ietf::RequestError::ID), 0, @@ -8733,12 +8923,15 @@ mod tests { let log = subscriber.session.log.clone(); let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8752,7 +8945,7 @@ mod tests { } } - assert!(attached, "the advertisement stays attached"); + assert!(attached.is_some(), "the advertisement stays attached"); assert_eq!(replies(&log, ietf::RequestOk::ID), 1, "REQUEST_OK went out"); assert_eq!(replies(&log, ietf::RequestError::ID), 0); let route = routed_now(&consumer, "room/host").expect("still routed"); @@ -8778,10 +8971,13 @@ mod tests { .encode(&ietf::PublishNamespace { request_id: RequestId(1), track_namespace: crate::Path::new("room/host"), - cluster: Some(cluster::Advert { - cost: 0, - ..clean.clone() - }), + params: ietf::AdvertParams { + cluster: Some(cluster::Advert { + cost: 0, + ..clean.clone() + }), + epoch: None, + }, authorization_token: None, }) .await @@ -8794,11 +8990,14 @@ mod tests { std::mem::forget(driver); let path = crate::Path::new("room/host").to_owned(); - let mut attached = true; + let mut attached = Some(0); let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, &path, - Some(clean.clone()), + Held { + cluster: Some(clean.clone()), + epoch: None + }, peer, &mut attached, None, @@ -8826,19 +9025,19 @@ mod tests { let consumer = origin.consume(); let peer = cluster::Peer::default(); - let mut live = std::collections::HashSet::new(); + let mut live = std::collections::HashMap::new(); for path in ["room/a", "room/b"] { let path = crate::Path::new(path).to_owned(); let advert = subscriber.route(None, &peer).expect("route"); - subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); - live.insert(path); + let id = subscriber.start_announce(path.clone(), advert, Admit::Session).unwrap(); + live.insert(path, id); } assert!(routed_now(&consumer, "room/a").is_some()); assert!(routed_now(&consumer, "room/b").is_some()); // What the stream's exit path does with whatever it still holds. - for path in live { - subscriber.stop_announce(path, false).unwrap(); + for (path, id) in live { + subscriber.stop_announce(path, id, false).unwrap(); } assert!(routed_now(&consumer, "room/a").is_none(), "room/a leaked a refcount"); @@ -9044,7 +9243,7 @@ mod tests { ietf::PublishNamespace { request_id: RequestId(1), track_namespace: crate::Path::new("room/alice"), - cluster: None, + params: Default::default(), authorization_token: Some(announce_token()), } } @@ -9820,7 +10019,7 @@ mod tests { let tokenless = ietf::PublishNamespace { request_id: RequestId(1), track_namespace: crate::Path::new("other/alice"), - cluster: None, + params: Default::default(), authorization_token: None, }; let mut run = std::pin::pin!(subscriber.run_publish_namespace_stream( @@ -9870,7 +10069,7 @@ mod tests { }; // The announce arrives already routed at cost 4; the update re-routes it to cost 0. let mut initial = token_publish_namespace(); - initial.cluster = Some(cluster::Advert { + initial.params.cluster = Some(cluster::Advert { hops: hop_path(&[7, 9]), cost: 4, }); @@ -9950,7 +10149,7 @@ mod tests { }; // The announce arrives routed at cost 4; the buffered updates re-route it. let mut initial = token_publish_namespace(); - initial.cluster = Some(cluster::Advert { + initial.params.cluster = Some(cluster::Advert { hops: hop_path(&[7, 9]), cost: 4, }); @@ -11488,6 +11687,7 @@ mod stitch_tests { range_filters: false, fill_timeout: false, properties_wanted: true, + epoch: None, } .encode_msg(&mut Encoder::new(&mut body, egress.into()), egress) .unwrap(); @@ -11507,6 +11707,7 @@ mod stitch_tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, } .encode_msg(&mut Encoder::new(&mut body, egress.into()), egress) .unwrap(); @@ -11514,7 +11715,7 @@ mod stitch_tests { }; let stream = Stream::open(&mut downstream, egress).await.unwrap(); publisher - .handle_stream(id, ietf::Body(body.into()), stream) + .handle_stream(id, ietf::Body(body.into()), stream, false) .unwrap() .await; let mut streams = std::collections::BTreeMap::>::new(); @@ -11581,10 +11782,11 @@ mod stitch_tests { } } - /// A relayed Timestamp leaves in the units the egress declares: the cache holds the - /// track in microseconds, whatever the publisher used. + /// A relayed Timestamp leaves in the units the publisher declared: the cache holds the + /// track on the publisher's grid, so a copy of the same instance over another route + /// matches it. #[moq_clock::test] - async fn passthrough_converts_relayed_timestamps_to_the_egress_units() { + async fn passthrough_keeps_the_publishers_timestamp_units() { let version = Version::Draft22; // Timestamp 42 (ms), then an unknown property that must survive beside it. let properties = [0x10, 42, 0x70, 7]; @@ -11595,11 +11797,8 @@ mod stitch_tests { ietf::GroupHeader::decode(&mut decoder, version).unwrap(); assert_eq!(decoder.varint().unwrap(), 0); let relayed = bytes::Bytes::copy_from_slice(decoder.bytes().unwrap()); - let decoded = super::super::object::read(&relayed, version, Some(Timescale::MICRO)).unwrap(); - assert_eq!( - decoded.timestamp, - Some(Timestamp::new(42_000, Timescale::MICRO).unwrap()) - ); + let decoded = super::super::object::read(&relayed, version, Some(Timescale::MILLI)).unwrap(); + assert_eq!(decoded.timestamp, Some(Timestamp::new(42, Timescale::MILLI).unwrap())); assert_eq!(decoded.properties.values.len(), 1); } @@ -12058,6 +12257,7 @@ mod stitch_tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let mut body = Vec::new(); subscribe @@ -12065,7 +12265,7 @@ mod stitch_tests { .unwrap(); let stream = Stream::open(&mut downstream, version).await.unwrap(); publisher - .handle_stream(ietf::Subscribe::ID, ietf::Body(body.into()), stream) + .handle_stream(ietf::Subscribe::ID, ietf::Body(body.into()), stream, false) .unwrap() .await; let sent = downstream.log.datagrams.lock().unwrap(); diff --git a/rs/moq-net/src/ietf/track.rs b/rs/moq-net/src/ietf/track.rs index fc62618ea8f..4b5d35feede 100644 --- a/rs/moq-net/src/ietf/track.rs +++ b/rs/moq-net/src/ietf/track.rs @@ -26,6 +26,8 @@ pub struct TrackStatus<'a> { /// Whether the requester wants Track Properties on the answer (INCLUDE_PROPERTIES, /// draft-20). pub properties_wanted: bool, + /// The publisher instance the requester expects (MoQ Epoch, draft-17+). + pub epoch: Option, } impl Message for TrackStatus<'_> { @@ -51,7 +53,11 @@ impl Message for TrackStatus<'_> { // Only the opt-out is worth bytes, and an older peer would read the // parameter as unknown, which is a protocol violation. let include_properties = (!self.properties_wanted && Filter::is_draft20(version)).then_some(false); - encode_params!(w, version, 0x35 => include_properties); + let epoch = self.epoch.clone().filter(|_| super::epoch::supported(version)); + encode_params!(w, version, + 0x35 => include_properties, + super::epoch::EPOCH_PARAM => epoch, + ); } } Ok(()) @@ -67,6 +73,7 @@ impl Message for TrackStatus<'_> { track_namespace: subscribe.track_namespace, track_name: subscribe.track_name, properties_wanted: subscribe.properties_wanted, + epoch: subscribe.epoch, }) } } @@ -261,6 +268,7 @@ mod tests { track_namespace: Path::new("test/ns"), track_name: "video".into(), properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -278,6 +286,7 @@ mod tests { track_namespace: Path::new("test/ns"), track_name: "video".into(), properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft15); @@ -295,6 +304,7 @@ mod tests { track_namespace: Path::new("test/ns"), track_name: "video".into(), properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft17); @@ -312,6 +322,7 @@ mod tests { track_namespace: Path::new("test/ns"), track_name: "video".into(), properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft16); @@ -329,6 +340,7 @@ mod tests { track_namespace: Path::new("test/ns"), track_name: "video".into(), properties_wanted: true, + epoch: None, }; let encoded = encode_message(&msg, Version::Draft18); @@ -362,6 +374,7 @@ mod tests { track_namespace: Path::new("ns"), track_name: "video".into(), properties_wanted: wanted, + epoch: None, }; let decoded: TrackStatus = decode_message(&encode_message(&msg, version), version) .unwrap_or_else(|e| panic!("{version}: {e}")); diff --git a/rs/moq-net/src/ietf/version.rs b/rs/moq-net/src/ietf/version.rs index 528babfcc25..78016e91d4b 100644 --- a/rs/moq-net/src/ietf/version.rs +++ b/rs/moq-net/src/ietf/version.rs @@ -104,6 +104,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; let subscribe_ok = SubscribeOk { @@ -142,6 +143,7 @@ mod tests { range_filters: false, fill_timeout: false, properties_wanted: false, + epoch: None, }; let group = GroupHeader { @@ -178,6 +180,7 @@ mod tests { rendezvous: false, range_filters: false, authorization_token: None, + epoch: None, }; // Draft-20 spells Next Object as a Length of 2 and two zero fields; draft-22 as type 0x05. diff --git a/rs/moq-net/src/setup.rs b/rs/moq-net/src/setup.rs index 5723b9fc48f..cb33a75f0b5 100644 --- a/rs/moq-net/src/setup.rs +++ b/rs/moq-net/src/setup.rs @@ -28,7 +28,7 @@ pub(crate) const SETUP_V17: u64 = 0x2F00; /// The moq-transport Setup Options this side offers, each on by default. /// /// Turning one off connects as a peer that does not speak that extension. moq-lite carries -/// both in its core, so this only changes moq-transport sessions. +/// them in its core, so this only changes moq-transport sessions. #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[serde(default, deny_unknown_fields)] #[non_exhaustive] @@ -38,6 +38,9 @@ pub struct Extensions { /// The MoQ Solicit extension: the peer answers our SUBSCRIBE_NAMESPACE rather than /// announcing unasked. pub solicit: bool, + /// The MoQ Epoch extension: announcements and requests carry the publisher's + /// [`Epoch`](crate::Epoch), as moq-lite 07 does (draft-17+). + pub epoch: bool, } impl Default for Extensions { @@ -45,6 +48,7 @@ impl Default for Extensions { Self { auth: true, solicit: true, + epoch: true, } } } diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index a7474e17a27..b43a8b57dfe 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -400,6 +400,7 @@ fn ietf_track_status_interop() { track_namespace: crate::Path::new(namespace), track_name: "video".into(), properties_wanted: wanted, + epoch: None, } .encode(&mut w, version) .unwrap(); diff --git a/rs/moq-net/tests/integration/catalog_acquisition.rs b/rs/moq-net/tests/integration/catalog_acquisition.rs index 40e893c4732..ca4bc66cf77 100644 --- a/rs/moq-net/tests/integration/catalog_acquisition.rs +++ b/rs/moq-net/tests/integration/catalog_acquisition.rs @@ -21,7 +21,9 @@ async fn link(version: Version, from: &origin::Producer, to: &origin::Producer, connect_mock(options).await } -async fn acquisition(version: &str) { +/// `carries_epoch`: the wire carries the epoch, as lite-07 and moq-transport with the MoQ +/// Epoch extension do. +async fn acquisition(version: &str, carries_epoch: bool) { let version: Version = version.parse().unwrap(); let publisher = origin(1); let subscriber = origin(2); @@ -46,10 +48,9 @@ async fn acquisition(version: &str) { // TRACK_INFO makes the replacement happen during acquisition without sleeps. let _new = link(version, &publisher, &subscriber, 1).await; // An epochless replacement restarts the advertisement; a matching epoch only updates it. - let lite07 = version == "moq-lite-07-wip".parse().unwrap(); let new_cost = match announced.next().await { - Some(moq_net::announce::Event::Update(announce)) if lite07 => announce.route.cost, - Some(moq_net::announce::Event::Restart(announce)) if !lite07 => announce.route.cost, + Some(moq_net::announce::Event::Update(announce)) if carries_epoch => announce.route.cost, + Some(moq_net::announce::Event::Restart(announce)) if !carries_epoch => announce.route.cost, other => panic!("{version}: unexpected route change {other:?}"), }; assert!(new_cost < old_cost, "the cheaper session wins the route"); @@ -58,7 +59,7 @@ async fn acquisition(version: &str) { group.write_frame(None, b"catalog".to_vec()).unwrap(); group.finish().unwrap(); let result = pending.await; - if lite07 { + if carries_epoch { let mut subscription = result.expect("same epoch must acquire"); let mut group = subscription.recv_group().await.unwrap().unwrap(); assert_eq!(group.read_frame().await.unwrap().unwrap().payload.as_ref(), b"catalog"); @@ -73,10 +74,12 @@ async fn acquisition(version: &str) { #[moq_clock::test] async fn epochless_replacement_refuses_pending_catalog() { - acquisition("moq-lite-06").await; + acquisition("moq-lite-06", false).await; } #[moq_clock::test] async fn same_epoch_replacement_acquires_pending_catalog() { - acquisition("moq-lite-07-wip").await; + acquisition("moq-lite-07-wip", true).await; + acquisition("moq-transport-17", true).await; + acquisition("moq-transport-22", true).await; } diff --git a/rs/moq-net/tests/integration/extensions.rs b/rs/moq-net/tests/integration/extensions.rs index 0cec5a10036..d9b5ac39370 100644 --- a/rs/moq-net/tests/integration/extensions.rs +++ b/rs/moq-net/tests/integration/extensions.rs @@ -150,3 +150,76 @@ async fn a_declined_auth_extension_is_not_negotiated() { } } } + +/// The route `path` is announced on in `origin` right now, if any. +fn route(origin: &origin::Producer, path: &str) -> Option { + let mut announced = origin.consume().announced(); + let mut route = None; + while let Some(event) = announced.try_next() { + match event { + moq_net::announce::Event::Start(update) + | moq_net::announce::Event::Update(update) + | moq_net::announce::Event::Restart(update) => { + if update.prefix.as_str() == path { + route = Some(update.route); + } + } + moq_net::announce::Event::End(update) => { + if update.prefix.as_str() == path { + route = None; + } + } + } + } + route +} + +/// MoQ Epoch carries the publisher's epoch, in either direction, only when both sides +/// offer it on draft-17 or later. A side declining it, or an older draft, leaves the +/// route epochless exactly as before the extension, and nothing on the wire breaks the +/// session. +#[moq_clock::test] +async fn an_epoch_crosses_only_when_both_offer_it() { + for name in MOQT { + let version: Version = name.parse().unwrap(); + let negotiable = !matches!(name, "moq-transport-14" | "moq-transport-15" | "moq-transport-16"); + for server_publishes in [true, false] { + for declines in [None, Some("server"), Some("client")] { + let context = format!("{name}, server publishes: {server_publishes}, declines: {declines:?}"); + let publisher = produce_origin(1); + let subscriber = produce_origin(2); + + let mut options = MockConnectOptions::new(version); + match server_publishes { + true => { + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(subscriber.clone()); + } + false => { + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(subscriber.clone()); + } + } + let no_epoch = declined(|e| e.epoch = false); + match declines { + Some("server") => options.server_extensions = no_epoch, + Some(_) => options.client_extensions = no_epoch, + None => {} + } + let pair = connect_mock(options).await; + + let epoch = moq_net::Epoch::mint(); + let broadcast = publisher.create_broadcast("room/cam").unwrap(); + broadcast + .announce(origin::Route::default().with_epoch(epoch.clone())) + .unwrap(); + moq_clock::sleep(SETTLE).await; + + let route = route(&subscriber, "room/cam").unwrap_or_else(|| panic!("{context}: never announced")); + let expected = (negotiable && declines.is_none()).then_some(epoch); + assert_eq!(route.epoch, expected, "{context}"); + assert_open(&pair, &context); + } + } + } +} diff --git a/rs/moq-net/tests/integration/multi_cdn.rs b/rs/moq-net/tests/integration/multi_cdn.rs index bee1aba6acc..6fb67494522 100644 --- a/rs/moq-net/tests/integration/multi_cdn.rs +++ b/rs/moq-net/tests/integration/multi_cdn.rs @@ -6,8 +6,10 @@ //! subscriber `S` links to both, ranking `A` first with //! [`origin::Producer::with_preference`] while pricing `B` cheaper, so only the //! preference puts `A` ahead. Losing `A` moves `S` to `B`, and `A` returning moves it -//! back. Between lite-07 routes with the same epoch each move resumes the subscription. -//! A moq-transport `B` carries no epoch, so each move is a restart and a re-request. +//! back. Between routes with the same epoch each move resumes the subscription, whether +//! `B` speaks lite-07 or moq-transport with the MoQ Epoch extension. A moq-transport `B` +//! that cannot carry the epoch (before draft-17) makes each move a restart and a +//! re-request. use crate::support; @@ -265,12 +267,11 @@ fn assert_continuous(seen: &[(u64, Vec, Option)], groups: u64) { } } -/// Two lite-07 CDNs under one epoch: `S` reads through `A` although `B` is cheaper, -/// resumes on `B` when `A` goes, and moves back once `A` returns, every frame once. -#[moq_clock::test] -async fn preferred_cdn_fails_over_and_back() { +/// Two CDNs under one epoch, `B` over `secondary`: `S` reads through `A` although `B` is +/// cheaper, resumes on `B` when `A` goes, and moves back once `A` returns, every frame once. +async fn fails_over_and_back(secondary: &str) { moq_clock::timeout(TEST_TIMEOUT, async { - let mut topology = Topology::new("moq-lite-07-wip".parse().unwrap()).await; + let mut topology = Topology::new(secondary.parse().unwrap()).await; let mut announced = topology.subscriber.consume().announced(); let start = announced.next().await.expect("announced"); assert!( @@ -306,13 +307,31 @@ async fn preferred_cdn_fails_over_and_back() { .expect("timed out"); } -/// A moq-transport `B` carries no epoch, so `S` cannot resume onto it: losing `A` -/// restarts the path and ends the subscription, and a re-request lands on `B`. `A` -/// returning is another restart, and a re-request lands back on `A`. #[moq_clock::test] -async fn transport_secondary_restarts() { +async fn preferred_cdn_fails_over_and_back() { + fails_over_and_back("moq-lite-07-wip").await; +} + +/// A moq-transport `B` with the MoQ Epoch extension carries `P`'s epoch, so `S` resumes +/// across a chain mixing lite-07 and moq-transport exactly as it does over lite-07 alone. +#[moq_clock::test] +async fn transport_secondary_fails_over_and_back() { + fails_over_and_back("moq-transport-22").await; +} + +/// The same over the first draft that can carry the epoch. +#[moq_clock::test] +async fn transport_17_secondary_fails_over_and_back() { + fails_over_and_back("moq-transport-17").await; +} + +/// A moq-transport `B` before draft-17 carries no epoch, so `S` cannot resume onto it: +/// losing `A` restarts the path and ends the subscription, and a re-request lands on `B`. +/// `A` returning is another restart, and a re-request lands back on `A`. +#[moq_clock::test] +async fn epochless_secondary_restarts() { moq_clock::timeout(TEST_TIMEOUT, async { - let mut topology = Topology::new("moq-transport-22".parse().unwrap()).await; + let mut topology = Topology::new("moq-transport-16".parse().unwrap()).await; let mut announced = topology.subscriber.consume().announced(); let start = announced.next().await.expect("announced"); assert!(via_a(&start), "{start:?}"); diff --git a/rs/moq-net/tests/integration/replacement.rs b/rs/moq-net/tests/integration/replacement.rs index 147c663aea3..12e851fc2a4 100644 --- a/rs/moq-net/tests/integration/replacement.rs +++ b/rs/moq-net/tests/integration/replacement.rs @@ -171,6 +171,26 @@ async fn epoch_lite07() { .expect("timed out"); } +/// moq-transport carries the epoch with the MoQ Epoch extension, from draft-17. +#[moq_clock::test] +async fn epoch_ietf() { + for version in ["moq-transport-17", "moq-transport-22"] { + moq_clock::timeout(TEST_TIMEOUT, replace(version, Some(epoch()))) + .await + .expect("timed out"); + } +} + +/// Without one, a moq-transport replacement restarts as it does over lite. +#[moq_clock::test] +async fn epochless_ietf() { + for version in ["moq-transport-22"] { + moq_clock::timeout(TEST_TIMEOUT, replace(version, None)) + .await + .expect("timed out"); + } +} + /// A route change alone is never fatal, but a dead route is: once an epochless replacement /// is announced, a subscription on the old instance keeps going while the old publisher /// serves it, and its session closing ends that subscription with an error, never cleanly. diff --git a/rs/moq-net/tests/integration/restart.rs b/rs/moq-net/tests/integration/restart.rs index c8be8d7b7ca..9f4be2691c4 100644 --- a/rs/moq-net/tests/integration/restart.rs +++ b/rs/moq-net/tests/integration/restart.rs @@ -333,7 +333,9 @@ async fn dynamic_epoch(version: &str, from: Option, to: Option) { let (fresh, mut subscription) = subscribe(&viewer, "live/cam").await; assert!(!fresh.is_clone(&stale), "{version}: joined the old instance's copy"); assert_eq!(claim.answered(), 2, "{version}: the old answer was served again"); - if version == "moq-lite-07-wip".parse().unwrap() { + // Every wire here but lite-06 carries the epoch: lite-07, and moq-transport with the + // MoQ Epoch extension. + if version != "moq-lite-06".parse().unwrap() { assert_eq!(fresh.info().epoch, to, "{version}: resolved under the old epoch"); } claim.write(1, "new:0"); diff --git a/rs/moq-net/tests/integration/route_change.rs b/rs/moq-net/tests/integration/route_change.rs index 4d0be924341..9191fdfbe18 100644 --- a/rs/moq-net/tests/integration/route_change.rs +++ b/rs/moq-net/tests/integration/route_change.rs @@ -8,9 +8,10 @@ //! every frame exactly once, in order, whether the route changes between groups or //! in the middle of one, and however it changes. //! -//! Older wire versions cannot carry the epoch, so `R` cannot tell the two routes -//! serve the same bytes: its subscription stays on its route and ends with it, while -//! a better route restarts the path for new requests. +//! moq-transport carries the epoch with the MoQ Epoch extension (draft-17+), so it +//! behaves the same. Older wire versions cannot carry the epoch, so `R` cannot tell the +//! two routes serve the same bytes: its subscription stays on its route and ends with +//! it, while a better route restarts the path for new requests. //! //! Two publishers sharing one explicit epoch, a redundant pair, are one source the //! same way. @@ -466,6 +467,9 @@ macro_rules! route_change_tests { route_change_tests! { lite_07: "moq-lite-07-wip", + ietf_17: "moq-transport-17", + ietf_19: "moq-transport-19", + ietf_22: "moq-transport-22", } macro_rules! pinned_tests { @@ -507,8 +511,8 @@ pinned_tests! { lite_06: "moq-lite-06", lite_05: "moq-lite-05", lite_04: "moq-lite-04", - ietf_19: "moq-transport-19", - ietf_22: "moq-transport-22", + ietf_14: "moq-transport-14", + ietf_16: "moq-transport-16", } /// `P` feeds `A` slowly and `B` promptly, and `R` reads through `A` until that route dies @@ -613,6 +617,7 @@ macro_rules! route_flap_tests { route_flap_tests! { flaps_lite_07: "moq-lite-07-wip", + flaps_ietf_22: "moq-transport-22", } /// How the incumbent of a redundant pair goes away. From f76d35498d1734887c2e1bd9262713721924724e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 09:55:10 -0700 Subject: [PATCH 2/7] feat(net): replace a moq-transport epoch make-before-break An epoch change no longer shows the namespace offline. On PUBLISH_NAMESPACE the new epoch is advertised, and the old request withdrawn only once the peer answers it; on a SUBSCRIBE_NAMESPACE stream a NAMESPACE under another epoch replaces the live one with no NAMESPACE_DONE. Gaining or losing an epoch, and any change toward a peer without MoQ Epoch, still withdraws first. A NAMESPACE repeat is a protocol violation only when it adds or drops an EPOCH. Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 17 +-- doc/concept/stats.md | 5 +- doc/setup/upgrade.md | 5 +- drafts/draft-lcurley-moq-epoch.md | 13 +- js/net/src/ietf/publisher.test.ts | 78 +++++++++-- js/net/src/ietf/publisher.ts | 54 +++++++- js/net/src/ietf/subscriber.test.ts | 49 +++++-- js/net/src/ietf/subscriber.ts | 13 +- rs/moq-net/src/ietf/publisher.rs | 177 ++++++++++++++++++++---- rs/moq-net/src/ietf/subscriber.rs | 16 ++- rs/moq-net/tests/integration/restart.rs | 32 +++-- 11 files changed, 367 insertions(+), 92 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index b0b4d5ad671..1199961fc09 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -107,14 +107,15 @@ authorization and hidden names work exactly as without one. of the old instance, so a new subscriber never sees its cached groups. The epoch and the restart message travel on moq-lite 07, which is opt-in. -moq-transport carries the epoch from draft 17 when both sides offer the -[epoch extension](/draft/moq-epoch), on by default, and a restart reaches it as -an end then a start of the path. Older moq-lite versions, older moq-transport -drafts, and a side that declines the extension carry no epoch. Without an -epoch, any other route winning is a restart, even a reconnect over the same -path, since nothing says it serves the same bytes. A peer that ignores the end -and start may keep cached objects of the old run under the same names, so an -end and a start is not a cache flush. +moq-transport carries the epoch from draft 17 when both sides offer the [epoch +extension](/draft/moq-epoch), on by default. A restart onto another epoch is +advertised before the old one is withdrawn, so the path is never absent, and one +that gains or loses an epoch is an end then a start. Older moq-lite versions, +older moq-transport drafts, and a side that declines the extension carry no +epoch. Without an epoch, any other route winning is a restart, even a reconnect +over the same path, since nothing says it serves the same bytes. A peer that +ignores the end and start may keep cached objects of the old run under the same +names, so an end and a start is not a cache flush. `moq` and `moqsink` mint a fresh epoch per run, kept across reconnects, and the RTMP, SRT, and WHIP ingests mint one per connection. Replicas share one by diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 52a82d2e233..e0ab7aa80e1 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -61,8 +61,9 @@ Each announcement carries a fresh [publisher epoch](/concept/moq-lite#publisher- on its route, so a restarted node or a group returning from idle is a new broadcast at the same path: it replaces the old one, and no relay serves it groups cached under the old epoch. A reader treats each epoch as its own set of -counters. The epoch rides moq-lite 07 announcements; over older versions and -moq-transport a reader sees the same change as an end and a start at the path. +counters. The epoch rides moq-lite 07 announcements, and moq-transport draft 17 +and later with the [epoch extension](/draft/moq-epoch); over anything else a +reader sees the same change as an end and a start at the path. An aggregating reader pins each node's subscription to its epoch, and when one publisher is reached through both kinds of link (with and without an epoch), it carries only that path's outgoing counters across the change. diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index db894231a00..04d2f581537 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -50,8 +50,9 @@ These land with the next breaking release. their readers upgraded together. - **Announce restarts.** moq-lite 07 adds `ANNOUNCE_RESTART` (0x3): another publisher instance now serves the prefix. lite-06's `ANNOUNCE_RESTART` is - named `ANNOUNCE_UPDATE`, as it always meant. On moq-lite 06 and older and - moq-transport, a restart is still an end then a start. + named `ANNOUNCE_UPDATE`, as it always meant. moq-transport draft 17 and later + with the epoch extension advertise another epoch before withdrawing the old + one. Elsewhere, a restart is still an end then a start. - **Publisher epochs ride the route** (#4942). moq-lite 07 carries the epoch after the path in `ANNOUNCE_START`, `TRACK`, `SUBSCRIBE`, and `FETCH`. Routes without an epoch no longer resume across routes, so default lite-06 diff --git a/drafts/draft-lcurley-moq-epoch.md b/drafts/draft-lcurley-moq-epoch.md index f996c594996..54377938bc1 100644 --- a/drafts/draft-lcurley-moq-epoch.md +++ b/drafts/draft-lcurley-moq-epoch.md @@ -110,9 +110,14 @@ An advertisement without EPOCH names no instance, so nothing says another advert A publisher includes the EPOCH of the instance it serves in each advertisement to a peer that negotiated this extension. A relay forwards the EPOCH it received unchanged, and MUST NOT include one for an advertisement that arrived without one. -An advertisement's EPOCH is fixed for as long as it stands. -An endpoint replacing the instance behind an advertisement withdraws it (PUBLISH_NAMESPACE_DONE, cancelling the PUBLISH_NAMESPACE, or NAMESPACE_DONE) and advertises again with the new EPOCH. -A receiver MUST close the session with a PROTOCOL_VIOLATION on a NAMESPACE that repeats a live suffix with a different EPOCH, or adds or drops one, without a NAMESPACE_DONE between them. +An advertisement's EPOCH is fixed for as long as it stands, and an update never changes it. +An endpoint replacing one instance with another, both named by an EPOCH, advertises the new instance before it withdraws the old, so the namespace is never absent in between: + +- With PUBLISH_NAMESPACE, it sends a new PUBLISH_NAMESPACE with the new EPOCH, and withdraws the old one (PUBLISH_NAMESPACE_DONE, or cancelling it) after the new one is answered. The two travel on different streams, and the answer is what orders them. +- With NAMESPACE, it repeats the live suffix with the new EPOCH, which replaces the old advertisement with no NAMESPACE_DONE between them. + +An advertisement that gains or loses an EPOCH names no instance on one side, so the endpoint withdraws it and advertises again. +A receiver MUST close the session with a PROTOCOL_VIOLATION on a NAMESPACE that repeats a live suffix and adds or drops an EPOCH, without a NAMESPACE_DONE between them. A withdrawal and the advertisement replacing it can travel on different streams and arrive in either order. A receiver holding several live advertisements of one namespace from a peer treats the one received last as current, so the late withdrawal or update of an older one does not restore the instance it named. @@ -140,7 +145,7 @@ The same separation applies to a joining FETCH, to subscriptions to an old and a # Peers Without This Extension {#downgrade} A relay serves a peer that did not negotiate this extension with the names that peer already uses. -It replaces an instance it advertised to such a peer by withdrawing the advertisement and sending a new one, keeps that peer's established subscriptions on the instance they started on until it ends, and resolves new requests to the current instance. +It replaces an instance it advertised to such a peer by withdrawing the advertisement before sending a new one, since a second advertisement would read as the same instance; it keeps that peer's established subscriptions on the instance they started on until it ends, and resolves new requests to the current instance. A relay MAY hide a move between advertisements of the same instance from such a peer. This is how a relay behaves, not a cache invalidation mechanism. diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 85262a0c32b..6ed63308be8 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1224,29 +1224,81 @@ test("an advertisement carries its epoch only once negotiated", async () => { } }); -/** A new instance at a path is other content, so it is a withdrawal and a fresh advertisement. */ -test("an epoch change withdraws and advertises the new epoch", async () => { +/** + * A new instance at a path is other content, but the namespace never goes absent: the new + * epoch is advertised first, and the old one withdrawn only once the peer accepted it, + * since the two streams are unordered. A peer without MoQ Epoch cannot tell the two apart, + * so it still sees the old one withdrawn first. + */ +test.each([true, false])( + "an epoch change advertises the new epoch before withdrawing the old (negotiated: %p)", + async (negotiated) => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server, { epoch: negotiated }); + const streams = accepted(pair.client); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + const first = Epoch.mint(); + broadcast.announce({ epoch: first }); + void pub.runPublishNamespaces(); + + const old = await take(streams); + expect(await old.reader.u53()).toBe(PublishNamespace.id); + expect((await PublishNamespace.decode(old.reader, VERSION, EPOCH)).params.epoch).toBe( + negotiated ? first : undefined, + ); + await acceptPublishNamespace(old); + + const second = Epoch.mint(); + broadcast.announce({ ...broadcast.route, epoch: second }); + const withdrawn = watch(old.reader.done()); + + const next = await take(streams); + expect(await next.reader.u53()).toBe(PublishNamespace.id); + expect((await PublishNamespace.decode(next.reader, VERSION, EPOCH)).params.epoch).toBe( + negotiated ? second : undefined, + ); + await flush(); + expect(withdrawn.state).toBe(negotiated ? "pending" : "rejected"); + + await acceptPublishNamespace(next); + expect(await old.reader.done().catch(error)).toMatchObject({ code: StreamCode.Cancel }); + } finally { + origin.close(); + } + }, +); + +/** On a SUBSCRIBE_NAMESPACE stream, another epoch is one NAMESPACE and no NAMESPACE_DONE. */ +test("a solicited namespace takes another epoch as one NAMESPACE and no NAMESPACE_DONE", async () => { const pair = createMockTransportPair(ALPN.DRAFT_19); - const { pub, origin } = publisher(pair.server, { epoch: true }); - const streams = accepted(pair.client); + const { pub, origin } = publisher(pair.server, { requiresSolicitation: true, epoch: true }); try { const broadcast = origin.createBroadcast(Path.from("mine")); const first = Epoch.mint(); broadcast.announce({ epoch: first }); - void pub.runPublishNamespaces(); - const old = await take(streams); - expect(await old.reader.u53()).toBe(PublishNamespace.id); - expect((await PublishNamespace.decode(old.reader, VERSION, EPOCH)).params.epoch).toBe(first); - await acceptPublishNamespace(old); + const subscription = await Stream.open(pair.client, { version: VERSION }); + const stream = await Stream.accept(pair.server, VERSION); + if (!stream) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), stream); + const entry = async () => { + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + return await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, EPOCH); + }; + + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, VERSION); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), params: { epoch: first } }); const second = Epoch.mint(); broadcast.announce({ ...broadcast.route, epoch: second }); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), params: { epoch: second } }); - expect(await old.reader.done().catch(error)).toMatchObject({ code: StreamCode.Cancel }); - const next = await take(streams); - expect(await next.reader.u53()).toBe(PublishNamespace.id); - expect((await PublishNamespace.decode(next.reader, VERSION, EPOCH)).params.epoch).toBe(second); + const more = watch(subscription.reader.u53()); + await flush(); + expect(more.state).toBe("pending"); + subscription.close(); } finally { origin.close(); } diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 584b631effb..587b32742c9 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -154,8 +154,11 @@ type Refused = "never" | number; */ type Answer = "held" | "dropped" | Refused; +/** One open PUBLISH_NAMESPACE request. */ +type NamespaceRequest = { path: Path.Valid; requestId: bigint; stream: Stream; auth?: Auth }; + /** The open PUBLISH_NAMESPACE request per advertised path. */ -type Requests = Map; +type Requests = Map; /** What one announce loop knows about the peer, keyed the way that loop names namespaces. */ interface Namespaces { @@ -181,6 +184,13 @@ interface Target { /** Advertise a namespace the peer does not hold. */ advertise(key: Path.Valid, next: Advertised): Promise; + /** + * Replace the instance behind a namespace the peer holds with another (MoQ Epoch): the + * new advertisement goes out before the old is withdrawn, so the peer never sees the + * namespace absent. + */ + replace(key: Path.Valid, next: Advertised): Promise; + /** Reprice a namespace the peer holds: the same broadcast at a new hop chain or cost. */ update(key: Path.Valid, next: Advertised, reprice: Reprice): Promise; @@ -1277,6 +1287,7 @@ export class Publisher { const target: Target = legacy ? { advertise: (suffix, snap) => this.#advertise(Path.join(prefix, suffix), requests, snap.route), + replace: (suffix, snap) => this.#replace(Path.join(prefix, suffix), requests, snap.route), update: (suffix, _snap, reprice) => this.#update(Path.join(prefix, suffix), requests, reprice), withdraw: (suffix) => this.#withdraw(Path.join(prefix, suffix), requests), held: (suffix) => requests.get(Path.join(prefix, suffix))?.auth, @@ -1284,6 +1295,8 @@ export class Publisher { } : { advertise: namespace, + // A repeat under another epoch replaces the instance in place. + replace: namespace, update: namespace, held: () => undefined, carry: () => undefined, @@ -1435,6 +1448,7 @@ export class Publisher { const requests: Requests = new Map(); const target: Target = { advertise: (path, snap) => this.#advertise(path, requests, snap.route), + replace: (path, snap) => this.#replace(path, requests, snap.route), update: (path, _snap, reprice) => this.#update(path, requests, reprice), withdraw: (path) => this.#withdraw(path, requests), held: (path) => requests.get(path)?.auth, @@ -1528,8 +1542,9 @@ export class Publisher { * Bring the peer's view in line with `updated`, one namespace at a time, and report * whether anything it should hold is still missing and worth coming back for. * - * Nothing the peer cannot see is sent, a reprice updates the namespace in place, and - * anything else is withdrawn first so a republish reads as withdraw-then-advertise. + * Nothing the peer cannot see is sent, a reprice updates the namespace in place, another + * epoch replaces it in place (MoQ Epoch), and anything else is withdrawn first so a + * republish reads as withdraw-then-advertise. * `ns` records what the peer holds rather than what we attempted: a declined * advertisement or update stays out of it, so the next turn offers it fresh instead * of believing it is already up. @@ -1552,7 +1567,8 @@ export class Publisher { const held = new Map(ns.active); for (const [key, snap] of ns.active) { - if (this.#change(key, snap, updated.get(key), target) !== "restart") continue; + const next = updated.get(key); + if (this.#change(key, snap, next, target) !== "restart" || this.#replaces(snap, next)) continue; await target.withdraw(key); held.delete(key); } @@ -1565,6 +1581,9 @@ export class Publisher { let answer: Answer; if (prev !== undefined && diff !== "restart") { answer = await target.update(key, snap, diff); + } else if (prev !== undefined) { + // Still held through a restart: another epoch replacing it. + answer = await target.replace(key, snap); } else { // A fresh offer waits for what a refusal asked for, whatever brought us back. if (!this.#offerable(key, ns.refused)) continue; @@ -1619,6 +1638,16 @@ export class Publisher { return { ...(diff === "same" ? {} : diff), token: to }; } + /** + * Whether `next` replaces the instance the peer holds in `held` with another, both named + * by an epoch on the wire (MoQ Epoch). Gaining or losing one is withdrawn and advertised + * afresh, and so is any instance change on a peer that cannot tell them apart. + */ + #replaces(held: Advertised, next: Advertised | undefined): boolean { + const [from, to] = [held.route.epoch, next?.route.epoch]; + return this.#epoch && from !== undefined && to !== undefined && from !== to; + } + /** `auth` when a request of this session can carry it. */ #carry(auth: Auth | undefined): Auth | undefined { return this.#auth?.carried(auth) === undefined ? undefined : auth; @@ -1828,11 +1857,28 @@ export class Publisher { * End a namespace's PUBLISH_NAMESPACE request: PUBLISH_NAMESPACE_DONE then FIN before * draft-17, a cancel in both directions after. */ + /** + * Replace the PUBLISH_NAMESPACE request for `path` with one for another instance. The two + * streams are unordered, so the old one is withdrawn only once the peer answered the new + * one, refused or not: it serves another instance either way. + */ + async #replace(path: Path.Valid, requests: Requests, route: Route): Promise { + const old = requests.get(path); + requests.delete(path); + const answer = await this.#advertise(path, requests, route); + if (old) await this.#end(old); + return answer; + } + async #withdraw(path: Path.Valid, requests: Requests) { const request = requests.get(path); if (!request) return; requests.delete(path); + await this.#end(request); + } + /** Withdraw one PUBLISH_NAMESPACE request, already out of its map. */ + async #end(request: NamespaceRequest) { // Draft-17+ withdraws by cancelling the request in both directions; a FIN is only // allowed to end SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS. const version = this.#session.version; diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index c70a3f9e4d5..b7cb641b364 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -2325,10 +2325,35 @@ test("an inline NAMESPACE route carries its epoch", async () => { }); /** - * A NAMESPACE names its instance until its NAMESPACE_DONE, so a repeat under another one - * means the peer skipped the withdrawal. + * A NAMESPACE repeated under another epoch replaces the instance in place: the path + * restarts and is never absent, and a fresh reader hears the new instance standing. */ -test("a NAMESPACE repeated under another epoch closes the session", async () => { +test("a NAMESPACE repeated under another epoch restarts the path in place", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true), epoch: true }); + const announced = subscriber.announced(); + const subscription = await acceptSubscribeNamespace(pair.client); + + const path = Path.from("room"); + const first = Epoch.mint(); + await inlineEpoch(subscription, path, first); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: { epoch: first } }); + + const second = Epoch.mint(); + await inlineEpoch(subscription, path, second); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "restart", route: { epoch: second } }); + + const fresh = subscriber.announced(); + expect(await fresh.next()).toMatchObject({ prefix: path, kind: "start", route: { epoch: second } }); + fresh.close(); + announced.close(); +}); + +/** + * Gaining or losing an epoch is not one instance replacing another, so a repeat that does + * either means the peer skipped the NAMESPACE_DONE. + */ +test.each(["gains", "loses"] as const)("a NAMESPACE repeat that %s an epoch closes the session", async (change) => { const pair = createMockTransportPair(ALPN.DRAFT_19); const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, quic: pair.server, epoch: true }); @@ -2338,15 +2363,23 @@ test("a NAMESPACE repeated under another epoch closes the session", async () => const subscription = await acceptSubscribeNamespace(pair.client); const epoch = Epoch.mint(); - await inlineEpoch(subscription, Path.from("room"), epoch); + const send = async (path: Path.Valid, named?: Epoch.Valid) => { + await subscription.writer.u53(SubscribeNamespaceEntry.id); + await new SubscribeNamespaceEntry({ suffix: path, params: { epoch: named } }).encode( + subscription.writer, + VERSION, + ); + }; + const [before, after] = change === "gains" ? [undefined, epoch] : [epoch, undefined]; + await send(Path.from("room"), before); expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "start" }); - // Control: a repeat under the same instance is a reprice, not a violation. - await inlineEpoch(subscription, Path.from("room"), epoch); - await inlineEpoch(subscription, Path.from("sentinel"), epoch); + // Control: a repeat that keeps the epoch, or its absence, is not a violation. + await send(Path.from("room"), before); + await send(Path.from("sentinel"), before); expect(await announced.next()).toMatchObject({ prefix: Path.from("sentinel"), kind: "start" }); - await inlineEpoch(subscription, Path.from("room"), Epoch.mint()); + await send(Path.from("room"), after); await violationClosed(pair); }); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 9185a8e1f35..ede6a2fb9cd 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -608,11 +608,10 @@ export class Subscriber { const params = entry.params ?? {}; const held = live.get(path); - // The epoch names the advertisement's instance for as long as it - // stands: a replacement is a NAMESPACE_DONE and a fresh NAMESPACE, - // never a repeat. - if (held !== undefined && held.epoch !== params.epoch) { - throw new ProtocolViolation(`NAMESPACE repeated under another epoch: ${path}`); + // A repeat under another epoch replaces the instance in place, but one + // that gains or loses an epoch skipped the NAMESPACE_DONE it needs. + if (held !== undefined && (held.epoch === undefined) !== (params.epoch === undefined)) { + throw new ProtocolViolation(`NAMESPACE repeated gaining or losing an epoch: ${path}`); } // A repeat updates the advertisement in place, so one that now @@ -628,9 +627,11 @@ export class Subscriber { } // A repeat replaces the advertisement in place: HOP_PATH / ROUTE_COST - // can change without a NAMESPACE_DONE. Only the first is a new path. + // can change without a NAMESPACE_DONE, and another epoch restarts the + // path without it ever going absent. Only the first is a new path. const route = this.#route(params); if (held !== undefined) { + held.epoch = params.epoch; this.#updateAnnounce(path, held.id, route); } else { live.set(path, { id: this.#attachAnnounce(path, route), epoch: params.epoch }); diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 6eb0261d2e9..4a778cb3cf1 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2963,10 +2963,14 @@ where let request = requests.get_mut(suffix); let held_auth = request.as_ref().and_then(|request| request.auth.clone()); let unchanged = advert == watch.sent && auth == held_auth; - // The epoch names the advertisement's instance for as long as it stands, so another - // one withdraws it and advertises afresh (MoQ Epoch). A restart arrives as an end and - // a start, so this only guards a change that skipped one. - let renamed = wanted && held && advert.params().epoch != watch.sent.params().epoch; + // The epoch names the advertisement's instance for as long as it stands, so an + // update never changes it (MoQ Epoch). One instance named by an epoch is replaced + // by another in place, the new advertised before the old is withdrawn, so the peer + // never sees the namespace absent. Gaining or losing an epoch withdraws and + // advertises afresh. + let (held_epoch, epoch) = (watch.sent.params().epoch, advert.params().epoch); + let renamed = wanted && held && held_epoch != epoch; + let replaced = renamed && held_epoch.is_some() && epoch.is_some(); // moq-transport renames a request's auth with REQUEST_UPDATE, but cannot name one on // a request that had none, nor drop one, and before draft-17 cannot update a // namespace at all: those withdraw the request and make it again. @@ -3019,6 +3023,19 @@ where } self.withdraw_namespace(target, requests, suffix.clone()).await?; } + (true, Some(_)) if replaced => { + // Separate streams are unordered, so the old one goes only once the + // peer answered the new one, refused or not: it serves another + // instance either way. + tracing::debug!(broadcast = %absolute, "publish_namespace for another epoch"); + let old = requests.remove(suffix); + refused = self + .advertise_namespace(requests, path, suffix.clone(), advert.params(), auth) + .await?; + if let Some(old) = old { + self.end_request(old).await; + } + } (true, Some(_)) => { tracing::debug!(broadcast = %absolute, renamed, "publish_namespace restart"); self.withdraw_namespace(target, requests, suffix.clone()).await?; @@ -3044,8 +3061,9 @@ where Target::Inline(stream) => { match (advert.wanted(), held) { (true, _) => { - if renamed { - tracing::debug!(broadcast = %absolute, "namespace_done for another epoch"); + // A repeat under another epoch replaces the instance in place. + if renamed && !replaced { + tracing::debug!(broadcast = %absolute, "namespace_done for an epoch gained or lost"); stream.writer.varint(ietf::NamespaceDone::ID).await?; stream .writer @@ -3505,28 +3523,8 @@ where ) -> Result<(), Error> { match target { Target::Requests(_) => { - if let Some(mut request) = requests.remove(&suffix) { - // Draft-17+ withdraws by cancelling the request in both directions; a FIN - // is only allowed to end SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS. - if !matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { - request.stream.reader.abort(&Error::Cancel); - request.stream.writer.abort(&Error::Cancel); - return Ok(()); - } - - // Best effort: the peer may already be gone. - let _ = request - .stream - .writer - .encode_message(&ietf::PublishNamespaceDone { - track_namespace: request.path.as_path(), - request_id: request.request_id, - }) - .await; - - // The withdrawal rides this request's own stream, which drops with it, so - // it needs the acknowledgement before the drop-time reset can discard it. - let _ = request.stream.writer.close().await; + if let Some(request) = requests.remove(&suffix) { + self.end_request(request).await; } } Target::Inline(stream) => { @@ -3542,6 +3540,30 @@ where Ok(()) } + /// Withdraw one PUBLISH_NAMESPACE request, best effort: the peer may already be gone. + async fn end_request(&self, mut request: NamespaceRequest) { + // Draft-17+ withdraws by cancelling the request in both directions; a FIN is only + // allowed to end SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS. + if !matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { + request.stream.reader.abort(&Error::Cancel); + request.stream.writer.abort(&Error::Cancel); + return; + } + + let _ = request + .stream + .writer + .encode_message(&ietf::PublishNamespaceDone { + track_namespace: request.path.as_path(), + request_id: request.request_id, + }) + .await; + + // The withdrawal rides this request's own stream, which drops with it, so it needs + // the acknowledgement before the drop-time reset can discard it. + let _ = request.stream.writer.close().await; + } + /// Close out every open PUBLISH_NAMESPACE request. A no-op for a loop whose entries /// ride the SUBSCRIBE_NAMESPACE stream itself, which retracts them by ending. async fn withdraw_requests( @@ -3999,8 +4021,10 @@ where } NamespaceEvent::Update(Some((update, active, restart))) => { // moq-transport has no restart: the peer sees the namespace end and start - // again, and resubscribes. - if restart { + // again, and resubscribes. One that tells instances apart (MoQ Epoch) takes + // another epoch in place instead, which `sync_namespace` makes before it + // breaks the old. + if restart && !Self::replaces(&ns, &update) { self.apply_update(&mut ns, &prefix, update.clone(), false).await?; } self.apply_update(&mut ns, &prefix, update, active).await?; @@ -4014,6 +4038,16 @@ where res } + /// Whether a restart onto `update` replaces one instance the peer holds by epoch with + /// another, rather than ending the advertisement. + fn replaces(ns: &Namespaces, update: &crate::announce::Announce) -> bool { + let held = ns + .watched + .get(&update.prefix) + .and_then(|watch| watch.sent.params().epoch); + ns.epochs && held.is_some() && update.route.epoch.is_some() && held != update.route.epoch + } + /// Reconcile what the peer holds with one route (un)announce. async fn apply_update( &self, @@ -12676,6 +12710,89 @@ mod tests { ); } + /// MoQ Epoch: a restart onto another epoch advertises the new instance before it + /// withdraws the old, and only once the peer accepted it, since the two streams are + /// unordered. The peer never sees the namespace absent. A peer without the extension + /// cannot tell the two apart, so it still sees the old one withdrawn first. + #[moq_clock::test] + async fn another_epoch_is_advertised_before_the_old_is_withdrawn() { + use crate::lite::test_transport::Sent; + const VERSION: Version = Version::Draft17; + + for epochs in [true, false] { + let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + let _old = origin + .announce("cam", crate::origin::Route::default().with_epoch(crate::Epoch::mint())) + .unwrap(); + settle().await; + + let ok = publish_namespace_ok(VERSION).await; + let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ok.clone(), ok]); + let log = session.log.clone(); + let declared = peer::PeerSetup::default(); + declared.set(peer::Peer { + solicit: Some(false), + epoch: epochs, + ..Default::default() + }); + let publisher = Publisher::new( + crate::time::sim(), + session, + origin.consume(), + Control::new(None, false), + None, + declared, + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + let mut _new = None; + for count in [1, 2] { + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"cam") >= count { + break; + } + settle().await; + } + assert_eq!(occurrences(&log, b"cam"), count, "epochs: {epochs}"); + if count == 1 { + // A newer epoch outranks the old at the same path: a restart. + let route = crate::origin::Route::default().with_epoch(crate::Epoch::mint()); + _new = Some(origin.announce("cam", route).unwrap()); + } + } + for _ in 0..10 { + assert!(futures::poll!(run.as_mut()).is_pending()); + settle().await; + } + + // Where each advertisement went out, and where the first one was withdrawn. + let trail = log.trail(); + let advertised: Vec<(usize, usize)> = trail + .iter() + .enumerate() + .filter_map(|(at, (stream, sent))| match sent { + Sent::Write(bytes) if bytes.windows(3).any(|window| window == b"cam") => Some((at, *stream)), + _ => None, + }) + .collect(); + let [(_, old), (made, new)] = advertised[..] else { + panic!("epochs: {epochs}: expected two advertisements, got {advertised:?}"); + }; + assert_ne!(old, new, "epochs: {epochs}: one request carried both"); + let broken = trail + .iter() + .position(|(stream, sent)| *stream == old && matches!(sent, Sent::Reset(_))) + .unwrap_or_else(|| panic!("epochs: {epochs}: the old advertisement was never withdrawn")); + assert_eq!( + made < broken, + epochs, + "epochs: {epochs}: advertised at {made}, withdrew at {broken}" + ); + } + } + async fn publish_namespace_ok(version: Version) -> Vec { let log = crate::lite::test_transport::Log::default(); let mut writer = crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), version); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 3a50588e2b0..f2debcd77c9 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -643,7 +643,7 @@ impl Advertised { struct Advertisement { /// Names it to [`Subscriber::stop_announce`] and [`Subscriber::update_announce`]. id: u64, - /// The publisher instance it named, which a repeat must not change. + /// The publisher instance it names: a repeat may name another, but not gain or lose one. epoch: Option, } @@ -1231,12 +1231,12 @@ where initial.initial = initial.initial.saturating_sub(1); let path = prefix.join(&msg.suffix); let params = msg.params.unwrap_or_default(); - // The epoch names the advertisement's instance for as long as it stands: a - // replacement is a NAMESPACE_DONE and a fresh NAMESPACE, never a repeat. + // A repeat under another epoch replaces the instance in place, but one that + // gains or loses an epoch skipped the NAMESPACE_DONE it needs. if let Some(held) = live.get(&path) - && held.epoch != params.epoch + && held.epoch.is_some() != params.epoch.is_some() { - tracing::warn!(%path, "namespace repeated under another epoch"); + tracing::warn!(%path, "namespace repeated gaining or losing an epoch"); return Err(Error::ProtocolViolation); } let Some(advert) = self.route(params.cluster.as_ref(), peer) else { @@ -1255,9 +1255,11 @@ where let advert = advert.with_epoch(params.epoch.clone()); tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, epoch = ?params.epoch, "namespace"); - if let Some(held) = live.get(&path) { + if let Some(held) = live.get_mut(&path) { // A repeat replaces the advertisement atomically; nothing is torn - // down merely because an update arrived. + // down merely because an update arrived, and another epoch restarts + // the route without it ever going absent. + held.epoch = params.epoch; self.update_announce(path, held.id, advert)?; } else { match self.start_announce(path.clone(), advert, Admit::Session) { diff --git a/rs/moq-net/tests/integration/restart.rs b/rs/moq-net/tests/integration/restart.rs index 9f4be2691c4..0392f722779 100644 --- a/rs/moq-net/tests/integration/restart.rs +++ b/rs/moq-net/tests/integration/restart.rs @@ -3,8 +3,9 @@ //! A replaced broadcast restarts announce consumers across relays, end to end over //! real sessions, while the subscriptions already on it stay. //! -//! On moq-lite-07 the restart travels as ANNOUNCE_RESTART; older versions and -//! moq-transport carry it as an end and a fresh start. Either way a downstream relay +//! On moq-lite-07 the restart travels as ANNOUNCE_RESTART, and on moq-transport between +//! two epochs as a new advertisement before the old one's withdrawal (MoQ Epoch); older +//! versions and anything epochless carry it as an end and a fresh start. Either way a downstream relay //! retires its copy of the old source, so a new subscriber never sees the old //! instance's cached groups. @@ -50,10 +51,21 @@ async fn next_event(announced: &mut announce::Consumer) -> announce::Event { .expect("announce ended") } -/// Expect the restart of `prefix` as `version` carries it: one restart on lite-07, an -/// end then a start elsewhere. +/// Expect the restart of `prefix` without any epoch, as `version` carries it: one restart +/// on lite-07, an end then a start elsewhere. async fn expect_restart(version: Version, announced: &mut announce::Consumer, prefix: &str) { - let restarts = version == "moq-lite-07-wip".parse().unwrap(); + expect_replaced( + version, + announced, + prefix, + version == "moq-lite-07-wip".parse().unwrap(), + ) + .await +} + +/// Expect the restart of `prefix` as one restart when the wire replaced the instance in +/// place, so the path was never absent, or as an end then a start. +async fn expect_replaced(version: Version, announced: &mut announce::Consumer, prefix: &str, restarts: bool) { match next_event(announced).await { announce::Event::Restart(announce) if restarts => assert_eq!(announce.prefix.as_str(), prefix), announce::Event::End(announce) if !restarts => { @@ -296,7 +308,7 @@ async fn dynamic_epoch(version: &str, from: Option, to: Option) { let _upstream = link(version, &publisher, &relay).await; let _downstream = link(version, &relay, &viewer).await; - let claim = Claim::new(&publisher, from); + let claim = Claim::new(&publisher, from.clone()); let mut announced = viewer.consume().announced(); match next_event(&mut announced).await { announce::Event::Start(announce) => assert_eq!(announce.prefix.as_str(), "live"), @@ -321,9 +333,13 @@ async fn dynamic_epoch(version: &str, from: Option, to: Option) { assert!(same.is_clone(&stale), "{version}: a re-price replaced the broadcast"); assert_eq!(claim.answered(), 1, "{version}: a re-price asked the handler again"); - // Another epoch, or none, is another instance downstream. + // Another epoch, or none, is another instance downstream. lite-07 restarts it in place, + // and so does moq-transport (MoQ Epoch) between two epochs: the new instance is + // advertised before the old is withdrawn, so the path is never absent. + let lite = |name: &str| version == name.parse().unwrap(); + let in_place = lite("moq-lite-07-wip") || !lite("moq-lite-06") && from.is_some() && to.is_some(); claim.update_epoch(to.clone()); - expect_restart(version, &mut announced, "live").await; + expect_replaced(version, &mut announced, "live", in_place).await; // The subscription already open stays on the old answer. claim.write(0, "old:2"); From 185d66dda13e2ff47d9e620a57f94b8e7628ca09 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 11:29:25 -0700 Subject: [PATCH 3/7] test(net): pass the epoch flag to main's new TRACK_STATUS test Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/publisher.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 4284360dac3..f0c3b1eed7d 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -9464,6 +9464,7 @@ mod serve_tests { ietf::TrackStatus::ID, ietf::Body(track_status("room", true, version).into()), stream, + false, ) .unwrap() .await; From e7aaad9fa3ab3bed604c262adc13cb93e23509f9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 11:29:25 -0700 Subject: [PATCH 4/7] fix(net): a repeat under another epoch becomes the newest advertisement A namespace advertised both inline and by a later PUBLISH_NAMESPACE kept routing to the request's old instance when the inline NAMESPACE repeated under a new epoch, since the repeat updated the older entry in place. It now moves to the tail, while a same-instance repeat still re-prices in place. JS also skips a closed announce consumer when the newest advertisement changes, as the end path already did. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/subscriber.test.ts | 23 +++++++++++++++ js/net/src/ietf/subscriber.ts | 8 ++++++ rs/moq-net/src/ietf/subscriber.rs | 45 ++++++++++++++++++++++++++++-- 3 files changed, 74 insertions(+), 2 deletions(-) diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index b7cb641b364..2c4aaae3d57 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -2349,6 +2349,29 @@ test("a NAMESPACE repeated under another epoch restarts the path in place", asyn announced.close(); }); +/** + * A namespace advertised both inline and by a later PUBLISH_NAMESPACE takes another epoch + * from either: an inline repeat under the new epoch is the newest advertisement, not an + * update to the older of the two. + */ +test("a NAMESPACE repeat under another epoch outranks a later PUBLISH_NAMESPACE", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true), epoch: true }); + const announced = subscriber.announced(); + const subscription = await acceptSubscribeNamespace(pair.client); + + const path = Path.from("room"); + const first = Epoch.mint(); + await inlineEpoch(subscription, path, first); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "start", route: { epoch: first } }); + await publishEpoch(pair, subscriber, path, first); + + const second = Epoch.mint(); + await inlineEpoch(subscription, path, second); + expect(await announced.next()).toMatchObject({ prefix: path, kind: "restart", route: { epoch: second } }); + announced.close(); +}); + /** * Gaining or losing an epoch is not one instance replacing another, so a repeat that does * either means the peer skipped the NAMESPACE_DONE. diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index cfb29ec23cc..38132ef313f 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -380,6 +380,12 @@ export class Subscriber { const existing = this.#announced.get(path); const advert = existing?.adverts.find((advert) => advert.id === id); if (existing === undefined || advert === undefined) return; + // A repeat under another epoch is a newer advertisement, so it becomes the newest; + // one of the same instance stays where it is. + if (advert.route.epoch !== route.epoch) { + existing.adverts.splice(existing.adverts.indexOf(advert), 1); + existing.adverts.push(advert); + } advert.route = route; this.#settleAnnounce(path, existing); } @@ -402,6 +408,8 @@ export class Subscriber { const kind = restart ? "restart" : "update"; for (const [consumer, filter] of this.#announcedConsumers) { if (!sees(filter, path)) continue; + // A consumer that closed stays registered until its reader loop notices. + if (consumer.closed.peek() !== undefined) continue; const scope = filter.scope; consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind, route }); } diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 67adbfab49a..a8ebf832265 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2277,8 +2277,14 @@ where match state.broadcasts.entry(path.clone()) { Entry::Occupied(entry) => { let entry = entry.into_mut(); - match entry.adverts.iter_mut().find(|(advert, _)| *advert == id) { - Some((_, held)) => *held = route, + match entry.adverts.iter().position(|(advert, _)| *advert == id) { + // A repeat under another epoch is a newer advertisement, so it becomes the + // newest; one of the same instance stays where it is. + Some(index) if entry.adverts[index].1.epoch != route.epoch => { + entry.adverts.remove(index); + entry.adverts.push((id, route)); + } + Some(index) => entry.adverts[index].1 = route, None => entry.adverts.push((id, route)), } // The newest advertisement stands, and an update to an older one changes @@ -8466,6 +8472,41 @@ mod tests { assert_eq!(routed_now(&consumer, "room/host"), None); } + /// MoQ Epoch: a namespace advertised both inline and by a later PUBLISH_NAMESPACE takes + /// another epoch from either. An inline repeat under the new epoch is the newest + /// advertisement, not an update to the older of the two. + #[moq_clock::test] + async fn a_repeat_under_another_epoch_becomes_the_newest() { + let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); + let consumer = origin.consume(); + let path = crate::Path::new("room/host").to_owned(); + let peer = cluster::Peer::default(); + let (old, new) = (crate::Epoch::mint(), crate::Epoch::mint()); + let advert = |subscriber: &Subscriber<_>, epoch: &crate::Epoch| { + subscriber + .route(None, &peer) + .expect("route") + .with_epoch(Some(epoch.clone())) + }; + let epoch_now = || routed_now(&consumer, "room/host").and_then(|route| route.epoch); + + let inline = advert(&subscriber, &old); + let inline = subscriber.start_announce(path.clone(), inline, Admit::Session).unwrap(); + let request = advert(&subscriber, &old); + let request = subscriber.start_announce(path.clone(), request, Admit::Session).unwrap(); + assert_eq!(epoch_now(), Some(old.clone())); + + let repeat = advert(&subscriber, &new); + subscriber.update_announce(path.clone(), inline, repeat).unwrap(); + assert_eq!(epoch_now(), Some(new.clone()), "the older request kept the old instance"); + + // The old instance's withdrawal leaves the new one standing. + subscriber.stop_announce(path.clone(), request, false).unwrap(); + assert_eq!(epoch_now(), Some(new)); + subscriber.stop_announce(path, inline, false).unwrap(); + assert_eq!(routed_now(&consumer, "room/host"), None); + } + /// Two *separate* advertisements for one namespace refcount a single route: /// it takes both retractions to retract it. #[moq_clock::test] From 0394a863edd4c48a383aabbfdc0c05934b61c3eb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 11:42:39 -0700 Subject: [PATCH 5/7] fix(net): a reflected NAMESPACE stays live on the wire A NAMESPACE that loops back through us detaches its route but stays advertised until its NAMESPACE_DONE, so a later repeat that gains or loses an EPOCH is still refused. The stream now tracks each suffix's epoch apart from its attached route. The epoch draft gains its moq-epoch-00 changelog. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-epoch.md | 8 ++ js/net/src/ietf/subscriber.test.ts | 31 +++++++ js/net/src/ietf/subscriber.ts | 20 ++-- rs/moq-net/src/ietf/subscriber.rs | 141 ++++++++++++++++++++++++----- 4 files changed, 164 insertions(+), 36 deletions(-) diff --git a/drafts/draft-lcurley-moq-epoch.md b/drafts/draft-lcurley-moq-epoch.md index 54377938bc1..a21f4c2d37a 100644 --- a/drafts/draft-lcurley-moq-epoch.md +++ b/drafts/draft-lcurley-moq-epoch.md @@ -188,6 +188,14 @@ The Setup Option is even, so its value is a bare varint; the parameter is odd, s --- back +# Appendix A: Changelog + +## moq-epoch-00 +- The EPOCH Setup Option (0x40B68) negotiates the extension on draft-17 and later. +- The EPOCH parameter (0x40B69), a UUIDv7, names the publisher instance on PUBLISH_NAMESPACE, NAMESPACE, SUBSCRIBE, TRACK_STATUS, and a FETCH that names its track. +- An advertisement's EPOCH is fixed. Another instance named by an EPOCH is advertised before the old one is withdrawn, so the namespace is never absent; one gaining or losing an EPOCH is withdrawn and advertised again. +- A request that carries EPOCH is served only by that instance, and refused as a namespace that does not exist otherwise. + # Acknowledgments {:numbered="false"} diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 2c4aaae3d57..826c60cea32 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -2372,6 +2372,37 @@ test("a NAMESPACE repeat under another epoch outranks a later PUBLISH_NAMESPACE" announced.close(); }); +/** + * A NAMESPACE that loops back through us detaches its route, but the advertisement stays + * live on the wire until its NAMESPACE_DONE: a repeat that restores a clean path while + * losing its epoch is still the violation it would be without the loop. + */ +test("a reflected NAMESPACE keeps its epoch live", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber({ session, quic: pair.server, cluster: { self: SELF, peer: PEER }, epoch: true }); + const warn = spyOn(console, "warn").mockImplementation(() => void 0); + onTestFinished(() => warn.mockRestore()); + const announced = subscriber.announced(); + const subscription = await acceptSubscribeNamespace(pair.client); + + const epoch = Epoch.mint(); + const send = async (hops: Hop[], named?: Epoch.Valid) => { + await subscription.writer.u53(SubscribeNamespaceEntry.id); + await new SubscribeNamespaceEntry({ + suffix: Path.from("room"), + params: { cluster: { hops, cost: 0n }, epoch: named }, + }).encode(subscription.writer, VERSION); + }; + await send([PEER], epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + await send([SELF, PEER], epoch); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "end" }); + + await send([PEER]); + await violationClosed(pair); +}); + /** * Gaining or losing an epoch is not one instance replacing another, so a repeat that does * either means the peer skipped the NAMESPACE_DONE. diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 38132ef313f..74c316ddba8 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -484,7 +484,9 @@ export class Subscriber { // Suffixes live on this stream, with the advertisement each holds and the epoch it named, // so a repeat is recognized as an update to it rather than a second one, which would leak. - const live = new Map(); + // An advertisement stays live on the wire until its NAMESPACE_DONE, even while its + // route is detached (`id` unset) for looping back through us. + const live = new Map(); // Set once the teardown below has given back everything this stream held. The read // loop is not awaited when the local consumer closes first, and closing the stream @@ -628,10 +630,8 @@ export class Subscriber { // over: the path is gone even though the message says active. if (this.#reflected(params.cluster)) { console.debug(`dropping reflected namespace: broadcast=${path}`); - if (held !== undefined) { - live.delete(path); - this.#detachAnnounce(path, held.id); - } + if (held?.id !== undefined) this.#detachAnnounce(path, held.id); + live.set(path, { epoch: params.epoch }); continue; } @@ -639,7 +639,7 @@ export class Subscriber { // can change without a NAMESPACE_DONE, and another epoch restarts the // path without it ever going absent. Only the first is a new path. const route = this.#route(params); - if (held !== undefined) { + if (held?.id !== undefined) { held.epoch = params.epoch; this.#updateAnnounce(path, held.id, route); } else { @@ -651,10 +651,8 @@ export class Subscriber { const path = Path.join(prefix, entry.suffix); const held = live.get(path); - if (held !== undefined) { - live.delete(path); - this.#detachAnnounce(path, held.id); - } + live.delete(path); + if (held?.id !== undefined) this.#detachAnnounce(path, held.id); } else if (msgType === PublishBlocked.id && version === Version.DRAFT_17) { const blocked = await PublishBlocked.decode(stream.reader, version); console.debug(`publish_blocked: suffix=${blocked.suffix} track=${blocked.trackName}`); @@ -704,7 +702,7 @@ export class Subscriber { // pin the path for the session even after the other source withdrew. released = true; for (const [path, held] of live) { - this.#detachAnnounce(path, held.id); + if (held.id !== undefined) this.#detachAnnounce(path, held.id); } live.clear(); } diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index a8ebf832265..7ab434d4784 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -641,10 +641,13 @@ impl Advertised { } } -/// One NAMESPACE a SUBSCRIBE_NAMESPACE stream holds. +/// One NAMESPACE a SUBSCRIBE_NAMESPACE stream holds, live on the wire until its +/// NAMESPACE_DONE whether or not its route is attached. struct Advertisement { - /// Names it to [`Subscriber::stop_announce`] and [`Subscriber::update_announce`]. - id: u64, + /// Names its attached route to [`Subscriber::stop_announce`] and + /// [`Subscriber::update_announce`]; `None` while it loops back through us or falls + /// outside the scope. + id: Option, /// The publisher instance it names: a repeat may name another, but not gain or lose one. epoch: Option, } @@ -1188,7 +1191,9 @@ where ) .await; for (path, advert) in live { - let _ = self.stop_announce(path, advert.id, false); + if let Some(id) = advert.id { + let _ = self.stop_announce(path, id, false); + } } res } @@ -1248,32 +1253,28 @@ where // An update replaces the advertisement it repeats, so a reflected // replacement retracts the route we were holding. Keeping it would // leave subscriptions on a path the peer no longer offers. + // + // The advertisement itself stays live on the wire, epoch and all. tracing::debug!(%path, "dropping reflected namespace"); - if let Some(held) = live.remove(&path) { - let _ = self.stop_announce(path, held.id, false); + let held = live.entry(path.clone()).or_insert(Advertisement { id: None, epoch: None }); + held.epoch = params.epoch; + if let Some(id) = held.id.take() { + let _ = self.stop_announce(path, id, false); } continue; }; let advert = advert.with_epoch(params.epoch.clone()); tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, epoch = ?params.epoch, "namespace"); - if let Some(held) = live.get_mut(&path) { + let held = live.entry(path.clone()).or_insert(Advertisement { id: None, epoch: None }); + held.epoch = params.epoch; + match held.id { // A repeat replaces the advertisement atomically; nothing is torn // down merely because an update arrived, and another epoch restarts // the route without it ever going absent. - held.epoch = params.epoch; - self.update_announce(path, held.id, advert)?; - } else { - match self.start_announce(path.clone(), advert, Admit::Session) { - Ok(id) => { - live.insert( - path, - Advertisement { - id, - epoch: params.epoch, - }, - ); - } + Some(id) => self.update_announce(path, id, advert)?, + None => match self.start_announce(path.clone(), advert, Admit::Session) { + Ok(id) => held.id = Some(id), // The interest names a pattern's literal head, so the peer // legitimately advertises namespaces beneath it that the // scope excludes; those are filtered here, not fatal. @@ -1281,7 +1282,7 @@ where tracing::debug!(%path, "namespace outside the subscribe scope; ignoring"); } Err(err) => return Err(err), - } + }, } } // Only NAMESPACE may come before the counted set is in. @@ -1290,8 +1291,8 @@ where let msg = ietf::NamespaceDone::decode_msg(&mut data, self.version)?; let path = prefix.join(&msg.suffix); tracing::debug!(%path, "namespace_done"); - if let Some(held) = live.remove(&path) { - let _ = self.stop_announce(path, held.id, false); + if let Some(id) = live.remove(&path).and_then(|held| held.id) { + let _ = self.stop_announce(path, id, false); } } _ => { @@ -6042,6 +6043,90 @@ mod tests { ); } + /// A NAMESPACE that loops back through us detaches its route, but the advertisement + /// stays live on the wire until its NAMESPACE_DONE: a repeat that restores a clean path + /// while gaining or losing an epoch is still the violation it would be without the loop. + #[moq_clock::test] + async fn a_reflected_namespace_keeps_its_epoch_live() { + const VERSION: Version = Version::Draft18; + let us = crate::Hop::new(5).unwrap(); + let epoch = crate::Epoch::mint(); + + for (reflected, drops) in [(false, true), (true, true), (true, false)] { + let log = crate::lite::test_transport::Log::default(); + let mut writer = + crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), VERSION); + writer.varint(ietf::RequestOk::ID).await.unwrap(); + writer + .encode(&ietf::RequestOk { + request_id: None, + active: None, + }) + .await + .unwrap(); + let mut adverts = vec![(hop_path(&[7, 9]), Some(epoch.clone()))]; + if reflected { + adverts.push((hop_path(&[7, 5, 9]), Some(epoch.clone()))); + } + adverts.push((hop_path(&[7, 9]), (!drops).then(|| epoch.clone()))); + for (hops, epoch) in adverts { + writer.varint(ietf::Namespace::ID).await.unwrap(); + writer + .encode(&ietf::Namespace { + suffix: crate::Path::new("room"), + params: Some(ietf::AdvertParams { + cluster: Some(cluster::Advert { hops, cost: 0 }), + epoch, + }), + }) + .await + .unwrap(); + } + let script = log.writes.lock().unwrap().clone(); + + let origin = crate::origin::Config::new(us).produce(); + let session = crate::lite::test_transport::ScriptedSession::new(script); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer { + cluster: cluster::Peer { + hop: Some(crate::Hop::new(9).unwrap()), + cost: None, + }, + epoch: true, + ..Default::default() + }); + let mut subscriber = Subscriber::new( + crate::time::sim(), + session.clone(), + origin, + Control::new(None, false), + None, + peer_setup, + us, + None, + VERSION, + tasks, + Default::default(), + ); + + let prefix = subscribe_prefixes(&subscriber.origin).pop().expect("one prefix"); + let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); + let mut run = + std::pin::pin!(subscriber.run_subscribe_namespace(stream, prefix, crate::model::Snapshot::landed())); + let mut result = None; + for _ in 0..100 { + if let std::task::Poll::Ready(done) = futures::poll!(run.as_mut()) { + result = Some(done); + break; + } + settle().await; + } + let violated = matches!(result, Some(Err(ref err)) if is_protocol_violation(err)); + assert_eq!(violated, drops, "reflected: {reflected}, drops: {drops}: {result:?}"); + } + } + /// MoQ Active Count is negotiated, so a REQUEST_OK that breaks the negotiation /// either way is the peer's fault: a count we cannot rely on, or one missing where we /// would otherwise wait on it forever. @@ -8493,12 +8578,18 @@ mod tests { let inline = advert(&subscriber, &old); let inline = subscriber.start_announce(path.clone(), inline, Admit::Session).unwrap(); let request = advert(&subscriber, &old); - let request = subscriber.start_announce(path.clone(), request, Admit::Session).unwrap(); + let request = subscriber + .start_announce(path.clone(), request, Admit::Session) + .unwrap(); assert_eq!(epoch_now(), Some(old.clone())); let repeat = advert(&subscriber, &new); subscriber.update_announce(path.clone(), inline, repeat).unwrap(); - assert_eq!(epoch_now(), Some(new.clone()), "the older request kept the old instance"); + assert_eq!( + epoch_now(), + Some(new.clone()), + "the older request kept the old instance" + ); // The old instance's withdrawal leaves the new one standing. subscriber.stop_announce(path.clone(), request, false).unwrap(); From acbe54de54d820b443641cc07d25c6e6c3b83fe6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 12:02:44 -0700 Subject: [PATCH 6/7] style(net): rustfmt Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 7ab434d4784..013651e14dc 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -1256,7 +1256,9 @@ where // // The advertisement itself stays live on the wire, epoch and all. tracing::debug!(%path, "dropping reflected namespace"); - let held = live.entry(path.clone()).or_insert(Advertisement { id: None, epoch: None }); + let held = live + .entry(path.clone()) + .or_insert(Advertisement { id: None, epoch: None }); held.epoch = params.epoch; if let Some(id) = held.id.take() { let _ = self.stop_announce(path, id, false); @@ -1266,7 +1268,9 @@ where let advert = advert.with_epoch(params.epoch.clone()); tracing::debug!(%path, hops = advert.route.hops.len(), cost = ?advert.route.cost, epoch = ?params.epoch, "namespace"); - let held = live.entry(path.clone()).or_insert(Advertisement { id: None, epoch: None }); + let held = live + .entry(path.clone()) + .or_insert(Advertisement { id: None, epoch: None }); held.epoch = params.epoch; match held.id { // A repeat replaces the advertisement atomically; nothing is torn From e9ba8bdc63e593e75b85d3d04dfb450b665d1e9b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 12:35:37 -0700 Subject: [PATCH 7/7] fix(net): a pinned request never waits for its instance An instance never comes back, so RENDEZVOUS_TIMEOUT on a request pinned to a gone one is refused DOES_NOT_EXIST, as the epoch draft says, not TIMEOUT. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.test.ts | 41 +++++++++++++--------- js/net/src/ietf/publisher.ts | 8 +++-- rs/moq-net/src/ietf/publisher.rs | 56 +++++++++++++++++++++++++++++-- 3 files changed, 84 insertions(+), 21 deletions(-) diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 6ed63308be8..0bc68b8db99 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1335,22 +1335,31 @@ test("a request pinned to another epoch is refused DOES_NOT_EXIST", async () => expect(await refusalCode(await status("room", Epoch.mint()), VERSION)).toBe(missing); expect(await refusalCode(await status("epochless", epoch), VERSION)).toBe(missing); - const subscribe = requestStream(VERSION); - await pub.runSubscribe( - new Subscribe({ - requestId: 7n, - trackNamespace: Path.from("room"), - trackName: "video", - subscriberPriority: 0, - epoch: Epoch.mint(), - }), - subscribe.stream, - ); - const r = subscribe.wire(); - expect(await r.u53()).toBe(RequestError.id); - expect((await RequestError.decode(r, VERSION)).errorCode).toBe( - toRequestCode("does_not_exist", "subscribe", VERSION), - ); + // An instance never comes back, so asking to wait for a gone one changes nothing. + for (const rendezvous of [false, true]) { + for (const [namespace, pinned] of [ + ["room", Epoch.mint()], + ["epochless", epoch], + ] as const) { + const subscribe = requestStream(VERSION); + await pub.runSubscribe( + new Subscribe({ + requestId: 7n, + trackNamespace: Path.from(namespace), + trackName: "video", + subscriberPriority: 0, + rendezvous, + epoch: pinned, + }), + subscribe.stream, + ); + const r = subscribe.wire(); + expect(await r.u53()).toBe(RequestError.id); + expect((await RequestError.decode(r, VERSION)).errorCode).toBe( + toRequestCode("does_not_exist", "subscribe", VERSION), + ); + } + } origin.close(); }); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 587b32742c9..69ba67f56f0 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -448,6 +448,10 @@ export class Publisher { // Legal requests we can't honor are refused one at a time. A subscription that // forwards nothing is only useful to a subscriber that later turns forwarding on, // and serving a Range Filter unfiltered would deliver objects it excluded. + // An instance never comes back, so a request pinned to a gone one is missing, not + // worth waiting for. + const rendezvous = msg.rendezvous && msg.epoch === undefined; + const unsupported = !msg.forward ? "FORWARD=0 not supported" : msg.rangeFilters @@ -476,7 +480,7 @@ export class Publisher { stream.abort(cancel); return; } - refusal = this.#failed(err, "subscribe", msg.rendezvous); + refusal = this.#failed(err, "subscribe", rendezvous); } } @@ -518,7 +522,7 @@ export class Publisher { stream, msg.requestId, SubscribeError.id, - this.#failed(err, "subscribe", msg.rendezvous && failed.code === StreamCode.Unroutable), + this.#failed(err, "subscribe", rendezvous && failed.code === StreamCode.Unroutable), ); return; } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index f0c3b1eed7d..7c8a534b2ca 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1179,6 +1179,9 @@ where // releasing what it holds upstream, and only then is the peer told. `acked` holds the // group stream count once SUBSCRIBE_OK is buffered, which decides how. let mut acked: Option> = None; + // An instance never comes back, so a request pinned to a gone one is missing, not + // worth waiting for. + let rendezvous = msg.rendezvous && msg.epoch.is_none(); let subscribed = { let serve = async { // Stats (subscriptions, viewer refcount, groups/frames/bytes) are counted in @@ -1201,7 +1204,7 @@ where Err(err) => { return Ok(Subscribed::Refused( err.to_string(), - rendezvous_error(err, msg.rendezvous, false), + rendezvous_error(err, rendezvous, false), )); } }; @@ -1211,7 +1214,7 @@ where Err(err) => { return Ok(Subscribed::Refused( err.to_string(), - rendezvous_error(err, msg.rendezvous, true), + rendezvous_error(err, rendezvous, true), )); } }; @@ -1231,7 +1234,7 @@ where Err(err) => { return Ok(Subscribed::Refused( err.to_string(), - rendezvous_error(err, msg.rendezvous, true), + rendezvous_error(err, rendezvous, true), )); } }; @@ -7692,6 +7695,53 @@ mod serve_tests { } } + /// A SUBSCRIBE pinned to a gone instance is refused as missing even when it asks to + /// wait: an instance never comes back, so there is nothing to rendezvous with. + #[moq_clock::test] + async fn a_pinned_request_never_waits_for_its_instance() { + for version in [Version::Draft17, Version::Draft20, Version::Draft22] { + let stale = crate::Epoch::mint(); + let pinned = crate::origin::Route::default().with_epoch(crate::Epoch::mint()); + for (name, route) in [("another epoch", pinned), ("no epoch", crate::origin::Route::default())] { + let mut h = serve_route(version, crate::track::Info::timed(), route); + publish_groups(&mut h, 0); + settle().await; + let expected = unroutable(version).await; + + // Built by hand: we never send RENDEZVOUS_TIMEOUT ourselves. + let encode = |body: &mut Vec| -> Result<(), crate::coding::EncodeError> { + let w = &mut Encoder::new(body, version.into()); + RequestId(REQUEST_ID).encode(w, version)?; + if version == Version::Draft17 { + w.varint(0)?; // required_request_id_delta + } + super::super::namespace::encode_namespace(w, &crate::Path::new("room"))?; + w.string("video")?; + encode_params!(w, version, + 0x04 => 7u64, + super::super::epoch::EPOCH_PARAM => Some(stale.clone()), + ); + Ok(()) + }; + let mut body = Vec::new(); + encode(&mut body).unwrap(); + + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .handle_stream(ietf::Subscribe::ID, ietf::Body(body.into()), stream, true) + .unwrap() + .await; + let wire = h.log.writes.lock().unwrap()[mark..].to_vec(); + assert!( + wire.windows(expected.len()).any(|window| window == expected.as_slice()), + "{version} {name}" + ); + } + } + } + /// An EPOCH on a request breaks a session that did not negotiate MoQ Epoch: the peer /// cannot have learned an instance it was never told about. #[moq_clock::test]