@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/types/shared/Room.d.ts

@@ -0,0 +1,143 @@
+import { type SignalingPeer, type SignalingPeerEvent, type SignalingPeerLeftEvent, type SignalingSignalEvent, type SignalingStream } from '../protocol/SignalingProtocol.js';
+import type { PeerConnectionConfiguration, PeerConnectionLike, StreamOf, TrackOf } from './Connections.js';
+import { Emitter, type EmitterListener } from './Emitter.js';
+import { Peer, type PeerSignal } from './Peer.js';
+/**
+ * The events of a {@link Room}.
+ */
+export type RoomEvents<Connection extends PeerConnectionLike<any>> = {
+    /**
+     * A member to connect to: each member already in the room when it was joined, then each member joining it. A
+     * listener added later is called at once for the peers already there.
+     */
+    peer: [peer: Peer<Connection>];
+    /**
+     * A peer was closed: its member left, its connection was lost for good, or the local member or the member is
+     * connected to another media server (a new peer of the member follows).
+     */
+    'peer-left': [peer: Peer<Connection>];
+    /**
+     * The room was left.
+     */
+    close: [];
+    /**
+     * A peer could not be created, or a peer failed to negotiate.
+     */
+    error: [error: Error, peer?: Peer<Connection>];
+};
+/**
+ * What a room needs of its signaling session
+ */
+export interface RoomHost<Connection extends PeerConnectionLike<any>> {
+    readonly localId: string;
+    readonly signalingUp: boolean;
+    create(configuration?: PeerConnectionConfiguration): Connection | Promise<Connection>;
+    send(room: string, to: string, signal: PeerSignal): Promise<void>;
+    leave(room: Room<Connection>): Promise<void>;
+    rejoin(room: Room<Connection>): void;
+}
+/**
+ * A room joined through the signaling: its {@link Peer}s, one for each other member. Listen to `peer` to use each of
+ * them (create its data channels, listen to its channels and its tracks), to `peer-left` for the ones closed; publish
+ * the tracks sent to every member with `publish()`.
+ *
+ * The members are connected peer to peer, or, in a room with a media server (its `sfu`), each member to the server
+ * only: the server forwards the tracks published to the other members, and the room and its peers work as without it.
+ */
+export declare class Room<Connection extends PeerConnectionLike<any> = PeerConnectionLike> extends Emitter<RoomEvents<Connection>> {
+    #private;
+    /**
+     * The name of the room.
+     */
+    readonly name: string;
+    /**
+     * Create a room (by the signaling session joining it).
+     * @param host The session.
+     * @param name The room.
+     * @param metadata The metadata the local member joined with.
+     */
+    constructor(host: RoomHost<Connection>, name: string, metadata: unknown);
+    /**
+     * The peers whose connection is created.
+     */
+    get peers(): Peer<Connection>[];
+    /**
+     * The metadata the local member joined with.
+     */
+    get metadata(): unknown;
+    /**
+     * Whether the room was left.
+     */
+    get left(): boolean;
+    /**
+     * The id of the media server of the room, when it has one: the members are connected to it, not to each other.
+     */
+    get sfu(): string | undefined;
+    /**
+     * The peer of a member.
+     * @param id The member's id.
+     * @returns The peer, or undefined when the member is not in the room or its connection is not created yet.
+     */
+    peer(id: string): Peer<Connection> | undefined;
+    /**
+     * A stream received through the media server of the room: the member sending it, and its id on the connection of
+     * that member (`event.streams` of a track carries the ids of the connection to the server).
+     * @param id The id of the stream on the connection to the server.
+     * @returns The stream, or undefined when the room has no media server or the stream is not known.
+     */
+    streamOf(id: string): SignalingStream | undefined;
+    /**
+     * Send a track to every member of the room, those joining later too: on each connection, or once to the media
+     * server of the room. A track published after `unpublish()` takes the transceiver of a track unpublished.
+     * @param track The track: a `MediaStreamTrack` in the browsers, a `MediaTrack` in Node.js.
+     * @param streams Its streams (a `MediaStream` in the browsers, its id in Node.js): the members group the tracks of
+     * a stream (to play the audio and the video together).
+     * @returns Resolves once the track is added to the connections.
+     */
+    publish(track: TrackOf<Connection>, ...streams: StreamOf<Connection>[]): Promise<void>;
+    /**
+     * Stop sending a track published: its transceivers stay, inactive, for the next track published.
+     * @param track The track.
+     * @returns Resolves once the track is taken out of the connections.
+     */
+    unpublish(track: TrackOf<Connection>): Promise<void>;
+    /**
+     * Add a listener of an event; a listener of `peer` is called at once for the peers already there.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns This room.
+     */
+    on<Event extends keyof RoomEvents<Connection>>(event: Event, listener: EmitterListener<RoomEvents<Connection>[Event]>): this;
+    /**
+     * Leave the room: its peers are closed.
+     * @returns Resolves once the server is told.
+     */
+    leave(): Promise<void>;
+    /**
+     * The members in the room when it was joined, or joined again after a reconnection of the signaling: the peers of
+     * the members not there any more are dropped (unless their connection is up), the new members get a peer
+     * @param peers
+     * @param metadata
+     * @param sfu The media server of the room, when it has one.
+     * @internal
+     */
+    members(peers: SignalingPeer[], metadata: unknown, sfu?: string): void;
+    /**
+     * A member joined (or joined again)
+     * @param event
+     * @internal
+     */
+    joined(event: SignalingPeerEvent): void;
+    /**
+     * A member left
+     * @param event
+     * @internal
+     */
+    departed(event: SignalingPeerLeftEvent): void;
+    /**
+     * A signal from a member
+     * @param event
+     * @internal
+     */
+    signal(event: SignalingSignalEvent): void;
+}

