@statewalker/webrun-streams-conformance 0.1.1 → 0.3.1

package/README.md

@@ -2,6 +2,28 @@
 
 Conformance suite for `Duplex` / `Connect` / `Serve` adapters in the `webrun-streams-*` family. Every adapter ships a one-line test file that calls `describeDuplexAdapter(name, makePair)` with its own pair factory.
 
+## Why it exists
+
+The promise of the [`webrun-streams`](../webrun-streams) seam is that a handler
+written once runs over *any* transport. That promise is only as good as the
+weakest adapter — and the failure modes that break it are the quiet ones: an
+adapter that works for small bodies but truncates at 10 MiB, that serialises
+concurrent calls, that drops a handler's `finally` on cancellation, or that
+turns a thrown `Error` into an anonymous disconnect.
+
+None of those show up in an adapter's own happy-path tests. This package makes
+them a shared, executable definition of "correct", so a new transport is a
+day's work rather than a new set of subtle incompatibilities.
+
+## Install
+
+```sh
+npm install --save-dev @statewalker/webrun-streams-conformance
+```
+
+It is a **test-time** dependency: it bundles `vitest` and defines suites via
+`describe` / `it`.
+
 ## Levels asserted
 
 - **L0** Envelope round-trip via an echo handler for body sizes empty / 1 KiB / 1 MiB / 10 MiB.
