@statewalker/webrun-streams-peerjs 0.1.1 → 0.2.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/README.md +140 -6
- package/dist/connect-serve.d.ts +17 -1
- package/dist/connect-serve.d.ts.map +1 -1
- package/dist/index.js +10 -4
- package/package.json +16 -8
- package/src/connect-serve.ts +27 -5
package/README.md
CHANGED
|
@@ -1,16 +1,150 @@
|
|
|
1
1
|
# @statewalker/webrun-streams-peerjs
|
|
2
2
|
|
|
3
|
-
PeerJS DataConnection
|
|
3
|
+
PeerJS `DataConnection`-backed `Connect` / `Serve` adapter in the
|
|
4
|
+
`webrun-streams-*` family.
|
|
5
|
+
|
|
6
|
+
## What this is
|
|
7
|
+
|
|
8
|
+
A binding between a PeerJS [`DataConnection`](https://peerjs.com/docs/#dataconnection)
|
|
9
|
+
and the [`webrun-streams`](../webrun-streams) `Duplex` seam. One
|
|
10
|
+
`DataConnection` becomes one `ByteChannel`; `emulateMux` layers many concurrent
|
|
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`.
|
|
16
|
+
|
|
17
|
+
## Why it exists
|
|
18
|
+
|
|
19
|
+
PeerJS is the least-effort route to a browser-to-browser connection: it ships a
|
|
20
|
+
public broker, so you get a working peer link without standing up signalling
|
|
21
|
+
infrastructure. What it hands you afterwards is a single message pipe with no
|
|
22
|
+
request framing, no concurrency, no half-close, and no error propagation.
|
|
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.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
npm install @statewalker/webrun-streams-peerjs peerjs
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`peerjs` is a **peer dependency** (`^1.5.5`) — you own the `Peer` instance and
|
|
37
|
+
its broker configuration.
|
|
38
|
+
|
|
39
|
+
> [!IMPORTANT]
|
|
40
|
+
> Connections must be opened with `serialization: "raw"`. PeerJS otherwise
|
|
41
|
+
> applies its own encoding to your bytes and the framing will not survive.
|
|
42
|
+
|
|
43
|
+
## Getting started
|
|
44
|
+
|
|
45
|
+
Responder — listen for inbound connections on a connected `Peer`:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import Peer from "peerjs";
|
|
49
|
+
import { serve } from "@statewalker/webrun-streams-peerjs";
|
|
50
|
+
|
|
51
|
+
const peer = new Peer("my-server-id");
|
|
52
|
+
await new Promise((r) => peer.on("open", r));
|
|
53
|
+
|
|
54
|
+
const stop = await serve({ peer }, async function* echo(input) {
|
|
55
|
+
for await (const chunk of input) yield chunk;
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Caller — connect, then hand the open `DataConnection` to the adapter:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import Peer from "peerjs";
|
|
63
|
+
import { connect } from "@statewalker/webrun-streams-peerjs";
|
|
64
|
+
|
|
65
|
+
const peer = new Peer();
|
|
66
|
+
const conn = peer.connect("my-server-id", { serialization: "raw" });
|
|
67
|
+
await new Promise((r) => conn.on("open", r));
|
|
68
|
+
|
|
69
|
+
const { call, close } = await connect({ conn });
|
|
70
|
+
|
|
71
|
+
for await (const chunk of call([new TextEncoder().encode("ping")])) {
|
|
72
|
+
console.log(new TextDecoder().decode(chunk)); // "ping"
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
await close();
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Note the asymmetry: `serve` takes the `Peer` (it accepts many inbound
|
|
79
|
+
connections), `connect` takes one already-open `DataConnection`.
|
|
80
|
+
|
|
81
|
+
### Carrying HTTP over it
|
|
4
82
|
|
|
5
83
|
```ts
|
|
6
|
-
import {
|
|
84
|
+
import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
|
|
85
|
+
|
|
86
|
+
const response = await fetchOverDuplex(call, new Request("http://peer/api/todo"));
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## API
|
|
90
|
+
|
|
91
|
+
### `connect(params): Promise<{ call, close }>`
|
|
92
|
+
|
|
93
|
+
Type: `Connect<ConnectPeerJsParams>`.
|
|
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>>`
|
|
7
104
|
|
|
8
|
-
|
|
9
|
-
|
|
105
|
+
Type: `Serve<ServePeerJsParams>`.
|
|
106
|
+
|
|
107
|
+
| Field | Type | Meaning |
|
|
108
|
+
| --- | --- | --- |
|
|
109
|
+
| `peer` | `Peer` | A connected peer; the adapter listens for inbound `DataConnection`s. |
|
|
110
|
+
| `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"responder"` regardless of `mux.side`. |
|
|
111
|
+
|
|
112
|
+
Returns an idempotent teardown.
|
|
113
|
+
|
|
114
|
+
### `byteChannelFromPeerJs(conn): ByteChannel`
|
|
115
|
+
|
|
116
|
+
Wraps one `DataConnection` as a `ByteChannel` (`send` / `recv` / `closed` /
|
|
117
|
+
`close`) for driving `emulateMux` yourself.
|
|
118
|
+
|
|
119
|
+
### `ConnectPeerJsParams` / `ServePeerJsParams`
|
|
120
|
+
|
|
121
|
+
The two parameter types above.
|
|
122
|
+
|
|
123
|
+
## Conformance
|
|
124
|
+
|
|
125
|
+
Runs [`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance)
|
|
126
|
+
against a local broker (the [`peer`](https://www.npmjs.com/package/peer) server).
|
|
127
|
+
|
|
128
|
+
The suite is **browser-gated**. `@roamhq/wrtc` covers the WebRTC primitives in
|
|
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.
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
pnpm --filter @statewalker/webrun-streams-peerjs test:browser # runs the suite
|
|
135
|
+
pnpm --filter @statewalker/webrun-streams-peerjs test # reports it skipped
|
|
10
136
|
```
|
|
11
137
|
|
|
12
|
-
|
|
138
|
+
## Dependencies
|
|
139
|
+
|
|
140
|
+
| Dependency | Kind | Why |
|
|
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. |
|
|
145
|
+
|
|
146
|
+
ESM only (`"type": "module"`).
|
|
13
147
|
|
|
14
148
|
## License
|
|
15
149
|
|
|
16
|
-
MIT
|
|
150
|
+
MIT © statewalker — see [LICENSE](../../LICENSE).
|
package/dist/connect-serve.d.ts
CHANGED
|
@@ -1,12 +1,28 @@
|
|
|
1
|
-
import { type Connect, type Serve } from "@statewalker/webrun-streams";
|
|
1
|
+
import { type Connect, type EmulateMuxOptions, type Serve } from "@statewalker/webrun-streams";
|
|
2
2
|
import type { DataConnection, Peer } from "peerjs";
|
|
3
3
|
export interface ConnectPeerJsParams {
|
|
4
4
|
/** Already-open `DataConnection` with `serialization: "raw"`. */
|
|
5
5
|
conn: DataConnection;
|
|
6
|
+
/**
|
|
7
|
+
* Flow-control tuning forwarded to `emulateMux` — `mtu` and
|
|
8
|
+
* `maxStreamBuffer`, which is the credit this side advertises. `side` here
|
|
9
|
+
* wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
|
|
10
|
+
* suite's L6 uses this to run at a window small enough that a sender
|
|
11
|
+
* genuinely stalls.
|
|
12
|
+
*/
|
|
13
|
+
mux?: EmulateMuxOptions;
|
|
6
14
|
}
|
|
7
15
|
export interface ServePeerJsParams {
|
|
8
16
|
/** Connected `Peer`. The adapter listens for inbound `DataConnection`s. */
|
|
9
17
|
peer: Peer;
|
|
18
|
+
/**
|
|
19
|
+
* Flow-control tuning forwarded to `emulateMux` — `mtu` and
|
|
20
|
+
* `maxStreamBuffer`, which is the credit this side advertises. `side` here
|
|
21
|
+
* wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
|
|
22
|
+
* suite's L6 uses this to run at a window small enough that a sender
|
|
23
|
+
* genuinely stalls.
|
|
24
|
+
*/
|
|
25
|
+
mux?: EmulateMuxOptions;
|
|
10
26
|
}
|
|
11
27
|
export declare const connect: Connect<ConnectPeerJsParams>;
|
|
12
28
|
export declare const serve: Serve<ServePeerJsParams>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,iBAAiB,EAEtB,KAAK,KAAK,EACX,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnD,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;IACX;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAShD,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAuB1C,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -91,9 +91,12 @@ function byteChannelFromPeerJs(conn) {
|
|
|
91
91
|
}
|
|
92
92
|
//#endregion
|
|
93
93
|
//#region src/connect-serve.ts
|
|
94
|
-
const connect = async ({ conn }) => {
|
|
94
|
+
const connect = async ({ conn, mux: muxOpts }) => {
|
|
95
95
|
const channel = byteChannelFromPeerJs(conn);
|
|
96
|
-
const mux = emulateMux(channel, {
|
|
96
|
+
const mux = emulateMux(channel, {
|
|
97
|
+
...muxOpts,
|
|
98
|
+
side: "initiator"
|
|
99
|
+
});
|
|
97
100
|
return {
|
|
98
101
|
call: mux.call,
|
|
99
102
|
async close() {
|
|
@@ -101,12 +104,15 @@ const connect = async ({ conn }) => {
|
|
|
101
104
|
}
|
|
102
105
|
};
|
|
103
106
|
};
|
|
104
|
-
const serve = async ({ peer }, handler) => {
|
|
107
|
+
const serve = async ({ peer, mux: muxOpts }, handler) => {
|
|
105
108
|
const muxes = [];
|
|
106
109
|
const onConnection = (conn) => {
|
|
107
110
|
const ready = () => {
|
|
108
111
|
const channel = byteChannelFromPeerJs(conn);
|
|
109
|
-
const mux = emulateMux(channel, {
|
|
112
|
+
const mux = emulateMux(channel, {
|
|
113
|
+
...muxOpts,
|
|
114
|
+
side: "responder"
|
|
115
|
+
});
|
|
110
116
|
mux.serve(handler);
|
|
111
117
|
muxes.push(mux);
|
|
112
118
|
channel.closed.then(() => mux.close());
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/webrun-streams-peerjs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "PeerJS DataConnection-backed Connect/Serve adapter in the webrun-streams-* family",
|
|
@@ -15,33 +15,41 @@
|
|
|
15
15
|
"url": "git@github.com:statewalker/webrun-wire.git"
|
|
16
16
|
},
|
|
17
17
|
"exports": {
|
|
18
|
-
".":
|
|
18
|
+
".": {
|
|
19
|
+
"source": "./src/index.ts",
|
|
20
|
+
"types": "./dist/index.d.ts",
|
|
21
|
+
"import": "./dist/index.js"
|
|
22
|
+
}
|
|
19
23
|
},
|
|
20
24
|
"files": [
|
|
21
25
|
"dist",
|
|
22
26
|
"src"
|
|
23
27
|
],
|
|
24
28
|
"dependencies": {
|
|
25
|
-
"@statewalker/webrun-streams": "0.
|
|
29
|
+
"@statewalker/webrun-streams": "^0.2.1"
|
|
26
30
|
},
|
|
27
31
|
"peerDependencies": {
|
|
28
32
|
"peerjs": "^1.5.5"
|
|
29
33
|
},
|
|
30
34
|
"devDependencies": {
|
|
31
|
-
"@
|
|
32
|
-
"@
|
|
35
|
+
"@biomejs/biome": "^2.5.15",
|
|
36
|
+
"@roamhq/wrtc": "^0.10.0",
|
|
37
|
+
"@types/node": "^26.6.4",
|
|
38
|
+
"@vitest/browser-playwright": "^5.0.3",
|
|
33
39
|
"peer": "^1.0.2",
|
|
34
40
|
"peerjs": "^1.5.5",
|
|
41
|
+
"playwright": "^1.63.0",
|
|
35
42
|
"rimraf": "^6.1.3",
|
|
36
|
-
"rolldown": "^1.2.
|
|
43
|
+
"rolldown": "^1.2.12",
|
|
37
44
|
"typescript": "^7.0.2",
|
|
38
|
-
"vitest": "^
|
|
39
|
-
"@statewalker/webrun-streams-conformance": "0.
|
|
45
|
+
"vitest": "^5.0.3",
|
|
46
|
+
"@statewalker/webrun-streams-conformance": "^0.3.1"
|
|
40
47
|
},
|
|
41
48
|
"sideEffects": false,
|
|
42
49
|
"publishConfig": {
|
|
43
50
|
"access": "public"
|
|
44
51
|
},
|
|
52
|
+
"types": "./dist/index.d.ts",
|
|
45
53
|
"scripts": {
|
|
46
54
|
"build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
|
|
47
55
|
"test": "vitest run",
|
package/src/connect-serve.ts
CHANGED
|
@@ -1,20 +1,42 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
type Connect,
|
|
3
|
+
type Duplex,
|
|
4
|
+
type EmulateMuxOptions,
|
|
5
|
+
emulateMux,
|
|
6
|
+
type Serve,
|
|
7
|
+
} from "@statewalker/webrun-streams";
|
|
2
8
|
import type { DataConnection, Peer } from "peerjs";
|
|
3
9
|
import { byteChannelFromPeerJs } from "./byte-channel.js";
|
|
4
10
|
|
|
5
11
|
export interface ConnectPeerJsParams {
|
|
6
12
|
/** Already-open `DataConnection` with `serialization: "raw"`. */
|
|
7
13
|
conn: DataConnection;
|
|
14
|
+
/**
|
|
15
|
+
* Flow-control tuning forwarded to `emulateMux` — `mtu` and
|
|
16
|
+
* `maxStreamBuffer`, which is the credit this side advertises. `side` here
|
|
17
|
+
* wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
|
|
18
|
+
* suite's L6 uses this to run at a window small enough that a sender
|
|
19
|
+
* genuinely stalls.
|
|
20
|
+
*/
|
|
21
|
+
mux?: EmulateMuxOptions;
|
|
8
22
|
}
|
|
9
23
|
|
|
10
24
|
export interface ServePeerJsParams {
|
|
11
25
|
/** Connected `Peer`. The adapter listens for inbound `DataConnection`s. */
|
|
12
26
|
peer: Peer;
|
|
27
|
+
/**
|
|
28
|
+
* Flow-control tuning forwarded to `emulateMux` — `mtu` and
|
|
29
|
+
* `maxStreamBuffer`, which is the credit this side advertises. `side` here
|
|
30
|
+
* wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
|
|
31
|
+
* suite's L6 uses this to run at a window small enough that a sender
|
|
32
|
+
* genuinely stalls.
|
|
33
|
+
*/
|
|
34
|
+
mux?: EmulateMuxOptions;
|
|
13
35
|
}
|
|
14
36
|
|
|
15
|
-
export const connect: Connect<ConnectPeerJsParams> = async ({ conn }) => {
|
|
37
|
+
export const connect: Connect<ConnectPeerJsParams> = async ({ conn, mux: muxOpts }) => {
|
|
16
38
|
const channel = byteChannelFromPeerJs(conn);
|
|
17
|
-
const mux = emulateMux(channel, { side: "initiator" });
|
|
39
|
+
const mux = emulateMux(channel, { ...muxOpts, side: "initiator" });
|
|
18
40
|
return {
|
|
19
41
|
call: mux.call,
|
|
20
42
|
async close() {
|
|
@@ -23,13 +45,13 @@ export const connect: Connect<ConnectPeerJsParams> = async ({ conn }) => {
|
|
|
23
45
|
};
|
|
24
46
|
};
|
|
25
47
|
|
|
26
|
-
export const serve: Serve<ServePeerJsParams> = async ({ peer }, handler: Duplex) => {
|
|
48
|
+
export const serve: Serve<ServePeerJsParams> = async ({ peer, mux: muxOpts }, handler: Duplex) => {
|
|
27
49
|
const muxes: Array<{ close: () => Promise<void> }> = [];
|
|
28
50
|
|
|
29
51
|
const onConnection = (conn: DataConnection): void => {
|
|
30
52
|
const ready = (): void => {
|
|
31
53
|
const channel = byteChannelFromPeerJs(conn);
|
|
32
|
-
const mux = emulateMux(channel, { side: "responder" });
|
|
54
|
+
const mux = emulateMux(channel, { ...muxOpts, side: "responder" });
|
|
33
55
|
mux.serve(handler);
|
|
34
56
|
muxes.push(mux);
|
|
35
57
|
void channel.closed.then(() => mux.close());
|