@norskvideo/moq-net 0.1.7 → 0.2.0

package/bandwidth.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Rate estimation split among the tracks sharing one connection.
+ *
+ * One estimate covers a whole connection, so senders sharing it divide it with
+ * an {@link Allocator} rather than each targeting the whole thing. How a sender
+ * then follows its share is policy and lives with the sender.
+ *
+ * @module
+ */
+import { type GetPromise, type Getter } from "@norskvideo/moq-signals";
+/**
+ * One demanded track's claim, snapshotted for {@link allocate}.
+ *
+ * `id` is the allocator's, not the track's sequence: two reservations of the
+ * same track are still two claims.
+ */
+export interface Want {
+    /** Allocator-assigned identity of this claim. */
+    id: number;
+    /** Publisher priority; higher is served first. */
+    priority: number;
+    /** Ceiling in bits per second, not a measurement of current output. */
+    max: number;
+}
+/**
+ * Divide `estimate` among `wants`, returning the slice for `id`.
+ *
+ * Strict priority: a tier is filled to its reservations before the next one
+ * sees a bit. Within a tier the split is max-min fair, so a share asking for
+ * less than an even split takes all of it and leaves the rest to the others.
+ *
+ * Surplus above the total reserved is left unclaimed rather than spread around.
+ * A reservation is what a sender can use, so handing it more is not a reason to
+ * send more than it was configured for.
+ *
+ * `undefined` when `id` isn't among the wants, which is how an idle or closed
+ * track reports "hold your rate" instead of a grant of zero.
+ *
+ * Rates are bits per second.
+ */
+export declare function allocate(estimate: number, wants: readonly Want[], id: number): number | undefined;
+/** What {@link Allocator.reserve} reads off a track. */
+export interface Demand {
+    /** Whether any subscriber is currently attached. */
+    readonly used: Getter<boolean>;
+    /** Settles once the track closes. */
+    readonly closed: GetPromise<Error | null>;
+    /** Publisher priority; higher is served first. */
+    readonly priority: number;
+}
+/**
+ * A non-owning handle on an allocator: reserve a slice, without its lifecycle.
+ *
+ * What a shared connection lends out. {@link Allocator} implements it, so code
+ * that is handed an allocator rather than owning one should accept this type:
+ * closing the registry stays the owner's alone, and a borrower cannot express it.
+ *
+ * @public
+ */
+export interface Handle {
+    /** Reserve up to `max` for `track`; see {@link Allocator.reserve}. */
+    reserve(track: Demand, max: number): Reservation;
+}
+/**
+ * Divides one connection's bandwidth estimate among the tracks sharing it.
+ *
+ * Every sender on a connection reads the same estimate, so N senders each
+ * targeting all of it oversubscribe the uplink N times over. Register a track
+ * here and it gets a {@link Reservation} reporting only its own slice, so the
+ * slices sum to the estimate instead of each matching it.
+ *
+ * Advisory, not enforced. A track that ignores its slice, or can't follow it at
+ * all (PCM audio has a fixed bitrate), still sends what it sends; the transport
+ * sheds the excess by dropping groups.
+ *
+ * Hand the same instance to every sender on the connection.
+ */
+export declare class Allocator implements Handle {
+    #private;
+    /**
+     * Divide `estimate`, normally a connection's sampled send rate.
+     *
+     * Omit it (or call {@link unlimited}) for nothing to divide: every reservation
+     * reports `undefined`, which already means "no opinion, hold your rate".
+     */
+    constructor(estimate?: Getter<number | undefined>);
+    /**
+     * An allocator with nothing to divide, so every reservation reports `undefined`.
+     *
+     * `undefined` already means "no opinion, hold your rate" to a sender, so this is
+     * what a transport with no congestion estimate, a local file, or a test harness
+     * wants.
+     */
+    static unlimited(): Allocator;
+    /**
+     * Reserve up to `max` for `track`, returning the reservation.
+     *
+     * `max` is a ceiling, not a measurement: reserve the most the track can ever
+     * send, not what it happens to be sending. A VBR encoder sitting on a black
+     * screen at 1 Mbps can jump to 6 Mbps between one frame and the next, and a
+     * reservation that had followed it down would have already handed that room
+     * to somebody else.
+     *
+     * Priority comes from the track (higher served first). A tier is filled to
+     * its reservations before the next one sees a bit; within a tier the split is
+     * max-min fair.
+     *
+     * The reservation lasts until {@link Reservation.close}: hold it for as long
+     * as the sender is publishing, change the ceiling with
+     * {@link Reservation.update}, and close it to hand the room back.
+     *
+     * {@link Reservation.peek} / {@link Reservation.grant} report `undefined`
+     * while nothing is subscribed to the track or the connection has no estimate.
+     * That tells a sender to hold its current rate rather than encode at zero.
+     */
+    reserve(track: Demand, max: number): Reservation;
+    /**
+     * Stop dividing. Existing reservations report `undefined` and further
+     * {@link reserve} calls still return a handle that never claims.
+     */
+    close(): void;
+}
+/**
+ * One track's standing claim on an {@link Allocator}, held for as long as the
+ * sender that took it is publishing.
+ *
+ * Close it to release the claim; a forgotten reservation keeps claiming until
+ * {@link close} (or {@link Symbol.dispose}) runs, and its siblings never get
+ * the room.
+ */
+export declare class Reservation implements Disposable {
+    #private;
+    private constructor();
+    /**
+     * This reservation's slice right now.
+     *
+     * Stateless, unlike {@link grant}, which is a signal of what was last
+     * published and so can lag a synchronous {@link update} by a microtask if
+     * something else writes the registry first. Call this after {@link update}.
+     */
+    peek(): number | undefined;
+    /**
+     * This reservation's current slice of the estimate.
+     *
+     * `undefined` while nothing is subscribed, the connection has no estimate, or
+     * this reservation has been closed: hold the current rate rather than encode
+     * at zero.
+     */
+    get grant(): Getter<number | undefined>;
+    /**
+     * Change the ceiling, keeping the same claim.
+     *
+     * For a sender whose ceiling genuinely moved: an encoder reopening at a
+     * resolution it negotiated with the device, not an encoder observing its own
+     * output.
+     */
+    update(max: number): void;
+    /** Release the claim so siblings take the room. Idempotent. */
+    close(): void;
+    /** Calls {@link close}, so `using` releases the claim. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=bandwidth.d.ts.map

package/bandwidth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth.d.ts","sourceRoot":"","sources":["../src/bandwidth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,MAAM,EAAU,MAAM,cAAc,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACpB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgCjG;AAED,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACtB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC1C,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAiCD;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACtB,sEAAsE;IACtE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,MAAM;;IAQvC;;;;;OAKG;IACH,YAAY,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,EAmBhD;IAED;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,IAAI,SAAS,CAE5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAmB/C;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAQZ;CA6CD;AAID;;;;;;;GAOG;AACH,qBAAa,WAAY,YAAW,UAAU;;IAM7C,OAAO,eAIN;IAMD;;;;;;OAMG;IACH,IAAI,IAAI,MAAM,GAAG,SAAS,CAGzB;IAED;;;;;;OAMG;IACH,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,CAEtC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGxB;IAED,+DAA+D;IAC/D,KAAK,IAAI,IAAI,CAKZ;IAED,0DAA0D;IAC1D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}

package/bandwidth.js

@@ -0,0 +1,304 @@
+/* @ts-self-types="./bandwidth.d.ts" */
+/**
+ * Rate estimation split among the tracks sharing one connection.
+ *
+ * One estimate covers a whole connection, so senders sharing it divide it with
+ * an {@link Allocator} rather than each targeting the whole thing. How a sender
+ * then follows its share is policy and lives with the sender.
+ *
+ * @module
+ */
+import { Effect, Signal } from "@norskvideo/moq-signals";
+/**
+ * Divide `estimate` among `wants`, returning the slice for `id`.
+ *
+ * Strict priority: a tier is filled to its reservations before the next one
+ * sees a bit. Within a tier the split is max-min fair, so a share asking for
+ * less than an even split takes all of it and leaves the rest to the others.
+ *
+ * Surplus above the total reserved is left unclaimed rather than spread around.
+ * A reservation is what a sender can use, so handing it more is not a reason to
+ * send more than it was configured for.
+ *
+ * `undefined` when `id` isn't among the wants, which is how an idle or closed
+ * track reports "hold your rate" instead of a grant of zero.
+ *
+ * Rates are bits per second.
+ */
+export function allocate(estimate, wants, id) {
+    // Integer bits per second: the same truncation the Rust allocator uses.
+    let budget = estimate;
+    let tier;
+    for (const want of wants) {
+        if (tier === undefined || want.priority > tier)
+            tier = want.priority;
+    }
+    while (tier !== undefined) {
+        // Ascending by reservation: each share takes an even cut of what's left, or
+        // all it asked for if that's less, which frees the difference for the rest.
+        const members = wants.filter((want) => want.priority === tier).sort((a, b) => a.max - b.max);
+        let remaining = members.length;
+        for (const want of members) {
+            const even = Math.floor(budget / remaining);
+            const grant = Math.min(want.max, even);
+            if (want.id === id)
+                return grant;
+            budget -= grant;
+            remaining -= 1;
+        }
+        let next;
+        for (const want of wants) {
+            if (want.priority < tier && (next === undefined || want.priority > next)) {
+                next = want.priority;
+            }
+        }
+        tier = next;
+    }
+    return undefined;
+}
+function wantsOf(entries) {
+    const wants = [];
+    for (const entry of entries) {
+        if (entry.demand.closed.peek() !== undefined)
+            continue;
+        if (!entry.demand.used.peek())
+            continue;
+        wants.push({ id: entry.id, priority: entry.priority, max: entry.max });
+    }
+    return wants;
+}
+function ceiling(max) {
+    if (!Number.isFinite(max) || max < 0) {
+        throw new Error(`reservation ceiling must be a finite non-negative number, got ${max}`);
+    }
+    return max;
+}
+/**
+ * Divides one connection's bandwidth estimate among the tracks sharing it.
+ *
+ * Every sender on a connection reads the same estimate, so N senders each
+ * targeting all of it oversubscribe the uplink N times over. Register a track
+ * here and it gets a {@link Reservation} reporting only its own slice, so the
+ * slices sum to the estimate instead of each matching it.
+ *
+ * Advisory, not enforced. A track that ignores its slice, or can't follow it at
+ * all (PCM audio has a fixed bitrate), still sends what it sends; the transport
+ * sheds the excess by dropping groups.
+ *
+ * Hand the same instance to every sender on the connection.
+ */
+export class Allocator {
+    #estimate;
+    #entries = new Signal([]);
+    #alive = new Signal(true);
+    #nextId = 0;
+    #signals = new Effect();
+    #registry;
+    /**
+     * Divide `estimate`, normally a connection's sampled send rate.
+     *
+     * Omit it (or call {@link unlimited}) for nothing to divide: every reservation
+     * reports `undefined`, which already means "no opinion, hold your rate".
+     */
+    constructor(estimate) {
+        this.#estimate = estimate;
+        this.#registry = {
+            peek: (id) => this.#peek(id),
+            update: (id, max) => this.#update(id, max),
+            release: (id) => this.#release(id),
+        };
+        this.#signals.run((effect) => {
+            if (!effect.get(this.#alive))
+                return;
+            if (this.#estimate)
+                effect.get(this.#estimate);
+            const entries = effect.get(this.#entries);
+            for (const entry of entries) {
+                effect.get(entry.demand.used);
+                effect.get(entry.demand.closed);
+            }
+            this.#publish();
+        });
+    }
+    /**
+     * An allocator with nothing to divide, so every reservation reports `undefined`.
+     *
+     * `undefined` already means "no opinion, hold your rate" to a sender, so this is
+     * what a transport with no congestion estimate, a local file, or a test harness
+     * wants.
+     */
+    static unlimited() {
+        return new Allocator();
+    }
+    /**
+     * Reserve up to `max` for `track`, returning the reservation.
+     *
+     * `max` is a ceiling, not a measurement: reserve the most the track can ever
+     * send, not what it happens to be sending. A VBR encoder sitting on a black
+     * screen at 1 Mbps can jump to 6 Mbps between one frame and the next, and a
+     * reservation that had followed it down would have already handed that room
+     * to somebody else.
+     *
+     * Priority comes from the track (higher served first). A tier is filled to
+     * its reservations before the next one sees a bit; within a tier the split is
+     * max-min fair.
+     *
+     * The reservation lasts until {@link Reservation.close}: hold it for as long
+     * as the sender is publishing, change the ceiling with
+     * {@link Reservation.update}, and close it to hand the room back.
+     *
+     * {@link Reservation.peek} / {@link Reservation.grant} report `undefined`
+     * while nothing is subscribed to the track or the connection has no estimate.
+     * That tells a sender to hold its current rate rather than encode at zero.
+     */
+    reserve(track, max) {
+        max = ceiling(max);
+        this.#prune();
+        const id = this.#nextId++;
+        const grant = new Signal(undefined);
+        this.#entries.mutate((entries) => {
+            entries.push({
+                id,
+                demand: track,
+                priority: track.priority,
+                max,
+                grant,
+            });
+        });
+        const reservation = makeReservation(this.#registry, id, grant);
+        this.#publish();
+        return reservation;
+    }
+    /**
+     * Stop dividing. Existing reservations report `undefined` and further
+     * {@link reserve} calls still return a handle that never claims.
+     */
+    close() {
+        if (!this.#alive.peek())
+            return;
+        this.#alive.set(false);
+        for (const entry of this.#entries.peek()) {
+            entry.grant.set(undefined);
+        }
+        this.#entries.set([]);
+        this.#signals.close();
+    }
+    #prune() {
+        const entries = this.#entries.peek();
+        const live = entries.filter((entry) => entry.demand.closed.peek() === undefined);
+        if (live.length !== entries.length)
+            this.#entries.set(live);
+    }
+    #publish() {
+        if (!this.#alive.peek())
+            return;
+        const estimate = this.#estimate?.peek();
+        const entries = this.#entries.peek();
+        const wants = wantsOf(entries);
+        for (const entry of entries) {
+            entry.grant.set(estimate == null ? undefined : allocate(estimate, wants, entry.id));
+        }
+    }
+    #peek(id) {
+        if (!this.#alive.peek())
+            return undefined;
+        const estimate = this.#estimate?.peek();
+        if (estimate == null)
+            return undefined;
+        const entries = this.#entries.peek();
+        if (!entries.some((entry) => entry.id === id))
+            return undefined;
+        return allocate(estimate, wantsOf(entries), id);
+    }
+    #update(id, max) {
+        if (!this.#alive.peek())
+            return;
+        max = ceiling(max);
+        this.#entries.mutate((entries) => {
+            const entry = entries.find((candidate) => candidate.id === id);
+            if (entry)
+                entry.max = max;
+        });
+        this.#publish();
+    }
+    #release(id) {
+        if (!this.#alive.peek())
+            return;
+        this.#entries.mutate((entries) => {
+            const index = entries.findIndex((entry) => entry.id === id);
+            if (index >= 0)
+                entries.splice(index, 1);
+        });
+        this.#publish();
+    }
+}
+let makeReservation;
+/**
+ * One track's standing claim on an {@link Allocator}, held for as long as the
+ * sender that took it is publishing.
+ *
+ * Close it to release the claim; a forgotten reservation keeps claiming until
+ * {@link close} (or {@link Symbol.dispose}) runs, and its siblings never get
+ * the room.
+ */
+export class Reservation {
+    #registry;
+    #id;
+    #grant;
+    #closed = false;
+    constructor(registry, id, grant) {
+        this.#registry = registry;
+        this.#id = id;
+        this.#grant = grant;
+    }
+    static {
+        makeReservation = (registry, id, grant) => new Reservation(registry, id, grant);
+    }
+    /**
+     * This reservation's slice right now.
+     *
+     * Stateless, unlike {@link grant}, which is a signal of what was last
+     * published and so can lag a synchronous {@link update} by a microtask if
+     * something else writes the registry first. Call this after {@link update}.
+     */
+    peek() {
+        if (this.#closed)
+            return undefined;
+        return this.#registry.peek(this.#id);
+    }
+    /**
+     * This reservation's current slice of the estimate.
+     *
+     * `undefined` while nothing is subscribed, the connection has no estimate, or
+     * this reservation has been closed: hold the current rate rather than encode
+     * at zero.
+     */
+    get grant() {
+        return this.#grant;
+    }
+    /**
+     * Change the ceiling, keeping the same claim.
+     *
+     * For a sender whose ceiling genuinely moved: an encoder reopening at a
+     * resolution it negotiated with the device, not an encoder observing its own
+     * output.
+     */
+    update(max) {
+        if (this.#closed)
+            return;
+        this.#registry.update(this.#id, max);
+    }
+    /** Release the claim so siblings take the room. Idempotent. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#grant.set(undefined);
+        this.#registry.release(this.#id);
+    }
+    /** Calls {@link close}, so `using` releases the claim. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=bandwidth.js.map

package/bandwidth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth.js","sourceRoot":"","sources":["../src/bandwidth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,EAAgC,MAAM,EAAE,MAAM,cAAc,CAAC;AAiB5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,KAAsB,EAAE,EAAU;IAC5E,wEAAwE;IACxE,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,IAAI,IAAwB,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,GAAG,IAAI;YAAE,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;IACtE,CAAC;IAED,OAAO,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,4EAA4E;QAC5E,4EAA4E;QAC5E,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAE7F,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACvC,IAAI,IAAI,CAAC,EAAE,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC;YAChB,SAAS,IAAI,CAAC,CAAC;QAChB,CAAC;QAED,IAAI,IAAwB,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;gBAC1E,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;YACtB,CAAC;QACF,CAAC;QACD,IAAI,GAAG,IAAI,CAAC;IACb,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AA0BD,SAAS,OAAO,CAAC,OAAyB;IACzC,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QACvD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,iEAAiE,GAAG,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAgBD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,SAAS;IACrB,SAAS,CAAyC;IAClD,QAAQ,GAAG,IAAI,MAAM,CAAU,EAAE,CAAC,CAAC;IACnC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC,CAAC;IACZ,QAAQ,GAAG,IAAI,MAAM,EAAE,CAAC;IACxB,SAAS,CAAW;IAEpB;;;;;OAKG;IACH,YAAY,QAAqC;QAChD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAE1B,IAAI,CAAC,SAAS,GAAG;YAChB,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC;YAC1C,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;SAClC,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,OAAO;YACrC,IAAI,IAAI,CAAC,SAAS;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC9B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,SAAS;QACf,OAAO,IAAI,SAAS,EAAE,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,KAAa,EAAE,GAAW;QACjC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,IAAI,MAAM,CAAqB,SAAS,CAAC,CAAC;QACxD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YAChC,OAAO,CAAC,IAAI,CAAC;gBACZ,EAAE;gBACF,MAAM,EAAE,KAAK;gBACb,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,GAAG;gBACH,KAAK;aACL,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,OAAO,WAAW,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,KAAK;QACJ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,OAAO;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1C,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,MAAM;QACL,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,SAAS,CAAC,CAAC;QACjF,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;YAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,QAAQ;QACP,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,OAAO;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC;IACF,CAAC;IAED,KAAK,CAAC,EAAU;QACf,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;QACxC,IAAI,QAAQ,IAAI,IAAI;YAAE,OAAO,SAAS,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;YAAE,OAAO,SAAS,CAAC;QAChE,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,EAAU,EAAE,GAAW;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,OAAO;QAChC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/D,IAAI,KAAK;gBAAE,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC;IAED,QAAQ,CAAC,EAAU;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,OAAO;QAChC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5D,IAAI,KAAK,IAAI,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC;CACD;AAED,IAAI,eAAmG,CAAC;AAExG;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACd,SAAS,CAAW;IACpB,GAAG,CAAS;IACZ,MAAM,CAA6B;IAC5C,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAoB,QAAkB,EAAE,EAAU,EAAE,KAAiC;QACpF,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;QACC,eAAe,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IACjF,CAAC;IAED;;;;;;OAMG;IACH,IAAI;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACnC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAW;QACjB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,+DAA+D;IAC/D,KAAK;QACJ,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,0DAA0D;IAC1D,CAAC,MAAM,CAAC,OAAO,CAAC;QACf,IAAI,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;CACD","sourcesContent":["/**\n * Rate estimation split among the tracks sharing one connection.\n *\n * One estimate covers a whole connection, so senders sharing it divide it with\n * an {@link Allocator} rather than each targeting the whole thing. How a sender\n * then follows its share is policy and lives with the sender.\n *\n * @module\n */\nimport { Effect, type GetPromise, type Getter, Signal } from \"@moq/signals\";\n\n/**\n * One demanded track's claim, snapshotted for {@link allocate}.\n *\n * `id` is the allocator's, not the track's sequence: two reservations of the\n * same track are still two claims.\n */\nexport interface Want {\n\t/** Allocator-assigned identity of this claim. */\n\tid: number;\n\t/** Publisher priority; higher is served first. */\n\tpriority: number;\n\t/** Ceiling in bits per second, not a measurement of current output. */\n\tmax: number;\n}\n\n/**\n * Divide `estimate` among `wants`, returning the slice for `id`.\n *\n * Strict priority: a tier is filled to its reservations before the next one\n * sees a bit. Within a tier the split is max-min fair, so a share asking for\n * less than an even split takes all of it and leaves the rest to the others.\n *\n * Surplus above the total reserved is left unclaimed rather than spread around.\n * A reservation is what a sender can use, so handing it more is not a reason to\n * send more than it was configured for.\n *\n * `undefined` when `id` isn't among the wants, which is how an idle or closed\n * track reports \"hold your rate\" instead of a grant of zero.\n *\n * Rates are bits per second.\n */\nexport function allocate(estimate: number, wants: readonly Want[], id: number): number | undefined {\n\t// Integer bits per second: the same truncation the Rust allocator uses.\n\tlet budget = estimate;\n\tlet tier: number | undefined;\n\tfor (const want of wants) {\n\t\tif (tier === undefined || want.priority > tier) tier = want.priority;\n\t}\n\n\twhile (tier !== undefined) {\n\t\t// Ascending by reservation: each share takes an even cut of what's left, or\n\t\t// all it asked for if that's less, which frees the difference for the rest.\n\t\tconst members = wants.filter((want) => want.priority === tier).sort((a, b) => a.max - b.max);\n\n\t\tlet remaining = members.length;\n\t\tfor (const want of members) {\n\t\t\tconst even = Math.floor(budget / remaining);\n\t\t\tconst grant = Math.min(want.max, even);\n\t\t\tif (want.id === id) return grant;\n\t\t\tbudget -= grant;\n\t\t\tremaining -= 1;\n\t\t}\n\n\t\tlet next: number | undefined;\n\t\tfor (const want of wants) {\n\t\t\tif (want.priority < tier && (next === undefined || want.priority > next)) {\n\t\t\t\tnext = want.priority;\n\t\t\t}\n\t\t}\n\t\ttier = next;\n\t}\n\n\treturn undefined;\n}\n\n/** What {@link Allocator.reserve} reads off a track. */\nexport interface Demand {\n\t/** Whether any subscriber is currently attached. */\n\treadonly used: Getter<boolean>;\n\t/** Settles once the track closes. */\n\treadonly closed: GetPromise<Error | null>;\n\t/** Publisher priority; higher is served first. */\n\treadonly priority: number;\n}\n\ninterface Entry {\n\tid: number;\n\tdemand: Demand;\n\tpriority: number;\n\tmax: number;\n\tgrant: Signal<number | undefined>;\n}\n\ninterface Registry {\n\tpeek(id: number): number | undefined;\n\tupdate(id: number, max: number): void;\n\trelease(id: number): void;\n}\n\nfunction wantsOf(entries: readonly Entry[]): Want[] {\n\tconst wants: Want[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.demand.closed.peek() !== undefined) continue;\n\t\tif (!entry.demand.used.peek()) continue;\n\t\twants.push({ id: entry.id, priority: entry.priority, max: entry.max });\n\t}\n\treturn wants;\n}\n\nfunction ceiling(max: number): number {\n\tif (!Number.isFinite(max) || max < 0) {\n\t\tthrow new Error(`reservation ceiling must be a finite non-negative number, got ${max}`);\n\t}\n\treturn max;\n}\n\n/**\n * A non-owning handle on an allocator: reserve a slice, without its lifecycle.\n *\n * What a shared connection lends out. {@link Allocator} implements it, so code\n * that is handed an allocator rather than owning one should accept this type:\n * closing the registry stays the owner's alone, and a borrower cannot express it.\n *\n * @public\n */\nexport interface Handle {\n\t/** Reserve up to `max` for `track`; see {@link Allocator.reserve}. */\n\treserve(track: Demand, max: number): Reservation;\n}\n\n/**\n * Divides one connection's bandwidth estimate among the tracks sharing it.\n *\n * Every sender on a connection reads the same estimate, so N senders each\n * targeting all of it oversubscribe the uplink N times over. Register a track\n * here and it gets a {@link Reservation} reporting only its own slice, so the\n * slices sum to the estimate instead of each matching it.\n *\n * Advisory, not enforced. A track that ignores its slice, or can't follow it at\n * all (PCM audio has a fixed bitrate), still sends what it sends; the transport\n * sheds the excess by dropping groups.\n *\n * Hand the same instance to every sender on the connection.\n */\nexport class Allocator implements Handle {\n\t#estimate: Getter<number | undefined> | undefined;\n\t#entries = new Signal<Entry[]>([]);\n\t#alive = new Signal(true);\n\t#nextId = 0;\n\t#signals = new Effect();\n\t#registry: Registry;\n\n\t/**\n\t * Divide `estimate`, normally a connection's sampled send rate.\n\t *\n\t * Omit it (or call {@link unlimited}) for nothing to divide: every reservation\n\t * reports `undefined`, which already means \"no opinion, hold your rate\".\n\t */\n\tconstructor(estimate?: Getter<number | undefined>) {\n\t\tthis.#estimate = estimate;\n\n\t\tthis.#registry = {\n\t\t\tpeek: (id) => this.#peek(id),\n\t\t\tupdate: (id, max) => this.#update(id, max),\n\t\t\trelease: (id) => this.#release(id),\n\t\t};\n\n\t\tthis.#signals.run((effect) => {\n\t\t\tif (!effect.get(this.#alive)) return;\n\t\t\tif (this.#estimate) effect.get(this.#estimate);\n\t\t\tconst entries = effect.get(this.#entries);\n\t\t\tfor (const entry of entries) {\n\t\t\t\teffect.get(entry.demand.used);\n\t\t\t\teffect.get(entry.demand.closed);\n\t\t\t}\n\t\t\tthis.#publish();\n\t\t});\n\t}\n\n\t/**\n\t * An allocator with nothing to divide, so every reservation reports `undefined`.\n\t *\n\t * `undefined` already means \"no opinion, hold your rate\" to a sender, so this is\n\t * what a transport with no congestion estimate, a local file, or a test harness\n\t * wants.\n\t */\n\tstatic unlimited(): Allocator {\n\t\treturn new Allocator();\n\t}\n\n\t/**\n\t * Reserve up to `max` for `track`, returning the reservation.\n\t *\n\t * `max` is a ceiling, not a measurement: reserve the most the track can ever\n\t * send, not what it happens to be sending. A VBR encoder sitting on a black\n\t * screen at 1 Mbps can jump to 6 Mbps between one frame and the next, and a\n\t * reservation that had followed it down would have already handed that room\n\t * to somebody else.\n\t *\n\t * Priority comes from the track (higher served first). A tier is filled to\n\t * its reservations before the next one sees a bit; within a tier the split is\n\t * max-min fair.\n\t *\n\t * The reservation lasts until {@link Reservation.close}: hold it for as long\n\t * as the sender is publishing, change the ceiling with\n\t * {@link Reservation.update}, and close it to hand the room back.\n\t *\n\t * {@link Reservation.peek} / {@link Reservation.grant} report `undefined`\n\t * while nothing is subscribed to the track or the connection has no estimate.\n\t * That tells a sender to hold its current rate rather than encode at zero.\n\t */\n\treserve(track: Demand, max: number): Reservation {\n\t\tmax = ceiling(max);\n\t\tthis.#prune();\n\n\t\tconst id = this.#nextId++;\n\t\tconst grant = new Signal<number | undefined>(undefined);\n\t\tthis.#entries.mutate((entries) => {\n\t\t\tentries.push({\n\t\t\t\tid,\n\t\t\t\tdemand: track,\n\t\t\t\tpriority: track.priority,\n\t\t\t\tmax,\n\t\t\t\tgrant,\n\t\t\t});\n\t\t});\n\n\t\tconst reservation = makeReservation(this.#registry, id, grant);\n\t\tthis.#publish();\n\t\treturn reservation;\n\t}\n\n\t/**\n\t * Stop dividing. Existing reservations report `undefined` and further\n\t * {@link reserve} calls still return a handle that never claims.\n\t */\n\tclose(): void {\n\t\tif (!this.#alive.peek()) return;\n\t\tthis.#alive.set(false);\n\t\tfor (const entry of this.#entries.peek()) {\n\t\t\tentry.grant.set(undefined);\n\t\t}\n\t\tthis.#entries.set([]);\n\t\tthis.#signals.close();\n\t}\n\n\t#prune(): void {\n\t\tconst entries = this.#entries.peek();\n\t\tconst live = entries.filter((entry) => entry.demand.closed.peek() === undefined);\n\t\tif (live.length !== entries.length) this.#entries.set(live);\n\t}\n\n\t#publish(): void {\n\t\tif (!this.#alive.peek()) return;\n\t\tconst estimate = this.#estimate?.peek();\n\t\tconst entries = this.#entries.peek();\n\t\tconst wants = wantsOf(entries);\n\t\tfor (const entry of entries) {\n\t\t\tentry.grant.set(estimate == null ? undefined : allocate(estimate, wants, entry.id));\n\t\t}\n\t}\n\n\t#peek(id: number): number | undefined {\n\t\tif (!this.#alive.peek()) return undefined;\n\t\tconst estimate = this.#estimate?.peek();\n\t\tif (estimate == null) return undefined;\n\t\tconst entries = this.#entries.peek();\n\t\tif (!entries.some((entry) => entry.id === id)) return undefined;\n\t\treturn allocate(estimate, wantsOf(entries), id);\n\t}\n\n\t#update(id: number, max: number): void {\n\t\tif (!this.#alive.peek()) return;\n\t\tmax = ceiling(max);\n\t\tthis.#entries.mutate((entries) => {\n\t\t\tconst entry = entries.find((candidate) => candidate.id === id);\n\t\t\tif (entry) entry.max = max;\n\t\t});\n\t\tthis.#publish();\n\t}\n\n\t#release(id: number): void {\n\t\tif (!this.#alive.peek()) return;\n\t\tthis.#entries.mutate((entries) => {\n\t\t\tconst index = entries.findIndex((entry) => entry.id === id);\n\t\t\tif (index >= 0) entries.splice(index, 1);\n\t\t});\n\t\tthis.#publish();\n\t}\n}\n\nlet makeReservation: (registry: Registry, id: number, grant: Signal<number | undefined>) => Reservation;\n\n/**\n * One track's standing claim on an {@link Allocator}, held for as long as the\n * sender that took it is publishing.\n *\n * Close it to release the claim; a forgotten reservation keeps claiming until\n * {@link close} (or {@link Symbol.dispose}) runs, and its siblings never get\n * the room.\n */\nexport class Reservation implements Disposable {\n\treadonly #registry: Registry;\n\treadonly #id: number;\n\treadonly #grant: Signal<number | undefined>;\n\t#closed = false;\n\n\tprivate constructor(registry: Registry, id: number, grant: Signal<number | undefined>) {\n\t\tthis.#registry = registry;\n\t\tthis.#id = id;\n\t\tthis.#grant = grant;\n\t}\n\n\tstatic {\n\t\tmakeReservation = (registry, id, grant) => new Reservation(registry, id, grant);\n\t}\n\n\t/**\n\t * This reservation's slice right now.\n\t *\n\t * Stateless, unlike {@link grant}, which is a signal of what was last\n\t * published and so can lag a synchronous {@link update} by a microtask if\n\t * something else writes the registry first. Call this after {@link update}.\n\t */\n\tpeek(): number | undefined {\n\t\tif (this.#closed) return undefined;\n\t\treturn this.#registry.peek(this.#id);\n\t}\n\n\t/**\n\t * This reservation's current slice of the estimate.\n\t *\n\t * `undefined` while nothing is subscribed, the connection has no estimate, or\n\t * this reservation has been closed: hold the current rate rather than encode\n\t * at zero.\n\t */\n\tget grant(): Getter<number | undefined> {\n\t\treturn this.#grant;\n\t}\n\n\t/**\n\t * Change the ceiling, keeping the same claim.\n\t *\n\t * For a sender whose ceiling genuinely moved: an encoder reopening at a\n\t * resolution it negotiated with the device, not an encoder observing its own\n\t * output.\n\t */\n\tupdate(max: number): void {\n\t\tif (this.#closed) return;\n\t\tthis.#registry.update(this.#id, max);\n\t}\n\n\t/** Release the claim so siblings take the room. Idempotent. */\n\tclose(): void {\n\t\tif (this.#closed) return;\n\t\tthis.#closed = true;\n\t\tthis.#grant.set(undefined);\n\t\tthis.#registry.release(this.#id);\n\t}\n\n\t/** Calls {@link close}, so `using` releases the claim. */\n\t[Symbol.dispose](): void {\n\t\tthis.close();\n\t}\n}\n"]}

package/bandwidth_api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public bandwidth allocation handles.
+ *
+ * @module
+ */
+export { Allocator, type Demand, type Handle, Reservation } from "./bandwidth";
+//# sourceMappingURL=bandwidth_api.d.ts.map

package/bandwidth_api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth_api.d.ts","sourceRoot":"","sources":["../src/bandwidth_api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/bandwidth_api.js

@@ -0,0 +1,8 @@
+/* @ts-self-types="./bandwidth_api.d.ts" */
+/**
+ * Public bandwidth allocation handles.
+ *
+ * @module
+ */
+export { Allocator, Reservation } from "./bandwidth.js";
+//# sourceMappingURL=bandwidth_api.js.map

package/bandwidth_api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth_api.js","sourceRoot":"","sources":["../src/bandwidth_api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAA4B,WAAW,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * Public bandwidth allocation handles.\n *\n * @module\n */\nexport { Allocator, type Demand, type Handle, Reservation } from \"./bandwidth.ts\";\n"]}

