@norskvideo/moq-net 0.1.8 → 0.2.0

package/hop.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Endpoint identity within a hop chain, shared by both wire protocols.
+ *
+ * moq-lite carries these natively on every announcement; moq-transport carries them
+ * via the MoQ Cluster extension (see `ietf/cluster.ts`). Mirrors `Hop` in
+ * `rs/moq-net`.
+ *
+ * @module
+ */
+import * as z from "zod/mini";
+/**
+ * One relay's identity in a broadcast's hop chain, encoded as a 62-bit varint on the wire.
+ *
+ * Names a *hop*, not an {@link !Origin | Origin} routing table: this is the id a relay
+ * stamps into a chain as an announcement passes through, so a receiver can spot its own
+ * id and reject a loop. The SETUP parameter that carries it session-wide is `Hop` too.
+ *
+ * The {@link HopSchema} validates any incoming value and brands it so the type system
+ * enforces "only validated ids flow into hop chains." Internal code that synthesizes one
+ * (e.g. {@link randomHop}) uses `HopSchema.parse(...)` to brand a raw bigint.
+ */
+export declare const HopSchema: z.core.$ZodBranded<z.ZodMiniBigInt<bigint>, "Hop", "out">;
+export type Hop = z.infer<typeof HopSchema>;
+/**
+ * The reserved id 0, meaning "no identity".
+ *
+ * It stands in for an endpoint that never declared one, and any number of endpoints can
+ * be 0, so it identifies nothing: it is never a loop, never a publisher two chains have
+ * in common, and never excluded from an advertisement. A chain that holds a 0 anywhere
+ * is anonymous for route selection.
+ */
+export declare const UNKNOWN_HOP: Hop;
+/**
+ * Maximum length of a hop chain. Must match `MAX_HOPS` in Rust's `model/origin.rs`.
+ *
+ * Broadcasts with longer chains are rejected, which bounds loop detection and rejects
+ * pathological announcements across clusters with unbounded forwarding.
+ */
+export declare const MAX_HOPS = 32;
+/**
+ * Generate a fresh hop with a random non-zero id.
+ *
+ * `crypto.getRandomValues` is overkill for best-effort loop detection, but
+ * used for slightly better distribution than `Math.random` at negligible cost.
+ *
+ * TEMPORARY: the wire format allows 62 bits, but older `@moq/lite` JS clients
+ * decode `AnnounceInterest.exclude_hop` as a u53 (number) and throw on anything
+ * > 2^53-1. To keep those clients alive against fresh peers, we cap the random
+ * id at 53 bits. Restore to 62 bits once the u62 fix has propagated to deployed
+ * bundles. Mirrors `Hop::random` in rs/moq-net.
+ */
+export declare function randomHop(): Hop;
+/**
+ * Name an unknown original publisher: put `stamp`, the receiving connection's own random id,
+ * in front of a chain that starts with 0, and turn an empty chain into `[stamp, 0]`. A
+ * publisher that reconnects then reads downstream as a new first hop, while the 0 after the
+ * stamp keeps the route ranked as anonymous. `undefined` if the chain is full or already holds
+ * `stamp`. Mirrors `Hops::stamp` in rs/moq-net.
+ */
+export declare function stampHops(hops: readonly Hop[], stamp: Hop): Hop[] | undefined;
+/**
+ * What pulling content via a route costs, in two magnitudes accumulated together
+ * and compared in that order: lower {@link Cost.warm} wins, and {@link Cost.cold}
+ * breaks the tie.
+ *
+ * Both price the same path against different cache states. `warm` is what one more
+ * subscription would cost the mesh right now, so it collapses to zero at any relay
+ * already carrying the broadcast. `cold` prices the identical path as if nothing were
+ * cached, so it keeps flowing through a warm relay unchanged and still says which of
+ * two warm relays sits closer to the publisher.
+ */
+export interface Cost {
+    /** The cost as the mesh stands today, discounted to zero at every carrying relay. */
+    warm: bigint;
+    /** The same path with every warm discount removed. */
+    cold: bigint;
+}
+/** Constructors for {@link Cost}. */
+export declare const Cost: {
+    /** A free path in both magnitudes: what a live publisher seeds. */
+    zero: Cost;
+};
+/**
+ * The path a route took through the mesh and what using it costs.
+ *
+ * The metadata half of an advertisement: an origin `dynamic()` pairs it with the
+ * pattern it covers, a broadcast `announce()` with the broadcast's exact path, and
+ * an announce event carries it so consumers can read it back.
+ */
+export interface Route {
+    /** The chain of hops the route has traversed, oldest first. */
+    hops: Hop[];
+    /** What pulling content via this route costs; lower wins. */
+    cost: Cost;
+}
+/** Constructors and helpers for {@link Route}. */
+export declare const Route: {
+    /** An empty hop chain at zero cost: what a publisher seeds for a live broadcast. */
+    default: Route;
+    /** Normalize a partial route, treating a bare bigint cost as both magnitudes alike. */
+    normalize(route?: Route | {
+        hops?: readonly Hop[];
+        cost?: Cost | bigint;
+    }): Route;
+};
+/**
+ * Whether this route passed through an anonymous hop (id 0) at any depth.
+ *
+ * An empty chain is a local announcement, not the anonymous mark. Ingress fills a
+ * received empty list with {@link UNKNOWN_HOP} before yielding it.
+ */
+export declare function isAnonymous(route: Route): boolean;
+/** Whether two routes name the same hop chain and cost. */
+export declare function routesEqual(a: Route | undefined, b: Route | undefined): boolean;
+//# sourceMappingURL=hop.d.ts.map

