@norskvideo/moq-net 0.1.3 → 0.1.4

package/consume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume.d.ts","sourceRoot":"","sources":["../src/consume.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,SAAS,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;;IAI1B,yFAAyF;IACzF,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAIpD;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAUzE;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAE5B;CACD"}

package/consume.js

@@ -0,0 +1,60 @@
+/* @ts-self-types="./consume.d.ts" */
+/**
+ * Per-path dedup cache for consumed broadcasts, shared by the moq-lite and moq-ietf
+ * subscribers.
+ *
+ * `Connection.consume(path)` must not mint a fresh subscription per call: repeat requests
+ * for the same path (e.g. several renditions referencing one `broadcast: "./source"`) should
+ * share a single upstream subscription. This mirrors the Rust `origin::Consumer` weak-cache:
+ * a still-live path resolves to a shared {@link broadcast.Consumer.clone}, a closed one is
+ * re-consumed on the next request. Each handle is reference-counted, so the shared broadcast
+ * closes once every caller has closed its handle.
+ *
+ * @internal
+ */
+export class BroadcastCache {
+    // The base handle per path; callers get reference-counted clones of it.
+    #cache = new Map();
+    /** A shared handle to the live broadcast cached for `path`, or `undefined` on a miss. */
+    get(path) {
+        const base = this.#cache.get(path);
+        if (base && base.closed.peek() === undefined)
+            return base.clone();
+        return undefined;
+    }
+    /**
+     * Cache `consumer` as the base handle for `path` (evicting it once it closes) and return it.
+     * Call on a {@link get} miss, after wiring up the fresh consumer's subscribe loop.
+     */
+    insert(path, consumer) {
+        this.#cache.set(path, consumer);
+        // Drop the entry once the broadcast closes (every handle released), so the next request
+        // re-consumes rather than cloning a dead handle. Guard against a newer entry for the path.
+        void consumer.closed.then(() => {
+            if (this.#cache.get(path) === consumer)
+                this.#cache.delete(path);
+        });
+        return consumer;
+    }
+    /**
+     * Stop sharing the broadcast cached for `path`, so the next request subscribes fresh.
+     *
+     * Call when the path's advertisement goes away. A handle only leaves the cache on its own
+     * once *every* holder has closed it, so one holder outliving the publisher (a second
+     * watcher, or a caller consuming the path directly) would otherwise keep the dead
+     * generation's cached tracks alive and hand them to whoever consumes the path next.
+     * Existing handles are left alone: they belong to their holders, and the wire resets
+     * whatever they still have open.
+     *
+     * Eviction is unconditional, which costs a dedup miss when two announcement streams watch
+     * one path: the second stream's retraction can arrive after the first has already seen the
+     * replacement, dropping the fresh entry so the next request subscribes again instead of
+     * sharing. Telling that stale retraction from a live one needs a generation id on the
+     * advertisement (moq-lite's `Epoch`, not yet on the wire), so until then this errs toward a
+     * duplicate subscription rather than risk handing out a dead one.
+     */
+    evict(path) {
+        this.#cache.delete(path);
+    }
+}
+//# sourceMappingURL=consume.js.map

package/consume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume.js","sourceRoot":"","sources":["../src/consume.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAC1B,wEAAwE;IACxE,MAAM,GAAG,IAAI,GAAG,EAAkC,CAAC;IAEnD,yFAAyF;IACzF,GAAG,CAAC,IAAgB;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QAClE,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAAgB,EAAE,QAA4B;QACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAEhC,wFAAwF;QACxF,2FAA2F;QAC3F,KAAK,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAC9B,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,QAAQ;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,IAAgB;QACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACD","sourcesContent":["import type * as broadcast from \"./broadcast.ts\";\nimport type * as Path from \"./path.ts\";\n\n/**\n * Per-path dedup cache for consumed broadcasts, shared by the moq-lite and moq-ietf\n * subscribers.\n *\n * `Connection.consume(path)` must not mint a fresh subscription per call: repeat requests\n * for the same path (e.g. several renditions referencing one `broadcast: \"./source\"`) should\n * share a single upstream subscription. This mirrors the Rust `origin::Consumer` weak-cache:\n * a still-live path resolves to a shared {@link broadcast.Consumer.clone}, a closed one is\n * re-consumed on the next request. Each handle is reference-counted, so the shared broadcast\n * closes once every caller has closed its handle.\n *\n * @internal\n */\nexport class BroadcastCache {\n\t// The base handle per path; callers get reference-counted clones of it.\n\t#cache = new Map<Path.Valid, broadcast.Consumer>();\n\n\t/** A shared handle to the live broadcast cached for `path`, or `undefined` on a miss. */\n\tget(path: Path.Valid): broadcast.Consumer | undefined {\n\t\tconst base = this.#cache.get(path);\n\t\tif (base && base.closed.peek() === undefined) return base.clone();\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Cache `consumer` as the base handle for `path` (evicting it once it closes) and return it.\n\t * Call on a {@link get} miss, after wiring up the fresh consumer's subscribe loop.\n\t */\n\tinsert(path: Path.Valid, consumer: broadcast.Consumer): broadcast.Consumer {\n\t\tthis.#cache.set(path, consumer);\n\n\t\t// Drop the entry once the broadcast closes (every handle released), so the next request\n\t\t// re-consumes rather than cloning a dead handle. Guard against a newer entry for the path.\n\t\tvoid consumer.closed.then(() => {\n\t\t\tif (this.#cache.get(path) === consumer) this.#cache.delete(path);\n\t\t});\n\n\t\treturn consumer;\n\t}\n\n\t/**\n\t * Stop sharing the broadcast cached for `path`, so the next request subscribes fresh.\n\t *\n\t * Call when the path's advertisement goes away. A handle only leaves the cache on its own\n\t * once *every* holder has closed it, so one holder outliving the publisher (a second\n\t * watcher, or a caller consuming the path directly) would otherwise keep the dead\n\t * generation's cached tracks alive and hand them to whoever consumes the path next.\n\t * Existing handles are left alone: they belong to their holders, and the wire resets\n\t * whatever they still have open.\n\t *\n\t * Eviction is unconditional, which costs a dedup miss when two announcement streams watch\n\t * one path: the second stream's retraction can arrive after the first has already seen the\n\t * replacement, dropping the fresh entry so the next request subscribes again instead of\n\t * sharing. Telling that stale retraction from a live one needs a generation id on the\n\t * advertisement (moq-lite's `Epoch`, not yet on the wire), so until then this errs toward a\n\t * duplicate subscription rather than risk handing out a dead one.\n\t */\n\tevict(path: Path.Valid): void {\n\t\tthis.#cache.delete(path);\n\t}\n}\n"]}

