@statewalker/webrun-streams-livekit 0.2.0 → 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/LICENSE +21 -0
- package/README.md +103 -79
- package/package.json +19 -13
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,66 +1,75 @@
|
|
|
1
1
|
# @statewalker/webrun-streams-livekit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Your handler is an ordinary `Duplex` —
|
|
13
|
-
`(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` — the same
|
|
14
|
-
function you would run over a WebSocket or WebRTC.
|
|
5
|
+
A `Connect` / `Serve` adapter that runs `@statewalker/webrun-streams` `Duplex` calls over a LiveKit
|
|
6
|
+
room. A connected `Room` plus the identity of one remote participant becomes one `ByteChannel`
|
|
7
|
+
(reliable data packets addressed to that participant), and `webrun-streams`' `emulateMux` runs
|
|
8
|
+
many concurrent calls over it. Your handler is an ordinary `Duplex`,
|
|
9
|
+
`(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>`, the same function you would
|
|
10
|
+
run over a WebSocket or a WebRTC data channel.
|
|
15
11
|
|
|
16
12
|
## Why it exists
|
|
17
13
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
adapter adds them, so an application written against the `Duplex` seam can move
|
|
25
|
-
from a direct WebRTC link to a LiveKit room by changing one import — the
|
|
26
|
-
handlers, the HTTP layer above them, and the tests all stay put.
|
|
27
|
-
|
|
28
|
-
Publishes are forced to LiveKit's **`RELIABLE`** mode (ordered, retransmitted),
|
|
29
|
-
because the framing above assumes byte-stream ordering.
|
|
14
|
+
Direct peer-to-peer links fail behind symmetric NATs, corporate firewalls and some mobile
|
|
15
|
+
networks, and multi-party sessions want a server anyway. LiveKit is a managed SFU that already
|
|
16
|
+
handles authentication, room membership and presence. What its data channel does not provide is
|
|
17
|
+
request semantics: there are no calls, no streams, no flow control, only packets. This adapter
|
|
18
|
+
adds them, so code written against the `Duplex` seam can move from a direct link to a LiveKit room
|
|
19
|
+
by changing the `connect` / `serve` import, with handlers and the layers above them unchanged.
|
|
30
20
|
|
|
31
|
-
##
|
|
21
|
+
## How to use
|
|
32
22
|
|
|
33
23
|
```sh
|
|
34
|
-
|
|
24
|
+
pnpm add @statewalker/webrun-streams-livekit livekit-client
|
|
35
25
|
```
|
|
36
26
|
|
|
37
|
-
`livekit-client` is a
|
|
38
|
-
|
|
27
|
+
`livekit-client` is a required peer dependency (`^2.18.3`). You create the `Room`, get its token,
|
|
28
|
+
connect it and disconnect it; this package never does. Browser only, because `livekit-client` is.
|
|
29
|
+
One entry point, `.`, ESM only.
|
|
39
30
|
|
|
40
|
-
|
|
31
|
+
| Export | Purpose |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `connect(params: LiveKitParams)` | `Connect<LiveKitParams>`. Resolves `{ call, close }`; each `call(input)` opens a new logical stream to `peerIdentity`. `close()` ends the mux, not the `Room`. |
|
|
34
|
+
| `serve(params: LiveKitParams, handler)` | `Serve<LiveKitParams>`. Runs `handler` for every stream `peerIdentity` opens. Resolves an idempotent teardown. |
|
|
35
|
+
| `LiveKitParams` | `{ room: Room; peerIdentity: string; mux?: EmulateMuxOptions }`. |
|
|
36
|
+
| `byteChannelFromLiveKit(room, peerIdentity)` | The `ByteChannel` both use, for driving `emulateMux` yourself. |
|
|
41
37
|
|
|
42
|
-
|
|
43
|
-
|
|
38
|
+
`mux` is forwarded to `emulateMux`: `mtu` (default here 12 KiB, see below), `maxStreamBuffer`
|
|
39
|
+
(per-stream inbound cap and advertised credit; `webrun-streams` default 8 MiB), `maxStreams`
|
|
40
|
+
(default 256). `side` is fixed by the function you call — `"initiator"` for `connect`,
|
|
41
|
+
`"responder"` for `serve` — and overrides `mux.side`.
|
|
44
42
|
|
|
45
|
-
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
Both sides take a connected `Room` and the identity of the participant at the other end.
|
|
46
|
+
|
|
47
|
+
### Serving
|
|
46
48
|
|
|
47
49
|
```ts
|
|
48
50
|
import { Room } from "livekit-client";
|
|
49
51
|
import { serve } from "@statewalker/webrun-streams-livekit";
|
|
50
52
|
|
|
51
53
|
const room = new Room();
|
|
52
|
-
await room.connect(url, token); // identity
|
|
54
|
+
await room.connect(url, token); // this participant's identity is "agent-7"
|
|
53
55
|
|
|
54
56
|
const stop = await serve({ room, peerIdentity: "client-3" }, async function* echo(input) {
|
|
55
57
|
for await (const chunk of input) yield chunk;
|
|
56
58
|
});
|
|
59
|
+
|
|
60
|
+
// later
|
|
61
|
+
await stop();
|
|
57
62
|
```
|
|
58
63
|
|
|
59
|
-
|
|
64
|
+
### Calling
|
|
60
65
|
|
|
61
66
|
```ts
|
|
67
|
+
import { Room } from "livekit-client";
|
|
62
68
|
import { connect } from "@statewalker/webrun-streams-livekit";
|
|
63
69
|
|
|
70
|
+
const room = new Room();
|
|
71
|
+
await room.connect(url, token); // this participant's identity is "client-3"
|
|
72
|
+
|
|
64
73
|
const { call, close } = await connect({ room, peerIdentity: "agent-7" });
|
|
65
74
|
|
|
66
75
|
for await (const chunk of call([new TextEncoder().encode("ping")])) {
|
|
@@ -70,7 +79,7 @@ for await (const chunk of call([new TextEncoder().encode("ping")])) {
|
|
|
70
79
|
await close();
|
|
71
80
|
```
|
|
72
81
|
|
|
73
|
-
###
|
|
82
|
+
### HTTP over the room
|
|
74
83
|
|
|
75
84
|
```ts
|
|
76
85
|
import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
|
|
@@ -78,72 +87,87 @@ import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
|
|
|
78
87
|
const response = await fetchOverDuplex(call, new Request("http://peer/api/events"));
|
|
79
88
|
```
|
|
80
89
|
|
|
81
|
-
|
|
82
|
-
LiveKit server, a token service, and two browser pages exchanging HTTP and SSE
|
|
83
|
-
through a room.
|
|
90
|
+
### Driving the mux yourself
|
|
84
91
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
92
|
+
```ts
|
|
93
|
+
import { emulateMux } from "@statewalker/webrun-streams";
|
|
94
|
+
import { byteChannelFromLiveKit } from "@statewalker/webrun-streams-livekit";
|
|
88
95
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
96
|
+
const channel = byteChannelFromLiveKit(room, "agent-7");
|
|
97
|
+
const mux = emulateMux(channel, { mtu: 12 * 1024, side: "initiator" });
|
|
98
|
+
// mux.call(input), mux.serve(handler), mux.close()
|
|
99
|
+
```
|
|
92
100
|
|
|
93
|
-
|
|
101
|
+
## Internals
|
|
94
102
|
|
|
95
|
-
|
|
96
|
-
|
|
103
|
+
```
|
|
104
|
+
handler / caller (Duplex)
|
|
105
|
+
│
|
|
106
|
+
emulateMux (webrun-streams): [varint streamId][1-byte type] frames, credit flow control
|
|
107
|
+
│
|
|
108
|
+
byteChannelFromLiveKit: one ByteChannel per (room, peerIdentity)
|
|
109
|
+
│ out: publishData(bytes, { reliable: true, destinationIdentities: [peerIdentity] })
|
|
110
|
+
│ in: "dataReceived" events, filtered by sender identity
|
|
111
|
+
▼
|
|
112
|
+
LiveKit SFU
|
|
113
|
+
```
|
|
97
114
|
|
|
98
|
-
###
|
|
115
|
+
### Why every publish is reliable and addressed
|
|
99
116
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
| `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is set by which function you call (`"initiator"` for `connect`, `"responder"` for `serve`) regardless of `mux.side`. **`mtu` defaults to 12 KiB here**, not `emulateMux`'s 64 KiB — see below. |
|
|
117
|
+
Every packet is published with `reliable: true` (ordered and retransmitted), because the mux
|
|
118
|
+
framing above assumes an ordered byte stream. Every packet carries `destinationIdentities:
|
|
119
|
+
[peerIdentity]`, so several pairs in one room do not fan out to every participant. Inbound packets
|
|
120
|
+
from any other identity are ignored, so one `Room` can carry several adapters, one per peer.
|
|
105
121
|
|
|
106
|
-
### `
|
|
122
|
+
### Why the default `mtu` is 12 KiB
|
|
107
123
|
|
|
108
|
-
|
|
109
|
-
|
|
124
|
+
A LiveKit reliable data packet is capped at about 15 KiB, and a larger payload is dropped rather
|
|
125
|
+
than fragmented. `emulateMux`'s own 64 KiB default therefore fails here, and silently: a 1 MiB body
|
|
126
|
+
arrives as zero bytes and a 10 MiB body never completes, with no error on either side. So
|
|
127
|
+
`connect` and `serve` default `mtu` to 12 KiB, which leaves room for the frame header inside the
|
|
128
|
+
packet. An explicit `mux.mtu` still wins, for a deployment that allows larger packets.
|
|
110
129
|
|
|
130
|
+
### What closes the channel, and what you see
|
|
111
131
|
|
|
112
|
-
|
|
132
|
+
The channel closes when the `Room` emits `disconnected`, when the `peerIdentity` participant
|
|
133
|
+
disconnects (`participantDisconnected`), or when its `close()` is called. In-flight and later calls
|
|
134
|
+
then fail with `webrun-streams`' `TransportClosedError` (`name` `"TransportClosedError"`). `serve`
|
|
135
|
+
also closes its mux when the channel closes. The channel does not reopen: if the peer leaves and
|
|
136
|
+
comes back, call `connect` / `serve` again.
|
|
113
137
|
|
|
114
|
-
A
|
|
115
|
-
|
|
116
|
-
therefore does not survive this transport, and it fails silently: a 1 MiB body
|
|
117
|
-
arrives as zero bytes and a 10 MiB body never completes, with no error on
|
|
118
|
-
either side. So `connect` and `serve` default `mtu` to 12 KiB — under the cap
|
|
119
|
-
with room for the frame header (`[varint streamId][1-byte type]`).
|
|
138
|
+
A failed `publishData` is swallowed; it surfaces through the disconnect events, not as an error on
|
|
139
|
+
the call.
|
|
120
140
|
|
|
121
|
-
|
|
122
|
-
can raise it.
|
|
141
|
+
### Two things that are easy to get wrong
|
|
123
142
|
|
|
124
|
-
|
|
143
|
+
- **Wait for the peer to be in the room before the first call.** The adapter addresses the remote
|
|
144
|
+
by identity, and LiveKit drops a data packet sent to a participant it has not announced yet
|
|
145
|
+
rather than queueing it. Wait for `RoomEvent.ParticipantConnected` (or check
|
|
146
|
+
`room.remoteParticipants`) first.
|
|
147
|
+
- **Each side names the other side's identity, exactly.** A wrong identity is not an error:
|
|
148
|
+
packets are filtered out and the call waits.
|
|
125
149
|
|
|
126
|
-
Conformance
|
|
127
|
-
Node shim:
|
|
150
|
+
### Conformance runs in a browser against a real server
|
|
128
151
|
|
|
129
152
|
```sh
|
|
130
153
|
pnpm --filter @statewalker/webrun-streams-livekit test:browser
|
|
131
154
|
```
|
|
132
155
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
`livekit-server-sdk`
|
|
136
|
-
|
|
137
|
-
|
|
156
|
+
This runs the `@statewalker/webrun-streams-conformance` suite in headless Chromium through
|
|
157
|
+
Playwright. A Vitest global setup starts `livekit-server --dev` on a loopback port and mints the
|
|
158
|
+
two access tokens with `livekit-server-sdk`, so the `livekit-server` binary must be on `PATH`.
|
|
159
|
+
Without it the setup fails with `livekit-server exited early (code …). Install it from
|
|
160
|
+
https://docs.livekit.io/home/self-hosting/local/`. Under plain `pnpm test` (Node) the suite is
|
|
161
|
+
skipped, because `livekit-client` needs a browser.
|
|
138
162
|
|
|
139
|
-
|
|
140
|
-
| --- | --- | --- |
|
|
141
|
-
| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `ByteChannel` seam and `emulateMux`. |
|
|
142
|
-
| `livekit-client` | **peer** (`^2.18.3`) | You supply and own the `Room`. |
|
|
143
|
-
| `livekit-server-sdk`, `testcontainers` | dev | Token minting and a containerised server for conformance. |
|
|
163
|
+
### Dependencies
|
|
144
164
|
|
|
145
|
-
|
|
165
|
+
- `@statewalker/webrun-streams` (runtime): the `Duplex` / `Connect` / `Serve` / `ByteChannel`
|
|
166
|
+
types and `emulateMux`.
|
|
167
|
+
- `livekit-client` (peer): you supply and own the `Room`.
|
|
168
|
+
- Dev only: `livekit-server-sdk` for test tokens, `@vitest/browser-playwright` and `playwright`
|
|
169
|
+
for the browser run, `@statewalker/webrun-streams-conformance` for the suite.
|
|
146
170
|
|
|
147
171
|
## License
|
|
148
172
|
|
|
149
|
-
MIT
|
|
173
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/webrun-streams-livekit",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "LiveKit-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-livekit#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-livekit"
|
|
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,23 +30,24 @@
|
|
|
25
30
|
"src"
|
|
26
31
|
],
|
|
27
32
|
"dependencies": {
|
|
28
|
-
"@statewalker/webrun-streams": "0.2.
|
|
33
|
+
"@statewalker/webrun-streams": "^0.2.2"
|
|
29
34
|
},
|
|
30
35
|
"peerDependencies": {
|
|
31
36
|
"livekit-client": "^2.18.3"
|
|
32
37
|
},
|
|
33
38
|
"devDependencies": {
|
|
34
|
-
"@
|
|
35
|
-
"@
|
|
36
|
-
"
|
|
37
|
-
"livekit-
|
|
38
|
-
"
|
|
39
|
+
"@biomejs/biome": "^2.5.15",
|
|
40
|
+
"@types/node": "^26.6.4",
|
|
41
|
+
"@vitest/browser-playwright": "^5.0.3",
|
|
42
|
+
"livekit-client": "^2.22.3",
|
|
43
|
+
"livekit-server-sdk": "^2.19.1",
|
|
44
|
+
"playwright": "^1.63.0",
|
|
39
45
|
"rimraf": "^6.1.3",
|
|
40
|
-
"rolldown": "^1.2.
|
|
41
|
-
"testcontainers": "^
|
|
46
|
+
"rolldown": "^1.2.12",
|
|
47
|
+
"testcontainers": "^12.2.0",
|
|
42
48
|
"typescript": "^7.0.2",
|
|
43
|
-
"vitest": "^
|
|
44
|
-
"@statewalker/webrun-streams-conformance": "0.2
|
|
49
|
+
"vitest": "^5.0.3",
|
|
50
|
+
"@statewalker/webrun-streams-conformance": "^0.3.2"
|
|
45
51
|
},
|
|
46
52
|
"sideEffects": false,
|
|
47
53
|
"publishConfig": {
|