package/hop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hop.d.ts","sourceRoot":"","sources":["../src/hop.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,2DAGR,CAAC;AAEf,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,GAAyB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,KAAK,CAAC;AAE3B;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,GAAG,CAO/B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,SAAS,CAK7E;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,IAAI;IACpB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACb;AAED,qCAAqC;AACrC,eAAO,MAAM,IAAI;IAChB,mEAAmE;IACnE,IAAI,EAA4B,IAAI;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACrB,+DAA+D;IAC/D,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,IAAI,CAAC;CACX;AAED,kDAAkD;AAClD,eAAO,MAAM,KAAK;IACjB,oFAAoF;IACpF,OAAO,EAAmC,KAAK;IAE/C,uFAAuF;IACvF,SAAS,SAAQ,KAAK,GAAG;QAAE,IAAI,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;KAAE,GAAQ,KAAK;CAOrF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEjD;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAS/E"}

package/hop.js

@@ -0,0 +1,119 @@
+/* @ts-self-types="./hop.d.ts" */
+/**
+ * Endpoint identity within a hop chain, shared by both wire protocols.
+ *
+ * moq-lite carries these natively on every announcement; moq-transport carries them
+ * via the MoQ Cluster extension (see `ietf/cluster.ts`). Mirrors `Hop` in
+ * `rs/moq-net`.
+ *
+ * @module
+ */
+import * as z from "zod/mini";
+/**
+ * One relay's identity in a broadcast's hop chain, encoded as a 62-bit varint on the wire.
+ *
+ * Names a *hop*, not an {@link !Origin | Origin} routing table: this is the id a relay
+ * stamps into a chain as an announcement passes through, so a receiver can spot its own
+ * id and reject a loop. The SETUP parameter that carries it session-wide is `Hop` too.
+ *
+ * The {@link HopSchema} validates any incoming value and brands it so the type system
+ * enforces "only validated ids flow into hop chains." Internal code that synthesizes one
+ * (e.g. {@link randomHop}) uses `HopSchema.parse(...)` to brand a raw bigint.
+ */
+export const HopSchema = z
+    .bigint()
+    .check(z.refine((value) => value >= 0n && value < 1n << 62n, "Hop must be a non-negative 62-bit integer"))
+    .brand("Hop");
+/**
+ * The reserved id 0, meaning "no identity".
+ *
+ * It stands in for an endpoint that never declared one, and any number of endpoints can
+ * be 0, so it identifies nothing: it is never a loop, never a publisher two chains have
+ * in common, and never excluded from an advertisement. A chain that holds a 0 anywhere
+ * is anonymous for route selection.
+ */
+export const UNKNOWN_HOP = HopSchema.parse(0n);
+/**
+ * Maximum length of a hop chain. Must match `MAX_HOPS` in Rust's `model/origin.rs`.
+ *
+ * Broadcasts with longer chains are rejected, which bounds loop detection and rejects
+ * pathological announcements across clusters with unbounded forwarding.
+ */
+export const MAX_HOPS = 32;
+/**
+ * Generate a fresh hop with a random non-zero id.
+ *
+ * `crypto.getRandomValues` is overkill for best-effort loop detection, but
+ * used for slightly better distribution than `Math.random` at negligible cost.
+ *
+ * TEMPORARY: the wire format allows 62 bits, but older `@moq/lite` JS clients
+ * decode `AnnounceInterest.exclude_hop` as a u53 (number) and throw on anything
+ * > 2^53-1. To keep those clients alive against fresh peers, we cap the random
+ * id at 53 bits. Restore to 62 bits once the u62 fix has propagated to deployed
+ * bundles. Mirrors `Hop::random` in rs/moq-net.
+ */
+export function randomHop() {
+    const buf = new BigUint64Array(1);
+    crypto.getRandomValues(buf);
+    // Mask to 53 bits.
+    const raw = buf[0] & 0x1fffffffffffffn;
+    // Guard against the (astronomically unlikely) zero draw.
+    return HopSchema.parse(raw === 0n ? 1n : raw);
+}
+/**
+ * Name an unknown original publisher: put `stamp`, the receiving connection's own random id,
+ * in front of a chain that starts with 0, and turn an empty chain into `[stamp, 0]`. A
+ * publisher that reconnects then reads downstream as a new first hop, while the 0 after the
+ * stamp keeps the route ranked as anonymous. `undefined` if the chain is full or already holds
+ * `stamp`. Mirrors `Hops::stamp` in rs/moq-net.
+ */
+export function stampHops(hops, stamp) {
+    if (hops.length === 0)
+        return [stamp, UNKNOWN_HOP];
+    if (hops[0] !== UNKNOWN_HOP)
+        return [...hops];
+    if (hops.length >= MAX_HOPS || hops.includes(stamp))
+        return undefined;
+    return [stamp, ...hops];
+}
+/** Constructors for {@link Cost}. */
+export const Cost = {
+    /** A free path in both magnitudes: what a live publisher seeds. */
+    zero: { warm: 0n, cold: 0n },
+};
+/** Constructors and helpers for {@link Route}. */
+export const Route = {
+    /** An empty hop chain at zero cost: what a publisher seeds for a live broadcast. */
+    default: { hops: [], cost: Cost.zero },
+    /** Normalize a partial route, treating a bare bigint cost as both magnitudes alike. */
+    normalize(route = {}) {
+        const hops = route.hops ? [...route.hops] : [];
+        const cost = route.cost;
+        if (cost === undefined)
+            return { hops, cost: Cost.zero };
+        if (typeof cost === "bigint")
+            return { hops, cost: { warm: cost, cold: cost } };
+        return { hops, cost: { warm: cost.warm, cold: cost.cold } };
+    },
+};
+/**
+ * Whether this route passed through an anonymous hop (id 0) at any depth.
+ *
+ * An empty chain is a local announcement, not the anonymous mark. Ingress fills a
+ * received empty list with {@link UNKNOWN_HOP} before yielding it.
+ */
+export function isAnonymous(route) {
+    return route.hops.includes(UNKNOWN_HOP);
+}
+/** Whether two routes name the same hop chain and cost. */
+export function routesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.cost.warm === b.cost.warm &&
+        a.cost.cold === b.cost.cold &&
+        a.hops.length === b.hops.length &&
+        a.hops.every((hop, i) => hop === b.hops[i]));
+}
+//# sourceMappingURL=hop.js.map