package/datagram.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A datagram: a single unreliable payload on a track, parallel to groups.
+ *
+ * @module
+ */
+import type { Timestamp } from "./time";
+/**
+ * A single unreliable payload on a track: a sequence number, a presentation timestamp, and the bytes.
+ *
+ * Unlike a {@link Group} (an ordered stream of frames over a QUIC stream), a datagram is one
+ * self-contained payload carried in a single QUIC datagram: best-effort, unordered, never
+ * retransmitted. It shares the track's monotonic sequence-number namespace with groups but is
+ * otherwise independent. Mirrors the Rust `Datagram`.
+ */
+export interface Datagram {
+    /** Per-track sequence number, shared with the group namespace. */
+    sequence: number;
+    /** Presentation timestamp in the track's timescale. */
+    timestamp: Timestamp;
+    /** The datagram payload. */
+    payload: Uint8Array;
+}
+//# sourceMappingURL=datagram.d.ts.map

package/datagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datagram.d.ts","sourceRoot":"","sources":["../src/datagram.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,EAAE,SAAS,CAAC;IACrB,4BAA4B;IAC5B,OAAO,EAAE,UAAU,CAAC;CACpB"}

package/datagram.js

@@ -0,0 +1,3 @@
+/* @ts-self-types="./datagram.d.ts" */
+export {};
+//# sourceMappingURL=datagram.js.map

package/datagram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datagram.js","sourceRoot":"","sources":["../src/datagram.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A datagram: a single unreliable payload on a track, parallel to groups.\n *\n * @module\n */\nimport type { Timestamp } from \"./time.ts\";\n\n/**\n * A single unreliable payload on a track: a sequence number, a presentation timestamp, and the bytes.\n *\n * Unlike a {@link Group} (an ordered stream of frames over a QUIC stream), a datagram is one\n * self-contained payload carried in a single QUIC datagram: best-effort, unordered, never\n * retransmitted. It shares the track's monotonic sequence-number namespace with groups but is\n * otherwise independent. Mirrors the Rust `Datagram`.\n */\nexport interface Datagram {\n\t/** Per-track sequence number, shared with the group namespace. */\n\tsequence: number;\n\t/** Presentation timestamp in the track's timescale. */\n\ttimestamp: Timestamp;\n\t/** The datagram payload. */\n\tpayload: Uint8Array;\n}\n"]}

