@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 +54 -32
- package/dist/describe-duplex-adapter.d.ts.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +143 -19
- package/dist/loopback.d.ts +13 -6
- package/dist/loopback.d.ts.map +1 -1
- package/dist/run-ahead.d.ts +23 -0
- package/dist/run-ahead.d.ts.map +1 -0
- package/package.json +3 -3
- package/src/describe-duplex-adapter.ts +26 -34
- package/src/index.ts +1 -0
- package/src/loopback.ts +15 -6
- package/src/run-ahead.ts +129 -0
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 | `{
|
|
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
|
|
63
|
-
|
|
64
|
-
|
|
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 {
|
|
72
|
+
import { connect, overPipe, serve, structuredCodec } from "@statewalker/webrun-rpc";
|
|
69
73
|
import type { MakePair } from "@statewalker/webrun-streams-conformance";
|
|
70
74
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
79
|
-
|
|
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
|
-
|
|
82
|
-
|
|
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
|
|
109
|
-
|
|
110
|
-
###
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
the
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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;
|
|
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
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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
|
|
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
|
|
210
|
-
|
|
211
|
-
|
|
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(
|
|
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
|
|
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 };
|
package/dist/loopback.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
-
|
|
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
|
|
35
|
+
* protocol or multiplexer.
|
|
29
36
|
*/
|
|
30
37
|
export declare const makeLoopbackPair: MakePair;
|
|
31
38
|
//# sourceMappingURL=loopback.d.ts.map
|
package/dist/loopback.d.ts.map
CHANGED
|
@@ -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,
|
|
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
|
+
"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.
|
|
34
|
-
"@statewalker/webrun-streams": "^0.
|
|
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
|
|
218
|
-
|
|
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
|
|
243
|
-
|
|
244
|
-
|
|
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
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
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
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
|
-
|
|
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
|
|
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,
|
package/src/run-ahead.ts
ADDED
|
@@ -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
|
+
}
|