@statewalker/webrun-streams-conformance 0.2.0 → 0.3.2
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/LICENSE +21 -0
- package/README.md +125 -53
- package/package.json +13 -7
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022-2026 statewalker
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,84 +1,156 @@
|
|
|
1
1
|
# @statewalker/webrun-streams-conformance
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A Vitest suite that checks a transport adapter against the `Duplex` /
|
|
6
|
+
`Connect` / `Serve` seam from `@statewalker/webrun-streams`. An adapter calls
|
|
7
|
+
`describeDuplexAdapter(name, makePair)` from one test file, with a factory that
|
|
8
|
+
stands up a fresh client/server pair, and gets seven levels of checks (L0 to
|
|
9
|
+
L6): large bodies, concurrency, half-close, cancellation, error propagation,
|
|
10
|
+
teardown and flow control. It also ships `makeLoopbackPair`, a pair with no
|
|
11
|
+
transport at all, which the suite must pass against.
|
|
6
12
|
|
|
7
|
-
|
|
8
|
-
written once runs over *any* transport. That promise is only as good as the
|
|
9
|
-
weakest adapter — and the failure modes that break it are the quiet ones: an
|
|
10
|
-
adapter that works for small bodies but truncates at 10 MiB, that serialises
|
|
11
|
-
concurrent calls, that drops a handler's `finally` on cancellation, or that
|
|
12
|
-
turns a thrown `Error` into an anonymous disconnect.
|
|
13
|
+
## Why it exists
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
15
|
+
The seam promises that a handler written once runs over any transport. That
|
|
16
|
+
holds only as far as the weakest adapter, and the failures that break it are
|
|
17
|
+
quiet ones: an adapter that works for small bodies but truncates at 10 MiB,
|
|
18
|
+
serialises concurrent calls, skips a handler's `finally` on cancellation, or
|
|
19
|
+
turns a thrown `Error` into an anonymous disconnect. An adapter's own
|
|
20
|
+
happy-path tests do not catch these. This package makes them one shared,
|
|
21
|
+
executable definition of "correct" that every adapter runs.
|
|
17
22
|
|
|
18
|
-
##
|
|
23
|
+
## How to use
|
|
19
24
|
|
|
20
25
|
```sh
|
|
21
|
-
|
|
26
|
+
pnpm add -D @statewalker/webrun-streams-conformance
|
|
22
27
|
```
|
|
23
28
|
|
|
24
|
-
It is a
|
|
25
|
-
`
|
|
29
|
+
It is a test-time dependency. It imports `describe`, `it` and `expect` from
|
|
30
|
+
`vitest`, so `describeDuplexAdapter` must be called from a file Vitest is
|
|
31
|
+
running. Runtime dependencies: `@statewalker/webrun-streams` and `vitest`. No
|
|
32
|
+
peer dependencies. One entry point, `.`.
|
|
26
33
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- **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.
|
|
34
|
+
| Export | Kind | What it gives |
|
|
35
|
+
| --- | --- | --- |
|
|
36
|
+
| `describeDuplexAdapter(name, makePair, options?)` | function | Registers L0 to L6 under `describe("<name> — Duplex conformance")`. |
|
|
37
|
+
| `makeLoopbackPair` | `MakePair` | Reference pair: `call` invokes the registered handler directly. |
|
|
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. |
|
|
41
|
+
| `DescribeDuplexAdapterOptions` | type | `{ concurrency?: number; skipHugeBody?: boolean }`. |
|
|
36
42
|
|
|
37
|
-
|
|
43
|
+
| Option | Default | Effect |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| `concurrency` | `10` | How many concurrent calls L1 runs. |
|
|
46
|
+
| `skipHugeBody` | `false` | Drop L0's 10 MiB case, for transports that rate-limit or are slow. |
|
|
38
47
|
|
|
39
|
-
|
|
48
|
+
## Examples
|
|
40
49
|
|
|
41
|
-
|
|
50
|
+
### Run the suite against an adapter
|
|
42
51
|
|
|
43
52
|
```ts
|
|
53
|
+
// tests/conformance.test.ts
|
|
44
54
|
import { describeDuplexAdapter } from "@statewalker/webrun-streams-conformance";
|
|
45
55
|
import { makeMyAdapterPair } from "./make-pair.js";
|
|
46
56
|
|
|
47
|
-
describeDuplexAdapter("my-adapter", makeMyAdapterPair);
|
|
57
|
+
describeDuplexAdapter("my-adapter", makeMyAdapterPair, { skipHugeBody: true });
|
|
48
58
|
```
|
|
49
59
|
|
|
50
|
-
|
|
51
|
-
`ConnectServePair` (`connect()`, `serve(handler)`, `close()`). It is called
|
|
52
|
-
once per test case, so each gets a fresh transport.
|
|
60
|
+
### Write a pair factory
|
|
53
61
|
|
|
54
|
-
A
|
|
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:
|
|
55
65
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
66
|
+
```ts
|
|
67
|
+
// tests/make-pair.ts
|
|
68
|
+
import { type ByteChannel, emulateMux } from "@statewalker/webrun-streams";
|
|
69
|
+
import type { MakePair } from "@statewalker/webrun-streams-conformance";
|
|
70
|
+
|
|
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 });
|
|
77
|
+
return {
|
|
78
|
+
connect: async () => ({ call: client.call, close: async () => {} }),
|
|
79
|
+
serve: async (handler) => server.serve(handler),
|
|
80
|
+
close: async () => {
|
|
81
|
+
await client.close();
|
|
82
|
+
await server.close();
|
|
83
|
+
},
|
|
84
|
+
};
|
|
85
|
+
};
|
|
86
|
+
```
|
|
60
87
|
|
|
61
|
-
|
|
88
|
+
### Check the suite itself
|
|
62
89
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
| `describeDuplexAdapter(name, makePair, options?)` | function | Registers the whole L0–L6 suite for one adapter. |
|
|
66
|
-
| `makeLoopbackPair()` | `MakePair` | The reference in-process pair; the suite's own self-test. |
|
|
67
|
-
| `MakePair` | type | `(tuning?: PairTuning) => Promise<ConnectServePair>` — called once per test case. |
|
|
68
|
-
| `ConnectServePair` | type | `{ connect(), serve(handler), close() }`. |
|
|
69
|
-
| `PairTuning` | type | `{ mtu?, maxStreamBuffer? }` — flow-control window L6 asks a pair for; an adapter that can forward it to `emulateMux` should. |
|
|
70
|
-
| `DescribeDuplexAdapterOptions` | type | `concurrency` (default 10), `skipHugeBody` (default false). |
|
|
90
|
+
```ts
|
|
91
|
+
import { describeDuplexAdapter, makeLoopbackPair } from "@statewalker/webrun-streams-conformance";
|
|
71
92
|
|
|
72
|
-
|
|
93
|
+
describeDuplexAdapter("loopback", makeLoopbackPair);
|
|
94
|
+
```
|
|
73
95
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
96
|
+
## Internals
|
|
97
|
+
|
|
98
|
+
### What each level asserts
|
|
99
|
+
|
|
100
|
+
| Level | Assertion |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| L0 | An echo handler round-trips bodies of 0 B, 1 KiB, 1 MiB and 10 MiB byte for byte. |
|
|
103
|
+
| L1 | `concurrency` concurrent calls each get back their own body. |
|
|
104
|
+
| L2 | Half-close: after the caller's input ends, the handler keeps yielding (three chunks, 30 ms apart) and the caller receives all of them. |
|
|
105
|
+
| 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
|
+
| 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
|
+
| 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.
|
|
124
|
+
|
|
125
|
+
### What L5 deliberately does not assert
|
|
126
|
+
|
|
127
|
+
L5 does not check what an in-flight call does when the transport closes under
|
|
128
|
+
it. That behaviour differs between transports, and each adapter tests it
|
|
129
|
+
itself.
|
|
130
|
+
|
|
131
|
+
### Why the loopback pair exists
|
|
132
|
+
|
|
133
|
+
`makeLoopbackPair` has no wire protocol and no multiplexer, so a failure
|
|
134
|
+
against it is a bug in the assertions, not in a transport. After
|
|
135
|
+
`pair.close()`, or before a handler is registered, its `call` returns a
|
|
136
|
+
generator that throws `loopback: pair closed` or
|
|
137
|
+
`loopback: no handler registered`.
|
|
138
|
+
|
|
139
|
+
### Constraints
|
|
140
|
+
|
|
141
|
+
- Body bytes are a deterministic fill, not `crypto.getRandomValues`, which is
|
|
142
|
+
limited to 64 KiB per call in browsers. The bytes only need to round-trip.
|
|
143
|
+
- Every test creates its own pair and closes it in a `finally`, so a factory
|
|
144
|
+
must support being called many times in one file.
|
|
145
|
+
|
|
146
|
+
### Dependencies
|
|
78
147
|
|
|
79
|
-
|
|
80
|
-
|
|
148
|
+
- `@statewalker/webrun-streams` (`workspace:^`): the `Duplex` type and
|
|
149
|
+
`collectBytes`.
|
|
150
|
+
- `vitest`: the suite is defined with `describe` / `it` / `expect`. It is a
|
|
151
|
+
regular dependency, not a peer, so the consumer's Vitest and this package's
|
|
152
|
+
should resolve to the same installed copy.
|
|
81
153
|
|
|
82
154
|
## License
|
|
83
155
|
|
|
84
|
-
MIT
|
|
156
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/webrun-streams-conformance",
|
|
3
|
-
"version": "0.2
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Conformance test suite for Duplex/Connect/Serve adapters in the webrun-streams-* family",
|
|
7
|
-
"
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/statewalker/webrun-wire/issues"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-streams-conformance#readme",
|
|
8
11
|
"author": {
|
|
9
12
|
"name": "Mikhail Kotelnikov",
|
|
10
13
|
"email": "mikhail.kotelnikov@gmail.com"
|
|
@@ -12,10 +15,12 @@
|
|
|
12
15
|
"license": "MIT",
|
|
13
16
|
"repository": {
|
|
14
17
|
"type": "git",
|
|
15
|
-
"url": "git
|
|
18
|
+
"url": "git+https://github.com/statewalker/webrun-wire.git",
|
|
19
|
+
"directory": "packages/webrun-streams-conformance"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
22
|
".": {
|
|
23
|
+
"source": "./src/index.ts",
|
|
19
24
|
"types": "./dist/index.d.ts",
|
|
20
25
|
"import": "./dist/index.js"
|
|
21
26
|
}
|
|
@@ -25,13 +30,14 @@
|
|
|
25
30
|
"src"
|
|
26
31
|
],
|
|
27
32
|
"dependencies": {
|
|
28
|
-
"vitest": "^
|
|
29
|
-
"@statewalker/webrun-streams": "0.2.
|
|
33
|
+
"vitest": "^5.0.3",
|
|
34
|
+
"@statewalker/webrun-streams": "^0.2.2"
|
|
30
35
|
},
|
|
31
36
|
"devDependencies": {
|
|
32
|
-
"@
|
|
37
|
+
"@biomejs/biome": "^2.5.15",
|
|
38
|
+
"@types/node": "^26.6.4",
|
|
33
39
|
"rimraf": "^6.1.3",
|
|
34
|
-
"rolldown": "^1.2.
|
|
40
|
+
"rolldown": "^1.2.12",
|
|
35
41
|
"typescript": "^7.0.2"
|
|
36
42
|
},
|
|
37
43
|
"sideEffects": false,
|