@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/types/peer/SignalingClient.d.ts

@@ -0,0 +1,236 @@
+import { Provider } from '@lakutata/core';
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { EmitterListener } from '../shared/Emitter.js';
+import type { Peer as SharedPeer } from '../shared/Peer.js';
+import type { Room as SharedRoom } from '../shared/Room.js';
+import { type JoinOptions, type SignalingSessionEvents } from '../shared/SignalingSession.js';
+import { type SignalingTransport } from '../shared/Transports.js';
+import { PeerConnection } from './PeerConnection.js';
+/**
+ * A room joined by a {@link SignalingClient}: its peers are {@link PeerConnection}s.
+ */
+export type Room = SharedRoom<PeerConnection>;
+/**
+ * Another member of a room joined by a {@link SignalingClient}, and the {@link PeerConnection} to it.
+ */
+export type Peer = SharedPeer<PeerConnection>;
+/**
+ * The options of a {@link SignalingClient}.
+ */
+export interface SignalingClientOptions {
+    /**
+     * The URL of the signaling: `http:` or `https:` for Socket.IO (with the package `socket.io-client`), `ws:` or `wss:`
+     * for JSON-RPC over WebSocket.
+     */
+    url: string;
+    /**
+     * The client id, the member's id in the rooms.
+     * @default a random UUID
+     */
+    id?: string;
+    /**
+     * The path of Socket.IO.
+     * @default '/socket.io'
+     */
+    path?: string;
+    /**
+     * More fields of the Socket.IO handshake's `auth` (a token), besides `id`.
+     * @default none
+     */
+    auth?: Record<string, unknown>;
+    /**
+     * How long a request waits for its answer, in milliseconds.
+     * @default 15000
+     */
+    timeout?: number;
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates, as `[first, last]`.
+     * @default any free port
+     */
+    icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates (the public address of a NAT forwarding `icePortRange` with the same
+     * port numbers).
+     * @default none
+     */
+    iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs of the connections, as MIME types in the order of preference (see `PeerConnection`).
+     * @default ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9']
+     */
+    codecs?: string[];
+    /**
+     * The name of a `PeerThreads` component: the connections to the other members run their engine in its worker
+     * threads (see the `threads` option of `PeerConnection`).
+     * @default none: the engines run in the main thread
+     */
+    threads?: string;
+}
+/**
+ * A lakutata application as a member of the rooms of a signaling server of this package (`Signaling` and
+ * `SignalingController`, on this application or another one): it joins rooms and connects to their other members,
+ * browsers or applications, with {@link PeerConnection}s. Over Socket.IO (an `http:` or `https:` URL, with the package
+ * `socket.io-client`) or JSON-RPC over WebSocket (a `ws:` or `wss:` URL, with the `WebSocket` of Node.js 22 and of Bun);
+ * it reconnects by itself and joins its rooms again, keeping the peer-to-peer connections.
+ *
+ * Get a new one with `getObject(SignalingClient, options)` (it is `@Transient`, and needs no registration); `close()`
+ * leaves the rooms and closes the connections.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {type Peer, type PeerChannel, type Room, SignalingClient} from '@lakutata/webrtc'
+ *
+ * //A service of a device: sends its telemetry to whoever joins its room
+ * class TelemetryService extends Component {
+ *     protected async init(): Promise<void> {
+ *         const signaling: SignalingClient = await this.getObject(SignalingClient, {url: 'https://example.com', id: 'device-7'})
+ *         const room: Room = await signaling.join('device-7')
+ *         room.on('peer', (peer: Peer): void => {
+ *             const channel: PeerChannel = peer.createDataChannel('telemetry')
+ *             const timer: NodeJS.Timeout = setInterval((): void => {
+ *                 if (channel.readyState === 'open') channel.send(JSON.stringify({temperature: 21.5}))
+ *             }, 1000)
+ *             peer.on('close', (): void => clearInterval(timer))
+ *         })
+ *     }
+ * }
+ * ```
+ */
+export declare class SignalingClient extends Provider {
+    #private;
+    /**
+     * The URL of the signaling.
+     */
+    protected readonly url: string;
+    /**
+     * The client id.
+     */
+    protected readonly id?: string;
+    /**
+     * The path of Socket.IO.
+     */
+    protected readonly path: string;
+    /**
+     * More fields of the Socket.IO handshake's auth.
+     */
+    protected readonly auth: Record<string, unknown>;
+    /**
+     * How long a request waits for its answer.
+     */
+    protected readonly timeout: number;
+    /**
+     * `all`, or `relay` to use only the TURN relays.
+     */
+    protected readonly iceTransportPolicy: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates.
+     */
+    protected readonly icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates.
+     */
+    protected readonly iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs of the connections.
+     */
+    protected readonly codecs?: string[];
+    /**
+     * The name of the component of the worker threads of the connections.
+     */
+    protected readonly threads?: string;
+    /**
+     * Connect to the signaling (the requests wait for the connection).
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Leave the rooms and disconnect.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The client id: the member's id in the rooms.
+     */
+    get clientId(): string;
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected(): boolean;
+    /**
+     * The rooms joined.
+     */
+    get rooms(): Room[];
+    /**
+     * The ICE servers given by the server, with the TURN credentials (renewed before they expire).
+     */
+    get iceServers(): SignalingIceServer[];
+    /**
+     * Join a room: its `peer` event gives the other members, each with its {@link PeerConnection}.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     * @throws {SignalingRequestError} When the server refuses (`E_SIGNALING_DENIED`, `E_SIGNALING_LIMIT`) or does not
+     * answer (`E_SIGNALING_TIMEOUT`).
+     * @example
+     * ```typescript
+     * import type {Room, SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const room: Room = await signaling.join('meeting', {metadata: {name: 'Recorder'}})
+     * ```
+     */
+    join(room: string, options?: JoinOptions): Promise<Room>;
+    /**
+     * Listen to the signaling: `connected` (again, after a disconnection; the rooms are joined again), `disconnected`
+     * (the peer-to-peer connections stay up), `error` (a background task failed).
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * signaling.on('disconnected', (): void => console.log('signaling lost, reconnecting'))
+     * ```
+     */
+    on<Event extends keyof SignalingSessionEvents>(event: Event, listener: EmitterListener<SignalingSessionEvents[Event]>): this;
+    /**
+     * Remove a listener added with `on`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const listener = (error: Error): void => console.error(error)
+     * signaling.on('error', listener)
+     * signaling.off('error', listener)
+     * ```
+     */
+    off<Event extends keyof SignalingSessionEvents>(event: Event, listener: EmitterListener<SignalingSessionEvents[Event]>): this;
+    /**
+     * Leave the rooms, close their connections, disconnect, and destroy the object.
+     * @returns Resolves once done.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * await signaling.close()
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * The transport of the URL: Socket.IO or JSON-RPC over WebSocket
+     * @protected
+     */
+    protected transport(): Promise<SignalingTransport>;
+}