package/hop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hop.js","sourceRoot":"","sources":["../src/hop.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Endpoint identity within a hop chain, shared by both wire protocols.\n *\n * moq-lite carries these natively on every announcement; moq-transport carries them\n * via the MoQ Cluster extension (see `ietf/cluster.ts`). Mirrors `Hop` in\n * `rs/moq-net`.\n *\n * @module\n */\nimport * as z from \"zod/mini\";\n\n/**\n * One relay's identity in a broadcast's hop chain, encoded as a 62-bit varint on the wire.\n *\n * Names a *hop*, not an {@link !Origin | Origin} routing table: this is the id a relay\n * stamps into a chain as an announcement passes through, so a receiver can spot its own\n * id and reject a loop. The SETUP parameter that carries it session-wide is `Hop` too.\n *\n * The {@link HopSchema} validates any incoming value and brands it so the type system\n * enforces \"only validated ids flow into hop chains.\" Internal code that synthesizes one\n * (e.g. {@link randomHop}) uses `HopSchema.parse(...)` to brand a raw bigint.\n */\nexport const HopSchema = z\n\t.bigint()\n\t.check(z.refine((value) => value >= 0n && value < 1n << 62n, \"Hop must be a non-negative 62-bit integer\"))\n\t.brand(\"Hop\");\n\nexport type Hop = z.infer<typeof HopSchema>;\n\n/**\n * The reserved id 0, meaning \"no identity\".\n *\n * It stands in for an endpoint that never declared one, and any number of endpoints can\n * be 0, so it identifies nothing: it is never a loop, never a publisher two chains have\n * in common, and never excluded from an advertisement. A chain that holds a 0 anywhere\n * is anonymous for route selection.\n */\nexport const UNKNOWN_HOP: Hop = HopSchema.parse(0n);\n\n/**\n * Maximum length of a hop chain. Must match `MAX_HOPS` in Rust's `model/origin.rs`.\n *\n * Broadcasts with longer chains are rejected, which bounds loop detection and rejects\n * pathological announcements across clusters with unbounded forwarding.\n */\nexport const MAX_HOPS = 32;\n\n/**\n * Generate a fresh hop with a random non-zero id.\n *\n * `crypto.getRandomValues` is overkill for best-effort loop detection, but\n * used for slightly better distribution than `Math.random` at negligible cost.\n *\n * TEMPORARY: the wire format allows 62 bits, but older `@moq/lite` JS clients\n * decode `AnnounceInterest.exclude_hop` as a u53 (number) and throw on anything\n * > 2^53-1. To keep those clients alive against fresh peers, we cap the random\n * id at 53 bits. Restore to 62 bits once the u62 fix has propagated to deployed\n * bundles. Mirrors `Hop::random` in rs/moq-net.\n */\nexport function randomHop(): Hop {\n\tconst buf = new BigUint64Array(1);\n\tcrypto.getRandomValues(buf);\n\t// Mask to 53 bits.\n\tconst raw = buf[0] & 0x1f_ffff_ffff_ffffn;\n\t// Guard against the (astronomically unlikely) zero draw.\n\treturn HopSchema.parse(raw === 0n ? 1n : raw);\n}\n\n/**\n * Name an unknown original publisher: put `stamp`, the receiving connection's own random id,\n * in front of a chain that starts with 0, and turn an empty chain into `[stamp, 0]`. A\n * publisher that reconnects then reads downstream as a new first hop, while the 0 after the\n * stamp keeps the route ranked as anonymous. `undefined` if the chain is full or already holds\n * `stamp`. Mirrors `Hops::stamp` in rs/moq-net.\n */\nexport function stampHops(hops: readonly Hop[], stamp: Hop): Hop[] | undefined {\n\tif (hops.length === 0) return [stamp, UNKNOWN_HOP];\n\tif (hops[0] !== UNKNOWN_HOP) return [...hops];\n\tif (hops.length >= MAX_HOPS || hops.includes(stamp)) return undefined;\n\treturn [stamp, ...hops];\n}\n\n/**\n * What pulling content via a route costs, in two magnitudes accumulated together\n * and compared in that order: lower {@link Cost.warm} wins, and {@link Cost.cold}\n * breaks the tie.\n *\n * Both price the same path against different cache states. `warm` is what one more\n * subscription would cost the mesh right now, so it collapses to zero at any relay\n * already carrying the broadcast. `cold` prices the identical path as if nothing were\n * cached, so it keeps flowing through a warm relay unchanged and still says which of\n * two warm relays sits closer to the publisher.\n */\nexport interface Cost {\n\t/** The cost as the mesh stands today, discounted to zero at every carrying relay. */\n\twarm: bigint;\n\t/** The same path with every warm discount removed. */\n\tcold: bigint;\n}\n\n/** Constructors for {@link Cost}. */\nexport const Cost = {\n\t/** A free path in both magnitudes: what a live publisher seeds. */\n\tzero: { warm: 0n, cold: 0n } as Cost,\n};\n\n/**\n * The path a route took through the mesh and what using it costs.\n *\n * The metadata half of an advertisement: an origin `dynamic()` pairs it with the\n * pattern it covers, a broadcast `announce()` with the broadcast's exact path, and\n * an announce event carries it so consumers can read it back.\n */\nexport interface Route {\n\t/** The chain of hops the route has traversed, oldest first. */\n\thops: Hop[];\n\t/** What pulling content via this route costs; lower wins. */\n\tcost: Cost;\n}\n\n/** Constructors and helpers for {@link Route}. */\nexport const Route = {\n\t/** An empty hop chain at zero cost: what a publisher seeds for a live broadcast. */\n\tdefault: { hops: [], cost: Cost.zero } as Route,\n\n\t/** Normalize a partial route, treating a bare bigint cost as both magnitudes alike. */\n\tnormalize(route: Route | { hops?: readonly Hop[]; cost?: Cost | bigint } = {}): Route {\n\t\tconst hops = route.hops ? [...route.hops] : [];\n\t\tconst cost = route.cost;\n\t\tif (cost === undefined) return { hops, cost: Cost.zero };\n\t\tif (typeof cost === \"bigint\") return { hops, cost: { warm: cost, cold: cost } };\n\t\treturn { hops, cost: { warm: cost.warm, cold: cost.cold } };\n\t},\n};\n\n/**\n * Whether this route passed through an anonymous hop (id 0) at any depth.\n *\n * An empty chain is a local announcement, not the anonymous mark. Ingress fills a\n * received empty list with {@link UNKNOWN_HOP} before yielding it.\n */\nexport function isAnonymous(route: Route): boolean {\n\treturn route.hops.includes(UNKNOWN_HOP);\n}\n\n/** Whether two routes name the same hop chain and cost. */\nexport function routesEqual(a: Route | undefined, b: Route | undefined): boolean {\n\tif (a === b) return true;\n\tif (!a || !b) return false;\n\treturn (\n\t\ta.cost.warm === b.cost.warm &&\n\t\ta.cost.cold === b.cost.cold &&\n\t\ta.hops.length === b.hops.length &&\n\t\ta.hops.every((hop, i) => hop === b.hops[i])\n\t);\n}\n"]}

