diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index c0f6fc071f2..a08f00c2984 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -13,8 +13,20 @@ upstream bandwidth. Each broadcast carries the list of relays it passed through. That hop list catches loops and picks the shortest route, and every relay breaks ties the same way so the cluster converges instead of flapping. Both wire protocols -carry it: natively on moq-lite, and via the [cluster extension](/draft/moq-cluster) -on moq-transport. +carry it: natively on moq-lite up to moq-lite-06, and via the +[cluster extension](/draft/moq-cluster) on moq-transport. + +moq-lite-07-wip carries no hop list. Each publishing node declares a random +routing identity, and relays run a distance-vector route to it, loop-free by +Babel's feasibility condition, so every claim of one origin shares that route. +The first relay a request reaches picks the origin node, by a hash of the path +and the node's identity that every relay computes alike, and names it on the +request so later hops follow their own route to that node. A relay running both +versions translates: a moq-lite-06 peer's routes enter the route layer as the +relay's own claims, and lite-07 routes reach a moq-lite-06 peer as a hop list +that starts at their origin node. A relay drops a moq-lite-06 route whose hop +list names its own routing identity, since that is one of its claims coming +back. A track from a moq-transport publisher keeps its Object IDs, object properties, and END\_OF\_GROUP status objects across a moq-lite-07 link, since relays @@ -94,8 +106,9 @@ max_hops = 6 ``` The same setting is `--cluster-max-hops` or `MOQ_CLUSTER_MAX_HOPS`. It covers -moq-lite-03 through moq-lite-07-wip and moq-transport drafts 18 through 22 when -the MoQ Cluster extension is negotiated. A forwarded path counts this relay's +moq-lite-03 through moq-lite-06 and moq-transport drafts 18 through 22 when +the MoQ Cluster extension is negotiated. moq-lite-07-wip routes carry no hop +path, so it does not bound them. A forwarded path counts this relay's own hop even when its peer appends it on receipt. Older versions and peers without hop paths hide their depth, which this setting cannot bound. @@ -153,9 +166,10 @@ connect = [{ url = "tls://core-a.internal:4443/", upstream = true }] ## Link costs Add `?cost=N` to a peer URL to route by price instead of hop count. An unpriced -link costs 1, which reproduces plain hop counting. Each relay adds the price of -the link an announcement arrived on before forwarding it, so a route's cost is -the sum of what it crossed. +link costs 1, which reproduces plain hop counting, and 1 is also the minimum: a +cost of 0 is refused. Each relay adds the price of the link an announcement +arrived on before forwarding it, so a route's cost is the sum of what it +crossed. Routing prefers the longest covering prefix, then a fully identified hop list over one holding an anonymous hop (0), then the lowest cost, then the shortest @@ -165,9 +179,15 @@ the same one for a given path. A publisher connected straight to the relay is not hashed at its own path: its newest session wins, so a publisher that restarts takes over from its lingering old session at once. +moq-lite-07-wip carries no hop list, so both hop-list steps drop out: the first +relay ranks the origin nodes announcing a path the same way otherwise, and +remaining ties hash the path with each node's routing identity. Later hops +follow their own route to the node it picked. Routes learned over an older +version rank as above. + ```toml [cluster] -connect = ["https://sibling.same-dc/?cost=0", "https://us-east.example.com/?cost=10"] +connect = ["https://sibling.same-dc/?cost=1", "https://us-east.example.com/?cost=10"] ``` The same policy reads as an object, the only form that accepts `token` and @@ -176,7 +196,7 @@ The same policy reads as an object, the only form that accepts `token` and ```toml [cluster] connect = [ - { url = "https://sibling.same-dc/", cost = 0 }, + { url = "https://sibling.same-dc/", cost = 1 }, { url = "https://us-east.example.com/", cost = 10, token = "PEER_JWT" }, ] ``` @@ -253,11 +273,9 @@ decides which relays receive the cluster token. ## Identity Each relay has a Hop ID: the value it adds to a route's hop list for loop -detection and shortest-path routing. It is random on every start, which is fine -for loop detection but makes a restarted relay look like a new node. Set -`cluster.id` to a stable non-zero 64-bit integer to pin it: below 2^53 if older -browser clients decode it, and below 2^62 to keep loop detection over moq-lite-06 -and older links, which carry a larger id as 0. +detection and shortest-path routing. It is random on every start, so a +restarted relay is a new node to the rest of the mesh, and there is no setting +to pin it. ## Failure detection diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 20b76f970c7..25afa723fda 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -305,7 +305,6 @@ See [Authentication](/bin/relay/auth). connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost prices the link, or use {url, cost, egress, token, upstream} objects. node = "https://us-west.example.com/" # This relay's own URL. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. -id = 12345 # Stable Hop ID across restarts. route_key = "route.key" # Route key; relays sharing the file fail over as one to scoped peers. max_hops = 32 # Longest accepted/forwarded hop path (1 to 32). diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 9a7bd7e0c07..ab340a85df7 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -21,6 +21,7 @@ What you use it for, beyond what the concept page already describes: - **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). - **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over, `None` once the path goes offline, and whatever serves it next, like JS `follow(path)`. `consumer.announced()` lists paths only as present or absent. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance. - **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-webrtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything. +- **Relay by opting into proxying.** On moq-lite-07 (`moq-lite-07-wip`, opt-in) a session sends its peer only the routes to its origin's own claims, so an application never becomes transit for anyone else. A relay built on the library marks the handle it publishes with `origin.clone().with_proxy(true)`, or one consumer with `consumer.with_proxy(true)`, to carry what it learned from other peers too; `moq-relay` does so for every session. Older versions advertise everything either way. - **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` is a server, a client, or both: its first dial announces a hidden client endpoint at `/.client/`, and its first accept a hidden server endpoint at `/.server/`, both used only to route sessions, so grants decide which roles it may take. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(server)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(server, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket). - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error. - **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower. diff --git a/quest/m2/announce-takeover.md b/quest/m2/announce-takeover.md index 7f0c565d315..aab0fa6580a 100644 --- a/quest/m2/announce-takeover.md +++ b/quest/m2/announce-takeover.md @@ -44,8 +44,10 @@ instance rule already covers the claim case and needs no wire message, so this quest removes the predecessor machinery and grows to [XL]. - **Removing ANNOUNCE_TAKEOVER.** Delete the 0x5 message and its codec in - `rs/moq-net/src/lite/announce.rs`, `compress.rs`, `publisher.rs`, - `subscriber.rs` and `replay.rs`; the predecessor tracking in + `rs/moq-net/src/lite/announce.rs`, `compress.rs`, `publisher/routed.rs`, + `subscriber/routed.rs` and `replay.rs`; the route layer's claim lineage + (`Claim::continues` in `rs/moq-net/src/route/node.rs`, fed by `OwnClaims` in + `origin.rs`); the predecessor tracking in `rs/moq-net/src/model/origin.rs` and `front.rs` (the `seen` stamps in `OriginConsumerState` and `PendingFront::via`); relay forwarding in `rs/moq-relay`; and `rs/moq-net/tests/integration/announce_takeover.rs`. diff --git a/quest/m2/cluster-routing/routes/README.md b/quest/m2/cluster-routing/routes/README.md index 56c20efceb8..1816813739e 100644 --- a/quest/m2/cluster-routing/routes/README.md +++ b/quest/m2/cluster-routing/routes/README.md @@ -20,13 +20,14 @@ claim whose withdrawal is already known. 5. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Floor regions have no order, and a repeated region is a violation.** A sorted order would need Rust's `Path` ordering reproduced exactly in JS. Decoding into a map rejects duplicates at the same cost. Superseded the same day by item 10, which removes regions. 6. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **The Hop setup parameter and ANNOUNCE_OK's Hop ID are dropped from lite-07.** Their only roles were path-vector exclusion and the implicit trailing hop. ANNOUNCE_OK reserves no body for a route-key proof: [moq-dev/moq#7937](https://github.com/moq-dev/moq/pull/7937), accepted the same day, proves the route key once per session in SETUP. The live hop-based codec still switches in session integration, as choice 1 requires. 7. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **An echo naming a Route ID that was never ended, or was already echoed, is a violation at the publisher.** The publisher can check this from its live and unacknowledged ids alone, with no growing state. -8. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ANNOUNCE_TAKEOVER keeps its shape, with a Route ID in place of hops, and its predecessor must be under the same route.** [quest/m2/announce-takeover.md](https://github.com/moq-dev/moq/blob/main/quest/m2/announce-takeover.md) deletes the message, so this keeps the change minimal. +8. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ANNOUNCE_TAKEOVER keeps its shape, with a Route ID in place of hops, and its predecessor must be under the same route.** [quest/m2/announce-takeover.md](https://github.com/moq-dev/moq/blob/main/quest/m2/announce-takeover.md) deletes the message, so this keeps the change minimal. Decided 2026-11-06 (maintainer, /quest-complete on [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)), asked whether session integration ports the message or lets lite-07 answer a claim as a restart or start until announce-takeover lands: ✅ **port it**, so a job answering a claim stays a takeover across relays. Rejected: accepting the restart and start. 9. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Unknown announce types stay skipped by length on lite-06+**, as before. An unknown reply type is refused. 10. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ANNOUNCE_FLOOR is a marker, not a region list:** `{Route ID, Revision}`. It closes a batch and certifies the stream's claims for that route across the whole requested prefix as the origin's at that Revision. A publisher that cannot vouch for the whole requested prefix at one Revision still closes the batch, with a floor that certifies nothing, encoded per item 13. Regions, the replacing list, and the 65,535-byte overflow go away. Accepted cost: a relay with partial knowledge of an origin certifies nothing for that route, so a receiver lets its stale claims go only on ROUTE_END. Rejected: one region per message; a multipart atomic list. 11. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Clamped claims collapse to the best one.** When several of a route's claims cover a request's prefix (`live` at cost 10 and `live/a` at cost 1, request `live/a/x`), the publisher presents only the most specific, and when it is withdrawn moves the presented claim to the next covering one with ANNOUNCE_UPDATE or ANNOUNCE_RESTART instead of ending it. No wire change; one live claim per prefix per route holds, and a receiver merges claims at the prefix each stream presents them. Rejected: carrying each claim's ancestor depth. 12. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **A floor certifies only what its own request shows.** A stream whose request did not set `Hidden` certifies nothing about hidden claims. No new wire field. Rejected: isolating differently filtered views. 13. ✅ Decided 2026-11-05 (maintainer): **ANNOUNCE_FLOOR encodes `Revision + 1`, with 0 meaning the floor certifies nothing,** the same offset as `Max Age`. Rust decodes it to `Option`. It replaces a Revision of 2^64-1 as the marker: a huge sentinel is a bad pattern and costs 9 bytes as a lite-07 varint. Rejected: a separate message; a boolean field. 14. ✅ Decided 2026-11-05 (maintainer: "use 0 as a sentinel, or make a new message type"; the agent picked the message): **A held route is ROUTE_HOLD (0xB), `{Route ID}`,** replacing a ROUTE_UPDATE with a Metric of 2^64-1. A metric of 0 is real (the origin's own route), so 0 cannot mark held, and offsetting every metric by one would still leave a held update's seqno and down-only bit meaningless and refused. The message carries only what a hold means, item 4's rule goes away, and a metric is now only bounded by overflow, so the wire refuses no metric. The 2^64-1 Seqno and Revision bounds stay: they are bounds, not markers, leaving room for a ROUTE_REQUEST's successor and for the floor's offset. +15. ✅ Decided 2026-11-06 (maintainer, /quest-complete on [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)), asked whether to amend the handoff contract's "a sender that certifies anything for a route answers every stream" or keep it: ✅ **send a route on a stream only while it meets the stream's interest**, with a floor certifying the last withdrawal before the route ends. Withdrawals still END, and what a node keeps per stream it answers is bounded by the origins that stream reads, at a ROUTE_END round trip when an origin leaves an interest. Rejected: keep answering every stream and bound only by per-peer caps, which is simpler but carries the whole node table on every stream. [Route session integration](/quest/m2/cluster-routing/routes/session.md) implements it. The route layer's core landed in @@ -330,10 +331,14 @@ loss never reports an END: delivered (`a_lost_scope_keeps_newer_knowledge_where_still_certified`). Otherwise a wildcard above both was last learned through the lost floor and is unknown at the kept floors' revision, so the view is rebuilt from the - neighbours' last views, a collection of that region. A sender that - certifies anything for a route answers every stream, even one whose - interest none of its regions meets, so its peer learns it certifies nothing - there rather than waiting (`a_disjoint_interest_is_answered_with_nothing`). + neighbours' last views, a collection of that region. A sender sends a + route on a stream only while the route meets the stream's interest (Plan + item 15): it starts the route before its first claim in or covering the + interest, and when the last such claim goes it sends a floor certifying the + withdrawal, then ends the route. A peer therefore holds no route, and + waits on no certifier, for an origin its interest does not meet. The router + still answers every stream until session integration scopes it + (`a_disjoint_interest_is_answered_with_nothing`). A claim is available only through a certifier that is not held; another scope's usable route cannot serve it. A certifier that has not answered yet counts as serving, as for a new next hop whose announcements trail its diff --git a/quest/m2/cluster-routing/routes/js.md b/quest/m2/cluster-routing/routes/js.md index 0426fdc7758..2c5126b740e 100644 --- a/quest/m2/cluster-routing/routes/js.md +++ b/quest/m2/cluster-routing/routes/js.md @@ -18,6 +18,18 @@ Decided 2026-10-27 (maintainer), from the cheapest one; fix it with the route-selection rework here. - Feed the availability API from [Announcement availability](/quest/m2/cluster-routing/routes/availability.md). - Rust/JS interop covers the route messages, the floor marker, and the echo. +- Restore the native JS lite-07 lanes. Decided 2026-11-06 (maintainer, + /quest-complete on [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)), + asked how to handle the in-tree lanes running JS on lite-07-wip once the + Rust side moved to the route wire: ✅ **skip them until this quest lands**, + so the nightly report stays meaningful. Rejected: leave them red; hold + #8023 for this quest. Every skip names this quest (`grep -rn routes/js.md + test rs`): `JS_LITE07_SKIP` in `test/interop/interop.sh` and `socket.sh` + (native JS grant printing, claims, track replacement, sockets, the browser + route key proof, the lite-07 compress and drop legs, the compressed catalog's lite-07 reader, and + `--versions moq-lite-07-wip` with JS clients), `lite_tracks_interop` in + `test/justfile`, and the lite-07 legs of `max_age_relay_javascript` and + `relay_fill_javascript`. ## Required diff --git a/quest/m2/cluster-routing/routes/session.md b/quest/m2/cluster-routing/routes/session.md index a6f2c1a9dc0..9afc6653e1c 100644 --- a/quest/m2/cluster-routing/routes/session.md +++ b/quest/m2/cluster-routing/routes/session.md @@ -1,150 +1,45 @@ -# [XL] Route session integration +# [L] Route session integration: bounded state ## Goal -One `Router` per origin node, fed by every lite-07 session, drives that -node's origin and every announce stream it answers. Its shown claims and -selected routes become the origin's routes, its outbox becomes each -stream's ROUTE and ANNOUNCE messages, and the first hop pins each request -to the identity it selected. A lite-06 peer is translated at the relay. A -peer can make the router hold only bounded state. The configuration -changes the contract decided ship with it. - -lite-07's live wire switches to the route layer that -`drafts/draft-lcurley-moq-lite.md` specifies, in Rust: ANNOUNCE_START, ANNOUNCE_UPDATE, ANNOUNCE_RESTART, and -ANNOUNCE_TAKEOVER name a Route ID and carry the Announce Cost in place of -the Hop ID list (`HopsRef`, `Hop Base`/`Hop Keep`, and `cluster.max_hops` -go from lite-07); ANNOUNCE_OK loses its Hop ID and SETUP its Hop parameter; -TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS carry the Node ID; a Cost -parameter of 0 is refused; the subscriber sends ROUTE_REQUEST and echoes -ROUTE_END. The new messages' codecs already exist (`AnnounceBroadcast`'s -route variants and `AnnounceReply`); until this lands the subscriber -refuses route messages. A hop-less ANNOUNCE cannot run before the router -drives sessions, which is why the switch lands here. +The route layer drives every lite-07 session +([#8023](https://github.com/moq-dev/moq/pull/8023)): one `route::Node` per +origin, Route IDs on the wire, requests pinned to the first hop's origin node, +lite-06 translated at the relay. What remains: the state a node keeps per +stream it answers is bounded by the origins that stream reads, not the whole +node table, and the public API drops what the route layer replaced. ## Plan - Scope route state to interested origins, not the CDN's whole node table. - Send a route before any announcement referencing it. The epic's handoff contract - defines held routes, letting go, and collection. -- ✅ Decided 2026-10-15 (maintainer): retract and re-file when a session's - grant union crosses the scoped boundary in either direction (a `**` token - added, or its expiry). Every forwarded route the session delivered is - retracted, and its current advertisements are re-filed under the new key, - so no route, feasibility distance, or alias stays under the old one. - Expiry cannot be refused, so refusing the transition was not an option. -- Only the first hop selects the origin. It keeps `route_order`'s shape over - the origin nodes announcing the path: longest prefix, newest epoch (within - one instance only, per [Instance and epoch](https://github.com/moq-dev/moq/pull/7489), - decided 2026-10-30), the link's priority (`origin::Producer::with_preference`), seed plus route - metric, then a rendezvous hash of the path and the identity, and the newest - connection only for an otherwise identical route. The hash drops the hop - chain, which differs per node, so every node agrees on a pool member - (`pool_ties_agree_only_on_a_path_and_identity_hash`). The request then names - that identity, and every later hop follows its own route to it, so - forwarding needs a route but not the claim. -- Reselecting the origin at every hop loops although each origin's routes are - loop-free (RFC 8966 s2.7): a ring of same-epoch origins whose relays - prioritize different links, and nested wildcards where a relay has not - heard the specific claim, both cycle past requester exclusion; joining - another relay's subscription by path or instance deadlocks; and without an - instance a later hop splices another publisher under the requester's - announcement with no Restart (`local_priorities_loop_path_only_requests`, - `overlapping_wildcards_loop_where_specific_claims_are_unheard`, - `aggregation_cycles_starve_without_a_forwarding_constraint`, - `reselection_without_an_instance_splices_another_publisher`, - `sweep_forwarding_progress`). A relay therefore joins a forwarded request - only to a subscription following its route to the same identity. When that - identity becomes unreachable the forwarded request ends, and the first hop - re-resolves, resuming only on a matching epoch. A request carrying a cost - bound instead also never loops, but stalls where a transit hop has not - heard the claim and still splices epochless sources. -- Mixed versions: a lite-06 peer keeps today's path vector, translated at the - relay that speaks both, for the rollout window only. -- Interest changes: key the router by announce stream, not session. The old - stream stays open, its routes counting and its batches discarded, until - the new stream has answered, so no route drops in between. A stream is - just another neighbor key to the router. -- A batch carries changes against the last batch on its stream. Restricting - a view to an interest is still linear in that origin's claims per change; - make it incremental here. -- Decided 2026-11-05 (maintainer, /quest-plan, the epic's Plan items 10 to - 12): each stream's floor is a whole-interest marker. Project the router's - per-region view onto it, certifying nothing unless the view knows the - route's claims across the stream's interest at one revision; present per - route only the most specific claim covering the interest, moved rather - than ended when it is withdrawn; and certify absence only for what the - stream's `Hidden` filter shows. Rerun the handoff sweeps through that - projection: a scope a relay lost now goes offline downstream only on - ROUTE_END, the accepted cost, so update the scoped fixtures' expectations - to it, while no sweep may revive a known withdrawal or report a false END. - Also cover a fresh claim that arrives only on an uncertified stream while - an older certified floor on another stream proves it absent - ([review](https://github.com/moq-dev/moq/pull/7764#discussion_r4485081975)): - the merge rule hides it until the certifying peer refreshes or lets go, - and the test pins that bound. -- Bound what a peer makes the router hold (routes, claims, views per - session) by design, as the session caps announcements today. -- Public API: the route-change surface on `broadcast::Route` and its - bindings will likely change, `Hops` and saturating `Cost` go, zero-cost - links are refused (update `?cost=0` examples and report the breaking - configuration change), a per-connection `proxy` preference is added, and - `cluster.id`/`--cluster-id` is removed rather than kept as an unused label - (decided 2026-10-13). `Preference` continues to rank feasible transit - routes; report it. -- Open, for the implementer to settle and record: how much of today's route - trie, fronts, and `route_order` survives intact. - -Decided 2026-10-27 (maintainer): the route layer deletes the epochless instance -machinery in `rs/moq-net/src/model/origin.rs`: `Instance::Route(generation)` -and its renewals, `restarted_since`, the held-restart Release for epochless -routes, and Selection retirement, leaving Follow's same-epoch -Update/Restart split as the only takeover rule. Once each origin is its own -ANNOUNCE and the first hop pins the request to its identity, the first hop's -route is the instance, so the per-hop renewal has nothing left to protect. -An epochless change of serving route stays a Restart, including the -same-origin next-hop change with no epoch (test it), and the routing -contract's epochless fixtures keep passing. Minting an epoch for every route -instead was tried and rejected -([moq-dev/moq#6948](https://github.com/moq-dev/moq/pull/6948)): each relay -mints at its own time, so mint order outranks cost, preference, and the -local-broadcast tie and relays disagree on a pool path's winner, while -ranking a minted epoch last keeps the renewal it was meant to delete. - -Moved 2026-10-30 (maintainer, the [route epic](https://github.com/moq-dev/moq/blob/1a6ac473d75fcbfd5d23bdbdfd64eb4750b077ad/quest/m1/api-audit/route/README.md)): -[Instance and epoch](https://github.com/moq-dev/moq/pull/7489) now deletes that -epochless machinery, so the route layer no longer does. A session mints -an `instance` (`~` plus random bits) for any route that -arrives without one, and newest-wins compares epochs only within one -instance, so mint order no longer outranks cost or preference. The rest of -the 2026-10-27 decision stands. The broadcast epoch fields here become that -publisher instance and its per-instance epoch, in place of the UUIDv7 -epoch. The route layer's own origin-node identity, with its seqno and -revision, stays separate ("keep administrative identity and broadcast epoch -separate", in the epic). - -Decided 2026-11-05 (maintainer, /quest-plan): a scoped peer's identities -are keyed by a route key the peer proves in its lite-07 SETUP: the session's -`PeerSetup::route_key` once its SETUP arrives, and `None` for a peer that proved -none. Relays set theirs with `--cluster-route-key`. Every identity a scoped, proven peer sends, its own included, is qualified -under its proven key, so relays sharing a key file fail over as one. A peer that proves no -key gets a per-session key. `Scope::qualify` still takes the key from the -caller, so this quest does not wait on the proof. Options shown: - -- ✅ A route key the peer proves once per session in SETUP, before the lite-07 cut - (2026-11-05, maintainer, /quest-plan; supersedes the per-announce proof option) -- A route label carried in the grant (the earlier recommendation), with the - proven key added after the cut -- A per-session key now -- A key the relay operator configures per scoped remote - -Research behind it: proving a neighbor's own key cannot remove qualification, -since a public key is public and a scoped peer could still forward a victim's -key with an inflated seqno; origin-signed routes still leave cost lies and -blackholing, at the price of per-update signatures and expiry refreshes. Keyed -by a proven key, every remaining attack stays inside the forger's grant, with -no grant field, no issuer-coordinated labels, and support for token-less -admission. + Today the router advertises every route to every watching stream. The + epic's handoff contract now has a sender send a route on a stream only + while it meets the stream's interest, with a floor certifying the last + withdrawal before the route ends (`routes/README.md` Plan item 15, decided + 2026-11-06): start the route before its first claim in or covering the + interest, and end it after the floor that certifies its last such claim's + withdrawal. Update `a_disjoint_interest_is_answered_with_nothing` to match. + What a peer makes the router hold is already capped: each route and claim + it sends takes one of the session's announce slots + (`a_lite07_claim_past_the_cap_closes_the_session`). What this bounds is + the state this node keeps per stream it answers. +- Present incrementally. `View::present` walks every claim of a route per + change and per interest (`Router::advertise`), so a large origin costs + linear work per update. Do it with the scoping change, which reshapes the + same per-stream presentation. +- Public API: `Hops`, `RouteInfo::hops`, and the saturating `Cost` stay while + lite-06 and the moq-transport cluster extension still carry hop chains. + Remove them, or hide them behind those wires, when the rollout window + closes (see Waiting). + +## Waiting + +- Maintainer: decide when `Hops`, `RouteInfo::hops`, and the saturating + `Cost` leave the public API. Every older wire still fills them, so an agent + cannot drop them without picking the rollout's end. Options: **when lite-06 + retires (recommended)**, since removing them now only moves them behind a + private type; or **now**, keeping a private chain type for the older wires. + Done when the Plan item above names the point. ## Related diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 3888d4bccdb..b366ff3357c 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -555,7 +555,7 @@ impl MoqSide { /// The cluster this process publishes and subscribes on, with the driver that /// must run for as long as it serves. Built once; the origin is its origin, whose - /// Hop ID is random per run unless `--cluster-id` names the node. + /// Hop ID is random per run. pub fn cluster(&self) -> anyhow::Result<(moq_relay::cluster::Cluster, moq_relay::cluster::Driver)> { moq_relay::cluster::Cluster::new(moq_relay::cluster::Options::new(self.cluster.clone())) } @@ -2682,7 +2682,7 @@ mod tests { ("--cluster-api-url", "https://api.example/peers", "--cluster-api-url"), ("--cluster-node", "https://self.example", "--cluster-node"), ("--cluster-token", "cluster.jwt", "--cluster-token"), - ("--cluster-id", "1", "--cluster-id"), + ("--cluster-max-hops", "8", "--cluster-max-hops"), ("--cluster-tier", "internal", "--cluster-tier"), ] { let cli = Invocation::try_parse_from(["moq", flag, value, "auth", "generate"]).unwrap(); diff --git a/rs/moq-hls/tests/integration/restart.rs b/rs/moq-hls/tests/integration/restart.rs index daa5f750793..2e8edfd4234 100644 --- a/rs/moq-hls/tests/integration/restart.rs +++ b/rs/moq-hls/tests/integration/restart.rs @@ -27,6 +27,9 @@ enum Case { /// As [`Self::Unanswered`], with the old run finished just before the new instance /// announces. FinishedFirst, + /// As [`Self::FinishedFirst`], with the old run's end delivered before the new instance + /// announces, so nobody reads its finished track when the restart ends its front. + FinishedSettled, } async fn takeover(version: &str, case: Case) { @@ -62,6 +65,10 @@ async fn takeover(version: &str, case: Case) { // Paused, the clock only moves once every task is idle, so the feed has its answer. Case::Answered => kio::clock::sleep(Duration::from_millis(500)).await, Case::FinishedFirst => old.finish(), + Case::FinishedSettled => { + old.finish(); + kio::clock::sleep(Duration::from_millis(500)).await; + } Case::Unanswered | Case::UnansweredUnfinished => {} } @@ -101,7 +108,7 @@ async fn takeover(version: &str, case: Case) { // The old run ends, while the new one carries on past the old run's last group unless it // leaves that group open. - if !matches!(case, Case::FinishedFirst) { + if !matches!(case, Case::FinishedFirst | Case::FinishedSettled) { old.finish(); } if !matches!(case, Case::UnansweredUnfinished) { @@ -147,6 +154,11 @@ async fn finished_first() { takeover("moq-lite-07-wip", Case::FinishedFirst).await; } +#[tokio::test(start_paused = true)] +async fn finished_settled() { + takeover("moq-lite-07-wip", Case::FinishedSettled).await; +} + /// Read `cursor` until it ends, asserting each segment carries only the old run's media. async fn drain_old(cursor: &mut segments::Consumer) -> (Vec, moq_hls::Result<()>) { let mut read = Vec::new(); diff --git a/rs/moq-mux/src/container/test_util.rs b/rs/moq-mux/src/container/test_util.rs index 7cb82777fd4..2d217cc286e 100644 --- a/rs/moq-mux/src/container/test_util.rs +++ b/rs/moq-mux/src/container/test_util.rs @@ -354,9 +354,10 @@ impl Link { gate: gate.clone(), answers: true, }; + // `from` may be a middle hop, so it forwards what it learned as well as its own. let client = moq_net::Client::new() .with_versions(version.into()) - .with_publisher(from.consume()); + .with_publisher(from.consume().with_proxy(true)); let server = moq_net::Server::new() .with_versions(version.into()) .with_subscriber(to.clone()); @@ -408,7 +409,7 @@ impl Link { .with_subscriber(to.clone()); let server = moq_net::Server::new() .with_versions(version.into()) - .with_publisher(from.consume()); + .with_publisher(from.consume().with_proxy(true)); let sessions = tokio::join!( async { let (session, driver) = client diff --git a/rs/moq-net-tests/tests/integration/hop_limit.rs b/rs/moq-net-tests/tests/integration/hop_limit.rs index 84ef63e2785..8c36f23ec50 100644 --- a/rs/moq-net-tests/tests/integration/hop_limit.rs +++ b/rs/moq-net-tests/tests/integration/hop_limit.rs @@ -27,7 +27,8 @@ fn forward(origin: &origin::Producer, path: &str, route: origin::RouteInfo) -> o } /// A permissive source sends an over-limit path to prove ingress refusal; an -/// accepted boundary path then proves egress counts the relay's own stamp. +/// accepted boundary path then proves egress counts the relay's own stamp. Lite-07 +/// carries no hop chain: its routes are loop-free by feasibility instead. #[kio::test] async fn hop_limit_bounds_receive_and_send() { for name in [ @@ -35,7 +36,6 @@ async fn hop_limit_bounds_receive_and_send() { "moq-lite-04", "moq-lite-05", "moq-lite-06", - "moq-lite-07-wip", "moq-transport-18", "moq-transport-22", ] { @@ -95,8 +95,9 @@ async fn hop_limit_bounds_receive_and_send() { /// withdraws only once no in-cap route is left. #[kio::test] async fn hop_limit_falls_back_to_a_forwardable_route() { - // Only wires carrying a route cost can rank a longer route first. - for name in ["moq-lite-06", "moq-lite-07-wip", "moq-transport-18", "moq-transport-22"] { + // Only wires carrying a route cost can rank a longer route first, and only those + // carrying a hop chain cap it: lite-07 carries none. + for name in ["moq-lite-06", "moq-transport-18", "moq-transport-22"] { let version = name.parse().unwrap(); let near = produce_origin(1); let far = produce_origin(4); diff --git a/rs/moq-net-tests/tests/integration/restart.rs b/rs/moq-net-tests/tests/integration/restart.rs index d31805f15b9..3dcd2cfffd3 100644 --- a/rs/moq-net-tests/tests/integration/restart.rs +++ b/rs/moq-net-tests/tests/integration/restart.rs @@ -210,25 +210,12 @@ impl Worker { } } -/// The worker that wins `path` among `workers`: the lowest spread hash of the path and its -/// instance, which every relay computes alike (`instance_key` in `moq-net`). -fn spread(path: &str, workers: &[u64]) -> String { - let key = |hop: &u64| { - let mut hash: u64 = 0x420C0DECB00B; - for byte in path.bytes().chain(format!("worker-{hop}").into_bytes()) { - hash = (hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3); - } - hash - }; - workers.iter().min_by_key(|hop| key(hop)).unwrap().to_string() -} - -/// Workers `10` and `11` claim `pool` behind `U -> D`, each under its own instance. `U` -/// spreads the pool's paths over them, but advertises one route for `pool`, its own winner -/// for the prefix, and `D` names that route's instance on every request it forwards, so -/// every hop serves the instance the first one chose: behind `D` the pool collapses onto -/// that one worker. Worker `12` joining takes `U`'s requests for the paths it wins, and -/// `D`'s whenever `U` advertises it for `pool`. +/// Workers `10` and `11` claim `pool` behind `U -> D`, each under its own instance, and +/// lite-07 routes each claim to its own origin node. Only the first hop selects the +/// origin, by a rendezvous hash of the path and the origin's identity that every node +/// computes alike, so `D` spreads the pool's paths over the workers exactly as `U` does +/// and names the chosen origin on every request it forwards. Worker `12` joining takes +/// over only the paths it wins, at both. async fn prefix_pool(version: &str) { let version: Version = version.parse().unwrap(); let upstream = produce_origin(2); @@ -241,53 +228,52 @@ async fn prefix_pool(version: &str) { } settle().await; - // The worker whose instance `D`'s route for `pool` names. + // `D`'s route for `pool` names one of the workers. let advertised = |announce: announce::Announce| { assert_eq!(announce.prefix.as_str(), "pool"); let instance = announce.route.instance().clone(); - instance.as_str().strip_prefix("worker-").expect("a worker").to_string() + assert!(instance.as_str().starts_with("worker-"), "{instance:?}"); }; let mut announced = downstream.consume().routes(); - let mut prefix = match next_event(&mut announced).await { + match next_event(&mut announced).await { origin::RouteEvent::Start(announce) => advertised(announce), other => panic!("{version}: expected the pool, got {other:?}"), + } + + // The worker serving `path` at `U`, which `D` must agree on. + let served = async |path: &str| { + let (_broadcast, mut subscription) = subscribe(&upstream, path).await; + let at_upstream = read(&mut subscription).await; + let (_broadcast, mut subscription) = subscribe(&downstream, path).await; + assert_eq!(read(&mut subscription).await, at_upstream, "{version}: {path} at D"); + at_upstream }; let paths = ["pool/job-0", "pool/job-1", "pool/job-2", "pool/job-3"]; - let mut held = Vec::new(); + let mut before = Vec::new(); for path in paths { - let (broadcast, mut subscription) = subscribe(&downstream, path).await; - assert_eq!(read(&mut subscription).await, prefix, "{version}: {path}"); - held.push((broadcast, subscription)); - let (_broadcast, mut subscription) = subscribe(&upstream, path).await; - assert_eq!( - read(&mut subscription).await, - spread(path, &[10, 11]), - "{version}: {path} at U" + let worker = served(path).await; + assert!( + ["10", "11"].contains(&worker.as_str()), + "{version}: {path} served by {worker}" ); + before.push(worker); } - assert!( - paths.iter().any(|path| spread(path, &[10, 11, 12]) == "12"), - "the paths must exercise the joining worker" - ); links.push(link(version, &workers[2].origin, &upstream).await); settle().await; while let Ok(Some(event)) = kio::clock::timeout(Duration::from_secs(1), announced.next()).await { match event { - origin::RouteEvent::Restart(announce) => prefix = advertised(announce), + origin::RouteEvent::Restart(announce) => advertised(announce), other => panic!("{version}: expected a restart at most, got {other:?}"), } } - for path in paths { - let (_broadcast, mut subscription) = subscribe(&downstream, path).await; - assert_eq!(read(&mut subscription).await, prefix, "{version}: {path}"); - let (_broadcast, mut subscription) = subscribe(&upstream, path).await; - assert_eq!( - read(&mut subscription).await, - spread(path, &[10, 11, 12]), - "{version}: {path} at U" + for (path, before) in paths.into_iter().zip(before) { + let worker = served(path).await; + assert!( + worker == before || worker == "12", + "{version}: {path} moved from {before} to {worker}, not to the joining worker" ); } } @@ -693,16 +679,14 @@ impl Pool { } } -/// Wake the worker for `path` through the claim and subscribe. moq-lite-07 announces the -/// answer as a takeover of the claim, so the first subscription keeps reading. Older wires -/// carry it as an ordinary announcement, which resets the first subscription through the -/// claim, so they wake the worker first and subscribe through the exact route. -async fn claimed(version: Version, origin: &origin::Producer, path: &str) -> (broadcast::Consumer, track::Subscriber) { - if version != "moq-lite-07-wip".parse().unwrap() { - let cold = origin.consume().request(path, None).await.unwrap(); - drop(cold.track("video").unwrap().subscribe(None).await); - settle().await; - } +/// Wake the worker for `path` through the claim and subscribe. Wake the worker first and +/// subscribe through the exact route, so the test reads the same on every wire, whether +/// it carries the answer as a takeover or as an ordinary announcement that resets the +/// first subscription through the claim. +async fn claimed(origin: &origin::Producer, path: &str) -> (broadcast::Consumer, track::Subscriber) { + let cold = origin.consume().request(path, None).await.unwrap(); + drop(cold.track("video").unwrap().subscribe(None).await); + settle().await; subscribe(origin, path).await } @@ -719,11 +703,11 @@ async fn claim_restart(version: &str) { let pool = Pool::new(&worker); settle().await; - let (_sibling, mut sibling) = claimed(version, &edge, "pool/q").await; + let (_sibling, mut sibling) = claimed(&edge, "pool/q").await; pool.write("pool/q", "q:0"); assert_eq!(read(&mut sibling).await, "q:0", "{version}"); - let (old, mut first) = claimed(version, &edge, "pool/p").await; + let (old, mut first) = claimed(&edge, "pool/p").await; for group in 0..3 { pool.write("pool/p", &format!("old:{group}")); assert_eq!(read(&mut first).await, format!("old:{group}"), "{version}"); @@ -732,7 +716,7 @@ async fn claim_restart(version: &str) { pool.close("pool/p"); settle().await; - let (fresh, mut returning) = claimed(version, &edge, "pool/p").await; + let (fresh, mut returning) = claimed(&edge, "pool/p").await; assert!(!fresh.is_clone(&old), "{version}: joined the old output"); assert_eq!(*pool.answered.borrow(), 3, "{version}: the worker was not asked again"); pool.write("pool/p", "new:0"); diff --git a/rs/moq-net/benches/announce.rs b/rs/moq-net/benches/announce.rs index 519642cd6db..55372555a20 100644 --- a/rs/moq-net/benches/announce.rs +++ b/rs/moq-net/benches/announce.rs @@ -9,8 +9,10 @@ //! //! - health: `/private/channel_N/stream-health-` from a few origins behind //! a shared pair of relays, the shape that motivated compression. -//! - unique: random single-segment paths and random two-hop chains, where nothing -//! is shared and every START pays the four zero base/keep bytes. +//! - unique: random single-segment paths and random two-hop chains, where no path +//! is shared and every START pays the two zero base/keep bytes. +//! +//! The hop chains travel only on lite-06; lite-07 names each claim's route instead. //! //! The byte counts print once before the timings. //! diff --git a/rs/moq-net/src/auth.rs b/rs/moq-net/src/auth.rs index 9b36d440c09..8623a8acc55 100644 --- a/rs/moq-net/src/auth.rs +++ b/rs/moq-net/src/auth.rs @@ -528,6 +528,15 @@ pub(crate) struct Permit { } impl Permit { + /// A permit limiting the peer to `limit`, with no grant of its own. + #[cfg(test)] + pub(crate) fn limited(limit: Patterns) -> Self { + Self { + granted: None, + limit: Some(limit), + } + } + /// Whether both allow `path`. pub(crate) fn matches(&self, path: &str) -> bool { self.granted(path) && self.within_limit(path) @@ -544,6 +553,47 @@ impl Permit { self.limit.as_ref().is_none_or(|limit| limit.matches(path)) } + /// Whether this allows every path at or beneath `prefix`, judged pattern by + /// pattern, so a `false` may be spurious but a `true` never is. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn covers_subtree(&self, prefix: &str) -> bool { + let Ok(subtree) = moq_pattern::Pattern::subtree(prefix) else { + return false; + }; + let covers = |patterns: &Option| patterns.as_ref().is_none_or(|patterns| patterns.contains(&subtree)); + covers(&self.granted) && covers(&self.limit) + } + + /// Whether the limit alone allows every path at or beneath `prefix`, judged + /// pattern by pattern, so a `false` may be spurious but a `true` never is. + #[cfg(feature = "async")] + pub(crate) fn within_limit_subtree(&self, prefix: &str) -> bool { + let Ok(subtree) = moq_pattern::Pattern::subtree(prefix) else { + return false; + }; + self.limit.as_ref().is_none_or(|limit| limit.contains(&subtree)) + } + + /// The prefixes this confines the peer to, or `None` when it confines nothing: the + /// heads of the scope's patterns, which grants this side issued. What the peer + /// granted this side limits only what this side does, so a client never scopes the + /// relay that answered its token. + #[cfg(feature = "async")] + pub(crate) fn regions(&self) -> Option> { + let limit = self.limit.as_ref()?; + let everything = moq_pattern::Pattern::subtree("").ok()?; + if limit.contains(&everything) { + return None; + } + Some(crate::model::interest_prefixes(limit)) + } + + /// Whether both set the same limit on the peer, whatever either was granted. + #[cfg(feature = "async")] + pub(crate) fn same_limit(&self, other: &Self) -> bool { + self.limit == other.limit + } + /// Whether this allows everything `other` does, judged part by part, so a `false` /// may be spurious but a `true` never is. pub(crate) fn covers(&self, other: &Self) -> bool { @@ -1227,6 +1277,12 @@ impl Link { Poll::Ready(link.permit(direction)) } + /// What `direction` allows right now. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn permit(&self, direction: Direction) -> Permit { + self.read(|link, _| link.permit(direction)) + } + /// The limit once it may have changed since `epoch` last saw it, advancing `epoch`. pub(crate) fn poll_limit(&self, epoch: &mut u64, waiter: &kio::Waiter) -> Poll> { let state = ready_or!(self.poll_epoch(*epoch, waiter)); @@ -2883,6 +2939,30 @@ mod tests { } } + /// Only a grant this side issued confines the peer's claims: a client scoped by the + /// relay that answered its token leaves the relay's own routes unscoped. + #[cfg(feature = "async")] + #[test] + fn regions_come_from_the_issued_scope_alone() { + let earned = Permit { + granted: Some(patterns(&[".socket"])), + limit: None, + }; + assert_eq!(earned.regions(), None, "the peer's grant to us scoped the peer"); + + let issued = Permit { + granted: None, + limit: Some(patterns(&[".socket/bob"])), + }; + assert_eq!(issued.regions(), Some(vec![crate::Path::from_static(".socket/bob")])); + + let everything = Permit { + granted: Some(patterns(&[".socket"])), + limit: Some(patterns(&[""])), + }; + assert_eq!(everything.regions(), None, "a root grant confines nothing"); + } + /// A limit replaces the last one, narrower or wider, and applies to a version /// without AUTH too. #[test] diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 2edab8c1ca4..1b2783a4106 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -224,8 +224,9 @@ impl Client { /// moq-transport via the MoQ Cluster extension). /// /// The dialer is the side that knows what a link costs, because it chose the peer: - /// use `0` for a sibling in the same datacenter and something large for another - /// region across a metered backbone. So this prices both directions. We add it to + /// use `1` for a sibling in the same datacenter and something large for another + /// region across a metered backbone. Zero is refused on moq-lite-07, whose routing + /// needs every link to cost something. So this prices both directions. We add it to /// the route cost of every announcement the peer sends us, and declare it in our /// SETUP so the peer adds it to every announcement we send, which is what a server /// accepting an anonymous connection needs: it cannot tell a sibling from a diff --git a/rs/moq-net/src/coding/writer.rs b/rs/moq-net/src/coding/writer.rs index 01bb04c8da2..71591b52578 100644 --- a/rs/moq-net/src/coding/writer.rs +++ b/rs/moq-net/src/coding/writer.rs @@ -509,6 +509,7 @@ mod tests { .buffer(&lite::Track { broadcast: crate::Path::from_static("test"), instance: None, + node: 0, track: "video".into(), }) .unwrap(); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 96ba9629baf..1dcd4ff6cae 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -364,6 +364,9 @@ fn hop_chain(ids: impl IntoIterator) -> Hops { } /// One announcement on an announce stream, resolved: what the application sees. +/// +/// The hop chain travels only on lite-06: lite-07 names the claim's route instead, so +/// its writer drops the chain and its reader decodes an empty one. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Announced { /// ANNOUNCE_START: a route's suffix and wire hop ids, taking the next id. @@ -402,19 +405,20 @@ impl AnnounceWriter { pub fn write(&mut self, announced: &Announced, data: &mut Vec) { let msg = match announced { Announced::Start(suffix, hops) => { - let (_, suffix, hops) = self.encoder.start(suffix.clone(), hop_chain(hops.iter().copied())); + let (_, suffix) = self.encoder.start(suffix.clone()); // A fixed instance, so the bytes stay pinned and match what `js/net` writes. lite::AnnounceBroadcast::Active { + route: 0, instance: self.version.has_instance().then(|| "a".parse().unwrap()), epoch: 0, suffix, - hops, + hops: self.chain(hops), cost: Default::default(), } } Announced::Update(id, hops) => lite::AnnounceBroadcast::Update { id: *id, - hops: self.encoder.update(*id, hop_chain(hops.iter().copied())), + hops: self.chain(hops), cost: Default::default(), }, Announced::End(id) => { @@ -425,6 +429,14 @@ impl AnnounceWriter { msg.encode(&mut Encoder::new(data, self.version.into()), self.version) .expect("could not encode an announcement"); } + + /// The hop chain as this version carries it: none on lite-07. + fn chain(&self, hops: &[u64]) -> Hops { + match self.version.has_routes() { + true => Hops::default(), + false => hop_chain(hops.iter().copied()), + } + } } /// Mark `track` as a copy received from a remote publisher, as a subscriber session does, for @@ -590,11 +602,11 @@ pub fn decode_announces(data: &[u8], compress: bool) -> Vec { while let Ok(msg) = lite::AnnounceBroadcast::decode(&mut data, version) { let announced = match msg { lite::AnnounceBroadcast::Active { suffix, hops, .. } => decoder - .start(suffix, hops) - .map(|(suffix, hops)| Announced::Start(suffix, hops.into_ids())), - lite::AnnounceBroadcast::Update { id, hops, .. } => decoder - .update(id, hops) - .map(|(_, hops)| Announced::Update(id, hops.into_ids())), + .start(suffix) + .map(|suffix| Announced::Start(suffix, hops.into_ids())), + lite::AnnounceBroadcast::Update { id, hops, .. } => { + decoder.get(id).map(|_| Announced::Update(id, hops.into_ids())) + } lite::AnnounceBroadcast::EndedId { id } => decoder.end(id).map(|_| Announced::End(id)), _ => continue, }; @@ -697,6 +709,7 @@ impl LiteSample { Self::Subscribe => lite::Subscribe { order: crate::track::Order::Descending, instance: None, + node: 0, id: 3, broadcast: Path::from_static("room/alice"), track: "video".into(), @@ -896,6 +909,7 @@ impl Default for Messages { lite_subscribe: lite::Subscribe { order: crate::track::Order::Descending, instance: None, + node: 0, id: 7, broadcast: Path::from_static("room/alice"), track: "video".into(), @@ -1080,6 +1094,7 @@ pub fn encode_subscribe(broadcast: &Path, track: &str, ietf: bool, out: &mut Vec id: 0, broadcast: broadcast.clone(), instance: None, + node: 0, track: track.into(), priority: 0, max_delay: std::time::Duration::ZERO, diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index 8e9d42770b4..be5f324ad66 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -28,10 +28,6 @@ const ROUTE_START: u64 = 6; const ROUTE_UPDATE: u64 = 7; const ROUTE_END: u64 = 8; const ANNOUNCE_FLOOR: u64 = 9; -#[cfg_attr( - not(any(test, feature = "fuzz")), - allow(dead_code, reason = "the lite-07 session does not drive the route layer yet") -)] const ROUTE_REQUEST: u64 = 10; const ROUTE_HOLD: u64 = 11; @@ -59,20 +55,23 @@ pub fn update_supported(version: Version) -> bool { /// repeating the path. Older versions send a single `ANNOUNCE_BROADCAST` /// message that retracts by path (`Ended`). /// -/// The path and hop chain are as they appear on the wire: on lite-07 they may name a -/// base announcement, resolved against the stream's history by -/// [`AnnounceDecoder`](super::AnnounceDecoder). +/// The path is as it appears on the wire: on lite-07 it may name a base announcement, +/// resolved against the stream's history by [`AnnounceDecoder`](super::AnnounceDecoder). +/// +/// Lite-07 names the route each claim travels under in place of a hop chain, so `hops` +/// must be empty there and `route` must be 0 on every earlier version. #[derive(Clone, Debug, PartialEq, Eq)] pub enum AnnounceBroadcast { /// ANNOUNCE_START (lite-06) / active (older): a broadcast is now available. - /// Carries the path suffix, (lite-07+) the instance and epoch it serves, the hop - /// chain, and (lite-06+) the static route cost, and assigns the next announce id. - /// The instance and epoch change only with a `Restart`. + /// Carries the path suffix, (lite-07+) the Route ID and the instance and epoch it + /// serves, (before lite-07) the hop chain, and (lite-06+) the cost, and assigns the + /// next announce id. The instance and epoch change only with a `Restart`. Active { suffix: PathRef, + route: u64, instance: Option, epoch: u64, - hops: HopsRef, + hops: Hops, cost: Cost, }, /// Pre-lite-06: a broadcast is no longer available, retracted by path. @@ -81,9 +80,8 @@ pub enum AnnounceBroadcast { /// announce id. The id is retired; referencing it again is a protocol violation. EndedId { id: u64 }, /// ANNOUNCE_UPDATE (lite-06+): atomically replace the metadata of the announcement - /// with this id (e.g. a new hop chain after a relay failover, or a route whose cost - /// moved). The id stays live. - Update { id: u64, hops: HopsRef, cost: Cost }, + /// with this id: its cost, and before lite-07 its hop chain. The id stays live. + Update { id: u64, hops: Hops, cost: Cost }, /// ANNOUNCE_RESTART (lite-07+): the announcement with this id now serves the /// instance and epoch given. Another instance is another stream, so whatever the /// receiver resolved under its prefix is stale; a higher epoch of the same one @@ -92,7 +90,6 @@ pub enum AnnounceBroadcast { id: u64, instance: Option, epoch: u64, - hops: HopsRef, cost: Cost, }, /// ANNOUNCE_TAKEOVER (lite-07+): an `Active` that continues what the live @@ -101,9 +98,9 @@ pub enum AnnounceBroadcast { Takeover { predecessor: u64, suffix: PathRef, + route: u64, instance: Option, epoch: u64, - hops: HopsRef, cost: Cost, }, /// An unknown lite-06+ announce type. The length-prefixed body was skipped so @@ -216,55 +213,37 @@ impl<'a> Decode<'a, Version> for PathRef { } } -/// A hop chain as it travels: `literal` leading hops, followed by the last `keep` -/// entries of a base announcement's chain. -/// -/// `base` counts back like [`PathRef::base`], independently of it. Only lite-07 -/// carries a base; every other version is `literal` alone. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -pub struct HopsRef { - pub base: u64, - pub literal: Hops, - pub keep: u64, +/// Encode the Route ID a claim travels under, which only lite-07 carries. +fn encode_route_id(w: &mut Encoder<'_>, version: Version, route: u64) -> Result<(), EncodeError> { + match version.has_routes() { + true => w.varint(route), + false if route != 0 => Err(EncodeError::InvalidState), + false => Ok(()), + } } -impl HopsRef { - /// The whole chain, with no base. - pub fn literal(literal: Hops) -> Self { - Self { - base: 0, - literal, - keep: 0, - } +/// Decode the Route ID a claim travels under, 0 on a version without one. +fn decode_route_id(r: &mut Decoder<'_>, version: Version) -> Result { + match version.has_routes() { + true => r.varint(), + false => Ok(0), } } -impl Encode for HopsRef { - fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { - if !version.has_announce_compression() { - if self.base != 0 || self.keep != 0 { - return Err(EncodeError::Version); - } - return self.literal.encode(w, version); - } - w.varint(self.base)?; - self.literal.encode(w, version)?; - w.varint(self.keep) +/// Encode a lite-06+ announcement's hop chain, which lite-07 replaces with its Route ID. +fn encode_chain(w: &mut Encoder<'_>, version: Version, hops: &Hops) -> Result<(), EncodeError> { + match version.has_routes() { + true if !hops.is_empty() => Err(EncodeError::InvalidState), + true => Ok(()), + false => hops.encode(w, version), } } -impl<'a> Decode<'a, Version> for HopsRef { - fn decode(buf: &mut Decoder<'a>, version: Version) -> Result { - if !version.has_announce_compression() { - return Ok(Self::literal(Hops::decode(buf, version)?)); - } - let base = buf.varint()?; - let literal = Hops::decode(buf, version)?; - let keep = buf.varint()?; - if base == 0 && keep != 0 { - return Err(DecodeError::InvalidValue); - } - Ok(Self { base, literal, keep }) +/// Decode a lite-06+ announcement's hop chain, empty on lite-07. +fn decode_chain(r: &mut Decoder<'_>, version: Version) -> Result { + match version.has_routes() { + true => Ok(Hops::default()), + false => Hops::decode(r, version), } } @@ -337,46 +316,46 @@ impl Encode for AnnounceBroadcast { match self { Self::Active { suffix, + route, instance, epoch, hops, cost, } => { suffix.encode(w, version)?; + encode_route_id(w, version, *route)?; super::instance::encode_route(w, version, instance.as_ref(), *epoch)?; - hops.encode(w, version)?; + encode_chain(w, version, hops)?; cost.encode(w, version)?; } Self::EndedId { id } => w.varint(*id)?, Self::Update { id, hops, cost } => { w.varint(*id)?; - hops.encode(w, version)?; + encode_chain(w, version, hops)?; cost.encode(w, version)?; } Self::Restart { id, instance, epoch, - hops, cost, } => { w.varint(*id)?; super::instance::encode_route(w, version, instance.as_ref(), *epoch)?; - hops.encode(w, version)?; cost.encode(w, version)?; } Self::Takeover { predecessor, suffix, + route, instance, epoch, - hops, cost, } => { w.varint(*predecessor)?; suffix.encode(w, version)?; + encode_route_id(w, version, *route)?; super::instance::encode_route(w, version, instance.as_ref(), *epoch)?; - hops.encode(w, version)?; cost.encode(w, version)?; } Self::Synced => {} @@ -407,14 +386,19 @@ impl Encode for AnnounceBroadcast { let prefix = w.prefix_varint(); match self { // The cost is a lite-06 addition, so it is simply not on the wire here. - Self::Active { suffix, hops, .. } => { - // Bases are a lite-07 addition; PathRef and HopsRef refuse one here. - if suffix.base != 0 || hops.base != 0 { + Self::Active { + suffix, route, hops, .. + } => { + // Bases are a lite-07 addition; PathRef refuses one here. + if suffix.base != 0 { return Err(EncodeError::Version); } + if *route != 0 { + return Err(EncodeError::InvalidState); + } AnnounceStatus::Active.encode(w, version)?; suffix.rest.encode(w, version)?; - encode_hops(w, version, &hops.literal)?; + encode_hops(w, version, hops)?; } Self::Ended { suffix, hops } => { AnnounceStatus::Ended.encode(w, version)?; @@ -456,12 +440,14 @@ impl<'a> Decode<'a, Version> for AnnounceBroadcast { Ok(match typ { ANNOUNCE_START => { let suffix = PathRef::decode(&mut body, version)?; + let route = decode_route_id(&mut body, version)?; let (instance, epoch) = super::instance::decode_route(&mut body, version)?; Self::Active { suffix, + route, instance, epoch, - hops: HopsRef::decode(&mut body, version)?, + hops: decode_chain(&mut body, version)?, cost: Cost::decode(&mut body, version)?, } } @@ -469,7 +455,7 @@ impl<'a> Decode<'a, Version> for AnnounceBroadcast { ANNOUNCE_END => Self::EndedId { id: body.varint()? }, ANNOUNCE_UPDATE => Self::Update { id: body.varint()?, - hops: HopsRef::decode(&mut body, version)?, + hops: decode_chain(&mut body, version)?, cost: Cost::decode(&mut body, version)?, }, ANNOUNCE_RESTART if version.has_announce_restart() => { @@ -479,20 +465,20 @@ impl<'a> Decode<'a, Version> for AnnounceBroadcast { id, instance, epoch, - hops: HopsRef::decode(&mut body, version)?, cost: Cost::decode(&mut body, version)?, } } ANNOUNCE_TAKEOVER if version.has_announce_takeover() => { let predecessor = body.varint()?; let suffix = PathRef::decode(&mut body, version)?; + let route = decode_route_id(&mut body, version)?; let (instance, epoch) = super::instance::decode_route(&mut body, version)?; Self::Takeover { predecessor, suffix, + route, instance, epoch, - hops: HopsRef::decode(&mut body, version)?, cost: Cost::decode(&mut body, version)?, } } @@ -561,9 +547,10 @@ impl AnnounceBroadcast { Ok(match status { AnnounceStatus::Active => Self::Active { suffix: PathRef::literal(suffix), + route: 0, instance: None, epoch: 0, - hops: HopsRef::literal(hops), + hops, cost: Cost::UNKNOWN, }, AnnounceStatus::Ended => Self::Ended { suffix, hops }, @@ -574,9 +561,10 @@ impl AnnounceBroadcast { // invalid value there. AnnounceStatus::Update if update_supported(version) => Self::Active { suffix: PathRef::literal(suffix), + route: 0, instance: None, epoch: 0, - hops: HopsRef::literal(hops), + hops, cost: Cost::UNKNOWN, }, AnnounceStatus::Update => return Err(DecodeError::InvalidValue), @@ -646,10 +634,6 @@ impl<'a> Message<'a> for AnnounceRequest { /// A message the subscriber sends on the Announce Stream after its ANNOUNCE_REQUEST /// (lite-07+), toward the publisher that sent the routes. -#[cfg_attr( - not(any(test, feature = "fuzz")), - allow(dead_code, reason = "the lite-07 session does not drive the route layer yet") -)] #[derive(Clone, Debug, PartialEq, Eq)] pub enum AnnounceReply { /// ROUTE_REQUEST: asks for a route to `node`, as the publisher named it, at least @@ -817,8 +801,10 @@ impl<'a> Message<'a> for AnnounceInit { /// /// `origin` is the responder's session origin id. In Lite05 the publisher no /// longer stamps it onto each Announce's hop chain; the subscriber appends it on -/// receipt instead. Lite05/06 carry `active`, the number of starts immediately -/// following; lite07 marks the initial set with SYNCED instead. +/// receipt instead. Lite05/06 carry it and `active`, the number of starts immediately +/// following. Lite07 has an empty body: its claims name their route instead of a hop +/// chain, and SYNCED marks the initial set, so neither field is sent and both decode +/// as unknown. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct AnnounceOk { pub origin: Hop, @@ -831,9 +817,15 @@ impl<'a> Message<'a> for AnnounceOk { if !version.has_announce_ok() { return Err(DecodeError::Version); } + if version.has_routes() { + return Ok(Self { + origin: Hop::UNKNOWN, + active: 0, + }); + } let origin = Hop::decode(r, version)?; - let active = if version.has_synced() { 0 } else { r.varint()? }; + let active = r.varint()?; Ok(Self { origin, active }) } @@ -841,12 +833,12 @@ impl<'a> Message<'a> for AnnounceOk { if !version.has_announce_ok() { return Err(EncodeError::Version); } + if version.has_routes() { + return Ok(()); + } self.origin.encode(w, version)?; - if !version.has_synced() { - w.varint(self.active)?; - } - Ok(()) + w.varint(self.active) } } @@ -880,8 +872,10 @@ mod tests { assert!(matches!(decode(&wire, usize::MAX), Err(DecodeError::InvalidValue))); } + /// Lite-07's ANNOUNCE_OK is empty: SYNCED replaces the count, and routes replace the + /// Hop ID. Lite-06 keeps both. #[test] - fn synced_replaces_only_lite07s_count() { + fn announce_ok_is_empty_on_lite07() { for version in [Version::Lite06, Version::Lite07] { let mut bytes = Vec::new(); AnnounceOk { @@ -895,10 +889,25 @@ mod tests { if version == Version::Lite06 { vec![2, 1, 7] } else { - vec![1, 1] + vec![0] } ); } + assert_eq!( + crate::coding::decode_buf(&mut &[0u8][..], Version::Lite07, |r, v| AnnounceOk::decode(r, v)).unwrap(), + AnnounceOk { + origin: Hop::UNKNOWN, + active: 0, + } + ); + // A body where the draft has none is malformed. + assert!( + crate::coding::decode_buf(&mut &[1u8, 1][..], Version::Lite07, |r, v| AnnounceOk::decode(r, v)).is_err() + ); + } + + #[test] + fn synced_marks_lite07s_initial_set() { let mut bytes = Vec::new(); AnnounceBroadcast::Synced .encode(&mut Encoder::new(&mut bytes, Version::Lite07.into()), Version::Lite07) @@ -918,10 +927,11 @@ mod tests { // Encode a normal Active, then flip its status byte (1 -> 2). let mut buf = Vec::new(); AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef::literal(Path::from_static("foo/bar")), - hops: HopsRef::default(), + hops: Hops::default(), cost: Cost::default(), } .encode(&mut Encoder::new(&mut buf, version.into()), version) @@ -1010,10 +1020,11 @@ mod tests { let mut hops = Hops::new(); hops.push(Hop::new(7).unwrap()).unwrap(); let msg = AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef::literal(Path::from_static("room/cam")), - hops: HopsRef::literal(hops.clone()), + hops: hops.clone(), cost: Cost::UNKNOWN, }; assert_eq!(broadcast_round_trip(&msg, Version::Lite05), msg); @@ -1034,10 +1045,11 @@ mod tests { let cost = Cost::new(12); let active = AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef::literal(Path::from_static("room/cam")), - hops: HopsRef::literal(hops.clone()), + hops: hops.clone(), cost, }; assert_eq!(broadcast_round_trip(&active, Version::Lite06), active); @@ -1045,22 +1057,18 @@ mod tests { let ended = AnnounceBroadcast::EndedId { id: 3 }; assert_eq!(broadcast_round_trip(&ended, Version::Lite06), ended); - let update = AnnounceBroadcast::Update { - id: 3, - hops: HopsRef::literal(hops), - cost, - }; + let update = AnnounceBroadcast::Update { id: 3, hops, cost }; assert_eq!(broadcast_round_trip(&update, Version::Lite06), update); } - // Lite07 carries both bases as they travel; the codec resolves nothing. + // Lite07 carries the path base as it travels, and the route in place of a hop chain; + // the codec resolves nothing. #[test] fn announce_broadcast_round_trip_on_lite07() { - let mut hops = Hops::new(); - hops.push(Hop::new(7).unwrap()).unwrap(); let cost = Cost::new(12); let active = AnnounceBroadcast::Active { + route: 4, instance: Some("a".parse().unwrap()), epoch: 5, suffix: PathRef { @@ -1068,22 +1076,14 @@ mod tests { keep: 3, rest: Path::from_static("cam"), }, - hops: HopsRef { - base: 1, - literal: hops.clone(), - keep: 2, - }, + hops: Hops::default(), cost, }; assert_eq!(broadcast_round_trip(&active, Version::Lite07), active); let update = AnnounceBroadcast::Update { id: 3, - hops: HopsRef { - base: 4, - literal: hops.clone(), - keep: 1, - }, + hops: Hops::default(), cost, }; assert_eq!(broadcast_round_trip(&update, Version::Lite07), update); @@ -1093,11 +1093,6 @@ mod tests { id: 3, instance: Some(Instance::random()), epoch, - hops: HopsRef { - base: 4, - literal: hops.clone(), - keep: 1, - }, cost, }; assert_eq!(broadcast_round_trip(&restart, Version::Lite07), restart); @@ -1109,28 +1104,127 @@ mod tests { keep: 1, rest: Path::from_static("p"), }, + route: 0, instance: Some(Instance::random()), epoch, - hops: HopsRef { - base: 1, - literal: hops.clone(), - keep: 1, - }, cost, }; assert_eq!(broadcast_round_trip(&takeover, Version::Lite07), takeover); } } + /// The draft's field order, byte for byte: ANNOUNCE_START is the path base, keep, and + /// rest, the Route ID, the instance and epoch, and the cost; ANNOUNCE_UPDATE is the + /// Announce ID and the cost; ANNOUNCE_TAKEOVER leads with its predecessor. + #[test] + fn lite07_announce_layout() { + let encode = |msg: AnnounceBroadcast| { + let mut buf = Vec::new(); + msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07) + .unwrap(); + buf + }; + let suffix = PathRef { + base: 1, + keep: 2, + rest: Path::from_static("c"), + }; + assert_eq!( + encode(AnnounceBroadcast::Active { + suffix: suffix.clone(), + route: 3, + instance: Some("a".parse().unwrap()), + epoch: 5, + hops: Hops::default(), + cost: Cost::new(6), + }), + [0, 9, 1, 2, 1, b'c', 3, 1, b'a', 5, 6] + ); + assert_eq!( + encode(AnnounceBroadcast::Update { + id: 7, + hops: Hops::default(), + cost: Cost::new(6), + }), + [2, 2, 7, 6] + ); + assert_eq!( + encode(AnnounceBroadcast::Restart { + id: 7, + instance: Some("a".parse().unwrap()), + epoch: 5, + cost: Cost::new(6), + }), + [3, 5, 7, 1, b'a', 5, 6] + ); + assert_eq!( + encode(AnnounceBroadcast::Takeover { + predecessor: 9, + suffix, + route: 3, + instance: Some("a".parse().unwrap()), + epoch: 5, + cost: Cost::new(6), + }), + [5, 10, 9, 1, 2, 1, b'c', 3, 1, b'a', 5, 6] + ); + } + + /// Lite-07 names a claim's route instead of its hop chain, so a chain is refused there. + #[test] + fn lite07_refuses_a_hop_chain() { + let mut hops = Hops::new(); + hops.push(Hop::new(7).unwrap()).unwrap(); + let refused = [ + AnnounceBroadcast::Active { + route: 0, + instance: Some("a".parse().unwrap()), + epoch: 0, + suffix: PathRef::literal(Path::from_static("cam")), + hops: hops.clone(), + cost: Cost::default(), + }, + AnnounceBroadcast::Update { + id: 0, + hops, + cost: Cost::default(), + }, + ]; + for msg in refused { + let mut buf = Vec::new(); + let res = msg.encode(&mut Encoder::new(&mut buf, Version::Lite07.into()), Version::Lite07); + assert!(matches!(res, Err(EncodeError::InvalidState)), "{msg:?}"); + } + } + + /// Only lite-07 carries a Route ID: a non-zero one has nowhere to go earlier, and an + /// earlier start decodes as route 0. + #[test] + fn a_route_id_needs_lite07() { + let msg = AnnounceBroadcast::Active { + route: 1, + instance: None, + epoch: 0, + suffix: PathRef::literal(Path::from_static("cam")), + hops: Hops::default(), + cost: Cost::default(), + }; + for version in [Version::Lite05, Version::Lite06] { + let mut buf = Vec::new(); + let res = msg.encode(&mut Encoder::new(&mut buf, version.into()), version); + assert!(matches!(res, Err(EncodeError::InvalidState)), "{version:?}"); + } + } + // Only lite-07 carries ANNOUNCE_TAKEOVER: older versions send a start instead. #[test] fn announce_takeover_needs_lite07() { let takeover = AnnounceBroadcast::Takeover { predecessor: 0, suffix: PathRef::literal(Path::from_static("p")), + route: 0, instance: Some(Instance::random()), epoch: 0, - hops: HopsRef::default(), cost: Cost::default(), }; assert!(matches!( @@ -1150,7 +1244,6 @@ mod tests { id: 1, instance: Some("a".parse().unwrap()), epoch: 0, - hops: HopsRef::default(), cost: Cost::default(), }; let mut buf = Vec::new(); @@ -1181,22 +1274,21 @@ mod tests { // A keep copies from a base, so one without a base is malformed. #[test] fn a_keep_without_a_base_is_rejected() { - for (path_keep, hop_keep) in [(1u8, 0u8), (0, 1)] { - // Path base, path keep, empty rest, instance "a", epoch, hop base, no hops, hop keep, cost. - let body = [0, path_keep, 0, 1, b'a', 0, 0, 0, hop_keep, 0]; - let mut buf = vec![ANNOUNCE_START as u8, body.len() as u8]; - buf.extend_from_slice(&body); - assert!(matches!( - crate::coding::decode_buf(&mut &buf[..], Version::Lite07, |r, v| AnnounceBroadcast::decode(r, v)), - Err(DecodeError::InvalidValue) - )); - } + // Path base, path keep, empty rest, route, instance "a", epoch, cost. + let body = [0, 1, 0, 0, 1, b'a', 0, 0]; + let mut buf = vec![ANNOUNCE_START as u8, body.len() as u8]; + buf.extend_from_slice(&body); + assert!(matches!( + crate::coding::decode_buf(&mut &buf[..], Version::Lite07, |r, v| AnnounceBroadcast::decode(r, v)), + Err(DecodeError::InvalidValue) + )); } // Only lite-07 has room for a base. #[test] fn a_base_needs_lite07() { let msg = AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef { @@ -1204,7 +1296,7 @@ mod tests { keep: 1, rest: Path::from_static("cam"), }, - hops: HopsRef::default(), + hops: Hops::default(), cost: Cost::default(), }; for version in [Version::Lite05, Version::Lite06] { @@ -1228,7 +1320,7 @@ mod tests { assert!(matches!( AnnounceBroadcast::Update { id: 1, - hops: HopsRef::default(), + hops: Hops::default(), cost: Cost::default() } .encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05), @@ -1251,20 +1343,22 @@ mod tests { #[test] fn route_cost_is_dropped_before_lite06() { let msg = AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef::literal(Path::from_static("room/cam")), - hops: HopsRef::default(), + hops: Hops::default(), cost: Cost::new(9), }; let got = broadcast_round_trip(&msg, Version::Lite05); assert_eq!( got, AnnounceBroadcast::Active { + route: 0, instance: None, epoch: 0, suffix: PathRef::literal(Path::from_static("room/cam")), - hops: HopsRef::default(), + hops: Hops::default(), cost: Cost::UNKNOWN, } ); diff --git a/rs/moq-net/src/lite/compress.rs b/rs/moq-net/src/lite/compress.rs index fd4ad5ce677..69fb2241565 100644 --- a/rs/moq-net/src/lite/compress.rs +++ b/rs/moq-net/src/lite/compress.rs @@ -1,57 +1,49 @@ -//! Lite-07 announce compression: an ANNOUNCE_START may copy the head of a live -//! announcement's path, and an ANNOUNCE_START or ANNOUNCE_UPDATE the tail of a live -//! announcement's hop chain, naming that base by its distance back from the stream's -//! next unassigned Announce ID. +//! Lite-07 announce compression: an ANNOUNCE_START or ANNOUNCE_TAKEOVER may copy the +//! head of a live announcement's path, naming that base by its distance back from the +//! stream's next unassigned Announce ID. //! //! The codec in `announce.rs` stays stateless and carries bases as they travel. The //! decoder here resolves them against the stream's live announcements, which the //! subscriber has to track anyway, and the encoder picks them. -use std::{ - borrow::Borrow, - collections::{BTreeSet, HashMap}, - hash::Hash, -}; +use std::collections::{BTreeSet, HashMap}; use crate::{ - Error, Hop, Hops, Path, + Error, Path, coding::{Form, varint}, }; -use super::{HopsRef, PathRef, Version}; - -/// A live announcement, as the peer holds it: its wire suffix and wire hop chain -/// (the one excluding ANNOUNCE_OK's Hop ID). -#[derive(Clone, Debug)] -struct Entry { - suffix: Path, - hops: Hops, -} +use super::{PathRef, Version}; -/// The live announcements on one stream by Announce ID, which is all a base can name. +/// The live announcements on one stream by Announce ID, each with its wire suffix, +/// which is all a base can name. #[derive(Debug, Default)] struct Live { next: u64, - entries: HashMap, + suffixes: HashMap, } impl Live { + /// The suffix of the live announcement with this id. + fn suffix(&self, id: u64) -> Result<&Path, Error> { + self.suffixes.get(&id).ok_or(Error::ProtocolViolation) + } + /// The live announcement `distance` back from the next id, or `None` for 0. - fn base(&self, distance: u64) -> Result, Error> { + fn base(&self, distance: u64) -> Result, Error> { if distance == 0 { return Ok(None); } let id = self.next.checked_sub(distance).ok_or(Error::ProtocolViolation)?; - let entry = self.entries.get(&id).ok_or(Error::ProtocolViolation)?; - Ok(Some(entry)) + self.suffix(id).map(Some) } - fn resolve_path(&self, path: PathRef) -> Result { + fn resolve(&self, path: PathRef) -> Result { let Some(base) = self.base(path.base)? else { return Ok(path.rest); }; let keep = usize::try_from(path.keep).map_err(|_| Error::ProtocolViolation)?; - let head = head(&base.suffix, keep).ok_or(Error::ProtocolViolation)?; + let head = head(base, keep).ok_or(Error::ProtocolViolation)?; let suffix = match (head.is_empty(), path.rest.is_empty()) { (true, _) => Ok(path.rest), (false, true) => Path::new(head), @@ -63,20 +55,6 @@ impl Live { } Ok(suffix) } - - fn resolve_hops(&self, hops: HopsRef) -> Result { - let Some(base) = self.base(hops.base)? else { - return Ok(hops.literal); - }; - let keep = usize::try_from(hops.keep).map_err(|_| Error::ProtocolViolation)?; - let tail = base.hops.as_slice(); - let start = tail.len().checked_sub(keep).ok_or(Error::ProtocolViolation)?; - let mut out = hops.literal; - for hop in &tail[start..] { - out.push(*hop).map_err(|_| Error::ProtocolViolation)?; - } - Ok(out) - } } /// The first `keep` segments of `path`, or `None` if it has fewer. @@ -100,84 +78,61 @@ pub(crate) struct AnnounceDecoder { } impl AnnounceDecoder { - /// An ANNOUNCE_START: resolve it and assign it the next id. - pub fn start(&mut self, suffix: PathRef, hops: HopsRef) -> Result<(Path, Hops), Error> { - let suffix = self.live.resolve_path(suffix)?; - let hops = self.live.resolve_hops(hops)?; + /// An ANNOUNCE_START: resolve its suffix and assign it the next id. + pub fn start(&mut self, suffix: PathRef) -> Result { + let suffix = self.live.resolve(suffix)?; let id = self.live.next; self.live.next += 1; - self.live.entries.insert( - id, - Entry { - suffix: suffix.clone(), - hops: hops.clone(), - }, - ); - Ok((suffix, hops)) + self.live.suffixes.insert(id, suffix.clone()); + Ok(suffix) } /// An ANNOUNCE_TAKEOVER: resolve it like a start against the live `predecessor`, - /// returning the predecessor's suffix too. One at the predecessor's own suffix - /// retires the predecessor, since a suffix holds one advertisement. - pub fn takeover(&mut self, predecessor: u64, suffix: PathRef, hops: HopsRef) -> Result<(Path, Path, Hops), Error> { - let previous = self - .live - .entries - .get(&predecessor) - .ok_or(Error::ProtocolViolation)? - .suffix - .clone(); - let (suffix, hops) = self.start(suffix, hops)?; + /// returning the predecessor's suffix, then its own. One at the predecessor's own + /// suffix retires the predecessor, since a suffix holds one advertisement. + pub fn takeover(&mut self, predecessor: u64, suffix: PathRef) -> Result<(Path, Path), Error> { + let previous = self.live.suffix(predecessor)?.clone(); + let suffix = self.start(suffix)?; if suffix == previous { - self.live.entries.remove(&predecessor); + self.live.suffixes.remove(&predecessor); } - Ok((previous, suffix, hops)) + Ok((previous, suffix)) + } + + /// The id the last start or takeover assigned. + pub fn last(&self) -> u64 { + self.live.next.saturating_sub(1) } - /// An ANNOUNCE_UPDATE: resolve its chain before replacing the old one, which it - /// may itself be based on. - pub fn update(&mut self, id: u64, hops: HopsRef) -> Result<(Path, Hops), Error> { - let hops = self.live.resolve_hops(hops)?; - let entry = self.live.entries.get_mut(&id).ok_or(Error::ProtocolViolation)?; - entry.hops = hops.clone(); - Ok((entry.suffix.clone(), hops)) + /// The suffix of the live id an ANNOUNCE_UPDATE or ANNOUNCE_RESTART names, which + /// stays live. + pub fn get(&self, id: u64) -> Result { + self.live.suffix(id).cloned() } /// An ANNOUNCE_END: retire the id, returning its suffix. pub fn end(&mut self, id: u64) -> Result { - let entry = self.live.entries.remove(&id).ok_or(Error::ProtocolViolation)?; - Ok(entry.suffix) + self.live.suffixes.remove(&id).ok_or(Error::ProtocolViolation) } } -/// The live ids under a run of keys: path segments from the head, or hop ids from -/// the tail. Every node holds the ids of the entries beneath it, so the entry sharing -/// the longest run with a query is found by walking the query down once, at a cost -/// that grows with its length rather than with the number of entries. -#[derive(Debug)] -struct Trie { - children: HashMap>, +/// The live ids under a run of leading path segments. Every node holds the ids of the +/// entries beneath it, so the entry sharing the longest head with a query is found by +/// walking the query down once, at a cost that grows with its length rather than with +/// the number of entries. +#[derive(Debug, Default)] +struct Trie { + children: HashMap, } #[derive(Debug)] -struct Node { +struct Node { ids: BTreeSet, - children: HashMap>, + children: HashMap, } -impl Default for Trie { - fn default() -> Self { - Self { - children: HashMap::new(), - } - } -} - -impl Trie { - fn insert<'a, Q>(&mut self, keys: impl Iterator, id: u64) - where - Q: ?Sized + ToOwned + 'a, - { +impl Trie { + fn insert<'a>(&mut self, keys: impl Iterator, id: u64) { let mut children = &mut self.children; for key in keys { let node = children.entry(key.to_owned()).or_insert_with(|| Node { @@ -189,19 +144,11 @@ impl Trie { } } - fn remove<'a, Q>(&mut self, keys: impl Iterator, id: u64) - where - Q: ?Sized + Hash + Eq + 'a, - K: Borrow, - { + fn remove<'a>(&mut self, keys: impl Iterator, id: u64) { Self::remove_from(&mut self.children, keys, id); } - fn remove_from<'a, Q>(children: &mut HashMap>, mut keys: impl Iterator, id: u64) - where - Q: ?Sized + Hash + Eq + 'a, - K: Borrow, - { + fn remove_from<'a>(children: &mut HashMap, mut keys: impl Iterator, id: u64) { let Some(key) = keys.next() else { return; }; @@ -219,11 +166,7 @@ impl Trie { /// How many leading keys the query shares with its closest entry, and that entry's /// id, preferring the newest (the smallest distance to encode). - fn longest<'a, Q>(&self, keys: impl Iterator) -> Option<(usize, u64)> - where - Q: ?Sized + Hash + Eq + 'a, - K: Borrow, - { + fn longest<'a>(&self, keys: impl Iterator) -> Option<(usize, u64)> { let mut children = &self.children; let mut best = None; for (depth, key) in keys.enumerate() { @@ -242,20 +185,13 @@ impl Trie { /// versions that have them. Only lite-07 keeps the live set, since nothing earlier /// can name a base. /// -/// One trie over the live paths by segment, and one over the live hop chains from the -/// last hop back, find the longest shared head and tail. A base is used only when it -/// encodes smaller than the literal. +/// A trie over the live paths by segment finds the longest shared head. A base is +/// used only when it encodes smaller than the literal. #[derive(Debug)] pub(crate) struct AnnounceEncoder { version: Version, live: Live, - heads: Trie, - tails: Trie, -} - -/// A hop chain from the last hop back. -fn reversed(hops: &Hops) -> impl Iterator { - hops.as_slice().iter().rev() + heads: Trie, } impl AnnounceEncoder { @@ -264,60 +200,39 @@ impl AnnounceEncoder { version, live: Live::default(), heads: Trie::default(), - tails: Trie::default(), } } - /// An ANNOUNCE_START: its id (on versions that assign one) and its wire form. - pub fn start(&mut self, suffix: Path, hops: Hops) -> (Option, PathRef, HopsRef) { + /// An ANNOUNCE_START: its id (on versions that assign one) and its wire suffix. + pub fn start(&mut self, suffix: Path) -> (Option, PathRef) { if !self.version.has_announce_id() { - return (None, PathRef::literal(suffix), HopsRef::literal(hops)); + return (None, PathRef::literal(suffix)); } let id = self.live.next; self.live.next += 1; if !self.version.has_announce_compression() { - return (Some(id), PathRef::literal(suffix), HopsRef::literal(hops)); + return (Some(id), PathRef::literal(suffix)); } // Distances count back from the id this START takes. let path = self.path_ref(&suffix, id); - let chain = self.hops_ref(&hops, id); self.heads.insert(suffix.parts(), id); - self.tails.insert(reversed(&hops), id); - self.live.entries.insert(id, Entry { suffix, hops }); - (Some(id), path, chain) + self.live.suffixes.insert(id, suffix); + (Some(id), path) } /// An ANNOUNCE_TAKEOVER of the live `predecessor`: like [`Self::start`], retiring /// the predecessor when it holds the same suffix. - pub fn takeover(&mut self, predecessor: u64, suffix: Path, hops: Hops) -> (u64, PathRef, HopsRef) { - let replaces = self - .live - .entries - .get(&predecessor) - .is_some_and(|entry| entry.suffix == suffix); - let (id, path, chain) = self.start(suffix, hops); + pub fn takeover(&mut self, predecessor: u64, suffix: Path) -> (u64, PathRef) { + let replaces = self.live.suffixes.get(&predecessor) == Some(&suffix); + let (id, path) = self.start(suffix); let id = id.expect("a takeover is only sent on a version with announce ids"); if replaces { self.end(predecessor); } - (id, path, chain) - } - - /// An ANNOUNCE_UPDATE for a live `id`: its wire hop chain. - pub fn update(&mut self, id: u64, hops: Hops) -> HopsRef { - if !self.version.has_announce_compression() { - return HopsRef::literal(hops); - } - // The decoder resolves against the chain this replaces, so it is a valid base. - let chain = self.hops_ref(&hops, self.live.next); - let entry = self.live.entries.get_mut(&id).expect("update for a live id"); - self.tails.remove(reversed(&entry.hops), id); - self.tails.insert(reversed(&hops), id); - entry.hops = hops; - chain + (id, path) } /// An ANNOUNCE_END for a live `id`. @@ -325,9 +240,8 @@ impl AnnounceEncoder { if !self.version.has_announce_compression() { return; } - let entry = self.live.entries.remove(&id).expect("end for a live id"); - self.heads.remove(entry.suffix.parts(), id); - self.tails.remove(reversed(&entry.hops), id); + let suffix = self.live.suffixes.remove(&id).expect("end for a live id"); + self.heads.remove(suffix.parts(), id); } /// The wire form of `suffix`, sized from its parts so only the winner is built. @@ -350,35 +264,6 @@ impl AnnounceEncoder { false => literal(), } } - - /// The wire form of `hops`, sized from its parts so only the winner is built. - fn hops_ref(&self, hops: &Hops, next: u64) -> HopsRef { - let form: Form = self.version.into(); - let literal = || HopsRef::literal(hops.clone()); - let Some((keep, id)) = self.tails.longest(reversed(hops)) else { - return literal(); - }; - let head = &hops.as_slice()[..hops.len() - keep]; - - let base = next - id; - let keep = keep as u64; - let chain = |hops: &[Hop]| { - varint_size(hops.len() as u64, form) - + hops - .iter() - .map(|hop| varint_size(hop.wire_id(form), form)) - .sum::() - }; - let size = varint_size(base, form) + chain(head) + varint_size(keep, form); - match size < varint_size(0, form) * 2 + chain(hops.as_slice()) { - true => HopsRef { - base, - literal: Hops::try_from(head.to_vec()).expect("a prefix of a valid chain is valid"), - keep, - }, - false => literal(), - } - } } /// The bytes `value` takes as a varint in `form`. @@ -399,10 +284,6 @@ mod tests { const VERSION: Version = Version::Lite07; - fn hops(ids: &[u64]) -> Hops { - Hops::try_from(ids.iter().map(|id| Hop::from_wire(*id)).collect::>()).unwrap() - } - fn path(base: u64, keep: u64, rest: &str) -> PathRef { PathRef { base, @@ -411,85 +292,52 @@ mod tests { } } - fn chain(base: u64, literal: &[u64], keep: u64) -> HopsRef { - HopsRef { - base, - literal: hops(literal), - keep, - } - } - - fn literal(suffix: &str, ids: &[u64]) -> (PathRef, HopsRef) { - (path(0, 0, suffix), chain(0, ids, 0)) + fn literal(suffix: &str) -> PathRef { + path(0, 0, suffix) } #[test] - fn resolves_a_path_head_and_hop_tail() { + fn resolves_a_path_head() { let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("pid/private/channel_1/health-1", &[1, 2, 3]); - decoder.start(p, h).unwrap(); + decoder.start(literal("pid/private/channel_1/health-1")).unwrap(); - // Three leading segments of the latest START, and its last two hops. - let (suffix, chain) = decoder.start(path(1, 3, "health-2"), chain(1, &[7], 2)).unwrap(); + // Three leading segments of the latest START. + let suffix = decoder.start(path(1, 3, "health-2")).unwrap(); assert_eq!(suffix.as_str(), "pid/private/channel_1/health-2"); - assert_eq!(chain, hops(&[7, 2, 3])); } #[test] - fn keeps_the_whole_path_and_chain() { + fn keeps_the_whole_path() { let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("a/b", &[1, 2]); - decoder.start(p, h).unwrap(); - // A full keep with an empty rest names a route above the base's: not a - // duplicate, since the rest extends it. - let (suffix, chain) = decoder.start(path(1, 2, "c"), chain(1, &[], 2)).unwrap(); + decoder.start(literal("a/b")).unwrap(); + // A full keep with a rest names a route beneath the base's: not a duplicate, + // since the rest extends it. + let suffix = decoder.start(path(1, 2, "c")).unwrap(); + assert_eq!(suffix.as_str(), "a/b/c"); + // And a full keep with an empty rest copies it whole. + let suffix = decoder.start(path(1, 3, "")).unwrap(); assert_eq!(suffix.as_str(), "a/b/c"); - assert_eq!(chain, hops(&[1, 2])); - // An update copying its own full chain. - let (suffix, chain) = decoder.update(0, chain_ref(2, 2)).unwrap(); - assert_eq!(suffix.as_str(), "a/b"); - assert_eq!(chain, hops(&[1, 2])); - } - - fn chain_ref(base: u64, keep: u64) -> HopsRef { - chain(base, &[], keep) } #[test] fn a_new_stream_has_no_base() { let mut decoder = AnnounceDecoder::default(); - assert!(matches!( - decoder.start(path(1, 0, "a"), chain(0, &[], 0)), - Err(Error::ProtocolViolation) - )); - let mut decoder = AnnounceDecoder::default(); - assert!(matches!( - decoder.start(path(0, 0, "a"), chain(1, &[], 0)), - Err(Error::ProtocolViolation) - )); + assert!(matches!(decoder.start(path(1, 0, "a")), Err(Error::ProtocolViolation))); } #[test] fn rejects_a_retired_or_unassigned_base() { let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("a", &[1]); - decoder.start(p, h).unwrap(); - let (p, h) = literal("b", &[2]); - decoder.start(p, h).unwrap(); + decoder.start(literal("a")).unwrap(); + decoder.start(literal("b")).unwrap(); decoder.end(0).unwrap(); // Id 0 is two back, and retired. - assert!(matches!( - decoder.start(path(2, 1, "x"), chain(0, &[], 0)), - Err(Error::ProtocolViolation) - )); + assert!(matches!(decoder.start(path(2, 1, "x")), Err(Error::ProtocolViolation))); // Three back was never assigned. - assert!(matches!( - decoder.start(path(3, 0, "x"), chain(0, &[], 0)), - Err(Error::ProtocolViolation) - )); + assert!(matches!(decoder.start(path(3, 0, "x")), Err(Error::ProtocolViolation))); // Id 1 is still live, so reusing it works after the END. - let (suffix, _) = decoder.start(path(1, 1, "x"), chain(1, &[], 1)).unwrap(); + let suffix = decoder.start(path(1, 1, "x")).unwrap(); assert_eq!(suffix.as_str(), "b/x"); } @@ -498,27 +346,22 @@ mod tests { #[test] fn takeover_assigns_an_id_and_retires_one_in_place() { let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("pool", &[1]); - decoder.start(p, h).unwrap(); + decoder.start(literal("pool")).unwrap(); - let (previous, suffix, chain) = decoder.takeover(0, path(1, 1, "p"), chain_ref(1, 1)).unwrap(); + let (previous, suffix) = decoder.takeover(0, path(1, 1, "p")).unwrap(); assert_eq!((previous.as_str(), suffix.as_str()), ("pool", "pool/p")); - assert_eq!(chain, hops(&[1])); - decoder.update(0, chain_ref(0, 0)).unwrap(); + assert_eq!(decoder.get(0).unwrap().as_str(), "pool"); // Id 2 at id 1's own suffix, copied from id 1 itself, which then retires. - let (previous, suffix, _) = decoder.takeover(1, path(1, 2, ""), chain_ref(1, 1)).unwrap(); + let (previous, suffix) = decoder.takeover(1, path(1, 2, "")).unwrap(); assert_eq!((previous.as_str(), suffix.as_str()), ("pool/p", "pool/p")); + assert!(matches!(decoder.get(1), Err(Error::ProtocolViolation))); assert!(matches!( - decoder.update(1, chain_ref(0, 0)), - Err(Error::ProtocolViolation) - )); - assert!(matches!( - decoder.takeover(1, path(0, 0, "pool/p/q"), chain_ref(0, 0)), + decoder.takeover(1, literal("pool/p/q")), Err(Error::ProtocolViolation) )); assert!(matches!( - decoder.takeover(9, path(0, 0, "pool/p/q"), chain_ref(0, 0)), + decoder.takeover(9, literal("pool/p/q")), Err(Error::ProtocolViolation) )); assert_eq!(decoder.end(2).unwrap().as_str(), "pool/p"); @@ -528,54 +371,17 @@ mod tests { #[test] fn rejects_a_keep_longer_than_the_base() { let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("a/b", &[1]); - decoder.start(p, h).unwrap(); - assert!(matches!( - decoder.start(path(1, 3, "x"), chain(0, &[], 0)), - Err(Error::ProtocolViolation) - )); - assert!(matches!( - decoder.update(0, chain_ref(1, 2)), - Err(Error::ProtocolViolation) - )); - } - - #[test] - fn rejects_a_resolved_chain_breaking_the_hop_rules() { - let mut decoder = AnnounceDecoder::default(); - let (p, h) = literal("a", &[1, 2]); - decoder.start(p, h).unwrap(); - // A literal hop the kept tail repeats. - assert!(matches!( - decoder.start(path(0, 0, "b"), chain(1, &[2], 1)), - Err(Error::ProtocolViolation) - )); - - // Anonymous hops may repeat across the two halves. - let (p, h) = literal("c", &[0]); - decoder.start(p, h).unwrap(); - let (_, resolved) = decoder.start(path(0, 0, "d"), chain(1, &[0], 1)).unwrap(); - assert_eq!(resolved, hops(&[0, 0])); - - // And the resolved chain is still capped. - // MAX_HOPS entries. - let full: Vec = (1..=32).collect(); - let (p, h) = literal("e", &full); - decoder.start(p, h).unwrap(); - assert!(matches!( - decoder.start(path(0, 0, "f"), chain(1, &[100], 32)), - Err(Error::ProtocolViolation) - )); + decoder.start(literal("a/b")).unwrap(); + assert!(matches!(decoder.start(path(1, 3, "x")), Err(Error::ProtocolViolation))); } #[test] fn rejects_a_resolved_path_too_deep() { let mut decoder = AnnounceDecoder::default(); let deep = vec!["x"; Path::MAX_PARTS].join("/"); - let (p, h) = literal(&deep, &[]); - decoder.start(p, h).unwrap(); + decoder.start(literal(&deep)).unwrap(); assert!(matches!( - decoder.start(path(1, Path::MAX_PARTS as u64, "y"), chain(0, &[], 0)), + decoder.start(path(1, Path::MAX_PARTS as u64, "y")), Err(Error::ProtocolViolation) )); } @@ -584,26 +390,20 @@ mod tests { fn rejects_a_resolved_path_too_long() { let mut decoder = AnnounceDecoder::default(); let head = "x".repeat(Path::MAX_BYTES - 2); - let (p, h) = literal(&head, &[]); - decoder.start(p, h).unwrap(); + decoder.start(literal(&head)).unwrap(); // `head/y` is exactly the limit, and one byte more is refused. - let (suffix, _) = decoder.start(path(1, 1, "y"), chain(0, &[], 0)).unwrap(); + let suffix = decoder.start(path(1, 1, "y")).unwrap(); assert_eq!(suffix.len(), Path::MAX_BYTES); - assert!(matches!( - decoder.start(path(1, 1, "yz"), chain(0, &[], 0)), - Err(Error::ProtocolViolation) - )); + assert!(matches!(decoder.start(path(1, 1, "yz")), Err(Error::ProtocolViolation))); } - /// Encode a message with `encoder`, decode it with `decoder`, and check that the - /// resolved values match the input. - fn start(encoder: &mut AnnounceEncoder, decoder: &mut AnnounceDecoder, suffix: &str, ids: &[u64]) -> (u64, usize) { - let (id, wire_path, wire_hops) = encoder.start(Path::new(suffix).unwrap(), hops(ids)); - let size = wire_path.encode_bytes(VERSION).unwrap().len() + wire_hops.encode_bytes(VERSION).unwrap().len(); - let (got_path, got_hops) = decoder.start(wire_path, wire_hops).unwrap(); - assert_eq!(got_path.as_str(), suffix); - assert_eq!(got_hops, hops(ids)); + /// Encode a START with `encoder`, decode it with `decoder`, and check that the + /// resolved suffix matches the input. Returns its id and wire size. + fn start(encoder: &mut AnnounceEncoder, decoder: &mut AnnounceDecoder, suffix: &str) -> (u64, usize) { + let (id, wire) = encoder.start(Path::new(suffix).unwrap()); + let size = wire.encode_bytes(VERSION).unwrap().len(); + assert_eq!(decoder.start(wire).unwrap().as_str(), suffix); (id.unwrap(), size) } @@ -612,22 +412,17 @@ mod tests { fn encoder_takeover_decodes_to_its_input() { let mut encoder = AnnounceEncoder::new(VERSION); let mut decoder = AnnounceDecoder::default(); - let (claim, _) = start(&mut encoder, &mut decoder, "pool", &[1, 2]); + let (claim, _) = start(&mut encoder, &mut decoder, "pool"); let mut predecessor = claim; - for (suffix, ids) in [ - ("pool/p", &[3, 1, 2][..]), - ("pool/p", &[4, 1, 2]), - ("pool/p/q", &[4, 1, 2]), - ] { - let (id, wire_path, wire_hops) = encoder.takeover(predecessor, Path::new(suffix).unwrap(), hops(ids)); - let (_, got_path, got_hops) = decoder.takeover(predecessor, wire_path, wire_hops).unwrap(); - assert_eq!(got_path.as_str(), suffix); - assert_eq!(got_hops, hops(ids)); + for suffix in ["pool/p", "pool/p", "pool/p/q"] { + let (id, wire) = encoder.takeover(predecessor, Path::new(suffix).unwrap()); + let (_, got) = decoder.takeover(predecessor, wire).unwrap(); + assert_eq!(got.as_str(), suffix); predecessor = id; } // Both sides retired the id replaced in place and kept the rest. - let (id, wire_path, wire_hops) = encoder.start(Path::new("other").unwrap(), hops(&[1, 2])); - decoder.start(wire_path, wire_hops).unwrap(); + let (id, wire) = encoder.start(Path::new("other").unwrap()); + decoder.start(wire).unwrap(); assert_eq!(id, Some(4)); assert!(matches!(decoder.end(1), Err(Error::ProtocolViolation))); decoder.end(claim).unwrap(); @@ -640,13 +435,10 @@ mod tests { let mut encoder = AnnounceEncoder::new(VERSION); let mut decoder = AnnounceDecoder::default(); - // Several origins behind a shared pair of relays. - let relays = [1u64 << 40, 1u64 << 41]; let mut ids = Vec::new(); for n in 0..40u64 { - let origin = 1000 + n % 4; let suffix = format!("pid{}/private/channel_{}/stream-health-{}", n % 4, n % 7, n); - let (id, _) = start(&mut encoder, &mut decoder, &suffix, &[origin, relays[0], relays[1]]); + let (id, _) = start(&mut encoder, &mut decoder, &suffix); ids.push(id); // Retire every third one so bases come and go. if n % 3 == 0 { @@ -656,103 +448,57 @@ mod tests { } } - // Updates resolve against the chain they replace. - for id in ids.iter().copied().take(5) { - let chain = hops(&[2000, relays[1]]); - let wire = encoder.update(id, chain.clone()); - let (_, got) = decoder.update(id, wire).unwrap(); - assert_eq!(got, chain); - } - - // And a later START still matches what the encoder remembers. - start( - &mut encoder, - &mut decoder, - "pid0/private/channel_0/x", - &[1000, relays[0], relays[1]], - ); + // A later START still matches what the encoder remembers. + start(&mut encoder, &mut decoder, "pid0/private/channel_0/x"); } #[test] - fn encoder_picks_the_longest_shared_head_and_tail() { + fn encoder_picks_the_longest_shared_head() { let mut encoder = AnnounceEncoder::new(VERSION); let mut decoder = AnnounceDecoder::default(); - start(&mut encoder, &mut decoder, "a/b/c", &[1u64 << 50, 1u64 << 51]); + start(&mut encoder, &mut decoder, "a/b/c"); // Shares a byte prefix with `a/b/d`, but no second segment. - start(&mut encoder, &mut decoder, "a/b-z", &[3]); - - let (_, wire_path, wire_hops) = encoder.start(Path::from_static("a/b/d"), hops(&[5, 1u64 << 51])); - assert_eq!(wire_path, path(2, 2, "d")); - assert_eq!(wire_hops, chain(2, &[5], 1)); - } + start(&mut encoder, &mut decoder, "a/b-z"); - /// Hop 100 is 2 bytes as a QUIC varint and 1 byte as leading-ones. Sharing that - /// single hop from 128 announcements back costs 4 bytes in both forms (the base - /// is 2 bytes either way). The literal chain is 5 bytes in QUIC and 4 in - /// leading-ones, so QUIC would compress and leading-ones ties. A tie stays literal. - #[test] - fn a_tie_stays_literal_where_hop_100_sizes_differ() { - let quic = Form::Quic; - let leading = Form::LeadingOnes; - assert_eq!(varint_size(100, quic), 2); - assert_eq!(varint_size(100, leading), 1); - - let base = 128; - let compressed = |form| varint_size(base, form) + varint_size(0, form) + varint_size(1, form); - let literal = |form| varint_size(0, form) * 2 + varint_size(1, form) + varint_size(100, form); - assert!(compressed(quic) < literal(quic)); - assert_eq!(compressed(leading), literal(leading)); - - let mut encoder = AnnounceEncoder::new(VERSION); - let mut decoder = AnnounceDecoder::default(); - start(&mut encoder, &mut decoder, "origin", &[100]); - for n in 1..128 { - let suffix = format!("f{n}"); - start(&mut encoder, &mut decoder, &suffix, &[1]); - } - let (_, wire_path, wire_hops) = encoder.start(Path::from_static("again"), hops(&[100])); - assert_eq!(wire_hops, HopsRef::literal(hops(&[100]))); - let (got_path, got_hops) = decoder.start(wire_path, wire_hops).unwrap(); - assert_eq!(got_path.as_str(), "again"); - assert_eq!(got_hops, hops(&[100])); + let (_, wire) = encoder.start(Path::from_static("a/b/d")); + assert_eq!(wire, path(2, 2, "d")); } #[test] fn encoder_sends_literal_when_nothing_is_shared() { let mut encoder = AnnounceEncoder::new(VERSION); let mut decoder = AnnounceDecoder::default(); - start(&mut encoder, &mut decoder, "a", &[1]); - let (_, wire_path, wire_hops) = encoder.start(Path::from_static("b"), hops(&[2])); - assert_eq!(wire_path, PathRef::literal(Path::from_static("b"))); - assert_eq!(wire_hops, HopsRef::literal(hops(&[2]))); + start(&mut encoder, &mut decoder, "a"); + let (_, wire) = encoder.start(Path::from_static("b")); + assert_eq!(wire, PathRef::literal(Path::from_static("b"))); } #[test] fn lite06_assigns_ids_without_bases() { let mut encoder = AnnounceEncoder::new(Version::Lite06); - let (id, _, _) = encoder.start(Path::from_static("a/b"), hops(&[1])); + let (id, _) = encoder.start(Path::from_static("a/b")); assert_eq!(id, Some(0)); - let (id, wire_path, wire_hops) = encoder.start(Path::from_static("a/c"), hops(&[1])); + let (id, wire) = encoder.start(Path::from_static("a/c")); assert_eq!(id, Some(1)); - assert_eq!(wire_path, PathRef::literal(Path::from_static("a/c"))); - assert_eq!(wire_hops, HopsRef::literal(hops(&[1]))); + assert_eq!(wire, PathRef::literal(Path::from_static("a/c"))); encoder.end(0); - assert_eq!(encoder.update(1, hops(&[1])), HopsRef::literal(hops(&[1]))); } /// A compressed stream pinned byte for byte: `js/net/src/lite/announce.test.ts` /// decodes the same hex, so a codec change on either side breaks both. - const GOLDEN: &str = "001800000a726f6f6d2f612f63616d01610000029111a2220000000f0102036d69630161000101b33301000208000101c044440100010101000e020101620161000201c055550100"; + const GOLDEN: &str = + "001200000a726f6f6d2f612f63616d0001610000000b0102036d69630001610000020200000101010009020101620001610000"; #[cfg(feature = "async")] fn golden() -> Vec { use crate::fuzz::Announced; + // Lite-07 names a route instead of a hop chain, so none travels. vec![ - Announced::Start(Path::from_static("room/a/cam"), vec![0x1111, 0x2222]), - Announced::Start(Path::from_static("room/a/mic"), vec![0x3333, 0x2222]), - Announced::Update(0, vec![0x4444, 0x2222]), + Announced::Start(Path::from_static("room/a/cam"), vec![]), + Announced::Start(Path::from_static("room/a/mic"), vec![]), + Announced::Update(0, vec![]), Announced::End(1), - Announced::Start(Path::from_static("room/b"), vec![0x5555, 0x2222]), + Announced::Start(Path::from_static("room/b"), vec![]), ] } @@ -767,7 +513,7 @@ mod tests { /// The literal lite-07 stream `js/net` writes for the same announcements, which /// never picks a base. - const JS_LITERAL: &str = "001800000a726f6f6d2f612f63616d01610000029111a2220000001800000a726f6f6d2f612f6d69630161000002b333a2220000020a000002c04444a22200000101010015000006726f6f6d2f620161000002c05555a2220000"; + const JS_LITERAL: &str = "001200000a726f6f6d2f612f63616d0001610000001200000a726f6f6d2f612f6d6963000161000002020000010101000e000006726f6f6d2f620001610000"; #[test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index d5fd1bb0e71..349f6c3d870 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -117,6 +117,9 @@ pub struct Datagrams<'a> { pub broadcast: Path, /// The instance the subscriber expects; see [`crate::origin::Route::instance`]. pub instance: Option, + /// The Node ID of the origin that serves the request, or 0 for whichever the + /// publisher selects. + pub node: u64, pub track: Cow<'a, str>, /// The subscriber's priority. pub priority: i8, @@ -129,6 +132,7 @@ impl Datagrams<'_> { id: self.id, broadcast: self.broadcast, instance: self.instance, + node: self.node, track: Cow::Owned(self.track.into_owned()), priority: self.priority, } @@ -145,12 +149,14 @@ impl<'a> Message<'a> for Datagrams<'a> { let id = r.varint()?; let broadcast = Path::decode(r, version)?; let instance = super::instance::decode_pin(r, version)?; + let node = super::instance::decode_node(r, version)?; let track = Cow::Borrowed(r.str()?); let priority = super::priority::from_wire(r.u8()?); Ok(Self { id, broadcast, instance, + node, track, priority, }) @@ -163,6 +169,7 @@ impl<'a> Message<'a> for Datagrams<'a> { w.varint(self.id)?; self.broadcast.encode(w, version)?; super::instance::encode_pin(w, version, self.instance.as_ref())?; + super::instance::encode_node(w, version, self.node)?; w.string(&self.track)?; w.u8(super::priority::to_wire(self.priority)); Ok(()) @@ -362,6 +369,7 @@ mod test { id: 7, broadcast: Path::from_static("room/alice"), instance: None, + node: 0x7a3f, track: "audio".into(), priority: -3, }; @@ -369,6 +377,7 @@ mod test { let (decoded, _) = Datagrams::decode_slice(&buf, Version::Lite07).unwrap(); assert_eq!(decoded.id, 7); assert_eq!(decoded.broadcast, request.broadcast); + assert_eq!(decoded.node, 0x7a3f); assert_eq!(decoded.track, "audio"); assert_eq!(decoded.priority, -3); assert!(matches!( diff --git a/rs/moq-net/src/lite/fetch.rs b/rs/moq-net/src/lite/fetch.rs index 575136726a6..288655be66a 100644 --- a/rs/moq-net/src/lite/fetch.rs +++ b/rs/moq-net/src/lite/fetch.rs @@ -16,6 +16,9 @@ pub struct Fetch<'a> { /// The instance the subscriber expects; see [`crate::origin::RouteInfo::instance`]. /// Lite07+ only. pub instance: Option, + /// The Node ID of the origin that serves the request, or 0 for whichever the + /// publisher selects. Lite07+ only. + pub node: u64, pub track: Cow<'a, str>, pub priority: i8, /// Reader freshness budget. Lite07+ only; omission uses the publisher's max age alone. @@ -34,6 +37,7 @@ impl Fetch<'_> { Fetch { broadcast: self.broadcast, instance: self.instance, + node: self.node, track: Cow::Owned(self.track.into_owned()), priority: self.priority, max_delay: self.max_delay, @@ -56,6 +60,7 @@ impl<'a> Message<'a> for Fetch<'a> { let broadcast = Path::decode(r, version)?; let instance = super::instance::decode_pin(r, version)?; + let node = super::instance::decode_node(r, version)?; let track = Cow::Borrowed(r.str()?); let priority = super::priority::from_wire(r.u8()?); let max_delay = match version.has_fetch_max_delay() { @@ -76,6 +81,7 @@ impl<'a> Message<'a> for Fetch<'a> { Ok(Self { broadcast, instance, + node, track, priority, max_delay, @@ -95,6 +101,7 @@ impl<'a> Message<'a> for Fetch<'a> { self.broadcast.encode(w, version)?; super::instance::encode_pin(w, version, self.instance.as_ref())?; + super::instance::encode_node(w, version, self.node)?; w.string(&self.track)?; w.u8(super::priority::to_wire(self.priority)); match version.has_fetch_max_delay() { @@ -128,6 +135,7 @@ mod test { fn fetch_sample() -> Fetch<'static> { Fetch { instance: None, + node: 0, broadcast: Path::from_static("room"), track: Cow::Borrowed("video"), priority: 3, @@ -171,6 +179,16 @@ mod test { .into_owned() } + /// Only lite-07 names the origin node; older versions decode as letting the + /// publisher select. + #[test] + fn fetch_node_roundtrips_only_on_lite07() { + let mut msg = fetch_sample(); + msg.node = 0x7a3f; + assert_eq!(fetch_roundtrip(Version::Lite07, &msg).node, 0x7a3f); + assert_eq!(fetch_roundtrip(Version::Lite06, &msg).node, 0); + } + #[test] fn fetch_roundtrips() { for version in [Version::Lite03, Version::Lite04, Version::Lite05] { diff --git a/rs/moq-net/src/lite/instance.rs b/rs/moq-net/src/lite/instance.rs index 9d46a3179f0..336e2357c73 100644 --- a/rs/moq-net/src/lite/instance.rs +++ b/rs/moq-net/src/lite/instance.rs @@ -29,6 +29,23 @@ pub(super) fn decode_pin(r: &mut Decoder<'_>, version: Version) -> Result