@statewalker/webrun-streams-livekit 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.
Files changed (2) hide show
  1. package/README.md +103 -79
  2. package/package.json +9 -5
package/README.md CHANGED
@@ -1,66 +1,75 @@
1
1
  # @statewalker/webrun-streams-livekit
2
2
 
3
- LiveKit-backed `Connect` / `Serve` adapter in the `webrun-streams-*` family.
3
+ ## What it is
4
4
 
5
- ## What this is
6
-
7
- A binding between a connected LiveKit [`Room`](https://docs.livekit.io/client-sdk-js/classes/Room.html)
8
- and the [`webrun-streams`](../webrun-streams) `Duplex` seam. A room plus a
9
- remote participant identity becomes one `ByteChannel`; `emulateMux` layers many
10
- concurrent logical calls on top.
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
- Peer-to-peer links are excellent until they aren't: symmetric NATs, corporate
19
- firewalls, mobile networks and multi-party sessions all argue for a managed
20
- SFU. LiveKit provides one, with authentication, room membership and presence
21
- already solved.
22
-
23
- What LiveKit's data channel does *not* provide is request semantics. This
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
- ## Install
21
+ ## How to use
32
22
 
33
23
  ```sh
34
- npm install @statewalker/webrun-streams-livekit livekit-client
24
+ pnpm add @statewalker/webrun-streams-livekit livekit-client
35
25
  ```
36
26
 
37
- `livekit-client` is a **peer dependency** (`^2.18.3`) — you own the `Room`, its
38
- token, and its lifecycle.
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
- ## Getting started
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
- Both sides take the same parameters: a connected `Room` and the identity of the
43
- participant at the other end.
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
- Responder:
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: "agent-7"
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
- Caller:
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
- ### Carrying HTTP over it
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
- [`apps/livekit-demo`](../../apps/livekit-demo) runs this end to end — a dev
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
- ## API
86
-
87
- ### `connect(params): Promise<{ call, close }>`
92
+ ```ts
93
+ import { emulateMux } from "@statewalker/webrun-streams";
94
+ import { byteChannelFromLiveKit } from "@statewalker/webrun-streams-livekit";
88
95
 
89
- Type: `Connect<LiveKitParams>`. Each `call(input)` opens a new logical stream
90
- addressed to `peerIdentity`; `close()` tears them down. It does not disconnect
91
- the `Room`, which you own.
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
- ### `serve(params, handler): Promise<() => Promise<void>>`
101
+ ## Internals
94
102
 
95
- Type: `Serve<LiveKitParams>`. Runs `handler` for inbound streams from
96
- `peerIdentity`. Returns an idempotent teardown.
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
- ### `LiveKitParams`
115
+ ### Why every publish is reliable and addressed
99
116
 
100
- | Field | Type | Meaning |
101
- | --- | --- | --- |
102
- | `room` | `Room` | An already-connected LiveKit room. |
103
- | `peerIdentity` | `string` | Identity of the remote participant this side talks to. |
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
- ### `byteChannelFromLiveKit(room, peerIdentity): ByteChannel`
122
+ ### Why the default `mtu` is 12 KiB
107
123
 
108
- Wraps a room + peer identity as a `ByteChannel` (`send` / `recv` / `closed` /
109
- `close`) for driving `emulateMux` yourself.
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
- ### Why the MTU default is lower here
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 LiveKit reliable data packet is capped at roughly 15 KiB, and a payload over
115
- that is dropped rather than fragmented. `emulateMux`'s own 64 KiB default
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
- An explicit `mux.mtu` still wins, so a deployment that permits larger packets
122
- can raise it.
141
+ ### Two things that are easy to get wrong
123
142
 
124
- ## Conformance
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 is **browser-gated** — it needs a real LiveKit server rather than a
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
- with the `WEBRUN_STREAMS_LIVEKIT_*` environment variables pointing at a running
134
- server. The package's dev dependencies include `testcontainers` and
135
- `livekit-server-sdk` for standing one up.
136
-
137
- ## Dependencies
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
- | Dependency | Kind | Why |
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
- ESM only (`"type": "module"`).
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 © statewalker — see [LICENSE](../../LICENSE).
173
+ MIT
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-livekit",
3
- "version": "0.2.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
- "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-livekit#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-livekit"
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.1"
33
+ "@statewalker/webrun-streams": "^0.2.2"
30
34
  },
31
35
  "peerDependencies": {
32
36
  "livekit-client": "^2.18.3"
@@ -43,7 +47,7 @@
43
47
  "testcontainers": "^12.2.0",
44
48
  "typescript": "^7.0.2",
45
49
  "vitest": "^5.0.3",
46
- "@statewalker/webrun-streams-conformance": "^0.3.1"
50
+ "@statewalker/webrun-streams-conformance": "^0.3.2"
47
51
  },
48
52
  "sideEffects": false,
49
53
  "publishConfig": {