package/ietf/adapter.d.ts

@@ -62,6 +62,10 @@ export declare class ControlStreamAdapter implements Session {
      * Must be called after construction. Runs until the control stream closes.
      */
     run(): Promise<void>;
-    close(): void;
+    /**
+     * Ends every virtual stream: cleanly for a deliberate close, or with `err` when the
+     * control stream died under them, since every request riding it was cut off.
+     */
+    close(err?: Error): void;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/ietf/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ietf/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,MAAM,EAAe,MAAM,cAAc,CAAC;AAI3D,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,cAAc,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,YAAY,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,OAAO;;IAK5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B,YAAY,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAIpE;IAEK,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAE9B;IAEK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE5C;IAEK,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAIjD;IAED,kDAAkD;IAClD,KAAK,SAEJ;CACD;AAmBD;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,OAAO;;IAQnD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IA+B9B,YACC,IAAI,EAAE,YAAY,EAClB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EAUf;IAED;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS5C;IAED;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAsDf;IAED;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAEpC;IAED;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAYjD;IAED;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAmDzB;IAuYD,KAAK,SA6BJ;CACD"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ietf/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAU,MAAM,EAAe,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,cAAc,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,YAAY,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,OAAO;;IAK5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B,YAAY,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAIpE;IAEK,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAE9B;IAEK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE5C;IAEK,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAIjD;IAED,kDAAkD;IAClD,KAAK,SAEJ;CACD;AAqBD;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,OAAO;;IAQnD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAmC9B,YACC,IAAI,EAAE,YAAY,EAClB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EAUf;IAED;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS5C;IAED;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAoDf;IAED;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAEpC;IAED;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAYjD;IAED;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA2DzB;IAqaD;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,QA8BhB;CACD"}