package/dist/types/shared/SignalingError.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The error of a signaling request the server refused or did not answer: its `errno` is the one of the server's
+ * exception (`E_SIGNALING_DENIED`, `E_SIGNALING_NOT_A_MEMBER`, `E_SIGNALING_LIMIT`, `E_INVALID_VALUE`…), or
+ * `E_SIGNALING_TIMEOUT` and `E_SIGNALING_CLOSED` for the requests without an answer.
+ * @example
+ * ```typescript
+ * import {SignalingRequestError, type SignalingClient} from '@lakutata/webrtc'
+ *
+ * declare const signaling: SignalingClient
+ * try {
+ *     await signaling.join('private')
+ * } catch (error) {
+ *     if (error instanceof SignalingRequestError && error.errno === 'E_SIGNALING_DENIED') console.log('not allowed in the room')
+ * }
+ * ```
+ */
+export declare class SignalingRequestError extends Error {
+    /**
+     * The error number.
+     */
+    readonly errno: string | number;
+    /**
+     * The error the server sent, as it sent it.
+     */
+    readonly data?: unknown;
+    /**
+     * Create the error.
+     * @param message The message.
+     * @param errno The error number.
+     * @param data The error the server sent.
+     */
+    constructor(message: string, errno: string | number, data?: unknown);
+}
+/**
+ * The error of a response sent by the server: the properties of its exception (Socket.IO), or the data of a JSON-RPC
+ * error
+ * @param error
+ * @param fallbackMessage
+ */
+export declare function signalingErrorOf(error: unknown, fallbackMessage: string): SignalingRequestError;

package/dist/types/shared/SignalingSession.d.ts

