@norskvideo/moq-net 0.1.0

package/connection/reload.js

@@ -0,0 +1,137 @@
+/* @ts-self-types="./reload.d.ts" */
+import { Effect, Signal } from "@norskvideo/moq-signals";
+import { empty as emptyPath } from "../path.js";
+import { connect } from "./connect.js";
+/** Maintains a MoQ connection, reconnecting with exponential backoff when it drops. */
+export class Reload {
+    /** Relay URL to connect to; updating it triggers a reconnect. */
+    url;
+    /** Whether reconnecting is active. */
+    enabled;
+    /** Current connection status. */
+    status = new Signal("disconnected");
+    /** The currently established session, or undefined while disconnected. */
+    established = new Signal(undefined);
+    // All actively announced broadcast paths, updated reactively.
+    #announced = new Signal(new Set());
+    /** The set of broadcast paths currently announced by the server, updated reactively. */
+    announced = this.#announced;
+    /** WebTransport options applied to each connection attempt (not reactive). */
+    webtransport;
+    /** WebSocket fallback options applied to each connection attempt (not reactive). */
+    websocket;
+    /** Backoff settings for the reconnect loop. */
+    delay;
+    /** The reactive effect scope driving the connect loop; closed by {@link Reload.close}. */
+    signals = new Effect();
+    /** Resolves when the reconnect loop stops via {@link Reload.close} or the retry timeout. */
+    closed;
+    #closedResolve;
+    #closedReject;
+    #delay;
+    // Timestamp when the current retry sequence started (for timeout).
+    #retryStart;
+    // Increased by 1 each time to trigger a reload.
+    #tick = new Signal(0);
+    constructor(props) {
+        this.url = Signal.from(props?.url);
+        this.enabled = Signal.from(props?.enabled ?? false);
+        this.delay = props?.delay ?? { initial: 1000, multiplier: 2, max: 30000 };
+        this.webtransport = props?.webtransport;
+        this.websocket = props?.websocket;
+        this.#delay = this.delay.initial;
+        this.closed = new Promise((resolve, reject) => {
+            this.#closedResolve = resolve;
+            this.#closedReject = reject;
+        });
+        // Create a reactive root so cleanup is easier.
+        this.signals.run(this.#connect.bind(this));
+        this.signals.run(this.#runAnnounced.bind(this));
+    }
+    #connect(effect) {
+        // Will retry when the tick changes.
+        effect.get(this.#tick);
+        const enabled = effect.get(this.enabled);
+        if (!enabled)
+            return;
+        const url = effect.get(this.url);
+        if (!url)
+            return;
+        effect.set(this.status, "connecting", "disconnected");
+        effect.spawn(async () => {
+            try {
+                const pending = connect(url, { websocket: this.websocket, webtransport: this.webtransport });
+                const connection = await Promise.race([effect.cancel, pending]);
+                if (!connection) {
+                    pending.then((conn) => conn.close()).catch(() => { });
+                    return;
+                }
+                effect.set(this.established, connection);
+                effect.cleanup(() => connection.close());
+                effect.set(this.status, "connected", "disconnected");
+                // Reset the exponential backoff and timeout on success.
+                this.#delay = this.delay.initial;
+                this.#retryStart = undefined;
+                await Promise.race([effect.cancel, connection.closed]);
+            }
+            catch (err) {
+                console.warn("connection error:", err);
+                // Track retry start for timeout.
+                this.#retryStart ??= performance.now();
+                const timeout = this.delay.timeout ?? 300000;
+                if (timeout > 0) {
+                    const elapsed = performance.now() - this.#retryStart;
+                    if (elapsed >= timeout) {
+                        console.warn("reconnect timed out");
+                        this.#closedReject(err instanceof Error ? err : new Error(String(err)));
+                        return;
+                    }
+                }
+                const tick = this.#tick.peek() + 1;
+                effect.timer(() => this.#tick.update((prev) => Math.max(prev, tick)), this.#delay);
+                this.#delay = Math.min(this.#delay * this.delay.multiplier, this.delay.max);
+            }
+        });
+    }
+    #runAnnounced(effect) {
+        this.#announced.set(new Set());
+        const conn = effect.get(this.established);
+        if (!conn)
+            return;
+        effect.cleanup(() => this.#announced.set(new Set()));
+        // Cloudflare's relay does not yet support SUBSCRIBE_NAMESPACE, so
+        // skip announce subscriptions entirely for those hosts.
+        if (conn.url.hostname.endsWith("mediaoverquic.com")) {
+            return;
+        }
+        const announced = conn.announced(emptyPath());
+        effect.cleanup(() => announced.close());
+        effect.spawn(async () => {
+            try {
+                for (;;) {
+                    const entry = await Promise.race([effect.cancel, announced.next()]);
+                    if (!entry)
+                        break;
+                    this.#announced.mutate((active) => {
+                        if (entry.active) {
+                            active.add(entry.path);
+                        }
+                        else {
+                            active.delete(entry.path);
+                        }
+                    });
+                }
+            }
+            catch (err) {
+                this.#announced.set(new Set());
+                throw err;
+            }
+        });
+    }
+    /** Stop reconnecting, close the current connection, and resolve {@link Reload.closed}. */
+    close() {
+        this.signals.close();
+        this.#closedResolve();
+    }
+}
+//# sourceMappingURL=reload.js.map

package/connection/reload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload.js","sourceRoot":"","sources":["../../src/connection/reload.ts"],"names":[],"mappings":"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","sourcesContent":["import { Effect, type Getter, Signal } from \"@moq/signals\";\nimport type * as Path from \"../path.ts\";\nimport { empty as emptyPath } from \"../path.ts\";\nimport { type ConnectProps, connect, type WebSocketOptions, type WebTransportProps } from \"./connect.ts\";\nimport type { Established } from \"./established.ts\";\n\n/** Exponential backoff settings for {@link Reload}'s reconnect loop. */\nexport type ReloadDelay = {\n\t// The delay in milliseconds before reconnecting.\n\t// default: 1000\n\tinitial: DOMHighResTimeStamp;\n\n\t// The multiplier for the delay.\n\t// default: 2\n\tmultiplier: number;\n\n\t// The maximum delay in milliseconds.\n\t// default: 30000\n\tmax: DOMHighResTimeStamp;\n\n\t// Maximum total time in milliseconds to spend retrying before giving up.\n\t// Resets after each successful connection. Set to 0 for unlimited retries.\n\t// default: 300000 (5 minutes)\n\ttimeout?: DOMHighResTimeStamp;\n};\n\n/** Options for {@link Reload}: connect options plus reactive URL/enabled signals and backoff tuning. */\nexport type ReloadProps = ConnectProps & {\n\t// Whether to reload the connection when it disconnects.\n\t// default: true\n\tenabled?: boolean | Signal<boolean>;\n\n\t// The URL of the relay server.\n\turl?: URL | Signal<URL | undefined>;\n\n\t// The delay for the reload.\n\tdelay?: ReloadDelay;\n};\n\n/** Current state of a {@link Reload} connection. */\nexport type ReloadStatus = \"connecting\" | \"connected\" | \"disconnected\";\n\n/** Maintains a MoQ connection, reconnecting with exponential backoff when it drops. */\nexport class Reload {\n\t/** Relay URL to connect to; updating it triggers a reconnect. */\n\turl: Signal<URL | undefined>;\n\n\t/** Whether reconnecting is active. */\n\tenabled: Signal<boolean>;\n\n\t/** Current connection status. */\n\tstatus = new Signal<ReloadStatus>(\"disconnected\");\n\n\t/** The currently established session, or undefined while disconnected. */\n\testablished = new Signal<Established | undefined>(undefined);\n\n\t// All actively announced broadcast paths, updated reactively.\n\t#announced = new Signal<Set<Path.Valid>>(new Set());\n\n\t/** The set of broadcast paths currently announced by the server, updated reactively. */\n\treadonly announced: Getter<Set<Path.Valid>> = this.#announced;\n\n\t/** WebTransport options applied to each connection attempt (not reactive). */\n\twebtransport?: WebTransportProps;\n\n\t/** WebSocket fallback options applied to each connection attempt (not reactive). */\n\twebsocket: WebSocketOptions | undefined;\n\n\t/** Backoff settings for the reconnect loop. */\n\tdelay: ReloadDelay;\n\n\t/** The reactive effect scope driving the connect loop; closed by {@link Reload.close}. */\n\tsignals = new Effect();\n\n\t/** Resolves when the reconnect loop stops via {@link Reload.close} or the retry timeout. */\n\tclosed: Promise<void>;\n\t#closedResolve!: () => void;\n\t#closedReject!: (err: Error) => void;\n\n\t#delay: DOMHighResTimeStamp;\n\n\t// Timestamp when the current retry sequence started (for timeout).\n\t#retryStart: DOMHighResTimeStamp | undefined;\n\n\t// Increased by 1 each time to trigger a reload.\n\t#tick = new Signal(0);\n\n\tconstructor(props?: ReloadProps) {\n\t\tthis.url = Signal.from(props?.url);\n\t\tthis.enabled = Signal.from(props?.enabled ?? false);\n\t\tthis.delay = props?.delay ?? { initial: 1000, multiplier: 2, max: 30000 };\n\t\tthis.webtransport = props?.webtransport;\n\t\tthis.websocket = props?.websocket;\n\n\t\tthis.#delay = this.delay.initial;\n\n\t\tthis.closed = new Promise((resolve, reject) => {\n\t\t\tthis.#closedResolve = resolve;\n\t\t\tthis.#closedReject = reject;\n\t\t});\n\n\t\t// Create a reactive root so cleanup is easier.\n\t\tthis.signals.run(this.#connect.bind(this));\n\t\tthis.signals.run(this.#runAnnounced.bind(this));\n\t}\n\n\t#connect(effect: Effect): void {\n\t\t// Will retry when the tick changes.\n\t\teffect.get(this.#tick);\n\n\t\tconst enabled = effect.get(this.enabled);\n\t\tif (!enabled) return;\n\n\t\tconst url = effect.get(this.url);\n\t\tif (!url) return;\n\n\t\teffect.set(this.status, \"connecting\", \"disconnected\");\n\n\t\teffect.spawn(async () => {\n\t\t\ttry {\n\t\t\t\tconst pending = connect(url, { websocket: this.websocket, webtransport: this.webtransport });\n\n\t\t\t\tconst connection = await Promise.race([effect.cancel, pending]);\n\t\t\t\tif (!connection) {\n\t\t\t\t\tpending.then((conn) => conn.close()).catch(() => {});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\teffect.set(this.established, connection);\n\t\t\t\teffect.cleanup(() => connection.close());\n\n\t\t\t\teffect.set(this.status, \"connected\", \"disconnected\");\n\n\t\t\t\t// Reset the exponential backoff and timeout on success.\n\t\t\t\tthis.#delay = this.delay.initial;\n\t\t\t\tthis.#retryStart = undefined;\n\n\t\t\t\tawait Promise.race([effect.cancel, connection.closed]);\n\t\t\t} catch (err) {\n\t\t\t\tconsole.warn(\"connection error:\", err);\n\n\t\t\t\t// Track retry start for timeout.\n\t\t\t\tthis.#retryStart ??= performance.now();\n\n\t\t\t\tconst timeout = this.delay.timeout ?? 300000;\n\t\t\t\tif (timeout > 0) {\n\t\t\t\t\tconst elapsed = performance.now() - this.#retryStart;\n\t\t\t\t\tif (elapsed >= timeout) {\n\t\t\t\t\t\tconsole.warn(\"reconnect timed out\");\n\t\t\t\t\t\tthis.#closedReject(err instanceof Error ? err : new Error(String(err)));\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tconst tick = this.#tick.peek() + 1;\n\t\t\t\teffect.timer(() => this.#tick.update((prev) => Math.max(prev, tick)), this.#delay);\n\n\t\t\t\tthis.#delay = Math.min(this.#delay * this.delay.multiplier, this.delay.max);\n\t\t\t}\n\t\t});\n\t}\n\n\t#runAnnounced(effect: Effect): void {\n\t\tthis.#announced.set(new Set());\n\n\t\tconst conn = effect.get(this.established);\n\t\tif (!conn) return;\n\n\t\teffect.cleanup(() => this.#announced.set(new Set()));\n\n\t\t// Cloudflare's relay does not yet support SUBSCRIBE_NAMESPACE, so\n\t\t// skip announce subscriptions entirely for those hosts.\n\t\tif (conn.url.hostname.endsWith(\"mediaoverquic.com\")) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst announced = conn.announced(emptyPath());\n\t\teffect.cleanup(() => announced.close());\n\n\t\teffect.spawn(async () => {\n\t\t\ttry {\n\t\t\t\tfor (;;) {\n\t\t\t\t\tconst entry = await Promise.race([effect.cancel, announced.next()]);\n\t\t\t\t\tif (!entry) break;\n\n\t\t\t\t\tthis.#announced.mutate((active) => {\n\t\t\t\t\t\tif (entry.active) {\n\t\t\t\t\t\t\tactive.add(entry.path);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tactive.delete(entry.path);\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t} catch (err) {\n\t\t\t\tthis.#announced.set(new Set());\n\t\t\t\tthrow err;\n\t\t\t}\n\t\t});\n\t}\n\n\t/** Stop reconnecting, close the current connection, and resolve {@link Reload.closed}. */\n\tclose() {\n\t\tthis.signals.close();\n\t\tthis.#closedResolve();\n\t}\n}\n"]}

