@lakutata/webrtc 0.0.0-stage → 3.1.4

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

@@ -0,0 +1,231 @@
+import type { SignalingCandidate, SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+/**
+ * What the rooms need of a data channel: `RTCDataChannel` of the browsers, `PeerChannel` of Node.js.
+ */
+export interface DataChannelLike {
+    /**
+     * Its label.
+     */
+    readonly label: string;
+    /**
+     * `connecting`, `open`, `closing` or `closed`.
+     */
+    readonly readyState: string;
+    /**
+     * Send a message.
+     * @param data The message.
+     */
+    send(data: string): void;
+    /**
+     * Add a listener of an event: `open`, `message`, `close`.
+     * @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;
+    /**
+     * Dispatch an event to the listeners.
+     * @param event The event.
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Close it.
+     */
+    close(): void;
+}
+/**
+ * What the rooms need of a transceiver: `RTCRtpTransceiver` of the browsers, `RtpTransceiver` of Node.js.
+ */
+export interface TransceiverLike {
+    /**
+     * The media id of its line in the description; `null` until negotiated.
+     */
+    readonly mid: string | null;
+    /**
+     * The direction wanted.
+     */
+    direction: string;
+    /**
+     * The direction negotiated.
+     */
+    readonly currentDirection: string | null;
+    /**
+     * Its sending side.
+     */
+    readonly sender: {
+        readonly track: {
+            readonly kind: string;
+        } | null;
+        replaceTrack(track: any): Promise<void>;
+        setStreams(...streams: any[]): void;
+    };
+    /**
+     * Its receiving side.
+     */
+    readonly receiver: {
+        readonly track: {
+            readonly kind: string;
+        };
+    };
+}
+/**
+ * The options of a data channel, as `RTCDataChannelInit`.
+ */
+export interface DataChannelOptions {
+    /**
+     * Whether the messages arrive in order.
+     * @default true
+     */
+    ordered?: boolean;
+    /**
+     * How many times a message is sent again at most; none for a reliable channel.
+     */
+    maxRetransmits?: number;
+    /**
+     * How long a message is sent again at most, in milliseconds; none for a reliable channel.
+     */
+    maxPacketLifeTime?: number;
+    /**
+     * The subprotocol.
+     * @default ''
+     */
+    protocol?: string;
+    /**
+     * Whether both peers create the channel themselves with the same `id`, instead of one of them announcing it.
+     * @default false
+     */
+    negotiated?: boolean;
+    /**
+     * The id of a negotiated channel.
+     */
+    id?: number;
+}
+/**
+ * The configuration of a peer connection that the rooms set: the ICE servers, and whether to use only the TURN relays.
+ */
+export interface PeerConnectionConfiguration {
+    /**
+     * The ICE servers.
+     */
+    iceServers?: SignalingIceServer[];
+    /**
+     * `all`, or `relay` to use only the TURN relays.
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * Whether it is the connection to the media server of a room: it negotiates the RTP header extensions the server
+     * uses (the `headerExtensions` of `PeerConnection`; the browsers always do).
+     */
+    headerExtensions?: boolean;
+}
+/**
+ * What the rooms need of a peer connection: `RTCPeerConnection` of the browsers, `PeerConnection` of Node.js.
+ */
+export interface PeerConnectionLike<Channel extends DataChannelLike = DataChannelLike> {
+    /**
+     * The state of the offer and answer exchange.
+     */
+    readonly signalingState: string;
+    /**
+     * The state of the connection.
+     */
+    readonly connectionState: string;
+    /**
+     * The local description.
+     */
+    readonly localDescription: SignalingDescription | null;
+    /**
+     * Add a listener of an event: `negotiationneeded`, `icecandidate`, `connectionstatechange`, `datachannel`, `track`.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    addEventListener(type: string, listener: (event: any) => void): void;
+    /**
+     * Set the local description: the offer or the answer it creates, or a rollback.
+     * @param description A rollback; none for the offer or the answer.
+     */
+    setLocalDescription(description?: {
+        type: 'rollback';
+    }): Promise<unknown>;
+    /**
+     * Set the remote description.
+     * @param description The description.
+     */
+    setRemoteDescription(description: SignalingDescription): Promise<unknown>;
+    /**
+     * Add a remote candidate.
+     * @param candidate The candidate.
+     */
+    addIceCandidate(candidate: SignalingCandidate): Promise<unknown>;
+    /**
+     * Create a data channel.
+     * @param label Its label.
+     * @param options Its options.
+     */
+    createDataChannel(label: string, options?: DataChannelOptions): Channel;
+    /**
+     * Add a track to send (the rooms use it for the types of the tracks and the streams).
+     * @param track The track.
+     * @param streams Its streams.
+     */
+    addTrack(track: any, ...streams: any[]): unknown;
+    /**
+     * Add a transceiver sending a track.
+     * @param track The track.
+     * @param init Its direction and its streams.
+     */
+    addTransceiver(track: any, init: {
+        direction: 'sendonly';
+        streams: any[];
+    }): TransceiverLike;
+    /**
+     * The transceivers.
+     */
+    getTransceivers(): TransceiverLike[];
+    /**
+     * Restart ICE: the next offer gathers new candidates.
+     */
+    restartIce(): void;
+    /**
+     * The configuration.
+     */
+    getConfiguration(): object;
+    /**
+     * Change the configuration (the ICE servers).
+     * @param configuration The whole configuration.
+     */
+    setConfiguration(configuration: object): void;
+    /**
+     * Close the connection.
+     */
+    close(): unknown;
+}
+/**
+ * Creates the peer connections of the rooms.
+ * @param configuration The ICE servers given by the signaling, and the transport policy.
+ * @returns The connection.
+ */
+export type PeerConnectionFactory<Connection extends PeerConnectionLike<any>> = (configuration: PeerConnectionConfiguration) => Connection | Promise<Connection>;
+/**
+ * The track type of a peer connection type: `MediaStreamTrack` in the browsers, `MediaTrack` in Node.js
+ */
+export type TrackOf<Connection extends PeerConnectionLike<any>> = Parameters<Connection['addTrack']>[0];
+/**
+ * The stream type of a peer connection type: `MediaStream` in the browsers, a stream id in Node.js
+ */
+export type StreamOf<Connection extends PeerConnectionLike<any>> = Parameters<Connection['addTrack']> extends [any, ...infer Streams] ? Streams[number] : never;
+/**
+ * The data channel type of a peer connection type
+ */
+export type ChannelOf<Connection extends PeerConnectionLike<any>> = ReturnType<Connection['createDataChannel']>;
+/**
+ * The track event type of a peer connection type: `RTCTrackEvent` in the browsers, `PeerTrackEvent` in Node.js
+ */
+export type TrackEventOf<Connection> = Connection extends {
+    ontrack: ((event: infer Event) => any) | null;
+} ? Event : never;

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

@@ -0,0 +1,50 @@
+/**
+ * The events of an emitter: for each event, the arguments of its listeners.
+ */
+export type EmitterEvents = Record<string, unknown[]>;
+/**
+ * A listener of an event.
+ */
+export type EmitterListener<Args extends unknown[]> = (...args: Args) => void;
+/**
+ * A small typed event emitter, the same in the browsers and in Node.js (it does not use `node:events`). A listener
+ * throwing does not stop the other listeners: its error is reported as an uncaught one, as the listeners of an
+ * `EventTarget` are.
+ */
+export declare class Emitter<Events extends EmitterEvents> {
+    #private;
+    /**
+     * Add a listener of an event.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    on<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Add a listener of the next emission of an event only.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    once<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns This emitter.
+     */
+    off<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Call the listeners of an event
+     * @param event
+     * @param args
+     * @protected
+     */
+    protected emit<Event extends keyof Events>(event: Event, ...args: Events[Event]): boolean;
+    /**
+     * Whether an event has listeners
+     * @param event
+     * @protected
+     */
+    protected listened(event: keyof Events): boolean;
+}

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

@@ -0,0 +1,182 @@
+import type { SignalingCandidate, SignalingControlMessage, SignalingDescription } from '../protocol/SignalingProtocol.js';
+import type { ChannelOf, DataChannelOptions, PeerConnectionLike, TrackEventOf, TrackOf } from './Connections.js';
+import { Emitter } from './Emitter.js';
+/**
+ * The events of a {@link Peer}.
+ */
+export type PeerEvents<Channel, TrackEvent = unknown> = {
+    /**
+     * A data channel the other member created.
+     */
+    datachannel: [channel: Channel];
+    /**
+     * An audio or video track of the other member: the `track` event of the connection (`event.track`,
+     * `event.streams`).
+     */
+    track: [event: TrackEvent];
+    /**
+     * The state of the connection changed: `new`, `connecting`, `connected`, `disconnected`, `failed`, `closed`.
+     */
+    connectionstatechange: [state: string];
+    /**
+     * The other member joined the room again with new metadata.
+     */
+    metadata: [metadata: unknown];
+    /**
+     * The peer is closed: the other member left, its connection failed for good, or the room was left.
+     */
+    close: [];
+    /**
+     * The negotiation failed.
+     */
+    error: [error: Error];
+};
+/**
+ * A signal for the other member
+ */
+export type PeerSignal = {
+    description?: SignalingDescription;
+    candidate?: SignalingCandidate;
+};
+/**
+ * What a peer needs of its room
+ */
+export interface PeerHost<Connection extends PeerConnectionLike<any>> {
+    readonly localId: string;
+    create(): Connection | Promise<Connection>;
+    send(to: string, signal: PeerSignal): Promise<void>;
+    readonly signalingUp: boolean;
+    closed(peer: Peer<Connection>): void;
+    readonly polite?: boolean;
+    readonly relay?: Peer<Connection>;
+    control?(message: SignalingControlMessage): void;
+}
+/**
+ * Another member of a room, and the peer-to-peer connection to it: `connection` is a `RTCPeerConnection` in the
+ * browsers and a `PeerConnection` in Node.js. The offers and the answers are exchanged through the signaling as the
+ * W3C "perfect negotiation" does it, so both members may add channels (and tracks) at any time, at the same time too:
+ * the member whose id comes first is the polite one, giving up its offer when both offer at once.
+ *
+ * The connection is set up when a data channel (or a track) is added on one side. It is repaired by itself: an ICE
+ * restart when it fails or stays disconnected for 5 seconds, once the signaling is up. The peer stays when its member's
+ * signaling is lost while their connection is up, and closes when the member leaves the room, when the connection
+ * fails without the member in the room, and when the room is left.
+ *
+ * In a room with a media server, the members are not connected to each other: `connection` is the connection to the
+ * server, the same for all the peers, and the tracks of a member come through it (the ids of their streams are the
+ * ones of that connection: see `Room.streamOf()`). When the local member or the member is connected to another media
+ * server (its node went down), the peer closes and the room emits a new one, as for a member joining again with a new
+ * session: the listeners of `peer` create its channels again.
+ */
+export declare class Peer<Connection extends PeerConnectionLike<any> = PeerConnectionLike> extends Emitter<PeerEvents<ChannelOf<Connection>, TrackEventOf<Connection>>> {
+    #private;
+    /**
+     * The other member's id.
+     */
+    readonly id: string;
+    /**
+     * Whether this side gives up its offer when both offer at once.
+     */
+    readonly polite: boolean;
+    /**
+     * Create the peer of a member (by its room).
+     * @param host The room.
+     * @param id The member's id.
+     * @param metadata The member's metadata.
+     * @param session The member's session.
+     */
+    constructor(host: PeerHost<Connection>, id: string, metadata: unknown, session: string | undefined);
+    /**
+     * The peer-to-peer connection to the member.
+     */
+    get connection(): Connection;
+    /**
+     * What the member gave when it joined.
+     */
+    get metadata(): unknown;
+    /**
+     * The session of the member's client.
+     */
+    get session(): string | undefined;
+    /**
+     * Whether the member is not in the room any more (its signaling was lost) while the connection is still up.
+     */
+    get away(): boolean;
+    /**
+     * Whether the peer is closed.
+     */
+    get closed(): boolean;
+    /**
+     * Resolves once the connection is created (the room emits `peer` then); in a room with a media server, once the
+     * connection to the server has exchanged its first offer and answer.
+     */
+    get ready(): Promise<void>;
+    /**
+     * Resolves once a first offer and its answer are exchanged.
+     * @internal
+     */
+    get negotiated(): Promise<void>;
+    /**
+     * Create a data channel to the member; the connection is set up (or negotiated again) by itself. In a room with a
+     * media server, the channel goes through the server, which relays its messages (and sees them): its `protocol` is
+     * the id of this member on this side, and the id of the local member on the other side.
+     * @param label The label of the channel.
+     * @param options Whether it is ordered, reliable, negotiated.
+     * @returns The channel: an `RTCDataChannel` in the browsers, a `PeerChannel` in Node.js.
+     * @throws {TypeError} In a room with a media server, for a channel with a `protocol` or a negotiated one.
+     */
+    createDataChannel(label: string, options?: DataChannelOptions): ChannelOf<Connection>;
+    /**
+     * Stop receiving a track of the member until resumed (a video not shown): with a media server, the server stops
+     * sending it; between two members, its transceiver stops receiving (a new negotiation).
+     * @param track A track of the member (`event.track` of `track`).
+     */
+    pause(track: TrackOf<Connection>): void;
+    /**
+     * Receive again a track paused.
+     * @param track The track.
+     */
+    resume(track: TrackOf<Connection>): void;
+    /**
+     * Restart ICE: new candidates are gathered and exchanged, for a connection whose network changed.
+     */
+    restartIce(): void;
+    /**
+     * Close the connection to the member.
+     */
+    close(): void;
+    /**
+     * A signal from the member, handled after the ones before it
+     * @param signal
+     * @internal
+     */
+    receive(signal: PeerSignal): void;
+    /**
+     * The member joined again
+     * @param metadata
+     * @internal
+     */
+    rejoined(metadata: unknown): void;
+    /**
+     * The member's signaling was lost; the peer stays while the connection is up
+     * @internal
+     */
+    left(): void;
+    /**
+     * The signaling is up again: the ICE restart waiting for it
+     * @internal
+     */
+    signalingUp(): void;
+    /**
+     * A track of the member, received through the media server
+     * @param event
+     * @internal
+     */
+    relayedTrack(event: TrackEventOf<Connection>): void;
+    /**
+     * A channel the member opened, relayed by the media server
+     * @param channel
+     * @internal
+     */
+    relayedChannel(channel: ChannelOf<Connection>): void;
+}

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

@@ -0,0 +1,173 @@
+import { type ChunkableChannel } from './ChunkedChannel.js';
+/**
+ * The error of a call of a {@link PeerServiceProxy}: the error the action threw (its `errno`, the whole error object
+ * as `data`), the JSON-RPC error of the request (`code`), `E_PEER_SERVICE_TIMEOUT` and `E_PEER_SERVICE_CLOSED` for
+ * the calls without a response, or `E_PEER_SERVICE_TOO_LARGE` for a request over the size limit, not sent.
+ * @example
+ * ```typescript
+ * import {PeerServiceError, type PeerServiceProxy} from '@lakutata/webrtc/client'
+ *
+ * declare const device: PeerServiceProxy
+ * try {
+ *     await device.invoke({method: 'door.open'})
+ * } catch (error) {
+ *     if (error instanceof PeerServiceError && error.errno === 'E_ACCESS_DENY') console.log('not allowed to open the door')
+ * }
+ * ```
+ */
+export declare class PeerServiceError extends Error {
+    /**
+     * The `errno` of the action's error (`E_ACCESS_DENY`, `E_INVALID_VALUE`…), the JSON-RPC error code when the error
+     * has none, or `E_PEER_SERVICE_TIMEOUT`, `E_PEER_SERVICE_CLOSED` and `E_PEER_SERVICE_TOO_LARGE`.
+     */
+    readonly errno: string | number;
+    /**
+     * The JSON-RPC error code of the response (`-32601` when no action matches, `-32602` for an invalid input…);
+     * `undefined` for the calls without a response.
+     */
+    readonly code?: number;
+    /**
+     * The error the application sent, as it sent it: the properties of the action's error.
+     */
+    readonly data?: unknown;
+    /**
+     * Create the error.
+     * @param message The message.
+     * @param errno The error number.
+     * @param code The JSON-RPC error code.
+     * @param data The error the application sent.
+     */
+    constructor(message: string, errno: string | number, code?: number, data?: unknown);
+}
+/**
+ * The options of a {@link PeerServiceProxy}.
+ */
+export interface PeerServiceProxyOptions {
+    /**
+     * The field of the input sent as the request's method: the `methodField` of the application's
+     * `webrtcServiceEntrypoint`.
+     * @default 'method'
+     */
+    methodField?: string;
+    /**
+     * The size of a response or an event received at most, in bytes: a larger one is dropped (its call then times out).
+     * @default 67108864 (64 MiB)
+     */
+    maxMessageSize?: number;
+    /**
+     * The size of a request sent at most, in bytes, as JSON: a larger call fails at once with
+     * `E_PEER_SERVICE_TOO_LARGE`, since the application drops the requests over its `limit` without knowing which call
+     * they were. The same as the default `limit` of `webrtcServiceEntrypoint`.
+     * @default 10485760 (10 MiB)
+     */
+    maxRequestSize?: number;
+}
+/**
+ * The service actions of another member, called through a data channel to it: the member is a lakutata application
+ * serving its service actions with `webrtcServiceEntrypoint` (its controllers' `@ServiceAction` methods). Create the
+ * channel with the label the application serves (`'service'` by default); the calls wait for it to open. A call is a
+ * request of JSON-RPC 2.0 whose method is the input's `methodField`, and the events the application pushes to this
+ * member (`Entrypoint.notify()` with the member's id, `Entrypoint.broadcast()`) reach the listeners added with `on`.
+ * The messages are cut into chunks as `ChunkedChannel` does, so their size is not limited by the data channel.
+ *
+ * The same in the browsers (`@lakutata/webrtc/client`) and in Node.js (`@lakutata/webrtc`).
+ * @example
+ * ```typescript
+ * import {PeerServiceProxy, type Peer} from '@lakutata/webrtc/client'
+ *
+ * declare const peer: Peer
+ * //The device's action declared with @ServiceAction({method: 'door.status'})
+ * const device: PeerServiceProxy = new PeerServiceProxy(peer.createDataChannel('service'))
+ * device.on('opened', (by: string): void => console.log(`opened by ${by}`))
+ * const status: {open: boolean} = await device.invoke({method: 'door.status', door: 'front'})
+ * ```
+ */
+export declare class PeerServiceProxy {
+    #private;
+    /**
+     * Call the service actions of a member through a data channel to it.
+     * @param channel The data channel: an `RTCDataChannel` in the browsers, a `PeerChannel` in Node.js; ordered and
+     * reliable (the default).
+     * @param options The method field, the size of a message received at most.
+     * @throws {TypeError} When the channel is not ordered.
+     */
+    constructor(channel: ChunkableChannel, options?: PeerServiceProxyOptions);
+    /**
+     * The data channel.
+     */
+    get channel(): ChunkableChannel;
+    /**
+     * Call a service action of the member.
+     * @param input The action's pattern and input: its `methodField` (`method` by default) is sent as the request's
+     * method, the rest as its params.
+     * @param timeout How long to wait for the response, in milliseconds (the time to open the channel included).
+     * @returns The action's result.
+     * @throws {PeerServiceError} The error of the action or of the request, `E_PEER_SERVICE_TIMEOUT` and
+     * `E_PEER_SERVICE_CLOSED` when no response came, or `E_PEER_SERVICE_TOO_LARGE` when the request is over
+     * `maxRequestSize` (it is not sent).
+     * @throws {TypeError} When the input's `methodField` is not a string.
+     * @example
+     * ```typescript
+     * import type {PeerServiceProxy} from '@lakutata/webrtc/client'
+     *
+     * declare const device: PeerServiceProxy
+     * //The request {"jsonrpc": "2.0", "id": 1, "method": "light.set", "params": {"room": "hall", "on": true}}
+     * await device.invoke({method: 'light.set', room: 'hall', on: true}, 5000)
+     * ```
+     */
+    invoke<T = any>(input: Record<string, unknown>, timeout?: number): Promise<T>;
+    /**
+     * Listen to an event the application pushes to this member.
+     * @param event The event's name.
+     * @param listener Called with the event's arguments.
+     * @returns The proxy.
+     * @example
+     * ```typescript
+     * import type {PeerServiceProxy} from '@lakutata/webrtc/client'
+     *
+     * declare const device: PeerServiceProxy
+     * //entrypoint.notify(<this member's id>, 'progress', 50) in the application
+     * device.on('progress', (percent: number): void => console.log(`${percent}%`))
+     * ```
+     */
+    on(event: string, listener: (...args: any[]) => void): this;
+    /**
+     * Listen to the next push of an event only.
+     * @param event The event's name.
+     * @param listener Called with the event's arguments.
+     * @returns The proxy.
+     * @example
+     * ```typescript
+     * import type {PeerServiceProxy} from '@lakutata/webrtc/client'
+     *
+     * declare const device: PeerServiceProxy
+     * device.once('ready', (): void => console.log('the device is ready'))
+     * ```
+     */
+    once(event: string, listener: (...args: any[]) => void): this;
+    /**
+     * Remove a listener of an event, or all of them.
+     * @param event The event's name.
+     * @param listener The listener; all the listeners of the event without it.
+     * @returns The proxy.
+     * @example
+     * ```typescript
+     * import type {PeerServiceProxy} from '@lakutata/webrtc/client'
+     *
+     * declare const device: PeerServiceProxy
+     * device.off('progress')
+     * ```
+     */
+    off(event: string, listener?: (...args: any[]) => void): this;
+    /**
+     * Close the data channel: the calls waiting for their response fail with `E_PEER_SERVICE_CLOSED`.
+     * @example
+     * ```typescript
+     * import type {PeerServiceProxy} from '@lakutata/webrtc/client'
+     *
+     * declare const device: PeerServiceProxy
+     * device.close()
+     * ```
+     */
+    close(): void;
+}