@statewalker/webrun-streams-conformance 0.3.1 → 0.3.3

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.
Files changed (2) hide show
  1. package/README.md +125 -53
  2. package/package.json +8 -4
package/README.md CHANGED
@@ -1,84 +1,156 @@
1
1
  # @statewalker/webrun-streams-conformance
2
2
 
3
- 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.
3
+ ## What it is
4
4
 
5
- ## Why it exists
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
- The promise of the [`webrun-streams`](../webrun-streams) seam is that a handler
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
- None of those show up in an adapter's own happy-path tests. This package makes
15
- them a shared, executable definition of "correct", so a new transport is a
16
- day's work rather than a new set of subtle incompatibilities.
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
- ## Install
23
+ ## How to use
19
24
 
20
25
  ```sh
21
- npm install --save-dev @statewalker/webrun-streams-conformance
26
+ pnpm add -D @statewalker/webrun-streams-conformance
22
27
  ```
23
28
 
24
- It is a **test-time** dependency: it bundles `vitest` and defines suites via
25
- `describe` / `it`.
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
- ## Levels asserted
28
-
29
- - **L0** Envelope round-trip via an echo handler for body sizes empty / 1 KiB / 1 MiB / 10 MiB.
30
- - **L1** N concurrent calls (default 10) with correct per-call body identity.
31
- - **L2** Half-close — caller exhausts input; handler keeps yielding response chunks.
32
- - **L3** Mid-stream cancellation — caller `.return()`s output; handler's `finally` runs.
33
- - **L4** Error propagation — handler `throw`s; caller sees `message` + `stack` + custom fields preserved.
34
- - **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.)
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
- ## Reference loopback
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
- `makeLoopbackPair()` returns a `ConnectServePair` whose `call` invokes the registered `handler` directly with no transport. The suite must pass green against the loopback — this is the self-test that the assertions are correctly formulated.
48
+ ## Examples
40
49
 
41
- ## Usage
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
- `makeMyAdapterPair` is a `MakePair` — an async factory returning a
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 third argument tunes the suite:
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
- | Option | Default | Effect |
57
- | --- | --- | --- |
58
- | `concurrency` | `10` | How many concurrent calls L1 runs. |
59
- | `skipHugeBody` | `false` | Drop L0's 10 MiB case, for transports that rate-limit. |
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
- ## API
88
+ ### Check the suite itself
62
89
 
63
- | Export | Kind | Purpose |
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
- ## Dependencies
93
+ describeDuplexAdapter("loopback", makeLoopbackPair);
94
+ ```
73
95
 
74
- | Dependency | Kind | Why |
75
- | --- | --- | --- |
76
- | [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam under test. |
77
- | `vitest` | runtime | The suite is defined with `describe` / `it`. |
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
- Consumed as a `devDependency` by every adapter in the family. ESM only
80
- (`"type": "module"`).
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 © statewalker — see [LICENSE](../../LICENSE).
156
+ MIT
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-conformance",
3
- "version": "0.3.1",
3
+ "version": "0.3.3",
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
- "homepage": "https://github.com/statewalker/webrun-wire",
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,7 +15,8 @@
12
15
  "license": "MIT",
13
16
  "repository": {
14
17
  "type": "git",
15
- "url": "git@github.com:statewalker/webrun-wire.git"
18
+ "url": "git+https://github.com/statewalker/webrun-wire.git",
19
+ "directory": "packages/webrun-streams-conformance"
16
20
  },
17
21
  "exports": {
18
22
  ".": {
@@ -27,7 +31,7 @@
27
31
  ],
28
32
  "dependencies": {
29
33
  "vitest": "^5.0.3",
30
- "@statewalker/webrun-streams": "^0.2.1"
34
+ "@statewalker/webrun-streams": "^0.2.3"
31
35
  },
32
36
  "devDependencies": {
33
37
  "@biomejs/biome": "^2.5.15",