package/group.d.ts

@@ -0,0 +1,66 @@
+/** An ordered stream of frames within a track, delivered over a single QUIC stream. */
+export declare class Group {
+    #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
+     */
+    writeFrame(frame: Uint8Array, extensions?: Uint8Array): void;
+    /** Write a string as a single UTF-8 encoded frame. */
+    writeString(str: string): void;
+    /** Write a value as a single JSON-encoded frame. */
+    writeJson(json: unknown): void;
+    /** Write a boolean as a single one-byte frame. */
+    writeBool(bool: boolean): void;
+    /** True once no further frames can be read: the group has closed and every buffered frame is read. */
+    get done(): boolean;
+    /**
+     * Reads the next already-buffered frame without blocking.
+     *
+     * 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.
+     */
+    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;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    readable(): Promise<void>;
+    /**
+     * Reads the next frame from the group.
+     * @returns A promise that resolves to the next frame or undefined
+     */
+    readFrame(): Promise<Uint8Array | undefined>;
+    /** Reads the next frame along with its sequence number within the group. */
+    readFrameSequence(): Promise<{
+        sequence: number;
+        data: Uint8Array;
+        extensions?: Uint8Array;
+    } | undefined>;
+    /** Reads the next frame and decodes it as a UTF-8 string. */
+    readString(): Promise<string | undefined>;
+    /** Reads the next frame and parses it as JSON. */
+    readJson(): Promise<unknown | undefined>;
+    /** Reads the next frame and decodes it as a one-byte boolean. */
+    readBool(): Promise<boolean | undefined>;
+    /** Closes the group, optionally with an error to abort readers. */
+    close(abort?: Error): void;
+}
+//# sourceMappingURL=group.d.ts.map

