@statewalker/webrun-streams-conformance 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -36,8 +36,10 @@ peer dependencies. One entry point, `.`.
36
36
  | `describeDuplexAdapter(name, makePair, options?)` | function | Registers L0 to L6 under `describe("<name> — Duplex conformance")`. |
37
37
  | `makeLoopbackPair` | `MakePair` | Reference pair: `call` invokes the registered handler directly. |
38
38
  | `MakePair` | type | `(tuning?: PairTuning) => Promise<ConnectServePair>`. Called once per test case, so each case gets a fresh transport. |
39
- | `ConnectServePair` | type | `{ connect(): Promise<{ call: Duplex; close(): Promise<void> }>; serve(handler: Duplex): Promise<() => Promise<void>>; close(): Promise<void> }`. |
40
- | `PairTuning` | type | `{ mtu?: number; maxStreamBuffer?: number }`. The flow-control window L6 asks for. |
39
+ | `ConnectServePair` | type | `{ connect(): Promise<{ call: Duplex; close(): Promise<void> }>; serve(handler: Duplex): Promise<() => Promise<void>>; close(): Promise<void>; runAheadBytes?: number }`. `runAheadBytes` is the most bytes a producer may get ahead of a consumer that stopped reading; L6 asserts it (see below). |
40
+ | `PairTuning` | type | `{ maxMessageSize?: number }`. L6 asks for 4 KiB, so its 256 KiB body crosses as many messages; a pair whose transport decides its own ceiling ignores it. |
41
+ | `measureRunAhead(makePair, direction)` | function | L6's run-ahead measurement, for one direction: resolves `{ bound, ahead, complete, intact }`. |
42
+ | `RunAheadMeasurement` | type | What `measureRunAhead` resolves. |
41
43
  | `DescribeDuplexAdapterOptions` | type | `{ concurrency?: number; skipHugeBody?: boolean }`. |
42
44
 
43
45
  | Option | Default | Effect |
@@ -59,32 +61,37 @@ describeDuplexAdapter("my-adapter", makeMyAdapterPair, { skipHugeBody: true });
59
61
 
60
62
  ### Write a pair factory
61
63
 
62
- A pair factory stands up both ends of one transport and forwards the tuning to
63
- the adapter if it can. For an adapter built on `emulateMux`, the tuning maps
64
- directly onto its options:
64
+ A pair factory stands up both ends of one transport. Most adapters are a pipe
65
+ for `@statewalker/webrun-rpc`'s port stack, so the factory runs `overPipe` and
66
+ `webrun-rpc`'s `connect` / `serve` over that pipe. Here the pipe is a
67
+ `MessageChannel`; a real adapter puts its own pipe (and its `signal` and
68
+ `maxMessageSize`) in its place:
65
69
 
66
70
  ```ts
67
71
  // tests/make-pair.ts
68
- import { type ByteChannel, emulateMux } from "@statewalker/webrun-streams";
72
+ import { connect, overPipe, serve, structuredCodec } from "@statewalker/webrun-rpc";
69
73
  import type { MakePair } from "@statewalker/webrun-streams-conformance";
70
74
 
71
- declare function makeChannelPair(): { a: ByteChannel; b: ByteChannel };
72
-
73
- export const makeMyAdapterPair: MakePair = async (tuning) => {
74
- const { a, b } = makeChannelPair();
75
- const client = emulateMux(a, { side: "initiator", ...tuning });
76
- const server = emulateMux(b, { side: "responder", ...tuning });
75
+ export const makeMyAdapterPair: MakePair = async () => {
76
+ const { port1, port2 } = new MessageChannel();
77
+ const codec = structuredCodec;
77
78
  return {
78
- connect: async () => ({ call: client.call, close: async () => {} }),
79
- serve: async (handler) => server.serve(handler),
79
+ runAheadBytes: 8192, // the port stack: a producer is never more than a chunk ahead
80
+ connect: () => connect({ mux: overPipe(port1, { codec, side: "initiator" }) }),
81
+ serve: (handler) => serve({ mux: overPipe(port2, { codec, side: "responder" }) }, handler),
80
82
  close: async () => {
81
- await client.close();
82
- await server.close();
83
+ port1.close();
84
+ port2.close();
83
85
  },
84
86
  };
85
87
  };
86
88
  ```
87
89
 
