@norskvideo/moq-net 0.1.2 → 0.1.4

package/lite/subscriber.js

@@ -1,20 +1,70 @@
 /* @ts-self-types="./subscriber.d.ts" */
-import { Announced } from "../announced.js";
-import { Broadcast } from "../broadcast.js";
-import { Group } from "../group.js";
+import { Signal } from "@norskvideo/moq-signals";
+import * as announce from "../announced.js";
+import * as broadcast from "../broadcast.js";
+import { BroadcastCache } from "../consume.js";
+import { error, ProtocolViolation, reason } from "../error.js";
+import * as netGroup from "../group.js";
+import { UNKNOWN_ORIGIN } from "../origin.js";
 import * as Path from "../path.js";
 import { Stream } from "../stream.js";
-import { error } from "../util/error.js";
-import { Announce, AnnounceInit, AnnounceInterest } from "./announce.js";
+import * as Time from "../time.js";
+import { withTimeout } from "../util/timeout.js";
+import { AnnounceInit, AnnounceOk, AnnounceRequest, decodeAnnounceBroadcastMaybe } from "./announce.js";
+import { Datagram as DatagramMessage } from "./datagram.js";
+import * as DatagramStream from "./datagram_stream.js";
+import { Fetch as FetchMessage } from "./fetch.js";
+import { sendOrder } from "./priority.js";
 import { Probe } from "./probe.js";
+import { ProbeLevel } from "./setup.js";
 import { StreamId } from "./stream.js";
 import { decodeSubscribeResponse, decodeSubscribeResponseMaybe, Subscribe, SubscribeUpdate } from "./subscribe.js";
-import { hasTrackStream, Version } from "./version.js";
+import { TrackInfo, Track as TrackMessage } from "./track.js";
+import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasExcludeHop, hasProbeRtt, restartSupported, Version, } from "./version.js";
+// Bound on how long stream-open plus the first response (SUBSCRIBE_OK on older
+// drafts, or TRACK_INFO on lite-05+) may take. Browsers cap concurrent QUIC streams
+// (Chrome ~100) and we open with waitUntilAvailable, so past the cap the open blocks
+// until the peer frees a slot. The timeout turns a stall into a clear error.
+const SUBSCRIBE_SETUP_TIMEOUT_MS = 10_000;
+/** Decode an unsigned zigzag varint back to a signed delta (mirrors Rust `VarInt::to_zigzag`). */
+function unzigzag(v) {
+    return (v >> 1n) ^ -(v & 1n);
+}
+// The TRACK stream and implicit SUBSCRIBE acceptance are lite-05+.
+function supportsTrackStream(version) {
+    switch (version) {
+        case Version.DRAFT_01:
+        case Version.DRAFT_02:
+        case Version.DRAFT_03:
+        case Version.DRAFT_04:
+            return false;
+        default:
+            return true;
+    }
+}
 /**
  * Handles subscribing to broadcasts and managing their lifecycle.
  *
  * @internal
  */