package/error.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Errors, including the code a peer reports when it resets a stream.
+ *
+ * @module
+ */
+/**
+ * An error the peer reported by resetting a stream, carrying the raw code it sent.
+ *
+ * The codes are not standardized, so this deliberately does not translate one into a local
+ * error: the number means whatever the peer's implementation says it means. A read or write
+ * rejects with this on every transport, so branch on {@link code} rather than feature-detecting
+ * `WebTransportError`, which a non-browser runtime never defines and the WebSocket fallback
+ * never throws.
+ *
+ * Code 0 is what a transport sends when a stream is dropped or aborted with no code of its own.
+ *
+ * ```ts
+ * try {
+ *   frame = await group.readFrame();
+ * } catch (err) {
+ *   // Whatever this peer's code 2 means to it.
+ *   if (err instanceof RemoteError && err.code === 2) return;
+ *   throw err;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class RemoteError extends Error {
+    /** The code the peer sent, verbatim. */
+    readonly code: number;
+    constructor(code: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A peer broke the protocol in a way the spec says must end the session.
+ *
+ * Thrown where the violation is detected, rather than handled there: a decoder has no session
+ * to close. The dispatch that owns the session watches for it and closes, so a nonconforming
+ * peer cannot repeat the violation on the next stream.
+ *
+ * @internal
+ */
+export declare class ProtocolViolation extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Decode a transport failure into a {@link RemoteError} error when it carries a stream reset code,
+ * otherwise pass it through.
+ *
+ * Native WebTransport rejects with a `WebTransportError`; the WebSocket fallback mints an error
+ * with the same `source`/`streamErrorCode` fields. Reading the fields rather than the class
+ * covers both, and works in a runtime with no `WebTransportError` at all.
+ *
+ * @internal Called at the transport boundary so the raw error never reaches an application.
+ */
+export declare function fromTransport(err: unknown): Error;
+/**
+ * Coerce an unknown thrown value into an `Error`.
+ *
+ * @internal
+ */
+export declare function error(err: unknown): Error;
+/**
+ * Format an error into a non-empty, human-readable string for logging.
+ *
+ * Safari always leaves `WebTransportError.message` blank, so a bare `err.message` degrades to
+ * an empty string and the reason is lost. This falls back to the error type name and appends
+ * the WebTransport `source` and application `streamErrorCode`, so the log line always says
+ * something.
+ */
+export declare function reason(err: unknown): string;
+//# sourceMappingURL=error.d.ts.map

package/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACrC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAItD;CACD;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACD;AAcD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAIjD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAa3C"}

package/error.js

@@ -0,0 +1,107 @@
+/* @ts-self-types="./error.d.ts" */
+/**
+ * Errors, including the code a peer reports when it resets a stream.
+ *
+ * @module
+ */
+/**
+ * An error the peer reported by resetting a stream, carrying the raw code it sent.
+ *
+ * The codes are not standardized, so this deliberately does not translate one into a local
+ * error: the number means whatever the peer's implementation says it means. A read or write
+ * rejects with this on every transport, so branch on {@link code} rather than feature-detecting
+ * `WebTransportError`, which a non-browser runtime never defines and the WebSocket fallback
+ * never throws.
+ *
+ * Code 0 is what a transport sends when a stream is dropped or aborted with no code of its own.
+ *
+ * ```ts
+ * try {
+ *   frame = await group.readFrame();
+ * } catch (err) {
+ *   // Whatever this peer's code 2 means to it.
+ *   if (err instanceof RemoteError && err.code === 2) return;
+ *   throw err;
+ * }
+ * ```
+ *
+ * @public
+ */
+export class RemoteError extends Error {
+    /** The code the peer sent, verbatim. */
+    code;
+    constructor(code, options) {
+        super(`remote error: ${code}`, options);
+        this.name = "RemoteError";
+        this.code = code;
+    }
+}
+/**
+ * A peer broke the protocol in a way the spec says must end the session.
+ *
+ * Thrown where the violation is detected, rather than handled there: a decoder has no session
+ * to close. The dispatch that owns the session watches for it and closes, so a nonconforming
+ * peer cannot repeat the violation on the next stream.
+ *
+ * @internal
+ */
+export class ProtocolViolation extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ProtocolViolation";
+    }
+}
+function streamCode(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const { source, streamErrorCode } = err;
+    if (source !== "stream" || typeof streamErrorCode !== "number")
+        return undefined;
+    return streamErrorCode;
+}
+/**
+ * Decode a transport failure into a {@link RemoteError} error when it carries a stream reset code,
+ * otherwise pass it through.
+ *
+ * Native WebTransport rejects with a `WebTransportError`; the WebSocket fallback mints an error
+ * with the same `source`/`streamErrorCode` fields. Reading the fields rather than the class
+ * covers both, and works in a runtime with no `WebTransportError` at all.
+ *
+ * @internal Called at the transport boundary so the raw error never reaches an application.
+ */
+export function fromTransport(err) {
+    const code = streamCode(err);
+    if (code === undefined)
+        return error(err);
+    return new RemoteError(code, { cause: err });
+}
+/**
+ * Coerce an unknown thrown value into an `Error`.
+ *
+ * @internal
+ */
+export function error(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Format an error into a non-empty, human-readable string for logging.
+ *
+ * Safari always leaves `WebTransportError.message` blank, so a bare `err.message` degrades to
+ * an empty string and the reason is lost. This falls back to the error type name and appends
+ * the WebTransport `source` and application `streamErrorCode`, so the log line always says
+ * something.
+ */
+export function reason(err) {
+    const e = error(err);
+    // WebTransportError carries the failure origin and the peer's application error code,
+    // often the only identifying detail since WebKit leaves `message` empty.
+    if (typeof WebTransportError !== "undefined" && e instanceof WebTransportError) {
+        const parts = [`source=${e.source}`];
+        if (e.streamErrorCode !== null)
+            parts.push(`code=${e.streamErrorCode}`);
+        const detail = parts.join(" ");
+        return e.message ? `${e.message} (${detail})` : `WebTransportError: ${detail}`;
+    }
+    return e.message || e.name || "unknown error";
+}
+//# sourceMappingURL=error.js.map

package/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACrC,wCAAwC;IAC/B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAA6B;QACtD,KAAK,CAAC,iBAAiB,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C,YAAY,OAAe,EAAE,OAA6B;QACzD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACjC,CAAC;CACD;AAKD,SAAS,UAAU,CAAC,GAAY;IAC/B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAE9D,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,GAAsB,CAAC;IAC3D,IAAI,MAAM,KAAK,QAAQ,IAAI,OAAO,eAAe,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEjF,OAAO,eAAe,CAAC;AACxB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY;IACjC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,GAAY;IAClC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAErB,sFAAsF;IACtF,yEAAyE;IACzE,IAAI,OAAO,iBAAiB,KAAK,WAAW,IAAI,CAAC,YAAY,iBAAiB,EAAE,CAAC;QAChF,MAAM,KAAK,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,CAAC,eAAe,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,sBAAsB,MAAM,EAAE,CAAC;IAChF,CAAC;IAED,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC;AAC/C,CAAC","sourcesContent":["/**\n * Errors, including the code a peer reports when it resets a stream.\n *\n * @module\n */\n\n/**\n * An error the peer reported by resetting a stream, carrying the raw code it sent.\n *\n * The codes are not standardized, so this deliberately does not translate one into a local\n * error: the number means whatever the peer's implementation says it means. A read or write\n * rejects with this on every transport, so branch on {@link code} rather than feature-detecting\n * `WebTransportError`, which a non-browser runtime never defines and the WebSocket fallback\n * never throws.\n *\n * Code 0 is what a transport sends when a stream is dropped or aborted with no code of its own.\n *\n * ```ts\n * try {\n *   frame = await group.readFrame();\n * } catch (err) {\n *   // Whatever this peer's code 2 means to it.\n *   if (err instanceof RemoteError && err.code === 2) return;\n *   throw err;\n * }\n * ```\n *\n * @public\n */\nexport class RemoteError extends Error {\n\t/** The code the peer sent, verbatim. */\n\treadonly code: number;\n\n\tconstructor(code: number, options?: { cause?: unknown }) {\n\t\tsuper(`remote error: ${code}`, options);\n\t\tthis.name = \"RemoteError\";\n\t\tthis.code = code;\n\t}\n}\n\n/**\n * A peer broke the protocol in a way the spec says must end the session.\n *\n * Thrown where the violation is detected, rather than handled there: a decoder has no session\n * to close. The dispatch that owns the session watches for it and closes, so a nonconforming\n * peer cannot repeat the violation on the next stream.\n *\n * @internal\n */\nexport class ProtocolViolation extends Error {\n\tconstructor(message: string, options?: { cause?: unknown }) {\n\t\tsuper(message, options);\n\t\tthis.name = \"ProtocolViolation\";\n\t}\n}\n\n/** The WebTransport-shaped fields a stream reset code arrives in. */\ntype StreamErrorLike = { source?: unknown; streamErrorCode?: unknown };\n\nfunction streamCode(err: unknown): number | undefined {\n\tif (typeof err !== \"object\" || err === null) return undefined;\n\n\tconst { source, streamErrorCode } = err as StreamErrorLike;\n\tif (source !== \"stream\" || typeof streamErrorCode !== \"number\") return undefined;\n\n\treturn streamErrorCode;\n}\n\n/**\n * Decode a transport failure into a {@link RemoteError} error when it carries a stream reset code,\n * otherwise pass it through.\n *\n * Native WebTransport rejects with a `WebTransportError`; the WebSocket fallback mints an error\n * with the same `source`/`streamErrorCode` fields. Reading the fields rather than the class\n * covers both, and works in a runtime with no `WebTransportError` at all.\n *\n * @internal Called at the transport boundary so the raw error never reaches an application.\n */\nexport function fromTransport(err: unknown): Error {\n\tconst code = streamCode(err);\n\tif (code === undefined) return error(err);\n\treturn new RemoteError(code, { cause: err });\n}\n\n/**\n * Coerce an unknown thrown value into an `Error`.\n *\n * @internal\n */\nexport function error(err: unknown): Error {\n\treturn err instanceof Error ? err : new Error(String(err));\n}\n\n/**\n * Format an error into a non-empty, human-readable string for logging.\n *\n * Safari always leaves `WebTransportError.message` blank, so a bare `err.message` degrades to\n * an empty string and the reason is lost. This falls back to the error type name and appends\n * the WebTransport `source` and application `streamErrorCode`, so the log line always says\n * something.\n */\nexport function reason(err: unknown): string {\n\tconst e = error(err);\n\n\t// WebTransportError carries the failure origin and the peer's application error code,\n\t// often the only identifying detail since WebKit leaves `message` empty.\n\tif (typeof WebTransportError !== \"undefined\" && e instanceof WebTransportError) {\n\t\tconst parts = [`source=${e.source}`];\n\t\tif (e.streamErrorCode !== null) parts.push(`code=${e.streamErrorCode}`);\n\t\tconst detail = parts.join(\" \");\n\t\treturn e.message ? `${e.message} (${detail})` : `WebTransportError: ${detail}`;\n\t}\n\n\treturn e.message || e.name || \"unknown error\";\n}\n"]}

package/group.d.ts

@@ -1,66 +1,171 @@
-/** An ordered stream of frames within a track, delivered over a single QUIC stream. */
-export declare class Group {
+/**
+ * Group role handles: an ordered stream of frames within a track, delivered over one QUIC stream.
+ *
+ * @module
+ */
+import { type GetPromise, type Getter } from "@norskvideo/moq-signals";
+import { Timestamp } from "./time";
+/** Maximum bytes of frames cached in a group before old frames are evicted from the front. */
+export declare const MAX_GROUP_CACHE_BYTES: number;
+/** Maximum number of frames cached in a group before old frames are evicted from the front. */
+export declare const MAX_GROUP_FRAMES = 1024;
+/**
+ * A frame buffered in a group: its presentation {@link Timestamp} and payload bytes.
+ *
+ * The timestamp carries its own scale, so a track can pick its units; the wire layer
+ * converts it into the track's negotiated timescale.
+ */
+export interface Frame {
+    /** The frame payload. */
+    payload: Uint8Array;
+    /**
+     * Presentation timestamp. Required: for a payload with no presentation time of its own
+     * (a JSON catalog, control state) pass {@link Timestamp.now} explicitly.
+     */
+    timestamp: Timestamp;
+}
+/** Options for a sequence-aware frame read. */
+export interface ReadOptions {
+    /**
+     * The lowest sequence number the caller wants; defaults to the whole group.
+     *
+     * Frames below it are discarded instead of returned, and frames evicted below it are not
+     * a gap: the read resumes at the next retained frame rather than throwing {@link Lagged}.
+     * An eviction at or above it still throws, because the caller asked for that frame.
+     */
+    from?: number;
+}
+/** Immutable group metadata. */
+export interface Info {
+    /** Sequence number of this group within its track. */
+    sequence: number;
+}
+/**
+ * Thrown by a frame read when the reader fell behind the group's eviction window: frames
+ * it had not yet read were dropped to stay under the cache cap, so the stream has a gap.
+ */
+export declare class Lagged extends Error {
+    constructor();
+}
+/**
+ * The write side of an ordered stream of frames within a track.
+ *
+ * @public
+ */
+export declare class Producer {
     #private;
     /** Sequence number of this group within its track. */
     readonly sequence: number;
-    /** Resolves with the abort error (or undefined) once closed. */
-    readonly closed: Promise<Error | undefined>;
     constructor(sequence: number);
     /**
-     * Writes a frame to the group.
-     * @param frame - The frame to write
+     * Settles once the group closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
+     */
+    get closed(): GetPromise<Error | null>;
+    /** A read handle for this group. */
+    consume(): Consumer;
+    /**
+     * Create an independent read handle that receives every frame written here.
+     *
+     * Frames written so far are replayed synchronously; later writes and close are teed
+     * in as they happen.
+     *
+     * @internal Track fan-out and fetch coalescing only. Use {@link consume} instead.
+     */
+    mirror(): Consumer;
+    /**
+     * Whether any mirror reader is currently attached.
+     *
+     * Pairs with {@link unused}. Fetch coalescing watches it to cancel a download once every reader
+     * has gone: a group can stay open indefinitely (a catalog track, a JSON stream), so it can't
+     * rely on the stream ending on its own.
+     *
+     * @internal Track fan-out and fetch coalescing only.
+     */
+    get used(): Getter<boolean>;
+    /**
+     * Resolves once no mirror reader remains (or the group closes).
+     *
+     * @internal Track fan-out and fetch coalescing only.
      */
-    writeFrame(frame: Uint8Array, extensions?: Uint8Array): void;
-    /** Write a string as a single UTF-8 encoded frame. */
+    unused(): Promise<void>;
+    /** Writes a frame to the group. */
+    writeFrame(frame: Frame): void;
+    /** Write a string as a single UTF-8 encoded frame, stamped with {@link Timestamp.now}. */
     writeString(str: string): void;
-    /** Write a value as a single JSON-encoded frame. */
+    /** Write a value as a single JSON-encoded frame, stamped with {@link Timestamp.now}. */
     writeJson(json: unknown): void;
-    /** Write a boolean as a single one-byte frame. */
+    /** Write a boolean as a single one-byte frame, stamped with {@link Timestamp.now}. */
     writeBool(bool: boolean): void;
+    /** True once the group has been closed. */
+    get isClosed(): boolean;
+    /** Closes the group, optionally with an error to abort readers. */
+    close(abort?: Error): void;
+}
+/**
+ * The read side of an ordered stream of frames within a track.
+ *
+ * Created internally: obtain one from {@link Producer.consume} or a track subscriber's
+ * group reads.
+ *
+ * @public
+ */
+export declare class Consumer {
+    #private;
+    /** Sequence number of this group within its track. */
+    readonly sequence: number;
+    private constructor();
+    /**
+     * Settles once the group closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
+     */
+    get closed(): GetPromise<Error | null>;
     /** True once no further frames can be read: the group has closed and every buffered frame is read. */
     get done(): boolean;
+    /** True once the group has been closed, regardless of whether buffered frames remain unread. Synchronous complement to the {@link closed} promise. */
+    get isClosed(): boolean;
+    /** True if frames were evicted from the front of this group before being read. */
+    get skipped(): boolean;
     /**
-     * Reads the next already-buffered frame without blocking.
+     * How many frames the group has held, including any already read or evicted.
      *
-     * Returns `undefined` when nothing is buffered right now. That is *not* by itself end-of-group:
-     * check {@link done} to tell "no frame buffered yet" (more may arrive) from "the group finished".
-     * Drain a backlog by looping until this returns `undefined`, then branch on {@link done}: if not
-     * done, {@link readable} resolves when the next frame arrives.
+     * It is also the next frame's sequence number, so `frameCount - 1` names the newest
+     * frame written so far. A publisher snapshots it to resolve the track's live edge.
      */
-    tryReadFrame(): Uint8Array | undefined;
-    /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */
-    tryReadFrameSequence(): {
-        sequence: number;
-        data: Uint8Array;
-        extensions?: Uint8Array;
-    } | undefined;
+    get frameCount(): number;
     /**
-     * Resolves once {@link readFrame} would not block: a frame is buffered, or the group has closed.
-     * Always settles (never hangs), so on a finished group it resolves immediately; pair it with
-     * {@link done} to avoid re-waiting on a group that has nothing left.
+     * Reads the next already-buffered frame without blocking.
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
      *
-     * Lets a caller fold "this group has a frame" into a larger wait (e.g. racing it against a new
-     * group arriving) without touching the group's internal signals.
+     * Returns `undefined` when nothing is buffered right now. That is not by itself
+     * end-of-group: check {@link done} to tell "no frame buffered yet" from "finished".
      */
+    tryReadFrame(): Frame | undefined;
+    /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */
+    tryReadFrameSequence(): ({
+        sequence: number;
+    } & Frame) | undefined;
+    /** Resolves once {@link readFrame} would not block. */
     readable(): Promise<void>;
     /**
      * Reads the next frame from the group.
-     * @returns A promise that resolves to the next frame or undefined
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
+     */
+    readFrame(): Promise<Frame | undefined>;
+    /**
+     * Reads the next frame along with its sequence number within the group.
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
      */
-    readFrame(): Promise<Uint8Array | undefined>;
-    /** Reads the next frame along with its sequence number within the group. */
-    readFrameSequence(): Promise<{
+    readFrameSequence(options?: ReadOptions): Promise<({
         sequence: number;
-        data: Uint8Array;
-        extensions?: Uint8Array;
-    } | undefined>;
-    /** Reads the next frame and decodes it as a UTF-8 string. */
+    } & Frame) | undefined>;
+    /** Reads the next frame and decodes its payload as a UTF-8 string. */
     readString(): Promise<string | undefined>;
-    /** Reads the next frame and parses it as JSON. */
+    /** Reads the next frame and parses its payload as JSON. */
     readJson(): Promise<unknown | undefined>;
-    /** Reads the next frame and decodes it as a one-byte boolean. */
+    /** Reads the next frame and decodes its payload as a one-byte boolean. */
     readBool(): Promise<boolean | undefined>;
-    /** Closes the group, optionally with an error to abort readers. */
+    /** Closes the group, optionally with an error to abort readers. Idempotent. */
     close(abort?: Error): void;
 }
 //# sourceMappingURL=group.d.ts.map

package/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"AAeA,uFAAuF;AACvF,qBAAa,KAAK;;IACjB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAE5C,YAAY,QAAQ,EAAE,MAAM,EAW3B;IAED;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,UAAU,QAQpD;IAED,sDAAsD;IACtD,WAAW,CAAC,GAAG,EAAE,MAAM,QAEtB;IAED,oDAAoD;IACpD,SAAS,CAAC,IAAI,EAAE,OAAO,QAEtB;IAED,kDAAkD;IAClD,SAAS,CAAC,IAAI,EAAE,OAAO,QAEtB;IAED,sGAAsG;IACtG,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;;;;;;OAOG;IACH,YAAY,IAAI,UAAU,GAAG,SAAS,CAErC;IAED,+FAA+F;IAC/F,oBAAoB,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,SAAS,CAKlG;IAED;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9B;IAED;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAEjD;IAED,4EAA4E;IACtE,iBAAiB,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,SAAS,CAAC,CAY9G;IAED,6DAA6D;IACvD,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG9C;IAED,kDAAkD;IAC5C,QAAQ,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAG7C;IAED,iEAAiE;IAC3D,QAAQ,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAG7C;IAED,mEAAmE;IACnE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"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"}