90
+ The factory may take the suite's `tuning` argument and pass `maxMessageSize`
91
+ on to `overPipe`. `runAheadBytes` declares the transport's buffering; leave it
92
+ out only if the transport has no known bound, and L6 then checks completion
93
+ alone (say why where the pair is declared).
94
+
88
95
  ### Check the suite itself
89
96
 
90
97
  ```ts
@@ -105,22 +112,37 @@ describeDuplexAdapter("loopback", makeLoopbackPair);
105
112
  | L3 | Mid-stream cancellation: the caller breaks out after 3 chunks of an endless response, and within 50 ms the handler's `finally` has run. |
106
113
  | L4 | Error propagation: a handler that throws an `Error` with `status: 418` and `code: "TEAPOT"` makes the caller's `for await` reject with the same `message`, `status` and `code`, and a non-empty `stack`. |
107
114
  | L5 | Teardown: calling the `serve` teardown twice resolves; `pair.close()` after a completed call resolves. |
108
- | L6 | Flow control: a 256 KiB body reaches a consumer that waits 1 ms per chunk, intact and in order, through `{ mtu: 4096, maxStreamBuffer: 16384 }`. |
109
-
110
- ### Why L6 uses a small window and a slow consumer
111
-
112
- At an adapter's default window (8 MiB for `emulateMux`) a 256 KiB body never
113
- exhausts credit, so no sender stalls and no grant is sent, and the test would
114
- pass with flow control removed. A 16 KiB window against a 256 KiB body makes
115
- the sender run out of credit and resume on grants sixteen times. The test
116
- itself checks completion and integrity; stalling and replenishment are covered
117
- by elimination: without grants the transfer hangs and the test times out;
118
- without credit reservation the sender floods the window and the receiver's
119
- buffer cap tears the stream down.
120
-
121
- An adapter that multiplexes natively, or has no configurable window, ignores
122
- `tuning`. For it, L6 is an integrity check at the adapter's own defaults and
123
- nothing more.
115
+ | L6 | Flow control (spec D17): a 256 KiB body crosses as 4 KiB messages to a consumer that waits 1 ms per chunk, intact; and in each direction, a producer of 4 KiB chunks facing a consumer that stops after one chunk stalls within the pair's `runAheadBytes`, then finishes, every byte intact, once the consumer resumes. |
116
+
117
+ ### L6 asserts how far a producer runs ahead (spec D17)
118
+
119
+ L6 used to ask a pair for a small credit window and check that a body crossed
120
+ it. That window was `emulateMux`'s (removed in Plan C3), and with no window to
121
+ shrink the level proved only integrity. Now each pair declares
122
+ `runAheadBytes`, the most a producer may get ahead of a consumer that has
123
+ stopped reading, and L6 measures it, in both directions. The producer yields
124
+ 4 KiB chunks, enough to exceed the bound twice over; the consumer takes one and
125
+ stops; once the producer has produced nothing for a second, `produced −
126
+ consumed` must be at most the bound; then the consumer resumes, and every byte
127
+ must arrive in place (byte k belongs to chunk k / 4096, whatever chunk
128
+ boundaries the transport chose). `measureRunAhead(makePair, direction)` is the
129
+ measurement itself, exported; the package's own `tests/l6-self.test.ts` shows it
130
+ catches a transport that buffers without bound while pulling only every 150 ms,
131
+ and one that duplicates a chunk and drops another.
132
+
133
+ | Pair | `runAheadBytes` | Measured |
134
+ | --- | --- | --- |
135
+ | loopback | 0 | 0 |
136
+ | port stack (`webrun-rpc`, `msgpack` byte pipe, `-ws`, `-peerjs`, `-livekit`) | 4 KiB (one chunk) | 0: the next chunk is produced only once the consumer pulls past the last |
137
+ | `-webrtc` `connect` / `serve` | `RECEIVE_WINDOW` (4 MiB) + 16 KiB | 4 MiB exactly |
138
+ | `-webrtc` port stack (`webrtcPortMux`) | 4 KiB (one chunk) | 0 |
139
+ | `-libp2p` `connect` / `serve` | 2 × the receiving node's yamux window + 256 KiB | 1.06-1.13 MiB with a 1 MiB window (2.00 MiB reading and stalling by turns), 16.05-16.12 MiB with yamux's default 16 MiB (before the paced reader: 22-24 MiB, until libp2p's read buffer aborted the stream) |
140
+ | `-libp2p` port stack (native `libp2pPortMux`, or `overPipe` on one stream) | 4 KiB (one chunk) | 0 |
141
+
142
+ The level dies on what it should: sending port-stack chunks without waiting for
143
+ their confirmation fails it, a WebRTC pair declaring half its window fails it at
144
+ exactly 4 MiB ahead, and a libp2p pair whose reader never pauses fails it (its
145
+ `tests/run-ahead.test.ts`, with the other mutants listed in that package).
124
146
 
125
147
  ### What L5 deliberately does not assert
126
148
 
@@ -1 +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,CAqPN"}
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;AAG9C,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,CAkON"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export { type DescribeDuplexAdapterOptions, describeDuplexAdapter, } from "./describe-duplex-adapter.js";
2
2
  export { type ConnectServePair, type MakePair, makeLoopbackPair, type PairTuning, } from "./loopback.js";
3
+ export { measureRunAhead, type RunAheadMeasurement } from "./run-ahead.js";
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1 +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,EACL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC"}
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,EACL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
package/dist/index.js CHANGED
@@ -1,5 +1,124 @@
1
1
  import { collectBytes } from "@statewalker/webrun-streams";
2
2
  import { describe, expect, it } from "vitest";
3
+ //#region src/run-ahead.ts
4
+ const CHUNK = 4096;
5
+ /** The producer counts as stopped after this long without producing. */
6
+ const QUIET_MS = 1e3;
7
+ /** The longest wait for it to stop. */
8
+ const SETTLE_LIMIT_MS = 8e3;
9
+ const delay$1 = (ms) => new Promise((r) => setTimeout(r, ms));
10
+ /**
11
+ * L6's measurement (spec D17), in one direction: a producer of 4 KiB chunks —
12
+ * chunk i filled with `i & 0xff` — faces a consumer that takes one chunk and
13
+ * stops. Once the producer has made nothing for {@link QUIET_MS}, how far it
14
+ * got ahead is recorded; then the consumer resumes, and every byte is checked
15
+ * in place, whatever chunk boundaries the transport chose. The producer makes
16
+ * enough to exceed a declared bound twice over (a pair with none gets 1 MiB).
17
+ * `response` puts the producer in the handler; `request` puts it in the caller.
18
+ */
19
+ async function measureRunAhead(makePair, direction) {
20
+ const pair = await makePair();
21
+ const bound = pair.runAheadBytes;
22
+ const count = bound === void 0 ? 256 : Math.max(64, Math.ceil((2 * bound + 65536) / CHUNK));
23
+ let produced = 0;
24
+ const producer = async function* () {
25
+ for (let i = 0; i < count; i++) {
26
+ produced++;
27
+ yield new Uint8Array(CHUNK).fill(i & 255);
28
+ }
29
+ };
30
+ /** Checks bytes as they stream past, at their offsets in the whole stream. */
31
+ const checker = () => {
32
+ let offset = 0;
33
+ let intact = true;
34
+ return {
35
+ take(chunk) {
36
+ for (let j = 0; j < chunk.byteLength; j++, offset++) if (chunk[j] !== (Math.floor(offset / CHUNK) & 255)) intact = false;
37
+ },
38
+ get bytes() {
39
+ return offset;
40
+ },
41
+ get intact() {
42
+ return intact;
43
+ }
44
+ };
45
+ };
46
+ const settled = async () => {
47
+ const start = Date.now();
48
+ let last = produced;
49
+ let quietSince = Date.now();
50
+ while (Date.now() - quietSince < QUIET_MS && Date.now() - start < SETTLE_LIMIT_MS) {
51
+ await delay$1(50);
52
+ if (produced !== last) {
53
+ last = produced;
54
+ quietSince = Date.now();
55
+ }
56
+ }
57
+ };
58
+ try {
59
+ if (direction === "response") {
60
+ await pair.serve(async function* (input) {
61
+ for await (const _ of input);
62
+ yield* producer();
63
+ });
64
+ const { call, close } = await pair.connect();
65
+ try {
66
+ const seen = checker();
67
+ const it = call([])[Symbol.asyncIterator]();
68
+ const first = await it.next();
69
+ if (!first.done) seen.take(first.value);
70
+ await settled();
71
+ const ahead = produced * CHUNK - seen.bytes;
72
+ for (let r = await it.next(); !r.done; r = await it.next()) seen.take(r.value);
73
+ return {
74
+ bound,
75
+ ahead,
76
+ complete: seen.bytes === count * CHUNK,
77
+ intact: seen.intact
78
+ };
79
+ } finally {
80
+ await close();
81
+ }
82
+ }
83
+ const seen = checker();
84
+ let resume;
85
+ const gate = new Promise((r) => {
86
+ resume = r;
87
+ });
88
+ await pair.serve(async function* (input) {
89
+ let first = true;
90
+ for await (const chunk of input) {
91
+ seen.take(chunk);
92
+ if (first) {
93
+ first = false;
94
+ yield new Uint8Array([1]);
95
+ await gate;
96
+ }
97
+ }
98
+ yield new Uint8Array([2]);
99
+ });
100
+ const { call, close } = await pair.connect();
101
+ try {
102
+ const it = call(producer())[Symbol.asyncIterator]();
103
+ await it.next();
104
+ await settled();
105
+ const ahead = produced * CHUNK - seen.bytes;
106
+ resume();
107
+ for (let r = await it.next(); !r.done; r = await it.next());
108
+ return {
109
+ bound,
110
+ ahead,
111
+ complete: seen.bytes === count * CHUNK,
112
+ intact: seen.intact
113
+ };
114
+ } finally {
115
+ await close();
116
+ }
117
+ } finally {
118
+ await pair.close();
119
+ }
120
+ }
121
+ //#endregion
3
122
  //#region src/describe-duplex-adapter.ts
4
123
  /**
5
124
  * Runs every conformance level (L0–L6) against the supplied `ConnectServePair`
@@ -195,36 +314,31 @@ function describeDuplexAdapter(name, makePair, opts = {}) {
195
314
  });
196
315
  });
197
316
  describe("L6: flow control", () => {
198
- it("delivers a body many times the advertised window to a slow consumer", async () => {
199
- const pair = await makePair({
200
- mtu: 4096,
201
- maxStreamBuffer: 16384
202
- });
317
+ it("delivers a 256 KiB body, crossing as many messages, to a slow consumer", async () => {
318
+ const pair = await makePair({ maxMessageSize: 4096 });
203
319
  try {
204
320
  await pair.serve(echoHandler);
205
321
  const size = 262144;
206
322
  const body = new Uint8Array(size);
207
323
  for (let i = 0; i < size; i++) body[i] = i & 255;
208
324
  const { call, close } = await pair.connect();
209
- const out = call([body]);
210
- let received = 0;
211
- let first = -1;
212
- let last = -1;
213
- for await (const chunk of out) {
214
- if (chunk.byteLength === 0) continue;
215
- if (first < 0) first = chunk[0];
216
- last = chunk[chunk.byteLength - 1];
217
- received += chunk.byteLength;
325
+ const received = [];
326
+ for await (const chunk of call([body])) {
327
+ received.push(chunk);
218
328
  await delay(1);
219
329
  }
220
- expect(received).toBe(size);
221
- expect(first).toBe(0);
222
- expect(last).toBe(255);
330
+ expect(bytesEqual(concat(received), body)).toBe(true);
223
331
  await close();
224
332
  } finally {
225
333
  await pair.close();
226
334
  }
227
335
  });
336
+ for (const direction of ["response", "request"]) it(`${direction} run-ahead: a producer facing a consumer that stopped reading stays within the pair's declared bound (none declared: completion only), and every byte arrives in place once it resumes`, async () => {
337
+ const r = await measureRunAhead(makePair, direction);
338
+ if (r.bound !== void 0) expect(r.ahead).toBeLessThanOrEqual(r.bound);
339
+ expect(r.complete).toBe(true);
340
+ expect(r.intact).toBe(true);
341
+ }, 6e4);
228
342
  });
