@statewalker/webrun-streams-peerjs 0.2.2 → 0.2.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.
- package/README.md +95 -81
- package/package.json +9 -5
package/README.md
CHANGED
|
@@ -1,70 +1,80 @@
|
|
|
1
1
|
# @statewalker/webrun-streams-peerjs
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`webrun-streams-*` family.
|
|
3
|
+
## What it is
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
logical calls on top of it.
|
|
12
|
-
|
|
13
|
-
Your handler is an ordinary `Duplex` —
|
|
14
|
-
`(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` — identical
|
|
15
|
-
to the one you would run over a WebSocket or a `MessagePort`.
|
|
5
|
+
A `Connect` / `Serve` adapter that runs `@statewalker/webrun-streams` `Duplex` calls over a PeerJS
|
|
6
|
+
[`DataConnection`](https://peerjs.com/docs/#dataconnection). One connection becomes one
|
|
7
|
+
`ByteChannel`, and `webrun-streams`' `emulateMux` runs many concurrent calls over it. Your handler
|
|
8
|
+
is an ordinary `Duplex`, `(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>`, the
|
|
9
|
+
same function you would run over a WebSocket or a `MessagePort`.
|
|
16
10
|
|
|
17
11
|
## Why it exists
|
|
18
12
|
|
|
19
|
-
PeerJS is the least-effort route to a browser-to-browser connection: it ships a
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
This adapter supplies those once, so the transport becomes an implementation
|
|
25
|
-
detail — prototype over PeerJS's public broker, then move the same handler to
|
|
26
|
-
[`webrun-streams-webrtc`](../webrun-streams-webrtc) or
|
|
27
|
-
[`webrun-streams-libp2p`](../webrun-streams-libp2p) for production without
|
|
28
|
-
touching it.
|
|
13
|
+
PeerJS is the least-effort route to a browser-to-browser connection: it ships a public broker, so
|
|
14
|
+
you get a working peer link without running signalling infrastructure. What it hands you is one
|
|
15
|
+
message pipe with no request framing, no concurrency, no half-close and no error propagation. This
|
|
16
|
+
adapter supplies those, so the transport becomes a detail: a handler prototyped over PeerJS runs
|
|
17
|
+
unchanged over any other `webrun-streams` adapter.
|
|
29
18
|
|
|
30
|
-
##
|
|
19
|
+
## How to use
|
|
31
20
|
|
|
32
21
|
```sh
|
|
33
|
-
|
|
22
|
+
pnpm add @statewalker/webrun-streams-peerjs peerjs
|
|
34
23
|
```
|
|
35
24
|
|
|
36
|
-
`peerjs` is a
|
|
37
|
-
its
|
|
25
|
+
`peerjs` is a required peer dependency (`^1.5.5`). You create and own the `Peer`, its broker
|
|
26
|
+
configuration and its connections. Browser only in practice: PeerJS needs WebRTC. One entry point,
|
|
27
|
+
`.`, ESM only.
|
|
28
|
+
|
|
29
|
+
**Connections must use `serialization: "raw"`.** Otherwise PeerJS encodes the bytes itself and the
|
|
30
|
+
mux framing does not survive. The adapter checks and throws
|
|
31
|
+
`TypeError: byteChannelFromPeerJs: DataConnection serialization is '<value>', expected 'raw'`.
|
|
32
|
+
|
|
33
|
+
| Export | Purpose |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `connect(params: ConnectPeerJsParams)` | `Connect`. Takes one open `DataConnection`. Resolves `{ call, close }`; each `call(input)` opens a new logical stream. `close()` ends the mux and closes the connection. |
|
|
36
|
+
| `serve(params: ServePeerJsParams, handler)` | `Serve`. Takes a `Peer`, serves `handler` on every inbound connection. Resolves an idempotent teardown. |
|
|
37
|
+
| `ConnectPeerJsParams` | `{ conn: DataConnection; mux?: EmulateMuxOptions }`. |
|
|
38
|
+
| `ServePeerJsParams` | `{ peer: Peer; mux?: EmulateMuxOptions }`. |
|
|
39
|
+
| `byteChannelFromPeerJs(conn)` | The `ByteChannel` both use, for driving `emulateMux` yourself. |
|
|
38
40
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
41
|
+
`mux` is forwarded to `emulateMux` (`mtu`, `maxStreamBuffer`, `maxStreams`, with `webrun-streams`'
|
|
42
|
+
defaults: 64 KiB, 8 MiB, 256). `side` is fixed by the function you call — `"initiator"` for
|
|
43
|
+
`connect`, `"responder"` for `serve` — and overrides `mux.side`.
|
|
42
44
|
|
|
43
|
-
|
|
45
|
+
`serve` takes the `Peer` because it accepts many inbound connections; `connect` takes one
|
|
46
|
+
connection you already opened.
|
|
44
47
|
|
|
45
|
-
|
|
48
|
+
## Examples
|
|
49
|
+
|
|
50
|
+
### Serving
|
|
46
51
|
|
|
47
52
|
```ts
|
|
48
|
-
import Peer from "peerjs";
|
|
53
|
+
import { Peer } from "peerjs";
|
|
49
54
|
import { serve } from "@statewalker/webrun-streams-peerjs";
|
|
50
55
|
|
|
51
56
|
const peer = new Peer("my-server-id");
|
|
52
|
-
await new Promise((
|
|
57
|
+
await new Promise((resolve) => peer.on("open", resolve));
|
|
53
58
|
|
|
54
59
|
const stop = await serve({ peer }, async function* echo(input) {
|
|
55
60
|
for await (const chunk of input) yield chunk;
|
|
56
61
|
});
|
|
62
|
+
|
|
63
|
+
// later: stop accepting, close every served connection's mux
|
|
64
|
+
await stop();
|
|
57
65
|
```
|
|
58
66
|
|
|
59
|
-
|
|
67
|
+
### Calling
|
|
60
68
|
|
|
61
69
|
```ts
|
|
62
|
-
import Peer from "peerjs";
|
|
70
|
+
import { Peer } from "peerjs";
|
|
63
71
|
import { connect } from "@statewalker/webrun-streams-peerjs";
|
|
64
72
|
|
|
65
73
|
const peer = new Peer();
|
|
74
|
+
await new Promise((resolve) => peer.on("open", resolve));
|
|
75
|
+
|
|
66
76
|
const conn = peer.connect("my-server-id", { serialization: "raw" });
|
|
67
|
-
await new Promise((
|
|
77
|
+
await new Promise((resolve) => conn.on("open", resolve));
|
|
68
78
|
|
|
69
79
|
const { call, close } = await connect({ conn });
|
|
70
80
|
|
|
@@ -75,10 +85,7 @@ for await (const chunk of call([new TextEncoder().encode("ping")])) {
|
|
|
75
85
|
await close();
|
|
76
86
|
```
|
|
77
87
|
|
|
78
|
-
|
|
79
|
-
connections), `connect` takes one already-open `DataConnection`.
|
|
80
|
-
|
|
81
|
-
### Carrying HTTP over it
|
|
88
|
+
### HTTP over the connection
|
|
82
89
|
|
|
83
90
|
```ts
|
|
84
91
|
import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
|
|
@@ -86,65 +93,72 @@ import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
|
|
|
86
93
|
const response = await fetchOverDuplex(call, new Request("http://peer/api/todo"));
|
|
87
94
|
```
|
|
88
95
|
|
|
89
|
-
|
|
96
|
+
### Driving the mux yourself
|
|
90
97
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
| Field | Type | Meaning |
|
|
96
|
-
| --- | --- | --- |
|
|
97
|
-
| `conn` | `DataConnection` | An already-open connection with `serialization: "raw"`. |
|
|
98
|
-
| `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"initiator"` regardless of `mux.side`. |
|
|
99
|
-
|
|
100
|
-
Each `call(input)` opens a new logical stream over that connection. `close()`
|
|
101
|
-
tears down the streams and the channel.
|
|
102
|
-
|
|
103
|
-
### `serve(params, handler): Promise<() => Promise<void>>`
|
|
104
|
-
|
|
105
|
-
Type: `Serve<ServePeerJsParams>`.
|
|
98
|
+
```ts
|
|
99
|
+
import { emulateMux } from "@statewalker/webrun-streams";
|
|
100
|
+
import { byteChannelFromPeerJs } from "@statewalker/webrun-streams-peerjs";
|
|
106
101
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
102
|
+
const channel = byteChannelFromPeerJs(conn); // conn opened with serialization: "raw"
|
|
103
|
+
const mux = emulateMux(channel, { side: "initiator" });
|
|
104
|
+
// mux.call(input), mux.serve(handler), mux.close()
|
|
105
|
+
```
|
|
111
106
|
|
|
112
|
-
|
|
107
|
+
## Internals
|
|
113
108
|
|
|
114
|
-
|
|
109
|
+
```
|
|
110
|
+
handler / caller (Duplex)
|
|
111
|
+
│
|
|
112
|
+
emulateMux (webrun-streams): framed streams, credit flow control
|
|
113
|
+
│
|
|
114
|
+
byteChannelFromPeerJs: one ByteChannel per DataConnection
|
|
115
|
+
│ out: conn.send(bytes) in: "data" events
|
|
116
|
+
▼
|
|
117
|
+
PeerJS DataConnection (serialization: "raw") ── WebRTC data channel
|
|
118
|
+
```
|
|
115
119
|
|
|
116
|
-
|
|
117
|
-
`close`) for driving `emulateMux` yourself.
|
|
120
|
+
### What the channel accepts, and what it drops
|
|
118
121
|
|
|
119
|
-
|
|
122
|
+
Inbound `data` may be a `Uint8Array`, an `ArrayBuffer`, any `ArrayBufferView` or a `Blob` (read
|
|
123
|
+
asynchronously); each is copied into a fresh `Uint8Array`. Anything else is ignored. Outbound
|
|
124
|
+
`send` is a silent no-op while `conn.open` is false, so **wait for the connection's `open` event
|
|
125
|
+
before `connect`**; bytes sent earlier are lost without an error.
|
|
120
126
|
|
|
121
|
-
|
|
127
|
+
### What closes the channel, and what you see
|
|
122
128
|
|
|
123
|
-
|
|
129
|
+
The channel closes on the connection's `close` event or when its `close()` is called. In-flight
|
|
130
|
+
and later calls then fail with `webrun-streams`' `TransportClosedError`. On the serving side each
|
|
131
|
+
inbound connection gets its own mux, created when the connection opens and closed when the
|
|
132
|
+
connection closes. A connection that arrives without `serialization: "raw"` makes the adapter
|
|
133
|
+
throw the `TypeError` above inside the connection's `open` handler, and that connection is not
|
|
134
|
+
served.
|
|
124
135
|
|
|
125
|
-
|
|
126
|
-
|
|
136
|
+
The serve teardown removes the `connection` listener and closes every mux it created. Muxes are
|
|
137
|
+
kept in a list until then, including those whose connection already closed.
|
|
127
138
|
|
|
128
|
-
|
|
129
|
-
Node, but the full PeerJS handshake hangs there, so
|
|
130
|
-
`tests/conformance.test.ts` registers the suite only when a `window` global is
|
|
131
|
-
present; the plain Node run reports it as skipped.
|
|
139
|
+
### Conformance runs in a browser against a local broker
|
|
132
140
|
|
|
133
141
|
```sh
|
|
134
142
|
pnpm --filter @statewalker/webrun-streams-peerjs test:browser # runs the suite
|
|
135
143
|
pnpm --filter @statewalker/webrun-streams-peerjs test # reports it skipped
|
|
136
144
|
```
|
|
137
145
|
|
|
138
|
-
|
|
146
|
+
The `@statewalker/webrun-streams-conformance` suite runs in headless Chromium through Playwright.
|
|
147
|
+
A Vitest global setup starts the reference broker (the [`peer`](https://www.npmjs.com/package/peer)
|
|
148
|
+
package's `PeerServer`) on a loopback port in a child process, so runs need no internet access.
|
|
149
|
+
The broker runs out of process because, hosted in-process, it keeps the test run alive after the
|
|
150
|
+
last test: its `close()` waits on the browser's WebSockets and it holds client-expiry timers with
|
|
151
|
+
no public way to clear them. Under plain `pnpm test` (Node) the suite is skipped: the full PeerJS
|
|
152
|
+
handshake hangs there.
|
|
139
153
|
|
|
140
|
-
|
|
141
|
-
| --- | --- | --- |
|
|
142
|
-
| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `ByteChannel` seam and `emulateMux`. |
|
|
143
|
-
| `peerjs` | **peer** (`^1.5.5`) | You supply and own the `Peer`. |
|
|
144
|
-
| `peer`, `@roamhq/wrtc` | dev | Local broker and WebRTC for the conformance run. |
|
|
154
|
+
### Dependencies
|
|
145
155
|
|
|
146
|
-
|
|
156
|
+
- `@statewalker/webrun-streams` (runtime): the `Duplex` / `Connect` / `Serve` / `ByteChannel`
|
|
157
|
+
types and `emulateMux`.
|
|
158
|
+
- `peerjs` (peer): you supply and own the `Peer`.
|
|
159
|
+
- Dev only: `peer` (the local broker), `@vitest/browser-playwright` and `playwright` (the browser
|
|
160
|
+
run), `@statewalker/webrun-streams-conformance` (the suite).
|
|
147
161
|
|
|
148
162
|
## License
|
|
149
163
|
|
|
150
|
-
MIT
|
|
164
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/webrun-streams-peerjs",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "PeerJS DataConnection-backed Connect/Serve adapter 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-peerjs#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
|
|
18
|
+
"url": "git+https://github.com/statewalker/webrun-wire.git",
|
|
19
|
+
"directory": "packages/webrun-streams-peerjs"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
22
|
".": {
|
|
@@ -26,7 +30,7 @@
|
|
|
26
30
|
"src"
|
|
27
31
|
],
|
|
28
32
|
"dependencies": {
|
|
29
|
-
"@statewalker/webrun-streams": "^0.2.
|
|
33
|
+
"@statewalker/webrun-streams": "^0.2.2"
|
|
30
34
|
},
|
|
31
35
|
"peerDependencies": {
|
|
32
36
|
"peerjs": "^1.5.5"
|
|
@@ -43,7 +47,7 @@
|
|
|
43
47
|
"rolldown": "^1.2.12",
|
|
44
48
|
"typescript": "^7.0.2",
|
|
45
49
|
"vitest": "^5.0.3",
|
|
46
|
-
"@statewalker/webrun-streams-conformance": "^0.3.
|
|
50
|
+
"@statewalker/webrun-streams-conformance": "^0.3.2"
|
|
47
51
|
},
|
|
48
52
|
"sideEffects": false,
|
|
49
53
|
"publishConfig": {
|