package/ietf/adapter.js

@@ -1,7 +1,7 @@
 /* @ts-self-types="./adapter.d.ts" */
 import { Mutex } from "async-mutex";
+import { error, ProtocolViolation } from "../error.js";
 import { Reader, Stream } from "../stream.js";
-import { decodeUtf8 } from "../util/utf8.js";
 import * as Varint from "../varint.js";
 import * as Namespace from "./namespace.js";
 import { Version } from "./version.js";
@@ -40,7 +40,7 @@ export class NativeSession {
 const Route = {
     NewRequest: 0, // Create virtual bidi stream, push initial message
     Response: 1, // Push message to existing stream (keep open)
-    ErrorResponse: 2, // Push message to existing stream, then close
+    ErrorResponse: 2, // Push a final message to existing stream, then close
     CloseStream: 3, // Close stream recv (no bytes pushed)
     FollowUp: 4, // Push follow-up message to existing stream
     MaxRequestId: 5, // Update flow control
@@ -64,9 +64,13 @@ export class ControlStreamAdapter {
     version;
     // Virtual streams keyed by requestId
     #streams = new Map();
-    // Namespace → requestId reverse lookup (v14/v15 namespace-keyed messages)
-    #namespaces = new Map();
-    // requestId → namespace reverse lookup (for cleanup in #closeStream)
+    // Namespace → requestId reverse lookups for v14/v15 namespace-keyed messages.
+    // DONE names an incoming announcement and CANCEL names an outgoing one, so a relay
+    // may legitimately hold the same namespace in both maps at once.
+    #incomingNamespaces = new Map();
+    #outgoingNamespaces = new Map();
+    // requestId → namespace reverse lookup, one entry per request including a refused
+    // duplicate, so #forget can clean up whichever request goes away.
     #namespacesByRequestId = new Map();
     // SubscribeNamespace requestIds — for routing 0x08/0x0E entries that lack requestId (v14/v15)
     #subscribeNamespaces = new Set();
@@ -123,7 +127,7 @@ export class ControlStreamAdapter {
             },
             cancel: () => {
                 if (registeredRequestId !== undefined) {
-                    this.#streams.delete(registeredRequestId);
+                    this.#forget(registeredRequestId);
                 }
             },
         });
@@ -146,7 +150,7 @@ export class ControlStreamAdapter {
                     buffer = buffer.subarray(boundary);
                     if (!registered) {
                         // First message: extract requestId and register before flushing
-                        const parsed = this.#tryParseOutgoing(toFlush);
+                        const parsed = await this.#tryParseOutgoing(toFlush);
                         if (parsed) {
                             registeredRequestId = parsed.requestId;
                             this.#streams.set(parsed.requestId, { controller });
@@ -157,9 +161,7 @@ export class ControlStreamAdapter {
                 }
             },
         });
-        const stream = new Stream({ readable, writable: sendWritable });
-        stream.reader.version = this.version;
-        stream.writer.version = this.version;
+        const stream = new Stream({ readable, writable: sendWritable, version: this.version });
         return stream;
     }
     /**
@@ -190,6 +192,8 @@ export class ControlStreamAdapter {
      * Must be called after construction. Runs until the control stream closes.
      */
     async run() {
+        // Why the virtual streams end: undefined only for a GOAWAY, which is not a failure.
+        let cause;
         try {
             // v16: also accept real bidi streams (for SubscribeNamespace)
             if (this.version === Version.DRAFT_16) {
@@ -197,8 +201,10 @@ export class ControlStreamAdapter {
             }
             for (;;) {
                 const done = await this.#reader.done();
-                if (done)
+                if (done) {
+                    cause = new ProtocolViolation("control stream closed");
                     break;
+                }
                 const typeId = await this.#reader.u53();
                 const size = await this.#reader.u16();
                 const body = await this.#reader.read(size);
@@ -234,8 +240,12 @@ export class ControlStreamAdapter {
                 }
             }
         }
+        catch (err) {
+            cause = error(err);
+            throw err;
+        }
         finally {
-            this.close();
+            this.close(cause);
         }
     }
     /** Accept real WebTransport bidi streams and queue them for acceptBi (v16). */
@@ -265,13 +275,11 @@ export class ControlStreamAdapter {
                 controller = c;
             },
             cancel: () => {
-                this.#streams.delete(requestId);
+                this.#forget(requestId);
             },
         });
         const sendWritable = this.#createSendWritable();