229
343
  });
230
344
  }
@@ -244,13 +358,22 @@ function bytesEqual(a, b) {
244
358
  function delay(ms) {
245
359
  return new Promise((r) => setTimeout(r, ms));
246
360
  }
361
+ function concat(chunks) {
362
+ const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0));
363
+ let at = 0;
364
+ for (const c of chunks) {
365
+ out.set(c, at);
366
+ at += c.byteLength;
367
+ }
368
+ return out;
369
+ }
247
370
  //#endregion
248
371
  //#region src/loopback.ts
249
372
  /**
250
373
  * Loopback pair: `call` invokes the registered `handler` directly, no
251
374
  * transport. The conformance suite must pass against this — it self-validates
252
375
  * that the assertions are correctly formulated independent of any wire
253
- * protocol or `emulateMux` behaviour.
376
+ * protocol or multiplexer.
254
377
  */
255
378
  const makeLoopbackPair = async () => {
256
379
  let handler = null;
@@ -265,6 +388,7 @@ const makeLoopbackPair = async () => {
265
388
  return handler(input);
266
389
  };
267
390
  return {
391
+ runAheadBytes: 0,
268
392
  async connect() {
269
393
  return {
270
394
  call,
@@ -284,4 +408,4 @@ const makeLoopbackPair = async () => {
284
408
  };
285
409
  };
286
410
  //#endregion
287
- export { describeDuplexAdapter, makeLoopbackPair };
411
+ export { describeDuplexAdapter, makeLoopbackPair, measureRunAhead };
@@ -10,22 +10,29 @@ export interface ConnectServePair {
10
10
  }>;
11
11
  serve(handler: Duplex): Promise<() => Promise<void>>;
12
12
  close(): Promise<void>;
13
+ /**
14
+ * The most bytes a producer may get ahead of a consumer that has stopped
15
+ * reading — this transport's buffering between the two ends. L6 asserts it,
16
+ * in both directions (spec D17). Omitted, the pair claims no bound and L6
17
+ * checks only that a stalled transfer completes once the consumer resumes;
18
+ * the test title says so.
19
+ */
20
+ runAheadBytes?: number;
13
21
  }
14
22
  /**
15
- * Flow-control tuning L6 asks a pair for. An adapter that can pass these
16
- * through to its `emulateMux` should; one that multiplexes natively, or has
17
- * no configurable window, ignores them and L6 degrades to an integrity check.
23
+ * What L6 asks of a pair (spec D17): bodies crossing as many messages. A pair
24
+ * that can set its payload ceiling passes `maxMessageSize` on; one whose
25
+ * transport decides ignores it.
18
26
  */
19
27
  export interface PairTuning {
20
- mtu?: number;
21
- maxStreamBuffer?: number;
28
+ maxMessageSize?: number;
22
29
  }
23
30
  export type MakePair = (tuning?: PairTuning) => Promise<ConnectServePair>;
24
31
  /**
25
32
  * Loopback pair: `call` invokes the registered `handler` directly, no
26
33
  * transport. The conformance suite must pass against this — it self-validates
27
34
  * that the assertions are correctly formulated independent of any wire
28
- * protocol or `emulateMux` behaviour.
35
+ * protocol or multiplexer.
29
36
  */
30
37
  export declare const makeLoopbackPair: MakePair;
31
38
  //# sourceMappingURL=loopback.d.ts.map
@@ -1 +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;;;;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"}
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;IACvB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QA0C9B,CAAC"}
@@ -0,0 +1,23 @@
1
+ import type { MakePair } from "./loopback.js";
2
+ /** What {@link measureRunAhead} saw. */
3
+ export interface RunAheadMeasurement {
4
+ /** The pair's declared `runAheadBytes` (undefined: it claims no bound). */
5
+ bound?: number;
6
+ /** Bytes produced beyond what the stalled consumer had taken, once the producer stopped. */
7
+ ahead: number;
8
+ /** Every chunk arrived once the consumer resumed. */
9
+ complete: boolean;
10
+ /** Every byte arrived in place: byte k of the stream belongs to chunk floor(k / 4096). */
11
+ intact: boolean;
12
+ }
13
+ /**
14
+ * L6's measurement (spec D17), in one direction: a producer of 4 KiB chunks —
15
+ * chunk i filled with `i & 0xff` — faces a consumer that takes one chunk and
16
+ * stops. Once the producer has made nothing for {@link QUIET_MS}, how far it
17
+ * got ahead is recorded; then the consumer resumes, and every byte is checked
18
+ * in place, whatever chunk boundaries the transport chose. The producer makes
19
+ * enough to exceed a declared bound twice over (a pair with none gets 1 MiB).
20
+ * `response` puts the producer in the handler; `request` puts it in the caller.
21
+ */
22
+ export declare function measureRunAhead(makePair: MakePair, direction: "response" | "request"): Promise<RunAheadMeasurement>;
23
+ //# sourceMappingURL=run-ahead.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-ahead.d.ts","sourceRoot":"","sources":["../src/run-ahead.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,0FAA0F;IAC1F,MAAM,EAAE,OAAO,CAAC;CACjB;AAUD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,UAAU,GAAG,SAAS,GAChC,OAAO,CAAC,mBAAmB,CAAC,CA8F9B"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-conformance",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Conformance test suite for Duplex/Connect/Serve adapters in the webrun-streams-* family",
@@ -30,8 +30,8 @@
30
30
  "src"
31
31
  ],
32
32
  "dependencies": {
33
- "vitest": "^5.0.3",
34
- "@statewalker/webrun-streams": "^0.2.3"
33
+ "vitest": "^5.0.5",
34
+ "@statewalker/webrun-streams": "^0.3.0"
35
35
  },
36
36
  "devDependencies": {
37
37
  "@biomejs/biome": "^2.5.15",
@@ -1,6 +1,7 @@
1
1
  import { collectBytes, type Duplex } from "@statewalker/webrun-streams";
2
2
  import { describe, expect, it } from "vitest";
3
3
  import type { MakePair } from "./loopback.js";
4
+ import { measureRunAhead } from "./run-ahead.js";
4
5
 
5
6
  export interface DescribeDuplexAdapterOptions {
6
7
  /** Number of concurrent calls for L1. Default 10. */
@@ -214,53 +215,34 @@ export function describeDuplexAdapter(
214
215
  });
215
216
 
216
217
  describe("L6: flow control", () => {
217
- it("delivers a body many times the advertised window to a slow consumer", async () => {
218
- // A 16 KiB window against a 256 KiB body: the sender must exhaust its
219
- // credit and wait for grants sixteen times over. An adapter that
220
- // ignores the tuning runs this at its own defaults, where it degrades
221
- // to an integrity check — that is stated in the README, not hidden.
222
- //
223
- // What the assertions below check is completion and integrity. That
224
- // this level also proves *stalling and replenishment* is an
225
- // elimination argument that lives in the mutations, not in this body:
226
- // delete the grant `ACK` and replenishment dies, so the transfer hangs
227
- // and this times out; bypass `reserve()` and stalling dies, so the
228
- // sender floods the window and the receiver's cap tears the stream
229
- // down. Both are measured in the plan's Task 5 Step 4 table. Keep the
230
- // small window and the slow drain — at the adapters' defaults nothing
231
- // stalls, no grant is emitted, and this level passes with credit
232
- // deleted entirely. An earlier draft shipped exactly that while
233
- // claiming otherwise.
234
- const pair = await makePair({ mtu: 4096, maxStreamBuffer: 16 * 1024 });
218
+ it("delivers a 256 KiB body, crossing as many messages, to a slow consumer", async () => {
219
+ const pair = await makePair({ maxMessageSize: 4096 });
235
220
  try {
236
221
  await pair.serve(echoHandler);
237
222
  const size = 256 * 1024;
238
223
  const body = new Uint8Array(size);
239
224
  for (let i = 0; i < size; i++) body[i] = i & 0xff;
240
-
241
225
  const { call, close } = await pair.connect();
242
- const out = call([body]);
243
- let received = 0;
244
- let first = -1;
245
- let last = -1;
246
- for await (const chunk of out) {
247
- if (chunk.byteLength === 0) continue;
248
- if (first < 0) first = chunk[0] as number;
249
- last = chunk[chunk.byteLength - 1] as number;
250
- received += chunk.byteLength;
251
- // Drain deliberately slowly, so the sender is stalled on credit
252
- // for most of the transfer rather than streaming through.
226
+ const received: Uint8Array[] = [];
227
+ for await (const chunk of call([body])) {
228
+ received.push(chunk);
253
229
  await delay(1);
254
230
  }
255
-
256
- expect(received).toBe(size);
257
- expect(first).toBe(0);
258
- expect(last).toBe((size - 1) & 0xff);
231
+ expect(bytesEqual(concat(received), body)).toBe(true);
259
232
  await close();
260
233
  } finally {
261
234
  await pair.close();
262
235
  }
263
236
  });
237
+
238
+ for (const direction of ["response", "request"] as const) {
239
+ it(`${direction} run-ahead: a producer facing a consumer that stopped reading stays within the pair's declared bound (none declared: completion only), and every byte arrives in place once it resumes`, async () => {
240
+ const r = await measureRunAhead(makePair, direction);
241
+ if (r.bound !== undefined) expect(r.ahead).toBeLessThanOrEqual(r.bound);
242
+ expect(r.complete).toBe(true);
243
+ expect(r.intact).toBe(true);
244
+ }, 60_000);
245
+ }
264
246
  });
265
247
  });
266
248
  }
@@ -289,3 +271,13 @@ function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
289
271
  function delay(ms: number): Promise<void> {
290
272
  return new Promise((r) => setTimeout(r, ms));
291
273
  }
274
+
275
+ function concat(chunks: Uint8Array[]): Uint8Array {
276
+ const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0));
277
+ let at = 0;
278
+ for (const c of chunks) {
279
+ out.set(c, at);
280
+ at += c.byteLength;
281
+ }
282
+ return out;
283
+ }
package/src/index.ts CHANGED
@@ -8,3 +8,4 @@ export {
8
8
  makeLoopbackPair,
9
9
  type PairTuning,
10
10
  } from "./loopback.js";