package/dist/types/protocol/SignalingProtocol.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The version of the signaling protocol, returned by `webrtc.join`; a later version stays compatible with the clients
+ * of this one.
+ */
+export declare const SIGNALING_PROTOCOL_VERSION: number;
+/**
+ * The methods of the signaling requests: a request is a service call whose pattern is `{method}` (the JSON-RPC method of
+ * a JSON-RPC request, the `method` field of a Socket.IO message).
+ */
+export declare const SignalingMethod: {
+    /**
+     * Join a room: `{room, metadata?, session?}`, answered with a {@link SignalingJoinResult}. The session is a random
+     * string the client chooses once per connection object: joining again with the same one (after a reconnection of the
+     * signaling) keeps the connections of the other members, a new one (a reloaded page) replaces them.
+     */
+    readonly join: "webrtc.join";
+    /**
+     * Send a description or a candidate to a member of a room: `{room, to, description?, candidate?}`, answered with
+     * `{delivered}`.
+     */
+    readonly signal: "webrtc.signal";
+    /**
+     * Leave a room: `{room}`, answered with `{}`.
+     */
+    readonly leave: "webrtc.leave";
+    /**
+     * Get the ICE servers again, with new TURN credentials: `{}`, answered with `{iceServers}`.
+     */
+    readonly iceServers: "webrtc.iceServers";
+    /**
+     * Tell the server the client is still there: `{}`, answered with `{}`. A client sends it every `heartbeatInterval`
+     * milliseconds of the join result when it is not 0 (the server cannot see the client's disconnection).
+     */
+    readonly heartbeat: "webrtc.heartbeat";
+};
+/**
+ * The events pushed by the server to the members of a room (`Entrypoint.notify`): a Socket.IO event, a JSON-RPC
+ * notification.
+ */
+export declare const SignalingEvent: {
+    /**
+     * A member joined a room the client is in: a {@link SignalingPeerEvent}.
+     */
+    readonly peerJoined: "webrtc:peer-joined";
+    /**
+     * A member left a room the client is in, or was disconnected: a {@link SignalingPeerLeftEvent}.
+     */
+    readonly peerLeft: "webrtc:peer-left";
+    /**
+     * A description or a candidate from a member: a {@link SignalingSignalEvent}.
+     */
+    readonly signal: "webrtc:signal";
+};
+/**
+ * A session description, as `RTCSessionDescriptionInit`.
+ */
+export interface SignalingDescription {
+    /**
+     * `offer`, `answer`, `pranswer` or `rollback`.
+     */
+    type: 'offer' | 'answer' | 'pranswer' | 'rollback';
+    /**
+     * The SDP; none for a rollback.
+     */
+    sdp?: string;
+}
+/**
+ * An ICE candidate, as `RTCIceCandidateInit`; an empty `candidate` is the end of the candidates.
+ */
+export interface SignalingCandidate {
+    /**
+     * The `candidate:` attribute of the SDP.
+     */
+    candidate: string;
+    /**
+     * The media stream of the candidate.
+     */
+    sdpMid?: string | null;
+    /**
+     * The index of its media description.
+     */
+    sdpMLineIndex?: number | null;
+    /**
+     * The ICE username fragment it belongs to.
+     */
+    usernameFragment?: string | null;
+}
+/**
+ * An ICE server, as `RTCIceServer`.
+ */
+export interface SignalingIceServer {
+    /**
+     * The URLs: `stun:host:port`, `turn:host:port?transport=udp|tcp`, `turns:host:port`.
+     */
+    urls: string | string[];
+    /**
+     * The TURN username.
+     */
+    username?: string;
+    /**
+     * The TURN password.
+     */
+    credential?: string;
+}
+/**
+ * The role the server gives a member it adds itself: `sfu` for the media server of a room (the other members connect
+ * to it only, and receive the media of each other through it), `whip` for a stream published with WHIP.
+ */
+export type SignalingRole = 'sfu' | 'whip';
+/**
+ * A member of a room, as the other members see it.
+ */
+export interface SignalingPeer {
+    /**
+     * The member's id: the client id of its connection to the signaling.
+     */
+    peerId: string;
+    /**
+     * What the member gave when it joined (a name, a role).
+     */
+    metadata?: unknown;
+    /**
+     * The session the member gave when it joined: a new one means a new client behind the same id.
+     */
+    session?: string;
+    /**
+     * The role of a member the server added itself; none for the clients.
+     */
+    role?: SignalingRole;
+    /**
+     * The id of the media server the member is connected to (a member of role `sfu`), in a room with one; set by the
+     * server. With a cluster, the members of a room may be connected to the media servers of different nodes.
+     */
+    sfu?: string;
+}
+/**
+ * A stream the media server of a room sends a member: its id on the connection to the server (the stream id of the
+ * MSID, at most 64 characters), the member it comes from, and its id on the connection of that member.
+ */
+export interface SignalingStream {
+    /**
+     * The id of the stream on the connection to the media server.
+     */
+    id: string;
+    /**
+     * The id of the member sending it.
+     */
+    peerId: string;
+    /**
+     * The id of the stream on the connection of that member.
+     */
+    stream: string;
+}
+/**
+ * The data channel of a member's connection to the media server of its room on which the member controls what it
+ * receives: both sides create it, negotiated, with this label and this id; its messages are
+ * {@link SignalingControlMessage}s in JSON.
+ */
+export declare const SignalingControlChannel: {
+    readonly label: "webrtc.control";
+    readonly id: 1023;
+};
+/**
+ * A message of a member to the media server of its room, on {@link SignalingControlChannel}: `pause` stops sending the
+ * member the track of a transceiver (by its `mid` on the connection to the server), `resume` sends it again.
+ */
+export interface SignalingControlMessage {
+    /**
+     * `pause` or `resume`.
+     */
+    type: 'pause' | 'resume';
+    /**
+     * The media id of the transceiver receiving the track.
+     */
+    mid: string;
+}
+/**
+ * The answer to `webrtc.join`.
+ */
+export interface SignalingJoinResult {
+    /**
+     * The version of the protocol ({@link SIGNALING_PROTOCOL_VERSION}).
+     */
+    v: number;
+    /**
+     * The id of the member who joined.
+     */
+    peerId: string;
+    /**
+     * The members already in the room.
+     */
+    peers: SignalingPeer[];
+    /**
+     * The ICE servers for the connections of the room, with TURN credentials valid for `credentialTtl` seconds.
+     */
+    iceServers: SignalingIceServer[];
+    /**
+     * How long the TURN credentials are valid, in seconds; 0 when there are none.
+     */
+    credentialTtl: number;
+    /**
+     * How often to send `webrtc.heartbeat`, in milliseconds; 0 when the server detects the disconnections itself.
+     */
+    heartbeatInterval: number;
+    /**
+     * The id of the media server of the room (a member of role `sfu`), when the room has one: the client connects to it
+     * only, not to the other members.
+     */
+    sfu?: string;
+}
+/**
+ * The event {@link SignalingEvent.peerJoined}.
+ */
+export interface SignalingPeerEvent extends SignalingPeer {
+    /**
+     * The room.
+     */
+    room: string;
+}
+/**
+ * The event {@link SignalingEvent.peerLeft}.
+ */
+export interface SignalingPeerLeftEvent {
+    /**
+     * The room.
+     */
+    room: string;
+    /**
+     * The id of the member.
+     */
+    peerId: string;
+    /**
+     * `left` when it asked to leave, `disconnected` when its client went away: its peer-to-peer connections may still be
+     * up, and it joins again with the same session once its client reconnects.
+     */
+    reason: 'left' | 'disconnected';
+}
+/**
+ * The event {@link SignalingEvent.signal}: a description or a candidate from another member.
+ */
+export interface SignalingSignalEvent {
+    /**
+     * The room.
+     */
+    room: string;
+    /**
+     * The id of the member who sent it.
+     */
+    from: string;
+    /**
+     * The session of the member who sent it.
+     */
+    session?: string;
+    /**
+     * A description, or none for a candidate.
+     */
+    description?: SignalingDescription;
+    /**
+     * A candidate, or none for a description.
+     */
+    candidate?: SignalingCandidate | null;
+    /**
+     * With a description of the media server of the room: the streams it sends, and whose they are.
+     */
+    streams?: SignalingStream[];
+}