-        const stream = new Stream({ readable, writable: sendWritable });
-        stream.reader.version = this.version;
-        stream.writer.version = this.version;
+        const stream = new Stream({ readable, writable: sendWritable, version: this.version });
         this.#streams.set(requestId, { controller });
         // Push initial message bytes so the dispatcher can read typeId + decode
         controller.enqueue(this.#encodeRaw(typeId, size, body));
@@ -299,16 +307,10 @@ export class ControlStreamAdapter {
     }
     #closeStream(requestId) {
         const entry = this.#streams.get(requestId);
+        this.#forget(requestId);
         if (!entry)
             return;
         console.debug(`adapter: closing stream requestId=${requestId}`);
-        this.#streams.delete(requestId);
-        this.#subscribeNamespaces.delete(requestId);
-        const namespace = this.#namespacesByRequestId.get(requestId);
-        if (namespace !== undefined) {
-            this.#namespaces.delete(namespace);
-            this.#namespacesByRequestId.delete(requestId);
-        }
         try {
             entry.controller.close();
         }
@@ -316,6 +318,26 @@ export class ControlStreamAdapter {
             // Already closed
         }
     }
+    /**
+     * Drop every routing entry a request owns, keeping the two namespace maps in step.
+     *
+     * Runs even when the virtual stream is already gone, so a request that was torn down
+     * locally still gives its namespace back.
+     */
+    #forget(requestId) {
+        this.#streams.delete(requestId);
+        this.#subscribeNamespaces.delete(requestId);
+        const registered = this.#namespacesByRequestId.get(requestId);
+        if (registered === undefined)
+            return;
+        this.#namespacesByRequestId.delete(requestId);
+        const namespaces = this.#namespaceRequests(registered.direction);
+        // Only the request holding the live announcement may retract it. A refused duplicate
+        // carries the same name, and letting its close withdraw the name would strand the
+        // original: its own DONE would then resolve to nothing.
+        if (namespaces.get(registered.namespace) === requestId)
+            namespaces.delete(registered.namespace);
+    }
     /**
      * Returns the total byte size of the first complete message in buffer,
      * or undefined if the buffer doesn't contain a complete message yet.
@@ -340,7 +362,7 @@ export class ControlStreamAdapter {
      * Try to parse the first outgoing message from accumulated bytes.
      * Returns the requestId if enough data is available, undefined otherwise.
      */
