@norskvideo/moq-net 0.1.2 → 0.1.4

package/track.js

@@ -1,69 +1,491 @@
 /* @ts-self-types="./track.d.ts" */
-import { Signal } from "@norskvideo/moq-signals";
-import { Group } from "./group.js";
-/** Reactive backing state for a {@link Track}: buffered groups, a closed flag, and the subscription priority. */
-export class TrackState {
+/**
+ * Track role handles: a live stream of groups (and best-effort datagrams) within a broadcast.
+ *
+ * @module
+ */
+import { Once, Signal } from "@norskvideo/moq-signals";
+import { Producer as GroupProducer, Lagged } from "./group.js";
+import { hooks } from "./internal.js";
+import { Timescale } from "./time.js";
+/** Default {@link Info.latencyMax} window (milliseconds) when the publisher does not set one. */
+export const DEFAULT_LATENCY_MAX_MS = 5000;
+/**
+ * How long (milliseconds) a datagram stays in the per-subscriber buffer before it is dropped.
+ *
+ * Datagrams are a best-effort send buffer, not a replay cache (unlike groups): only the last few
+ * tens of milliseconds are kept, so a consumer that stalls loses stale datagrams instead of
+ * replaying them. Mirrors the Rust `MAX_DATAGRAM_AGE`.
+ */
+const MAX_DATAGRAM_AGE_MS = 50;
+/**
+ * Sanity cap on a datagram payload: the QUIC DATAGRAM frame ceiling. The real limit is
+ * per-hop (the negotiated transport datagram size minus a small header) and oversize
+ * datagrams are dropped there; a payload above this cap could never fit anywhere.
+ */
+const MAX_DATAGRAM_BYTES = 65535;
+/** Fill in any unset {@link Info} fields with their defaults. */
+export function infoDefaults(info = {}) {
+    return {
+        timescale: info.timescale ?? Timescale.MILLI,
+        latencyMax: info.latencyMax ?? DEFAULT_LATENCY_MAX_MS,
+        priority: info.priority ?? 0,
+        ordered: info.ordered ?? false,
+    };
+}
+// Materialize the defaults at the model boundary so every layer observes a complete
+// subscription rather than interpreting an omitted field differently.
+function subscriptionDefaults(subscription = {}) {
+    return {
+        priority: subscription.priority ?? 0,
+        ordered: subscription.ordered ?? false,
+        latencyMax: subscription.latencyMax ?? 0,
+        startGroup: subscription.startGroup,
+        endGroup: subscription.endGroup,
+    };
+}
+// Aggregate the preferences of every live subscriber, matching Rust's Subscription::poll_combined.
+function combineSubscriptions(states) {
+    let combined;
+    for (const state of states) {
+        const subscription = state.update.peek();
+        if (!subscription)
+            continue;
+        if (!combined) {
+            combined = { ...subscription };
+            continue;
+        }
+        combined.priority = Math.max(combined.priority ?? 0, subscription.priority ?? 0);
+        combined.ordered = (combined.ordered ?? false) && (subscription.ordered ?? false);
+        combined.latencyMax = Math.max(combined.latencyMax ?? 0, subscription.latencyMax ?? 0);
+        if (subscription.startGroup !== undefined) {
+            combined.startGroup =
+                combined.startGroup === undefined
+                    ? subscription.startGroup
+                    : Math.min(combined.startGroup, subscription.startGroup);
+        }
+        if (combined.endGroup === undefined || subscription.endGroup === undefined) {
+            combined.endGroup = undefined;
+        }
+        else {
+            combined.endGroup = Math.max(combined.endGroup, subscription.endGroup);
+        }
+    }
+    return combined;
+}
+/**
+ * A request for a track the peer wants, yielded by `Broadcast.Producer.requested`.
+ *
+ * Created internally by the broadcast when a subscription (or info lookup) needs a track
+ * served; answer it with {@link accept} or {@link reject}.
+ *
+ * @public
+ */
+export class Request {
+    /** The requested track name. */
+    name;
+    #producer;
+    #sequences;
+    constructor(options) {
+        this.name = options.name;
+        this.#producer = options.producer;
+        this.#sequences = options.sequences;
+    }
+    static {
+        hooks.makeRequest = (options) => new Request(options);
+    }
+    /** The aggregate subscription requested for this track. */
+    get subscription() {
+        return this.#producer.subscription.peek() ?? subscriptionDefaults();
+    }
+    /** The subscriber's priority for this track. */
+    get priority() {
+        return this.subscription.priority ?? 0;
+    }
+    /** Accept the request, committing the track's immutable {@link Info}. */
+    accept(info = {}) {
+        bindProducer(this.name, this.#producer, this.#sequences);
+        return this.#producer.accept(info);
+    }
+    /** Reject the request, closing the track optionally with an error. */
+    reject(err) {
+        this.#producer.close(err);
+    }
+}
+/**
+ * A lazy handle to a track on a consumed broadcast.
+ *
+ * @public
+ */
+export class Consumer {
+    /** The track name. */
+    name;
+    #broadcast;
+    constructor(name, broadcast) {
+        this.name = name;
+        this.#broadcast = broadcast;
+    }
+    /** Open a live subscription to the track. */
+    subscribe(options) {
+        return this.#broadcast.subscribe(this.name, options);
+    }
+    /** Fetch the track's immutable publisher properties without subscribing. */
+    info() {
+        return this.#broadcast.resolveTrackInfo(this.name);
+    }
+    /** Fetch a single group by sequence without holding a live subscription. */
+    fetchGroup(sequence, options) {
+        return this.#broadcast.fetchGroup(this.name, sequence, options);
+    }
+}
+// The shared state behind a Producer / Subscriber pair. Package-internal
+// wiring, unexported so it never appears in the published type declarations.
+class TrackState {
+    /** The producer fanning into this sink, so a subscriber can mint a sibling of itself. */
+    producer;
     groups = new Signal([]);
-    closed = new Signal(false);
-    priority = new Signal(undefined);
+    /** Best-effort datagram channel, parallel to {@link groups}; an age-evicted send buffer per subscriber. */
+    datagrams = new Signal([]);
+    latest;
+    closed = new Once();
+    update;
+    /** Resolved once the producer commits the immutable properties. */
+    info = new Signal(undefined);
+    constructor(subscription) {
+        this.update = new Signal(subscription === undefined ? undefined : subscriptionDefaults(subscription));
+    }
+}
+// Settle a track state's closed Once. Idempotent: Once.set throws on a second settle, and a
+// Producer closing its sinks races the Subscriber closing itself (the sink is only removed from
+// #sinks a microtask later, via the closed subscription below).
+function closeTrackState(state, abort) {
+    if (state.closed.peek() !== undefined)
+        return false;
+    state.closed.set(abort ?? null);
+    return true;
+}
+// Resolve the track's immutable publisher properties, or reject if it closes first.
+// On a producer this resolves once info is committed (at accept time); on a consumer
+// once the wire layer commits the TRACK_INFO it received (lite-05+) or defaults (older
+// drafts), so awaiting it never yields a placeholder.
+async function resolveInfo(state) {
+    for (;;) {
+        const info = state.info.peek();
+        if (info)
+            return info;
+        const closed = state.closed.peek();
+        if (closed instanceof Error)
+            throw closed;
+        if (closed !== undefined)
+            throw new Error("track closed before info was known");
+        await Signal.race(state.info, state.closed);
+    }
+}
+function bindProducer(name, producer, sequences) {
+    let shared = sequences.get(name);
+    if (!shared) {
+        shared = { next: 0 };
+        sequences.set(name, shared);
+    }
+    bindProducerSequence(producer, shared);
 }
-/** A live stream of groups within a broadcast, identified by name. */
-export class Track {
-    /** Name of this track within its broadcast. */
+let bindProducerSequence;
+// Constructs a Subscriber from within this module without exposing a public
+// constructor that would leak the unexported TrackState. Assigned in the class's
+// static block.
+let makeSubscriber;
+/**
+ * The write side of a track, mirroring the Rust `Producer`.
+ *
+ * A producer is a fan-out source: every {@link subscribe} (including each wire
+ * subscription the publisher serves from it) gets an independent
+ * {@link Subscriber} that receives a full copy of the groups, each with its own
+ * read cursor. Groups are mirrored into every live subscriber and retained for the
+ * track's `latencyMax` window so a late subscriber replays the recent groups.
+ *
+ * Obtained from {@link Request.accept} (the wire asks the application for a track to
+ * serve) or constructed directly for an in-process track.
+ */
+export class Producer {
+    /** The track name. */
     name;
-    /** Reactive backing state. */
-    state = new TrackState();
-    #next;
-    #nextSequence = 0;
-    /** Resolves with the abort error (or undefined) once closed. */
-    closed;
+    // The producer's own state is the source of truth (info/closed); subscribers
+    // read mirrored sinks, never this state directly.
+    #state = new TrackState();
+    #sequence = { next: 0 };
+    // Recently written source groups, retained for replay to late subscribers and
+    // pruned once closed and older than the cache window. Each entry tracks the mirror
+    // it handed to every sink so eviction can drop them too: otherwise a slow consumer
+    // that never reads would pin old groups (and their frame bytes) forever.
+    #cache = [];
+    // One independent downstream state per live subscriber.
+    #sinks = new Set();
+    // Whether any subscriber is currently attached. Exposed as {@link used}; the consumer wire
+    // watches it to tear down an idle upstream, and a publisher can watch it for on-demand capture.
+    #used = new Signal(false);
     constructor(name) {
         this.name = name;
-        this.closed = new Promise((resolve) => {
-            const dispose = this.state.closed.subscribe((closed) => {
-                if (!closed)
+    }
+    static {
+        bindProducerSequence = (producer, sequence) => {
+            producer.#sequence = sequence;
+        };
+    }
+    /**
+     * Resolve this track's immutable publisher properties, committed at accept time.
+     * Rejects if the track is closed before the properties are known.
+     */
+    info() {
+        return resolveInfo(this.#state);
+    }
+    /**
+     * Settles once the track closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
+     */
+    get closed() {
+        return this.#state.closed;
+    }
+    /**
+     * The aggregate subscription across live subscribers, or `undefined` when there are none.
+     * The wire layer watches this to emit SUBSCRIBE_UPDATE.
+     */
+    get subscription() {
+        return this.#state.update;
+    }
+    /** Commit the immutable publisher properties, resolving {@link info}. Returns `this`. */
+    accept(info = {}) {
+        const resolved = infoDefaults(info);
+        this.#state.info.set(resolved);
+        // Propagate to any sink handed out before accept (the on-demand path).
+        for (const sink of this.#sinks)
+            sink.info.set(resolved);
+        return this;
+    }
+    /** An independent {@link Subscriber} receiving a full copy of this track's groups. */
+    subscribe(options = {}) {
+        const sink = new TrackState(options);
+        this.#addSink(sink);
+        return makeSubscriber(this.name, sink);
+    }
+    /**
+     * Whether the track currently has any subscribers.
+     *
+     * Watch it (`effect.get` / `.peek()`) to drive on-demand work: a publisher can start and stop
+     * capture with demand, and the consumer wire watches it to tear an idle upstream subscription
+     * down instead of downloading to nobody. Pairs with {@link unused}. Mirrors the Rust `Demand`.
+     */
+    get used() {
+        return this.#used;
+    }
+    /** Resolves once the track has no subscribers (or has closed). Await it to react to demand ending. */
+    async unused() {
+        while (this.#used.peek() && this.#state.closed.peek() === undefined) {
+            await Signal.race(this.#used, this.#state.closed);
+        }
+    }
+    // Register a downstream sink: seed its info, replay the retained window, and (while
+    // the track is open) mirror future groups into it. A late subscriber to a closed
+    // track still drains the buffered groups before seeing the end.
+    #addSink(sink) {
+        sink.producer = this;
+        const info = this.#state.info.peek();
+        if (info)
+            sink.info.set(info);
+        const closed = this.#state.closed.peek();
+        if (closed === undefined) {
+            this.#sinks.add(sink);
+            this.#used.set(true);
+            // Forward subscription updates from the sink's Subscriber to the producer's own
+            // state, which the wire layer (or the serving application) watches.
+            const forward = sink.update.subscribe(() => this.#updateSubscription());
+            this.#updateSubscription();
+            // Drop the sink once its consumer goes away, closing its mirrors so source
+            // groups stop teeing into them, so a long-lived producer doesn't leak. This
+            // covers mirrors already handed out via recvGroup (no longer in sink.groups)
+            // by closing them through the cache's per-sink tracking.
+            const dispose = sink.closed.subscribe((c) => {
+                if (c === undefined)
                     return;
-                resolve(closed instanceof Error ? closed : undefined);
+                const abort = c instanceof Error ? c : undefined;
+                forward();
+                this.#sinks.delete(sink);
+                this.#updateSubscription();
+                for (const entry of this.#cache) {
+                    const mirror = entry.mirrors.get(sink);
+                    if (mirror) {
+                        mirror.close(abort);
+                        entry.mirrors.delete(sink);
+                    }
+                }
+                for (const group of sink.groups.peek())
+                    group.close(abort);
                 dispose();
+                // Update demand: once the last subscriber leaves, the consumer wire (watching
+                // {@link unused}) tears the upstream down instead of downloading to nobody.
+                this.#used.set(this.#sinks.size > 0);
             });
+        }
+        this.#prune();
+        for (const entry of this.#cache)
+            this.#mirror(entry, sink);
+        if (closed !== undefined)
+            closeTrackState(sink, closed instanceof Error ? closed : undefined);
+    }
+    // Recompute from every live sink because an update or close can narrow as well as widen
+    // the aggregate. The wire layer observes this signal and emits SUBSCRIBE_UPDATE.
+    #updateSubscription() {
+        this.#state.update.set(combineSubscriptions(this.#sinks));
+    }
+    // Mirror a cached source group into a sink. The mirror fills synchronously as the
+    // source is written and keeps its own read cursor; frame bytes are shared by
+    // reference. Tracked on the entry so eviction can drop it from the sink.
+    #mirror(entry, sink) {
+        const dst = entry.group.mirror();
+        entry.mirrors.set(sink, dst);
+        sink.latest = Math.max(sink.latest ?? 0, dst.sequence);
+        sink.groups.mutate((groups) => {
+            groups.push(dst);
+            groups.sort((a, b) => a.sequence - b.sequence);
         });
     }
-    /**
-     * Appends a new group to the track.
-     * @returns A GroupProducer for the new group
-     */
+    // Drop a cached group's mirror from every sink so no consumer can pin it.
+    #evict(entry) {
+        for (const [sink, mirror] of entry.mirrors) {
+            sink.groups.mutate((groups) => {
+                const i = groups.indexOf(mirror);
+                if (i >= 0)
+                    groups.splice(i, 1);
+            });
+            mirror.close();
+        }
+        entry.mirrors.clear();
+    }
+    // Evict cached groups that are closed and older than the cache window.
+    #prune() {
+        const latencyMaxMs = this.#state.info.peek()?.latencyMax ?? DEFAULT_LATENCY_MAX_MS;
+        const cutoff = Date.now() - latencyMaxMs;
+        const retained = [];
+        for (const entry of this.#cache) {
+            if (entry.time > cutoff || entry.group.closed.peek() === undefined) {
+                retained.push(entry);
+                continue;
+            }
+            this.#evict(entry);
+        }
+        this.#cache = retained;
+    }
+    // Retain a source group and fan it out to every live sink.
+    #publish(group) {
+        const entry = { group, time: Date.now(), mirrors: new Map() };
+        this.#cache.push(entry);
+        this.#prune();
+        for (const sink of this.#sinks)
+            this.#mirror(entry, sink);
+    }
+    /** Append a new group with the next sequence number. */
     appendGroup() {
-        if (this.state.closed.peek())
+        if (this.#state.closed.peek() !== undefined)
             throw new Error("track is closed");
-        const group = new Group(this.#next ?? 0);
-        this.#next = group.sequence + 1;
-        this.state.groups.mutate((groups) => {
-            groups.push(group);
-            groups.sort((a, b) => a.sequence - b.sequence);
-        });
+        const sequence = this.#sequence;
+        const group = new GroupProducer(sequence.next);
+        sequence.next = group.sequence + 1;
+        this.#publish(group);
         return group;
     }
     /**
-     * Inserts an existing group into the track.
-     * @param group - The group to insert
+     * Insert an existing group into the track.
+     *
+     * Throws on a sequence that is still cached: a live duplicate would fan out to every
+     * subscriber twice. An aborted incarnation is evicted so a fresh group can serve the
+     * sequence again. Best effort (mirrors Rust): nothing remembers a sequence whose cache
+     * entry is already gone, so a long-evicted sequence is accepted as new.
      */
     writeGroup(group) {
-        if (this.state.closed.peek())
+        if (this.#state.closed.peek() !== undefined)
             throw new Error("track is closed");
-        // Only advance #next upward (for appendGroup auto-increment).
-        if (group.sequence >= (this.#next ?? 0)) {
-            this.#next = group.sequence + 1;
+        const existing = this.#cache.findIndex((entry) => entry.group.sequence === group.sequence);
+        if (existing >= 0) {
+            const entry = this.#cache[existing];
+            if (!(entry.group.closed.peek() instanceof Error)) {
+                throw new Error(`duplicate group: sequence=${group.sequence}`);
+            }
+            this.#evict(entry);
+            this.#cache.splice(existing, 1);
         }
-        this.state.groups.mutate((groups) => {
-            groups.push(group);
-            groups.sort((a, b) => a.sequence - b.sequence);
-        });
+        // Only advance the shared counter upward (for appendGroup auto-increment).
+        const sequence = this.#sequence;
+        if (group.sequence >= sequence.next) {
+            sequence.next = group.sequence + 1;
+        }
+        this.#publish(group);
+    }
+    // Fan a datagram out to every live subscriber, dropping the oldest once the ring is full.
+    // Late subscribers do NOT replay old datagrams (best-effort, unlike the group cache).
+    #publishDatagram(datagram) {
+        const now = performance.now();
+        for (const sink of this.#sinks) {
+            sink.datagrams.mutate((list) => {
+                list.push({ datagram, time: now });
+                // Drop anything older than the send-buffer window.
+                while (list.length > 0 && now - list[0].time > MAX_DATAGRAM_AGE_MS)
+                    list.shift();
+            });
+        }
+    }
+    /**
+     * Append a datagram with the next sequence number, returning the assigned sequence.
+     *
+     * A datagram is delivered best-effort over a single QUIC datagram, parallel to the track's
+     * groups but drawing from the same sequence namespace (interleaving with {@link appendGroup}
+     * never reuses a number). The payload must fit the negotiated transport datagram size minus
+     * a small header; an oversize payload is dropped at each hop (there is no group fallback), so
+     * keep datagram payloads small (e.g. a single audio frame). Datagrams are never delivered
+     * over IETF moq-transport or stream-only transports (the WebSocket fallback). A payload over
+     * 65535 bytes (the QUIC datagram frame ceiling) throws. An origin publisher uses this; a
+     * relay preserving upstream numbering uses {@link writeDatagram}.
+     */
+    appendDatagram(timestamp, payload) {
+        if (this.#state.closed.peek() !== undefined)
+            throw new Error("track is closed");
+        if (payload.byteLength > MAX_DATAGRAM_BYTES)
+            throw new Error("datagram payload too large");
+        const counter = this.#sequence;
+        const sequence = counter.next;
+        counter.next = sequence + 1;
+        this.#publishDatagram({ sequence, timestamp, payload });
+        return sequence;
     }
     /**
-     * Appends a frame to the track in its own group.
+     * Write a datagram with an explicit sequence number.
      *
-     * @param frame - The frame to append
+     * Preserves the supplied sequence (advancing the shared counter if needed) so a relay can
+     * forward a datagram without renumbering it. The size limits of {@link appendDatagram}
+     * apply. Most origin publishers want {@link appendDatagram} instead.
      */
+    writeDatagram(datagram) {
+        if (this.#state.closed.peek() !== undefined)
+            throw new Error("track is closed");
+        if (datagram.payload.byteLength > MAX_DATAGRAM_BYTES)
+            throw new Error("datagram payload too large");
+        const sequence = this.#sequence;
+        if (datagram.sequence >= sequence.next) {
+            sequence.next = datagram.sequence + 1;
+        }
+        this.#publishDatagram(datagram);
+    }
+    /** Close the track and every subscriber, mirroring the abort to their groups. Idempotent. */
+    close(abort) {
+        closeTrackState(this.#state, abort);
+        for (const { group } of this.#cache)
+            group.close(abort);
+        for (const sink of this.#sinks) {
+            for (const group of sink.groups.peek())
+                group.close(abort);
+            closeTrackState(sink, abort);
+        }
+        this.#sinks.clear();
+    }
+    /** Append a frame as its own single-frame group. */
     writeFrame(frame) {
         const group = this.appendGroup();
         group.writeFrame(frame);
@@ -87,101 +509,299 @@ export class Track {
         group.writeBool(bool);
         group.close();
     }
+}
+/**
+ * The read side of a live track subscription, mirroring the Rust `Subscriber`.
+ *
+ * Obtained from `Broadcast.Consumer.subscribe` / `Track.Consumer.subscribe`, or from
+ * {@link Producer.subscribe} for an in-process track. Reads the groups a
+ * {@link Producer} on the same underlying state writes.
+ */
+export class Subscriber {
+    /** The track name. */
+    name;
+    #state;
+    #nextSequence = 0;
+    #cursor = new Signal({ start: 0 });
+    constructor(name, state) {
+        this.name = name;
+        this.#state = state;
+    }
+    static {
+        makeSubscriber = (name, state) => new Subscriber(name, state);
+    }
     /**
-     * Receive the next group available on this track, in arrival order.
+     * Resolve this track's immutable publisher properties.
      *
-     * Groups may arrive out of order or with gaps due to network conditions.
-     * Use {@link nextGroupOrdered} if you need groups in sequence order,
-     * skipping those that arrive too late.
+     * Resolves once the wire layer commits the TRACK_INFO it received (lite-05+) or
+     * defaults (older drafts), so awaiting it never yields a placeholder. Rejects if
+     * the track is closed before the properties are known (e.g. a rejected subscription).
+     */
+    info() {
+        return resolveInfo(this.#state);
+    }
+    /** Settles once the track closes; see {@link Producer.closed}. */
+    get closed() {
+        return this.#state.closed;
+    }
+    /** This subscriber's current options, including defaults and the last {@link update}. */
+    get subscription() {
+        return this.#state.update;
+    }
+    /** Return the latest group sequence observed on this track, if any. */
+    latest() {
+        return this.#state.latest;
+    }
+    /**
+     * The newest frame this track has produced, or `undefined` while it has none.
+     *
+     * Read from the groups buffered for this subscriber, so nothing is consumed. A newest
+     * group that has no frames yet falls back to the newest older group that does. It
+     * reads as `undefined` once the newest group has been evicted or received: what is
+     * left can no longer say where the edge is.
+     */
+    largest() {
+        const latest = this.#state.latest;
+        if (latest === undefined)
+            return undefined;
+        const groups = this.#state.groups.peek();
+        const newest = groups[groups.length - 1];
+        if (!newest || newest.sequence !== latest)
+            return undefined;
+        for (let i = groups.length - 1; i >= 0; i--) {
+            const count = groups[i].frameCount;
+            if (count > 0)
+                return { group: groups[i].sequence, frame: count - 1 };
+        }
+        return undefined;
+    }
+    /**
+     * An independent subscriber to the same track, with its own cursor and its own replay of
+     * the retained window.
+     *
+     * Reads here do not consume anything this one would deliver, which is what lets a
+     * publisher read the cache alongside the cursor it is serving from. Resolving the track
+     * again through the broadcast would not do: a dynamic serve is one request per peer
+     * subscription, so that mints a second producer the application has to answer separately.
+     *
+     * @internal Wire layers only.
+     */
+    fork(options) {
+        const producer = this.#state.producer;
+        if (!producer)
+            throw new Error("track has no producer to fork from");
+        return producer.subscribe(options);
+    }
+    /** Start this subscriber's local read cursor at `sequence`, without changing its wire request. */
+    startAt(sequence) {
+        this.#cursor.update((cursor) => ({ ...cursor, start: sequence }));
+    }
+    /**
+     * Cap {@link nextGroup} and {@link recvGroup} at `sequence` inclusively, or omit it to
+     * remove the cap. Groups above the cap remain buffered and become readable if the cap
+     * is raised. This local cursor does not change the subscription's wire request.
+     */
+    endAt(sequence) {
+        this.#cursor.update((cursor) => ({ ...cursor, end: sequence }));
+    }
+    /** Close the track (optionally with an error), closing any pending groups. Idempotent. */
+    close(abort) {
+        // Settle if we're first (the producer may already have); either way drop anything
+        // still buffered. Groups parked at the endAt cap deliberately outlive a clean
+        // producer close, so the subscriber leaving is what must release them: closing
+        // and clearing wakes a pending read to observe the end instead of hanging.
+        closeTrackState(this.#state, abort);
+        this.#state.groups.mutate((groups) => {
+            for (const group of groups)
+                group.close(abort);
+            groups.length = 0;
+        });
+    }
+    /**
+     * Receive every group on this track exactly once, as it becomes available.
+     *
+     * Groups may arrive out of order or with gaps due to network conditions; unlike
+     * {@link nextGroup}, one that arrives after a newer group was already returned is
+     * still delivered. When several groups are buffered, the lowest sequence is
+     * returned first.
+     *
+     * Honors the floor set by {@link startAt} and the cap set by {@link endAt}: a group
+     * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even
+     * after a clean close, without blocking in-range groups that arrive behind it.
      */
     async recvGroup() {
         for (;;) {
-            const groups = this.state.groups.peek();
-            if (groups.length > 0) {
-                return groups.shift();
-            }
-            const closed = this.state.closed.peek();
+            const group = this.tryRecvGroup();
+            if (group)
+                return group;
+            const closed = this.#state.closed.peek();
             if (closed instanceof Error)
                 throw closed;
-            if (closed)
+            // A group beyond the cap outlives a clean close: it becomes deliverable if
+            // the cap rises, so the track isn't over while any are held.
+            if (closed !== undefined && !this.#state.groups.peek()[0])
                 return undefined;
-            await Signal.race(this.state.groups, this.state.closed);
+            await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
         }
     }
     /**
-     * @deprecated Use {@link recvGroup} for arrival order, or {@link nextGroupOrdered} for sequence order.
+     * Take the next buffered group without blocking, honoring the same cursor bounds as
+     * {@link recvGroup}.
+     *
+     * Returns `undefined` when nothing is deliverable right now, which is not by itself the
+     * end of the track: a group may still arrive, or one may be parked beyond the
+     * {@link endAt} cap. Use it to drain what the retained window already holds, where
+     * waiting for a sequence nothing will republish would park forever.
      */
-    async nextGroup() {
-        return this.recvGroup();
+    tryRecvGroup() {
+        const groups = this.#state.groups.peek();
+        const { start, end } = this.#cursor.peek();
+        while (groups.length > 0 && groups[0].sequence < start)
+            groups.shift()?.close();
+        // The buffer is sequence-sorted, so an in-range group that arrives behind a
+        // beyond-cap one sorts in front of it and is never blocked by it.
+        const group = groups[0];
+        if (group && (end === undefined || group.sequence <= end)) {
+            groups.shift();
+            return group;
+        }
+        return undefined;
     }
     /**
-     * Return the next group with a strictly-greater sequence number than the last returned.
-     *
-     * Late arrivals (with a sequence number at or below the last one returned) are silently skipped.
+     * Receive the next datagram in arrival order.
      *
-     * NOTE: This will be renamed to `nextGroup` in the next major version.
+     * Datagrams are a separate best-effort channel from groups (see
+     * {@link Producer.appendDatagram}); they share only the sequence namespace. A consumer
+     * that falls too far behind silently loses the oldest datagrams. Read this alongside
+     * {@link recvGroup} (e.g. in a separate loop) to receive both channels concurrently. Returning
+     * a datagram advances {@link nextGroup} past that sequence.
      */
-    async nextGroupOrdered() {
+    async recvDatagram() {
         for (;;) {
-            const group = await this.recvGroup();
-            if (!group)
+            const datagrams = this.#state.datagrams.peek();
+            // Evict datagrams older than the send-buffer window (also enforced on write), so a
+            // reader that stalled skips stale datagrams instead of replaying them.
+            const cutoff = performance.now() - MAX_DATAGRAM_AGE_MS;
+            while (datagrams.length > 0 && datagrams[0].time < cutoff)
+                datagrams.shift();
+            if (datagrams.length > 0) {
+                const datagram = datagrams.shift()?.datagram;
+                if (datagram) {
+                    this.#nextSequence = Math.max(this.#nextSequence, datagram.sequence + 1);
+                }
+                return datagram;
+            }
+            const closed = this.#state.closed.peek();
+            if (closed instanceof Error)
+                throw closed;
+            if (closed !== undefined)
                 return undefined;
-            if (group.sequence < this.#nextSequence) {
-                group.close();
-                continue;
+            await Signal.race(this.#state.datagrams, this.#state.closed);
+        }
+    }
+    /**
+     * Return the next group with a strictly-greater sequence number than the last returned.
+     *
+     * Late arrivals (sequence at or below the last returned) are silently skipped.
+     * Use {@link recvGroup} to see every group in arrival order instead.
+     */
+    async nextGroup() {
+        for (;;) {
+            const groups = this.#state.groups.peek();
+            const cursor = this.#cursor.peek();
+            const start = Math.max(cursor.start, this.#nextSequence);
+            while (groups.length > 0 && groups[0].sequence < start)
+                groups.shift()?.close();
+            const group = groups[0];
+            if (group && (cursor.end === undefined || group.sequence <= cursor.end)) {
+                groups.shift();
+                this.#nextSequence = group.sequence + 1;
+                return group;
             }
-            this.#nextSequence = group.sequence + 1;
-            return group;
+            const closed = this.#state.closed.peek();
+            if (closed instanceof Error)
+                throw closed;
+            if (closed !== undefined && !group)
+                return undefined;
+            await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
         }
     }
-    /** Reads the next frame across all groups, discarding older groups. */
+    /**
+     * Reads the next frame across all groups, discarding older groups.
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
+     */
     async readFrame() {
-        return (await this.readFrameSequence())?.data;
+        const next = await this.readFrameSequence();
+        return next ? { payload: next.payload, timestamp: next.timestamp } : undefined;
     }
-    /** Reads the next frame along with its group and frame sequence numbers. */
+    /**
+     * Reads the next frame along with its group and frame sequence numbers.
+     * Treat the returned frame bytes as read-only; they are shared with other consumers.
+     */
     async readFrameSequence() {
         for (;;) {
-            const groups = this.state.groups.peek();
-            // Discard old groups.
+            const groups = this.#state.groups.peek();
+            const { start } = this.#cursor.peek();
+            while (groups.length > 0 && groups[0].sequence < start)
+                groups.shift()?.close();
+            // Drain older groups first, dropping each once empty.
             while (groups.length > 1) {
+                if (groups[0].skipped) {
+                    // The reader fell behind this group's eviction window. Drop it and
+                    // signal the gap; the next read resyncs from the following group.
+                    groups.shift()?.close();
+                    throw new Lagged();
+                }
                 const next = groups[0].tryReadFrameSequence();
                 if (next) {
-                    return { group: groups[0].sequence, frame: next.sequence, data: next.data };
+                    return {
+                        group: groups[0].sequence,
+                        frame: next.sequence,
+                        payload: next.payload,
+                        timestamp: next.timestamp,
+                    };
                 }
-                // Skip this old group
                 groups.shift()?.close();
             }
-            // If there's no groups, wait for a new one.
             if (groups.length === 0) {
-                const closed = this.state.closed.peek();
+                const closed = this.#state.closed.peek();
                 if (closed instanceof Error)
                     throw closed;
-                if (closed)
+                if (closed !== undefined)
                     return undefined;
-                await Signal.race(this.state.groups, this.state.closed);
+                await Signal.race(this.#state.groups, this.#cursor, this.#state.closed);
                 continue;
             }
-            // If there's a group, wait for a frame.
             const group = groups[0];
-            const next = group.tryReadFrameSequence();
-            if (next) {
-                return { group: group.sequence, frame: next.sequence, data: next.data };
+            if (group.skipped) {
+                // Fell behind this group's eviction window. Drop it and signal the gap;
+                // the next read resyncs from the following group.
+                groups.shift()?.close();
+                throw new Lagged();
             }
-            // If the track is closed, return undefined.
-            const closed = this.state.closed.peek();
+            const next = group.tryReadFrameSequence();
+            if (next)
+                return {
+                    group: group.sequence,
+                    frame: next.sequence,
+                    payload: next.payload,
+                    timestamp: next.timestamp,
+                };
+            const closed = this.#state.closed.peek();
             if (closed instanceof Error)
                 throw closed;
-            if (closed)
+            if (closed !== undefined)
                 return undefined;
-            // Wake on a new group or the track closing. Only fold in the current group's readability
-            // while it can still deliver frames: a finished group's readable() resolves immediately, so
-            // racing it would busy-loop until a newer group arrives instead of waiting.
+            // A finished (drained + closed) group has nothing left: drop it and loop, rather than
+            // busy-waiting on its already-resolved readable() (which would livelock and starve the
+            // macrotask that delivers the next group).
             if (group.done) {
-                await Signal.race(this.state.groups, this.state.closed);
-            }
-            else {
-                await Promise.race([Signal.race(this.state.groups, this.state.closed), group.readable()]);
+                groups.shift()?.close();
+                continue;
             }
+            // Lone open group with nothing buffered yet: wait for a frame on it, a new group, or
+            // the track closing.
+            await Promise.race([Signal.race(this.#state.groups, this.#cursor, this.#state.closed), group.readable()]);
         }
     }
     /** Reads the next frame and decodes it as a UTF-8 string. */
@@ -189,7 +809,7 @@ export class Track {
         const next = await this.readFrame();
         if (!next)
             return undefined;
-        return new TextDecoder().decode(next);
+        return new TextDecoder().decode(next.payload);
     }
     /** Reads the next frame and parses it as JSON. */
     async readJson() {
@@ -203,25 +823,17 @@ export class Track {
         const next = await this.readFrame();
         if (!next)
             return undefined;
-        if (next.byteLength !== 1 || !(next[0] === 0 || next[0] === 1))
+        const payload = next.payload;
+        if (payload.byteLength !== 1 || !(payload[0] === 0 || payload[0] === 1))
             throw new Error("invalid bool frame");
-        return next[0] === 1;
-    }
-    /**
-     * Update the subscription priority. Triggers a SUBSCRIBE_UPDATE
-     * to the publisher when used on a subscribed track.
-     */
-    updatePriority(priority) {
-        this.state.priority.set(priority, true);
+        return payload[0] === 1;
     }
     /**
-     * Closes the publisher and all associated groups.
+     * Update this subscription's options (e.g. priority), triggering a SUBSCRIBE_UPDATE to the
+     * publisher. Mirrors the Rust `Subscriber::update`.
      */
-    close(abort) {
-        this.state.closed.set(abort ?? true);
-        for (const group of this.state.groups.peek()) {
-            group.close(abort);
-        }
+    update(options) {
+        this.#state.update.set(subscriptionDefaults(options));
     }
 }
 //# sourceMappingURL=track.js.map