@statewalker/webrun-streams-signaling 0.1.1
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 +113 -0
- package/dist/byte-channel.d.ts +23 -0
- package/dist/byte-channel.d.ts.map +1 -0
- package/dist/byte-queue.d.ts +15 -0
- package/dist/byte-queue.d.ts.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +708 -0
- package/dist/peer-connection.d.ts +72 -0
- package/dist/peer-connection.d.ts.map +1 -0
- package/dist/peer-manager.d.ts +30 -0
- package/dist/peer-manager.d.ts.map +1 -0
- package/dist/qr-signaling.d.ts +60 -0
- package/dist/qr-signaling.d.ts.map +1 -0
- package/dist/room-manager.d.ts +32 -0
- package/dist/room-manager.d.ts.map +1 -0
- package/dist/types.d.ts +159 -0
- package/dist/types.d.ts.map +1 -0
- package/package.json +53 -0
- package/src/byte-channel.ts +99 -0
- package/src/byte-queue.ts +68 -0
- package/src/index.ts +30 -0
- package/src/peer-connection.ts +355 -0
- package/src/peer-manager.ts +74 -0
- package/src/qr-signaling.ts +227 -0
- package/src/room-manager.ts +114 -0
- package/src/types.ts +177 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Room membership manager over a LiveKit-style `Room`.
|
|
3
|
+
*
|
|
4
|
+
* Relocated from `@statewalker/vcs-port-livekit`'s `RoomManager` and adapted to
|
|
5
|
+
* the target API: `join`/`participants`/`channelTo`/`leave`. Participant
|
|
6
|
+
* tracking is the original event-wiring; `channelTo` yields a per-participant
|
|
7
|
+
* webrun-streams {@link ByteChannel} (see {@link byteChannelFromRoom}).
|
|
8
|
+
*
|
|
9
|
+
* The vendor (`livekit-client`) stays an optional peerDependency: the `Room` is
|
|
10
|
+
* injected via {@link RoomManagerOptions.roomFactory} (production:
|
|
11
|
+
* `() => new Room()`), so this module never hard-imports it.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import type { ByteChannel } from "@statewalker/webrun-streams";
|
|
15
|
+
import { byteChannelFromRoom } from "./byte-channel.js";
|
|
16
|
+
import type { RoomLike, RoomManagerOptions, RoomParticipantLike } from "./types.js";
|
|
17
|
+
import { ROOM_EVENT } from "./types.js";
|
|
18
|
+
|
|
19
|
+
export class RoomManager {
|
|
20
|
+
private readonly options: RoomManagerOptions;
|
|
21
|
+
private room: RoomLike | null = null;
|
|
22
|
+
|
|
23
|
+
private readonly seen: string[] = [];
|
|
24
|
+
private live: ((identity: string) => void) | null = null;
|
|
25
|
+
private endParticipants: (() => void) | null = null;
|
|
26
|
+
private readonly cleanups: Array<() => void> = [];
|
|
27
|
+
|
|
28
|
+
constructor(options: RoomManagerOptions) {
|
|
29
|
+
this.options = options;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Join a room by name (token is resolved via `options.getToken`). */
|
|
33
|
+
async join(room: string): Promise<void> {
|
|
34
|
+
const token = await this.options.getToken(room);
|
|
35
|
+
const instance = this.options.roomFactory();
|
|
36
|
+
this.room = instance;
|
|
37
|
+
|
|
38
|
+
const onJoin = (...args: unknown[]): void => {
|
|
39
|
+
const participant = args[0] as RoomParticipantLike;
|
|
40
|
+
this.seen.push(participant.identity);
|
|
41
|
+
this.live?.(participant.identity);
|
|
42
|
+
};
|
|
43
|
+
instance.on(ROOM_EVENT.participantConnected, onJoin);
|
|
44
|
+
this.cleanups.push(() => instance.off(ROOM_EVENT.participantConnected, onJoin));
|
|
45
|
+
|
|
46
|
+
await instance.connect(this.options.url, token);
|
|
47
|
+
|
|
48
|
+
for (const [, participant] of instance.remoteParticipants) {
|
|
49
|
+
this.seen.push(participant.identity);
|
|
50
|
+
this.live?.(participant.identity);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Observe participant identities: those already present, then joiners. */
|
|
55
|
+
participants(): AsyncIterable<string> {
|
|
56
|
+
return {
|
|
57
|
+
[Symbol.asyncIterator]: () => {
|
|
58
|
+
const buffer: string[] = [...this.seen];
|
|
59
|
+
let cursor = 0;
|
|
60
|
+
let pending: ((r: IteratorResult<string>) => void) | null = null;
|
|
61
|
+
let ended = false;
|
|
62
|
+
|
|
63
|
+
this.live = (identity: string) => {
|
|
64
|
+
if (pending) {
|
|
65
|
+
const resolve = pending;
|
|
66
|
+
pending = null;
|
|
67
|
+
resolve({ value: identity, done: false });
|
|
68
|
+
} else {
|
|
69
|
+
buffer.push(identity);
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
this.endParticipants = () => {
|
|
73
|
+
ended = true;
|
|
74
|
+
if (pending) {
|
|
75
|
+
const resolve = pending;
|
|
76
|
+
pending = null;
|
|
77
|
+
resolve({ value: undefined, done: true } as IteratorResult<string>);
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
return {
|
|
82
|
+
next: (): Promise<IteratorResult<string>> => {
|
|
83
|
+
if (cursor < buffer.length) {
|
|
84
|
+
return Promise.resolve({ value: buffer[cursor++], done: false });
|
|
85
|
+
}
|
|
86
|
+
if (ended) {
|
|
87
|
+
return Promise.resolve({ value: undefined, done: true } as IteratorResult<string>);
|
|
88
|
+
}
|
|
89
|
+
return new Promise<IteratorResult<string>>((resolve) => {
|
|
90
|
+
pending = resolve;
|
|
91
|
+
});
|
|
92
|
+
},
|
|
93
|
+
};
|
|
94
|
+
},
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** Open a {@link ByteChannel} to a specific participant. */
|
|
99
|
+
async channelTo(peerId: string): Promise<ByteChannel> {
|
|
100
|
+
if (!this.room) throw new Error("channelTo() before join()");
|
|
101
|
+
return byteChannelFromRoom(this.room, peerId);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Leave the room: unsubscribe and disconnect. */
|
|
105
|
+
async leave(): Promise<void> {
|
|
106
|
+
for (const cleanup of this.cleanups) cleanup();
|
|
107
|
+
this.cleanups.length = 0;
|
|
108
|
+
this.endParticipants?.();
|
|
109
|
+
this.live = null;
|
|
110
|
+
const room = this.room;
|
|
111
|
+
this.room = null;
|
|
112
|
+
if (room) await room.disconnect();
|
|
113
|
+
}
|
|
114
|
+
}
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Signaling / connection-setup types.
|
|
3
|
+
*
|
|
4
|
+
* Relocated from the retiring `@statewalker/vcs-port-{webrtc,livekit}` packages
|
|
5
|
+
* and neutralised: nothing here is VCS/Git-specific. These describe the generic
|
|
6
|
+
* P2P handshake (WebRTC offer/answer/ICE, QR payloads, LiveKit room membership)
|
|
7
|
+
* used to *establish* a channel. The byte transport itself is
|
|
8
|
+
* `@statewalker/webrun-streams` (a `ByteChannel`), not this package.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/** WebRTC peer role in the connection. */
|
|
12
|
+
export type PeerRole = "initiator" | "responder";
|
|
13
|
+
|
|
14
|
+
/** Connection state for a WebRTC peer. */
|
|
15
|
+
export type ConnectionState =
|
|
16
|
+
| "new"
|
|
17
|
+
| "connecting"
|
|
18
|
+
| "connected"
|
|
19
|
+
| "disconnected"
|
|
20
|
+
| "failed"
|
|
21
|
+
| "closed";
|
|
22
|
+
|
|
23
|
+
/** ICE candidate for connection establishment. */
|
|
24
|
+
export interface IceCandidate {
|
|
25
|
+
candidate: string;
|
|
26
|
+
sdpMid: string | null;
|
|
27
|
+
sdpMLineIndex: number | null;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Session description for WebRTC signaling. */
|
|
31
|
+
export interface SessionDescription {
|
|
32
|
+
type: "offer" | "answer";
|
|
33
|
+
sdp: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Signaling message exchanged between peers. */
|
|
37
|
+
export type SignalingMessage =
|
|
38
|
+
| { type: "offer"; sdp: string }
|
|
39
|
+
| { type: "answer"; sdp: string }
|
|
40
|
+
| { type: "candidate"; candidate: IceCandidate }
|
|
41
|
+
| { type: "ready" };
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Compressed signaling data for QR code exchange.
|
|
45
|
+
*
|
|
46
|
+
* Contains everything needed to establish a connection in a single compact
|
|
47
|
+
* payload suitable for QR codes.
|
|
48
|
+
*/
|
|
49
|
+
export interface CompressedSignal {
|
|
50
|
+
/** Protocol version */
|
|
51
|
+
v: number;
|
|
52
|
+
/** Session ID for matching peers */
|
|
53
|
+
id: string;
|
|
54
|
+
/** Peer role */
|
|
55
|
+
role: PeerRole;
|
|
56
|
+
/** SDP offer or answer (compressed) */
|
|
57
|
+
sdp: string;
|
|
58
|
+
/** ICE candidates (compressed) */
|
|
59
|
+
ice: string[];
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Factory for the underlying WebRTC peer connection. Defaults to
|
|
64
|
+
* `new RTCPeerConnection(config)`; tests inject a mock so no real vendor
|
|
65
|
+
* network is required.
|
|
66
|
+
*/
|
|
67
|
+
export type RtcPeerConnectionFactory = (config: RTCConfiguration) => RTCPeerConnection;
|
|
68
|
+
|
|
69
|
+
/** Options for creating a WebRTC peer connection. */
|
|
70
|
+
export interface WebRtcConnectionOptions {
|
|
71
|
+
/** ICE servers for connection establishment */
|
|
72
|
+
iceServers?: RTCIceServer[];
|
|
73
|
+
/** Timeout for connection establishment (ms) */
|
|
74
|
+
connectionTimeout?: number;
|
|
75
|
+
/** Timeout for ICE gathering (ms) */
|
|
76
|
+
iceGatheringTimeout?: number;
|
|
77
|
+
/** Data channel label */
|
|
78
|
+
channelLabel?: string;
|
|
79
|
+
/** Whether to use ordered delivery */
|
|
80
|
+
ordered?: boolean;
|
|
81
|
+
/** Maximum retransmits for unreliable mode */
|
|
82
|
+
maxRetransmits?: number;
|
|
83
|
+
/** Underlying peer-connection factory (injected in tests). */
|
|
84
|
+
rtc?: RtcPeerConnectionFactory;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Events emitted by a low-level {@link PeerConnection}. */
|
|
88
|
+
export interface PeerConnectionEvents {
|
|
89
|
+
/** Emitted when connection state changes */
|
|
90
|
+
stateChange: (state: ConnectionState) => void;
|
|
91
|
+
/** Emitted when a signaling message is ready to send */
|
|
92
|
+
signal: (message: SignalingMessage) => void;
|
|
93
|
+
/** Emitted when the data channel opens */
|
|
94
|
+
open: () => void;
|
|
95
|
+
/** Emitted when the connection closes */
|
|
96
|
+
close: () => void;
|
|
97
|
+
/** Emitted on error */
|
|
98
|
+
error: (error: Error) => void;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* A signaling transport routes {@link SignalingMessage}s to and from peers by
|
|
103
|
+
* id. It is the rendezvous side-channel over which the WebRTC handshake flows;
|
|
104
|
+
* the concrete implementation (websocket, room, in-memory bus) is out of scope
|
|
105
|
+
* for this package. Tests provide an in-memory pair.
|
|
106
|
+
*/
|
|
107
|
+
export interface SignalingTransport {
|
|
108
|
+
/** This endpoint's own peer id. */
|
|
109
|
+
readonly localId: string;
|
|
110
|
+
/** Send a signaling message to a specific peer. */
|
|
111
|
+
send(to: string, msg: SignalingMessage): void;
|
|
112
|
+
/** Subscribe to inbound signaling messages; returns an unsubscribe fn. */
|
|
113
|
+
onMessage(handler: (from: string, msg: SignalingMessage) => void): () => void;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Default ICE servers (public STUN servers). */
|
|
117
|
+
export const DEFAULT_ICE_SERVERS: RTCIceServer[] = [
|
|
118
|
+
{ urls: "stun:stun.l.google.com:19302" },
|
|
119
|
+
{ urls: "stun:stun1.l.google.com:19302" },
|
|
120
|
+
];
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Information about a participant in a room.
|
|
124
|
+
* Relocated from `@statewalker/vcs-port-livekit`.
|
|
125
|
+
*/
|
|
126
|
+
export interface ParticipantInfo {
|
|
127
|
+
/** Unique identity string */
|
|
128
|
+
identity: string;
|
|
129
|
+
/** Display name (may be empty) */
|
|
130
|
+
name: string;
|
|
131
|
+
/** Whether the participant is currently connected */
|
|
132
|
+
connected: boolean;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Narrow structural view of a LiveKit `Room`. Kept structural (rather than a
|
|
137
|
+
* hard `import` of `livekit-client`) so the vendor stays an *optional*
|
|
138
|
+
* peerDependency and tests can supply a mock without installing it. A real
|
|
139
|
+
* `livekit-client` `Room` satisfies this shape.
|
|
140
|
+
*/
|
|
141
|
+
export interface RoomParticipantLike {
|
|
142
|
+
identity: string;
|
|
143
|
+
name?: string;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export interface RoomLocalParticipantLike {
|
|
147
|
+
publishData(
|
|
148
|
+
data: Uint8Array,
|
|
149
|
+
opts?: { reliable?: boolean; destinationIdentities?: string[] },
|
|
150
|
+
): Promise<void>;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
export interface RoomLike {
|
|
154
|
+
connect(url: string, token: string): Promise<void>;
|
|
155
|
+
disconnect(): Promise<void>;
|
|
156
|
+
readonly remoteParticipants: Map<string, RoomParticipantLike>;
|
|
157
|
+
readonly localParticipant: RoomLocalParticipantLike;
|
|
158
|
+
on(event: string, cb: (...args: unknown[]) => void): unknown;
|
|
159
|
+
off(event: string, cb: (...args: unknown[]) => void): unknown;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Options for a {@link RoomManager}. */
|
|
163
|
+
export interface RoomManagerOptions {
|
|
164
|
+
/** Room server URL (e.g. "ws://localhost:7880"). */
|
|
165
|
+
url: string;
|
|
166
|
+
/** Resolve an access token for a given room name (out of scope: token issuer). */
|
|
167
|
+
getToken: (room: string) => Promise<string>;
|
|
168
|
+
/** Room factory. Production: `() => new Room()` from `livekit-client`. */
|
|
169
|
+
roomFactory: () => RoomLike;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** LiveKit `RoomEvent` string values used here (avoids a runtime vendor import). */
|
|
173
|
+
export const ROOM_EVENT = {
|
|
174
|
+
participantConnected: "participantConnected",
|
|
175
|
+
participantDisconnected: "participantDisconnected",
|
|
176
|
+
dataReceived: "dataReceived",
|
|
177
|
+
} as const;
|