-    #tryParseOutgoing(buffer) {
+    async #tryParseOutgoing(buffer) {
         if (buffer.length === 0)
             return undefined;
         // Check typeId varint size before decoding
@@ -363,8 +385,7 @@ export class ControlStreamAdapter {
         // PublishNamespace (0x06): also parse namespace for v14/v15 reverse lookup
         if (typeId === 0x06) {
             try {
-                const [, afterReqId] = Varint.decode(body);
-                this.#parseAndRegisterNamespace(afterReqId, requestId);
+                await this.#registerNamespace(body, "outgoing");
             }
             catch {
                 // Non-critical: only needed for v14/v15 PublishNamespaceDone/Cancel
@@ -377,20 +398,28 @@ export class ControlStreamAdapter {
         return { requestId };
     }
     /**
-     * Parse a namespace from raw bytes and register it for reverse lookup.
+     * Decode a PublishNamespace body and register its namespace for the v14/v15
+     * namespace-keyed withdrawals. Returns the request ID it carried.
+     *
+     * The one decode site for both directions: outgoing announcements go through
+     * #tryParseOutgoing and incoming ones through #classify. The direction selects the
+     * map that the peer's DONE or CANCEL will later consult.
      */
-    #parseAndRegisterNamespace(buf, requestId) {
-        const [partCount, afterCount] = Varint.decode(buf);
-        let cursor = afterCount;
-        const parts = [];
-        for (let i = 0; i < partCount; i++) {
-            const [len, afterLen] = Varint.decode(cursor);
-            parts.push(decodeUtf8(afterLen.subarray(0, len)));
-            cursor = afterLen.subarray(len);
-        }
-        const namespace = Namespace.fromTuple(parts);
-        this.#namespaces.set(namespace, requestId);
-        this.#namespacesByRequestId.set(requestId, namespace);
+    async #registerNamespace(body, direction) {
+        const r = new Reader(undefined, body, this.version);
+        const requestId = await r.u62();
+        const namespace = await Namespace.decode(r);
+        const namespaces = this.#namespaceRequests(direction);
+        this.#namespacesByRequestId.set(requestId, { namespace, direction });
+        // First announcement in this direction wins. A duplicate is refused with 409, and
+        // overwriting here would point the first request's withdrawal at the refused one,
+        // which has no stream left, leaving the namespace announced forever.
+        if (!namespaces.has(namespace))
+            namespaces.set(namespace, requestId);
+        return requestId;
+    }
+    #namespaceRequests(direction) {
+        return direction === "incoming" ? this.#incomingNamespaces : this.#outgoingNamespaces;
     }
     /** Create a WritableStream that buffers and writes complete messages to the control stream under mutex. */
     #createSendWritable() {
@@ -431,13 +460,17 @@ export class ControlStreamAdapter {
             const r = new Reader(undefined, body, this.version);
             return await r.u62();
         };
-        const readNamespaceRequestId = async () => {
+        // v14/v15 name their withdrawals instead of numbering them. A name we have no
+        // announcement for is dropped, not fatal: it belongs to a duplicate we already
+        // refused, or to a request that is already gone, so there is nothing left to close.
+        // The mapping itself is released by #forget when the stream goes.
+        const readNamespaceRequestId = async (direction) => {
             const r = new Reader(undefined, body, this.version);
             const namespace = await Namespace.decode(r);
-            const requestId = this.#namespaces.get(namespace);
+            const namespaces = this.#namespaceRequests(direction);
+            const requestId = namespaces.get(namespace);
             if (requestId === undefined)
-                throw new Error(`unknown namespace: ${namespace}`);
-            this.#namespaces.delete(namespace);
+                console.warn(`adapter: no announcement for namespace: ${namespace}`);
             return requestId;
         };
         switch (typeId) {
@@ -457,12 +490,8 @@ export class ControlStreamAdapter {
                 return { route: Route.NewRequest, requestId };
             }
             case 0x06: {
-                // PublishNamespace — also store namespace for v14/v15 reverse lookup
-                const r = new Reader(undefined, body, this.version);
-                const requestId = await r.u62();
-                const namespace = await Namespace.decode(r);
-                this.#namespaces.set(namespace, requestId);
-                this.#namespacesByRequestId.set(requestId, namespace);
+                // PublishNamespace: also store the namespace for v14/v15 reverse lookup
+                const requestId = await this.#registerNamespace(body, "incoming");
                 return { route: Route.NewRequest, requestId };
             }
             case 0x11: {
@@ -534,7 +563,10 @@ export class ControlStreamAdapter {
                 return { route: Route.FollowUp, requestId: subNs08 };
             }
             case 0x0e: {
-                // v15: NamespaceDone entry (no requestId) — route to SubscribeNamespace stream
+                if (this.version === Version.DRAFT_14 || this.version === Version.DRAFT_15) {
+                    throw new Error("unexpected message 0x0e");
+                }
+                // v16+: NamespaceDone entry (no requestId) — route to SubscribeNamespace stream
                 const subNs0e = this.#subscribeNamespaces.values().next().value;
                 if (subNs0e === undefined)
                     throw new Error("unexpected message 0x0e: no SubscribeNamespace stream");
@@ -554,9 +586,9 @@ export class ControlStreamAdapter {
                 return { route: Route.CloseStream, requestId };
             }
             case 0x0b: {
-                // PublishDone
+                // PublishDone: the subscriber reads its status and stream count before the end.
                 const requestId = await readRequestId();
-                return { route: Route.CloseStream, requestId };
+                return { route: Route.ErrorResponse, requestId };
             }
             case 0x17: {
                 // FetchCancel
@@ -564,21 +596,27 @@ export class ControlStreamAdapter {
                 return { route: Route.CloseStream, requestId };
             }
             case 0x09: {
-                // PublishNamespaceDone: v16 uses requestId, v14/v15 uses namespace
+                // PublishNamespaceDone: v16 uses requestId, v14/v15 names the incoming
+                // announcement its sender is withdrawing.
                 if (this.version === Version.DRAFT_16) {
                     const requestId = await readRequestId();
                     return { route: Route.CloseStream, requestId };
                 }
-                const requestId = await readNamespaceRequestId();
+                const requestId = await readNamespaceRequestId("incoming");
+                if (requestId === undefined)
+                    return { route: Route.Ignore, requestId: 0n };
                 return { route: Route.CloseStream, requestId };
             }
             case 0x0c: {
-                // PublishNamespaceCancel: v16 uses requestId, v14/v15 uses namespace
+                // PublishNamespaceCancel: v16 uses requestId, v14/v15 names the outgoing
+                // announcement its sender is rejecting.
                 if (this.version === Version.DRAFT_16) {
                     const requestId = await readRequestId();
                     return { route: Route.CloseStream, requestId };
                 }
-                const requestId = await readNamespaceRequestId();
+                const requestId = await readNamespaceRequestId("outgoing");
+                if (requestId === undefined)
+                    return { route: Route.Ignore, requestId: 0n };
                 return { route: Route.CloseStream, requestId };
             }
             case 0x14: {
@@ -607,15 +645,21 @@ export class ControlStreamAdapter {
                 throw new Error(`unknown control message type: 0x${typeId.toString(16)}`);
         }
     }
-    close() {
+    /**
+     * Ends every virtual stream: cleanly for a deliberate close, or with `err` when the
+     * control stream died under them, since every request riding it was cut off.
+     */
+    close(err) {
         if (this.#closed)
             return;
         this.#closed = true;
         console.debug("adapter: close() called");
-        // Close all virtual streams
         for (const entry of this.#streams.values()) {
             try {
-                entry.controller.close();
+                if (err)
+                    entry.controller.error(err);
+                else
+                    entry.controller.close();
             }
             catch {
                 // Already closed
@@ -628,7 +672,8 @@ export class ControlStreamAdapter {
         }
         this.#incomingWaiters = [];
         // Clear namespace mappings
-        this.#namespaces.clear();
+        this.#incomingNamespaces.clear();
+        this.#outgoingNamespaces.clear();
         this.#namespacesByRequestId.clear();
         this.#subscribeNamespaces.clear();
         // Unblock maxRequestId waiters