@@ -10,6 +32,7 @@ Conformance suite for `Duplex` / `Connect` / `Serve` adapters in the `webrun-str
 - **L3** Mid-stream cancellation — caller `.return()`s output; handler's `finally` runs.
 - **L4** Error propagation — handler `throw`s; caller sees `message` + `stack` + custom fields preserved.
 - **L5** Transport teardown — calling the `serve` teardown twice resolves rather than throwing, and closing the pair after a completed call resolves cleanly. (It does *not* assert what an in-flight call does when the transport closes underneath it; that is deliberately left to each adapter.)
+- **L6** Flow control — a 256 KiB body reaches a deliberately slow consumer intact through a 16 KiB advertised window, so the sender must exhaust its credit and resume on grants sixteen times over. Adapters that accept `mux` options can run it at that window; today that is `-ws` and `webrun-rpc`, the only two with an executable conformance run. `-peerjs` and `-livekit` accept the option but have no pair helper yet, so L6 does not run for them. The loopback, `-webrtc` and `-libp2p` have no `emulateMux` to tune, so for them it is an end-to-end integrity check and nothing more.
 
 ## Reference loopback
 
@@ -35,6 +58,27 @@ A third argument tunes the suite:
 | `concurrency` | `10` | How many concurrent calls L1 runs. |
 | `skipHugeBody` | `false` | Drop L0's 10 MiB case, for transports that rate-limit. |
 
+## API
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `describeDuplexAdapter(name, makePair, options?)` | function | Registers the whole L0–L6 suite for one adapter. |
+| `makeLoopbackPair()` | `MakePair` | The reference in-process pair; the suite's own self-test. |
+| `MakePair` | type | `(tuning?: PairTuning) => Promise<ConnectServePair>` — called once per test case. |
+| `ConnectServePair` | type | `{ connect(), serve(handler), close() }`. |
+| `PairTuning` | type | `{ mtu?, maxStreamBuffer? }` — flow-control window L6 asks a pair for; an adapter that can forward it to `emulateMux` should. |
+| `DescribeDuplexAdapterOptions` | type | `concurrency` (default 10), `skipHugeBody` (default false). |
+
+## Dependencies
+
+| Dependency | Kind | Why |
+| --- | --- | --- |
+| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam under test. |
+| `vitest` | runtime | The suite is defined with `describe` / `it`. |
+
+Consumed as a `devDependency` by every adapter in the family. ESM only
+(`"type": "module"`).
+
 ## License
 
-MIT
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/describe-duplex-adapter.d.ts

@@ -6,7 +6,7 @@ export interface DescribeDuplexAdapterOptions {
     skipHugeBody?: boolean;
 }
 /**
- * Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+ * Runs every conformance level (L0–L6) against the supplied `ConnectServePair`
  * factory. Each adapter package in the `webrun-streams-*` family invokes this
  * from its own one-line Vitest file.
  */

package/dist/describe-duplex-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-duplex-adapter.d.ts","sourceRoot":"","sources":["../src/describe-duplex-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAmMN"}
+{"version":3,"file":"describe-duplex-adapter.d.ts","sourceRoot":"","sources":["../src/describe-duplex-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAqPN"}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { type DescribeDuplexAdapterOptions, describeDuplexAdapter, } from "./describe-duplex-adapter.js";
-export { type ConnectServePair, type MakePair, makeLoopbackPair } from "./loopback.js";
+export { type ConnectServePair, type MakePair, makeLoopbackPair, type PairTuning, } from "./loopback.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ import { collectBytes } from "@statewalker/webrun-streams";
 import { describe, expect, it } from "vitest";
 //#region src/describe-duplex-adapter.ts
 /**
-* Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+* Runs every conformance level (L0–L6) against the supplied `ConnectServePair`
 * factory. Each adapter package in the `webrun-streams-*` family invokes this
 * from its own one-line Vitest file.
 */
@@ -194,6 +194,38 @@ function describeDuplexAdapter(name, makePair, opts = {}) {
 				await expect(pair.close()).resolves.toBeUndefined();
 			});
 		});
+		describe("L6: flow control", () => {
+			it("delivers a body many times the advertised window to a slow consumer", async () => {
+				const pair = await makePair({
+					mtu: 4096,
+					maxStreamBuffer: 16384
+				});
+				try {
+					await pair.serve(echoHandler);
+					const size = 262144;
+					const body = new Uint8Array(size);
+					for (let i = 0; i < size; i++) body[i] = i & 255;
+					const { call, close } = await pair.connect();
+					const out = call([body]);
+					let received = 0;
+					let first = -1;
+					let last = -1;
+					for await (const chunk of out) {
+						if (chunk.byteLength === 0) continue;
+						if (first < 0) first = chunk[0];
+						last = chunk[chunk.byteLength - 1];
+						received += chunk.byteLength;
+						await delay(1);
+					}
+					expect(received).toBe(size);
+					expect(first).toBe(0);
+					expect(last).toBe(255);
+					await close();
+				} finally {
+					await pair.close();
+				}
+			});
+		});
 	});
 }
 const echoHandler = async function* echo(input) {

package/dist/loopback.d.ts

@@ -11,7 +11,16 @@ export interface ConnectServePair {
     serve(handler: Duplex): Promise<() => Promise<void>>;
     close(): Promise<void>;
 }
-export type MakePair = () => Promise<ConnectServePair>;
+/**
+ * Flow-control tuning L6 asks a pair for. An adapter that can pass these
+ * through to its `emulateMux` should; one that multiplexes natively, or has
+ * no configurable window, ignores them and L6 degrades to an integrity check.
+ */
+export interface PairTuning {
+    mtu?: number;
+    maxStreamBuffer?: number;
+}
+export type MakePair = (tuning?: PairTuning) => Promise<ConnectServePair>;
 /**
  * Loopback pair: `call` invokes the registered `handler` directly, no
  * transport. The conformance suite must pass against this — it self-validates

package/dist/loopback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAwC9B,CAAC"}
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAwC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-conformance",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "description": "Conformance test suite for Duplex/Connect/Serve adapters in the webrun-streams-* family",
@@ -15,26 +15,32 @@
     "url": "git@github.com:statewalker/webrun-wire.git"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "vitest": "^4.1.10",
-    "@statewalker/webrun-streams": "0.1.1"
+    "vitest": "^5.0.3",
+    "@statewalker/webrun-streams": "^0.2.1"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
+    "rolldown": "^1.2.12",
     "typescript": "^7.0.2"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",

package/src/describe-duplex-adapter.ts

@@ -10,7 +10,7 @@ export interface DescribeDuplexAdapterOptions {
 }
 
 /**
- * Runs every conformance level (L0–L5) against the supplied `ConnectServePair`
+ * Runs every conformance level (L0–L6) against the supplied `ConnectServePair`
  * factory. Each adapter package in the `webrun-streams-*` family invokes this
  * from its own one-line Vitest file.
  */
@@ -212,6 +212,56 @@ export function describeDuplexAdapter(
         await expect(pair.close()).resolves.toBeUndefined();
       });
     });
+
+    describe("L6: flow control", () => {
+      it("delivers a body many times the advertised window to a slow consumer", async () => {
+        // A 16 KiB window against a 256 KiB body: the sender must exhaust its
+        // credit and wait for grants sixteen times over. An adapter that
+        // ignores the tuning runs this at its own defaults, where it degrades
+        // to an integrity check — that is stated in the README, not hidden.
+        //
+        // What the assertions below check is completion and integrity. That
+        // this level also proves *stalling and replenishment* is an
+        // elimination argument that lives in the mutations, not in this body:
+        // delete the grant `ACK` and replenishment dies, so the transfer hangs
+        // and this times out; bypass `reserve()` and stalling dies, so the
+        // sender floods the window and the receiver's cap tears the stream
+        // down. Both are measured in the plan's Task 5 Step 4 table. Keep the
+        // small window and the slow drain — at the adapters' defaults nothing
+        // stalls, no grant is emitted, and this level passes with credit
+        // deleted entirely. An earlier draft shipped exactly that while
+        // claiming otherwise.
+        const pair = await makePair({ mtu: 4096, maxStreamBuffer: 16 * 1024 });
+        try {
+          await pair.serve(echoHandler);
+          const size = 256 * 1024;
+          const body = new Uint8Array(size);
+          for (let i = 0; i < size; i++) body[i] = i & 0xff;
+
+          const { call, close } = await pair.connect();
+          const out = call([body]);
+          let received = 0;
+          let first = -1;
+          let last = -1;
+          for await (const chunk of out) {
+            if (chunk.byteLength === 0) continue;
+            if (first < 0) first = chunk[0] as number;
+            last = chunk[chunk.byteLength - 1] as number;
+            received += chunk.byteLength;
+            // Drain deliberately slowly, so the sender is stalled on credit
+            // for most of the transfer rather than streaming through.
+            await delay(1);
+          }
+
+          expect(received).toBe(size);
+          expect(first).toBe(0);
+          expect(last).toBe((size - 1) & 0xff);
+          await close();
+        } finally {
+          await pair.close();
+        }
+      });
+    });
   });
 }
 

package/src/index.ts

@@ -2,4 +2,9 @@ export {
   type DescribeDuplexAdapterOptions,
   describeDuplexAdapter,
 } from "./describe-duplex-adapter.js";
-export { type ConnectServePair, type MakePair, makeLoopbackPair } from "./loopback.js";
+export {
+  type ConnectServePair,
+  type MakePair,
+  makeLoopbackPair,
+  type PairTuning,
+} from "./loopback.js";

package/src/loopback.ts

@@ -10,7 +10,17 @@ export interface ConnectServePair {
   close(): Promise<void>;
 }
 
-export type MakePair = () => Promise<ConnectServePair>;
+/**
+ * Flow-control tuning L6 asks a pair for. An adapter that can pass these
+ * through to its `emulateMux` should; one that multiplexes natively, or has
+ * no configurable window, ignores them and L6 degrades to an integrity check.
+ */
+export interface PairTuning {
+  mtu?: number;
+  maxStreamBuffer?: number;
+}
+
+export type MakePair = (tuning?: PairTuning) => Promise<ConnectServePair>;
 
 /**
  * Loopback pair: `call` invokes the registered `handler` directly, no