Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions demo/web/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -182,17 +182,17 @@ 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<string>();
effect.spawn(async () => {
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;
Expand Down
8 changes: 5 additions & 3 deletions demo/web/src/stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ discovery.run((effect) => {
if (!origin) return;

const prefix = Net.Path.from(STATS_PREFIX);
const announced = origin.announced(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
Expand All @@ -131,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;
Expand Down
2 changes: 1 addition & 1 deletion demo/web/src/watch.html
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ <h3>How it works:</h3>
<code class="language-html">&lt;moq-watch&gt;</code> <a
href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components">Web Component</a>.
A single connection discovers broadcasts via MoQ announcements
(<code class="language-typescript">connection.announced(prefix)</code>) and we reconcile one
(<code class="language-typescript">connection.announced(Path.Pattern.subtree(prefix))</code>) and we reconcile one
tile per live <code>.hang</code> or <code>.msf</code> broadcast, adding and removing them as publishers come and go.
No F5 needed; restart a publisher and its tile reconnects on its own.
</p>
Expand Down
14 changes: 7 additions & 7 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions js/moq-boy/src/element.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +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.
const announced = this.origin.consume().announced(prefix);
const announced = this.origin.consume().announced(Moq.Path.Pattern.subtree(prefix));
effect.cleanup(() => announced.close());

effect.spawn(async () => {
Expand All @@ -139,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;
Expand Down
47 changes: 21 additions & 26 deletions js/net/src/announced.ts
Original file line number Diff line number Diff line change
@@ -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
*/
Expand All @@ -21,7 +21,10 @@ 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 origin (for a session, its URL path). A
* route claimed above the scope passed to `announced()` is clamped to that scope.
Comment thread
kixelated marked this conversation as resolved.
Resolved
*/
pattern: Path.Pattern;
/** True while the route is advertised, false when it was retracted. */
active: boolean;
Expand Down Expand Up @@ -50,15 +53,8 @@ function closeState(state: AnnounceState, abort?: Error) {
* @public
*/
export class Producer {
/** Path prefix this stream is scoped to. */
prefix: Path.Valid;

#state = new AnnounceState();

constructor(prefix = Path.empty()) {
this.prefix = prefix;
}

/**
* 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.
Expand All @@ -69,7 +65,7 @@ export class Producer {

/** A read handle for this announcement stream. */
consume(): Consumer {
return makeConsumer(this.prefix, this.#state);
return makeConsumer(this.#state);
}

/** Writes an announcement to the queue. */
Expand All @@ -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: (prefix: Path.Valid, 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 {
/** Path prefix this stream is scoped to. */
prefix: Path.Valid;

#state: AnnounceState;

private constructor(prefix: Path.Valid, state: AnnounceState) {
this.prefix = prefix;
private constructor(state: AnnounceState) {
this.#state = state;
}

Expand All @@ -115,7 +107,7 @@ export class Consumer {
}

static {
makeConsumer = (prefix, state) => new Consumer(prefix, state);
makeConsumer = (state) => new Consumer(state);
}

/** Returns the next announcement. */
Expand Down Expand Up @@ -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;
Expand All @@ -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.
Expand Down Expand Up @@ -342,7 +335,9 @@ 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 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
Expand All @@ -367,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);
}

Expand Down
7 changes: 5 additions & 2 deletions js/net/src/connection/established.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Comment thread
kixelated marked this conversation as resolved.
Resolved
Comment thread
kixelated marked this conversation as resolved.
Resolved

/**
* Consume the broadcast at the given path, immediately.
Expand Down
11 changes: 11 additions & 0 deletions js/net/src/connection/pool.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
});
18 changes: 12 additions & 6 deletions js/net/src/connection/pool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -262,12 +263,17 @@ 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 {
const producer = new Announce.Producer(prefix);
announced(scope: Path.Pattern = Path.Pattern.all()): Announce.Consumer {
Comment thread
kixelated marked this conversation as resolved.
Resolved
// 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();

// Closing the consumer closes the shared state, so stop appending after that.
Expand All @@ -284,7 +290,7 @@ export class Connection {
const origin = effect.get(this.#origin);
if (!origin) return;

const upstream = origin.announced(prefix);
const upstream = origin.announced(scope);
Comment thread
kixelated marked this conversation as resolved.
Resolved
effect.cleanup(() => upstream.close());

// Track what this origin announced so a URL switch retracts it.
Expand Down
11 changes: 11 additions & 0 deletions js/net/src/connection/reload.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
});
22 changes: 14 additions & 8 deletions js/net/src/connection/reload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ 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 { 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";
Expand Down Expand Up @@ -439,20 +439,26 @@ 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
* reconnect, so a consumer draining `next()` never clings to a dead route across a reconnect.
*
* Stays empty while the relay lacks {@link Established.discovery}.
*/
announced(prefix: Path.Valid = emptyPath()): Announce.Consumer {
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(prefix);
if (this.consume) return this.consume.announced(scope);

const producer = new Announce.Producer(prefix);
// 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();

const pump = new Effect();
Expand All @@ -464,7 +470,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.
Expand All @@ -485,8 +491,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 });
}
}
}
Expand Down
Loading
Loading