package/broadcast.d.ts

@@ -4,52 +4,74 @@
  * @module
  */
 import { type GetPromise } from "@norskvideo/moq-signals";
-import type { Consumer as GroupConsumer } from "./group";
+import { Route } from "./hop";
+import * as Path from "./path";
 import * as track from "./track";
 /**
  * The write side of a broadcast.
  *
  * @public
  */
-export declare class Producer implements track.Broadcast {
+export declare class Producer {
     #private;
+    constructor();
     /**
      * Settles once the broadcast closes: `null` on a clean close, or the abort {@link Error}.
      * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
      */
     get closed(): GetPromise<Error | null>;
-    /** A read handle for this broadcast. */
+    /** A read handle for this broadcast, named by the path the origin created it at. */
     consume(): Consumer;
-    /** Return the next track requested by a peer. */
-    requested(): Promise<track.Request | undefined>;
     /** Insert a track that is served directly, without an on-demand request round-trip. */
     insertTrack(track: track.Producer): void;
     /** Create a track, insert it into the broadcast, and return its producer. */
     createTrack(name: string, info?: Partial<track.Info>): track.Producer;
     /** Remove a statically inserted track by name. */
     removeTrack(name: string): void;
-    /** Open a live subscription to a track. Used by the publishing wire layer. */
-    subscribe(name: string, options?: track.Subscription): track.Subscriber;
-    /** Resolve a track's immutable info. Used by the publishing wire layer. */
-    resolveTrackInfo(name: string): Promise<track.Info>;
-    /** Fetch a single group from the local retained window. Used by track handles. */
-    fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise<GroupConsumer>;
     /** A lazy read handle for a track on this broadcast. */
     track(name: string): track.Consumer;
-    /** Close the broadcast, optionally with an error to abort waiters. Idempotent. */
+    /**
+     * Advertise this broadcast's exact path, or re-price a standing advertisement in place.
+     *
+     * Call it once the tracks a subscriber needs first (a catalog) exist. Until then the
+     * broadcast exists for nobody, on its own origin or at a peer. Retracts on
+     * {@link unannounce} or {@link close}. Throws if this producer was not created through an
+     * origin, or if the broadcast is already closed.
+     */
+    announce(route?: Route | {
+        hops?: Route["hops"];
+        cost?: Route["cost"] | bigint;
+    }): void;
+    /**
+     * Retract the advertisement of this broadcast's path, if any, from local consumers and
+     * peers alike. {@link announce} brings it back.
+     */
+    unannounce(): void;
+    /** End the broadcast for good: retract it, serve no new tracks, and refuse a later {@link announce}. Idempotent. */
+    close(): void;
+    /** @deprecated A broadcast end carries no cause; call `close()` without one. */
     close(abort?: Error): void;
 }
 /**
  * The read side of a broadcast.
  *
- * Created internally: obtain one from {@link Producer.consume} or the connection's
- * `consume(path)`. The wire layers subclass it to resolve tracks over the network.
+ * Created internally: obtain one from {@link Producer.consume} or an origin request.
+ * The wire layers subclass it to resolve tracks over the network.
  *
  * @public
  */
-export declare class Consumer implements track.Broadcast {
+export declare class Consumer {
     #private;
-    protected constructor(state?: never);
+    protected constructor(shared?: never);
+    /**
+     * The path this handle names the broadcast by, which relative references in its catalog
+     * (hang's `broadcast` field) resolve against.
+     *
+     * An origin stamps each handle it hands out with the path it was requested at, relative to
+     * that origin handle's scope root, and a broadcast it created with the path it was created at.
+     * Empty for a standalone broadcast, which is then its own root: any `..` reference escapes.
+     */
+    get path(): Path.Valid;
     /**
      * Settles once the broadcast closes: `null` on a clean close, or the abort {@link Error}.
      * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
@@ -61,8 +83,8 @@ export declare class Consumer implements track.Broadcast {
     /**
      * Return another handle to the same broadcast, reference-counted with this one.
      *
-     * Both handles read the same tracks and share one {@link closed} state; the broadcast
-     * closes only once *every* handle has {@link close}d. Used by the connection's per-path
+     * Both handles read the same tracks, carry the same {@link path}, and share one {@link closed}
+     * state; the broadcast closes only once *every* handle has {@link close}d. Used by the connection's per-path
      * consume cache to share one subscription across callers. Subclasses that resolve info over
      * the wire override this to preserve their type (see the wire layer's consumed broadcast).
      */
@@ -70,25 +92,12 @@ export declare class Consumer implements track.Broadcast {
     protected shareState(): never;
     /** Get a lazy handle for a track on this broadcast. Repeat subscriptions dedupe onto one upstream subscription. */
     track(name: string): track.Consumer;
-    /** Open a live subscription to a track. Used by the subscribing wire layer. Repeat subscriptions to the same track share one upstream subscription. */
-    subscribe(name: string, options?: track.Subscription): track.Subscriber;
-    /** Return the next track requested by the local consumer. Used by the subscribing wire layer. */
-    requested(): Promise<track.Request | undefined>;
-    /**
-     * Resolve a track's immutable info. Used by track handles. This base resolves it from
-     * the local producers; the consuming wire layer overrides it to fetch over the wire.
-     */
-    resolveTrackInfo(name: string): Promise<track.Info>;
-    /**
-     * Fetch a single group by sequence. Used by track handles. This base serves from the
-     * local retained window; the consuming wire layer overrides it to fetch over the wire
-     * (or to reject when the transport has no FETCH).
-     */
-    fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise<GroupConsumer>;
     /**
-     * Release this handle. The broadcast is closed (optionally with an error to abort waiters)
-     * once this was the last live handle; while other {@link clone}s remain open it stays live.
+     * Release this handle. The broadcast is closed once this was the last live handle;
+     * while other {@link clone}s remain open it stays live.
      */
+    close(): void;
+    /** @deprecated A broadcast end carries no cause; call `close()` without one. */
     close(abort?: Error): void;
 }
 //# sourceMappingURL=broadcast.d.ts.map