package/dist/types/service/WebRTCServiceEntrypoint.d.ts

@@ -0,0 +1,158 @@
+import type { EntrypointAdapter, MiddlewareDefinition, ServiceContext } from '@lakutata/entrypoint';
+import { type ChannelRuntime } from '@lakutata/entrypoint/channel';
+import { type JSONRPCMappingOptions } from '@lakutata/entrypoint/adapter/jsonrpc';
+import { SignalingClient, type Peer, type Room, type SignalingClientOptions } from '../peer/SignalingClient.js';
+import type { PeerChannel } from '../peer/PeerChannel.js';
+/**
+ * The options of {@link webrtcServiceEntrypoint}: the signaling client whose rooms it serves, the rooms, the label of
+ * the channels, and how the requests map to the service actions (`methodField`, `toPattern`, `positionalParams`, as
+ * with `jsonRPCServiceEntrypoint`).
+ */
+export type WebRTCServiceEntrypointOptions = JSONRPCMappingOptions & {
+    /**
+     * The adapter name, to tell apart several service adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The options of a signaling client created by the adapter (its `url`, its `id`: the member id of the application
+     * in the rooms). The adapter closes it when it stops. Give either `signaling` or `client`.
+     */
+    signaling?: SignalingClientOptions;
+    /**
+     * A function returning the signaling client of the application, when the application also uses it (to publish its
+     * camera to the same rooms, for example): two clients with the same id would replace each other in the rooms. It is
+     * called once the application has launched; the adapter neither leaves its rooms nor closes it. Give either
+     * `signaling` or `client`.
+     */
+    client?: (runtime: ChannelRuntime<ServiceContext>) => SignalingClient | Promise<SignalingClient>;
+    /**
+     * The rooms whose members may call the service actions. They are joined once the application has launched (a room
+     * the client has joined already is served as it is); a failed join is reported to `onError` and tried again after 1
+     * second, then after twice as long each time, up to 10 seconds, except when the signaling refuses the room
+     * (`E_SIGNALING_DENIED`).
+     */
+    rooms: string[];
+    /**
+     * The metadata of the application in the rooms it joins, given to the other members.
+     * @default none
+     */
+    metadata?: unknown;
+    /**
+     * The label of the data channels carrying the requests: the members create a channel with this label to the
+     * application; the channels with other labels are left to the application.
+     * @default 'service'
+     */
+    label?: string;
+    /**
+     * The largest request, in bytes: a larger one is dropped and answered with an Invalid Request error without id
+     * (`-32600`).
+     * @default 10485760 (10 MiB)
+     */
+    limit?: number;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Called when a room cannot be joined, or the signaling client cannot be got, with the error.
+     * @default the error is written to the application's `log` component (`console.error` without one)
+     */
+    onError?: (error: unknown) => void | Promise<void>;
+};
+/**
+ * The member behind a service action's request served by {@link webrtcServiceEntrypoint}, as
+ * {@link webrtcRequestOfContext} returns it.
+ */
+export type WebRTCRequestInfo = {
+    /**
+     * The member that called: its id (also the context's `clientId`), its metadata and its session.
+     */
+    peer: Peer;
+    /**
+     * The room the member called through.
+     */
+    room: Room;
+    /**
+     * The data channel the request came through.
+     */
+    channel: PeerChannel;
+};
+/**
+ * Get the member that called a service action through a data channel, when {@link webrtcServiceEntrypoint} serves the
+ * request (to read its metadata, the room it called through, or close its channel).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The member, its room and its channel, or `undefined` when another adapter serves the request.
+ * @example
+ * ```typescript
+ * import {Controller, type ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {webrtcRequestOfContext, type WebRTCRequestInfo} from '@lakutata/webrtc'
+ *
+ * class WhoController extends Controller {
+ *     @ServiceAction({method: 'whoami'})
+ *     public async whoami(): Promise<{id?: string, room?: string}> {
+ *         const request: WebRTCRequestInfo | undefined = webrtcRequestOfContext(this.context as ServiceContext)
+ *         return {id: request?.peer.id, room: request?.room.name}
+ *     }
+ * }
+ * ```
+ */
+export declare function webrtcRequestOfContext(context: ServiceContext): WebRTCRequestInfo | undefined;
+/**
+ * Create a service adapter of an entrypoint served through WebRTC data channels: the application joins rooms of a
+ * signaling server as a member, and the other members (browsers, applications) call its service actions directly, over
+ * their peer-to-peer connection to it. A member creates a data channel with the adapter's label (`'service'` by
+ * default) to the application; with `PeerServiceProxy` (`@lakutata/webrtc/client` in the browsers), it calls the
+ * actions through it and receives the events pushed to it. In a room with a media server, the channel goes through
+ * the server, which sees the messages.
+ *
+ * The messages are JSON-RPC 2.0, as with `jsonRPCServiceEntrypoint`: the requests, the batches, the notifications, the
+ * error codes, and the events pushed as notifications. Each message is cut into chunks as `ChunkedChannel` does: each
+ * frame is a binary message whose first byte holds the flags (1: the last chunk of a message, 2: a text message) and
+ * the rest a part of the message, so a message of any size goes through.
+ *
+ * The client id of a request (`ServiceContext.clientId`) is the member id of the caller, and
+ * {@link webrtcRequestOfContext} gives its peer, room and channel. The member id is as trustworthy as the signaling
+ * server makes it: the server sends the signals of a member with the id it knows it by, so a member cannot pass for
+ * another one, but the id of a member is the client id of its connection to the signaling, which the client gives. Have
+ * the signaling server check who its clients are (its `authorize` option, the entrypoint's access control) before
+ * relying on the ids in the access control of the actions; the metadata of a member is what the member gave.
+ *
+ * `Entrypoint.notify(<member id>, …)` pushes an event to every channel of the member, `Entrypoint.broadcast()` to
+ * every channel. When a channel closes (its member left), its requests in progress are aborted. When the entrypoint
+ * stops, the new requests are answered with a `STOPPING` error (`-32001`); once the requests in progress are answered,
+ * the channels are closed, and the signaling client created by the adapter leaves its rooms.
+ * @param options The signaling client, the rooms, the label of the channels, the mapping of the requests.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {webrtcServiceEntrypoint} from '@lakutata/webrtc'
+ *
+ * class DoorController extends Controller {
+ *     @ServiceAction({method: 'door.status'})
+ *     public async status(input: {door: string}): Promise<{door: string, open: boolean}> {
+ *         return {door: input.door, open: false}
+ *     }
+ * }
+ *
+ * //A device in a private network: the browsers joining its room call its actions without going through a server
+ * Application.run({
+ *     id: 'door.device',
+ *     name: 'Door',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [DoorController],
+ *             service: webrtcServiceEntrypoint({
+ *                 signaling: {url: 'https://signaling.example.com', id: 'door-7'},
+ *                 rooms: ['door-7']
+ *             })
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * })
+ * ```
+ */
+export declare function webrtcServiceEntrypoint(options: WebRTCServiceEntrypointOptions): EntrypointAdapter<ServiceContext>;