From a054e36d2774e2853306337c6b06d359a55c2db7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 13 Sep 2026 13:04:58 -0700 Subject: [PATCH 1/8] claim quest/m1/api-origin-pattern-scopes From 3677aa204bcf7bee32946094ada1381accd21072 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 13 Sep 2026 15:08:22 -0700 Subject: [PATCH 2/8] feat(net)!: scope origins with pattern unions Replace prefix-valued origin scope inputs and outputs with the shared pattern-union types. Co-Authored-By: Muse Spark --- demo/web/src/stats.ts | 3 +- js/moq-boy/src/element.tsx | 3 +- js/net/src/announced.ts | 27 ++-- js/net/src/connection/pool.ts | 6 +- js/net/src/connection/reload.ts | 6 +- js/net/src/ietf/subscriber.ts | 19 ++- js/net/src/lite/subscriber.ts | 4 +- js/net/src/origin.test.ts | 79 +++++++++- js/net/src/origin.ts | 95 +++++++----- js/room/src/room.test.ts | 4 +- js/room/src/room.ts | 9 +- js/watch/src/broadcast.ts | 2 +- quest/m1/README.md | 1 - quest/m1/api-origin-pattern-scopes.md | 38 ----- quest/m1/merge-dev.md | 1 - quest/m2/path-patterns/origin.md | 2 - rs/moq-cli/src/hls.rs | 6 +- rs/moq-cli/src/rtc.rs | 11 +- rs/moq-net/src/ietf/publisher.rs | 10 +- rs/moq-net/src/ietf/session.rs | 6 +- rs/moq-net/src/ietf/subscriber.rs | 12 +- rs/moq-net/src/lite/publisher.rs | 11 +- rs/moq-net/src/lite/subscriber.rs | 5 +- rs/moq-net/src/model/origin.rs | 204 ++++++++++++++++++++------ rs/moq-net/src/path/mod.rs | 15 ++ rs/moq-relay/src/auth.rs | 54 +++---- rs/moq-relay/src/connection.rs | 6 +- rs/moq-tokio/examples/clock.rs | 4 +- rs/moq-tokio/tests/broadcast.rs | 18 ++- 29 files changed, 446 insertions(+), 215 deletions(-) delete mode 100644 quest/m1/api-origin-pattern-scopes.md diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index d2cff394c85..1023575b974 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -117,7 +117,8 @@ discovery.run((effect) => { if (!origin) return; const prefix = Net.Path.from(STATS_PREFIX); - const announced = origin.announced(prefix); + // The origin speaks scopes; the intended prefix converts explicitly to its subtree. + const announced = origin.announced(new Net.Path.Patterns([Net.Path.Pattern.subtree(prefix)])); effect.cleanup(() => announced.close()); // One sub-effect per node so we can tear a node's subscriptions down when it diff --git a/js/moq-boy/src/element.tsx b/js/moq-boy/src/element.tsx index f0f4ec785cb..844a290c701 100644 --- a/js/moq-boy/src/element.tsx +++ b/js/moq-boy/src/element.tsx @@ -130,7 +130,8 @@ export default class MoqBoy extends HTMLElement { // The origin's stream spans reconnects: entries retract when the session dies and // return when the next one re-announces them, so this loop never needs to restart. - const announced = this.origin.consume().announced(prefix); + // The origin speaks scopes; the intended prefix converts explicitly to its subtree. + const announced = this.origin.consume().announced(new Moq.Path.Patterns([Moq.Path.Pattern.subtree(prefix)])); effect.cleanup(() => announced.close()); effect.spawn(async () => { diff --git a/js/net/src/announced.ts b/js/net/src/announced.ts index 40528e66311..de4ba60beee 100644 --- a/js/net/src/announced.ts +++ b/js/net/src/announced.ts @@ -21,7 +21,7 @@ import * as Path from "./path.js"; * @public */ export interface Update { - /** What the route covers, relative to the prefix passed to `announced()`. */ + /** What the route covers, relative to the scope passed to `announced()`. */ pattern: Path.Pattern; /** True while the route is advertised, false when it was retracted. */ active: boolean; @@ -50,13 +50,13 @@ function closeState(state: AnnounceState, abort?: Error) { * @public */ export class Producer { - /** Path prefix this stream is scoped to. */ - prefix: Path.Valid; + /** The scopes this stream presents, as prefix-shaped patterns (`foo/**`, `**`). */ + scope: Path.Patterns; #state = new AnnounceState(); - constructor(prefix = Path.empty()) { - this.prefix = prefix; + constructor(scope: Path.Patterns = new Path.Patterns([Path.Pattern.all()])) { + this.scope = scope; } /** @@ -69,7 +69,7 @@ export class Producer { /** A read handle for this announcement stream. */ consume(): Consumer { - return makeConsumer(this.prefix, this.#state); + return makeConsumer(this.scope, this.#state); } /** Writes an announcement to the queue. */ @@ -88,7 +88,7 @@ export class Producer { // Constructs a Consumer from within this module without exposing a public constructor // that would leak the unexported AnnounceState. Assigned in the class's static block. -let makeConsumer: (prefix: Path.Valid, state: AnnounceState) => Consumer; +let makeConsumer: (scope: Path.Patterns, state: AnnounceState) => Consumer; /** * The read side of an announcement stream. @@ -99,13 +99,13 @@ let makeConsumer: (prefix: Path.Valid, state: AnnounceState) => Consumer; * @public */ export class Consumer { - /** Path prefix this stream is scoped to. */ - prefix: Path.Valid; + /** The scopes this stream presents, as prefix-shaped patterns (`foo/**`, `**`). */ + scope: Path.Patterns; #state: AnnounceState; - private constructor(prefix: Path.Valid, state: AnnounceState) { - this.prefix = prefix; + private constructor(scope: Path.Patterns, state: AnnounceState) { + this.scope = scope; this.#state = state; } @@ -115,7 +115,7 @@ export class Consumer { } static { - makeConsumer = (prefix, state) => new Consumer(prefix, state); + makeConsumer = (scope, state) => new Consumer(scope, state); } /** Returns the next announcement. */ @@ -342,7 +342,8 @@ export class Broadcast { // Follow the table regardless of sessions: a local publish resolves with no // connection at all (and keeps resolving while one reconnects), and the // identity-diffed announcements swap the handle on a republish. - const announced = origin.announced(this.path); + // The scope is the path's subtree: the exact path plus everything beneath it. + const announced = origin.announced(new Path.Patterns([Path.Pattern.subtree(this.path)])); effect.cleanup(() => announced.close()); // Held open while the path is announced. A request resolves to the table's route when diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 6d7f754f522..1091e706028 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -267,7 +267,9 @@ export class Connection { * new one's arrivals stream in. */ announced(prefix: Path.Valid = Path.empty()): Announce.Consumer { - const producer = new Announce.Producer(prefix); + // The origin speaks scopes; the intended prefix converts explicitly to its subtree. + const scope = new Path.Patterns([Path.Pattern.subtree(prefix)]); + const producer = new Announce.Producer(scope); const consumer = producer.consume(); // Closing the consumer closes the shared state, so stop appending after that. @@ -284,7 +286,7 @@ export class Connection { const origin = effect.get(this.#origin); if (!origin) return; - const upstream = origin.announced(prefix); + const upstream = origin.announced(scope); effect.cleanup(() => upstream.close()); // Track what this origin announced so a URL switch retracts it. diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index c22a288bd4d..ea8b427ef9d 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -448,11 +448,13 @@ export class Reload { * Stays empty while the relay lacks {@link Established.discovery}. */ announced(prefix: Path.Valid = emptyPath()): Announce.Consumer { + // The origin speaks scopes; the intended prefix converts explicitly to its subtree. + const scope = new Path.Patterns([Path.Pattern.subtree(prefix)]); // With a consume origin the table already spans reconnects (the forwarder retracts // a dead session's entries), so its stream is the same thing with less machinery. - if (this.consume) return this.consume.announced(prefix); + if (this.consume) return this.consume.announced(scope); - const producer = new Announce.Producer(prefix); + const producer = new Announce.Producer(scope); const consumer = producer.consume(); const pump = new Effect(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index ddfeef67389..dff5b26a740 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -104,8 +104,9 @@ export class Subscriber { // to end from retracting what the other still holds. #announced = new Map(); - // Any consumers that want each new announcement. - #announcedConsumers = new Set(); + // Any consumers that want each new announcement, keyed by the wire interest + // prefix their stream filters on. + #announcedConsumers = new Map(); /** * Creates a new Subscriber instance. @@ -145,13 +146,15 @@ export class Subscriber { * that only answers are both discovered. */ announced(prefix = Path.empty()): announce.Consumer { - const announced = new announce.Producer(prefix); + // The announce stream presents scopes; the wire interest prefix converts + // explicitly to its subtree. + const announced = new announce.Producer(new Path.Patterns([Path.Pattern.subtree(prefix)])); for (const active of this.#announced.keys()) { const suffix = Path.stripPrefix(prefix, active); if (suffix === null) continue; announced.append({ pattern: Path.Pattern.subtree(suffix), active: true }); } - this.#announcedConsumers.add(announced); + this.#announcedConsumers.set(announced, prefix); void this.#runAnnounced(announced, prefix).finally(() => { this.#announcedConsumers.delete(announced); @@ -171,8 +174,8 @@ export class Subscriber { if (count > 0) return; console.debug(`announced: broadcast=${path} active=true`); - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); + for (const [consumer, prefix] of this.#announcedConsumers) { + const suffix = Path.stripPrefix(prefix, path); if (suffix === null) continue; consumer.append({ pattern: Path.Pattern.subtree(suffix), active: true }); } @@ -196,8 +199,8 @@ export class Subscriber { this.#consumes.evict(path); console.debug(`announced: broadcast=${path} active=false`); - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); + for (const [consumer, prefix] of this.#announcedConsumers) { + const suffix = Path.stripPrefix(prefix, path); if (suffix === null) continue; try { consumer.append({ pattern: Path.Pattern.subtree(suffix), active: false }); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 53f07581990..08c677682d1 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -159,7 +159,9 @@ export class Subscriber { * versions stay consistent with that. */ announced(prefix = Path.empty()): announce.Consumer { - const announced = new announce.Producer(prefix); + // The announce stream presents scopes; the wire interest prefix converts + // explicitly to its subtree. + const announced = new announce.Producer(new Path.Patterns([Path.Pattern.subtree(prefix)])); void this.#runAnnounced(announced, prefix); return announced.consume(); } diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 1c5584dd010..b72ab097990 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -48,6 +48,11 @@ async function routed(consumer: Consumer, path: Path.Valid): Promise Path.Pattern.subtree(prefix))); +} + /** A stand-in for a session announcing a route: serves any path from `producer`. */ function provider(producer: BroadcastProducer) { return () => producer.consume(); @@ -194,7 +199,7 @@ test("announced streams the table with prefix-relative paths", async () => { const a = publish(origin, Path.from("room/a")); - const announced = consumer.announced(Path.from("room")); + const announced = consumer.announced(scope(Path.from("room"))); // The initial state arrives first. expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("a")), active: true }); @@ -250,7 +255,7 @@ test("announced reports a broader covering route at the root", async () => { // A route above the requested prefix covers everything under it, so it // presents at the root, matching what request() resolves there. - const announced = consumer.announced(Path.from("room/alice")); + const announced = consumer.announced(scope(Path.from("room/alice"))); expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.empty()), active: true }); dispose(); @@ -1025,3 +1030,73 @@ test("literal and subtree claims keep distinct pattern identities", async () => announced.close(); origin.close(); }); + +test("announced accepts prefix-shaped unions and reports them in the new vocabulary", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + + // The root grant is `**`, the old empty prefix. + const root = consumer.announced(new Path.Patterns([Path.Pattern.all()])); + expect(root.scope.equals(new Path.Patterns([Path.Pattern.all()]))).toBe(true); + + // `foo/**` keeps the old `foo` prefix meaning. + const scoped = consumer.announced(scope(Path.from("room"))); + expect(scoped.scope.equals(scope(Path.from("room")))).toBe(true); + + // Multiple prefixes fan out: a route under each presents under its own member. + const a = publish(origin, Path.from("alpha/x")); + const b = publish(origin, Path.from("beta/y")); + publish(origin, Path.from("other/z")); + const multi = consumer.announced(scope(Path.from("alpha"), Path.from("beta"))); + expect(await multi.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("x")), active: true }); + expect(await multi.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("y")), active: true }); + + root.close(); + scoped.close(); + multi.close(); + a.close(); + b.close(); + origin.close(); +}); + +test("announced with an empty union grants nothing and stays silent", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + + publish(origin, Path.from("room/a")); + const announced = consumer.announced(new Path.Patterns()); + const raced = await Promise.race([announced.next().then(() => "event"), settle().then(() => "silent")]); + expect(raced).toBe("silent"); + + announced.close(); + origin.close(); +}); + +test("announced refuses non-prefix grants without narrowing or widening", () => { + const origin = new Producer(); + const consumer = origin.consume(); + + const refused = (text: string) => { + const union = new Path.Patterns([Path.Pattern.parse(text)]); + expect(() => consumer.announced(union)).toThrow(); + }; + + // An exact path is not a grant over its subtree. + refused("room"); + // The empty pattern names only the root, not everything beneath it. + refused(""); + // Suffixes and segment wildcards name sets a prefix cannot cover. + refused("*room"); + refused("room/*"); + refused("*"); + // A `**` anywhere but the end is not a subtree. + refused("**/room"); + refused("room/**/chat"); + + // A supported member cannot conceal an unsupported one. + const mixed = new Path.Patterns([Path.Pattern.parse("room/**"), Path.Pattern.parse("other")]); + expect(mixed.size).toBe(2); + expect(() => consumer.announced(mixed)).toThrow(); + + origin.close(); +}); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 7447451a7b6..3b7cd527d1b 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -326,8 +326,8 @@ export interface Table { /** Resolve `path`, without waiting for an announcement; see {@link Consumer.request}. */ request(path: Path.Valid): Request; - /** The available broadcasts under `prefix`, as a live stream; see {@link Consumer.announced}. */ - announced(prefix?: Path.Valid): announce.Consumer; + /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ + announced(scope?: Path.Patterns): announce.Consumer; } /** @@ -622,9 +622,9 @@ export class Producer implements Table { return this.#reader.routes(path); } - /** The available broadcasts under `prefix`, as a live stream; see {@link Consumer.announced}. */ - announced(prefix?: Path.Valid): announce.Consumer { - return this.#reader.announced(prefix); + /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ + announced(scope?: Path.Patterns): announce.Consumer { + return this.#reader.announced(scope); } /** Close the origin, every broadcast it still routes, and its announcement streams. Idempotent. */ @@ -694,6 +694,27 @@ function prefixPattern(pattern: Path.Pattern | string): { parsed: Path.Pattern; return { parsed, prefix: Path.from(parsed.text) }; } +/** + * The literal prefixes a scope grants, validating the whole union first. + * + * `foo/**` keeps the old `foo` prefix meaning and `**` keeps the old empty-prefix + * meaning. Anything else (an exact `foo`, the empty pattern, a suffix, or any + * segment wildcard) throws rather than narrowing or widening the grant, so a + * supported member cannot conceal an unsupported one. An empty union grants + * nothing and yields no prefixes. + */ +function scopePrefixes(scope: Path.Patterns): Path.Valid[] { + const prefixes: Path.Valid[] = []; + for (const pattern of scope) { + const prefix = pattern.asPrefix(); + if (prefix === undefined) { + throw new Error(`announced() only supports prefix-shaped patterns (foo/**), got "${pattern.text}"`); + } + prefixes.push(Path.from(prefix)); + } + return prefixes; +} + /** * An open request for a path nothing announced; see {@link Consumer.request}. * @@ -925,19 +946,23 @@ export class Consumer { } /** - * The announced routes under `prefix`, as a live stream: every currently advertised - * prefix arrives first as `active`, then additions and retractions as they happen. A - * local broadcast appears only after {@link broadcast.Producer.announce}; a dynamic - * or received route announces the prefix it covers. Paths are relative to `prefix`. + * The announced routes under `scope`, as a live stream: every currently advertised + * route arriving first as `active`, then additions and retractions as they happen. + * Each member must be prefix-shaped (`foo/**` for the old `foo` prefix, `**` for + * everything); anything else throws rather than narrowing or widening the grant. + * An empty union grants nothing and stays silent. A local broadcast appears only + * after {@link broadcast.Producer.announce}; a dynamic or received route announces + * the prefix it covers. Paths are relative to each scope member's prefix. * The stream ends when the origin closes or the consumer is closed. */ - announced(prefix: Path.Valid = Path.empty()): announce.Consumer { - const producer = new announce.Producer(prefix); - void this.#runAnnounced(producer, prefix); + announced(scope: Path.Patterns = new Path.Patterns([Path.Pattern.all()])): announce.Consumer { + const prefixes = scopePrefixes(scope); + const producer = new announce.Producer(scope); + void this.#runAnnounced(producer, prefixes); return producer.consume(); } - async #runAnnounced(producer: announce.Producer, prefix: Path.Valid): Promise { + async #runAnnounced(producer: announce.Producer, prefixes: Path.Valid[]): Promise { // Keyed by suffix, valued by identity plus route. Diffing identity rather than // mere presence means a republish emits a retraction then a fresh announcement; // a re-price of the same identity emits another active (a restart). @@ -953,29 +978,31 @@ export class Consumer { const next = new Map(); // Routes first, so an advertised local at the same path overwrites it: the // announcement points at whatever request() would resolve. - // The most specific route covering `prefix` itself wins the root slot, - // matching request() resolution. - let rootLen = -1; - for (const [key, entries] of routes ?? []) { - const entry = entries[0]; - if (!entry) continue; - const snap: Advertised = { identity: entry.identity, route: entry.route.peek() }; - const advertised = Path.Pattern.parse(key); - for (const residual of advertised.rebase(prefix)) { - const presentedPath = residual.text; - if (residual.asPrefix() === "") { - const spec = advertised.segments.length; - if (spec < rootLen) continue; - rootLen = spec; + // Each scope member keeps its own root slot: the most specific route + // covering that member's prefix wins it, matching request() resolution. + for (const prefix of prefixes) { + let rootLen = -1; + for (const [key, entries] of routes ?? []) { + const entry = entries[0]; + if (!entry) continue; + const snap: Advertised = { identity: entry.identity, route: entry.route.peek() }; + const advertised = Path.Pattern.parse(key); + for (const residual of advertised.rebase(prefix)) { + const presentedPath = residual.text; + if (residual.asPrefix() === "") { + const spec = advertised.segments.length; + if (spec < rootLen) continue; + rootLen = spec; + } + next.set(presentedPath, snap); } - next.set(presentedPath, snap); } - } - for (const [path, front] of local ?? []) { - const route = advertisedLocal?.get(path); - if (!route) continue; - const suffix = Path.stripPrefix(prefix, path); - if (suffix !== null) next.set(Path.Pattern.subtree(suffix).text, { identity: front, route }); + for (const [path, front] of local ?? []) { + const route = advertisedLocal?.get(path); + if (!route) continue; + const suffix = Path.stripPrefix(prefix, path); + if (suffix !== null) next.set(Path.Pattern.subtree(suffix).text, { identity: front, route }); + } } for (const [path, snap] of active) { diff --git a/js/room/src/room.test.ts b/js/room/src/room.test.ts index 62ccee9840e..35ee3e357b8 100644 --- a/js/room/src/room.test.ts +++ b/js/room/src/room.test.ts @@ -15,8 +15,8 @@ test("room restores the announce prefix and reconciles local identity changes", const streams: Net.Announce.Producer[] = []; const connection = { origin: new Signal({ - announced(prefix: Net.Path.Valid) { - const stream = new Net.Announce.Producer(prefix); + announced(scope?: Net.Path.Patterns) { + const stream = new Net.Announce.Producer(scope); streams.push(stream); stream.append({ pattern: Net.Path.Pattern.subtree(Net.Path.from("bob/camera.hang")), diff --git a/js/room/src/room.ts b/js/room/src/room.ts index 0d5b325f4d9..8413badda14 100644 --- a/js/room/src/room.ts +++ b/js/room/src/room.ts @@ -62,10 +62,11 @@ export class Room { const origin = effect.get(this.connection.origin); if (!origin) return; const prefix = effect.get(this.prefix) ?? Moq.Path.empty(); - const announced = origin.announced(prefix); + // The origin speaks scopes; the intended prefix converts explicitly to its subtree. + const announced = origin.announced(new Moq.Path.Patterns([Moq.Path.Pattern.subtree(prefix)])); effect.cleanup(() => announced.close()); - effect.spawn(this.#run.bind(this, announced, effect)); + effect.spawn(this.#run.bind(this, announced, prefix, effect)); effect.cleanup(() => { for (const remote of this.#remotes.peek().values()) remote.close(); this.#remotes.set(new Map()); @@ -78,7 +79,7 @@ export class Room { return this.#remotes; } - async #run(announced: Moq.Announce.Consumer, effect: Effect): Promise { + async #run(announced: Moq.Announce.Consumer, prefix: Moq.Path.Valid, effect: Effect): Promise { for (;;) { const update = await Promise.race([effect.cancel, announced.next()]); if (!update) break; @@ -93,7 +94,7 @@ export class Room { if (local && parsed.identity === local) continue; if (update.active) { - this.#add(parsed.identity, parsed.kind, Moq.Path.join(announced.prefix, suffix)); + this.#add(parsed.identity, parsed.kind, Moq.Path.join(prefix, suffix)); } else { this.#remove(parsed.identity, parsed.kind); } diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 2aeeca0b2ca..cf718d53c14 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -182,7 +182,7 @@ export class Broadcast { const origin = effect.get(this.in.origin); if (!origin) return; - const announced = origin.announced(Path.empty()); + const announced = origin.announced(); effect.cleanup(() => announced.close()); this.#announced.set(new Set()); diff --git a/quest/m1/README.md b/quest/m1/README.md index fe2b7e5c411..f39d835518e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -25,7 +25,6 @@ does not require it. ## Quests - [Reserved codes](/quest/m1/lite-reserved-codes.md) - the four stream codes sent from the reserved range are registered in the draft's own range and round-trip in both languages -- [Origin scope API](/quest/m1/api-origin-pattern-scopes.md) - typed scope grants preserve current prefixes and refuse unsupported patterns - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy - [Publisher finish borrows](/quest/m1/api-finish-borrow.md) - finish borrows the handle so abort can still run after a clean end - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the send and receive estimates carry `estimated_*_rate` on the C ABI, every binding, and moqsink diff --git a/quest/m1/api-origin-pattern-scopes.md b/quest/m1/api-origin-pattern-scopes.md deleted file mode 100644 index 168a4b6ae1e..00000000000 --- a/quest/m1/api-origin-pattern-scopes.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] Origin scope pattern API - -## Goal - -Published origin scope APIs use the shared pattern-union types before the -release, while preserving every currently supported prefix grant. General -pattern enforcement remains in m2 without another signature change. - -## Plan - -Replace prefix-valued public scope inputs and allowed-scope outputs in Rust -and JavaScript with the shared pattern-union types. Include public selection -operations that expose `PathPrefixes`. Roots remain literal paths. Keep the -existing refusal result for scopes that cannot be represented; do not add a -second scope method or silently narrow or widen a grant. - -Implement prefix-shaped unions completely: `foo/**` retains the old `foo` -prefix meaning and `**` retains the old empty-prefix meaning. An empty union -grants nothing. An exact `foo` or empty pattern is not a prefix grant and must -be refused until general pattern enforcement lands. Validate the whole union -before constructing a scoped handle, so a supported member cannot conceal an -unsupported one. - -Convert every existing caller's intended prefixes explicitly, including relay -auth, cluster sessions, HLS, stats, native clients, examples, and any binding -that exposes these operations. `allowed` reports the actual grant in the new -vocabulary. Preserve nested scoping and literal-root rebasing for all accepted -unions. Keep legacy token and wire prefix decoding unchanged at their boundary. - -Run Rust/JS scope tests and the existing cross-language CI cases. Cover the -root grant, empty union, multiple prefixes, nested roots, unchanged allowed -and refused paths, and explicit refusal of exact, suffix, and segment-wildcard -grants. Update public API documentation. No new wire encoding or v1 token -default belongs here. Target dev. - -## Related - -- [Origin scopes](/quest/m2/path-patterns/origin.md) - implements the full pattern algebra through this API diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md index ae0b70a2723..53a8d7c8d24 100644 --- a/quest/m1/merge-dev.md +++ b/quest/m1/merge-dev.md @@ -50,7 +50,6 @@ additive quest that builds on dev-only code start on main afterwards from - [Reserved codes](/quest/m1/lite-reserved-codes.md) - nothing provisional ships on the released wire - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the estimates carry one name on the C ABI and every binding - [moq-tokio names](/quest/m1/api-tokio-names.md) - moq-tokio's first release under this name has settled names -- [Origin scope API](/quest/m1/api-origin-pattern-scopes.md) - typed scope grants preserve current prefixes and refuse unsupported patterns - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy - [m0](/quest/m0/README.md) - every release blocker lands or is punted before the merge diff --git a/quest/m2/path-patterns/origin.md b/quest/m2/path-patterns/origin.md index 27362a4b7c3..6310dc41694 100644 --- a/quest/m2/path-patterns/origin.md +++ b/quest/m2/path-patterns/origin.md @@ -48,5 +48,3 @@ the existing subscription closes and no further objects arrive. ## Required - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts - -- [Origin scope pattern API](/quest/m1/api-origin-pattern-scopes.md) - the published shape and functional prefix behavior land before the release diff --git a/rs/moq-cli/src/hls.rs b/rs/moq-cli/src/hls.rs index d2960cd84ac..02ac50f9009 100644 --- a/rs/moq-cli/src/hls.rs +++ b/rs/moq-cli/src/hls.rs @@ -6,7 +6,6 @@ use std::net::SocketAddr; use anyhow::Context; use axum::http::Method; use hang::moq_net; -use hang::moq_net::AsPath; use crate::moq::{ImportTarget, notify_ready}; @@ -74,8 +73,11 @@ pub async fn import(target: ImportTarget, playlist: String) -> anyhow::Result<() /// `//master.m3u8` and `//manifest.mpd`); other broadcasts in the /// Origin are not served. pub async fn export(origin: moq_net::origin::Consumer, args: ExportArgs, name: String) -> anyhow::Result<()> { + let scope = moq_net::Patterns::from( + moq_net::Pattern::subtree(&name).with_context(|| format!("invalid broadcast name `{name}`"))?, + ); let scoped = origin - .scope(&[name.as_path()]) + .scope(&scope) .with_context(|| format!("failed to scope origin to broadcast `{name}`"))?; let mut config = moq_hls::export::Config::default(); diff --git a/rs/moq-cli/src/rtc.rs b/rs/moq-cli/src/rtc.rs index ff9bebe700d..cb65fe37b6f 100644 --- a/rs/moq-cli/src/rtc.rs +++ b/rs/moq-cli/src/rtc.rs @@ -7,7 +7,6 @@ use std::net::SocketAddr; use anyhow::Context; use axum::http::Method; use hang::moq_net; -use hang::moq_net::AsPath; use moq_tokio::RedactedUrl; use url::Url; @@ -68,8 +67,11 @@ pub async fn listen_import(target: ImportTarget, listen: Listen) -> anyhow::Resu /// WHEP server: serve WebRTC plays of `name` from the Origin (export). pub async fn listen_export(origin: moq_net::origin::Consumer, name: String, listen: Listen) -> anyhow::Result<()> { + let scope = moq_net::Patterns::from( + moq_net::Pattern::subtree(&name).with_context(|| format!("invalid broadcast name `{name}`"))?, + ); let subscriber = origin - .scope(&[name.as_path()]) + .scope(&scope) .with_context(|| format!("failed to scope origin to broadcast `{name}`"))?; // A WHEP server only reads; it still needs a publisher handle for the shared // glue, so hand it an unused, empty Origin producer. @@ -80,8 +82,11 @@ pub async fn listen_export(origin: moq_net::origin::Consumer, name: String, list /// Restrict a producer to the single broadcast `name` so a WHIP peer can only publish it. fn scope_producer(origin: &moq_net::origin::Producer, name: &str) -> anyhow::Result { + let scope = moq_net::Patterns::from( + moq_net::Pattern::subtree(name).with_context(|| format!("invalid broadcast name `{name}`"))?, + ); origin - .scope(&[name.as_path()]) + .scope(&scope) .with_context(|| format!("failed to scope origin to broadcast `{name}`")) } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index be16c0b41e2..57fdf432a30 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1617,10 +1617,12 @@ where // A prefix outside our scope (empty origin, or a token that doesn't grant it) // just means we have nothing to announce; respond with an empty set rather than // erroring, which would look fatal to the peer. - let origin = self - .origin - .scope(&[prefix.as_path()]) - .unwrap_or_else(|| self.origin.empty()); + // The wire prefix decodes as a literal path; convert it explicitly to its + // subtree grant, refusing anything that cannot be a subtree. + let scope = crate::Pattern::subtree(prefix.as_str()) + .map(crate::Patterns::from) + .unwrap_or_default(); + let origin = self.origin.scope(&scope).unwrap_or_else(|| self.origin.empty()); // Send OK response match self.version { diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index fd7bc70e08f..9f662253500 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -982,9 +982,13 @@ mod tests { #[tokio::test] async fn every_permitted_prefix_gets_its_own_subscribe_namespace() { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + let scope: crate::Patterns = ["cam", "mic"] + .into_iter() + .map(|prefix| crate::Pattern::subtree(prefix).unwrap()) + .collect(); let scoped = origin .with_root("rootns") - .and_then(|rooted| rooted.scope(&[crate::Path::new("cam"), crate::Path::new("mic")])) + .and_then(|rooted| rooted.scope(&scope)) .expect("scope the origin to two prefixes"); let gate = kio::Producer::new(true); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 38eb4bcebcc..d5d7da7131e 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -637,7 +637,11 @@ where /// advertise answers with an empty set, which costs one stream, while waiting to find /// out costs a round trip on every session. pub fn subscribe_prefixes(&self) -> Vec { - self.origin.allowed().map(|p| p.to_owned()).collect() + self.origin + .allowed() + .iter() + .map(|pattern| Path::new(pattern.as_prefix().expect("allowed patterns are prefix-shaped")).to_owned()) + .collect() } /// Send SUBSCRIBE_NAMESPACE for one prefix on a bidi stream. @@ -2826,9 +2830,10 @@ mod tests { #[tokio::test] async fn a_rooted_subscriber_asks_for_its_scope_not_its_root() { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + let scope = crate::Patterns::from(crate::Pattern::subtree("cam").unwrap()); let scoped = origin .with_root("rootns") - .and_then(|rooted| rooted.scope(&[crate::Path::new("cam")])) + .and_then(|rooted| rooted.scope(&scope)) .expect("scope the origin"); let gate = kio::Producer::new(true); @@ -2898,9 +2903,10 @@ mod tests { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); let consumer = origin.consume(); + let scope = crate::Patterns::from(crate::Pattern::subtree("cam").unwrap()); let scoped = origin .with_root("rootns") - .and_then(|rooted| rooted.scope(&[crate::Path::new("cam")])) + .and_then(|rooted| rooted.scope(&scope)) .expect("scope the origin"); let session = crate::lite::test_transport::ScriptedSession::new(namespace_response(VERSION, "x.hang").await); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 8b4acdf5ba9..30c6638224b 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -10,7 +10,7 @@ use std::{ use web_transport_trait::Stats; use crate::{ - AsPath, Error, Hop, Hops, + Error, Hop, Hops, coding::{Encode, Stream, Writer}, lite::{ self, @@ -200,7 +200,7 @@ impl Publisher, origin: &origin::Consumer, announced: &mut announce::Consumer, - prefix: impl AsPath, + prefix: impl crate::AsPath, self_origin: Hop, version: Version, ) -> Result<(), Error> { @@ -542,10 +542,15 @@ impl AnnounceServe { // that doesn't grant it), we simply have nothing to announce. Respond with an // empty set and keep the stream open (the subscriber treats a FIN here as a // fatal stream close), rather than erroring, which would reset the stream. + // The wire prefix decodes as a literal path; convert it explicitly to its + // subtree grant, refusing anything that cannot be a subtree. + let scope = crate::Pattern::subtree(prefix.as_str()) + .map(crate::Patterns::from) + .unwrap_or_default(); let origin = self .shared .origin - .scope(&[prefix.as_path()]) + .scope(&scope) .unwrap_or_else(|| self.shared.origin.empty()); // Register the split-horizon peer on the announce cursor too. The origin // model uses this exposure to park a reflected copy before it can replace diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 7f51e24c0a9..e84fbcc8767 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -518,10 +518,13 @@ pub(super) struct SubscriberDriver { impl SubscriberDriver { pub fn new(subscriber: Subscriber) -> Self { + // The granted scopes double as the wire announce-interest prefixes; they are + // always prefix-shaped, so the conversion back to paths cannot fail. let prefixes = subscriber .origin .allowed() - .map(|p| p.to_owned()) + .iter() + .map(|pattern| Path::new(pattern.as_prefix().expect("allowed patterns are prefix-shaped")).to_owned()) .collect::>() .into_iter() .map(|prefix| AnnouncePrefix::new(subscriber.clone(), prefix)) diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index c6a05a3bb13..d478f644501 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -919,13 +919,14 @@ impl OriginNodes { } } - // Returns nested roots that match the prefixes. + // Returns nested roots that match the patterns. // PathPrefixes guarantees no duplicates or overlapping prefixes. - pub fn select(&self, prefixes: &PathPrefixes) -> Option { + pub fn select(&self, patterns: &Patterns) -> Option { + let prefixes = PathPrefixes::from_patterns(patterns)?; let mut roots = Vec::new(); for (root, absolute) in &self.nodes { - for prefix in prefixes { + for prefix in &prefixes { if root.has_prefix(prefix) { // Keep the existing subtree if we're allowed to access it. roots.push((root.to_owned(), absolute.clone())); @@ -1369,16 +1370,16 @@ impl Producer { Ok(prefixes) } - /// Returns a new Producer restricted to publishing under one of `prefixes`. + /// Returns a new Producer restricted to publishing under one of `patterns`. /// - /// Returns None if there are no legal prefixes (the requested prefixes are - /// disjoint from this producer's current scope). - // TODO accept PathPrefixes instead of &[Path] - pub fn scope(&self, prefixes: &[Path]) -> Option { - let prefixes = PathPrefixes::new(prefixes); + /// Each member must be prefix-shaped (`foo/**` for the old `foo` prefix, `**` for + /// the old empty prefix). Returns None when any member cannot be represented yet + /// (an exact `foo`, the empty pattern, a suffix, or any segment wildcard), or when + /// the requested patterns are disjoint from this producer's current scope. + pub fn scope(&self, patterns: &Patterns) -> Option { Some(Producer { info: self.info, - nodes: self.nodes.select(&prefixes)?, + nodes: self.nodes.select(patterns)?, root: self.root.clone(), shared: self.shared.clone(), pool: self.pool.clone(), @@ -1426,10 +1427,14 @@ impl Producer { &self.root } - /// Iterate over the path prefixes this handle is permitted to publish or subscribe under. - // TODO return PathPrefixes - pub fn allowed(&self) -> impl Iterator> { - self.nodes.nodes.iter().map(|(root, _)| root) + /// The granted scopes as prefix-shaped patterns: `foo/**` for the old `foo` + /// prefix, `**` for the old empty prefix. + pub fn allowed(&self) -> Patterns { + self.nodes + .nodes + .iter() + .map(|(root, _)| Pattern::subtree(root.as_str()).expect("scope roots are literal paths")) + .collect() } /// Converts a relative path to an absolute path. @@ -3590,14 +3595,15 @@ impl Consumer { pub async fn routed(&self, path: impl AsPath) -> Option { let path = path.as_path(); - // Scope a fresh consumer down to this path: any covering route then clamps - // to exactly the path, so we only wake for relevant announcements. - let consumer = self.scope(std::slice::from_ref(&path))?; + // Scope a fresh consumer down to this path's subtree: any covering route then + // clamps to exactly the path, so we only wake for relevant announcements. + let subtree = Pattern::subtree(path.as_str()).ok()?; + let consumer = self.scope(&Patterns::from(subtree))?; // `scope` keeps narrower permissions intact: if we ask for `foo` on a // consumer limited to `foo/specific`, no route can ever clamp to exactly // `foo`. Bail rather than loop forever. - if !consumer.allowed().any(|allowed| path.has_prefix(allowed)) { + if !consumer.allowed().matches(path.as_str()) { return None; } @@ -3628,8 +3634,11 @@ impl Consumer { // `scope` keeps narrower permissions intact: if the whole path is not // reachable, no route can ever cover it, so bail rather than loop forever. - let scoped = self.scope(std::slice::from_ref(&path)).ok_or(Error::Unauthorized)?; - if !scoped.allowed().any(|allowed| path.has_prefix(allowed)) { + let subtree = Pattern::subtree(path.as_str()) + .map(Patterns::from) + .map_err(|_| Error::Unauthorized)?; + let scoped = self.scope(&subtree).ok_or(Error::Unauthorized)?; + if !scoped.allowed().matches(path.as_str()) { return Err(Error::Unauthorized); } loop { @@ -3667,15 +3676,15 @@ impl Consumer { } } - /// Returns a new Consumer restricted to broadcasts under one of `prefixes`. + /// Returns a new Consumer restricted to broadcasts under one of `patterns`. /// - /// Returns None if there are no legal prefixes (the requested prefixes are - /// disjoint from this consumer's current scope, so it would always return None). - // TODO accept PathPrefixes instead of &[Path] - pub fn scope(&self, prefixes: &[Path]) -> Option { - let prefixes = PathPrefixes::new(prefixes); + /// Each member must be prefix-shaped (`foo/**` for the old `foo` prefix, `**` for + /// the old empty prefix). Returns None when any member cannot be represented yet + /// (an exact `foo`, the empty pattern, a suffix, or any segment wildcard), or when + /// the requested patterns are disjoint from this consumer's current scope. + pub fn scope(&self, patterns: &Patterns) -> Option { Some(Consumer { - nodes: self.nodes.select(&prefixes)?, + nodes: self.nodes.select(patterns)?, ..self.clone() }) } @@ -3817,10 +3826,14 @@ impl Consumer { &self.root } - /// Iterate over the path prefixes this handle is permitted to publish or subscribe under. - // TODO return PathPrefixes - pub fn allowed(&self) -> impl Iterator> { - self.nodes.nodes.iter().map(|(root, _)| root) + /// The granted scopes as prefix-shaped patterns: `foo/**` for the old `foo` + /// prefix, `**` for the old empty prefix. + pub fn allowed(&self) -> Patterns { + self.nodes + .nodes + .iter() + .map(|(root, _)| Pattern::subtree(root.as_str()).expect("scope roots are literal paths")) + .collect() } /// Converts a relative path to an absolute path. @@ -4088,6 +4101,11 @@ mod tests { Pattern::subtree(prefix).unwrap() } + /// The scope granting these prefixes: each spelled as its subtree pattern. + fn scopes(prefixes: &[&str]) -> Patterns { + prefixes.iter().map(|prefix| subtree(prefix)).collect() + } + /// Yield to the driver until `check` passes, bounded so a bug fails instead /// of hanging. async fn settle(mut check: impl FnMut() -> bool) { @@ -4226,10 +4244,7 @@ mod tests { let producer = origin(1).produce(); let bare = producer.node_count(); - let scoped = producer - .consume() - .scope(&[Path::new("room/a"), Path::new("room/b")]) - .unwrap(); + let scoped = producer.consume().scope(&scopes(&["room/a", "room/b"])).unwrap(); assert_eq!(producer.node_count(), bare, "scoping should not create nodes"); assert!(producer.consume().with_root("room/c").is_some()); assert_eq!(producer.node_count(), bare, "rooting should not create nodes"); @@ -4247,8 +4262,8 @@ mod tests { #[tokio::test] async fn scoped_handles_survive_a_prune() { let producer = origin(1).produce(); - let scoped = producer.scope(&[Path::new("channel")]).unwrap(); - let consumer = producer.consume().scope(&[Path::new("channel")]).unwrap(); + let scoped = producer.scope(&scopes(&["channel"])).unwrap(); + let consumer = producer.consume().scope(&scopes(&["channel"])).unwrap(); // Create the scoped subtree and prune it straight back out. let mut first = scoped.create_broadcast("channel/chat").unwrap(); @@ -4266,7 +4281,7 @@ mod tests { #[tokio::test] async fn announce_clamps_to_producer_scope() { let producer = origin(1).produce(); - let scoped = producer.scope(&[Path::new("room")]).unwrap(); + let scoped = producer.scope(&scopes(&["room"])).unwrap(); // A broad claim through a narrow scope advertises only the intersection. let _a = scoped.announce("", Route::default()).unwrap(); @@ -4285,7 +4300,7 @@ mod tests { let producer = origin(1).produce(); let _a = producer.announce("", Route::default()).unwrap(); - let consumer = producer.consume().scope(&[Path::new("room")]).unwrap(); + let consumer = producer.consume().scope(&scopes(&["room"])).unwrap(); let mut announced = consumer.announced(); announced.assert_next_active("room"); } @@ -4563,7 +4578,7 @@ mod tests { #[test] fn wildcard_scope_is_refused_not_clamped() { let producer = origin(1).produce(); - let scoped = producer.scope(&[Path::new("room")]).unwrap(); + let scoped = producer.scope(&scopes(&["room"])).unwrap(); let err = scoped .dynamic("**".parse().unwrap(), Route::default()) .err() @@ -4929,7 +4944,7 @@ mod tests { async fn out_of_scope_request_never_reaches_the_dynamic_handler() { let producer = origin(1).produce(); let dynamic = producer.dynamic(Pattern::all(), Route::default()).unwrap(); - let scoped = producer.consume().scope(&[Path::new("tenant-a")]).unwrap(); + let scoped = producer.consume().scope(&scopes(&["tenant-a"])).unwrap(); // `tenant-a-other` shares a character prefix but not a segment, so this // also pins that the check is segment-aware rather than textual. @@ -5449,16 +5464,115 @@ mod tests { let producer = origin(1).produce(); let _a = producer.announce("", Route::default()).unwrap(); - let consumer = producer - .consume() - .scope(&[Path::new("alpha"), Path::new("beta")]) - .unwrap(); + let consumer = producer.consume().scope(&scopes(&["alpha", "beta"])).unwrap(); let mut announced = consumer.announced(); announced.assert_next_active("alpha"); announced.assert_next_active("beta"); announced.assert_next_wait(); } + #[test] + fn scope_reports_prefix_shaped_grants() { + let producer = origin(1).produce(); + + // The root grant is `**`, the old empty prefix. + let root = producer.scope(&Patterns::from(Pattern::all())).unwrap(); + assert_eq!(root.allowed(), Patterns::from(Pattern::all())); + + // `foo/**` keeps the old `foo` prefix meaning. + let scoped = producer.scope(&scopes(&["room"])).unwrap(); + assert_eq!(scoped.allowed(), scopes(&["room"])); + + // Multiple prefixes round-trip, with overlap collapsed. + let multi = producer.scope(&scopes(&["room", "room/chat", "anon"])).unwrap(); + assert_eq!(multi.allowed(), scopes(&["room", "anon"])); + + // The consumer side reports the same way. + let consumer = producer.consume().scope(&scopes(&["room"])).unwrap(); + assert_eq!(consumer.allowed(), scopes(&["room"])); + } + + #[test] + fn scope_empty_union_grants_nothing() { + let producer = origin(1).produce(); + + // An empty union grants nothing: scoping is refused, like a disjoint prefix. + assert!(producer.scope(&Patterns::new()).is_none()); + assert!(producer.consume().scope(&Patterns::new()).is_none()); + } + + #[test] + fn scope_nests_and_rebases_roots() { + let producer = origin(1).produce(); + + // Narrowing twice intersects; the grant stays in the new vocabulary. + let scoped = producer.scope(&scopes(&["room"])).unwrap(); + let nested = scoped.scope(&scopes(&["room/chat"])).unwrap(); + assert_eq!(nested.allowed(), scopes(&["room/chat"])); + + // A disjoint nesting is refused, not widened. + assert!(scoped.scope(&scopes(&["other"])).is_none()); + + // A literal root rebases the grant without changing its meaning. + let rooted = nested.with_root("room/chat").unwrap(); + assert_eq!(rooted.allowed(), scopes(&[""])); + + // Publishing through the nested view lands where the root says. + let mut broadcast = nested.create_broadcast("room/chat/live").unwrap(); + assert!(producer.consume().get_broadcast("room/chat/live").is_some()); + broadcast.finish(); + } + + #[test] + fn scope_refuses_non_prefix_grants() { + let producer = origin(1).produce(); + let refused = |text: &str| { + let pattern: Pattern = text.parse().unwrap(); + let union = Patterns::from(pattern); + assert!( + producer.scope(&union).is_none(), + "{text} is not a prefix grant and must be refused" + ); + assert!( + producer.consume().scope(&union).is_none(), + "{text} is not a prefix grant and must be refused" + ); + }; + + // An exact path is not a grant over its subtree. + refused("room"); + // The empty pattern names only the root, not everything beneath it. + refused(""); + // Suffixes and segment wildcards name sets a prefix cannot cover. + refused("*room"); + refused("room/*"); + refused("*"); + // A `**` anywhere but the end is not a subtree. + refused("**/room"); + refused("room/**/chat"); + } + + #[test] + fn scope_validates_the_whole_union() { + let producer = origin(1).produce(); + + // A supported member cannot conceal an unsupported one: neither member + // contains the other, so both survive reduction and the union is refused. + let mixed: Patterns = ["room/**".parse().unwrap(), "other".parse().unwrap()] + .into_iter() + .collect(); + assert_eq!(mixed.len(), 2); + assert!(producer.scope(&mixed).is_none()); + assert!(producer.consume().scope(&mixed).is_none()); + + let mixed: Patterns = ["room/**".parse().unwrap(), "other/*.jpg".parse().unwrap()] + .into_iter() + .collect(); + assert_eq!(mixed.len(), 2); + assert!(producer.scope(&mixed).is_none()); + assert!(producer.consume().scope(&mixed).is_none()); + } + /// Charging a link accumulates onto both halves, saturating rather than wrapping /// so a bogus peer sorts last, not first. The ceiling is the largest cost a /// varint can carry, so whatever a peer advertises, the sum we forward still diff --git a/rs/moq-net/src/path/mod.rs b/rs/moq-net/src/path/mod.rs index 5c6bdca25a7..cd663bb4f34 100644 --- a/rs/moq-net/src/path/mod.rs +++ b/rs/moq-net/src/path/mod.rs @@ -817,6 +817,21 @@ impl PathPrefixes { pub fn iter(&self) -> std::slice::Iter<'_, PathOwned> { self.paths.iter() } + + /// Build from prefix-shaped patterns, refusing the whole union when any member is not one. + /// + /// `foo/**` keeps the old `foo` prefix meaning and `**` keeps the old empty-prefix + /// meaning. An exact `foo`, the empty pattern, a suffix, or any segment wildcard is + /// not a prefix grant and refuses the whole union with `None`, so a supported member + /// cannot conceal an unsupported one. An empty union grants nothing. + pub fn from_patterns(patterns: &Patterns) -> Option { + let mut paths = Vec::with_capacity(patterns.len()); + for pattern in patterns { + let prefix = pattern.as_prefix()?; + paths.push(Path::new(prefix).to_owned()); + } + Some(Self::new(paths)) + } } impl std::ops::Deref for PathPrefixes { diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index 82c8a0e38fd..caf4a544cd9 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -7,7 +7,7 @@ use std::sync::Arc; use axum::http; use moq_auth::{Counters, Grant, Request, lease}; use moq_auth::{Pattern, Patterns}; -use moq_net::{Path, PathOwned, PathPrefixes, stats::Tier}; +use moq_net::{Path, PathOwned, stats::Tier}; use serde::{Deserialize, Serialize}; use serde_with::{OneOrMany, serde_as}; use url::Url; @@ -170,10 +170,10 @@ pub struct AuthToken { pub(crate) path: String, /// The root the session is scoped to: the grant's `root` alias, else the dialed path. pub root: PathOwned, - /// Prefixes the holder may subscribe to, relative to `root`. - pub subscribe: PathPrefixes, - /// Prefixes the holder may publish to, relative to `root`. - pub publish: PathPrefixes, + /// The subtree grants the holder may subscribe to, relative to `root`. + pub subscribe: Patterns, + /// The subtree grants the holder may publish to, relative to `root`. + pub publish: Patterns, /// The tier this session's stats record under. pub tier: Tier, } @@ -181,28 +181,24 @@ pub struct AuthToken { impl AuthToken { /// Reduce `grant` for a session that dialed `path`. /// - /// The origin scopes by prefix until pattern scopes land, so only `foo/**` and - /// `**` have an exact prefix. Anything else is refused naming the pattern, - /// including a literal `foo`: reading it as the prefix `foo` would widen one - /// broadcast into a subtree. + /// The origin scopes by prefix, so only `foo/**` and `**` have an exact prefix. + /// Anything else is refused naming the pattern, including a literal `foo`: + /// reading it as the prefix `foo` would widen one broadcast into a subtree. + /// The token keeps the Patterns the grant already yields rather than converting + /// them to prefixes. pub fn new(path: &str, grant: &Grant) -> Result { - let prefixes = |patterns: &Patterns| -> Result { - patterns - .iter() - .map(|pattern| { - pattern - .as_prefix() - .map(|prefix| Path::new(prefix).to_owned()) - .ok_or_else(|| AuthError::UnsupportedPattern(pattern.to_string())) - }) - .collect() + let supported = |patterns: &Patterns| -> Result { + match patterns.iter().find(|pattern| pattern.as_prefix().is_none()) { + Some(pattern) => Err(AuthError::UnsupportedPattern(pattern.to_string())), + None => Ok(patterns.clone()), + } }; let root = grant.root.as_deref().unwrap_or(path); Ok(Self { path: path.to_string(), root: Path::new(root).to_owned(), - subscribe: prefixes(&grant.subscribe)?, - publish: prefixes(&grant.publish)?, + subscribe: supported(&grant.subscribe)?, + publish: supported(&grant.publish)?, tier: crate::configured_tier(grant.tier.clone()), }) } @@ -214,13 +210,10 @@ impl AuthToken { } /// Whether `other` still covers everything this token scopes: the same root and - /// every prefix still granted. A narrower re-check closes the session until + /// every grant still held. A narrower re-check closes the session until /// pattern scopes can resize it in place. pub(crate) fn covered_by(&self, other: &Self) -> bool { - let covers = |granted: &PathPrefixes, held: &PathPrefixes| { - held.iter().all(|prefix| granted.iter().any(|g| prefix.has_prefix(g))) - }; - self.root == other.root && covers(&other.subscribe, &self.subscribe) && covers(&other.publish, &self.publish) + self.root == other.root && other.subscribe.covers(&self.subscribe) && other.publish.covers(&self.publish) } } @@ -418,10 +411,7 @@ mod tests { let request = auth.request(moq_auth::Transport::Quic, "/anon/room"); let admitted = futures::executor::block_on(auth.admit(request, Counters::default())).unwrap(); assert_eq!(admitted.token.root, Path::new("anon/room").to_owned()); - assert_eq!( - admitted.token.subscribe, - PathPrefixes::from(vec![Path::new("anon").to_owned()]) - ); + assert_eq!(admitted.token.subscribe, patterns(&["anon/**"])); assert_eq!(admitted.token.tier, Tier::default()); } @@ -432,8 +422,8 @@ mod tests { grant.tier = Some("gold".into()); let token = AuthToken::new("/vanity/room", &grant).unwrap(); assert_eq!(token.root, Path::new("pid/room").to_owned()); - assert_eq!(token.publish, PathPrefixes::from(vec![Path::new("alice").to_owned()])); - assert_eq!(token.subscribe, PathPrefixes::from(vec![Path::new("").to_owned()])); + assert_eq!(token.publish, patterns(&["alice/**"])); + assert_eq!(token.subscribe, patterns(&["**"])); assert_eq!(token.tier, Tier::new("gold")); for pattern in ["*/chat", "alice", ""] { diff --git a/rs/moq-relay/src/connection.rs b/rs/moq-relay/src/connection.rs index 9c3cdec5193..c34069717bb 100644 --- a/rs/moq-relay/src/connection.rs +++ b/rs/moq-relay/src/connection.rs @@ -203,13 +203,13 @@ pub(crate) fn authorize( match (&publish, &subscribe) { (Some(publish), Some(subscribe)) => { - tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, publish = %publish.allowed().map(moq_net::Path::as_str).collect::>().join(","), subscribe = %subscribe.allowed().map(moq_net::Path::as_str).collect::>().join(","), "session accepted"); + tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, publish = %publish.allowed().iter().map(|pattern| pattern.as_str()).collect::>().join(","), subscribe = %subscribe.allowed().iter().map(|pattern| pattern.as_str()).collect::>().join(","), "session accepted"); } (Some(publish), None) => { - tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, publish = %publish.allowed().map(moq_net::Path::as_str).collect::>().join(","), "publisher accepted"); + tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, publish = %publish.allowed().iter().map(|pattern| pattern.as_str()).collect::>().join(","), "publisher accepted"); } (None, Some(subscribe)) => { - tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, subscribe = %subscribe.allowed().map(moq_net::Path::as_str).collect::>().join(","), "subscriber accepted"); + tracing::info!(%transport, ?role, tier = %token.tier, root = %token.root, subscribe = %subscribe.allowed().iter().map(|pattern| pattern.as_str()).collect::>().join(","), "subscriber accepted"); } _ => unreachable!("authorized above guarantees at least one origin"), } diff --git a/rs/moq-tokio/examples/clock.rs b/rs/moq-tokio/examples/clock.rs index e777b8c61b3..683a56ef331 100644 --- a/rs/moq-tokio/examples/clock.rs +++ b/rs/moq-tokio/examples/clock.rs @@ -98,8 +98,10 @@ async fn main() -> anyhow::Result<()> { tracing::info!(broadcast = %config.broadcast, "waiting for broadcast to be online"); let path: moq_net::Path<'_> = config.broadcast.into(); + let scope = + moq_net::Patterns::from(moq_net::Pattern::subtree(path.as_str()).context("invalid broadcast name")?); let consumer = origin - .scope(&[path]) + .scope(&scope) .context("not allowed to consume broadcast")? .consume(); let mut announced = consumer.announced(); diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index f6411a875f7..a699ddd7eac 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -2665,7 +2665,7 @@ async fn announce_interest_unauthorized_keeps_session_alive() { let publish = pub_origin .consume() - .scope(&["allowed".into()]) + .scope(&moq_net::Patterns::from(moq_net::Pattern::subtree("allowed").unwrap())) .expect("failed to scope publish origin"); let (mut server, addr) = test_server().await; @@ -2674,7 +2674,12 @@ async fn announce_interest_unauthorized_keeps_session_alive() { // "denied" is disjoint from the publisher's scope, so its announce stream is FINed. let sub_origin = moq_tokio::origin::spawn(Hop::random()); let consume = sub_origin - .scope(&["allowed".into(), "denied".into()]) + .scope( + &["allowed", "denied"] + .into_iter() + .map(|prefix| moq_net::Pattern::subtree(prefix).unwrap()) + .collect::(), + ) .expect("failed to scope consume origin"); let sub_consumer = consume.consume(); let mut announcements = sub_consumer.announced(); @@ -2732,7 +2737,12 @@ async fn publish_only_client_to_subscribe_only_server() { // ── subscriber (server): interested in both "allowed" and "denied" ── let sub_origin = moq_tokio::origin::spawn(Hop::random()); let consume = sub_origin - .scope(&["allowed".into(), "denied".into()]) + .scope( + &["allowed", "denied"] + .into_iter() + .map(|prefix| moq_net::Pattern::subtree(prefix).unwrap()) + .collect::(), + ) .expect("failed to scope consume origin"); let sub_consumer = consume.consume(); let mut announcements = sub_consumer.announced(); @@ -2808,7 +2818,7 @@ async fn publish_only_client_to_subscribe_only_server() { let publish = pub_origin .consume() - .scope(&["allowed".into()]) + .scope(&moq_net::Patterns::from(moq_net::Pattern::subtree("allowed").unwrap())) .expect("failed to scope publish origin"); let (_client, connection) = tokio::time::timeout(TIMEOUT, connect_once(test_client().with_publisher(publish), url)) From fb54bc77de1ce91cb14ccc0f76198e663648bcc1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 17:27:19 -0700 Subject: [PATCH 3/8] feat(js)!: scope discovery with one pattern, name announcements from the origin `announced(scope: Path.Pattern)` on origins and sessions takes a single prefix-shaped pattern (default `**`) and yields patterns relative to the origin, clamped to the scope, mirroring the Rust origin where announced paths are root-relative and scope never moves the root. A union of scopes with member-relative events was ambiguous: `alpha/x` and `beta/x` both presented as `x/**`. Announce.Producer/Consumer drop their scope field; nothing read it. Relay auth keeps PublicAccess as literal prefixes, since it feeds the legacy token claims; only the verified AuthToken carries Patterns. Scope coverage uses Patterns::covers. Co-Authored-By: Claude Opus 5 --- demo/web/src/index.ts | 8 +-- demo/web/src/stats.ts | 9 +-- doc/lib/js/net.md | 8 +-- js/moq-boy/src/element.tsx | 7 +- js/net/src/announced.ts | 46 ++++++------ js/net/src/connection/established.ts | 7 +- js/net/src/connection/pool.ts | 12 ++-- js/net/src/connection/reload.ts | 16 ++--- js/net/src/ietf/connection.ts | 12 ++-- js/net/src/ietf/subscriber.test.ts | 30 ++++---- js/net/src/ietf/subscriber.ts | 27 ++++---- js/net/src/integration.test.ts | 6 +- js/net/src/internal.ts | 16 +++++ js/net/src/lite/connection.ts | 6 +- js/net/src/lite/subscriber.test.ts | 28 ++++---- js/net/src/lite/subscriber.ts | 30 ++++---- js/net/src/origin.test.ts | 83 +++++----------------- js/net/src/origin.ts | 100 ++++++++++----------------- js/room/src/room.test.ts | 7 +- js/room/src/room.ts | 9 +-- 20 files changed, 202 insertions(+), 265 deletions(-) diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index d7858bff143..7a3b3abf20f 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -182,7 +182,7 @@ function createTile(name: string): WatchTile { const discovery = new Signals.Effect(); discovery.run((effect) => { const prefix = prefixPath(effect.get(prefixInput)); - const announced = connection.announced(prefix); + const announced = connection.announced(Net.Path.Pattern.subtree(prefix)); effect.cleanup(() => announced.close()); const live = new Set(); @@ -190,9 +190,9 @@ discovery.run((effect) => { for (;;) { const entry = await Promise.race([effect.cancel, announced.next()]); if (!entry) break; - const suffix = entry.pattern.asPrefix(); - if (suffix === undefined) continue; - const path = Net.Path.join(prefix, Net.Path.from(suffix)); + const covered = entry.pattern.asPrefix(); + if (covered === undefined) continue; + const path = Net.Path.from(covered); // Only catalog-backed broadcasts are watchable streams; this skips the relay's // `.stats` broadcast (see the stats dashboard demo for that one). if (!path.endsWith(".hang") && !path.endsWith(".msf")) continue; diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index 1023575b974..0fdeea0543a 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -117,8 +117,7 @@ discovery.run((effect) => { if (!origin) return; const prefix = Net.Path.from(STATS_PREFIX); - // The origin speaks scopes; the intended prefix converts explicitly to its subtree. - const announced = origin.announced(new Net.Path.Patterns([Net.Path.Pattern.subtree(prefix)])); + const announced = origin.announced(Net.Path.Pattern.subtree(prefix)); effect.cleanup(() => announced.close()); // One sub-effect per node so we can tear a node's subscriptions down when it @@ -132,9 +131,11 @@ discovery.run((effect) => { for (;;) { const entry = await Promise.race([effect.cancel, announced.next()]); if (!entry) break; - const node = entry.pattern.asPrefix(); + const covered = entry.pattern.asPrefix(); + if (covered === undefined) continue; + const path = Net.Path.from(covered); + const node = Net.Path.stripPrefix(prefix, path); if (!node) continue; - const path = Net.Path.join(prefix, Net.Path.from(node)); if (entry.active) { if (subs.has(node)) continue; diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 37bbe04951e..70e4b25fa3d 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -40,7 +40,7 @@ for (;;) { - **Origins** hold the broadcasts, not the connection: closing a session unannounces them but leaves them created for the next one. `origin.request(path)` prefers a local broadcast, so a page that watches what it publishes reads its own copy with no round trip. Create, populate, then `announce()` for an exact path; use `dynamic(pattern, route)` when the set of paths is not known: an exact-path subscribe before the tracks exist is refused, and announcing only makes a path discoverable. - **Connections** race WebTransport against WebSocket. `new Connection({ url })` pools one connection per relay URL and reconnects with backoff, which the elements use. `closed` settles when the handle is released (`null` on a clean close); the failure that stopped retrying the current URL is `error`, and a new URL recovers the same handle. A connection owns one send-rate sampler and one `Bandwidth.Allocator`; publishers reserve against it so their encoder targets sum to the estimate instead of each matching it. - **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched. -- **Discovery** by prefix (`origin.announced(prefix)`). Each event's `pattern` is the claim, relative to that prefix. `origin.dynamic(pattern, route)` advertises any path pattern; a prefix is `live/**`. +- **Discovery** by scope (`origin.announced(scope)`, a prefix-shaped `Path.Pattern` like `live/**`; default everything). Each event's `pattern` is the claim, relative to the origin. `origin.dynamic(pattern, route)` advertises any path pattern. - **Subscriptions** carry a priority and max age; groups arrive out of order and are read frame by frame, with `Lagged` when a reader asks for a frame the group never held and `GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. - **Errors** split by scope: a stream reset throws `StreamError` with a `StreamCode`, a session close gives `SessionError` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Same on either transport. Named conditions like `Lagged` subclass `StreamError`, so one `code` check catches a gap whether it happened here or at the peer, and resetting a moq-lite stream with one sends that code rather than a bare internal error. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. @@ -81,9 +81,9 @@ Three operations, on an origin: advertised; `close()` retracts it. A request under a prefix-shaped claim with no local broadcast is a `BroadcastRequest` to `accept` or `reject`. -A wildcard is a capability, not an inventory. `origin.announced(prefix)` -yields `Announce.Update` values: `pattern` is the claim relative to `prefix`, -`active` is false on a retraction, and `route` carries hops and cost while +A wildcard is a capability, not an inventory. `origin.announced(scope)` +yields `Announce.Update` values: `pattern` is the claim relative to the origin, +clamped to `scope`; `active` is false on a retraction, and `route` carries hops and cost while advertised (omitted on a retraction). Use `pattern.asPrefix()` when you need a prefix-shaped claim; an arbitrary pattern is not a broadcast name. Resolving a non-prefix pattern into a diff --git a/js/moq-boy/src/element.tsx b/js/moq-boy/src/element.tsx index 844a290c701..9039badd6c8 100644 --- a/js/moq-boy/src/element.tsx +++ b/js/moq-boy/src/element.tsx @@ -130,8 +130,7 @@ export default class MoqBoy extends HTMLElement { // The origin's stream spans reconnects: entries retract when the session dies and // return when the next one re-announces them, so this loop never needs to restart. - // The origin speaks scopes; the intended prefix converts explicitly to its subtree. - const announced = this.origin.consume().announced(new Moq.Path.Patterns([Moq.Path.Pattern.subtree(prefix)])); + const announced = this.origin.consume().announced(Moq.Path.Pattern.subtree(prefix)); effect.cleanup(() => announced.close()); effect.spawn(async () => { @@ -140,7 +139,9 @@ export default class MoqBoy extends HTMLElement { if (!entry) break; // Skip nested paths (e.g. "viewer/..." sub-broadcasts). - const suffix = entry.pattern.asPrefix(); + const covered = entry.pattern.asPrefix(); + if (covered === undefined) continue; + const suffix = Moq.Path.stripPrefix(prefix, Moq.Path.from(covered)); if (!suffix || suffix.includes("/")) continue; const id = suffix; diff --git a/js/net/src/announced.ts b/js/net/src/announced.ts index de4ba60beee..1b58e5e6c80 100644 --- a/js/net/src/announced.ts +++ b/js/net/src/announced.ts @@ -1,5 +1,5 @@ /** - * Broadcast announcement streams: which broadcast paths are available under a prefix. + * Broadcast announcement streams: which broadcast paths are available under a scope. * * @module */ @@ -21,7 +21,10 @@ import * as Path from "./path.js"; * @public */ export interface Update { - /** What the route covers, relative to the scope passed to `announced()`. */ + /** + * What the route covers, relative to the origin (for a session, its URL path). A + * route claimed above the scope passed to `announced()` is clamped to that scope. + */ pattern: Path.Pattern; /** True while the route is advertised, false when it was retracted. */ active: boolean; @@ -50,15 +53,8 @@ function closeState(state: AnnounceState, abort?: Error) { * @public */ export class Producer { - /** The scopes this stream presents, as prefix-shaped patterns (`foo/**`, `**`). */ - scope: Path.Patterns; - #state = new AnnounceState(); - constructor(scope: Path.Patterns = new Path.Patterns([Path.Pattern.all()])) { - this.scope = scope; - } - /** * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}. * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it. @@ -69,7 +65,7 @@ export class Producer { /** A read handle for this announcement stream. */ consume(): Consumer { - return makeConsumer(this.scope, this.#state); + return makeConsumer(this.#state); } /** Writes an announcement to the queue. */ @@ -88,24 +84,20 @@ export class Producer { // Constructs a Consumer from within this module without exposing a public constructor // that would leak the unexported AnnounceState. Assigned in the class's static block. -let makeConsumer: (scope: Path.Patterns, state: AnnounceState) => Consumer; +let makeConsumer: (state: AnnounceState) => Consumer; /** * The read side of an announcement stream. * * Created internally: obtain one from {@link Producer.consume} or the connection's - * `announced(prefix)`. + * `announced(scope)`. * * @public */ export class Consumer { - /** The scopes this stream presents, as prefix-shaped patterns (`foo/**`, `**`). */ - scope: Path.Patterns; - #state: AnnounceState; - private constructor(scope: Path.Patterns, state: AnnounceState) { - this.scope = scope; + private constructor(state: AnnounceState) { this.#state = state; } @@ -115,7 +107,7 @@ export class Consumer { } static { - makeConsumer = (scope, state) => new Consumer(scope, state); + makeConsumer = (state) => new Consumer(state); } /** Returns the next announcement. */ @@ -276,7 +268,8 @@ export class Broadcast { return; } - const announced = conn.announced(path); + const scope = Path.Pattern.subtree(path); + const announced = conn.announced(scope); effect.cleanup(() => announced.close()); let current: broadcast.Consumer | undefined; @@ -296,9 +289,9 @@ export class Broadcast { const event = await Promise.race([effect.cancel, announced.next()]); if (!event) break; - // Prefix-shaped claims covering this path (`asPrefix() === ""`). A literal - // PATTERN ad at the same path has `asPrefix() === undefined` and is skipped. - if (event.pattern.asPrefix() !== "") continue; + // Prefix-shaped claims covering this path clamp to its subtree. A literal + // PATTERN ad at the same path is not prefix-shaped and is skipped. + if (!event.pattern.equals(scope)) continue; if (event.active) { // A live subscription survives a redundant (re-)announce; only replace a dead one. @@ -343,7 +336,8 @@ export class Broadcast { // connection at all (and keeps resolving while one reconnects), and the // identity-diffed announcements swap the handle on a republish. // The scope is the path's subtree: the exact path plus everything beneath it. - const announced = origin.announced(new Path.Patterns([Path.Pattern.subtree(this.path)])); + const scope = Path.Pattern.subtree(this.path); + const announced = origin.announced(scope); effect.cleanup(() => announced.close()); // Held open while the path is announced. A request resolves to the table's route when @@ -368,9 +362,9 @@ export class Broadcast { const event = await Promise.race([effect.cancel, announced.next()]); if (!event) break; - // Prefix-shaped claims covering this path (`asPrefix() === ""`). A literal - // PATTERN ad at the same path has `asPrefix() === undefined` and is skipped. - if (event.pattern.asPrefix() !== "") continue; + // Prefix-shaped claims covering this path clamp to its subtree. A literal + // PATTERN ad at the same path is not prefix-shaped and is skipped. + if (!event.pattern.equals(scope)) continue; live.set(event.active); } diff --git a/js/net/src/connection/established.ts b/js/net/src/connection/established.ts index 428de781e90..9d7b33ba635 100644 --- a/js/net/src/connection/established.ts +++ b/js/net/src/connection/established.ts @@ -34,8 +34,11 @@ export interface Established { */ readonly discovery: boolean; - /** Subscribe to broadcast announcements under an optional path prefix, returning paths relative to that prefix. */ - announced(prefix?: Path.Valid): announce.Consumer; + /** + * Subscribe to broadcast announcements under `scope`, a prefix-shaped pattern (`foo/**`, + * default `**` for everything). Patterns are relative to the session, not the scope. + */ + announced(scope?: Path.Pattern): announce.Consumer; /** * Consume the broadcast at the given path, immediately. diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 1091e706028..91018aca008 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -262,14 +262,12 @@ export class Connection { } /** - * Subscribe to broadcast announcements under an optional prefix, spanning reconnects - * and URL switches: a switch retracts everything from the old relay's origin, then the - * new one's arrivals stream in. + * Subscribe to broadcast announcements under `scope` (a prefix-shaped pattern, default + * everything), spanning reconnects and URL switches: a switch retracts everything from + * the old relay's origin, then the new one's arrivals stream in. */ - announced(prefix: Path.Valid = Path.empty()): Announce.Consumer { - // The origin speaks scopes; the intended prefix converts explicitly to its subtree. - const scope = new Path.Patterns([Path.Pattern.subtree(prefix)]); - const producer = new Announce.Producer(scope); + announced(scope: Path.Pattern = Path.Pattern.all()): Announce.Consumer { + const producer = new Announce.Producer(); const consumer = producer.consume(); // Closing the consumer closes the shared state, so stop appending after that. diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index ea8b427ef9d..4d1ab1184b7 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -4,7 +4,6 @@ import { Allocator } from "../bandwidth.ts"; import { error, SessionCode, SessionError } from "../error.ts"; import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; -import { empty as emptyPath } from "../path.ts"; import * as Time from "../time.ts"; import { type ConnectProps, connect, type WebSocketOptions, type WebTransportProps } from "./connect.ts"; import type { Established } from "./established.ts"; @@ -439,7 +438,8 @@ export class Reload { } /** - * Subscribe to broadcast announcements under an optional prefix, spanning reconnects. + * Subscribe to broadcast announcements under `scope` (a prefix-shaped pattern, default + * everything), spanning reconnects. * * The same {@link Announce.Consumer} stream as {@link Established.announced}, but everything active * is retracted (an `active: false` update) whenever the connection drops and re-announced on @@ -447,14 +447,12 @@ export class Reload { * * Stays empty while the relay lacks {@link Established.discovery}. */ - announced(prefix: Path.Valid = emptyPath()): Announce.Consumer { - // The origin speaks scopes; the intended prefix converts explicitly to its subtree. - const scope = new Path.Patterns([Path.Pattern.subtree(prefix)]); + announced(scope: Path.Pattern = Path.Pattern.all()): Announce.Consumer { // With a consume origin the table already spans reconnects (the forwarder retracts // a dead session's entries), so its stream is the same thing with less machinery. if (this.consume) return this.consume.announced(scope); - const producer = new Announce.Producer(scope); + const producer = new Announce.Producer(); const consumer = producer.consume(); const pump = new Effect(); @@ -466,7 +464,7 @@ export class Reload { // consumer empty rather than opening a subscription that can't be answered. if (!conn.discovery) return; - const upstream = conn.announced(prefix); + const upstream = conn.announced(scope); effect.cleanup(() => upstream.close()); // Track what this connection announced so we can retract it if the connection drops. @@ -487,8 +485,8 @@ export class Reload { // Retract everything from the connection that just went away, so a per-broadcast // watcher tears down instead of clinging to the dead route. if (consumer.closed.peek() === undefined) { - for (const prefix of active) { - producer.append({ pattern: Path.Pattern.parse(prefix), active: false }); + for (const pattern of active) { + producer.append({ pattern: Path.Pattern.parse(pattern), active: false }); } } } diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index b7602740976..4b5cdb6dc98 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -6,7 +6,7 @@ import { type Probe, type Stats, transportStats } from "../connection/stats.ts"; import { type Transport, transportOf } from "../connection/transport.ts"; import { error, fromClose, ProtocolViolation, StreamCode, StreamError } from "../error.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; -import * as Path from "../path.ts"; +import type * as Path from "../path.ts"; import { type Reader, Readers, type Stream } from "../stream.ts"; import { ControlStreamAdapter, NativeSession, type Session } from "./adapter.ts"; import * as Cluster from "./cluster.ts"; @@ -177,13 +177,9 @@ export class Connection implements Established { } } - /** - * Gets an announced reader for the specified prefix. - * @param prefix - The prefix for announcements - * @returns An Announced instance - */ - announced(prefix = Path.empty()): announce.Consumer { - return this.#subscriber.announced(prefix); + /** Gets an announced reader for `scope`; see {@link Established.announced}. */ + announced(scope?: Path.Pattern): announce.Consumer { + return this.#subscriber.announced(scope); } /** diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index e9972cff16f..c8ba0dd454b 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -57,7 +57,7 @@ test("every peer is asked", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); - subscriber.announced(Path.empty()); + subscriber.announced(); expect(await nextStream(pair.client)).toBeDefined(); }); @@ -71,7 +71,7 @@ test("an unsolicited announcement lands", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); // The question we asked, which this peer never answers. expect(await nextStream(pair.client)).toBeDefined(); @@ -148,7 +148,7 @@ test("an announcement survives the first of its two sources ending", async () => const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); // Unsolicited first, then the same path inline on the subscription. @@ -185,7 +185,7 @@ test("an announcement ends once its last source does", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); const request = await Stream.open(pair.server, { version: VERSION }); @@ -222,9 +222,9 @@ test("a subscription that dies releases what it advertised", async () => { const subscriber = new Subscriber({ session }); // Two feeds, so one outlives the stream that carries the advertisement. - const doomed = subscriber.announced(Path.empty()); + const doomed = subscriber.announced(); const streamA = await acceptSubscribeNamespace(pair.client); - const survivor = subscriber.announced(Path.empty()); + const survivor = subscriber.announced(); await acceptSubscribeNamespace(pair.client); await inlineNamespace(streamA, Path.from("orphan")); @@ -249,7 +249,7 @@ test("a duplicate legacy publish_namespace is still refused", async () => { const session = new NativeSession(pair.server, Version.DRAFT_15, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const first = await Stream.open(pair.server, { version: Version.DRAFT_15 }); const handler = subscriber.runPublishNamespace( @@ -285,7 +285,7 @@ test("an entry buffered past a consumer close does not pin the path", async () = const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); // Both entries land in one chunk, so the second is buffered while the first is being @@ -298,7 +298,7 @@ test("an entry buffered past a consumer close does not pin the path", async () = // Whatever the loop managed to attach, the stream gave back on its way out. await new Promise((resolve) => setTimeout(resolve, 50)); - const fresh = subscriber.announced(Path.empty()); + const fresh = subscriber.announced(); const seeded = await Promise.race([ fresh.next(), new Promise<"nothing">((resolve) => setTimeout(() => resolve("nothing"), 250)), @@ -316,7 +316,7 @@ test("concurrent legacy publish_namespace requests take one reference", async () const session = new NativeSession(pair.server, Version.DRAFT_15, true); const subscriber = new Subscriber({ session }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); // Dispatched together, as the connection would on two incoming streams. const first = await Stream.open(pair.server, { version: Version.DRAFT_15 }); @@ -356,7 +356,7 @@ test("an inline NAMESPACE that looped back through us is dropped", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); // Ours coming back, then someone else's. Only the second is news. @@ -374,7 +374,7 @@ test("an inline NAMESPACE that starts looping back is retracted", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); await inlineNamespace(subscription, Path.from("theirs"), { hops: [PEER], cost: 0n }); @@ -390,7 +390,7 @@ test("a PUBLISH_NAMESPACE that looped back through us is refused", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); const request = await Stream.open(pair.server, { version: VERSION }); @@ -424,7 +424,7 @@ test("a NAMESPACE missing its hop path closes the session", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - subscriber.announced(Path.empty()); + subscriber.announced(); const subscription = await acceptSubscribeNamespace(pair.client); // The base form, which a negotiated session must never send. @@ -447,7 +447,7 @@ test("a PUBLISH_NAMESPACE update that starts looping back is detached", async () const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await acceptSubscribeNamespace(pair.client); const advert = (hops: Hop[]) => diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index dff5b26a740..060e375b4b4 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -3,6 +3,7 @@ import * as broadcast from "../broadcast.ts"; import { BroadcastCache } from "../consume.ts"; import { error, ProtocolViolation, reason } from "../error.ts"; import * as netGroup from "../group.ts"; +import { scopePrefix } from "../internal.ts"; import * as Path from "../path.ts"; import type { Reader, Stream } from "../stream.ts"; import { type Timescale, Timestamp } from "../time.ts"; @@ -139,20 +140,20 @@ export class Subscriber { } /** - * Gets an announced reader for the specified prefix. + * Gets an announced reader for `scope`, a prefix-shaped pattern (`foo/**`, or `**` + * for everything). Patterns are relative to the session, not the scope. * * The peer is asked with SUBSCRIBE_NAMESPACE regardless of what it declared, and an * unsolicited PUBLISH_NAMESPACE lands here too, so a peer that only tells and one * that only answers are both discovered. */ - announced(prefix = Path.empty()): announce.Consumer { - // The announce stream presents scopes; the wire interest prefix converts - // explicitly to its subtree. - const announced = new announce.Producer(new Path.Patterns([Path.Pattern.subtree(prefix)])); + announced(scope: Path.Pattern = Path.Pattern.all()): announce.Consumer { + // The wire speaks announce interest by prefix. + const prefix = scopePrefix(scope); + const announced = new announce.Producer(); for (const active of this.#announced.keys()) { - const suffix = Path.stripPrefix(prefix, active); - if (suffix === null) continue; - announced.append({ pattern: Path.Pattern.subtree(suffix), active: true }); + if (!Path.hasPrefix(prefix, active)) continue; + announced.append({ pattern: Path.Pattern.subtree(active), active: true }); } this.#announcedConsumers.set(announced, prefix); @@ -175,9 +176,8 @@ export class Subscriber { console.debug(`announced: broadcast=${path} active=true`); for (const [consumer, prefix] of this.#announcedConsumers) { - const suffix = Path.stripPrefix(prefix, path); - if (suffix === null) continue; - consumer.append({ pattern: Path.Pattern.subtree(suffix), active: true }); + if (!Path.hasPrefix(prefix, path)) continue; + consumer.append({ pattern: Path.Pattern.subtree(path), active: true }); } } @@ -200,10 +200,9 @@ export class Subscriber { console.debug(`announced: broadcast=${path} active=false`); for (const [consumer, prefix] of this.#announcedConsumers) { - const suffix = Path.stripPrefix(prefix, path); - if (suffix === null) continue; + if (!Path.hasPrefix(prefix, path)) continue; try { - consumer.append({ pattern: Path.Pattern.subtree(suffix), active: false }); + consumer.append({ pattern: Path.Pattern.subtree(path), active: false }); } catch { // Consumer already closed, will be cleaned up } diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index d16c9dca835..d8637e4816b 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -76,11 +76,11 @@ async function runPublishSubscribeFlow(protocol: string, version?: number) { expect(entry.pattern.asPrefix()).toBe("test" as Path.Valid); expect(entry.active).toBe(true); - // Prefix-scoped discovery returns paths relative to the requested prefix. - const prefixed = client.announced(Path.from("root")); + // Scoped discovery only echoes the suffix on the wire, but presents the whole path. + const prefixed = client.announced(Path.Pattern.subtree(Path.from("root"))); const prefixedEntry = await prefixed.next(); if (!prefixedEntry) throw new Error("expected prefixed entry"); - expect(prefixedEntry.pattern.asPrefix()).toBe("child" as Path.Valid); + expect(prefixedEntry.pattern.asPrefix()).toBe("root/child" as Path.Valid); expect(prefixedEntry.active).toBe(true); // Client consumes the broadcast and subscribes to a track diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index e1f3df3727b..cb47de2a802 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -8,9 +8,25 @@ import type { Dispose, Getter } from "@moq/signals"; import type { Announcer, Producer as BroadcastProducer } from "./broadcast.ts"; import type { Frame, Consumer as GroupConsumer } from "./group.ts"; +import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; import type { Groups, Producer, Request, Subscriber } from "./track.ts"; +/** + * The literal prefix a discovery scope covers: `foo` for `foo/**`, the empty path for `**`. + * + * Anything else (an exact `foo`, the empty pattern, a suffix, or any segment wildcard) + * throws rather than narrowing or widening the scope. Until general pattern matching + * lands, discovery filters by prefix. + */ +export function scopePrefix(scope: Path.Pattern): Path.Valid { + const prefix = scope.asPrefix(); + if (prefix === undefined) { + throw new Error(`announced() only supports prefix-shaped patterns (foo/**), got "${scope.text}"`); + } + return Path.from(prefix); +} + /** * What a non-blocking group read found, which is everything the caller needs to decide what * to do next: no second look at the track's closed state, and no ordering rule to get wrong. diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index c56ccd7c4b8..e3be681ea9f 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -7,7 +7,7 @@ import { type Transport, transportOf } from "../connection/transport.ts"; import { error, fromClose, StreamCode, StreamError } from "../error.ts"; import { type Hop, randomHop } from "../hop.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; -import * as Path from "../path.ts"; +import type * as Path from "../path.ts"; import { type Reader, Readers, Stream, Writer } from "../stream.ts"; import { AnnounceRequest } from "./announce.ts"; import { Fetch } from "./fetch.ts"; @@ -169,8 +169,8 @@ export class Connection implements Established { } } - announced(prefix = Path.empty()): announce.Consumer { - return this.#subscriber.announced(prefix); + announced(scope?: Path.Pattern): announce.Consumer { + return this.#subscriber.announced(scope); } consume(path: Path.Valid): broadcast.Consumer { diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 6f64d430bfe..fe735e75e5b 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -130,7 +130,7 @@ const PEER = HopSchema.parse(2n); test("a restart from the same publisher is a route change, not a republish", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -170,7 +170,7 @@ test("a restart from the same publisher is a route change, not a republish", asy test("a restart that re-prices the same publisher emits the new route", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -206,7 +206,7 @@ test("a restart that re-prices the same publisher emits the new route", async () test("a lite-05 duplicate announce follows the same restart rule", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_05); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_05)); @@ -233,7 +233,7 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { // `unknown_publisher_restart_replaces` regression. test("a restart from an unidentified publisher replaces rather than reroutes", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); @@ -347,7 +347,7 @@ test("an announce skipped as a reflected loop still holds its path", async () => // The subscriber's own origin, so a chain naming it reflects back through us. const SELF = 1n; const { subscriber, send, abortReason, sessionEnded, settle } = announceHarness(Version.DRAFT_06, SELF); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -389,7 +389,7 @@ test("an announce skipped as a reflected loop still holds its path", async () => test("a restart replaces an announce that was skipped as a reflected loop", async () => { const SELF = 1n; const { subscriber, send, settle } = announceHarness(Version.DRAFT_06, SELF); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -419,7 +419,7 @@ test("a restart replaces an announce that was skipped as a reflected loop", asyn test("retiring an id whose announce was skipped ends nothing", async () => { const SELF = 1n; const { subscriber, send, settle } = announceHarness(Version.DRAFT_06, SELF); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -454,7 +454,7 @@ test("retiring an id whose announce was skipped ends nothing", async () => { test("a draft-02 initial announcement can still be retracted", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_02); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); // ANNOUNCE_INIT carries the initial set. These are advertisements like any other, so @@ -472,7 +472,7 @@ test("a draft-02 initial announcement can still be retracted", async () => { test("a duplicate start is reported even when its own route reflects", async () => { const SELF = 1n; const { subscriber, send, settle } = announceHarness(Version.DRAFT_06, SELF); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -506,7 +506,7 @@ test("a duplicate start is reported even when its own route reflects", async () test("a draft-02 initial set naming a path twice is refused", async () => { const { subscriber, send, abortReason, sessionEnded, settle } = announceHarness(Version.DRAFT_02); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); // One advertisement per path, and the initial set is advertisements. Two entries for @@ -530,7 +530,7 @@ test("a draft-02 initial set naming a path twice is refused", async () => { test("a violation on a very long path still ends the session", async () => { const SELF = 1n; const { subscriber, send, sessionEnded, settle } = announceHarness(Version.DRAFT_06, SELF); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); @@ -557,7 +557,7 @@ test("a draft-04 duplicate start is a violation, not a restart", async () => { // restart, is exempt. The Rust loop routes every other version through `start_announce`, // which rejects it. const { subscriber, send, sessionEnded, settle } = announceHarness(Version.DRAFT_04); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); const active: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_A] }; @@ -574,7 +574,7 @@ test("a draft-04 duplicate start is a violation, not a restart", async () => { test("a draft-05 duplicate start is still a restart", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_05); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_05)); @@ -598,7 +598,7 @@ test("a draft-05 duplicate start is still a restart", async () => { test("literal pattern and prefix wire claims retain separate identities", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(Path.empty()); + const announced = subscriber.announced(); await settle(); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); await send((w) => diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 08c677682d1..f61d629eb36 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -6,6 +6,7 @@ import { BroadcastCache } from "../consume.ts"; import { error, ProtocolViolation, reason, StreamCode, StreamError } from "../error.ts"; import * as netGroup from "../group.ts"; import { Cost, type Hop, Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { scopePrefix } from "../internal.ts"; import * as Path from "../path.ts"; import { type Reader, Stream } from "../stream.ts"; import * as Time from "../time.ts"; @@ -152,17 +153,18 @@ export class Subscriber { } /** - * Subscribe to broadcast announcements under `prefix`. + * Subscribe to broadcast announcements under `scope`, a prefix-shaped pattern + * (`foo/**`, or `**` for everything). Patterns are relative to the session, not + * the scope. * * Reflected announces (those whose hop chain already includes this * connection) are always dropped: moq-lite-06 has none to keep, and older * versions stay consistent with that. */ - announced(prefix = Path.empty()): announce.Consumer { - // The announce stream presents scopes; the wire interest prefix converts - // explicitly to its subtree. - const announced = new announce.Producer(new Path.Patterns([Path.Pattern.subtree(prefix)])); - void this.#runAnnounced(announced, prefix); + announced(scope: Path.Pattern = Path.Pattern.all()): announce.Consumer { + const announced = new announce.Producer(); + // The wire speaks announce interest by prefix, and echoes suffixes beneath it. + void this.#runAnnounced(announced, scopePrefix(scope)); return announced.consume(); } @@ -230,13 +232,13 @@ export class Subscriber { // ANNOUNCE_OK, so nothing names the publisher. for (const suffix of init.suffixes) { const pattern = Path.Pattern.subtree(suffix); - const path = Path.join(prefix, suffix); + const claim = pattern.rooted(prefix); if (advertised.has(pattern.text)) { - throw new ProtocolViolation(`duplicate announce for ${path}`); + throw new ProtocolViolation(`duplicate announce for ${claim.text}`); } advertised.set(pattern.text, { publisher: undefined, live: true }); - console.debug(`announced: broadcast=${path} active=true`); - announced.append({ pattern, active: true, route: Route.default }); + console.debug(`announced: broadcast=${claim.text} active=true`); + announced.append({ pattern: claim, active: true, route: Route.default }); } break; } @@ -318,6 +320,8 @@ export class Subscriber { continue; } + // The wire names the suffix beneath the interest prefix; the claim names the + // covered paths from the session root, which is what the consumer sees. const claim = pattern.rooted(prefix); const suffix = pattern.asPrefix(); const path = suffix === undefined ? undefined : Path.join(prefix, Path.from(suffix)); @@ -352,7 +356,7 @@ export class Subscriber { if (!previous?.live) return; if (path !== undefined) this.#consumes.evict(path); console.debug(`announced: broadcast=${claim.text} active=false`); - announced.append({ pattern, active: false }); + announced.append({ pattern: claim, active: false }); }; // In Lite05+ the sender's origin arrives via AnnounceOk, not in each hop @@ -398,7 +402,7 @@ export class Subscriber { if (!routesEqual(previous.route, route)) { advertised.set(pattern.text, { publisher, live: true, route }); console.debug(`announced: broadcast=${claim.text} rerouted`); - announced.append({ pattern, active: true, route }); + announced.append({ pattern: claim, active: true, route }); } else { console.debug(`announced: broadcast=${claim.text} rerouted`); } @@ -416,7 +420,7 @@ export class Subscriber { advertised.set(pattern.text, { publisher, live: true, route }); console.debug(`announced: broadcast=${claim.text} active=true`); - announced.append({ pattern, active: true, route }); + announced.append({ pattern: claim, active: true, route }); } announced.close(); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index b72ab097990..3d79bcc5212 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -48,11 +48,6 @@ async function routed(consumer: Consumer, path: Path.Valid): Promise Path.Pattern.subtree(prefix))); -} - /** A stand-in for a session announcing a route: serves any path from `producer`. */ function provider(producer: BroadcastProducer) { return () => producer.consume(); @@ -193,25 +188,25 @@ test("the table is reactive", async () => { origin.close(); }); -test("announced streams the table with prefix-relative paths", async () => { +test("announced streams the table under a scope with origin-relative paths", async () => { const origin = new Producer(); const consumer = origin.consume(); const a = publish(origin, Path.from("room/a")); - const announced = consumer.announced(scope(Path.from("room"))); + const announced = consumer.announced(Path.Pattern.subtree(Path.from("room"))); - // The initial state arrives first. - expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("a")), active: true }); + // The initial state arrives first, named from the origin rather than the scope. + expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("room/a")), active: true }); - // Additions under the prefix stream in; paths outside it are invisible. + // Additions under the scope stream in; paths outside it are invisible. const b = publish(origin, Path.from("room/b")); publish(origin, Path.from("lobby/c")); - expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("b")), active: true }); + expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("room/b")), active: true }); // Removals retract. b.close(); - expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("b")), active: false }); + expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("room/b")), active: false }); // The stream ends when the origin closes. origin.close(); @@ -253,13 +248,14 @@ test("announced reports a broader covering route at the root", async () => { const upstream = new BroadcastProducer(); const dispose = serve(origin, Path.from("room"), provider(upstream)); - // A route above the requested prefix covers everything under it, so it - // presents at the root, matching what request() resolves there. - const announced = consumer.announced(scope(Path.from("room/alice"))); - expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.empty()), active: true }); + // A route above the requested scope covers everything under it, so it clamps + // to the scope, matching what request() resolves there. + const scope = Path.Pattern.subtree(Path.from("room/alice")); + const announced = consumer.announced(scope); + expect(await announced.next()).toMatchObject({ pattern: scope, active: true }); dispose(); - expect(await announced.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.empty()), active: false }); + expect(await announced.next()).toMatchObject({ pattern: scope, active: false }); announced.close(); upstream.close(); @@ -1031,57 +1027,15 @@ test("literal and subtree claims keep distinct pattern identities", async () => origin.close(); }); -test("announced accepts prefix-shaped unions and reports them in the new vocabulary", async () => { - const origin = new Producer(); - const consumer = origin.consume(); - - // The root grant is `**`, the old empty prefix. - const root = consumer.announced(new Path.Patterns([Path.Pattern.all()])); - expect(root.scope.equals(new Path.Patterns([Path.Pattern.all()]))).toBe(true); - - // `foo/**` keeps the old `foo` prefix meaning. - const scoped = consumer.announced(scope(Path.from("room"))); - expect(scoped.scope.equals(scope(Path.from("room")))).toBe(true); - - // Multiple prefixes fan out: a route under each presents under its own member. - const a = publish(origin, Path.from("alpha/x")); - const b = publish(origin, Path.from("beta/y")); - publish(origin, Path.from("other/z")); - const multi = consumer.announced(scope(Path.from("alpha"), Path.from("beta"))); - expect(await multi.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("x")), active: true }); - expect(await multi.next()).toMatchObject({ pattern: Path.Pattern.subtree(Path.from("y")), active: true }); - - root.close(); - scoped.close(); - multi.close(); - a.close(); - b.close(); - origin.close(); -}); - -test("announced with an empty union grants nothing and stays silent", async () => { - const origin = new Producer(); - const consumer = origin.consume(); - - publish(origin, Path.from("room/a")); - const announced = consumer.announced(new Path.Patterns()); - const raced = await Promise.race([announced.next().then(() => "event"), settle().then(() => "silent")]); - expect(raced).toBe("silent"); - - announced.close(); - origin.close(); -}); - -test("announced refuses non-prefix grants without narrowing or widening", () => { +test("announced refuses a scope that is not prefix-shaped", () => { const origin = new Producer(); const consumer = origin.consume(); const refused = (text: string) => { - const union = new Path.Patterns([Path.Pattern.parse(text)]); - expect(() => consumer.announced(union)).toThrow(); + expect(() => consumer.announced(Path.Pattern.parse(text))).toThrow(); }; - // An exact path is not a grant over its subtree. + // An exact path is not a scope over its subtree. refused("room"); // The empty pattern names only the root, not everything beneath it. refused(""); @@ -1093,10 +1047,5 @@ test("announced refuses non-prefix grants without narrowing or widening", () => refused("**/room"); refused("room/**/chat"); - // A supported member cannot conceal an unsupported one. - const mixed = new Path.Patterns([Path.Pattern.parse("room/**"), Path.Pattern.parse("other")]); - expect(mixed.size).toBe(2); - expect(() => consumer.announced(mixed)).toThrow(); - origin.close(); }); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 3b7cd527d1b..018101542fe 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -15,7 +15,7 @@ import * as announce from "./announced.ts"; import * as broadcast from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; import { Route, routesEqual } from "./hop.ts"; -import { hooks } from "./internal.ts"; +import { hooks, scopePrefix } from "./internal.ts"; import * as Path from "./path.ts"; export type { Cost, Hop, Route } from "./hop.ts"; @@ -327,7 +327,7 @@ export interface Table { request(path: Path.Valid): Request; /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ - announced(scope?: Path.Patterns): announce.Consumer; + announced(scope?: Path.Pattern): announce.Consumer; } /** @@ -623,7 +623,7 @@ export class Producer implements Table { } /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ - announced(scope?: Path.Patterns): announce.Consumer { + announced(scope?: Path.Pattern): announce.Consumer { return this.#reader.announced(scope); } @@ -694,27 +694,6 @@ function prefixPattern(pattern: Path.Pattern | string): { parsed: Path.Pattern; return { parsed, prefix: Path.from(parsed.text) }; } -/** - * The literal prefixes a scope grants, validating the whole union first. - * - * `foo/**` keeps the old `foo` prefix meaning and `**` keeps the old empty-prefix - * meaning. Anything else (an exact `foo`, the empty pattern, a suffix, or any - * segment wildcard) throws rather than narrowing or widening the grant, so a - * supported member cannot conceal an unsupported one. An empty union grants - * nothing and yields no prefixes. - */ -function scopePrefixes(scope: Path.Patterns): Path.Valid[] { - const prefixes: Path.Valid[] = []; - for (const pattern of scope) { - const prefix = pattern.asPrefix(); - if (prefix === undefined) { - throw new Error(`announced() only supports prefix-shaped patterns (foo/**), got "${pattern.text}"`); - } - prefixes.push(Path.from(prefix)); - } - return prefixes; -} - /** * An open request for a path nothing announced; see {@link Consumer.request}. * @@ -947,25 +926,24 @@ export class Consumer { /** * The announced routes under `scope`, as a live stream: every currently advertised - * route arriving first as `active`, then additions and retractions as they happen. - * Each member must be prefix-shaped (`foo/**` for the old `foo` prefix, `**` for - * everything); anything else throws rather than narrowing or widening the grant. - * An empty union grants nothing and stays silent. A local broadcast appears only - * after {@link broadcast.Producer.announce}; a dynamic or received route announces - * the prefix it covers. Paths are relative to each scope member's prefix. - * The stream ends when the origin closes or the consumer is closed. + * route arrives first as `active`, then additions and retractions as they happen. + * The scope must be prefix-shaped (`foo/**`, or `**` for everything); anything else + * throws rather than narrowing or widening it. A local broadcast appears only after + * {@link broadcast.Producer.announce}; a dynamic or received route announces the + * prefix it covers, clamped to the scope. Patterns are relative to the origin, not + * the scope. The stream ends when the origin closes or the consumer is closed. */ - announced(scope: Path.Patterns = new Path.Patterns([Path.Pattern.all()])): announce.Consumer { - const prefixes = scopePrefixes(scope); - const producer = new announce.Producer(scope); - void this.#runAnnounced(producer, prefixes); + announced(scope: Path.Pattern = Path.Pattern.all()): announce.Consumer { + const prefix = scopePrefix(scope); + const producer = new announce.Producer(); + void this.#runAnnounced(producer, prefix); return producer.consume(); } - async #runAnnounced(producer: announce.Producer, prefixes: Path.Valid[]): Promise { - // Keyed by suffix, valued by identity plus route. Diffing identity rather than - // mere presence means a republish emits a retraction then a fresh announcement; - // a re-price of the same identity emits another active (a restart). + async #runAnnounced(producer: announce.Producer, prefix: Path.Valid): Promise { + // Keyed by the presented pattern, valued by identity plus route. Diffing identity + // rather than mere presence means a republish emits a retraction then a fresh + // announcement; a re-price of the same identity emits another active (a restart). let active = new Map(); try { @@ -978,31 +956,29 @@ export class Consumer { const next = new Map(); // Routes first, so an advertised local at the same path overwrites it: the // announcement points at whatever request() would resolve. - // Each scope member keeps its own root slot: the most specific route - // covering that member's prefix wins it, matching request() resolution. - for (const prefix of prefixes) { - let rootLen = -1; - for (const [key, entries] of routes ?? []) { - const entry = entries[0]; - if (!entry) continue; - const snap: Advertised = { identity: entry.identity, route: entry.route.peek() }; - const advertised = Path.Pattern.parse(key); - for (const residual of advertised.rebase(prefix)) { - const presentedPath = residual.text; - if (residual.asPrefix() === "") { - const spec = advertised.segments.length; - if (spec < rootLen) continue; - rootLen = spec; - } - next.set(presentedPath, snap); + // The most specific route covering the scope itself wins the root slot, + // matching request() resolution. + let rootLen = -1; + for (const [key, entries] of routes ?? []) { + const entry = entries[0]; + if (!entry) continue; + const snap: Advertised = { identity: entry.identity, route: entry.route.peek() }; + const advertised = Path.Pattern.parse(key); + // Rebasing clamps the claim to the scope; rooting names the result from the origin. + for (const residual of advertised.rebase(prefix)) { + if (residual.asPrefix() === "") { + const spec = advertised.segments.length; + if (spec < rootLen) continue; + rootLen = spec; } + next.set(residual.rooted(prefix).text, snap); } - for (const [path, front] of local ?? []) { - const route = advertisedLocal?.get(path); - if (!route) continue; - const suffix = Path.stripPrefix(prefix, path); - if (suffix !== null) next.set(Path.Pattern.subtree(suffix).text, { identity: front, route }); - } + } + for (const [path, front] of local ?? []) { + const route = advertisedLocal?.get(path); + if (!route) continue; + if (Path.hasPrefix(prefix, path)) + next.set(Path.Pattern.subtree(path).text, { identity: front, route }); } for (const [path, snap] of active) { diff --git a/js/room/src/room.test.ts b/js/room/src/room.test.ts index 35ee3e357b8..1fbc322cfdd 100644 --- a/js/room/src/room.test.ts +++ b/js/room/src/room.test.ts @@ -15,11 +15,12 @@ test("room restores the announce prefix and reconciles local identity changes", const streams: Net.Announce.Producer[] = []; const connection = { origin: new Signal({ - announced(scope?: Net.Path.Patterns) { - const stream = new Net.Announce.Producer(scope); + announced(scope: Net.Path.Pattern) { + expect(scope.equals(Net.Path.Pattern.subtree(Net.Path.from("room-a")))).toBe(true); + const stream = new Net.Announce.Producer(); streams.push(stream); stream.append({ - pattern: Net.Path.Pattern.subtree(Net.Path.from("bob/camera.hang")), + pattern: Net.Path.Pattern.subtree(Net.Path.from("room-a/bob/camera.hang")), active: true, }); return stream.consume(); diff --git a/js/room/src/room.ts b/js/room/src/room.ts index 8413badda14..6b20cbf7e36 100644 --- a/js/room/src/room.ts +++ b/js/room/src/room.ts @@ -62,8 +62,7 @@ export class Room { const origin = effect.get(this.connection.origin); if (!origin) return; const prefix = effect.get(this.prefix) ?? Moq.Path.empty(); - // The origin speaks scopes; the intended prefix converts explicitly to its subtree. - const announced = origin.announced(new Moq.Path.Patterns([Moq.Path.Pattern.subtree(prefix)])); + const announced = origin.announced(Moq.Path.Pattern.subtree(prefix)); effect.cleanup(() => announced.close()); effect.spawn(this.#run.bind(this, announced, prefix, effect)); @@ -86,7 +85,9 @@ export class Room { const covered = update.pattern.isLiteral ? update.pattern.text : update.pattern.asPrefix(); if (covered === undefined) continue; - const suffix = Moq.Path.from(covered); + // Announcements name the whole path; participants are named beneath the prefix. + const suffix = Moq.Path.stripPrefix(prefix, Moq.Path.from(covered)); + if (suffix === null) continue; const parsed = parse(suffix); if (!parsed) continue; @@ -94,7 +95,7 @@ export class Room { if (local && parsed.identity === local) continue; if (update.active) { - this.#add(parsed.identity, parsed.kind, Moq.Path.join(prefix, suffix)); + this.#add(parsed.identity, parsed.kind, Moq.Path.from(covered)); } else { this.#remove(parsed.identity, parsed.kind); } From 659bacae420742a85cbb5834cf440db1c7c2d88e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 17:51:48 -0700 Subject: [PATCH 4/8] quest(m1): move origin scopes to m1 with the announce match shape The announce event shape is a published API in every language, so the quest lands on dev before the release: events carry the covered pattern relative to the origin plus one capture per wildcard in the scope, assembled locally while the wire keeps echoing only the suffix beneath the literal head. Co-Authored-By: Claude Opus 5 --- quest/m1/README.md | 1 + .../origin.md => m1/api-origin-scopes.md} | 24 ++++++++++++++----- quest/m2/origin-cpu/origin-tree.md | 2 +- quest/m2/path-patterns/README.md | 2 -- quest/m2/path-patterns/interest.md | 2 +- 5 files changed, 21 insertions(+), 10 deletions(-) rename quest/{m2/path-patterns/origin.md => m1/api-origin-scopes.md} (65%) diff --git a/quest/m1/README.md b/quest/m1/README.md index f39d835518e..9e2862a7798 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -25,6 +25,7 @@ does not require it. ## Quests - [Reserved codes](/quest/m1/lite-reserved-codes.md) - the four stream codes sent from the reserved range are registered in the draft's own range and round-trip in both languages +- [Origin scopes](/quest/m1/api-origin-scopes.md) - literal origin roots carry arbitrary pattern unions, and announce events report the match with its captures - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy - [Publisher finish borrows](/quest/m1/api-finish-borrow.md) - finish borrows the handle so abort can still run after a clean end - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the send and receive estimates carry `estimated_*_rate` on the C ABI, every binding, and moqsink diff --git a/quest/m2/path-patterns/origin.md b/quest/m1/api-origin-scopes.md similarity index 65% rename from quest/m2/path-patterns/origin.md rename to quest/m1/api-origin-scopes.md index 6310dc41694..898a922e0df 100644 --- a/quest/m2/path-patterns/origin.md +++ b/quest/m1/api-origin-scopes.md @@ -4,14 +4,26 @@ `moq-net` origin handles retain literal roots while an arbitrary union of path patterns authorizes and filters every publish, subscribe, and announcement -beneath them. +beneath them, and an announcement reports how it matched the scope. The +announce event shape is a published API in every language, so it settles on +dev before the release. ## Plan -- Extend the pattern-valued scope API from m1 to every supported pattern union, +- Extend the pattern-valued scope API to every supported pattern union, removing its explicit refusal of non-prefix grants without changing its public - signatures. A root remains a literal coordinate transform; never join or - mount at a wildcard. + signatures: Rust `scope(&Patterns)`, JS `announced(scope: Path.Pattern)`. A + root remains a literal coordinate transform; never join or mount at a + wildcard. +- Announce events carry a match, not a bare pattern: the covered pattern + relative to the origin, plus one capture per wildcard in the scope, the way a + regex match exposes the whole match and then its groups. `foo/*/chat` + matched by `foo/alice/chat` captures `alice`; `foo/**` matched by + `foo/alice/chat` captures `alice/chat`. Decide how a claim that is itself a + pattern reports a capture the scope cannot pin (a `**` route under a `*` + scope). The wire keeps echoing only the suffix beneath the literal head; the + match is assembled locally. Mirror the shape in Rust, JS, and every binding + that exposes announcements (`moq_announced`, the wrappers). - Watch origin-tree nodes at each pattern's literal head, then reapply the full matcher on broadcast creation, lookup, and announce fan-out. Patterns sharing a head share the node without sharing permission. @@ -45,6 +57,6 @@ the existing subscription closes and no further objects arrive. - [#2714](https://github.com/moq-dev/moq/issues/2714) - close this issue when the quest finishes -## Required +## Related -- [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts +- [Pattern interest](/quest/m2/path-patterns/interest.md) - carries the same scopes on the lite-06 wire once they are enforced here diff --git a/quest/m2/origin-cpu/origin-tree.md b/quest/m2/origin-cpu/origin-tree.md index d450cf21c60..7ee5f8152f0 100644 --- a/quest/m2/origin-cpu/origin-tree.md +++ b/quest/m2/origin-cpu/origin-tree.md @@ -33,4 +33,4 @@ their literal-head notification and filtering requirements. - [Route-selection CPU](/quest/m2/origin-cpu/origin-index.md) - per-broadcast alternatives - [Relay memory](/quest/m2/relay-memory.md) - memory measurements -- [Origin scopes](/quest/m2/path-patterns/origin.md) - future pattern-scoped views +- [Origin scopes](/quest/m1/api-origin-scopes.md) - pattern-scoped views diff --git a/quest/m2/path-patterns/README.md b/quest/m2/path-patterns/README.md index e8573c3d40f..e44ccaf376d 100644 --- a/quest/m2/path-patterns/README.md +++ b/quest/m2/path-patterns/README.md @@ -76,8 +76,6 @@ CAT cannot represent `pid/*/chat`. ## Quests -- [Origin scopes](/quest/m2/path-patterns/origin.md) - literal origin roots - carry arbitrary pattern unions without widening authorization - [Pattern interest](/quest/m2/path-patterns/interest.md) - moq-lite-06 carries pattern grants in AUTH and full-pattern interest in ANNOUNCE_REQUEST diff --git a/quest/m2/path-patterns/interest.md b/quest/m2/path-patterns/interest.md index e06c41d0890..c8f65087363 100644 --- a/quest/m2/path-patterns/interest.md +++ b/quest/m2/path-patterns/interest.md @@ -32,4 +32,4 @@ IETF over-request plus local-filter fallback. - [Lite auth](/quest/m2/auth/lite.md) - establish the AUTH exchange before upgrading its grants to patterns -- [Origin scopes](/quest/m2/path-patterns/origin.md) +- [Origin scopes](/quest/m1/api-origin-scopes.md) - the scopes this wire carries are enforced there first From 1fc21deb955f06b686c7c4a000ba9b564f129b0f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 19:27:21 -0700 Subject: [PATCH 5/8] fix(relay): carry pattern grants through the moq-auth token, repoint quest links Rebase onto dev after moq-auth landed: the verified token keeps the Patterns moq-auth already hands it, refusing non-prefix members with UnsupportedPattern instead of converting to PathPrefixes. Quest links follow the moved origin scopes quest. Co-Authored-By: Claude Opus 5 --- quest/m2/auth/README.md | 4 ++-- quest/m2/auth/relay-refresh.md | 4 ++-- quest/m2/processor/advertise-auth.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/quest/m2/auth/README.md b/quest/m2/auth/README.md index a400e7ad152..32c806cfc5c 100644 --- a/quest/m2/auth/README.md +++ b/quest/m2/auth/README.md @@ -37,7 +37,7 @@ Decisions settled while planning, recorded so review does not relitigate them: the union and cancels publications and subscriptions that lose authorization. Other authorized work continues on the same session. An empty union leaves the session connected with no access, so it can accept a fresh token. - [Origin scopes](/quest/m2/path-patterns/origin.md) owns the common resize + [Origin scopes](/quest/m1/api-origin-scopes.md) owns the common resize operation; relay token handling requires it rather than shipping a temporary close-on-shrink policy. - **A public grant contains publish patterns, subscribe patterns, and an @@ -103,7 +103,7 @@ ALPN. ## Related -- [Origin scopes](/quest/m2/path-patterns/origin.md) - resizes a live session +- [Origin scopes](/quest/m1/api-origin-scopes.md) - resizes a live session when the union shrinks, for revalidation and token expiry alike - [Pattern interest](/quest/m2/path-patterns/interest.md) - moves AUTH's legacy wire prefixes to patterns along with ANNOUNCE_REQUEST - [Expiring media grants](/quest/m2/processor/grant-lease.md) - a worker's diff --git a/quest/m2/auth/relay-refresh.md b/quest/m2/auth/relay-refresh.md index 0cc5b1cb7e4..57ad827792b 100644 --- a/quest/m2/auth/relay-refresh.md +++ b/quest/m2/auth/relay-refresh.md @@ -35,7 +35,7 @@ expiry, an expiry that leaves the union intact ends only that token, and token happened to carry subscribe prefixes, and swapped in whenever the set grows, the first live re-scope the relay performs; keep it behind one function that - [Origin scopes](/quest/m2/path-patterns/origin.md) later extends to a + [Origin scopes](/quest/m1/api-origin-scopes.md) later extends to a shrinking union. - Expiry: the deadline today is the admitted lease's `closed()` inside one `tokio::select!` arm. Select on one lease per token in the set instead, and on any firing recompute the union without it: unchanged @@ -88,5 +88,5 @@ Additive. ## Related -- [Origin scopes](/quest/m2/path-patterns/origin.md) - extends the re-scope +- [Origin scopes](/quest/m1/api-origin-scopes.md) - extends the re-scope to a shrinking union diff --git a/quest/m2/processor/advertise-auth.md b/quest/m2/processor/advertise-auth.md index 19e1d469a2b..5748c7e277e 100644 --- a/quest/m2/processor/advertise-auth.md +++ b/quest/m2/processor/advertise-auth.md @@ -29,5 +29,5 @@ publish grant. ## Required - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Origin scopes](/quest/m2/path-patterns/origin.md) - supplies the +- [Origin scopes](/quest/m1/api-origin-scopes.md) - supplies the pattern-scoped origin handles the advertise scope extends From 303307e57e4cd5e67dd7fbb357633cee2ea84cf7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 14 Sep 2026 19:37:29 -0700 Subject: [PATCH 6/8] fix(js): refuse unsupported announce scopes before the pump, migrate the smoke subscriber Connection.announced and Reload.announced validated the scope only inside the effect that reaches an origin, so an unsupported pattern while disconnected was logged and left the consumer waiting forever. The js-native smoke subscriber still passed a Path to the pattern-only method. Co-Authored-By: Claude Opus 5 --- js/net/src/connection/pool.test.ts | 11 +++++++++++ js/net/src/connection/pool.ts | 6 ++++++ js/net/src/connection/reload.test.ts | 11 +++++++++++ js/net/src/connection/reload.ts | 6 ++++++ test/smoke/clients/js-native/subscribe.ts | 8 ++++---- 5 files changed, 38 insertions(+), 4 deletions(-) diff --git a/js/net/src/connection/pool.test.ts b/js/net/src/connection/pool.test.ts index 53adea1ad56..f5dba9e5dd7 100644 --- a/js/net/src/connection/pool.test.ts +++ b/js/net/src/connection/pool.test.ts @@ -378,3 +378,14 @@ test("auth eviction lets a later handle dial fresh and the old lease still clean second.close(); }); + +test("announced refuses a non-prefix scope before any connection exists", () => { + const handle = new Connection({ url }); + try { + // The pump that would reach the origin runs inside an effect, which only logs a + // throw; the refusal has to happen where the caller can see it. + expect(() => handle.announced(Path.Pattern.parse("room/*"))).toThrow(/prefix-shaped/); + } finally { + handle.close(); + } +}); diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 91018aca008..91b57b0d437 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -6,6 +6,7 @@ import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import * as Announce from "../announced.ts"; import type { Handle } from "../bandwidth.ts"; +import { scopePrefix } from "../internal.ts"; import * as Origin from "../origin.ts"; import * as Path from "../path.ts"; import * as Time from "../time.ts"; @@ -267,6 +268,11 @@ export class Connection { * the old relay's origin, then the new one's arrivals stream in. */ announced(scope: Path.Pattern = Path.Pattern.all()): Announce.Consumer { + // Refuse an unsupported scope here, where the caller can see it; the pump below + // runs later inside an effect, which would only log the throw and leave the + // consumer waiting forever. + scopePrefix(scope); + const producer = new Announce.Producer(); const consumer = producer.consume(); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index ac97a93512d..710c84bb299 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -572,3 +572,14 @@ test("closing an announce consumer during upstream teardown does not append retr errors.mockRestore(); } }); + +test("announced refuses a non-prefix scope before any session exists", () => { + const reload = new Reload({ enabled: false }); + try { + // The pump that would reach the session runs inside an effect, which only logs a + // throw; the refusal has to happen where the caller can see it. + expect(() => reload.announced(Path.Pattern.parse("room/*"))).toThrow(/prefix-shaped/); + } finally { + reload.close(); + } +}); diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index 4d1ab1184b7..327c6406777 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -2,6 +2,7 @@ import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals import * as Announce from "../announced.ts"; import { Allocator } from "../bandwidth.ts"; import { error, SessionCode, SessionError } from "../error.ts"; +import { scopePrefix } from "../internal.ts"; import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import * as Time from "../time.ts"; @@ -452,6 +453,11 @@ export class Reload { // a dead session's entries), so its stream is the same thing with less machinery. if (this.consume) return this.consume.announced(scope); + // Refuse an unsupported scope here, where the caller can see it; the pump below + // runs later inside an effect, which would only log the throw and leave the + // consumer waiting forever. + scopePrefix(scope); + const producer = new Announce.Producer(); const consumer = producer.consume(); diff --git a/test/smoke/clients/js-native/subscribe.ts b/test/smoke/clients/js-native/subscribe.ts index 17b273dae0e..9df20cb1da3 100644 --- a/test/smoke/clients/js-native/subscribe.ts +++ b/test/smoke/clients/js-native/subscribe.ts @@ -51,10 +51,10 @@ async function run(): Promise { // wait into consume(); the JS API leaves it to the caller. The outer timeout // below bounds how long we wait. // - // `announced(path)` is scoped to `path`, so each entry's `path` is relative to it - // (empty for the broadcast at `path` itself). Any active entry means a matching - // broadcast is up, so wait for one. - const announced = connection.announced(path); + // The scope is the subtree at `path`, so each entry's pattern is relative to the + // connection (`path` itself for the broadcast there). Any active entry means a + // matching broadcast is up, so wait for one. + const announced = connection.announced(Moq.Path.Pattern.subtree(path)); try { for (;;) { const entry = await announced.next(); From 9c6b0d0971a63a0ee468c81430a9e9e657cbeead Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 04:54:38 -0700 Subject: [PATCH 7/8] docs(quest): repoint CAT origin-scope links after the m1 move The origin-scopes quest now lives on m1; CAT verify still named the old path. Co-Authored-By: grok-4.6 --- quest/m3/cat/verify.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m3/cat/verify.md b/quest/m3/cat/verify.md index 980f6d28ede..a28847cefe9 100644 --- a/quest/m3/cat/verify.md +++ b/quest/m3/cat/verify.md @@ -52,7 +52,7 @@ rather than a set of prefixed names; `@moq/auth` stays flat. bare `**` with nothing appended. A field value containing `/` or `*` cannot be a segment and refuses the token naming the scope. `f*` and `*f` are patterns the relay only admits once [Origin - scopes](/quest/m2/path-patterns/origin.md) lifts its prefix-shaped + scopes](/quest/m1/api-origin-scopes.md) lifts its prefix-shaped adapter, which is why that quest is required here. A scope with a track match is refused naming the scope. `exp` is `expires`, `moqt-reval` is `revalidate`, and `Grant::validate` keeps refusing a cadence without an @@ -85,7 +85,7 @@ gain flags. Wire: none. ## Required -- [Origin scopes](/quest/m2/path-patterns/origin.md) - the relay admits +- [Origin scopes](/quest/m1/api-origin-scopes.md) - the relay admits `f*` and `*f` grants only after it - [Setup token](/quest/m3/cat/setup-token.md) - the token reaches the server's request From 66d03a06690e9d20b353b1e7a5000454bc2de007 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 05:38:08 -0700 Subject: [PATCH 8/8] fix(net): keep max-depth paths routable after subtree scopes A 32-part path cannot be spelled as path/**, so routed and routed_broadcast must not require that conversion. Discovery events stay origin-relative in the concept guide, and the watch demo shows announced(Path.Pattern.subtree). Co-Authored-By: grok-4.6 --- demo/web/src/watch.html | 2 +- doc/concept/moq-lite.md | 14 +++++------ rs/moq-net/src/model/origin.rs | 45 ++++++++++++++++++++++++++-------- 3 files changed, 43 insertions(+), 18 deletions(-) diff --git a/demo/web/src/watch.html b/demo/web/src/watch.html index 94a969687ac..3b3913760a6 100644 --- a/demo/web/src/watch.html +++ b/demo/web/src/watch.html @@ -118,7 +118,7 @@

How it works:

<moq-watch> Web Component. A single connection discovers broadcasts via MoQ announcements - (connection.announced(prefix)) and we reconcile one + (connection.announced(Path.Pattern.subtree(prefix))) and we reconcile one tile per live .hang or .msf broadcast, adding and removing them as publishers come and go. No F5 needed; restart a publisher and its tile reconnects on its own.

diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index b9a16fee63f..905e2c03ab5 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -78,13 +78,13 @@ subscriber must not treat the pattern as a concrete broadcast name. Use `create_broadcast(path)` and `announce(route)` when the path is known; use `dynamic` when the set of paths is not. -A subscriber watching under a prefix sees the advertisement rebased to that -scope. `**/a` advertised cluster-wide and consumed at `a` arrives as both the -empty pattern (exactly `a`) and `**/a` (deeper paths ending in `a`). A pattern -that cannot match under the prefix is not sent. Announce events carry the -matcher: Rust `announce::Update.pattern` and TypeScript `Announce.Update.pattern` -are a `Pattern`. Use `as_prefix()` / `asPrefix()` when a consumer specifically -needs a prefix-shaped claim. +A subscriber watching under a prefix sees advertisements named from the origin, +clamped to the requested scope. A route claimed above the scope is presented as +the scope itself: `room` advertised cluster-wide and consumed at `room/alice` +arrives as `room/alice/**`. A pattern that cannot match under the prefix is not +sent. Announce events carry the matcher: Rust `announce::Update.pattern` and +TypeScript `Announce.Update.pattern` are a `Pattern`. Use `as_prefix()` / +`asPrefix()` when a consumer specifically needs a prefix-shaped claim. When a subscriber asks for a matching path the advertiser will not serve, the advertiser refuses that request rather than stretching the claim. The same diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index d478f644501..e89825362d2 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -16,7 +16,7 @@ use web_transport_trait::{MaybeSend, MaybeSync}; use super::{Requests, WeakCache, WeakEntry}; use crate::{ - AsPath, Error, Path, PathOwned, PathPrefixes, Pattern, Patterns, + AsPath, Error, InvalidPattern, Path, PathOwned, PathPrefixes, Pattern, Patterns, coding::{BoundsExceeded, Decode, DecodeError, Encode, EncodeError}, runtime::{AnyTimers, Instant, Timers, TimersSlot}, util::{TaskSet, Tasks, TasksWeak}, @@ -3597,8 +3597,13 @@ impl Consumer { // Scope a fresh consumer down to this path's subtree: any covering route then // clamps to exactly the path, so we only wake for relevant announcements. - let subtree = Pattern::subtree(path.as_str()).ok()?; - let consumer = self.scope(&Patterns::from(subtree))?; + // A max-depth path cannot be spelled as `path/**` (`**` would be a 33rd + // segment), so watch the existing stream and match covering claims instead. + let consumer = match Pattern::subtree(path.as_str()) { + Ok(subtree) => self.scope(&Patterns::from(subtree))?, + Err(InvalidPattern::TooManySegments) => self.clone(), + Err(_) => return None, + }; // `scope` keeps narrower permissions intact: if we ask for `foo` on a // consumer limited to `foo/specific`, no route can ever clamp to exactly @@ -3612,7 +3617,10 @@ impl Consumer { let mut announced = consumer.untagged().announced(); loop { let update = announced.next().await?; - if update.active && update.pattern.as_prefix() == Some(path.as_str()) { + if !update.active { + continue; + } + if update.pattern.as_prefix() == Some(path.as_str()) || update.pattern.matches(path.as_str()) { return Some(update.route); } } @@ -3632,13 +3640,9 @@ impl Consumer { pub async fn routed_broadcast(&self, path: impl AsPath) -> Result { let path = path.as_path(); - // `scope` keeps narrower permissions intact: if the whole path is not + // `allowed` keeps narrower permissions intact: if the whole path is not // reachable, no route can ever cover it, so bail rather than loop forever. - let subtree = Pattern::subtree(path.as_str()) - .map(Patterns::from) - .map_err(|_| Error::Unauthorized)?; - let scoped = self.scope(&subtree).ok_or(Error::Unauthorized)?; - if !scoped.allowed().matches(path.as_str()) { + if !self.allowed().matches(path.as_str()) { return Err(Error::Unauthorized); } loop { @@ -4996,6 +5000,27 @@ mod tests { fut.now_or_never().expect("covered").expect("routed"); } + #[tokio::test] + async fn routed_accepts_a_max_depth_path() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let path = (0..Path::MAX_PARTS) + .map(|i| format!("s{i}")) + .collect::>() + .join("/"); + assert_eq!(Path::new(&path).parts().count(), Path::MAX_PARTS); + assert_eq!(Pattern::subtree(&path), Err(InvalidPattern::TooManySegments)); + + assert!(consumer.allowed().matches(&path)); + + let mut fut = consumer.routed(&path).boxed(); + assert!((&mut fut).now_or_never().is_none()); + + // A covering root still resolves: the lookup must not require `path/**`. + let _a = producer.announce("", Route::default()).unwrap(); + fut.now_or_never().expect("covered").expect("routed"); + } + #[tokio::test] async fn teardown_ends_everything() { let (producer, driver) = Producer::new(Config::new(origin(1)));