11
+ export { measureRunAhead, type RunAheadMeasurement } from "./run-ahead.js";
package/src/loopback.ts CHANGED
@@ -8,16 +8,23 @@ export interface ConnectServePair {
8
8
  connect(): Promise<{ call: Duplex; close: () => Promise<void> }>;
9
9
  serve(handler: Duplex): Promise<() => Promise<void>>;
10
10
  close(): Promise<void>;
11
+ /**
12
+ * The most bytes a producer may get ahead of a consumer that has stopped
13
+ * reading — this transport's buffering between the two ends. L6 asserts it,
14
+ * in both directions (spec D17). Omitted, the pair claims no bound and L6
15
+ * checks only that a stalled transfer completes once the consumer resumes;
16
+ * the test title says so.
17
+ */
18
+ runAheadBytes?: number;
11
19
  }
12
20
 
13
21
  /**
14
- * Flow-control tuning L6 asks a pair for. An adapter that can pass these
15
- * through to its `emulateMux` should; one that multiplexes natively, or has
16
- * no configurable window, ignores them and L6 degrades to an integrity check.
22
+ * What L6 asks of a pair (spec D17): bodies crossing as many messages. A pair
23
+ * that can set its payload ceiling passes `maxMessageSize` on; one whose
24
+ * transport decides ignores it.
17
25
  */
