@norskvideo/moq-net 0.1.8 → 0.2.1

package/group.js

@@ -5,36 +5,27 @@
  * @module
  */
 import { Once, Signal } from "@norskvideo/moq-signals";
+import { FrameTooLarge, GroupTooLarge, TooFarBehind } from "./error.js";
+import { hooks } from "./internal.js";
 import { Timestamp } from "./time.js";
-/** Maximum bytes of frames cached in a group before old frames are evicted from the front. */
+/** Maximum bytes of frames in a group. A write that would exceed this aborts with {@link GroupTooLarge}. */
 export const MAX_GROUP_CACHE_BYTES = 32 * 1024 * 1024;
-/** Maximum number of frames cached in a group before old frames are evicted from the front. */
-export const MAX_GROUP_FRAMES = 1024;
-/**
- * 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 class Lagged extends Error {
-    constructor() {
-        super("lagged: frames were evicted before being read");
-        this.name = "Lagged";
-    }
-}
+/** Maximum number of frames in a group. 8192 is the largest legal group; the 8193rd write is {@link GroupTooLarge}. */
+export const MAX_GROUP_FRAMES = 8192;
 /** Reactive backing state shared by the group producer and one consumer. */
 class GroupState {
     sequence;
     frames = new Signal([]);
     closed = new Once();
     total = new Signal(0); // The total number of frames in the group thus far
-    // Absolute sequence of the frame at the front of `frames`, advanced by a read and by an
-    // eviction alike: the sequence the next read returns.
+    // Absolute sequence of the frame at the front of `frames`, advanced by a read: the
+    // sequence the next read returns.
     start = 0;
-    // One past the newest frame the cache cap evicted before it could be read, or 0 when
-    // none was. A read that wanted a frame below it has a gap, so it throws Lagged rather
-    // than skipping silently; a read that starts above it never asked for the missing
-    // frames, so it proceeds.
-    evicted = 0;
     cacheBytes = 0;
+    // The first frame's timestamp, retained after reads.
+    timestamp;
+    // The newest frame's timestamp: where a reader that has taken every frame sits.
+    latest;
     constructor(sequence) {
         this.sequence = sequence;
     }
@@ -42,17 +33,11 @@ class GroupState {
 function appendFrame(state, frame) {
     if (state.closed.peek() !== undefined)
         throw new Error("group is closed");
+    state.timestamp ??= frame.timestamp;
+    state.latest = frame.timestamp;
     state.cacheBytes += frame.payload.byteLength;
     state.frames.mutate((frames) => {
         frames.push(frame);
-        while (frames.length > MAX_GROUP_FRAMES || state.cacheBytes > MAX_GROUP_CACHE_BYTES) {
-            const evicted = frames.shift();
-            if (!evicted)
-                break;
-            state.cacheBytes -= evicted.payload.byteLength;
-            state.start++;
-            state.evicted = state.start;
-        }
     });
     state.total.update((total) => total + 1);
 }
@@ -70,10 +55,21 @@ export class Producer {
     // cancel an abandoned download; a group can stay open indefinitely (a catalog or JSON stream),
     // so this is what stops a reader-less fetch instead of the stream ending on its own.
     #used = new Signal(false);
+    // When the group was created or last written. Retention ages a group from this,
+    // not from its creation, so a group still being filled is never reclaimed.
+    #activity = performance.now();
     constructor(sequence) {
         this.#state = new GroupState(sequence);
         this.sequence = sequence;
     }
+    /**
+     * When the group was created or last written, in `performance.now()` milliseconds.
+     *
+     * @internal Track retention only.
+     */
+    get activity() {
+        return this.#activity;
+    }
     /**
      * 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.
@@ -95,10 +91,11 @@ export class Producer {
      */
     mirror() {
         const dst = new GroupState(this.sequence);
+        dst.timestamp = this.#state.timestamp;
+        dst.latest = this.#state.latest;
         for (const frame of this.#state.frames.peek())
             appendFrame(dst, frame);
         dst.start = this.#state.start;
-        dst.evicted = this.#state.evicted;
         // The replay only covers what is still buffered, so the count has to come from the
         // source: it is what names a frame's absolute sequence, and what a publisher reads
         // to resolve the live edge.
@@ -146,6 +143,30 @@ export class Producer {
     }
     /** Writes a frame to the group. */
     writeFrame(frame) {
+        // Closed first: a write after a clean close at the cap would otherwise take the
+        // overflow path, wipe committed frames, and leave readers with an empty success.
+        if (this.#state.closed.peek() !== undefined)
+            throw new Error("group is closed");
+        // A frame past the cache cap would make the group exceed its budget by itself, so
+        // accepting it would report success for a write nothing can ever read. Rust rejects
+        // it up front with `Error::FrameTooLarge`; do the same rather than silently dropping it.
+        if (frame.payload.byteLength > MAX_GROUP_CACHE_BYTES)
+            throw new FrameTooLarge();
+        if (this.#state.total.peek() >= MAX_GROUP_FRAMES ||
+            this.#state.cacheBytes + frame.payload.byteLength > MAX_GROUP_CACHE_BYTES) {
+            const err = new GroupTooLarge();
+            this.#state.frames.set([]);
+            this.#state.cacheBytes = 0;
+            if (this.#mirrors) {
+                for (const mirror of this.#mirrors) {
+                    mirror.frames.set([]);
+                    mirror.cacheBytes = 0;
+                }
+            }
+            this.close(err);
+            throw err;
+        }
+        this.#activity = performance.now();
         appendFrame(this.#state, frame);
         if (this.#mirrors) {
             for (const mirror of this.#mirrors) {
@@ -187,6 +208,65 @@ export class Producer {
     }
 }
 let makeConsumer;
+// A consumer can finish from its own expiry verdict or from the shared group state. Keep
+// one stable public handle while letting peek() observe either source synchronously, before
+// signal subscribers run in the next microtask.
+class CombinedClosed {
+    #preferred;
+    #source;
+    #sourceCleanReady;
+    #value = new Once();
+    #dispose;
+    constructor(preferred, source, sourceCleanReady) {
+        this.#preferred = preferred;
+        this.#source = source;
+        this.#sourceCleanReady = sourceCleanReady;
+        if (this.#sync())
+            return;
+        const dispose = [preferred.changed(() => this.#sync()), source.changed(() => this.#sync())];
+        this.#dispose = () => {
+            for (const close of dispose)
+                close();
+        };
+    }
+    #sync() {
+        if (this.#value.peek() !== undefined)
+            return true;
+        const preferred = this.#preferred.peek();
+        const source = this.#source.peek();
+        const value = preferred !== undefined
+            ? preferred
+            : source instanceof Error || this.#sourceCleanReady()
+                ? source
+                : undefined;
+        if (value === undefined)
+            return false;
+        this.#value.set(value);
+        this.#dispose?.();
+        this.#dispose = undefined;
+        return true;
+    }
+    refresh() {
+        this.#sync();
+    }
+    peek() {
+        this.#sync();
+        return this.#value.peek();
+    }
+    changed(fn) {
+        this.#sync();
+        return fn ? this.#value.changed(fn) : this.#value.changed();
+    }
+    subscribe(fn) {
+        this.#sync();
+        return this.#value.subscribe(fn);
+    }
+    // biome-ignore lint/suspicious/noThenProperty: CombinedClosed is intentionally awaitable.
+    then(onFulfilled, onRejected) {
+        this.#sync();
+        return this.#value.then(onFulfilled, onRejected);
+    }
+}
 /**
  * The read side of an ordered stream of frames within a track.
  *
@@ -199,42 +279,160 @@ export class Consumer {
     /** Sequence number of this group within its track. */
     sequence;
     #state;
+    #expiry;
+    // Sticky verdicts, set once. `#ended` is a drained group the budget gave up on,
+    // which is indistinguishable from one that ended: nothing was lost, so it reads as
+    // the end of the group. `#terminal` is a failure, including a budget that gave up
+    // while content was still unread.
+    #ended = false;
+    #terminal;
+    #verdict = new Once();
+    #closed;
+    #pendingFrames = 0;
     constructor(state) {
         this.#state = state;
         this.sequence = state.sequence;
     }
     /**
-     * Settles once the group closes: `null` on a clean close, or the abort {@link Error}.
+     * Settles when this consumer reaches a terminal state: `null` after a clean close has no
+     * unread or in-flight frames, or the terminal {@link Error}.
      * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
      */
     get closed() {
-        return this.#state.closed;
+        this.#closed ??= new CombinedClosed(this.#verdict, this.#state.closed, () => this.#state.frames.peek().length === 0 && this.#pendingFrames === 0);
+        return this.#closed;
     }
     static {
         makeConsumer = (state) => new Consumer(state);
+        hooks.groupTimestamp = (group) => group.#state.timestamp;
+        hooks.groupLatest = (group) => group.#state.latest;
+        hooks.expireGroup = (group, expiry) => {
+            group.#expiry = expiry;
+        };
+        hooks.guardGroup = (group, operation) => group.#guard(operation);
+        hooks.readGroupFrame = (group, from) => group.#readFramePosition(true, from);
+        hooks.evictGroup = (group) => {
+            group.#evict();
+        };
+    }
+    // Evaluate the drift budget for a read that has nothing buffered and is about to
+    // wait. A group with frames in hand is always drained: the budget bounds a group
+    // that has stalled while the live edge moved on, not a reader slower than the wire.
+    // Returns true if a verdict was just reached, so the caller re-checks.
+    //
+    // `unread` is for a caller that still holds content the reader has not seen (a
+    // publisher part-way through writing a frame): giving up there is a truncation, so
+    // it fails rather than ending.
+    #expire(unread = false) {
+        if (this.#terminal || this.#ended)
+            return false;
+        if (this.#state.closed.peek() instanceof Error)
+            return false;
+        if (!this.#expiry?.expired())
+            return false;
+        if (unread) {
+            this.#terminal = new Error("group exceeded the subscription max age budget");
+        }
+        else {
+            this.#ended = true;
+        }
+        if (this.#verdict.peek() === undefined)
+            this.#verdict.set(this.#terminal ?? null);
+        return true;
+    }
+    // Takes a thunk rather than a started promise, so a group already past its budget
+    // never begins the write: an abandoned write would reject later with no handler.
+    #guard(operation) {
+        this.#expire(true);
+        if (this.#terminal)
+            return Promise.reject(this.#terminal);
+        const expiry = this.#expiry;
+        if (!expiry)
+            return operation();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const disposes = [];
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                for (const dispose of disposes)
+                    dispose();
+                fn();
+            };
+            const check = () => {
+                this.#expire(true);
+                if (this.#terminal) {
+                    const error = this.#terminal;
+                    finish(() => reject(error));
+                }
+            };
+            for (const changed of expiry.changed)
+                disposes.push(changed.subscribe(check));
+            operation().then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+            check();
+        });
     }
-    #readBufferedFrame() {
+    #evict() {
         const frames = this.#state.frames.peek();
-        const frame = frames.shift();
-        if (!frame)
+        if (frames.length > 0) {
+            // Unread content is going away either way. If the budget had already given up
+            // on this group that is the more specific reason, so ask it first; otherwise
+            // the reader simply lagged behind the cache.
+            this.#expire(true);
+            if (!this.#terminal && !this.#ended) {
+                this.#terminal = new TooFarBehind();
+                if (this.#verdict.peek() === undefined)
+                    this.#verdict.set(this.#terminal);
+            }
+        }
+        if (frames.length > 0) {
+            this.#state.start += frames.length;
+        }
+        this.#state.cacheBytes = 0;
+        this.#state.frames.set([]);
+    }
+    async #changed() {
+        if (!this.#expiry) {
+            await Signal.race(this.#state.frames, this.#state.closed);
+            return;
+        }
+        await Signal.race(this.#state.frames, this.#state.closed, ...this.#expiry.changed);
+    }
+    #readBufferedFrame(pending = false) {
+        const frames = this.#state.frames.peek();
+        const buffered = frames.shift();
+        if (!buffered)
             return undefined;
-        this.#state.cacheBytes -= frame.payload.byteLength;
-        return { sequence: this.#state.start++, frame };
+        const sequence = this.#state.start++;
+        if (pending)
+            this.#pendingFrames++;
+        let completed = false;
+        return {
+            sequence,
+            frame: buffered,
+            complete: () => {
+                if (completed)
+                    return;
+                completed = true;
+                if (pending)
+                    this.#pendingFrames--;
+                this.#closed?.refresh();
+            },
+        };
     }
     /** 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() !== undefined;
+        return (this.#terminal !== undefined ||
+            this.#ended ||
+            (this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== undefined));
     }
     /** True once the group has been closed, regardless of whether buffered frames remain unread. Synchronous complement to the {@link closed} promise. */
     get isClosed() {
-        return this.#state.closed.peek() !== undefined;
-    }
-    /** True if frames were evicted from the front of this group before being read. */
-    get skipped() {
-        return this.#state.evicted > 0;
+        return this.#terminal !== undefined || this.#ended || this.#state.closed.peek() !== undefined;
     }
     /**
-     * How many frames the group has held, including any already read or evicted.
+     * How many frames the group has held, including any already read.
      *
      * 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.
@@ -250,24 +448,36 @@ export class Consumer {
      * end-of-group: check {@link done} to tell "no frame buffered yet" from "finished".
      */
     tryReadFrame() {
+        if (this.#terminal || this.#ended)
+            return undefined;
         const read = this.#readBufferedFrame();
+        read?.complete();
         return read?.frame;
     }
     /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */
     tryReadFrameSequence() {
+        if (this.#terminal || this.#ended)
+            return undefined;
         const read = this.#readBufferedFrame();
         if (!read)
             return undefined;
+        read.complete();
         return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };
     }
     /** Resolves once {@link readFrame} would not block. */
     async readable() {
         for (;;) {
+            if (this.#terminal || this.#ended)
+                return;
             if (this.#state.frames.peek().length > 0)
                 return;
-            if (this.#state.closed.peek() !== undefined)
+            if (this.#state.closed.peek() !== undefined) {
+                this.#closed?.refresh();
                 return;
-            await Signal.race(this.#state.frames, this.#state.closed);
+            }
+            if (this.#expire())
+                return;
+            await this.#changed();
         }
     }
     /**
@@ -275,18 +485,36 @@ export class Consumer {
      * Treat the returned frame bytes as read-only; they are shared with other consumers.
      */
     async readFrame() {
+        return (await this.#readFramePosition())?.frame;
+    }
+    async #readFramePosition(pending = false, from = 0) {
         for (;;) {
-            if (this.#state.evicted > 0)
-                throw new Lagged();
-            const read = this.#readBufferedFrame();
-            if (read)
-                return read.frame;
+            if (this.#terminal)
+                throw this.#terminal;
+            if (this.#ended)
+                return;
+            const read = this.#readBufferedFrame(pending);
+            if (read) {
+                if (read.sequence < from) {
+                    read.complete();
+                    continue;
+                }
+                if (!pending)
+                    read.complete();
+                return read;
+            }
             const closed = this.#state.closed.peek();
             if (closed instanceof Error)
                 throw closed;
-            if (closed !== undefined)
+            if (closed !== undefined) {
+                this.#closed?.refresh();
                 return;
-            await Signal.race(this.#state.frames, this.#state.closed);
+            }
+            // Nothing buffered and the group is still open: this wait is the stall the
+            // drift budget bounds, and the only place it applies.
+            if (this.#expire())
+                continue;
+            await this.#changed();
         }
     }
     /**
@@ -294,23 +522,10 @@ export class Consumer {
      * Treat the returned frame bytes as read-only; they are shared with other consumers.
      */
     async readFrameSequence(options) {
-        const from = options?.from ?? 0;
-        for (;;) {
-            if (this.#state.evicted > from)
-                throw new Lagged();
-            const read = this.#readBufferedFrame();
-            if (read) {
-                if (read.sequence < from)
-                    continue;
-                return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };
-            }
-            const closed = this.#state.closed.peek();
-            if (closed instanceof Error)
-                throw closed;
-            if (closed !== undefined)
-                return;
-            await Signal.race(this.#state.frames, this.#state.closed);
-        }
+        const read = await this.#readFramePosition(false, options?.from ?? 0);
+        if (!read)
+            return undefined;
+        return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };
     }
     /** Reads the next frame and decodes its payload as a UTF-8 string. */
     async readString() {

package/group.js.map

@@ -1 +1 @@
-{"version":3,"file":"group.js","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Group role handles: an ordered stream of frames within a track, delivered over one QUIC stream.\n *\n * @module\n */\nimport { type GetPromise, type Getter, Once, Signal } from \"@moq/signals\";\nimport { Timestamp } from \"./time.ts\";\n\n/** Maximum bytes of frames cached in a group before old frames are evicted from the front. */\nexport const MAX_GROUP_CACHE_BYTES = 32 * 1024 * 1024;\n\n/** Maximum number of frames cached in a group before old frames are evicted from the front. */\nexport const MAX_GROUP_FRAMES = 1024;\n\n/**\n * A frame buffered in a group: its presentation {@link Timestamp} and payload bytes.\n *\n * The timestamp carries its own scale, so a track can pick its units; the wire layer\n * converts it into the track's negotiated timescale.\n */\nexport interface Frame {\n\t/** The frame payload. */\n\tpayload: Uint8Array;\n\t/**\n\t * Presentation timestamp. Required: for a payload with no presentation time of its own\n\t * (a JSON catalog, control state) pass {@link Timestamp.now} explicitly.\n\t */\n\ttimestamp: Timestamp;\n}\n\n/** Options for a sequence-aware frame read. */\nexport interface ReadOptions {\n\t/**\n\t * The lowest sequence number the caller wants; defaults to the whole group.\n\t *\n\t * Frames below it are discarded instead of returned, and frames evicted below it are not\n\t * a gap: the read resumes at the next retained frame rather than throwing {@link Lagged}.\n\t * An eviction at or above it still throws, because the caller asked for that frame.\n\t */\n\tfrom?: number;\n}\n\n/** Immutable group metadata. */\nexport interface Info {\n\t/** Sequence number of this group within its track. */\n\tsequence: number;\n}\n\n/**\n * Thrown by a frame read when the reader fell behind the group's eviction window: frames\n * it had not yet read were dropped to stay under the cache cap, so the stream has a gap.\n */\nexport class Lagged extends Error {\n\tconstructor() {\n\t\tsuper(\"lagged: frames were evicted before being read\");\n\t\tthis.name = \"Lagged\";\n\t}\n}\n\n/** Reactive backing state shared by the group producer and one consumer. */\nclass GroupState {\n\treadonly sequence: number;\n\tframes = new Signal<Frame[]>([]);\n\tclosed = new Once<Error | null>();\n\ttotal = new Signal<number>(0); // The total number of frames in the group thus far\n\n\t// Absolute sequence of the frame at the front of `frames`, advanced by a read and by an\n\t// eviction alike: the sequence the next read returns.\n\tstart = 0;\n\n\t// One past the newest frame the cache cap evicted before it could be read, or 0 when\n\t// none was. A read that wanted a frame below it has a gap, so it throws Lagged rather\n\t// than skipping silently; a read that starts above it never asked for the missing\n\t// frames, so it proceeds.\n\tevicted = 0;\n\n\tcacheBytes = 0;\n\n\tconstructor(sequence: number) {\n\t\tthis.sequence = sequence;\n\t}\n}\n\nfunction appendFrame(state: GroupState, frame: Frame) {\n\tif (state.closed.peek() !== undefined) throw new Error(\"group is closed\");\n\n\tstate.cacheBytes += frame.payload.byteLength;\n\tstate.frames.mutate((frames) => {\n\t\tframes.push(frame);\n\n\t\twhile (frames.length > MAX_GROUP_FRAMES || state.cacheBytes > MAX_GROUP_CACHE_BYTES) {\n\t\t\tconst evicted = frames.shift();\n\t\t\tif (!evicted) break;\n\t\t\tstate.cacheBytes -= evicted.payload.byteLength;\n\t\t\tstate.start++;\n\t\t\tstate.evicted = state.start;\n\t\t}\n\t});\n\n\tstate.total.update((total) => total + 1);\n}\n\n/**\n * The write side of an ordered stream of frames within a track.\n *\n * @public\n */\nexport class Producer {\n\t/** Sequence number of this group within its track. */\n\treadonly sequence: number;\n\n\t#state: GroupState;\n\t#mirrors?: Set<GroupState>;\n\n\t// Whether any mirror reader is attached (see {@link used}). Fetch coalescing watches it to\n\t// cancel an abandoned download; a group can stay open indefinitely (a catalog or JSON stream),\n\t// so this is what stops a reader-less fetch instead of the stream ending on its own.\n\t#used = new Signal<boolean>(false);\n\n\tconstructor(sequence: number) {\n\t\tthis.#state = new GroupState(sequence);\n\t\tthis.sequence = sequence;\n\t}\n\n\t/**\n\t * Settles once the group 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 group. */\n\tconsume(): Consumer {\n\t\treturn makeConsumer(this.#state);\n\t}\n\n\t/**\n\t * Create an independent read handle that receives every frame written here.\n\t *\n\t * Frames written so far are replayed synchronously; later writes and close are teed\n\t * in as they happen.\n\t *\n\t * @internal Track fan-out and fetch coalescing only. Use {@link consume} instead.\n\t */\n\tmirror(): Consumer {\n\t\tconst dst = new GroupState(this.sequence);\n\t\tfor (const frame of this.#state.frames.peek()) appendFrame(dst, frame);\n\t\tdst.start = this.#state.start;\n\t\tdst.evicted = this.#state.evicted;\n\t\t// The replay only covers what is still buffered, so the count has to come from the\n\t\t// source: it is what names a frame's absolute sequence, and what a publisher reads\n\t\t// to resolve the live edge.\n\t\tdst.total.set(this.#state.total.peek());\n\n\t\tconst closed = this.#state.closed.peek();\n\t\tif (closed !== undefined) {\n\t\t\tdst.closed.set(closed);\n\t\t\treturn makeConsumer(dst);\n\t\t}\n\n\t\tthis.#mirrors ??= new Set();\n\t\tthis.#mirrors.add(dst);\n\t\tthis.#used.set(true);\n\n\t\t// Track this mirror's close eagerly (not just lazily on the next write) so demand drops the\n\t\t// moment the last reader leaves, letting an abandoned fetch cancel even with no more frames.\n\t\tconst dispose = dst.closed.subscribe((c) => {\n\t\t\tif (c === undefined) return;\n\t\t\tthis.#mirrors?.delete(dst);\n\t\t\tthis.#used.set((this.#mirrors?.size ?? 0) > 0);\n\t\t\tdispose();\n\t\t});\n\n\t\treturn makeConsumer(dst);\n\t}\n\n\t/**\n\t * Whether any mirror reader is currently attached.\n\t *\n\t * Pairs with {@link unused}. Fetch coalescing watches it to cancel a download once every reader\n\t * has gone: a group can stay open indefinitely (a catalog track, a JSON stream), so it can't\n\t * rely on the stream ending on its own.\n\t *\n\t * @internal Track fan-out and fetch coalescing only.\n\t */\n\tget used(): Getter<boolean> {\n\t\treturn this.#used;\n\t}\n\n\t/**\n\t * Resolves once no mirror reader remains (or the group closes).\n\t *\n\t * @internal Track fan-out and fetch coalescing only.\n\t */\n\tasync unused(): Promise<void> {\n\t\twhile (this.#used.peek() && this.#state.closed.peek() === undefined) {\n\t\t\tawait Signal.race(this.#used, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Writes a frame to the group. */\n\twriteFrame(frame: Frame) {\n\t\tappendFrame(this.#state, frame);\n\n\t\tif (this.#mirrors) {\n\t\t\tfor (const mirror of this.#mirrors) {\n\t\t\t\tif (mirror.closed.peek() !== undefined) this.#mirrors.delete(mirror);\n\t\t\t\telse appendFrame(mirror, frame);\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Write a string as a single UTF-8 encoded frame, stamped with {@link Timestamp.now}. */\n\twriteString(str: string) {\n\t\tthis.writeFrame({ payload: new TextEncoder().encode(str), timestamp: Timestamp.now() });\n\t}\n\n\t/** Write a value as a single JSON-encoded frame, stamped with {@link Timestamp.now}. */\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, stamped with {@link Timestamp.now}. */\n\twriteBool(bool: boolean) {\n\t\tthis.writeFrame({ payload: new Uint8Array([bool ? 1 : 0]), timestamp: Timestamp.now() });\n\t}\n\n\t/** True once the group has been closed. */\n\tget isClosed(): boolean {\n\t\treturn this.#state.closed.peek() !== undefined;\n\t}\n\n\t/** Closes the group, optionally with an error to abort readers. */\n\tclose(abort?: Error) {\n\t\tif (this.#state.closed.peek() !== undefined) return;\n\t\tthis.#state.closed.set(abort ?? null);\n\n\t\tif (this.#mirrors) {\n\t\t\tfor (const mirror of this.#mirrors) {\n\t\t\t\tif (mirror.closed.peek() === undefined) mirror.closed.set(abort ?? null);\n\t\t\t}\n\t\t\tthis.#mirrors.clear();\n\t\t}\n\t}\n}\n\nlet makeConsumer: (state: GroupState) => Consumer;\n\n/**\n * The read side of an ordered stream of frames within a track.\n *\n * Created internally: obtain one from {@link Producer.consume} or a track subscriber's\n * group reads.\n *\n * @public\n */\nexport class Consumer {\n\t/** Sequence number of this group within its track. */\n\treadonly sequence: number;\n\n\t#state: GroupState;\n\n\tprivate constructor(state: GroupState) {\n\t\tthis.#state = state;\n\t\tthis.sequence = state.sequence;\n\t}\n\n\t/**\n\t * Settles once the group 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\tstatic {\n\t\tmakeConsumer = (state) => new Consumer(state);\n\t}\n\n\t#readBufferedFrame(): { sequence: number; frame: Frame } | undefined {\n\t\tconst frames = this.#state.frames.peek();\n\t\tconst frame = frames.shift();\n\t\tif (!frame) return undefined;\n\n\t\tthis.#state.cacheBytes -= frame.payload.byteLength;\n\t\treturn { sequence: this.#state.start++, frame };\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() !== undefined;\n\t}\n\n\t/** True once the group has been closed, regardless of whether buffered frames remain unread. Synchronous complement to the {@link closed} promise. */\n\tget isClosed(): boolean {\n\t\treturn this.#state.closed.peek() !== undefined;\n\t}\n\n\t/** True if frames were evicted from the front of this group before being read. */\n\tget skipped(): boolean {\n\t\treturn this.#state.evicted > 0;\n\t}\n\n\t/**\n\t * How many frames the group has held, including any already read or evicted.\n\t *\n\t * It is also the next frame's sequence number, so `frameCount - 1` names the newest\n\t * frame written so far. A publisher snapshots it to resolve the track's live edge.\n\t */\n\tget frameCount(): number {\n\t\treturn this.#state.total.peek();\n\t}\n\n\t/**\n\t * Reads the next already-buffered frame without blocking.\n\t * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t *\n\t * Returns `undefined` when nothing is buffered right now. That is not by itself\n\t * end-of-group: check {@link done} to tell \"no frame buffered yet\" from \"finished\".\n\t */\n\ttryReadFrame(): Frame | undefined {\n\t\tconst read = this.#readBufferedFrame();\n\t\treturn read?.frame;\n\t}\n\n\t/** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */\n\ttryReadFrameSequence(): ({ sequence: number } & Frame) | undefined {\n\t\tconst read = this.#readBufferedFrame();\n\t\tif (!read) return undefined;\n\t\treturn { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };\n\t}\n\n\t/** Resolves once {@link readFrame} would not block. */\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() !== undefined) 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 * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t */\n\tasync readFrame(): Promise<Frame | undefined> {\n\t\tfor (;;) {\n\t\t\tif (this.#state.evicted > 0) throw new Lagged();\n\n\t\t\tconst read = this.#readBufferedFrame();\n\t\t\tif (read) return read.frame;\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;\n\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 along with its sequence number within the group.\n\t * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t */\n\tasync readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> {\n\t\tconst from = options?.from ?? 0;\n\n\t\tfor (;;) {\n\t\t\tif (this.#state.evicted > from) throw new Lagged();\n\n\t\t\tconst read = this.#readBufferedFrame();\n\t\t\tif (read) {\n\t\t\t\tif (read.sequence < from) continue;\n\t\t\t\treturn { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };\n\t\t\t}\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;\n\n\t\t\tawait Signal.race(this.#state.frames, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Reads the next frame and decodes its payload 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.payload) : undefined;\n\t}\n\n\t/** Reads the next frame and parses its payload 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 its payload as a one-byte boolean. */\n\tasync readBool(): Promise<boolean | undefined> {\n\t\tconst frame = await this.readFrame();\n\t\treturn frame ? frame.payload[0] === 1 : undefined;\n\t}\n\n\t/** Closes the group, optionally with an error to abort readers. Idempotent. */\n\tclose(abort?: Error) {\n\t\tif (this.#state.closed.peek() !== undefined) return; // already closed\n\t\tthis.#state.closed.set(abort ?? null);\n\t}\n}\n"]}
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Group role handles: an ordered stream of frames within a track, delivered over one QUIC stream.\n *\n * @module\n */\nimport { type Dispose, type GetPromise, type Getter, Once, Signal } from \"@moq/signals\";\nimport { FrameTooLarge, GroupTooLarge, TooFarBehind } from \"./error.ts\";\nimport { hooks, type ReadGroupFrame } from \"./internal.ts\";\nimport { Timestamp } from \"./time.ts\";\n\n/** Maximum bytes of frames in a group. A write that would exceed this aborts with {@link GroupTooLarge}. */\nexport const MAX_GROUP_CACHE_BYTES = 32 * 1024 * 1024;\n\n/** Maximum number of frames in a group. 8192 is the largest legal group; the 8193rd write is {@link GroupTooLarge}. */\nexport const MAX_GROUP_FRAMES = 8192;\n\n/**\n * A frame buffered in a group: its presentation {@link Timestamp} and payload bytes.\n *\n * The timestamp carries its own scale, so a track can pick its units; the wire layer\n * converts it into the track's negotiated timescale.\n */\nexport interface Frame {\n\t/** The frame payload. */\n\tpayload: Uint8Array;\n\t/**\n\t * Presentation timestamp. Required: for a payload with no presentation time of its own\n\t * (a JSON catalog, control state) pass {@link Timestamp.now} explicitly.\n\t */\n\ttimestamp: Timestamp;\n}\n\n/** Options for a sequence-aware frame read. */\nexport interface ReadOptions {\n\t/**\n\t * The lowest sequence number the caller wants; defaults to the whole group.\n\t *\n\t * Frames below it are discarded instead of returned. The group still starts at frame 0,\n\t * so this is a reader filter, not a missing prefix.\n\t */\n\tfrom?: number;\n}\n\n/** Immutable group metadata. */\nexport interface Info {\n\t/** Sequence number of this group within its track. */\n\tsequence: number;\n}\n\n/** Reactive backing state shared by the group producer and one consumer. */\nclass GroupState {\n\treadonly sequence: number;\n\tframes = new Signal<Frame[]>([]);\n\tclosed = new Once<Error | null>();\n\ttotal = new Signal<number>(0); // The total number of frames in the group thus far\n\n\t// Absolute sequence of the frame at the front of `frames`, advanced by a read: the\n\t// sequence the next read returns.\n\tstart = 0;\n\n\tcacheBytes = 0;\n\t// The first frame's timestamp, retained after reads.\n\ttimestamp?: Timestamp;\n\t// The newest frame's timestamp: where a reader that has taken every frame sits.\n\tlatest?: Timestamp;\n\n\tconstructor(sequence: number) {\n\t\tthis.sequence = sequence;\n\t}\n}\n\nfunction appendFrame(state: GroupState, frame: Frame) {\n\tif (state.closed.peek() !== undefined) throw new Error(\"group is closed\");\n\n\tstate.timestamp ??= frame.timestamp;\n\tstate.latest = frame.timestamp;\n\tstate.cacheBytes += frame.payload.byteLength;\n\tstate.frames.mutate((frames) => {\n\t\tframes.push(frame);\n\t});\n\n\tstate.total.update((total) => total + 1);\n}\n\n/**\n * The write side of an ordered stream of frames within a track.\n *\n * @public\n */\nexport class Producer {\n\t/** Sequence number of this group within its track. */\n\treadonly sequence: number;\n\n\t#state: GroupState;\n\t#mirrors?: Set<GroupState>;\n\n\t// Whether any mirror reader is attached (see {@link used}). Fetch coalescing watches it to\n\t// cancel an abandoned download; a group can stay open indefinitely (a catalog or JSON stream),\n\t// so this is what stops a reader-less fetch instead of the stream ending on its own.\n\t#used = new Signal<boolean>(false);\n\n\t// When the group was created or last written. Retention ages a group from this,\n\t// not from its creation, so a group still being filled is never reclaimed.\n\t#activity = performance.now();\n\n\tconstructor(sequence: number) {\n\t\tthis.#state = new GroupState(sequence);\n\t\tthis.sequence = sequence;\n\t}\n\n\t/**\n\t * When the group was created or last written, in `performance.now()` milliseconds.\n\t *\n\t * @internal Track retention only.\n\t */\n\tget activity(): number {\n\t\treturn this.#activity;\n\t}\n\n\t/**\n\t * Settles once the group 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 group. */\n\tconsume(): Consumer {\n\t\treturn makeConsumer(this.#state);\n\t}\n\n\t/**\n\t * Create an independent read handle that receives every frame written here.\n\t *\n\t * Frames written so far are replayed synchronously; later writes and close are teed\n\t * in as they happen.\n\t *\n\t * @internal Track fan-out and fetch coalescing only. Use {@link consume} instead.\n\t */\n\tmirror(): Consumer {\n\t\tconst dst = new GroupState(this.sequence);\n\t\tdst.timestamp = this.#state.timestamp;\n\t\tdst.latest = this.#state.latest;\n\t\tfor (const frame of this.#state.frames.peek()) appendFrame(dst, frame);\n\t\tdst.start = this.#state.start;\n\t\t// The replay only covers what is still buffered, so the count has to come from the\n\t\t// source: it is what names a frame's absolute sequence, and what a publisher reads\n\t\t// to resolve the live edge.\n\t\tdst.total.set(this.#state.total.peek());\n\n\t\tconst closed = this.#state.closed.peek();\n\t\tif (closed !== undefined) {\n\t\t\tdst.closed.set(closed);\n\t\t\treturn makeConsumer(dst);\n\t\t}\n\n\t\tthis.#mirrors ??= new Set();\n\t\tthis.#mirrors.add(dst);\n\t\tthis.#used.set(true);\n\n\t\t// Track this mirror's close eagerly (not just lazily on the next write) so demand drops the\n\t\t// moment the last reader leaves, letting an abandoned fetch cancel even with no more frames.\n\t\tconst dispose = dst.closed.subscribe((c) => {\n\t\t\tif (c === undefined) return;\n\t\t\tthis.#mirrors?.delete(dst);\n\t\t\tthis.#used.set((this.#mirrors?.size ?? 0) > 0);\n\t\t\tdispose();\n\t\t});\n\n\t\treturn makeConsumer(dst);\n\t}\n\n\t/**\n\t * Whether any mirror reader is currently attached.\n\t *\n\t * Pairs with {@link unused}. Fetch coalescing watches it to cancel a download once every reader\n\t * has gone: a group can stay open indefinitely (a catalog track, a JSON stream), so it can't\n\t * rely on the stream ending on its own.\n\t *\n\t * @internal Track fan-out and fetch coalescing only.\n\t */\n\tget used(): Getter<boolean> {\n\t\treturn this.#used;\n\t}\n\n\t/**\n\t * Resolves once no mirror reader remains (or the group closes).\n\t *\n\t * @internal Track fan-out and fetch coalescing only.\n\t */\n\tasync unused(): Promise<void> {\n\t\twhile (this.#used.peek() && this.#state.closed.peek() === undefined) {\n\t\t\tawait Signal.race(this.#used, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Writes a frame to the group. */\n\twriteFrame(frame: Frame) {\n\t\t// Closed first: a write after a clean close at the cap would otherwise take the\n\t\t// overflow path, wipe committed frames, and leave readers with an empty success.\n\t\tif (this.#state.closed.peek() !== undefined) throw new Error(\"group is closed\");\n\t\t// A frame past the cache cap would make the group exceed its budget by itself, so\n\t\t// accepting it would report success for a write nothing can ever read. Rust rejects\n\t\t// it up front with `Error::FrameTooLarge`; do the same rather than silently dropping it.\n\t\tif (frame.payload.byteLength > MAX_GROUP_CACHE_BYTES) throw new FrameTooLarge();\n\t\tif (\n\t\t\tthis.#state.total.peek() >= MAX_GROUP_FRAMES ||\n\t\t\tthis.#state.cacheBytes + frame.payload.byteLength > MAX_GROUP_CACHE_BYTES\n\t\t) {\n\t\t\tconst err = new GroupTooLarge();\n\t\t\tthis.#state.frames.set([]);\n\t\t\tthis.#state.cacheBytes = 0;\n\t\t\tif (this.#mirrors) {\n\t\t\t\tfor (const mirror of this.#mirrors) {\n\t\t\t\t\tmirror.frames.set([]);\n\t\t\t\t\tmirror.cacheBytes = 0;\n\t\t\t\t}\n\t\t\t}\n\t\t\tthis.close(err);\n\t\t\tthrow err;\n\t\t}\n\n\t\tthis.#activity = performance.now();\n\t\tappendFrame(this.#state, frame);\n\n\t\tif (this.#mirrors) {\n\t\t\tfor (const mirror of this.#mirrors) {\n\t\t\t\tif (mirror.closed.peek() !== undefined) this.#mirrors.delete(mirror);\n\t\t\t\telse appendFrame(mirror, frame);\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Write a string as a single UTF-8 encoded frame, stamped with {@link Timestamp.now}. */\n\twriteString(str: string) {\n\t\tthis.writeFrame({ payload: new TextEncoder().encode(str), timestamp: Timestamp.now() });\n\t}\n\n\t/** Write a value as a single JSON-encoded frame, stamped with {@link Timestamp.now}. */\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, stamped with {@link Timestamp.now}. */\n\twriteBool(bool: boolean) {\n\t\tthis.writeFrame({ payload: new Uint8Array([bool ? 1 : 0]), timestamp: Timestamp.now() });\n\t}\n\n\t/** True once the group has been closed. */\n\tget isClosed(): boolean {\n\t\treturn this.#state.closed.peek() !== undefined;\n\t}\n\n\t/** Closes the group, optionally with an error to abort readers. */\n\tclose(abort?: Error) {\n\t\tif (this.#state.closed.peek() !== undefined) return;\n\t\tthis.#state.closed.set(abort ?? null);\n\n\t\tif (this.#mirrors) {\n\t\t\tfor (const mirror of this.#mirrors) {\n\t\t\t\tif (mirror.closed.peek() === undefined) mirror.closed.set(abort ?? null);\n\t\t\t}\n\t\t\tthis.#mirrors.clear();\n\t\t}\n\t}\n}\n\nlet makeConsumer: (state: GroupState) => Consumer;\n\n// A consumer can finish from its own expiry verdict or from the shared group state. Keep\n// one stable public handle while letting peek() observe either source synchronously, before\n// signal subscribers run in the next microtask.\nclass CombinedClosed implements GetPromise<Error | null> {\n\t#preferred: Once<Error | null>;\n\t#source: Once<Error | null>;\n\t#sourceCleanReady: () => boolean;\n\t#value = new Once<Error | null>();\n\t#dispose?: Dispose;\n\n\tconstructor(preferred: Once<Error | null>, source: Once<Error | null>, sourceCleanReady: () => boolean) {\n\t\tthis.#preferred = preferred;\n\t\tthis.#source = source;\n\t\tthis.#sourceCleanReady = sourceCleanReady;\n\t\tif (this.#sync()) return;\n\n\t\tconst dispose = [preferred.changed(() => this.#sync()), source.changed(() => this.#sync())];\n\t\tthis.#dispose = () => {\n\t\t\tfor (const close of dispose) close();\n\t\t};\n\t}\n\n\t#sync(): boolean {\n\t\tif (this.#value.peek() !== undefined) return true;\n\t\tconst preferred = this.#preferred.peek();\n\t\tconst source = this.#source.peek();\n\t\tconst value =\n\t\t\tpreferred !== undefined\n\t\t\t\t? preferred\n\t\t\t\t: source instanceof Error || this.#sourceCleanReady()\n\t\t\t\t\t? source\n\t\t\t\t\t: undefined;\n\t\tif (value === undefined) return false;\n\n\t\tthis.#value.set(value);\n\t\tthis.#dispose?.();\n\t\tthis.#dispose = undefined;\n\t\treturn true;\n\t}\n\n\trefresh() {\n\t\tthis.#sync();\n\t}\n\n\tpeek(): Error | null | undefined {\n\t\tthis.#sync();\n\t\treturn this.#value.peek();\n\t}\n\n\tchanged(): Promise<Error | null | undefined>;\n\tchanged(fn: (value: Error | null | undefined) => void): Dispose;\n\tchanged(fn?: (value: Error | null | undefined) => void): Promise<Error | null | undefined> | Dispose {\n\t\tthis.#sync();\n\t\treturn fn ? this.#value.changed(fn) : this.#value.changed();\n\t}\n\n\tsubscribe(fn: (value: Error | null | undefined) => void): Dispose {\n\t\tthis.#sync();\n\t\treturn this.#value.subscribe(fn);\n\t}\n\n\t// biome-ignore lint/suspicious/noThenProperty: CombinedClosed is intentionally awaitable.\n\tthen<R1 = Error | null, R2 = never>(\n\t\tonFulfilled?: ((value: Error | null) => R1 | PromiseLike<R1>) | null,\n\t\tonRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,\n\t): PromiseLike<R1 | R2> {\n\t\tthis.#sync();\n\t\treturn this.#value.then(onFulfilled, onRejected);\n\t}\n}\n\n/**\n * The read side of an ordered stream of frames within a track.\n *\n * Created internally: obtain one from {@link Producer.consume} or a track subscriber's\n * group reads.\n *\n * @public\n */\nexport class Consumer {\n\t/** Sequence number of this group within its track. */\n\treadonly sequence: number;\n\n\t#state: GroupState;\n\t#expiry?: { expired: () => boolean; changed: readonly Getter<unknown>[] };\n\t// Sticky verdicts, set once. `#ended` is a drained group the budget gave up on,\n\t// which is indistinguishable from one that ended: nothing was lost, so it reads as\n\t// the end of the group. `#terminal` is a failure, including a budget that gave up\n\t// while content was still unread.\n\t#ended = false;\n\t#terminal?: Error;\n\t#verdict = new Once<Error | null>();\n\t#closed?: CombinedClosed;\n\t#pendingFrames = 0;\n\n\tprivate constructor(state: GroupState) {\n\t\tthis.#state = state;\n\t\tthis.sequence = state.sequence;\n\t}\n\n\t/**\n\t * Settles when this consumer reaches a terminal state: `null` after a clean close has no\n\t * unread or in-flight frames, or the terminal {@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\tthis.#closed ??= new CombinedClosed(\n\t\t\tthis.#verdict,\n\t\t\tthis.#state.closed,\n\t\t\t() => this.#state.frames.peek().length === 0 && this.#pendingFrames === 0,\n\t\t);\n\t\treturn this.#closed;\n\t}\n\n\tstatic {\n\t\tmakeConsumer = (state) => new Consumer(state);\n\t\thooks.groupTimestamp = (group) => group.#state.timestamp;\n\t\thooks.groupLatest = (group) => group.#state.latest;\n\t\thooks.expireGroup = (group, expiry) => {\n\t\t\tgroup.#expiry = expiry;\n\t\t};\n\t\thooks.guardGroup = (group, operation) => group.#guard(operation);\n\t\thooks.readGroupFrame = (group, from) => group.#readFramePosition(true, from);\n\t\thooks.evictGroup = (group) => {\n\t\t\tgroup.#evict();\n\t\t};\n\t}\n\n\t// Evaluate the drift budget for a read that has nothing buffered and is about to\n\t// wait. A group with frames in hand is always drained: the budget bounds a group\n\t// that has stalled while the live edge moved on, not a reader slower than the wire.\n\t// Returns true if a verdict was just reached, so the caller re-checks.\n\t//\n\t// `unread` is for a caller that still holds content the reader has not seen (a\n\t// publisher part-way through writing a frame): giving up there is a truncation, so\n\t// it fails rather than ending.\n\t#expire(unread = false): boolean {\n\t\tif (this.#terminal || this.#ended) return false;\n\t\tif (this.#state.closed.peek() instanceof Error) return false;\n\t\tif (!this.#expiry?.expired()) return false;\n\n\t\tif (unread) {\n\t\t\tthis.#terminal = new Error(\"group exceeded the subscription max age budget\");\n\t\t} else {\n\t\t\tthis.#ended = true;\n\t\t}\n\t\tif (this.#verdict.peek() === undefined) this.#verdict.set(this.#terminal ?? null);\n\t\treturn true;\n\t}\n\n\t// Takes a thunk rather than a started promise, so a group already past its budget\n\t// never begins the write: an abandoned write would reject later with no handler.\n\t#guard<T>(operation: () => Promise<T>): Promise<T> {\n\t\tthis.#expire(true);\n\t\tif (this.#terminal) return Promise.reject(this.#terminal);\n\t\tconst expiry = this.#expiry;\n\t\tif (!expiry) return operation();\n\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tlet settled = false;\n\t\t\tconst disposes: Dispose[] = [];\n\t\t\tconst finish = (fn: () => void) => {\n\t\t\t\tif (settled) return;\n\t\t\t\tsettled = true;\n\t\t\t\tfor (const dispose of disposes) dispose();\n\t\t\t\tfn();\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\tthis.#expire(true);\n\t\t\t\tif (this.#terminal) {\n\t\t\t\t\tconst error = this.#terminal;\n\t\t\t\t\tfinish(() => reject(error));\n\t\t\t\t}\n\t\t\t};\n\n\t\t\tfor (const changed of expiry.changed) disposes.push(changed.subscribe(check));\n\t\t\toperation().then(\n\t\t\t\t(value) => finish(() => resolve(value)),\n\t\t\t\t(error: unknown) => finish(() => reject(error)),\n\t\t\t);\n\t\t\tcheck();\n\t\t});\n\t}\n\n\t#evict() {\n\t\tconst frames = this.#state.frames.peek();\n\t\tif (frames.length > 0) {\n\t\t\t// Unread content is going away either way. If the budget had already given up\n\t\t\t// on this group that is the more specific reason, so ask it first; otherwise\n\t\t\t// the reader simply lagged behind the cache.\n\t\t\tthis.#expire(true);\n\t\t\tif (!this.#terminal && !this.#ended) {\n\t\t\t\tthis.#terminal = new TooFarBehind();\n\t\t\t\tif (this.#verdict.peek() === undefined) this.#verdict.set(this.#terminal);\n\t\t\t}\n\t\t}\n\t\tif (frames.length > 0) {\n\t\t\tthis.#state.start += frames.length;\n\t\t}\n\t\tthis.#state.cacheBytes = 0;\n\t\tthis.#state.frames.set([]);\n\t}\n\n\tasync #changed(): Promise<void> {\n\t\tif (!this.#expiry) {\n\t\t\tawait Signal.race(this.#state.frames, this.#state.closed);\n\t\t\treturn;\n\t\t}\n\t\tawait Signal.race(this.#state.frames, this.#state.closed, ...this.#expiry.changed);\n\t}\n\n\t#readBufferedFrame(pending = false): ReadGroupFrame | undefined {\n\t\tconst frames = this.#state.frames.peek();\n\t\tconst buffered = frames.shift();\n\t\tif (!buffered) return undefined;\n\n\t\tconst sequence = this.#state.start++;\n\t\tif (pending) this.#pendingFrames++;\n\t\tlet completed = false;\n\t\treturn {\n\t\t\tsequence,\n\t\t\tframe: buffered,\n\t\t\tcomplete: () => {\n\t\t\t\tif (completed) return;\n\t\t\t\tcompleted = true;\n\t\t\t\tif (pending) this.#pendingFrames--;\n\t\t\t\tthis.#closed?.refresh();\n\t\t\t},\n\t\t};\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 (\n\t\t\tthis.#terminal !== undefined ||\n\t\t\tthis.#ended ||\n\t\t\t(this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== undefined)\n\t\t);\n\t}\n\n\t/** True once the group has been closed, regardless of whether buffered frames remain unread. Synchronous complement to the {@link closed} promise. */\n\tget isClosed(): boolean {\n\t\treturn this.#terminal !== undefined || this.#ended || this.#state.closed.peek() !== undefined;\n\t}\n\n\t/**\n\t * How many frames the group has held, including any already read.\n\t *\n\t * It is also the next frame's sequence number, so `frameCount - 1` names the newest\n\t * frame written so far. A publisher snapshots it to resolve the track's live edge.\n\t */\n\tget frameCount(): number {\n\t\treturn this.#state.total.peek();\n\t}\n\n\t/**\n\t * Reads the next already-buffered frame without blocking.\n\t * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t *\n\t * Returns `undefined` when nothing is buffered right now. That is not by itself\n\t * end-of-group: check {@link done} to tell \"no frame buffered yet\" from \"finished\".\n\t */\n\ttryReadFrame(): Frame | undefined {\n\t\tif (this.#terminal || this.#ended) return undefined;\n\t\tconst read = this.#readBufferedFrame();\n\t\tread?.complete();\n\t\treturn read?.frame;\n\t}\n\n\t/** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */\n\ttryReadFrameSequence(): ({ sequence: number } & Frame) | undefined {\n\t\tif (this.#terminal || this.#ended) return undefined;\n\t\tconst read = this.#readBufferedFrame();\n\t\tif (!read) return undefined;\n\t\tread.complete();\n\t\treturn { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };\n\t}\n\n\t/** Resolves once {@link readFrame} would not block. */\n\tasync readable(): Promise<void> {\n\t\tfor (;;) {\n\t\t\tif (this.#terminal || this.#ended) return;\n\t\t\tif (this.#state.frames.peek().length > 0) return;\n\t\t\tif (this.#state.closed.peek() !== undefined) {\n\t\t\t\tthis.#closed?.refresh();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (this.#expire()) return;\n\t\t\tawait this.#changed();\n\t\t}\n\t}\n\n\t/**\n\t * Reads the next frame from the group.\n\t * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t */\n\tasync readFrame(): Promise<Frame | undefined> {\n\t\treturn (await this.#readFramePosition())?.frame;\n\t}\n\n\tasync #readFramePosition(pending = false, from = 0): Promise<ReadGroupFrame | undefined> {\n\t\tfor (;;) {\n\t\t\tif (this.#terminal) throw this.#terminal;\n\t\t\tif (this.#ended) return;\n\n\t\t\tconst read = this.#readBufferedFrame(pending);\n\t\t\tif (read) {\n\t\t\t\tif (read.sequence < from) {\n\t\t\t\t\tread.complete();\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (!pending) read.complete();\n\t\t\t\treturn read;\n\t\t\t}\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) {\n\t\t\t\tthis.#closed?.refresh();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Nothing buffered and the group is still open: this wait is the stall the\n\t\t\t// drift budget bounds, and the only place it applies.\n\t\t\tif (this.#expire()) continue;\n\t\t\tawait this.#changed();\n\t\t}\n\t}\n\n\t/**\n\t * Reads the next frame along with its sequence number within the group.\n\t * Treat the returned frame bytes as read-only; they are shared with other consumers.\n\t */\n\tasync readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> {\n\t\tconst read = await this.#readFramePosition(false, options?.from ?? 0);\n\t\tif (!read) return undefined;\n\t\treturn { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp };\n\t}\n\n\t/** Reads the next frame and decodes its payload 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.payload) : undefined;\n\t}\n\n\t/** Reads the next frame and parses its payload 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 its payload as a one-byte boolean. */\n\tasync readBool(): Promise<boolean | undefined> {\n\t\tconst frame = await this.readFrame();\n\t\treturn frame ? frame.payload[0] === 1 : undefined;\n\t}\n\n\t/** Closes the group, optionally with an error to abort readers. Idempotent. */\n\tclose(abort?: Error) {\n\t\tif (this.#state.closed.peek() !== undefined) return; // already closed\n\t\tthis.#state.closed.set(abort ?? null);\n\t}\n}\n"]}