@@ -0,0 +1,97 @@
+import { type SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { PeerConnectionFactory, PeerConnectionLike } from './Connections.js';
+import { Emitter } from './Emitter.js';
+import { Room } from './Room.js';
+import { type SignalingTransport } from './Transports.js';
+/**
+ * The events of a signaling session.
+ */
+export type SignalingSessionEvents = {
+    /**
+     * The signaling is connected again (after a disconnection): the rooms are joined again.
+     */
+    connected: [];
+    /**
+     * The signaling is disconnected; the peer-to-peer connections stay up.
+     */
+    disconnected: [];
+    /**
+     * A background task failed: joining a room again, renewing the TURN credentials.
+     */
+    error: [error: Error];
+};
+/**
+ * The options of a signaling session.
+ */
+export interface SignalingSessionOptions<Connection extends PeerConnectionLike<any>> {
+    /**
+     * Creates the peer connections.
+     */
+    createPeerConnection: PeerConnectionFactory<Connection>;
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * The session: a random string by default.
+     */
+    session?: string;
+}
+/**
+ * The options of joining a room.
+ */
+export interface JoinOptions {
+    /**
+     * What the other members get about the local member (a name, a role).
+     */
+    metadata?: unknown;
+}
+/**
+ * The signaling of a client: it joins rooms, relays the signals of their peers, keeps the membership alive (heartbeats
+ * for the transports needing them), renews the TURN credentials before they expire, and joins the rooms again after a
+ * reconnection of its transport (with the same session, so the other members keep their connections).
+ */
+export declare class SignalingSession<Connection extends PeerConnectionLike<any> = PeerConnectionLike> extends Emitter<SignalingSessionEvents> {
+    #private;
+    /**
+     * Create a session on a transport.
+     * @param transport The transport.
+     * @param options How to create the peer connections.
+     */
+    constructor(transport: SignalingTransport, options: SignalingSessionOptions<Connection>);
+    /**
+     * The local member's id (its client id), known once a room is joined.
+     */
+    get id(): string | undefined;
+    /**
+     * The session: the other members keep their connections when the client joins again with it.
+     */
+    get session(): string;
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected(): boolean;
+    /**
+     * The ICE servers given by the server, with the TURN credentials.
+     */
+    get iceServers(): SignalingIceServer[];
+    /**
+     * The rooms joined.
+     */
+    get rooms(): Room<Connection>[];
+    /**
+     * Join a room: a {@link Room}, whose `peer` event gives the other members. Joining a room already joined updates the
+     * metadata and gives the same room.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     */
+    join(room: string, options?: JoinOptions): Promise<Room<Connection>>;
+    /**
+     * Close the session: the rooms are left and their peers closed. A socket given by the application stays open (its
+     * listeners are removed); a WebSocket created by the function given is closed.
+     * @returns Resolves once the rooms are left.
+     */
+    close(): Promise<void>;
+}

package/dist/types/shared/Transports.d.ts

@@ -0,0 +1,139 @@
+/**
+ * How a signaling session talks to the server: requests, the events pushed by the server, and the state of the
+ * connection.
+ */
+export interface SignalingTransport {
+    /**
+     * Whether the connection is up.
+     */
+    readonly connected: boolean;
+    /**
+     * Send a request.
+     * @param method The method (`webrtc.join`…).
+     * @param params Its parameters.
+     * @returns The answer.
+     */
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    /**
+     * Listen to the events pushed by the server.
+     * @param listener Given the event and its payload.
+     * @returns A function removing the listener.
+     */
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    /**
+     * Listen to the connections and disconnections.
+     * @param listener Given whether the connection is up.
+     * @returns A function removing the listener.
+     */
+    watch(listener: (connected: boolean) => void): () => void;
+    /**
+     * Stop: the requests in progress fail, the connection is closed when the transport opened it.
+     */
+    close(): void;
+}
+/**
+ * What the signaling needs of a Socket.IO client socket (`io()` of socket.io-client): the socket is given by the
+ * application, its client id being its `auth.id`.
+ */
+export interface SocketIOSocketLike {
+    /**
+     * Whether it is connected.
+     */
+    readonly connected: boolean;
+    /**
+     * Send an event.
+     * @param event The event.
+     * @param args Its arguments, the last one an acknowledgement callback.
+     */
+    emit(event: string, ...args: any[]): unknown;
+    /**
+     * Add a listener.
+     * @param event The event.
+     * @param listener The listener.
+     */
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    /**
+     * Remove a listener.
+     * @param event The event.
+     * @param listener The listener.
+     */
+    off(event: string, listener?: (...args: any[]) => void): unknown;
+}
+/**
+ * What the signaling needs of a WebSocket (`WebSocket` of the browsers, of Node.js 22 and of Bun) speaking JSON-RPC to
+ * the server; its client id is the `id` query parameter of its URL.
+ */
+export interface WebSocketLike {
+    /**
+     * 0 connecting, 1 open, 2 closing, 3 closed.
+     */
+    readonly readyState: number;
+    /**
+     * Send a text message.
+     * @param data The message.
+     */
+    send(data: string): void;
+    /**
+     * Close it.
+     * @param code The close code.
+     * @param reason The reason.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Add a listener: `open`, `message`, `close`, `error`.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    addEventListener(type: string, listener: (event: any) => void): void;
+    /**
+     * Remove a listener.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    removeEventListener(type: string, listener: (event: any) => void): void;
+}
+/**
+ * The timers of Node.js are not to hold the process
+ * @param timer
+ */
+export declare function unrefTimer<Timer>(timer: Timer): Timer;
+/**
+ * The signaling over a Socket.IO socket: a request is the event `message`, `{method, ...params}`, answered by its
+ * acknowledgement `{success, error, payload}`; the events are Socket.IO events. A request sent when the socket
+ * disconnects fails at once (its answer cannot come any more); one made while it is disconnected is sent once it
+ * connects again.
+ */
+export declare class SocketIOTransport implements SignalingTransport {
+    #private;
+    /**
+     * Use a socket.
+     * @param socket The socket of the application.
+     * @param timeout How long a request waits for its answer, in milliseconds.
+     */
+    constructor(socket: SocketIOSocketLike, timeout?: number);
+    get connected(): boolean;
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    watch(listener: (connected: boolean) => void): () => void;
+    close(): void;
+}
+/**
+ * The signaling over JSON-RPC 2.0 on a WebSocket: the requests are JSON-RPC requests, the events are notifications whose
+ * `params` hold the payload. Given a function creating the WebSocket, it reconnects after a disconnection, waiting 1
+ * second, then twice as long each time, 30 seconds at most. A request sent on a socket that closes fails at once (its
+ * answer cannot come any more); one made while the socket is not open is sent once it opens.
+ */
+export declare class JSONRPCTransport implements SignalingTransport {
+    #private;
+    /**
+     * Use a WebSocket.
+     * @param socket The WebSocket, or a function creating one (to reconnect).
+     * @param timeout How long a request waits for its answer, in milliseconds.
+     */
+    constructor(socket: WebSocketLike | (() => WebSocketLike), timeout?: number);
+    get connected(): boolean;
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    watch(listener: (connected: boolean) => void): () => void;
+    close(): void;
+}

package/dist/types/signaling/MediaServers.d.ts

@@ -0,0 +1,40 @@
+import type { Signaling } from './Signaling.js';
+/**
+ * Gives a member joining a room the media server it connects to: the id of the member of the server, once the server is
+ * in the room; none for a room without one
+ * @param room The room.
+ * @param peerId The id of the member joining.
+ * @throws {SignalingLimitException} When the media server takes no more members.
+ */
+export type MediaServerAssignment = (room: string, peerId: string) => Promise<string | undefined>;
+/**
+ * The media server attached to each signaling
+ */
+export declare const mediaServers: WeakMap<Signaling, MediaServerAssignment>;
+/**
+ * The service a media server announces on the cluster (`Cluster.announce()`), with its load
+ */
+export declare const MEDIA_SERVER_SERVICE: string;
+/**
+ * The load of a media server, as it announces it
+ */
+export interface MediaServerLoad {
+    readonly members: number;
+    readonly viewers: number;
+    readonly maxMembers: number;
+}
+/**
+ * The topic of the requests to a media server of the cluster: give a member joining a room (through a node without a
+ * media server) a media server, as the media server would for a member joining through its own node
+ */
+export declare const MEDIA_SERVER_ASSIGN_TOPIC: string;
+/**
+ * The answer to a request of a media server for a member (MEDIA_SERVER_ASSIGN_TOPIC, and the requests between the media
+ * servers): the id of the member of the server (null for a room without one), or full when no media server takes the
+ * member
+ */
+export type MediaServerReply = {
+    sfu: string | null;
+} | {
+    full: true;
+};