@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/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/cjs/protocol/SignalingProtocol.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalingControlChannel = exports.SignalingEvent = exports.SignalingMethod = exports.SIGNALING_PROTOCOL_VERSION = void 0;
+/**
+ * The version of the signaling protocol, returned by `webrtc.join`; a later version stays compatible with the clients
+ * of this one.
+ */
+exports.SIGNALING_PROTOCOL_VERSION = 1;
+/**
+ * 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).
+ */
+exports.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.
+     */
+    join: 'webrtc.join',
+    /**
+     * Send a description or a candidate to a member of a room: `{room, to, description?, candidate?}`, answered with
+     * `{delivered}`.
+     */
+    signal: 'webrtc.signal',
+    /**
+     * Leave a room: `{room}`, answered with `{}`.
+     */
+    leave: 'webrtc.leave',
+    /**
+     * Get the ICE servers again, with new TURN credentials: `{}`, answered with `{iceServers}`.
+     */
+    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).
+     */
+    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.
+ */
+exports.SignalingEvent = {
+    /**
+     * A member joined a room the client is in: a {@link SignalingPeerEvent}.
+     */
+    peerJoined: 'webrtc:peer-joined',
+    /**
+     * A member left a room the client is in, or was disconnected: a {@link SignalingPeerLeftEvent}.
+     */
+    peerLeft: 'webrtc:peer-left',
+    /**
+     * A description or a candidate from a member: a {@link SignalingSignalEvent}.
+     */
+    signal: 'webrtc:signal'
+};
+/**
+ * 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.
+ */
+exports.SignalingControlChannel = {
+    label: 'webrtc.control',
+    id: 1023
+};

package/dist/cjs/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>;