package/group.d.ts.map

@@ -0,0 +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"}

package/group.js

@@ -0,0 +1,135 @@
+/* @ts-self-types="./group.d.ts" */
+import { Signal } from "@norskvideo/moq-signals";
+class GroupState {
+    frames = new Signal([]);
+    closed = new Signal(false);
+    total = new Signal(0); // The total number of frames in the group thus far
+}
+/** An ordered stream of frames within a track, delivered over a single QUIC stream. */
+export class Group {
+    /** Sequence number of this group within its track. */
+    sequence;
+    // Reactive backing state, deliberately private: read through the read* methods so callers can't
+    // poke the signals directly (and so the internal representation can change).
+    #state = new GroupState();
+    /** Resolves with the abort error (or undefined) once closed. */
+    closed;
+    constructor(sequence) {
+        this.sequence = sequence;
+        // Cache the closed promise to avoid recreating it every time.
+        this.closed = new Promise((resolve) => {
+            const dispose = this.#state.closed.subscribe((closed) => {
+                if (!closed)
+                    return;
+                resolve(closed instanceof Error ? closed : undefined);
+                dispose();
+            });
+        });
+    }
+    /**
+     * Writes a frame to the group.
+     * @param frame - The frame to write
+     */
+    writeFrame(frame, extensions) {
+        if (this.#state.closed.peek())
+            throw new Error("group is closed");
+        this.#state.frames.mutate((frames) => {
+            frames.push({ data: frame, extensions });
+        });
+        this.#state.total.update((total) => total + 1);
+    }
+    /** Write a string as a single UTF-8 encoded frame. */
+    writeString(str) {
+        this.writeFrame(new TextEncoder().encode(str));
+    }
+    /** Write a value as a single JSON-encoded frame. */
+    writeJson(json) {
+        this.writeString(JSON.stringify(json));
+    }
+    /** Write a boolean as a single one-byte frame. */
+    writeBool(bool) {
+        this.writeFrame(new Uint8Array([bool ? 1 : 0]));
+    }
+    /** True once no further frames can be read: the group has closed and every buffered frame is read. */
+    get done() {
+        return this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== false;
+    }
+    /**
+     * Reads the next already-buffered frame without blocking.
+     *
+     * 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.
+     */
+    tryReadFrame() {
+        return this.tryReadFrameSequence()?.data;
+    }
+    /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */
+    tryReadFrameSequence() {
+        const frames = this.#state.frames.peek();
+        const frame = frames.shift();
+        if (frame === undefined)
+            return undefined;
+        return { sequence: this.#state.total.peek() - frames.length - 1, data: frame.data, extensions: frame.extensions };
+    }
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    async readable() {
+        for (;;) {
+            if (this.#state.frames.peek().length > 0)
+                return;
+            if (this.#state.closed.peek())
+                return;
+            await Signal.race(this.#state.frames, this.#state.closed);
+        }
+    }
+    /**
+     * Reads the next frame from the group.
+     * @returns A promise that resolves to the next frame or undefined
+     */
+    async readFrame() {
+        return (await this.readFrameSequence())?.data;
+    }
+    /** Reads the next frame along with its sequence number within the group. */
+    async readFrameSequence() {
+        for (;;) {
+            const next = this.tryReadFrameSequence();
+            if (next)
+                return next;
+            // Drain buffered frames before observing the close, so a closed group still yields them.
+            const closed = this.#state.closed.peek();
+            if (closed instanceof Error)
+                throw closed;
+            if (closed)
+                return undefined;
+            await this.readable();
+        }
+    }
+    /** Reads the next frame and decodes it as a UTF-8 string. */
+    async readString() {
+        const frame = await this.readFrame();
+        return frame ? new TextDecoder().decode(frame) : undefined;
+    }
+    /** Reads the next frame and parses it as JSON. */
+    async readJson() {
+        const frame = await this.readString();
+        return frame ? JSON.parse(frame) : undefined;
+    }
+    /** Reads the next frame and decodes it as a one-byte boolean. */
+    async readBool() {
+        const frame = await this.readFrame();
+        return frame ? frame[0] === 1 : undefined;
+    }
+    /** Closes the group, optionally with an error to abort readers. */
+    close(abort) {
+        this.#state.closed.set(abort ?? true);
+    }
+}
+//# sourceMappingURL=group.js.map

package/group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"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","sourcesContent":["import { Signal } from \"@moq/signals\";\n\n/** Reactive backing state for a {@link Group}: buffered frames, a closed flag, and the running frame count. */\n/** A buffered frame: its payload plus any raw MOQ Object Properties bytes. */\ninterface BufferedFrame {\n\tdata: Uint8Array;\n\textensions?: Uint8Array;\n}\n\nclass GroupState {\n\tframes = new Signal<BufferedFrame[]>([]);\n\tclosed = new Signal<boolean | Error>(false);\n\ttotal = new Signal<number>(0); // The total number of frames in the group thus far\n}\n\n/** An ordered stream of frames within a track, delivered over a single QUIC stream. */\nexport class Group {\n\t/** Sequence number of this group within its track. */\n\treadonly sequence: number;\n\n\t// Reactive backing state, deliberately private: read through the read* methods so callers can't\n\t// poke the signals directly (and so the internal representation can change).\n\t#state = new GroupState();\n\n\t/** Resolves with the abort error (or undefined) once closed. */\n\treadonly closed: Promise<Error | undefined>;\n\n\tconstructor(sequence: number) {\n\t\tthis.sequence = sequence;\n\n\t\t// Cache the closed promise to avoid recreating it every time.\n\t\tthis.closed = new Promise((resolve) => {\n\t\t\tconst dispose = this.#state.closed.subscribe((closed) => {\n\t\t\t\tif (!closed) return;\n\t\t\t\tresolve(closed instanceof Error ? closed : undefined);\n\t\t\t\tdispose();\n\t\t\t});\n\t\t});\n\t}\n\n\t/**\n\t * Writes a frame to the group.\n\t * @param frame - The frame to write\n\t */\n\twriteFrame(frame: Uint8Array, extensions?: Uint8Array) {\n\t\tif (this.#state.closed.peek()) throw new Error(\"group is closed\");\n\n\t\tthis.#state.frames.mutate((frames) => {\n\t\t\tframes.push({ data: frame, extensions });\n\t\t});\n\n\t\tthis.#state.total.update((total) => total + 1);\n\t}\n\n\t/** Write a string as a single UTF-8 encoded frame. */\n\twriteString(str: string) {\n\t\tthis.writeFrame(new TextEncoder().encode(str));\n\t}\n\n\t/** Write a value as a single JSON-encoded frame. */\n\twriteJson(json: unknown) {\n\t\tthis.writeString(JSON.stringify(json));\n\t}\n\n\t/** Write a boolean as a single one-byte frame. */\n\twriteBool(bool: boolean) {\n\t\tthis.writeFrame(new Uint8Array([bool ? 1 : 0]));\n\t}\n\n\t/** True once no further frames can be read: the group has closed and every buffered frame is read. */\n\tget done(): boolean {\n\t\treturn this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== false;\n\t}\n\n\t/**\n\t * Reads the next already-buffered frame without blocking.\n\t *\n\t * Returns `undefined` when nothing is buffered right now. That is *not* by itself end-of-group:\n\t * check {@link done} to tell \"no frame buffered yet\" (more may arrive) from \"the group finished\".\n\t * Drain a backlog by looping until this returns `undefined`, then branch on {@link done}: if not\n\t * done, {@link readable} resolves when the next frame arrives.\n\t */\n\ttryReadFrame(): Uint8Array | undefined {\n\t\treturn this.tryReadFrameSequence()?.data;\n\t}\n\n\t/** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */\n\ttryReadFrameSequence(): { sequence: number; data: Uint8Array; extensions?: Uint8Array } | undefined {\n\t\tconst frames = this.#state.frames.peek();\n\t\tconst frame = frames.shift();\n\t\tif (frame === undefined) return undefined;\n\t\treturn { sequence: this.#state.total.peek() - frames.length - 1, data: frame.data, extensions: frame.extensions };\n\t}\n\n\t/**\n\t * Resolves once {@link readFrame} would not block: a frame is buffered, or the group has closed.\n\t * Always settles (never hangs), so on a finished group it resolves immediately; pair it with\n\t * {@link done} to avoid re-waiting on a group that has nothing left.\n\t *\n\t * Lets a caller fold \"this group has a frame\" into a larger wait (e.g. racing it against a new\n\t * group arriving) without touching the group's internal signals.\n\t */\n\tasync readable(): Promise<void> {\n\t\tfor (;;) {\n\t\t\tif (this.#state.frames.peek().length > 0) return;\n\t\t\tif (this.#state.closed.peek()) return;\n\t\t\tawait Signal.race(this.#state.frames, this.#state.closed);\n\t\t}\n\t}\n\n\t/**\n\t * Reads the next frame from the group.\n\t * @returns A promise that resolves to the next frame or undefined\n\t */\n\tasync readFrame(): Promise<Uint8Array | undefined> {\n\t\treturn (await this.readFrameSequence())?.data;\n\t}\n\n\t/** Reads the next frame along with its sequence number within the group. */\n\tasync readFrameSequence(): Promise<{ sequence: number; data: Uint8Array; extensions?: Uint8Array } | undefined> {\n\t\tfor (;;) {\n\t\t\tconst next = this.tryReadFrameSequence();\n\t\t\tif (next) return next;\n\n\t\t\t// Drain buffered frames before observing the close, so a closed group still yields them.\n\t\t\tconst closed = this.#state.closed.peek();\n\t\t\tif (closed instanceof Error) throw closed;\n\t\t\tif (closed) return undefined;\n\n\t\t\tawait this.readable();\n\t\t}\n\t}\n\n\t/** Reads the next frame and decodes it as a UTF-8 string. */\n\tasync readString(): Promise<string | undefined> {\n\t\tconst frame = await this.readFrame();\n\t\treturn frame ? new TextDecoder().decode(frame) : undefined;\n\t}\n\n\t/** Reads the next frame and parses it as JSON. */\n\tasync readJson(): Promise<unknown | undefined> {\n\t\tconst frame = await this.readString();\n\t\treturn frame ? JSON.parse(frame) : undefined;\n\t}\n\n\t/** Reads the next frame and decodes it as a one-byte boolean. */\n\tasync readBool(): Promise<boolean | undefined> {\n\t\tconst frame = await this.readFrame();\n\t\treturn frame ? frame[0] === 1 : undefined;\n\t}\n\n\t/** Closes the group, optionally with an error to abort readers. */\n\tclose(abort?: Error) {\n\t\tthis.#state.closed.set(abort ?? true);\n\t}\n}\n"]}

package/group.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=group.test.d.ts.map

package/group.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.test.d.ts","sourceRoot":"","sources":["../src/group.test.ts"],"names":[],"mappings":""}

package/group.test.js

@@ -0,0 +1,66 @@
+/* @ts-self-types="./group.test.d.ts" */
+import { expect, test } from "bun:test";
+import { Group } from "./group.js";
+const dec = new TextDecoder();
+test("tryReadFrame drains buffered frames then returns undefined", () => {
+    const group = new Group(0);
+    group.writeString("a");
+    group.writeString("b");
+    expect(dec.decode(group.tryReadFrame())).toBe("a");
+    expect(dec.decode(group.tryReadFrame())).toBe("b");
+    // Nothing buffered: undefined, and the group is not closed so this is not end-of-group.
+    expect(group.tryReadFrame()).toBeUndefined();
+});
+test("tryReadFrameSequence reports per-frame sequence numbers", () => {
+    const group = new Group(7);
+    group.writeString("a");
+    group.writeString("b");
+    expect(group.tryReadFrameSequence()).toEqual({ sequence: 0, data: new TextEncoder().encode("a") });
+    expect(group.tryReadFrameSequence()).toEqual({ sequence: 1, data: new TextEncoder().encode("b") });
+    expect(group.tryReadFrameSequence()).toBeUndefined();
+});
+test("done distinguishes a finished group from one that is merely empty", () => {
+    const group = new Group(0);
+    // Open and empty: not done (more frames may arrive), and tryReadFrame is undefined.
+    expect(group.tryReadFrame()).toBeUndefined();
+    expect(group.done).toBe(false);
+    group.writeString("a");
+    // Buffered but closed: still not done until the frame is drained.
+    group.close();
+    expect(group.done).toBe(false);
+    group.tryReadFrame();
+    // Drained and closed: now done.
+    expect(group.tryReadFrame()).toBeUndefined();
+    expect(group.done).toBe(true);
+});
+test("readable resolves once a frame is buffered", async () => {
+    const group = new Group(0);
+    // No frame yet: readable() must stay pending for an empty, open group.
+    const readable = group.readable();
+    let settled = false;
+    void readable.then(() => {
+        settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    // Writing makes it resolve.
+    group.writeString("hi");
+    await readable; // must not hang
+    expect(dec.decode(group.tryReadFrame())).toBe("hi");
+});
+test("readable resolves once the group closes, even with nothing buffered", async () => {
+    const group = new Group(0);
+    const readable = group.readable();
+    group.close();
+    await readable; // resolves on close so callers don't wait forever
+    expect(group.tryReadFrame()).toBeUndefined();
+});
+test("buffered frames are still readable after the group closes", async () => {
+    const group = new Group(0);
+    group.writeString("a");
+    group.close();
+    // Closing doesn't discard buffered frames; the blocking reader drains them before ending.
+    expect(await group.readString()).toBe("a");
+    expect(await group.readFrame()).toBeUndefined();
+});
+//# sourceMappingURL=group.test.js.map

package/group.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.test.js","sourceRoot":"","sources":["../src/group.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { expect, test } from \"bun:test\";\nimport { Group } from \"./group.ts\";\n\nconst dec = new TextDecoder();\n\ntest(\"tryReadFrame drains buffered frames then returns undefined\", () => {\n\tconst group = new Group(0);\n\tgroup.writeString(\"a\");\n\tgroup.writeString(\"b\");\n\n\texpect(dec.decode(group.tryReadFrame())).toBe(\"a\");\n\texpect(dec.decode(group.tryReadFrame())).toBe(\"b\");\n\t// Nothing buffered: undefined, and the group is not closed so this is not end-of-group.\n\texpect(group.tryReadFrame()).toBeUndefined();\n});\n\ntest(\"tryReadFrameSequence reports per-frame sequence numbers\", () => {\n\tconst group = new Group(7);\n\tgroup.writeString(\"a\");\n\tgroup.writeString(\"b\");\n\n\texpect(group.tryReadFrameSequence()).toEqual({ sequence: 0, data: new TextEncoder().encode(\"a\") });\n\texpect(group.tryReadFrameSequence()).toEqual({ sequence: 1, data: new TextEncoder().encode(\"b\") });\n\texpect(group.tryReadFrameSequence()).toBeUndefined();\n});\n\ntest(\"done distinguishes a finished group from one that is merely empty\", () => {\n\tconst group = new Group(0);\n\t// Open and empty: not done (more frames may arrive), and tryReadFrame is undefined.\n\texpect(group.tryReadFrame()).toBeUndefined();\n\texpect(group.done).toBe(false);\n\n\tgroup.writeString(\"a\");\n\t// Buffered but closed: still not done until the frame is drained.\n\tgroup.close();\n\texpect(group.done).toBe(false);\n\n\tgroup.tryReadFrame();\n\t// Drained and closed: now done.\n\texpect(group.tryReadFrame()).toBeUndefined();\n\texpect(group.done).toBe(true);\n});\n\ntest(\"readable resolves once a frame is buffered\", async () => {\n\tconst group = new Group(0);\n\t// No frame yet: readable() must stay pending for an empty, open group.\n\tconst readable = group.readable();\n\tlet settled = false;\n\tvoid readable.then(() => {\n\t\tsettled = true;\n\t});\n\tawait Promise.resolve();\n\texpect(settled).toBe(false);\n\n\t// Writing makes it resolve.\n\tgroup.writeString(\"hi\");\n\tawait readable; // must not hang\n\texpect(dec.decode(group.tryReadFrame())).toBe(\"hi\");\n});\n\ntest(\"readable resolves once the group closes, even with nothing buffered\", async () => {\n\tconst group = new Group(0);\n\tconst readable = group.readable();\n\tgroup.close();\n\tawait readable; // resolves on close so callers don't wait forever\n\texpect(group.tryReadFrame()).toBeUndefined();\n});\n\ntest(\"buffered frames are still readable after the group closes\", async () => {\n\tconst group = new Group(0);\n\tgroup.writeString(\"a\");\n\tgroup.close();\n\n\t// Closing doesn't discard buffered frames; the blocking reader drains them before ending.\n\texpect(await group.readString()).toBe(\"a\");\n\texpect(await group.readFrame()).toBeUndefined();\n});\n"]}

package/ietf/adapter.d.ts

@@ -0,0 +1,65 @@
+import { Stream } from "../stream";
+import { type IetfVersion } from "./version";
+/**
+ * Interface for opening outgoing bidi streams and allocating request IDs.
+ * Implemented by both ControlStreamAdapter (v14-v16) and NativeSession (v17).
+ */
+export interface Session {
+    openBi(): Stream | Promise<Stream>;
+    openNativeBi?(): Promise<Stream>;
+    acceptBi(): Promise<Stream | undefined>;
+    nextRequestId(): Promise<bigint | undefined>;
+    close?(): void;
+    readonly version: IetfVersion;
+}
+/**
+ * v17 native session — thin wrapper around WebTransport.
+ * Each request gets its own real bidi stream; no control stream multiplexing.
+ */
+export declare class NativeSession implements Session {
+    #private;
+    readonly version: IetfVersion;
+    constructor(quic: WebTransport, version: IetfVersion);
+    openBi(): Promise<Stream>;
+    acceptBi(): Promise<Stream | undefined>;
+    nextRequestId(): Promise<bigint | undefined>;
+}
+/**
+ * Converts v14-v16 control stream multiplexing into virtual bidi streams.
+ *
+ * Reads control messages, classifies them, and routes to virtual Stream objects.
+ * Each request/response pair gets its own virtual Stream, making all versions
+ * look like v17's stream-per-request model.
+ */
+export declare class ControlStreamAdapter implements Session {
+    #private;
+    readonly version: IetfVersion;
+    constructor(quic: WebTransport, controlStream: Stream, version: IetfVersion, maxRequestId: bigint);
+    /**
+     * Accept the next incoming virtual bidi stream.
+     * Blocks until a new request arrives on the control stream.
+     */
+    acceptBi(): Promise<Stream | undefined>;
+    /**
+     * Open an outgoing virtual bidi stream.
+     * Buffers writes until the first full message is available, parses the
+     * requestId (and namespace for PublishNamespace), self-registers, then
+     * flushes. Subsequent writes go directly to the control stream.
+     */
+    openBi(): Stream;
+    /**
+     * Open a real WebTransport bidi stream (for v16 SubscribeNamespace).
+     */
+    openNativeBi(): Promise<Stream>;
+    /**
+     * Allocate the next request ID, blocking if flow control limit reached.
+     */
+    nextRequestId(): Promise<bigint | undefined>;
+    /**
+     * Main run loop — reads control stream messages and routes to virtual streams.
+     * Must be called after construction. Runs until the control stream closes.
+     */
+    run(): Promise<void>;
+    close(): void;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/ietf/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ietf/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,MAAM,EAAe,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,cAAc,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,YAAY,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,OAAO;;IAG5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B,YAAY,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAGnD;IAEK,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAE9B;IAEK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE5C;IAEK,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAIjD;CACD;AAmBD;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,OAAO;;IAQnD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAyB9B,YAAY,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAQhG;IAED;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS5C;IAED;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAsDf;IAED;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAEpC;IAED;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAYjD;IAED;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAmDzB;IAwYD,KAAK,SA6BJ;CACD"}