18
26
  export interface PairTuning {
19
- mtu?: number;
20
- maxStreamBuffer?: number;
27
+ maxMessageSize?: number;
21
28
  }
22
29
 
23
30
  export type MakePair = (tuning?: PairTuning) => Promise<ConnectServePair>;
@@ -26,7 +33,7 @@ export type MakePair = (tuning?: PairTuning) => Promise<ConnectServePair>;
26
33
  * Loopback pair: `call` invokes the registered `handler` directly, no
27
34
  * transport. The conformance suite must pass against this — it self-validates
28
35
  * that the assertions are correctly formulated independent of any wire
29
- * protocol or `emulateMux` behaviour.
36
+ * protocol or multiplexer.
30
37
  */
31
38
  export const makeLoopbackPair: MakePair = async () => {
32
39
  let handler: Duplex | null = null;
@@ -49,6 +56,8 @@ export const makeLoopbackPair: MakePair = async () => {
49
56
  };
50
57
 
51
58
  return {
59
+ // `call` is the handler itself: a value is produced only when pulled.
60
+ runAheadBytes: 0,
52
61
  async connect() {
53
62
  return {
54
63
  call,
@@ -0,0 +1,129 @@
1
+ import type { MakePair } from "./loopback.js";
2
+
3
+ /** What {@link measureRunAhead} saw. */
4
+ export interface RunAheadMeasurement {
5
+ /** The pair's declared `runAheadBytes` (undefined: it claims no bound). */
6
+ bound?: number;
7
+ /** Bytes produced beyond what the stalled consumer had taken, once the producer stopped. */
8
+ ahead: number;
9
+ /** Every chunk arrived once the consumer resumed. */
10
+ complete: boolean;
11
+ /** Every byte arrived in place: byte k of the stream belongs to chunk floor(k / 4096). */
12
+ intact: boolean;
13
+ }
14
+
15
+ const CHUNK = 4096;
16
+ /** The producer counts as stopped after this long without producing. */
17
+ const QUIET_MS = 1000;
18
+ /** The longest wait for it to stop. */
19
+ const SETTLE_LIMIT_MS = 8000;
20
+
21
+ const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
22
+
23
+ /**
24
+ * L6's measurement (spec D17), in one direction: a producer of 4 KiB chunks —
25
+ * chunk i filled with `i & 0xff` — faces a consumer that takes one chunk and
26
+ * stops. Once the producer has made nothing for {@link QUIET_MS}, how far it
27
+ * got ahead is recorded; then the consumer resumes, and every byte is checked
28
+ * in place, whatever chunk boundaries the transport chose. The producer makes
29
+ * enough to exceed a declared bound twice over (a pair with none gets 1 MiB).
30
+ * `response` puts the producer in the handler; `request` puts it in the caller.
31
+ */
32
+ export async function measureRunAhead(
33
+ makePair: MakePair,
34
+ direction: "response" | "request",
35
+ ): Promise<RunAheadMeasurement> {
36
+ const pair = await makePair();
37
+ const bound = pair.runAheadBytes;
38
+ const count =
39
+ bound === undefined ? 256 : Math.max(64, Math.ceil((2 * bound + 64 * 1024) / CHUNK));
40
+ let produced = 0;
41
+ const producer = async function* () {
42
+ for (let i = 0; i < count; i++) {
43
+ produced++;
44
+ yield new Uint8Array(CHUNK).fill(i & 0xff);
45
+ }
46
+ };
47
+ /** Checks bytes as they stream past, at their offsets in the whole stream. */
48
+ const checker = () => {
49
+ let offset = 0;
50
+ let intact = true;
51
+ return {
52
+ take(chunk: Uint8Array) {
53
+ for (let j = 0; j < chunk.byteLength; j++, offset++) {
54
+ if (chunk[j] !== (Math.floor(offset / CHUNK) & 0xff)) intact = false;
55
+ }
56
+ },
57
+ get bytes() {
58
+ return offset;
59
+ },
60
+ get intact() {
61
+ return intact;
62
+ },
63
+ };
64
+ };
65
+ const settled = async () => {
66
+ const start = Date.now();
67
+ let last = produced;
68
+ let quietSince = Date.now();
69
+ while (Date.now() - quietSince < QUIET_MS && Date.now() - start < SETTLE_LIMIT_MS) {
70
+ await delay(50);
71
+ if (produced !== last) {
72
+ last = produced;
73
+ quietSince = Date.now();
74
+ }
75
+ }
76
+ };
77
+ try {
78
+ if (direction === "response") {
79
+ await pair.serve(async function* (input) {
80
+ for await (const _ of input);
81
+ yield* producer();
82
+ });
83
+ const { call, close } = await pair.connect();
84
+ try {
85
+ const seen = checker();
86
+ const it = call([])[Symbol.asyncIterator]();
87
+ const first = await it.next();
88
+ if (!first.done) seen.take(first.value);
89
+ await settled();
90
+ const ahead = produced * CHUNK - seen.bytes;
91
+ for (let r = await it.next(); !r.done; r = await it.next()) seen.take(r.value);
92
+ return { bound, ahead, complete: seen.bytes === count * CHUNK, intact: seen.intact };
93
+ } finally {
94
+ await close();
95
+ }
96
+ }
97
+ const seen = checker();
98
+ let resume!: () => void;
99
+ const gate = new Promise<void>((r) => {
100
+ resume = r;
101
+ });
102
+ await pair.serve(async function* (input) {
103
+ let first = true;
104
+ for await (const chunk of input) {
105
+ seen.take(chunk);
106
+ if (first) {
107
+ first = false;
108
+ yield new Uint8Array([1]); // the first chunk arrived
109
+ await gate;
110
+ }
111
+ }
112
+ yield new Uint8Array([2]); // the input ended
113
+ });
114
+ const { call, close } = await pair.connect();
115
+ try {
116
+ const it = call(producer())[Symbol.asyncIterator]();
117
+ await it.next();
118
+ await settled();
119
+ const ahead = produced * CHUNK - seen.bytes;
120
+ resume();
121
+ for (let r = await it.next(); !r.done; r = await it.next());
122
+ return { bound, ahead, complete: seen.bytes === count * CHUNK, intact: seen.intact };
123
+ } finally {
124
+ await close();
125
+ }
126
+ } finally {
127
+ await pair.close();
128
+ }
129
+ }