@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/topics.js

@@ -0,0 +1,959 @@
+// Topics (SDK §4, WP §6–§7), the JS spelling of the Rust client's `topics.rs`.
+//
+// A publisher is an intent (`channel.ts`): its handle task asks the runtime `synapse/topic/register`
+// on every session and, admitted, installs the broadcast `<prefix>/topic/<bind>/<topic>` — `desc`
+// (one retained frame: the descriptor with our time domain) and `data` — which `publish()` writes to
+// on the fast lane, synchronously; while nothing is installed frames are dropped and counted.
+//
+// A subscription follows its *topic*: a task (`followTopic`) subscribes to each publisher the
+// catalog lists for the topic but ourselves and hands its `data` track to the read; a publisher that
+// leaves the catalog is removed; a new session resets the set. The catalog is the runtime's statement
+// (listed = alive): a publisher whose subscribe fails is left out until the catalog next changes,
+// when every listed publisher not held is tried again; no timer of our own. A datagram publisher
+// whose own `desc` has `fec` gets a follower (the video path: `FecReader` per publisher).
+import * as Moq from "@moq/net";
+import { FLAGS, MSGPACK, SynapseError, TYPES, auParamSets, auSyncPoints, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, isVideo, mediaFlags, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
+import { Handle, start as startHandle } from "./channel.js";
+import { FecReader, FecWriter, ReportWriter, feedbackListener, requireFec } from "./fec.js";
+import { RETAINED_FRAME_MAX_AGE_MS, StreamWriter, latestSubscription, moqTimestamp, streamTopicSubscription, waitActive, writeLatest } from "./session.js";
+import { AsyncQueue, deferred, withTimeout, TIMEOUT } from "./util.js";
+/** moq's cap on one `stream` frame (a group's cache). */
+const STREAM_FRAME_MAX = 32 * 1024 * 1024;
+/** The bound on adding one publisher (its broadcast, its `desc`, its `data` subscription). */
+const ADD_WITHIN_MS = 2000;
+/** The most messages one read takes from one publisher: a publisher that stays readable cannot keep a read from returning. */
+const DRAIN_PER_READ = 256;
+/** The cap of the every-message `fec` queue (frames): moq's own bound on a track's unread datagrams, as in Rust (`FEC_QUEUE_CAP` 64). */
+const FEC_QUEUE_CAP = 64;
+/** The publisher shared by every `publisher(topic)` handle of one topic on this node. */
+export class TopicPublisher {
+    node;
+    contract;
+    wasm;
+    warn;
+    name;
+    registerSvc = "synapse/topic/register";
+    unregisterSvc = "synapse/topic/unregister";
+    desc;
+    fecParams;
+    fecStats;
+    #bound;
+    #verdict = { status: "unbound" };
+    #seq = 0;
+    published = 0;
+    droppedDisconnected = 0;
+    handles = 0;
+    handle;
+    constructor(node, contract, maxDatagram, wasm, warn) {
+        this.node = node;
+        this.contract = contract;
+        this.wasm = wasm;
+        this.warn = warn;
+        this.name = contract.name;
+        let fec = contract.delivery === "datagram" ? contract.fec : undefined;
+        if (fec) {
+            fec = { ...fec, symbol_size: fec.symbol_size === 0 ? fecSymbolSizeFor(maxDatagram) : fec.symbol_size };
+            if (fec.symbol_size < 8 || fec.symbol_size % 8 !== 0)
+                throw new SynapseError("invalid_input", `fec symbol_size ${fec.symbol_size} must be a multiple of 8`);
+            this.fecStats = { blocks: 0, plain: 0, superseded: 0, symbols: 0, reports: 0, repairPct: fec.repair_pct };
+        }
+        this.fecParams = fec;
+        this.desc = contract.desc(node.dom);
+        if (fec)
+            this.desc.fec = { ...fec };
+        this.handle = startHandle(node, this);
+    }
+    get verdict() { return this.#verdict; }
+    get isBound() { return this.#bound !== undefined; }
+    registerArgs(bind) { return { topic: this.name, desc: this.desc, bind }; }
+    unregisterArgs(bind) { return { topic: this.name, bind }; }
+    /** Admitted: the broadcast is created, the descriptor written, the data track made, then announced (WP §7.1). */
+    install(s, bind, _mailbox) {
+        const bc = s.createBroadcast(topicPath(s.prefix, bind, this.name));
+        // The one-frame descriptor is kept for the publisher's life: a subscriber joining later reads it (see `RETAINED_FRAME_MAX_AGE_MS`).
+        const desc = bc.createTrack("desc", { priority: moqPriority(1), maxAge: Moq.Time.Milli(RETAINED_FRAME_MAX_AGE_MS) });
+        writeLatest(desc, { flags: FLAGS.KEY, type: TYPES.PUB, seq: 1, tUs: nowUs() }, encodeBody(this.desc));
+        // Stream frames carry the publish stamp at microsecond timescale (newest among one millisecond's messages is by stamp, not poll order).
+        const dataTrack = bc.createTrack("data", this.contract.delivery === "stream" ? { priority: moqPriority(3), timescale: Moq.Time.Timescale.MICRO } : { priority: moqPriority(3) });
+        let data;
+        if (this.contract.delivery === "stream")
+            data = { kind: "stream", w: new StreamWriter(dataTrack) };
+        else if (!this.fecParams)
+            data = { kind: "datagram", track: dataTrack };
+        else {
+            const params = { ...this.fecParams, repair_pct: this.fecStats.repairPct };
+            data = { kind: "fec", w: new FecWriter(this.name, dataTrack, this.wasm, params, this.fecStats, () => { }) };
+        }
+        bc.announce();
+        let feedback;
+        if (data.kind === "fec" && this.fecParams.repair_pct > 0) {
+            feedback = new AbortController();
+            const w = data.w;
+            void feedbackListener(s, this.name, this.fecParams.repair_pct, pct => w.setRepairPct(pct), () => { this.fecStats.reports++; }, feedback.signal, this.warn);
+        }
+        const old = this.#bound;
+        this.#bound = { bc, desc, data, feedback };
+        if (old)
+            finish(old);
+    }
+    retract() { const b = this.#bound; this.#bound = undefined; if (b)
+        finish(b); }
+    setVerdict(v) { this.#verdict = v; }
+    /**
+     * Publishes one frame (SDK §13: synchronous, never awaits the network). While nothing is installed
+     * (between sessions, a refused register being asked again) the frame is dropped and counted. A
+     * `stream` frame over moq's cap, a plain datagram over the session's datagram size, or a `fec`
+     * frame the codec refuses is refused (`invalid_input`) without taking a `seq`.
+     */
+    publishFrame(type, flags, tUs, tlvs, body) {
+        // A `MEDIA` frame on a msgpack topic contradicts the descriptor every subscriber decodes by (WP §7.2).
+        if (type === TYPES.MEDIA && !this.contract.raw)
+            throw new SynapseError("invalid_input", `topic ${this.name}: a MEDIA frame needs a raw topic (a contentType other than ${MSGPACK})`);
+        const b = this.#bound;
+        if (!b) {
+            this.droppedDisconnected++;
+            return;
+        }
+        const header = { flags, type: type, seq: 0, tUs };
+        if (tlvs.length)
+            header.tlvs = tlvs;
+        const len = 16 + body.length;
+        if (b.data.kind === "stream" && len > STREAM_FRAME_MAX)
+            throw new SynapseError("invalid_input", `stream topic ${this.name}: ${len} bytes exceeds moq's ${STREAM_FRAME_MAX}-byte frame cap`);
+        if (b.data.kind === "datagram" && len > this.node.knobs.maxDatagram)
+            throw new SynapseError("invalid_input", `datagram topic ${this.name}: ${len} bytes exceeds the session's datagram size of ${this.node.knobs.maxDatagram} bytes; use a stream topic, or a datagram topic with fec`);
+        header.seq = this.#seq;
+        let written = true;
+        try {
+            switch (b.data.kind) {
+                case "stream":
+                    if (hasPendingSentUs(header))
+                        stampSentUs(header, nowUs());
+                    b.data.w.write(header, body);
+                    break;
+                case "datagram":
+                    if (hasPendingSentUs(header))
+                        stampSentUs(header, nowUs());
+                    b.data.track.appendDatagram(moqTimestamp(tUs), frame(header, body));
+                    break;
+                case "fec":
+                    b.data.w.publish(header, body);
+                    break;
+            }
+        }
+        catch (e) {
+            if (e instanceof SynapseError && e.code === "invalid_input")
+                throw e;
+            written = false; // the session is going down under us: the unbind is on its way
+        }
+        this.#seq = (this.#seq + 1) >>> 0;
+        if (written)
+            this.published++;
+        else
+            this.droppedDisconnected++;
+    }
+    /**
+     * The typed form: validates against the contract's schema and encodes msgpack; a raw topic's bytes
+     * go as given, and on a `video/*` topic as a `MEDIA` frame whose `KEY`/`CONFIG`/`RECOVERY` flags
+     * are read off the bitstream (Rust `Publisher<RawBody>::publish`).
+     */
+    publish(value, opts = {}) {
+        const tUs = opts.tUs ?? nowUs();
+        if (this.contract.raw) {
+            if (!(value instanceof Uint8Array))
+                throw new SynapseError("invalid_input", `topic ${this.name} (${this.contract.contentType}) takes bytes`);
+            if (!isVideo(this.contract.contentType)) {
+                this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], value);
+                return;
+            }
+            const { idr, recovery } = auSyncPoints(value);
+            this.publishFrame(TYPES.MEDIA, mediaFlags({ key: idr, config: auParamSets(value) !== undefined, recovery }) | (opts.flags ?? 0), tUs, [], value);
+            return;
+        }
+        let v = value;
+        if (this.contract.schema) {
+            const r = validateSync(this.contract.schema, value);
+            if (r.issues)
+                throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid value", data: { issues: r.issues } });
+            v = r.value;
+        }
+        this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], encodeBody(v));
+    }
+    /** An encoder's frame with the flags it already carries and its `STAGES` stamps (no re-parse); `tUs` 0 = now. The video helper's path (Rust `publish_media_frame`), not a user verb. */
+    publishMediaFrame(f) { const h = mediaHeader(f, 0); this.publishFrame(h.type, h.flags, f.tUs || nowUs(), h.tlvs ?? [], f.data); }
+    stats() {
+        const s = { published: this.published, droppedDisconnected: this.droppedDisconnected };
+        if (this.fecStats)
+            s.fec = { blocks: this.fecStats.blocks, plain: this.fecStats.plain, superseded: this.fecStats.superseded };
+        return s;
+    }
+}
+function finish(b) {
+    b.feedback?.abort();
+    try {
+        if (b.data.kind === "fec")
+            b.data.w.close();
+        else if (b.data.kind === "stream")
+            b.data.w.close();
+        else
+            b.data.track.close();
+    }
+    catch { /* closed */ }
+    try {
+        b.desc.close();
+    }
+    catch { /* closed */ }
+    try {
+        b.bc.close();
+    }
+    catch { /* closed */ }
+}
+/**
+ * The key of a publisher handle's encoder-frame path, the JS spelling of Rust's `pub(crate)
+ * publish_media_frame`: `@synapse-sdk/media`'s `videoPublisher` reaches it by the same
+ * `Symbol.for` key (the two packages share no module), so it is on no public type.
+ */
+export const PUBLISH_MEDIA_FRAME = Symbol.for("@synapse-sdk/client:publishMediaFrame");
+/** The application's handle: the last one closed ends the publisher's task (`unregister`). */
+export class PublisherHandle {
+    p;
+    onLast;
+    #closed = false;
+    constructor(p, onLast) {
+        this.p = p;
+        this.onLast = onLast;
+        p.handles++;
+    }
+    get topic() { return this.p.name; }
+    get verdict() { return this.p.verdict; }
+    ready() { return this.p.handle.ready(); }
+    /** A closed handle publishes nothing (the Rust handle is gone once dropped): `not_connected`. */
+    #open() { if (this.#closed)
+        throw new SynapseError("not_connected", "publisher closed"); }
+    publish(value, opts) { this.#open(); this.p.publish(value, opts); }
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f) { this.#open(); this.p.publishMediaFrame(f); }
+    stats() { return this.p.stats(); }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        if (--this.p.handles === 0) {
+            this.p.handle.unregister();
+            this.onLast();
+        }
+    }
+    async [Symbol.asyncDispose]() { this.close(); }
+}
+/** Resolves the codec a `fec` topic needs (once per process). */
+export async function wasmFor(contract) {
+    return contract.delivery === "datagram" && contract.fec ? requireFec(`topic ${contract.name}`) : undefined;
+}
+// ------------------------------------------------------------------------------ subscription
+/** What a source gives when its track ended. */
+const END = Symbol("end");
+/**
+ * The bound on the datagrams one source holds for the read: the ring moq itself keeps of a track's
+ * unread datagrams (`MAX_DATAGRAMS = 64` in moq-net; Rust `FEC_QUEUE_CAP` is the same 64).
+ * `@moq/net` 0.4.2 has no synchronous datagram read, so a datagram source's reader takes them into
+ * this holder as they arrive and the read drains it: what the Rust read sees in moq's ring.
+ */
+const DATAGRAM_RING = 64;
+/** `seq` wraps at u32: "newer" is a positive signed distance (RFC 1982). */
+const newer = (seq, than) => (((seq - than) | 0) > 0);
+export class TopicSubscription {
+    node;
+    contract;
+    opts;
+    warn;
+    topic;
+    stats = { read: 0, superseded: 0, staleDrops: 0, mismatch: 0, fecGiveup: 0, repaired: 0, coalesced: 0 };
+    #sources = [];
+    /** Frames the `fec` followers reassembled; latest mode keeps one per publisher. */
+    #fec = [];
+    #wake;
+    #ended = false;
+    #stop = new AbortController();
+    latest;
+    #deadlineUs;
+    #throttleUntil = 0;
+    #throttled;
+    #throttleTimer;
+    constructor(node, contract, opts, warn) {
+        this.node = node;
+        this.contract = contract;
+        this.opts = opts;
+        this.warn = warn;
+        this.topic = contract.name;
+        this.latest = (opts.queueDepth ?? 1) !== 0;
+        this.#deadlineUs = opts.deadlineMs !== undefined ? opts.deadlineMs * 1000 : undefined;
+        void followTopic(this);
+    }
+    get signal() { return this.#stop.signal; }
+    get ownDom() { return this.node.dom.id; }
+    /** The follow task hands a plain publisher here (a datagram source's reader starts); the waiting `next()` is woken. */
+    addSource(src) {
+        if (this.#ended) {
+            closeSource(src);
+            return;
+        }
+        this.#sources.push(src);
+        if (!src.stream)
+            void this.#readDatagrams(src);
+        this.#signal();
+    }
+    /** A datagram source's reader: one `recvDatagram` at a time into `held`, until the track or the source ends. */
+    async #readDatagrams(src) {
+        try {
+            for (;;) {
+                const d = await src.sub.recvDatagram();
+                if (!d || src.ended)
+                    break;
+                this.#hold(src, d.payload);
+                this.#signal();
+            }
+        }
+        catch { /* the track broke: its end */ }
+        src.done = true;
+        this.#signal();
+    }
+    /** Into a datagram source's holder: latest mode keeps the newest `seq`, every-message mode the last `DATAGRAM_RING`; what is displaced counts `superseded`. */
+    #hold(src, payload) {
+        if (!this.latest) {
+            src.held.push(payload);
+            if (src.held.length > DATAGRAM_RING) {
+                src.held.shift();
+                this.stats.superseded++;
+            }
+            return;
+        }
+        let seq;
+        try {
+            seq = decodeHeader(payload).header.seq;
+        }
+        catch {
+            this.stats.mismatch++;
+            return;
+        }
+        if (src.held.length) {
+            this.stats.superseded++;
+            if (!newer(seq, src.heldSeq))
+                return; // an older or equal `seq` arriving later
+        }
+        src.held[0] = payload;
+        src.heldSeq = seq;
+    }
+    /**
+     * The next payload ready on `src` without waiting (Rust `Source::poll_payload`), `END` once its
+     * track ended, `undefined` when nothing is ready: a stream source then holds one pending read
+     * (`recvGroup` / `readFrame`) that wakes the read when it settles.
+     */
+    #poll(src) {
+        if (!src.stream)
+            return src.held.length ? src.held.shift() : src.done ? END : undefined;
+        if (src.ready !== undefined) {
+            const r = src.ready;
+            src.ready = undefined;
+            return r;
+        }
+        if (src.wait)
+            return undefined;
+        for (;;) {
+            const g = src.group;
+            if (g) {
+                const f = g.tryReadFrame();
+                if (f)
+                    return f.payload;
+                // The group ended, or moq expired it (the read fell behind its budget): the next one.
+                if (g.done || g.closed.peek() instanceof Error) {
+                    src.group = undefined;
+                    continue;
+                }
+                src.wait = g.readFrame().then(f => { if (f)
+                    src.ready = f.payload;
+                else if (src.group === g)
+                    src.group = undefined; }, () => { if (src.group === g)
+                    src.group = undefined; }).finally(() => { src.wait = undefined; this.#signal(); });
+                return undefined;
+            }
+            let next;
+            try {
+                next = src.sub.tryRecvGroup();
+            }
+            catch {
+                return END;
+            }
+            if (next) {
+                src.group = next;
+                continue;
+            }
+            src.wait = src.sub.recvGroup().then(r => { if (r)
+                src.group = r;
+            else
+                src.ready = END; }, () => { src.ready = END; }).finally(() => { src.wait = undefined; this.#signal(); });
+            return undefined;
+        }
+    }
+    /** The publisher leaves the read: its subscription and request are closed, a payload it gave is never returned. */
+    removeSource(src) {
+        const i = this.#sources.indexOf(src);
+        if (i >= 0)
+            this.#sources.splice(i, 1);
+        closeSource(src);
+        this.#signal();
+    }
+    /** A `fec` follower's frame: latest mode replaces the publisher's pending one. */
+    pushFec(env) {
+        if (this.latest) {
+            const i = this.#fec.findIndex(e => e.publisher === env.publisher);
+            if (i >= 0) {
+                this.#fec[i] = env;
+                this.stats.superseded++;
+            }
+            else
+                this.#fec.push(env);
+        }
+        else {
+            this.#fec.push(env);
+            if (this.#fec.length > FEC_QUEUE_CAP) {
+                this.#fec.shift();
+                this.stats.superseded++;
+            }
+        }
+        this.#signal();
+    }
+    dropFecOf(publisher) { for (let i = this.#fec.length - 1; i >= 0; i--)
+        if (this.#fec[i].publisher === publisher)
+            this.#fec.splice(i, 1); }
+    /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
+    clearFec() { this.#fec.length = 0; this.#throttled = undefined; }
+    #signal() { const w = this.#wake; this.#wake = undefined; w?.resolve(); }
+    /**
+     * The established descriptor's `content_type` (the catalog's, the runtime's statement), set by the
+     * follow task from each snapshot: bodies decode by it, not by what this subscription declared.
+     */
+    contentType;
+    /** The decoding step: header facts plus the body by the established `content_type` (msgpack → a value, validated when the contract has a schema; anything else → bytes), or `mismatch` and dropped. */
+    envelope(payload, publisher, dom) {
+        let header, hlen;
+        try {
+            ({ header, hlen } = decodeHeader(payload));
+        }
+        catch {
+            this.stats.mismatch++;
+            return undefined;
+        }
+        const body = payload.subarray(hlen);
+        let data;
+        if ((this.contentType ?? this.contract.contentType) !== MSGPACK)
+            data = body;
+        else {
+            let v;
+            try {
+                v = decodeBody(body);
+            }
+            catch {
+                this.stats.mismatch++;
+                return undefined;
+            }
+            if (this.contract.schema) {
+                const r = validateSync(this.contract.schema, v);
+                if (r.issues) {
+                    this.stats.mismatch++;
+                    return undefined;
+                }
+                v = r.value;
+            }
+            data = v;
+        }
+        const f = header.flags;
+        return { data, tUs: Number(header.tUs), seq: header.seq, publisher, dom, flags: f, type: header.type, tlvs: header.tlvs ?? [], key: (f & FLAGS.KEY) !== 0, config: (f & FLAGS.CONFIG) !== 0, recovery: (f & FLAGS.RECOVERY) !== 0 };
+    }
+    /** One payload taken from `src` (Rust `drain_source`'s step): every-message mode keeps it, latest mode keeps the newest `seq`. */
+    #take(src, payload, t, nowUs_) {
+        if (!this.latest && this.#deadlineUs === undefined) {
+            const e = this.envelope(payload, src.publisher, src.dom);
+            if (e)
+                t.out.push(e);
+            return;
+        }
+        // The header only: a superseded message's body is never decoded.
+        let h;
+        try {
+            h = decodeHeader(payload).header;
+        }
+        catch {
+            this.stats.mismatch++;
+            return;
+        }
+        if (this.#deadlineUs !== undefined && src.dom === this.ownDom && nowUs_ - Number(h.tUs) > this.#deadlineUs) {
+            this.stats.staleDrops++;
+            return;
+        }
+        if (!this.latest) {
+            const e = this.envelope(payload, src.publisher, src.dom);
+            if (e)
+                t.out.push(e);
+            return;
+        }
+        if (src.last !== undefined && !newer(h.seq, src.last)) {
+            this.stats.superseded++;
+            return;
+        }
+        if (t.newest && !newer(h.seq, t.newest.seq)) {
+            this.stats.superseded++;
+            return;
+        }
+        if (t.newest)
+            this.stats.superseded++;
+        t.newest = { seq: h.seq, payload };
+    }
+    /**
+     * The next batch, never empty; `undefined` once the subscription or the node ended. Drains what
+     * every source has ready, synchronously (at most `DRAIN_PER_READ` per source), and the `fec`
+     * frames; with nothing to return it waits for a source's pending read or reader, a `fec` frame,
+     * a change of the set or the end of a `throttleMs` interval, and drains again.
+     */
+    async next() {
+        for (;;) {
+            if (this.#ended)
+                return undefined;
+            const out = [];
+            let more = false;
+            const now = nowUs();
+            for (const src of [...this.#sources]) {
+                const t = { newest: undefined, out, count: 0 };
+                for (;;) {
+                    if (t.count === DRAIN_PER_READ) {
+                        more = true;
+                        break;
+                    } // what is left is taken by the next read
+                    const p = this.#poll(src);
+                    if (p === undefined)
+                        break;
+                    if (p === END) {
+                        src.ended = true;
+                        break;
+                    }
+                    t.count++;
+                    this.#take(src, p, t, now);
+                }
+                if (t.newest) {
+                    const e = this.envelope(t.newest.payload, src.publisher, src.dom);
+                    if (e) {
+                        src.last = t.newest.seq;
+                        out.push(e);
+                    }
+                }
+                // A source whose track ended leaves the read.
+                if (src.ended) {
+                    this.#sources.splice(this.#sources.indexOf(src), 1);
+                    closeSource(src);
+                }
+            }
+            // The `fec` frames: already one per publisher in latest mode (see `pushFec`); the drop-late rule here, at the read.
+            for (const env of this.#fec.splice(0)) {
+                if (this.#deadlineUs !== undefined && env.dom === this.ownDom && now - env.tUs > this.#deadlineUs) {
+                    this.stats.staleDrops++;
+                    continue;
+                }
+                out.push(env);
+            }
+            const batch = this.#throttle(out);
+            if (batch) {
+                this.stats.read += batch.length;
+                return batch;
+            }
+            // Everything taken was dropped while a source is at its per-read bound: drain again at once.
+            if (more)
+                continue;
+            // Woken by a source's pending read or reader, a `fec` frame, a change of the set, the throttle's end, the end.
+            this.#wake ??= deferred();
+            await this.#wake.promise;
+        }
+    }
+    /**
+     * `throttleMs`: at most one batch per interval; a batch inside the interval is held (newest per
+     * publisher) and merged into the next; when the interval ends a waiting `next()` returns it.
+     */
+    #throttle(out) {
+        const t = this.opts.throttleMs;
+        if (t === undefined)
+            return out.length ? out : undefined;
+        const now = performance.now();
+        const held = this.#throttled ?? [];
+        for (const e of out) {
+            const i = held.findIndex(h => h.publisher === e.publisher);
+            if (i >= 0) {
+                held[i] = e;
+                this.stats.coalesced++;
+            }
+            else
+                held.push(e);
+        }
+        if (!held.length)
+            return undefined;
+        if (now < this.#throttleUntil) {
+            this.#throttled = held;
+            this.#throttleTimer ??= setTimeout(() => { this.#throttleTimer = undefined; this.#signal(); }, this.#throttleUntil - now);
+            return undefined;
+        }
+        this.#throttled = undefined;
+        this.#throttleUntil = now + t;
+        return held;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const b = await this.next();
+            if (!b)
+                return;
+            yield b;
+        }
+    }
+    /** Ends the subscription: the follow task stops, every track is closed, a pending `next()` returns `undefined`. */
+    unsubscribe() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#stop.abort();
+        for (const s of this.#sources.splice(0))
+            closeSource(s);
+        this.#fec.length = 0;
+        this.#throttled = undefined;
+        if (this.#throttleTimer !== undefined) {
+            clearTimeout(this.#throttleTimer);
+            this.#throttleTimer = undefined;
+        }
+        this.#signal();
+    }
+    async [Symbol.asyncDispose]() { this.unsubscribe(); }
+}
+/** A source is done: its subscription and its request are closed (its pending read settles as the end). */
+function closeSource(src) {
+    src.ended = true;
+    try {
+        src.sub.close();
+    }
+    catch { /* closed */ }
+    try {
+        src.req.close();
+    }
+    catch { /* closed */ }
+}
+/**
+ * The task behind one subscription (control path only, never a frame): follows the topic as the
+ * module docs say. Interrupted by a session change, a catalog change or the node's end.
+ */
+async function followTopic(sub) {
+    const { node, contract, opts } = sub;
+    // Unbounded, as the Rust task's event channel: no session event is ever dropped.
+    const events = new AsyncQueue(Infinity);
+    const { session: first, unmonitor } = node.monitor(e => events.push(e));
+    let session = first;
+    let epoch;
+    let snapshot;
+    const have = new Map();
+    /** The publishers tried on this snapshot (held or failed): each listed one is tried once per snapshot. */
+    let tried = new Set();
+    const stopAll = async () => { for (const [, f] of have)
+        if (f.following.kind === "fec") {
+            f.following.stop.abort();
+            await f.following.done;
+        } have.clear(); };
+    const ended = (f) => f.following.kind === "plain" ? f.following.src.ended : f.following.finished;
+    let pending;
+    const onStop = () => events.push({ kind: "nodeEnded" });
+    sub.signal.addEventListener("abort", onStop, { once: true });
+    try {
+        for (;;) {
+            if (sub.signal.aborted)
+                return;
+            if (pending) {
+                if (pending.kind === "started")
+                    session = pending.session;
+                else if (pending.kind === "ended")
+                    session = undefined;
+                else
+                    return;
+                pending = undefined;
+            }
+            if (session?.epoch !== epoch) {
+                epoch = session?.epoch;
+                snapshot = session?.topics.get();
+                // Everything followed is the previous session's (Rust `Change::Reset`): the read's sources
+                // leave first, then the `fec` followers stop, then what they handed to the read is cleared.
+                for (const [, f] of have)
+                    if (f.following.kind === "plain")
+                        sub.removeSource(f.following.src);
+                await stopAll();
+                tried = new Set();
+                sub.clearFec();
+            }
+            const todo = [];
+            // The topic's delivery is the catalog's (the established descriptor): a bare-name subscription has no contract to say.
+            let delivery = contract.delivery;
+            if (session && snapshot) {
+                const entry = snapshot.topics[contract.name];
+                delivery = entry?.desc?.delivery ?? contract.delivery;
+                // ... and so is the body's `content_type` (what the read decodes by).
+                sub.contentType = entry?.desc?.content_type;
+                const wanted = new Map();
+                if (entry)
+                    for (const [prefix, l] of Object.entries(entry.publishers))
+                        if (prefix !== session.prefix)
+                            wanted.set(topicPath(prefix, l.bind, contract.name), { prefix, name: l.name });
+                for (const [path, f] of [...have]) {
+                    if (wanted.has(path) && !ended(f))
+                        continue;
+                    have.delete(path);
+                    if (f.following.kind === "fec") {
+                        f.following.stop.abort();
+                        await f.following.done;
+                        sub.dropFecOf(f.publisher);
+                    }
+                    else
+                        sub.removeSource(f.following.src);
+                }
+                for (const p of [...tried])
+                    if (!wanted.has(p))
+                        tried.delete(p);
+                for (const [path, w] of wanted)
+                    if (!have.has(path) && !tried.has(path))
+                        todo.push({ path, ...w });
+            }
+            const s = session;
+            const nextEvent = events.next();
+            const catalogChanged = s ? s.topics.changed() : new Promise(() => { });
+            const passAbort = new AbortController();
+            const pass = (async () => {
+                if (!s)
+                    return;
+                for (const t of todo) {
+                    if (passAbort.signal.aborted)
+                        return;
+                    tried.add(t.path);
+                    // One addition, stopped by the pass's end or by its bound: a stopped addition closes what it opened.
+                    const one = new AbortController();
+                    const stopOne = () => one.abort();
+                    passAbort.signal.addEventListener("abort", stopOne, { once: true });
+                    try {
+                        const adding = add(s, t.path, delivery, opts, one.signal);
+                        const added = await withTimeout(adding, ADD_WITHIN_MS);
+                        if (added === TIMEOUT) {
+                            one.abort();
+                            adding.then(closeAdded, () => { });
+                            sub.warn(`topic ${contract.name}: listed publisher ${t.prefix} not subscribed within ${ADD_WITHIN_MS} ms; tried again at the next catalog change`);
+                            continue;
+                        }
+                        if (passAbort.signal.aborted) {
+                            closeAdded(added);
+                            continue;
+                        }
+                        if (added.kind === "plain") {
+                            const src = { path: t.path, prefix: t.prefix, publisher: t.name, dom: added.dom, req: added.req, sub: added.sub, stream: added.stream, group: undefined, wait: undefined, ready: undefined, held: [], heldSeq: undefined, done: false, last: undefined, ended: false };
+                            sub.addSource(src);
+                            have.set(t.path, { prefix: t.prefix, publisher: t.name, following: { kind: "plain", src } });
+                        }
+                        else {
+                            const stop = new AbortController();
+                            const following = { kind: "fec", stop, done: Promise.resolve(), finished: false };
+                            following.done = followFec(sub, s, t.prefix, t.name, added.req, added.bc, added.desc, stop.signal).finally(() => { following.finished = true; });
+                            have.set(t.path, { prefix: t.prefix, publisher: t.name, following });
+                        }
+                    }
+                    catch (e) {
+                        sub.warn(`topic ${contract.name}: listed publisher ${t.prefix} not subscribed (${e instanceof Error ? e.message : String(e)}); tried again at the next catalog change`);
+                    }
+                    finally {
+                        passAbort.signal.removeEventListener("abort", stopOne);
+                    }
+                }
+            })();
+            const woke = await Promise.race([nextEvent.then(e => ({ kind: "event", e })), catalogChanged.then(() => ({ kind: "catalog" })), pass.then(() => ({ kind: "pass" }))]);
+            if (woke.kind === "event") {
+                passAbort.abort();
+                pending = woke.e ?? { kind: "nodeEnded" };
+            }
+            else if (woke.kind === "catalog") {
+                passAbort.abort();
+                snapshot = s.topics.get();
+                tried = new Set();
+            }
+            else if (!todo.length) {
+                // Nothing to do: wait for the next event or catalog change.
+                const w = await Promise.race([nextEvent.then(e => ({ kind: "event", e })), catalogChanged.then(() => ({ kind: "catalog" }))]);
+                if (w.kind === "event")
+                    pending = w.e ?? { kind: "nodeEnded" };
+                else {
+                    snapshot = s.topics.get();
+                    tried = new Set();
+                }
+            }
+        }
+    }
+    finally {
+        sub.signal.removeEventListener("abort", onStop);
+        unmonitor();
+        await stopAll();
+        void events.close(true);
+        sub.unsubscribe();
+    }
+}
+/** Closes an addition nobody took (its pass ended, or it came in after its bound). */
+function closeAdded(a) {
+    if (a.kind === "plain") {
+        try {
+            a.sub.close();
+        }
+        catch { /* closed */ }
+    }
+    else {
+        try {
+            a.bc.close();
+        }
+        catch { /* closed */ }
+    }
+    try {
+        a.req.close();
+    }
+    catch { /* closed */ }
+}
+/**
+ * Subscribes to publisher `path`'s `data` track on `s`; its own `desc` is read first (its time
+ * domain and its `fec`). A failed or stopped (`signal`) addition closes its request.
+ */
+async function add(s, path, delivery, opts, signal) {
+    const req = s.request(path);
+    try {
+        const bc = await waitActive(req, ADD_WITHIN_MS, signal);
+        const desc = await ownDesc(bc, signal);
+        if (signal.aborted)
+            throw new SynapseError("canceled", "aborted");
+        if (!desc)
+            throw new Error("no readable descriptor");
+        const dom = desc.dom.id;
+        if (delivery === "datagram" && desc.fec)
+            return { kind: "fec", req, bc, desc };
+        const priority = moqPriority(opts.priority ?? 3);
+        const sub = bc.track("data").subscribe(delivery === "stream" ? streamTopicSubscription(priority) : latestSubscription(priority, opts.maxAgeMs ?? 0));
+        return { kind: "plain", req, sub, dom, stream: delivery === "stream" };
+    }
+    catch (e) {
+        try {
+            req.close();
+        }
+        catch { /* closed */ }
+        throw e;
+    }
+}
+/** The publisher's own descriptor from its `desc` track; a stopped `signal` closes the track and reads as none. */
+async function ownDesc(bc, signal) {
+    if (signal.aborted)
+        return undefined;
+    const sub = bc.track("desc").subscribe(latestSubscription(moqPriority(0)));
+    const stop = () => sub.close();
+    signal.addEventListener("abort", stop, { once: true });
+    try {
+        const g = await sub.recvGroup();
+        if (!g)
+            return undefined;
+        const f = await g.readFrame();
+        if (!f)
+            return undefined;
+        const { hlen } = decodeHeader(f.payload);
+        const d = decodeBody(f.payload.subarray(hlen));
+        return d && typeof d === "object" && d.dom && typeof d.dom.id === "string" ? d : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        signal.removeEventListener("abort", stop);
+        sub.close();
+    }
+}
+/**
+ * The publisher's frames on a `fec` topic: every datagram through its `FecReader`, polled after each
+ * and every 10 ms; frames into the subscription's `fec` queue; one `REPORT` a second while datagrams
+ * arrive. Ends when stopped, when the broadcast ends or fails, or when the codec is missing (warned;
+ * tried again at the next catalog change like every listed publisher).
+ */
+async function followFec(sub, s, prefix, publisher, req, bc, desc, signal) {
+    let reader;
+    let reports;
+    let tick;
+    let reportTick;
+    let track;
+    try {
+        const wasm = await requireFec(`topic ${sub.topic}`);
+        if (signal.aborted)
+            return;
+        const params = sub.opts.fecDeadlineMs !== undefined ? { ...(desc.fec), deadline_ms: sub.opts.fecDeadlineMs } : desc.fec;
+        reader = new FecReader(wasm, params, sub.opts.fecDeadlineMs);
+        const r = reader;
+        track = bc.track("data").subscribe(latestSubscription(moqPriority(sub.opts.priority ?? 3), sub.opts.maxAgeMs ?? 0));
+        const t = track;
+        signal.addEventListener("abort", () => t.close(), { once: true });
+        let prev = r.stats();
+        const poll = () => {
+            for (const f of r.poll(nowUs())) {
+                const env = sub.envelope(f.frame, publisher, desc.dom.id);
+                if (env)
+                    sub.pushFec(env);
+            }
+            const st = r.stats();
+            sub.stats.fecGiveup += st.lost - prev.lost;
+            sub.stats.repaired += st.repaired - prev.repaired;
+            prev = st;
+        };
+        tick = setInterval(poll, 10);
+        let received = false;
+        if (sub.opts.fecFeedback ?? true) {
+            reports = new ReportWriter(s, prefix, sub.topic);
+            const w = reports;
+            reportTick = setInterval(() => { if (!received)
+                return; try {
+                w.write(r.takeReport());
+            }
+            catch {
+                w.close();
+                reports = undefined;
+                if (reportTick !== undefined)
+                    clearInterval(reportTick);
+            } }, 1000);
+        }
+        for (;;) {
+            const d = await t.recvDatagram();
+            if (!d)
+                break;
+            received = true;
+            if (!r.push(d.payload, nowUs()))
+                sub.stats.mismatch++;
+            poll();
+        }
+    }
+    catch (e) {
+        if (!signal.aborted)
+            sub.warn(`topic ${sub.topic}: follower of ${prefix} ended (${e instanceof Error ? e.message : String(e)}); tried again at the next catalog change`);
+    }
+    finally {
+        if (tick !== undefined)
+            clearInterval(tick);
+        if (reportTick !== undefined)
+            clearInterval(reportTick);
+        reports?.close();
+        try {
+            track?.close();
+        }
+        catch { /* closed */ }
+        reader?.close();
+        try {
+            bc.close();
+        }
+        catch { /* closed */ }
+        try {
+            req.close();
+        }
+        catch { /* closed */ }
+    }
+}