@norskvideo/moq-net 0.1.8 → 0.2.0

package/README.md

@@ -8,11 +8,11 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org/)
 
 A TypeScript [Media over QUIC](https://moq.dev/) (MoQ) client for both browsers and server JS/TS environments.
-`@moq/net` is the **networking layer**: real-time pub/sub with built-in caching, fan-out, and prioritization, on top of QUIC. At session setup it negotiates one of two wire protocols, either the simplified [moq-lite](https://doc.moq.dev/concept/layer/moq-lite) protocol or the full IETF [moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) draft.
+`@moq/net` is the **networking layer**: real-time pub/sub with built-in caching, fan-out, and prioritization, on top of QUIC. At session setup it negotiates one of two wire protocols, either the simplified [moq-lite](https://doc.moq.dev/concept/moq-lite) protocol or the full IETF [moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) draft.
 
 Check out [hang](../hang) for a higher-level media library that uses this package.
 
-> **Note:** moq-lite is a subset of moq-transport and is forwards compatible with it, so this client works with any moq-transport CDN (ex. [Cloudflare](https://moq.dev/blog/first-cdn/)). See the [compatibility docs](https://doc.moq.dev/concept/layer/moq-lite#compatibility) for details.
+> **Note:** moq-lite is a subset of moq-transport and is forwards compatible with it, so this client works with any moq-transport CDN (ex. [Cloudflare](https://moq.dev/blog/first-cdn/)). See the [compatibility docs](https://doc.moq.dev/concept/moq-lite#compatibility) for details.
 
 ## Quick Start
 

package/announce.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Broadcast announcement streams.
+ *
+ * @module
+ */
+export { Consumer, isActive, type Kind, type Update } from "./announced";
+//# sourceMappingURL=announce.d.ts.map

package/announce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../src/announce.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC"}

package/announce.js

@@ -0,0 +1,8 @@
+/* @ts-self-types="./announce.d.ts" */
+/**
+ * Broadcast announcement streams.
+ *
+ * @module
+ */
+export { Consumer, isActive } from "./announced.js";
+//# sourceMappingURL=announce.js.map

package/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../src/announce.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAA0B,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * Broadcast announcement streams.\n *\n * @module\n */\nexport { Consumer, isActive, type Kind, type Update } from \"./announced.ts\";\n"]}

package/announced.d.ts

@@ -1,23 +1,56 @@
 /**
- * Broadcast announcement streams: which broadcast paths are available under a prefix.
+ * Broadcast announcement streams: which broadcast paths are available under a scope.
  *
  * @module
  */
-import { type GetPromise, type Getter, type GetterInit } from "@norskvideo/moq-signals";
-import type * as broadcast from "./broadcast.js";
-import type { Established } from "./connection/established.js";
-import * as Path from "./path.js";
+import { type GetPromise } from "@norskvideo/moq-signals";
+import type { Route } from "./hop.js";
+import type * as Path from "./path.js";
 /**
- * The availability of a broadcast.
+ * What an {@link Update} reports about its prefix.
  *
  * @public
  */
-export interface Event {
-    /** Broadcast path relative to the prefix passed to `announced()`. */
-    path: Path.Valid;
-    /** True when the broadcast is available, false when it was removed. */
-    active: boolean;
+export type Kind = "announced" | "updated" | "retracted";
+/**
+ * A route announcement, update, or retraction.
+ *
+ * An announcement is always a prefix, never a broadcast: a route claims that
+ * {@link prefix} and every path beneath it can be served. By convention a publisher
+ * announces each broadcast's exact path, so enumerating routes enumerates broadcasts;
+ * resolve one with the origin's `request(path)`. Narrow with a {@link Path.Pattern}
+ * locally to follow a subset.
+ *
+ * @public
+ */
+export interface Update {
+    /**
+     * The prefix the route covers, relative to the origin (for a session, its URL path).
+     */
+    prefix: Path.Valid;
+    /** What the filter's wildcards stood for, when this prefix pins all of them. */
+    captures: Path.Pattern[] | undefined;
+    /** Whether the prefix was announced, re-priced, or retracted. */
+    kind: Kind;
+    /** Hops and cost of the route; on a retraction, its last advertised values. */
+    route: Route;
+}
+/**
+ * Options for an announcement stream.
+ *
+ * @public
+ */
+export interface Options {
+    /**
+     * Also report hidden routes: those with a path segment starting with `.` below the
+     * scope's literal head. Hidden routes are left out by default, so a platform can add
+     * `.`-named broadcasts (stats, internal routes) without them turning up in apps that
+     * list everything. Subscribing to a hidden path by name works either way.
+     */
+    hidden?: boolean;
 }
+/** Whether a route covers the path after an update of this {@link Kind}. */
+export declare function isActive(kind: Kind): boolean;
 /**
  * The write side of an announcement stream.
  *
@@ -25,9 +58,6 @@ export interface Event {
  */
 export declare class Producer {
     #private;
-    /** Path prefix this stream is scoped to. */
-    prefix: Path.Valid;
-    constructor(prefix?: Path.Valid);
     /**
      * 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.
@@ -36,7 +66,7 @@ export declare class Producer {
     /** A read handle for this announcement stream. */
     consume(): Consumer;
     /** Writes an announcement to the queue. */
-    append(event: Event): void;
+    append(update: Update): void;
     /** Closes the writer. Idempotent. */
     close(abort?: Error): void;
 }
@@ -44,92 +74,20 @@ export declare class Producer {
  * 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 declare class Consumer {
     #private;
-    /** Path prefix this stream is scoped to. */
-    prefix: Path.Valid;
     private constructor();
     /** Settles once the stream closes; see {@link Producer.closed}. */
     get closed(): GetPromise<Error | null>;
+    /** The announcements as they arrive, until the stream closes. */
+    [Symbol.asyncIterator](): AsyncGenerator<Update, void, undefined>;
     /** Returns the next announcement. */
-    next(): Promise<Event | undefined>;
+    next(): Promise<Update | undefined>;
     /** Closes the reader. Idempotent. */
     close(abort?: Error): void;
 }
-/**
- * What to watch, for {@link Broadcast}.
- *
- * @public
- */
-export interface BroadcastProps {
-    /**
-     * The connection to watch on. Accepts a live {@link Established} session, or a reactive one
-     * (a `Connection.Reload`'s `established`), which is how the handle survives reconnects.
-     */
-    connection: GetterInit<Established | undefined>;
-    /** The broadcast path to watch. */
-    path: Path.Valid;
-}
-/**
- * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live
- * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody
- * publishes it.
- *
- * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.
- * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the
- * publisher stays silent forever unless it retries; this waits for the announcement instead.
- *
- * A same-name republish re-consumes, so the handle attaches to the new instance rather than
- * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the
- * subscription resumes across the new route, so `active` holds the same consumer throughout and
- * never goes offline. Only a change of publisher produces an offline/online transition.
- *
- * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast
- * drops to `undefined` while disconnected and resolves again once the new connection announces it.
- *
- * Falls back to consuming blind (and warns once) on a relay without
- * {@link Established.discovery}, where there is no announcement to wait for. `active` then
- * means *assumed present* rather than known live: nothing reports whether the path exists, so
- * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either
- * way, and because it is scoped to the path rather than to one publisher, a subscribe made
- * after a publisher finally appears succeeds.
- *
- * If discovery fails on a live session (the announcement stream is reset, or the relay
- * refuses it) the handle goes offline and stays there: nothing reopens the stream on that
- * connection. Build it from a `Connection.Reload` if you need it to recover, since a new
- * connection starts a new stream.
- *
- * Close it to release the announcement stream and the current broadcast.
- *
- * @public
- */
-export declare class Broadcast {
-    #private;
-    /** The broadcast path this handle watches. */
-    readonly path: Path.Valid;
-    /**
-     * The live broadcast, or `undefined` while it is offline.
-     *
-     * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is
-     * republished. `active` keeps pointing at whatever you closed, so once you drop the last
-     * reference the shared broadcast is gone and reads fail until the next announcement replaces
-     * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole
-     * handle to release everything.
-     */
-    readonly active: Getter<broadcast.Consumer | undefined>;
-    /**
-     * Watch a path on a connection.
-     *
-     * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the
-     * session you want to follow isn't either connection type, e.g. your own
-     * `Getter<Established | undefined>`.
-     */
-    constructor({ connection, path }: BroadcastProps);
-    /** Closes the handle and the broadcast it currently holds. Idempotent. */
-    close(): void;
-}
 //# sourceMappingURL=announced.d.ts.map

package/announced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"announced.d.ts","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAwB,MAAM,cAAc,CAAC;AAC3G,OAAO,KAAK,KAAK,SAAS,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACrB,qEAAqE;IACrE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IACjB,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;CAChB;AAiBD;;;;GAIG;AACH,qBAAa,QAAQ;;IACpB,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IAInB,YAAY,MAAM,aAAe,EAEhC;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED,kDAAkD;IAClD,OAAO,IAAI,QAAQ,CAElB;IAED,2CAA2C;IAC3C,MAAM,CAAC,KAAK,EAAE,KAAK,QAKlB;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IACpB,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IAInB,OAAO,eAGN;IAED,mEAAmE;IACnE,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAMD,qCAAqC;IAC/B,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAWvC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,UAAU,EAAE,UAAU,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEhD,mCAAmC;IACnC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAS;;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IAE1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAKxD;;;;;;OAMG;IACH,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,cAAc,EA6E/C;IAED,0EAA0E;IAC1E,KAAK,SAEJ;CACD"}
+{"version":3,"file":"announced.d.ts","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM;IACtB;;OAEG;IACH,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IACnB,gFAAgF;IAChF,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC;IACrC,iEAAiE;IACjE,IAAI,EAAE,IAAI,CAAC;IACX,+EAA+E;IAC/E,KAAK,EAAE,KAAK,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C;AAiBD;;;;GAIG;AACH,qBAAa,QAAQ;;IAGpB;;;OAGG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED,kDAAkD;IAClD,OAAO,IAAI,QAAQ,CAElB;IAED,2CAA2C;IAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,QAKpB;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IAGpB,OAAO,eAEN;IAED,mEAAmE;IACnE,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAMD,iEAAiE;IAC1D,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAMvE;IAED,qCAAqC;IAC/B,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAWxC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD"}

package/announced.js

@@ -1,11 +1,14 @@
 /* @ts-self-types="./announced.d.ts" */
 /**
- * Broadcast announcement streams: which broadcast paths are available under a prefix.
+ * Broadcast announcement streams: which broadcast paths are available under a scope.
  *
  * @module
  */
-import { Effect, getter, Once, Signal } from "@norskvideo/moq-signals";
-import * as Path from "./path.js";
+import { Once, Signal } from "@norskvideo/moq-signals";
+/** Whether a route covers the path after an update of this {@link Kind}. */
+export function isActive(kind) {
+    return kind !== "retracted";
+}
 /** Reactive backing state shared by announcement producers and consumers. */
 class AnnounceState {
     queue = new Signal([]);
@@ -26,12 +29,7 @@ function closeState(state, abort) {
  * @public
  */
 export class Producer {
-    /** Path prefix this stream is scoped to. */
-    prefix;
     #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.
@@ -41,14 +39,14 @@ export class Producer {
     }
     /** A read handle for this announcement stream. */
     consume() {
-        return makeConsumer(this.prefix, this.#state);
+        return makeConsumer(this.#state);
     }
     /** Writes an announcement to the queue. */
-    append(event) {
+    append(update) {
         if (this.#state.closed.peek() !== undefined)
             throw new Error("announcements are closed");
         this.#state.queue.mutate((queue) => {
-            queue.push(event);
+            queue.push(update);
         });
     }
     /** Closes the writer. Idempotent. */
@@ -63,16 +61,13 @@ let makeConsumer;
  * 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;
     #state;
-    constructor(prefix, state) {
-        this.prefix = prefix;
+    constructor(state) {
         this.#state = state;
     }
     /** Settles once the stream closes; see {@link Producer.closed}. */
@@ -80,7 +75,16 @@ export class Consumer {
         return this.#state.closed;
     }
     static {
-        makeConsumer = (prefix, state) => new Consumer(prefix, state);
+        makeConsumer = (state) => new Consumer(state);
+    }
+    /** The announcements as they arrive, until the stream closes. */
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const update = await this.next();
+            if (!update)
+                return;
+            yield update;
+        }
     }
     /** Returns the next announcement. */
     async next() {
@@ -101,143 +105,4 @@ export class Consumer {
         closeState(this.#state, abort);
     }
 }
-// Connections already warned about missing broadcast discovery, so the fallback logs at most
-// once per connection instead of once per watched path.
-const warnedNoDiscovery = new WeakSet();
-/**
- * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live
- * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody
- * publishes it.
- *
- * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.
- * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the
- * publisher stays silent forever unless it retries; this waits for the announcement instead.
- *
- * A same-name republish re-consumes, so the handle attaches to the new instance rather than
- * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the
- * subscription resumes across the new route, so `active` holds the same consumer throughout and
- * never goes offline. Only a change of publisher produces an offline/online transition.
- *
- * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast
- * drops to `undefined` while disconnected and resolves again once the new connection announces it.
- *
- * Falls back to consuming blind (and warns once) on a relay without
- * {@link Established.discovery}, where there is no announcement to wait for. `active` then
- * means *assumed present* rather than known live: nothing reports whether the path exists, so
- * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either
- * way, and because it is scoped to the path rather than to one publisher, a subscribe made
- * after a publisher finally appears succeeds.
- *
- * If discovery fails on a live session (the announcement stream is reset, or the relay
- * refuses it) the handle goes offline and stays there: nothing reopens the stream on that
- * connection. Build it from a `Connection.Reload` if you need it to recover, since a new
- * connection starts a new stream.
- *
- * Close it to release the announcement stream and the current broadcast.
- *
- * @public
- */
-export class Broadcast {
-    /** The broadcast path this handle watches. */
-    path;
-    /**
-     * The live broadcast, or `undefined` while it is offline.
-     *
-     * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is
-     * republished. `active` keeps pointing at whatever you closed, so once you drop the last
-     * reference the shared broadcast is gone and reads fail until the next announcement replaces
-     * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole
-     * handle to release everything.
-     */
-    active;
-    #active = new Signal(undefined);
-    #signals = new Effect();
-    /**
-     * Watch a path on a connection.
-     *
-     * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the
-     * session you want to follow isn't either connection type, e.g. your own
-     * `Getter<Established | undefined>`.
-     */
-    constructor({ connection, path }) {
-        this.path = path;
-        this.active = this.#active;
-        const source = getter(connection);
-        this.#signals.run((effect) => {
-            const conn = effect.get(source);
-            if (!conn)
-                return;
-            // Without discovery no announcement ever arrives, so waiting would hang forever.
-            if (!conn.discovery) {
-                if (!warnedNoDiscovery.has(conn)) {
-                    warnedNoDiscovery.add(conn);
-                    console.warn("relay does not support broadcast discovery; consuming without waiting.");
-                }
-                const blind = conn.consume(path);
-                effect.cleanup(() => blind.close());
-                effect.set(this.#active, blind, undefined);
-                // The announcement-gated path below goes offline when the stream ends with the
-                // session; without discovery there is no stream, so watch the session itself.
-                // A consumed broadcast is a path-scoped handle, not a subscription, so its own
-                // `closed` says nothing about whether the path exists or the session is alive.
-                // Raced against the run's teardown so a closed handle isn't retained until the
-                // session ends; the cleanup above has already cleared `active` in that case.
-                effect.spawn(async () => {
-                    await Promise.race([effect.cancel, conn.closed]);
-                    if (this.#active.peek() === blind)
-                        this.#active.set(undefined);
-                });
-                return;
-            }
-            const announced = conn.announced(path);
-            effect.cleanup(() => announced.close());
-            let current;
-            const offline = () => {
-                const mine = current;
-                current?.close();
-                current = undefined;
-                // Only clear what this run put there. A spawn task that resumes after its run was
-                // torn down would otherwise wipe the consumer a newer run already installed.
-                if (this.#active.peek() === mine)
-                    this.#active.set(undefined);
-            };
-            effect.cleanup(offline);
-            effect.spawn(async () => {
-                try {
-                    for (;;) {
-                        const event = await Promise.race([effect.cancel, announced.next()]);
-                        if (!event)
-                            break;
-                        // Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children.
-                        if (event.path !== Path.empty())
-                            continue;
-                        if (event.active) {
-                            // A live subscription survives a redundant (re-)announce; only replace a dead one.
-                            if (current && current.closed.peek() === undefined)
-                                continue;
-                            current?.close();
-                            current = conn.consume(path);
-                            this.#active.set(current);
-                        }
-                        else {
-                            offline();
-                        }
-                    }
-                }
-                catch (err) {
-                    // Discovery failed: the session died under the stream, or the relay refused
-                    // to answer. Nothing reopens it on this connection, so say so out loud.
-                    console.warn("broadcast discovery failed", err);
-                }
-                // The stream ended, or this run was torn down (its cleanup already ran). Either
-                // way there is nothing left announcing the path, so don't hold a dead broadcast.
-                offline();
-            });
-        });
-    }
-    /** Closes the handle and the broadcast it currently holds. Idempotent. */
-    close() {
-        this.#signals.close();
-    }
-}
 //# sourceMappingURL=announced.js.map

package/announced.js.map

@@ -1 +1 @@
-{"version":3,"file":"announced.js","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Broadcast announcement streams: which broadcast paths are available under a prefix.\n *\n * @module\n */\nimport { Effect, type GetPromise, type Getter, type GetterInit, getter, Once, Signal } from \"@moq/signals\";\nimport type * as broadcast from \"./broadcast.js\";\nimport type { Established } from \"./connection/established.js\";\nimport * as Path from \"./path.js\";\n\n/**\n * The availability of a broadcast.\n *\n * @public\n */\nexport interface Event {\n\t/** Broadcast path relative to the prefix passed to `announced()`. */\n\tpath: Path.Valid;\n\t/** True when the broadcast is available, false when it was removed. */\n\tactive: boolean;\n}\n\n/** Reactive backing state shared by announcement producers and consumers. */\nclass AnnounceState {\n\tqueue = new Signal<Event[]>([]);\n\tclosed = new Once<Error | null>();\n}\n\n// Once.set throws on a second settle, and both ends of a stream can close independently.\nfunction closeState(state: AnnounceState, abort?: Error) {\n\tif (state.closed.peek() !== undefined) return;\n\tstate.closed.set(abort ?? null);\n\tstate.queue.mutate((queue) => {\n\t\tqueue.length = 0;\n\t});\n}\n\n/**\n * The write side of an announcement stream.\n *\n * @public\n */\nexport class Producer {\n\t/** Path prefix this stream is scoped to. */\n\tprefix: Path.Valid;\n\n\t#state = new AnnounceState();\n\n\tconstructor(prefix = Path.empty()) {\n\t\tthis.prefix = prefix;\n\t}\n\n\t/**\n\t * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}.\n\t * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.\n\t */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\t/** A read handle for this announcement stream. */\n\tconsume(): Consumer {\n\t\treturn makeConsumer(this.prefix, this.#state);\n\t}\n\n\t/** Writes an announcement to the queue. */\n\tappend(event: Event) {\n\t\tif (this.#state.closed.peek() !== undefined) throw new Error(\"announcements are closed\");\n\t\tthis.#state.queue.mutate((queue) => {\n\t\t\tqueue.push(event);\n\t\t});\n\t}\n\n\t/** Closes the writer. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n\n// Constructs a Consumer from within this module without exposing a public constructor\n// that would leak the unexported AnnounceState. Assigned in the class's static block.\nlet makeConsumer: (prefix: Path.Valid, state: AnnounceState) => Consumer;\n\n/**\n * The read side of an announcement stream.\n *\n * Created internally: obtain one from {@link Producer.consume} or the connection's\n * `announced(prefix)`.\n *\n * @public\n */\nexport class Consumer {\n\t/** Path prefix this stream is scoped to. */\n\tprefix: Path.Valid;\n\n\t#state: AnnounceState;\n\n\tprivate constructor(prefix: Path.Valid, state: AnnounceState) {\n\t\tthis.prefix = prefix;\n\t\tthis.#state = state;\n\t}\n\n\t/** Settles once the stream closes; see {@link Producer.closed}. */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\tstatic {\n\t\tmakeConsumer = (prefix, state) => new Consumer(prefix, state);\n\t}\n\n\t/** Returns the next announcement. */\n\tasync next(): Promise<Event | undefined> {\n\t\tfor (;;) {\n\t\t\tconst announce = this.#state.queue.peek().shift();\n\t\t\tif (announce) return announce;\n\n\t\t\tconst closed = this.#state.closed.peek();\n\t\t\tif (closed instanceof Error) throw closed;\n\t\t\tif (closed !== undefined) return undefined;\n\n\t\t\tawait Signal.race(this.#state.queue, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Closes the reader. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n\n// Connections already warned about missing broadcast discovery, so the fallback logs at most\n// once per connection instead of once per watched path.\nconst warnedNoDiscovery = new WeakSet<Established>();\n\n/**\n * What to watch, for {@link Broadcast}.\n *\n * @public\n */\nexport interface BroadcastProps {\n\t/**\n\t * The connection to watch on. Accepts a live {@link Established} session, or a reactive one\n\t * (a `Connection.Reload`'s `established`), which is how the handle survives reconnects.\n\t */\n\tconnection: GetterInit<Established | undefined>;\n\n\t/** The broadcast path to watch. */\n\tpath: Path.Valid;\n}\n\n/**\n * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live\n * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody\n * publishes it.\n *\n * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.\n * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the\n * publisher stays silent forever unless it retries; this waits for the announcement instead.\n *\n * A same-name republish re-consumes, so the handle attaches to the new instance rather than\n * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the\n * subscription resumes across the new route, so `active` holds the same consumer throughout and\n * never goes offline. Only a change of publisher produces an offline/online transition.\n *\n * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast\n * drops to `undefined` while disconnected and resolves again once the new connection announces it.\n *\n * Falls back to consuming blind (and warns once) on a relay without\n * {@link Established.discovery}, where there is no announcement to wait for. `active` then\n * means *assumed present* rather than known live: nothing reports whether the path exists, so\n * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either\n * way, and because it is scoped to the path rather than to one publisher, a subscribe made\n * after a publisher finally appears succeeds.\n *\n * If discovery fails on a live session (the announcement stream is reset, or the relay\n * refuses it) the handle goes offline and stays there: nothing reopens the stream on that\n * connection. Build it from a `Connection.Reload` if you need it to recover, since a new\n * connection starts a new stream.\n *\n * Close it to release the announcement stream and the current broadcast.\n *\n * @public\n */\nexport class Broadcast {\n\t/** The broadcast path this handle watches. */\n\treadonly path: Path.Valid;\n\n\t/**\n\t * The live broadcast, or `undefined` while it is offline.\n\t *\n\t * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is\n\t * republished. `active` keeps pointing at whatever you closed, so once you drop the last\n\t * reference the shared broadcast is gone and reads fail until the next announcement replaces\n\t * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole\n\t * handle to release everything.\n\t */\n\treadonly active: Getter<broadcast.Consumer | undefined>;\n\n\t#active = new Signal<broadcast.Consumer | undefined>(undefined);\n\t#signals = new Effect();\n\n\t/**\n\t * Watch a path on a connection.\n\t *\n\t * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the\n\t * session you want to follow isn't either connection type, e.g. your own\n\t * `Getter<Established | undefined>`.\n\t */\n\tconstructor({ connection, path }: BroadcastProps) {\n\t\tthis.path = path;\n\t\tthis.active = this.#active;\n\n\t\tconst source = getter(connection);\n\t\tthis.#signals.run((effect) => {\n\t\t\tconst conn = effect.get(source);\n\t\t\tif (!conn) return;\n\n\t\t\t// Without discovery no announcement ever arrives, so waiting would hang forever.\n\t\t\tif (!conn.discovery) {\n\t\t\t\tif (!warnedNoDiscovery.has(conn)) {\n\t\t\t\t\twarnedNoDiscovery.add(conn);\n\t\t\t\t\tconsole.warn(\"relay does not support broadcast discovery; consuming without waiting.\");\n\t\t\t\t}\n\n\t\t\t\tconst blind = conn.consume(path);\n\t\t\t\teffect.cleanup(() => blind.close());\n\t\t\t\teffect.set(this.#active, blind, undefined);\n\n\t\t\t\t// The announcement-gated path below goes offline when the stream ends with the\n\t\t\t\t// session; without discovery there is no stream, so watch the session itself.\n\t\t\t\t// A consumed broadcast is a path-scoped handle, not a subscription, so its own\n\t\t\t\t// `closed` says nothing about whether the path exists or the session is alive.\n\t\t\t\t// Raced against the run's teardown so a closed handle isn't retained until the\n\t\t\t\t// session ends; the cleanup above has already cleared `active` in that case.\n\t\t\t\teffect.spawn(async () => {\n\t\t\t\t\tawait Promise.race([effect.cancel, conn.closed]);\n\t\t\t\t\tif (this.#active.peek() === blind) this.#active.set(undefined);\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst announced = conn.announced(path);\n\t\t\teffect.cleanup(() => announced.close());\n\n\t\t\tlet current: broadcast.Consumer | undefined;\n\t\t\tconst offline = () => {\n\t\t\t\tconst mine = current;\n\t\t\t\tcurrent?.close();\n\t\t\t\tcurrent = undefined;\n\t\t\t\t// Only clear what this run put there. A spawn task that resumes after its run was\n\t\t\t\t// torn down would otherwise wipe the consumer a newer run already installed.\n\t\t\t\tif (this.#active.peek() === mine) this.#active.set(undefined);\n\t\t\t};\n\t\t\teffect.cleanup(offline);\n\n\t\t\teffect.spawn(async () => {\n\t\t\t\ttry {\n\t\t\t\t\tfor (;;) {\n\t\t\t\t\t\tconst event = await Promise.race([effect.cancel, announced.next()]);\n\t\t\t\t\t\tif (!event) break;\n\n\t\t\t\t\t\t// Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children.\n\t\t\t\t\t\tif (event.path !== Path.empty()) continue;\n\n\t\t\t\t\t\tif (event.active) {\n\t\t\t\t\t\t\t// A live subscription survives a redundant (re-)announce; only replace a dead one.\n\t\t\t\t\t\t\tif (current && current.closed.peek() === undefined) continue;\n\t\t\t\t\t\t\tcurrent?.close();\n\t\t\t\t\t\t\tcurrent = conn.consume(path);\n\t\t\t\t\t\t\tthis.#active.set(current);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\toffline();\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\t// Discovery failed: the session died under the stream, or the relay refused\n\t\t\t\t\t// to answer. Nothing reopens it on this connection, so say so out loud.\n\t\t\t\t\tconsole.warn(\"broadcast discovery failed\", err);\n\t\t\t\t}\n\n\t\t\t\t// The stream ended, or this run was torn down (its cleanup already ran). Either\n\t\t\t\t// way there is nothing left announcing the path, so don't hold a dead broadcast.\n\t\t\t\toffline();\n\t\t\t});\n\t\t});\n\t}\n\n\t/** Closes the handle and the broadcast it currently holds. Idempotent. */\n\tclose() {\n\t\tthis.#signals.close();\n\t}\n}\n"]}
+{"version":3,"file":"announced.js","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Broadcast announcement streams: which broadcast paths are available under a scope.\n *\n * @module\n */\nimport { type GetPromise, Once, Signal } from \"@moq/signals\";\nimport type { Route } from \"./hop.js\";\nimport type * as Path from \"./path.js\";\n\n/**\n * What an {@link Update} reports about its prefix.\n *\n * @public\n */\nexport type Kind = \"announced\" | \"updated\" | \"retracted\";\n\n/**\n * A route announcement, update, or retraction.\n *\n * An announcement is always a prefix, never a broadcast: a route claims that\n * {@link prefix} and every path beneath it can be served. By convention a publisher\n * announces each broadcast's exact path, so enumerating routes enumerates broadcasts;\n * resolve one with the origin's `request(path)`. Narrow with a {@link Path.Pattern}\n * locally to follow a subset.\n *\n * @public\n */\nexport interface Update {\n\t/**\n\t * The prefix the route covers, relative to the origin (for a session, its URL path).\n\t */\n\tprefix: Path.Valid;\n\t/** What the filter's wildcards stood for, when this prefix pins all of them. */\n\tcaptures: Path.Pattern[] | undefined;\n\t/** Whether the prefix was announced, re-priced, or retracted. */\n\tkind: Kind;\n\t/** Hops and cost of the route; on a retraction, its last advertised values. */\n\troute: Route;\n}\n\n/**\n * Options for an announcement stream.\n *\n * @public\n */\nexport interface Options {\n\t/**\n\t * Also report hidden routes: those with a path segment starting with `.` below the\n\t * scope's literal head. Hidden routes are left out by default, so a platform can add\n\t * `.`-named broadcasts (stats, internal routes) without them turning up in apps that\n\t * list everything. Subscribing to a hidden path by name works either way.\n\t */\n\thidden?: boolean;\n}\n\n/** Whether a route covers the path after an update of this {@link Kind}. */\nexport function isActive(kind: Kind): boolean {\n\treturn kind !== \"retracted\";\n}\n\n/** Reactive backing state shared by announcement producers and consumers. */\nclass AnnounceState {\n\tqueue = new Signal<Update[]>([]);\n\tclosed = new Once<Error | null>();\n}\n\n// Once.set throws on a second settle, and both ends of a stream can close independently.\nfunction closeState(state: AnnounceState, abort?: Error) {\n\tif (state.closed.peek() !== undefined) return;\n\tstate.closed.set(abort ?? null);\n\tstate.queue.mutate((queue) => {\n\t\tqueue.length = 0;\n\t});\n}\n\n/**\n * The write side of an announcement stream.\n *\n * @public\n */\nexport class Producer {\n\t#state = new AnnounceState();\n\n\t/**\n\t * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}.\n\t * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.\n\t */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\t/** A read handle for this announcement stream. */\n\tconsume(): Consumer {\n\t\treturn makeConsumer(this.#state);\n\t}\n\n\t/** Writes an announcement to the queue. */\n\tappend(update: Update) {\n\t\tif (this.#state.closed.peek() !== undefined) throw new Error(\"announcements are closed\");\n\t\tthis.#state.queue.mutate((queue) => {\n\t\t\tqueue.push(update);\n\t\t});\n\t}\n\n\t/** Closes the writer. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n\n// Constructs a Consumer from within this module without exposing a public constructor\n// that would leak the unexported AnnounceState. Assigned in the class's static block.\nlet makeConsumer: (state: AnnounceState) => Consumer;\n\n/**\n * The read side of an announcement stream.\n *\n * Created internally: obtain one from {@link Producer.consume} or the connection's\n * `announced(scope)`.\n *\n * @public\n */\nexport class Consumer {\n\t#state: AnnounceState;\n\n\tprivate constructor(state: AnnounceState) {\n\t\tthis.#state = state;\n\t}\n\n\t/** Settles once the stream closes; see {@link Producer.closed}. */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\tstatic {\n\t\tmakeConsumer = (state) => new Consumer(state);\n\t}\n\n\t/** The announcements as they arrive, until the stream closes. */\n\tasync *[Symbol.asyncIterator](): AsyncGenerator<Update, void, undefined> {\n\t\tfor (;;) {\n\t\t\tconst update = await this.next();\n\t\t\tif (!update) return;\n\t\t\tyield update;\n\t\t}\n\t}\n\n\t/** Returns the next announcement. */\n\tasync next(): Promise<Update | undefined> {\n\t\tfor (;;) {\n\t\t\tconst announce = this.#state.queue.peek().shift();\n\t\t\tif (announce) return announce;\n\n\t\t\tconst closed = this.#state.closed.peek();\n\t\t\tif (closed instanceof Error) throw closed;\n\t\t\tif (closed !== undefined) return undefined;\n\n\t\t\tawait Signal.race(this.#state.queue, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Closes the reader. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n"]}