+// What we close a session with on a protocol violation.
+//
+// The draft names the condition but assigns no numbers, so this is the Rust
+// implementation's code for `Error::ProtocolViolation`: matching it is what makes the
+// two report the same thing, where the default 0 would tell the peer it closed cleanly.
+const PROTOCOL_VIOLATION_CODE = 15;
+// WebTransport rejects a close reason over 1024 bytes of UTF-8 by throwing, so a reason
+// built from peer-supplied data has to be bounded before it gets there. A broadcast path
+// is peer-supplied and long enough to reach this on its own.
+const MAX_CLOSE_REASON = 1024;
+// The longest prefix of `text` that fits a close reason. `encodeInto` stops on a whole
+// code point, so `read` never lands mid-character the way slicing bytes would.
+function closeReason(text) {
+    const encoder = new TextEncoder();
+    const buf = new Uint8Array(MAX_CLOSE_REASON);
+    const { read } = encoder.encodeInto(text, buf);
+    return text.slice(0, read);
+}
 export class Subscriber {
     #quic;
     // The version of the connection.
@@ -22,13 +72,22 @@ export class Subscriber {
     // Shared with the Publisher so callers can optionally filter out their
     // own announcements on a per-call basis (see {@link AnnouncedOptions}).
     origin;
-    // Our subscribed tracks.
+    // Our subscribed tracks. `timescale` resolves once known (from TRACK_INFO on
+    // lite-05+, or implicit defaults on older drafts); group streams block on it
+    // before decoding any frame, since a group's QUIC stream can race ahead.
     #subscribes = new Map();
     #subscribeNext = 0n;
-    // Recv bandwidth producer (Lite03+ only).
-    #recvBandwidth;
-    // RTT producer (Lite04+ only).
-    #rtt;
+    // Dedup consumed broadcasts per path: repeat consume() calls share one subscription.
+    #consumes = new BroadcastCache();
+    // Dedup in-flight one-shot fetches, keyed by [broadcast, track, sequence]. Concurrent (or
+    // repeat, while still open) fetchGroup() calls for the same group share one FETCH stream and
+    // each get an independent mirror; the entry is evicted once the group closes.
+    #fetches = new Map();
+    // The peer's PROBE estimates, written as they arrive (Lite03+ only).
+    #probe;
+    // The peer's SETUP (lite-05+), undefined until it arrives. Gates opening the PROBE
+    // stream on the peer having advertised Probe >= Report.
+    #peerSetup;
     // Distinguishes failures from streams torn down by Subscriber.close().
     #closed = new AbortController();
     /**
@@ -36,17 +95,17 @@ export class Subscriber {
      * @param quic - The WebTransport session to use
      * @param version - The protocol version
      * @param origin - Origin id shared with the Publisher
-     * @param recvBandwidth - Optional bandwidth producer for PROBE
-     * @param rtt - Optional RTT signal for PROBE
+     * @param probe - Optional sink for the peer's PROBE estimates
+     * @param peerSetup - Optional peer SETUP slot for capability gating (lite-05+)
      *
      * @internal
      */
-    constructor(quic, version, origin, recvBandwidth, rtt) {
+    constructor(quic, version, origin, probe, peerSetup) {
         this.#quic = quic;
         this.version = version;
         this.origin = origin;
-        this.#recvBandwidth = recvBandwidth;
-        this.#rtt = rtt;
+        this.#probe = probe;
+        this.#peerSetup = peerSetup;
     }
     /**
      * Subscribe to broadcast announcements under `prefix`.
@@ -55,31 +114,68 @@ export class Subscriber {
      * this connection's {@link origin}.
      */
     announced(prefix = Path.empty(), options = {}) {
-        const announced = new Announced();
+        const announced = new announce.Producer(prefix);
         void this.#runAnnounced(announced, prefix, options);
-        return announced;
+        return announced.consume();
     }
     async #runAnnounced(announced, prefix, options) {
         console.debug(`announced: prefix=${prefix}`);
-        // Send our own session-level origin id so the peer can skip announces
-        // whose hop chain already passed through us. Matches the Rust subscriber's
-        // `exclude_hop: self.self_origin.id` in `run_announce_prefix`.
-        const msg = new AnnounceInterest(prefix, this.origin);
+        // Lite04/05: send our own session-level origin id so the peer can skip announces
+        // whose hop chain already passed through us. Encoding drops it on every other
+        // version, where we drop the reflected announce on receipt instead. Matches the
+        // Rust subscriber's `exclude_hop: self.self_origin.id` in `run_announce_prefix`.
+        const msg = new AnnounceRequest(prefix, this.origin);
+        // Drop reflected announces so callers asking for "someone else's broadcasts"
+        // don't re-see their own publishes. A caller can always ask for this, and it is
+        // required on versions that don't carry excludeHop above: there the peer isn't
+        // filtering them out for us, so filtering here keeps what the app sees the same
+        // as lite-05. Lite01-03 carry no real hop ids, so the check never matches there.
+        const dropReflected = options.ignoreSelf || !hasExcludeHop(this.version);
+        // Opened outside the try so the catch can reach it: a protocol violation below has
+        // to reset the stream, not just close our side of it.
+        let stream;
         try {
-            // Open a stream and send the announce interest.
-            const stream = await Stream.open(this.#quic);
+            stream = await Stream.open(this.#quic);
+        }
+        catch (err) {
+            announced.close(error(err));
+            return;
+        }
+        try {
+            // Send the announce interest.
             await stream.writer.u53(StreamId.Announce);
             await msg.encode(stream.writer, this.version);
+            // Lite05+: the publisher reports its own origin id before any announces.
+            // It no longer stamps itself onto each hop chain, so we append it here to
+            // keep the ignoreSelf loop check seeing the full chain.
+            let responderOrigin;
+            if (hasAnnounceOk(this.version)) {
+                const ok = await AnnounceOk.decode(stream.reader, this.version);
+                // A responder that withholds its identity sends the reserved 0. It names
+                // nobody, so folding it into a chain would stamp a placeholder that cannot
+                // close a loop or tell two publishers apart. Treat it as absent instead,
+                // which is the loop-blind route the draft describes.
+                responderOrigin = ok.origin === UNKNOWN_ORIGIN ? undefined : ok.origin;
+            }
+            const advertised = new Map();
             switch (this.version) {
                 case Version.DRAFT_01:
                 case Version.DRAFT_02: {
                     // Receive ANNOUNCE_INIT first
                     const init = await AnnounceInit.decode(stream.reader, this.version);
-                    // Process initial announcements
+                    // Process initial announcements. These are advertisements like any other, so
+                    // they go on record and obey the same one-per-path rule: the initial set
+                    // naming a path twice is the same violation as two ANNOUNCE_STARTs for it,
+                    // and the record is what catches either. Draft01/02 carry no hop ids and no
+                    // ANNOUNCE_OK, so nothing names the publisher.
                     for (const suffix of init.suffixes) {
                         const path = Path.join(prefix, suffix);
+                        if (advertised.has(suffix)) {
+                            throw new ProtocolViolation(`duplicate announce for ${path}`);
+                        }
+                        advertised.set(suffix, { publisher: undefined, live: true });
                         console.debug(`announced: broadcast=${path} active=true`);
-                        announced.append({ path, active: true });
+                        announced.append({ path: suffix, active: true });
                     }
                     break;
                 }
@@ -87,145 +183,492 @@ export class Subscriber {
                     // Draft03+: no AnnounceInit, initial state comes via Announce messages.
                     break;
             }
+            // Lite06+: announce ids. Each received `active` implicitly assigns the next
+            // per-stream ordinal; `endedId`/`restart` reference it. Tracked even for
+            // announces we skip via ignoreSelf, since the sender doesn't know we skipped.
+            let nextAnnounceId = 0n;
+            const announcedById = new Map();
             // Receive announce updates (for Draft03, this includes initial state)
             for (;;) {
                 const announce = await Promise.race([
-                    Announce.decodeMaybe(stream.reader, this.version),
+                    decodeAnnounceBroadcastMaybe(stream.reader, this.version),
                     announced.closed,
                 ]);
+                // undefined: the stream ended. null: the consumer closed cleanly.
                 if (!announce)
                     break;
                 if (announce instanceof Error)
                     throw announce;
-                // Optionally drop reflected announces so callers asking for
-                // "someone else's broadcasts" don't re-see their own publishes.
-                if (options.ignoreSelf && announce.hops.includes(this.origin)) {
+                let suffix;
+                let active;
+                // Present on active/restart; ended messages never carry hops worth checking.
+                let hops;
+                switch (announce.status) {
+                    case "active":
+                        suffix = announce.suffix;
+                        active = true;
+                        hops = announce.hops;
+                        if (hasAnnounceId(this.version)) {
+                            announcedById.set(nextAnnounceId++, announce.suffix);
+                        }
+                        break;
+                    case "ended":
+                        suffix = announce.suffix;
+                        active = false;
+                        break;
+                    case "endedId": {
+                        // Resolve and retire the id; an unknown or retired id is a protocol violation.
+                        const path = announcedById.get(announce.id);
+                        if (path === undefined)
+                            throw new ProtocolViolation(`unknown announce id: ${announce.id}`);
+                        announcedById.delete(announce.id);
+                        suffix = path;
+                        active = false;
+                        break;
+                    }
+                    case "restart": {
+                        // Resolve the id; it stays live (the replacement reuses it).
+                        const path = announcedById.get(announce.id);
+                        if (path === undefined)
+                            throw new ProtocolViolation(`unknown announce id: ${announce.id}`);
+                        suffix = path;
+                        active = true;
+                        hops = announce.hops;
+                        break;
+                    }
+                }
+                const path = Path.join(prefix, suffix);
+                // One current advertisement per path per stream, decided before anything below
+                // can skip this announcement. A second ANNOUNCE_START for a path the peer
+                // already advertised is a violation whether or not its route would be usable
+                // here, and whether or not we kept the first; letting a skip pre-empt it would
+                // retract the live route and leave the stream open on a peer already out of
+                // spec.
+                //
+                // lite-05 alone is exempt, where a duplicate ANNOUNCE *is* the replacement
+                // idiom. lite-06 gave that its own message and older versions never had one, so
+                // a duplicate means the same thing on both sides of it. Mirrors the branch the
+                // Rust announce loop takes before `start_announce`.
+                const duplicateIsRestart = restartSupported(this.version) && !hasAnnounceId(this.version);
+                if (announce.status === "active" && !duplicateIsRestart && advertised.has(suffix)) {
+                    throw new ProtocolViolation(`duplicate announce for ${path}`);
+                }
+                // Retract the path: forget the advertisement, drop the shared consume entry so a
+                // later announce subscribes fresh rather than cloning the dead generation's tracks,
+                // and tell the consumer. A no-op for an advertisement never surfaced, which is
+                // what an id retiring a skipped announce resolves to.
+                const retract = () => {
+                    const previous = advertised.get(suffix);
+                    advertised.delete(suffix);
+                    if (!previous?.live)
+                        return;
+                    this.#consumes.evict(path);
+                    console.debug(`announced: broadcast=${path} active=false`);
+                    announced.append({ path: suffix, active: false });
+                };
+                // In Lite05+ the sender's origin arrives via AnnounceOk, not in each hop
+                // list, so fold it back in before checking.
+                if (hops !== undefined && dropReflected) {
+                    const full = responderOrigin !== undefined ? [...hops, responderOrigin] : hops;
+                    if (full.includes(this.origin)) {
+                        // A reflected restart means the peer's remaining route loops back through
+                        // us, so the route is gone even though the message says active. The
+                        // advertisement stays live: the peer still holds the path and its id still
+                        // resolves here.
+                        retract();
+                        advertised.set(suffix, { publisher: undefined, live: false });
+                        continue;
+                    }
+                }
+                if (active) {
+                    // The first hop identifies the original publisher; an empty chain means the
+                    // peer itself originated it. See `restart_announce` in the Rust subscriber.
+                    const publisher = hops?.[0] ?? responderOrigin;
+                    // A publisher with no identity (an empty chain from a peer that withheld its
+                    // own id, or a lite-03 UNKNOWN placeholder) never proves continuity: two such
+                    // advertisements can be unrelated publishers. Mirrors the
+                    // `publisher == Origin::UNKNOWN` arm of the Rust `restart_announce`.
+                    const identified = publisher !== undefined && publisher !== UNKNOWN_ORIGIN;
+                    // A second advertisement for a path we already carry is a restart: either an
+                    // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE.
+                    const previous = advertised.get(suffix);
+                    if (previous?.live) {
+                        if (identified && previous.publisher === publisher) {
+                            // Same publisher, new route. In-flight subscriptions resume across it,
+                            // so there is nothing for a consumer to react to. An unidentified
+                            // publisher falls through to the replacement path below instead.
+                            console.debug(`announced: broadcast=${path} rerouted`);
+                            continue;
+                        }
+                        // A different publisher took the path, so cached track info and existing
+                        // subscriptions must not carry over. Surface a real end before the start.
+                        retract();
+                    }
+                    // After `retract()`, which clears the entry: the path is advertised again, by
+                    // whoever just took it over. Recording it before would leave nothing behind, so
+                    // the *next* takeover would read as a first announcement and skip its own end.
+                    advertised.set(suffix, { publisher, live: true });
+                }
+                else {
+                    retract();
                     continue;
                 }
-                const path = Path.join(prefix, announce.suffix);
-                console.debug(`announced: broadcast=${path} active=${announce.active}`);
-                announced.append({ path, active: announce.active });
+                console.debug(`announced: broadcast=${path} active=true`);
+                announced.append({ path: suffix, active: true });
             }
             announced.close();
         }
         catch (err) {
-            announced.close(error(err));
+            const e = error(err);
+            // Reaches here on a protocol violation the peer committed (a second
+            // advertisement for a live path, an unknown announce id) as well as on a
+            // transport failure. Either way the peer has to be told: closing only our side
+            // would leave it announcing into a stream nobody reads.
+            stream.abort(e);
+            announced.close(e);
+            // A violation ends the session, not just this stream, so a nonconforming peer
+            // cannot repeat it on the next one. Matches `ietf::Subscriber` and the Rust
+            // lite subscriber, where the announce half only ever ends the session on error.
+            if (e instanceof ProtocolViolation) {
+                this.#quic.close({ closeCode: PROTOCOL_VIOLATION_CODE, reason: closeReason(reason(e)) });
+            }
         }
     }
     /**
      * Consumes a broadcast from the connection.
      *
+     * Deduplicated per path: repeat calls for the same still-live path share one reference-counted
+     * broadcast (and one upstream subscription). The shared broadcast closes once every caller has
+     * closed its handle, so callers close normally.
+     *
      * @param name - The name of the broadcast to consume
      * @returns A Broadcast instance
      */
     consume(path) {
-        const broadcast = new Broadcast();
+        return this.#consumes.get(path) ?? this.#consumes.insert(path, this.#createConsume(path));
+    }
+    #createConsume(path) {
+        // A consumed broadcast resolves info() and fetchGroup() over the wire by reaching
+        // back into this Subscriber (see ConsumeBroadcast below), rather than the wire
+        // installing callbacks on the broadcast.
+        const consumer = new ConsumeBroadcast(this, path);
         void (async () => {
             for (;;) {
-                const request = await broadcast.requested();
+                const request = await consumer.requested();
                 if (!request)
                     break;
                 void this.#runSubscribe(path, request);
             }
         })();
-        return broadcast;
+        return consumer;
     }
     async #runSubscribe(broadcast, request) {
         const id = this.#subscribeNext++;
-        // Save the writer so we can append groups to it.
-        this.#subscribes.set(id, request.track);
-        console.debug(`subscribe start: id=${id} broadcast=${broadcast} track=${request.track.name}`);
-        const msg = new Subscribe({ id, broadcast, track: request.track.name, priority: request.priority });
-        const stream = await Stream.open(this.#quic);
-        await stream.writer.u53(StreamId.Subscribe);
-        await msg.encode(stream.writer, this.version);
+        const subscription = request.subscription;
+        // `timescale` stays undefined until TRACK_INFO (or, on older drafts,
+        // implicit defaults) resolves it; runGroup blocks on it before decoding.
+        const timescale = new Signal(undefined);
+        console.debug(`subscribe start: id=${id} broadcast=${broadcast} track=${request.name}`);
+        const msg = new Subscribe({
+            id,
+            broadcast,
+            track: request.name,
+            priority: subscription.priority ?? 0,
+            ordered: subscription.ordered,
+            maxLatency: subscription.latencyMax,
+            startGroup: subscription.startGroup,
+            endGroup: subscription.endGroup,
+        });
+        // Open the stream under a timeout. The stream handle flows back via `state`
+        // so the timeout path can abort it if it finishes opening after the deadline.
+        const state = {};
+        const setup = this.#openSubscribe(state, msg, request, id, timescale);
+        let opened;
         try {
-            // The first response MUST be a SUBSCRIBE_OK.
-            const resp = await decodeSubscribeResponse(stream.reader, this.version);
-            if (!("ok" in resp)) {
-                throw new Error("first subscribe response must be SUBSCRIBE_OK");
-            }
-            console.debug(`subscribe ok: id=${id} broadcast=${broadcast} track=${request.track.name}`);
-            // Watch for priority changes and send SUBSCRIBE_UPDATE. Lite01/Lite02
+            opened = await withTimeout(setup, SUBSCRIBE_SETUP_TIMEOUT_MS, `subscribe timed out after ${SUBSCRIBE_SETUP_TIMEOUT_MS}ms waiting for the first response (browser stream limit reached?)`);
+            console.debug(`subscribe ok: id=${id} broadcast=${broadcast} track=${request.name}`);
+        }
+        catch (err) {
+            const e = error(err);
+            request.reject(e);
+            this.#subscribes.delete(id);
+            console.warn(`subscribe error: id=${id} broadcast=${broadcast} track=${request.name} error=${reason(e)}`);
+            // If the stream eventually opens after the timeout, abort it so we
+            // don't leak it. Cover both branches: setup may resolve late, or it
+            // may reject (e.g. encode/decode failure) after the stream is open.
+            setup.then(() => state.stream?.abort(e), () => state.stream?.abort(e));
+            return;
+        }
+        const { stream, producer } = opened;
+        try {
+            // Watch for subscription changes and send SUBSCRIBE_UPDATE. Lite01/Lite02
             // don't carry SUBSCRIBE_UPDATE on the wire, so skip the watcher there
             // and just wait on the stream/track like before.
-            // Draining responses also consumes any SUBSCRIBE_END / SUBSCRIBE_DROP and
-            // resolves when the publisher FINs.
-            const waits = [this.#drainResponses(stream), request.track.closed];
-            switch (this.version) {
-                case Version.DRAFT_01:
-                case Version.DRAFT_02:
-                    break;
-                default:
-                    waits.push(this.#runPriorityUpdates(id, broadcast, request.track, msg, stream));
-                    break;
+            //
+            // On lite-05+ the publisher sends SUBSCRIBE_START/END/DROP on this stream;
+            // drain them (we don't drive delivery off the resolved range) so the FIN is
+            // observed. Older drafts just wait for the stream to close.
+            const closed = supportsTrackStream(this.version) ? this.#drainResponses(stream) : stream.reader.closed;
+            const subscriptionUpdates = this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02
+                ? undefined
+                : this.#runSubscriptionUpdates(id, broadcast, producer, msg, stream);
+            // Terminal conditions (stream end, track close, a failed subscription update) settle at most
+            // once; race them into one stable promise so the demand loop doesn't re-subscribe each pass.
+            const terminal = [closed, producer.closed];
+            if (subscriptionUpdates !== undefined)
+                terminal.push(subscriptionUpdates);
+            const done = Promise.race(terminal);
+            // Serve until a terminal condition fires or the last local subscriber leaves. The unused
+            // wake is level-triggered: re-check demand so a subscriber that returns before we tear
+            // down (e.g. a quickly unmuted tile) resumes on the same subscription.
+            const idle = Symbol("idle");
+            for (;;) {
+                const reason = await Promise.race([done, producer.unused().then(() => idle)]);
+                if (reason === idle && producer.closed.peek() === undefined && producer.used.peek())
+                    continue;
+                break;
             }
-            await Promise.race(waits);
-            request.track.close();
+            producer.close();
             stream.close();
-            console.debug(`subscribe close: id=${id} broadcast=${broadcast} track=${request.track.name}`);
+            console.debug(`subscribe close: id=${id} broadcast=${broadcast} track=${request.name}`);
         }
         catch (err) {
             const e = error(err);
-            request.track.close(e);
-            console.warn(`subscribe error: id=${id} broadcast=${broadcast} track=${request.track.name} error=${e.message}`);
+            producer.close(e);
+            console.warn(`subscribe error: id=${id} broadcast=${broadcast} track=${request.name} error=${reason(e)}`);
             stream.abort(e);
         }
         finally {
             this.#subscribes.delete(id);
         }
     }
-    /**
-     * Drain responses on the subscribe stream until the publisher FINs.
-     *
-     * The first SUBSCRIBE_OK is consumed by the caller; this reads any further
-     * SUBSCRIBE_END / SUBSCRIBE_DROP. They aren't acted on yet (groups arrive on
-     * their own streams regardless), but consuming them keeps the stream aligned.
-     */
+    // Determine the track's immutable properties, accept the request (so the
+    // application's track.Subscriber resolves and incoming groups have a producer to
+    // write into), register it, then open the subscribe stream. `state.stream` is
+    // populated as soon as the subscribe stream opens so the caller can clean it up
+    // on timeout even before this promise settles.
+    //
+    // On lite-05+ the properties come from a TRACK stream opened first, and the
+    // SUBSCRIBE is accepted implicitly (no SUBSCRIBE_OK). Older drafts carry no
+    // per-track properties, so they resolve to defaults and just drain SUBSCRIBE_OK.
+    async #openSubscribe(state, msg, request, id, timescale) {
+        let producer;
+        let drainOk = false;
+        if (supportsTrackStream(this.version)) {
+            // Fetch the immutable properties once via the TRACK stream.
+            const info = await this.#trackInfo(msg.broadcast, msg.track);
+            producer = request.accept(this.#toModelInfo(info));
+            timescale.set(info.timescale);
+        }
+        else {
+            // Older drafts negotiate nothing per-track: verbatim frames, no timescale.
+            producer = request.accept();
+            timescale.set(0);
+            drainOk = true;
+        }
+        // Register before opening SUBSCRIBE so a racing GROUP stream finds the entry.
+        this.#subscribes.set(id, { track: producer, timescale });
+        state.stream = await Stream.open(this.#quic);
+        await state.stream.writer.u53(StreamId.Subscribe);
+        await msg.encode(state.stream.writer, this.version);
+        if (drainOk) {
+            // The first response MUST be a SUBSCRIBE_OK (older drafts only).
+            const resp = await decodeSubscribeResponse(state.stream.reader, this.version);
+            if (!("ok" in resp)) {
+                throw new Error("first subscribe response must be SUBSCRIBE_OK");
+            }
+        }
+        return { stream: state.stream, producer };
+    }
+    // Opens a TRACK stream, reads the single TRACK_INFO, and FINs. Lite-05+ only.
+    async #trackInfo(broadcast, track) {
+        const stream = await Stream.open(this.#quic);
+        try {
+            await stream.writer.u53(StreamId.Track);
+            await new TrackMessage(broadcast, track).encode(stream.writer, this.version);
+            const info = await TrackInfo.decode(stream.reader, this.version);
+            // The publisher FINs after TRACK_INFO; FIN our side too.
+            stream.close();
+            return info;
+        }
+        catch (err) {
+            stream.abort(error(err));
+            throw err;
+        }
+    }
+    // Map the wire TRACK_INFO onto the model track.Info a producer/consumer holds.
+    #toModelInfo(info) {
+        return {
+            timescale: Time.Timescale(info.timescale),
+            // Publisher Max Latency rides on the wire, so the local retention window
+            // matches what the upstream advertises (relays re-serve with the same bound).
+            latencyMax: info.latencyMax,
+            priority: info.priority,
+            ordered: info.ordered,
+        };
+    }
+    // Resolve a track's immutable model info via a TRACK stream (lite-05+), for the
+    // ConsumeBroadcast backing track.Consumer.info(). On older drafts there's no TRACK
+    // stream, so this rejects rather than fabricating defaults.
+    async resolveTrackInfo(broadcast, track) {
+        if (!supportsTrackStream(this.version)) {
+            throw new Error("track info requires moq-lite-05 or newer");
+        }
+        return this.#toModelInfo(await this.#trackInfo(broadcast, track));
+    }
+    // Open a FETCH stream for one group and stream its bare frames into a group, for the
+    // ConsumeBroadcast backing track.Consumer.fetchGroup() (lite-05+).
+    fetchGroup(broadcast, track, sequence, options = {}) {
+        // Coalesce onto a still-open fetch of the same group so we don't open a second FETCH
+        // stream (and re-download it); each caller reads an independent mirror.
+        const key = JSON.stringify([broadcast, track, sequence]);
+        const existing = this.#fetches.get(key);
+        if (existing && !existing.isClosed)
+            return Promise.resolve(existing.mirror());
+        // Create and cache the group synchronously (before any await) so a concurrent fetch for
+        // the same group finds it and coalesces rather than racing to open its own stream.
+        const group = new netGroup.Producer(sequence);
+        this.#fetches.set(key, group);
+        void group.closed.then(() => {
+            if (this.#fetches.get(key) === group)
+                this.#fetches.delete(key);
+        });
+        return this.#runFetch(broadcast, track, sequence, options, group);
+    }
+    // Open the FETCH stream and pump the response into the shared group. Setup errors close the
+    // group (so coalesced mirrors observe them and the entry evicts) and reject this caller.
+    async #runFetch(broadcast, track, sequence, options, group) {
+        try {
+            if (!supportsTrackStream(this.version)) {
+                throw new Error("fetch group requires moq-lite-05 or newer");
+            }
+            const info = await this.#trackInfo(broadcast, track);
+            const priority = options.priority ?? 0;
+            const stream = await Stream.open(this.#quic, { sendOrder: sendOrder({ priority }) });
+            try {
+                await stream.writer.u53(StreamId.Fetch);
+                await new FetchMessage(broadcast, track, priority, sequence).encode(stream.writer, this.version);
+            }
+            catch (err) {
+                stream.abort(error(err));
+                throw err;
+            }
+            // Mint this caller's reader before starting the pump, so the group has demand when the
+            // pump begins watching it (an abandoned fetch cancels once every reader has left).
+            const consumer = group.mirror();
+            void this.#runFetchResponse(stream, group, Time.Timescale(info.timescale));
+            return consumer;
+        }
+        catch (err) {
+            group.close(error(err));
+            throw err;
+        }
+    }
+    // Read the FETCH response (bare zigzag-delta-timestamped frames) into the group, then
+    // FIN. A stream-level failure aborts the group so its reader observes the gap.
+    async #runFetchResponse(stream, group, timescale) {
+        try {
+            let prevTs = 0n;
+            // Serve until the stream FINs, the group closes, or every reader leaves. A group can
+            // stay open indefinitely (a catalog or JSON stream), so an abandoned fetch is stopped by
+            // demand, not by the stream ending. `closed` and `unused` are watched across frames as
+            // stable promises (not re-subscribed to the signals each frame); the unused check is
+            // level-triggered, so a coalesced fetch that arrives before we cancel re-arms and resumes.
+            const idle = Symbol("idle");
+            const closed = Promise.resolve(group.closed);
+            let unused = group.unused().then(() => idle);
+            for (;;) {
+                const done = await Promise.race([stream.reader.done(), closed, unused]);
+                if (done === idle) {
+                    if (!group.isClosed && group.used.peek()) {
+                        unused = group.unused().then(() => idle);
+                        continue;
+                    }
+                    break;
+                }
+                if (done !== false)
+                    break;
+                prevTs += unzigzag(await stream.reader.u62());
+                const timestamp = new Time.Timestamp(Number(prevTs), timescale);
+                const size = await stream.reader.u53();
+                const payload = await stream.reader.read(size);
+                if (!payload)
+                    break;
+                group.writeFrame({ payload, timestamp });
+            }
+            group.close();
+            stream.close();
+        }
+        catch (err) {
+            const e = error(err);
+            group.close(e);
+            stream.abort(e);
+        }
+    }
+    // Drains SUBSCRIBE_START/END/DROP on the subscribe stream until FIN (lite-05+).
+    // The resolved range is informational here; the producer already orders groups.
+    // Resolves (never rejects) on FIN or on the stream being reset out from under it,
+    // so it's safe to drop from a Promise.race without an unhandled rejection.
     async #drainResponses(stream) {
-        for (;;) {
-            const resp = await decodeSubscribeResponseMaybe(stream.reader, this.version);
-            if (!resp)
-                break;
+        try {
+            for (;;) {
+                const resp = await decodeSubscribeResponseMaybe(stream.reader, this.version);
+                if (!resp)
+                    return;
+            }
+        }
+        catch {
+            // Stream closed or reset; nothing more to drain.
         }
     }
     /**
-     * Send SUBSCRIBE_UPDATE messages whenever the track's priority signal changes.
+     * Send SUBSCRIBE_UPDATE messages whenever the track's aggregate subscription changes.
      *
      * Resolves cleanly when the stream or track closes, so the caller can include
      * this in Promise.race without leaving a dangling pending write that would
-     * become an unhandled rejection if the user calls updatePriority after close.
+     * become an unhandled rejection if the user calls update after close.
      *
      * Peeks the signal at the top of every iteration so that updates which landed
      * before SubscribeOk arrived (or between iterations, before .next() registered
      * its listener) aren't lost.
      */
-    async #runPriorityUpdates(id, broadcast, track, msg, stream) {
+    async #runSubscriptionUpdates(id, broadcast, track, msg, stream) {
         const stopped = Promise.race([track.closed, stream.reader.closed]).then(() => null);
-        let lastSent;
+        let lastSent = {
+            priority: msg.priority,
+            ordered: msg.ordered,
+            latencyMax: msg.maxLatency,
+            startGroup: msg.startGroup,
+            endGroup: msg.endGroup,
+        };
         for (;;) {
-            const current = track.state.priority.peek();
-            if (current === undefined || current === lastSent) {
+            const current = track.subscription.peek();
+            if (current === undefined || this.#sameSubscription(current, lastSent)) {
                 // Nothing new to send; wait for a change or termination.
-                const next = await Promise.race([track.state.priority.next(), stopped]);
+                const next = await Promise.race([track.subscription.changed(), stopped]);
                 if (next === null)
                     return;
                 continue;
             }
-            // Round-trip the other Subscribe parameters so the publisher doesn't
-            // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxLatency/etc.
             const update = new SubscribeUpdate({
-                priority: current,
-                ordered: msg.ordered,
-                maxLatency: msg.maxLatency,
-                startGroup: msg.startGroup,
-                endGroup: msg.endGroup,
+                priority: current.priority ?? 0,
+                ordered: current.ordered,
+                maxLatency: current.latencyMax,
+                startGroup: current.startGroup,
+                endGroup: current.endGroup,
             });
             await update.encode(stream.writer, this.version);
-            lastSent = current;
-            console.debug(`subscribe update: id=${id} broadcast=${broadcast} track=${track.name} priority=${current}`);
+            lastSent = { ...current };
+            console.debug(`subscribe update: id=${id} broadcast=${broadcast} track=${track.name}`);
         }
     }
+    #sameSubscription(a, b) {
+        return ((a.priority ?? 0) === (b.priority ?? 0) &&
+            (a.ordered ?? false) === (b.ordered ?? false) &&
+            (a.latencyMax ?? 0) === (b.latencyMax ?? 0) &&
+            a.startGroup === b.startGroup &&
+            a.endGroup === b.endGroup);
+    }
     /**
      * Handles a group message.
      * @param group - The group message
@@ -234,30 +677,51 @@ export class Subscriber {
      * @internal
      */
     async runGroup(group, stream) {
-        const subscribe = this.#subscribes.get(group.subscribe);
-        if (!subscribe) {
+        const entry = this.#subscribes.get(group.subscribe);
+        if (!entry) {
             if (group.subscribe >= this.#subscribeNext) {
                 throw new Error(`unknown subscription: id=${group.subscribe}`);
             }
             return;
         }
-        const producer = new Group(group.sequence);
-        subscribe.writeGroup(producer);
+        const { track, timescale } = entry;
+        const producer = new netGroup.Producer(group.sequence);
+        track.writeGroup(producer);
         try {
+            // Block until the timescale is known; the group's stream can arrive before
+            // TRACK_INFO (or implicit defaults) resolves it on the subscribe stream.
+            let scale = timescale.peek();
+            while (scale === undefined) {
+                if (track.closed.peek() !== undefined) {
+                    // Subscription ended before the scale resolved; nothing to decode.
+                    producer.close();
+                    stream.stop(new Error("cancel"));
+                    return;
+                }
+                await Signal.race(timescale, track.closed);
+                scale = timescale.peek();
+            }
+            // A non-zero scale means every frame is prefixed with a zigzag-delta timestamp
+            // (the lite-05 FRAME format), which we decode into a Timestamp at that scale.
+            // Scale 0 (pre-lite-05) carries no timestamp, so we wall-clock-stamp.
+            let prevTs = 0n;
             for (;;) {
-                const done = await Promise.race([stream.done(), subscribe.closed, producer.closed]);
+                const done = await Promise.race([stream.done(), track.closed, producer.closed]);
                 if (done !== false)
                     break;
-                if (hasTrackStream(this.version)) {
-                    // moq-lite-05+ prefixes each frame with a zigzag timestamp delta. Decode it
-                    // to stay aligned with the wire, but don't surface it yet.
-                    await stream.u62();
+                let timestamp;
+                if (scale !== 0) {
+                    prevTs += unzigzag(await stream.u62());
+                    timestamp = new Time.Timestamp(Number(prevTs), Time.Timescale(scale));
+                }
+                else {
+                    timestamp = Time.Timestamp.now();
                 }
                 const size = await stream.u53();
                 const payload = await stream.read(size);
                 if (!payload)
                     break;
-                producer.writeFrame(payload);
+                producer.writeFrame({ payload, timestamp });
             }
             producer.close();
             stream.stop(new Error("cancel"));
@@ -268,6 +732,69 @@ export class Subscriber {
             stream.stop(e);
         }
     }
+    /**
+     * Receives QUIC datagrams and routes each to its subscription's track producer (lite-05 §6.4).
+     *
+     * Returns immediately on a non-datagram transport or pre-lite-05 version. A decode error or an
+     * unknown subscribe id drops that datagram without tearing down the session (best-effort); the
+     * loop ends only when the datagram stream closes.
+     *
+     * @internal
+     */
+    async runDatagrams() {
+        if (!hasDatagrams(this.version) || DatagramStream.maxDatagramSize(this.#quic) === 0) {
+            return;
+        }
+        // Never reject: this loop is awaited alongside the connection's other tasks, so a
+        // datagram-stream failure must not tear the whole session down (it's best-effort).
+        const reader = DatagramStream.datagramReader(this.#quic);
+        if (!reader)
+            return;
+        try {
+            try {
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    if (!value)
+                        continue;
+                    try {
+                        await this.#routeDatagram(value);
+                    }
+                    catch (err) {
+                        console.debug(`dropping datagram: ${reason(err)}`);
+                    }
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        catch (err) {
+            const e = error(err);
+            if (e.message === "The session is closed.") {
+                console.debug(`datagram receive stopped: ${e.message}`);
+            }
+            else {
+                console.warn("datagram stream error", err);
+            }
+        }
+    }
+    // Decode one datagram body and hand it to the matching subscription's producer. Drops the
+    // datagram (best-effort) if the subscription is unknown/closed or its timescale isn't resolved.
+    async #routeDatagram(payload) {
+        const dg = await DatagramMessage.decode(payload);
+        const entry = this.#subscribes.get(dg.subscribe);
+        if (!entry)
+            return; // Unknown or already-closed subscription.
+        // Datagrams are lite-05+, which always negotiates a timescale; if it hasn't resolved
+        // yet (the datagram raced ahead of TRACK_INFO), drop rather than guess.
+        const scale = entry.timescale.peek();
+        if (!scale)
+            return;
+        const timestamp = new Time.Timestamp(dg.timestamp, Time.Timescale(scale));
+        entry.track.writeDatagram({ sequence: dg.sequence, timestamp, payload: dg.payload });
+    }
     /**
      * Opens a PROBE bidi stream to receive bandwidth estimates from the publisher.
      * Returns immediately if recv bandwidth is not supported.
@@ -279,14 +806,31 @@ export class Subscriber {
      *
      * @internal
      */
+    // Await the peer's advertised probe level, blocking until its SETUP arrives. The peer
+    // MUST send exactly one SETUP, so this resolves once that stream is read.
+    async #peerProbeLevel(peerSetup) {
+        let setup = peerSetup.peek();
+        while (setup === undefined) {
+            setup = await peerSetup.changed();
+        }
+        return setup.probe;
+    }
     async runProbe() {
-        if (!this.#recvBandwidth)
+        if (!this.#probe)
             return;
         if (this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02)
             return;
+        // Lite-05+ gates the PROBE stream on the peer advertising Probe >= Report in its
+        // SETUP. Wait for the SETUP, then bail if the peer can't report bitrate. Older
+        // drafts have no SETUP, so they keep probing unconditionally.
+        if (this.#peerSetup) {
+            const probe = await this.#peerProbeLevel(this.#peerSetup);
+            if (probe < ProbeLevel.Report)
+                return;
+        }
         // Probe is best-effort: any failure (stream reset by peer, missing peer support,
         // transport hiccup) MUST NOT tear down the connection. On error, drop the
-        // bandwidth/RTT estimates so consumers know they're stale.
+        // estimates so consumers know they're stale.
         try {
             const stream = await Stream.open(this.#quic);
             await stream.writer.u53(StreamId.Probe);
@@ -294,10 +838,18 @@ export class Subscriber {
                 const probe = await Probe.decodeMaybe(stream.reader, this.version);
                 if (!probe)
                     break;
-                this.#recvBandwidth.set(probe.bitrate ?? undefined);
-                if (this.#rtt && probe.rtt !== undefined) {
-                    this.#rtt.set(probe.rtt);
-                }
+                // lite-03 carries no RTT field, so an absent value there means "not
+                // carried" and the last reading stands. From lite-04 the field is
+                // always present and 0 explicitly means unknown, so undefined is the
+                // peer retracting a value we would otherwise hold forever.
+                const prev = this.#probe.peek();
+                const rtt = probe.rtt !== undefined ? Time.Milli(probe.rtt) : undefined;
+                this.#probe.set({
+                    // `undefined` is the peer reporting "unknown", not an estimate of
+                    // zero; letting it through would become a real 0 bps ABR target.
+                    estimatedRecvRate: probe.bitrate,
+                    rtt: hasProbeRtt(this.version) ? rtt : (rtt ?? prev.rtt),
+                });
             }
         }
         catch (err) {
@@ -306,16 +858,41 @@ export class Subscriber {
             }
         }
         finally {
-            this.#recvBandwidth.set(undefined);
-            this.#rtt?.set(undefined);
+            this.#probe.set({});
         }
     }
     close() {
         this.#closed.abort();
-        for (const track of this.#subscribes.values()) {
+        for (const { track } of this.#subscribes.values()) {
             track.close();
         }
         this.#subscribes.clear();
     }
 }
+/**
+ * A broadcast consumed from a lite session. It resolves `track.Consumer.info()` and
+ * `.fetchGroup()` over the wire (lite-05+ TRACK / FETCH streams) by reaching into the
+ * {@link Subscriber} it was opened from, the way the Rust `BroadcastConsumer` holds its
+ * session. Live subscribes still flow through the inherited requested() queue.
+ */
+class ConsumeBroadcast extends broadcast.Consumer {
+    #subscriber;
+    #path;
+    constructor(subscriber, path, state) {
+        super(state);
+        this.#subscriber = subscriber;
+        this.#path = path;
+    }
+    // Preserve the subclass (and its wire-backed info/fetchGroup) when the consume cache shares
+    // this broadcast across callers.
+    clone() {
+        return new ConsumeBroadcast(this.#subscriber, this.#path, this.shareState());
+    }
+    resolveTrackInfo(name) {
+        return this.#subscriber.resolveTrackInfo(this.#path, name);
+    }
+    fetchGroup(name, sequence, options) {
+        return this.#subscriber.fetchGroup(this.#path, name, sequence, options);
+    }
+}
 //# sourceMappingURL=subscriber.js.map