@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/service/WebRTCServiceEntrypoint.js

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webrtcRequestOfContext = webrtcRequestOfContext;
+exports.webrtcServiceEntrypoint = webrtcServiceEntrypoint;
+const channel_1 = require("@lakutata/entrypoint/channel");
+const jsonrpc_1 = require("@lakutata/entrypoint/adapter/jsonrpc");
+const ChunkedChannel_js_1 = require("../shared/ChunkedChannel.js");
+const SignalingError_js_1 = require("../shared/SignalingError.js");
+const SignalingClient_js_1 = require("../peer/SignalingClient.js");
+/**
+ * The first delay before a failed join is tried again, in milliseconds
+ */
+const FIRST_RETRY_DELAY = 1000;
+/**
+ * The longest delay before a failed join is tried again, in milliseconds
+ */
+const MAX_RETRY_DELAY = 10000;
+/**
+ * How long closing waits for the responses being sent, in milliseconds
+ */
+const CLOSE_SEND_TIMEOUT = 2000;
+/**
+ * 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}
+ *     }
+ * }
+ * ```
+ */
+function webrtcRequestOfContext(context) {
+    return context.webrtc;
+}
+/**
+ * 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']
+ * })
+ * ```
+ */
+function webrtcServiceEntrypoint(options) {
+    const label = options.label ?? 'service';
+    const limit = options.limit ?? 10 * 1024 * 1024;
+    const protocol = new channel_1.JSONRPCProtocol(options);
+    let client;
+    let owned = false;
+    let stopping = false;
+    let closed = false;
+    //The channels of each member
+    const clients = new Map();
+    //The end of the serving of each channel, of each peer, of each room
+    const channels = new Map();
+    const peers = new Map();
+    const rooms = new Map();
+    //The responses and the events being sent, awaited before the channels close
+    const sending = new Set();
+    const timers = new Set();
+    /**
+     * Give an error to the onError handler, or write it to the log of the application
+     * @param runtime
+     * @param error
+     * @param message
+     */
+    const report = async (runtime, error, message) => {
+        if (options.onError) {
+            try {
+                return await options.onError(error);
+            }
+            catch (handlerError) {
+                error = handlerError;
+                message = 'The onError handler of the WebRTC service adapter failed';
+            }
+        }
+        try {
+            const logger = await runtime.getObject('log');
+            logger.error(error, message);
+        }
+        catch {
+            console.error(`${message}:`, error);
+        }
+    };
+    /**
+     * Send a message on a channel, if it is open
+     * @param chunked
+     * @param message
+     */
+    const send = (chunked, message) => {
+        if (closed)
+            return false;
+        const sent = chunked.send(message).catch(() => undefined);
+        sending.add(sent);
+        void sent.finally(() => sending.delete(sent));
+        return true;
+    };
+    /**
+     * Serve the requests of a channel of a member
+     * @param runtime
+     * @param channel
+     * @param peer
+     * @param room
+     */
+    const serveChannel = (runtime, channel, peer, room) => {
+        if (stopping || closed)
+            return channel.close();
+        let chunked;
+        try {
+            chunked = new ChunkedChannel_js_1.ChunkedChannel(channel, { maxMessageSize: limit });
+        }
+        catch {
+            //An unordered channel
+            return channel.close();
+        }
+        const abort = new AbortController();
+        const info = { peer: peer, room: room, channel: channel };
+        const answer = async (data) => {
+            if (typeof data !== 'string') {
+                send(chunked, JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: jsonrpc_1.JSONRPCErrorCode.INVALID_REQUEST, message: 'The message is not text' } }));
+                return;
+            }
+            const response = await protocol.handle(data, {
+                runtime: runtime,
+                transport: 'webrtc',
+                clientId: peer.id,
+                extra: { webrtc: info },
+                signal: abort.signal,
+                stopping: () => stopping
+            });
+            if (response !== undefined && !abort.signal.aborted)
+                send(chunked, JSON.stringify(response));
+        };
+        chunked.on('message', (data) => void answer(data));
+        chunked.on('error', (error) => void send(chunked, JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: jsonrpc_1.JSONRPCErrorCode.INVALID_REQUEST, message: error.message } })));
+        const members = clients.get(peer.id) ?? new Set();
+        clients.set(peer.id, members);
+        members.add(chunked);
+        const end = () => {
+            if (!channels.delete(chunked))
+                return;
+            channel.removeEventListener('close', end);
+            peer.off('close', end);
+            abort.abort();
+            members.delete(chunked);
+            if (!members.size && clients.get(peer.id) === members)
+                clients.delete(peer.id);
+        };
+        channels.set(chunked, end);
+        channel.addEventListener('close', end);
+        peer.on('close', end);
+        if (channel.readyState === 'closed')
+            end();
+    };
+    /**
+     * Serve the channels a member creates
+     * @param runtime
+     * @param peer
+     * @param room
+     */
+    const servePeer = (runtime, peer, room) => {
+        if (peers.has(peer) || peer.closed)
+            return;
+        const onChannel = (channel) => {
+            if (channel.label === label)
+                serveChannel(runtime, channel, peer, room);
+        };
+        const end = () => {
+            peers.delete(peer);
+            peer.off('datachannel', onChannel);
+            peer.off('close', end);
+        };
+        peers.set(peer, end);
+        peer.on('datachannel', onChannel);
+        peer.on('close', end);
+    };
+    /**
+     * Serve the members of a room
+     * @param runtime
+     * @param room
+     */
+    const serveRoom = (runtime, room) => {
+        if (rooms.has(room))
+            return;
+        const onPeer = (peer) => servePeer(runtime, peer, room);
+        const end = () => {
+            rooms.delete(room);
+            room.off('peer', onPeer);
+            room.off('close', end);
+        };
+        rooms.set(room, end);
+        //Called at once for the peers already there
+        room.on('peer', onPeer);
+        room.on('close', end);
+    };
+    /**
+     * Join a room and serve it; tried again later when it fails, unless the signaling refuses the room
+     * @param runtime
+     * @param name
+     * @param delay
+     */
+    const join = async (runtime, name, delay) => {
+        if (closed || !client)
+            return;
+        try {
+            const room = client.rooms.find((each) => each.name === name && !each.left) ?? await client.join(name, { metadata: options.metadata });
+            if (!closed)
+                serveRoom(runtime, room);
+        }
+        catch (error) {
+            if (closed)
+                return;
+            await report(runtime, error, `The WebRTC service adapter could not join the room ${name}`);
+            if (closed || (error instanceof SignalingError_js_1.SignalingRequestError && error.errno === 'E_SIGNALING_DENIED'))
+                return;
+            const timer = setTimeout(() => {
+                timers.delete(timer);
+                void join(runtime, name, Math.min(delay * 2, MAX_RETRY_DELAY));
+            }, delay);
+            timers.add(timer);
+        }
+    };
+    return {
+        channel: 'service',
+        definition: channel_1.ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            if (!options.signaling === !options.client)
+                throw new TypeError('Give the WebRTC service adapter either the options of a signaling client (signaling) or a function returning one (client)');
+            if (!options.rooms?.length)
+                throw new TypeError('Give the WebRTC service adapter the rooms to serve (rooms)');
+            //Created now, so its invalid options fail the start; it connects by itself, the rooms wait for the launch
+            if (options.signaling) {
+                client = await runtime.getObject(SignalingClient_js_1.SignalingClient, options.signaling);
+                owned = true;
+            }
+            //Once the application has launched: a signaling server of the same application is listening then
+            void runtime.ready.then(async () => {
+                if (closed)
+                    return;
+                if (!client) {
+                    try {
+                        client = await options.client(runtime);
+                    }
+                    catch (error) {
+                        return await report(runtime, error, 'The WebRTC service adapter could not get its signaling client');
+                    }
+                }
+                for (const name of options.rooms)
+                    void join(runtime, name, FIRST_RETRY_DELAY);
+            });
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+        },
+        notify: (clientId, event, args) => {
+            const members = clients.get(clientId);
+            if (!members?.size)
+                return false;
+            const notification = channel_1.JSONRPCProtocol.notification(event, args);
+            members.forEach((chunked) => send(chunked, notification));
+            return true;
+        },
+        broadcast: (event, args) => {
+            const notification = channel_1.JSONRPCProtocol.notification(event, args);
+            channels.forEach((_end, chunked) => send(chunked, notification));
+            return clients.size;
+        },
+        close: async () => {
+            //The responses of the requests ended are sent before the channels close
+            if (sending.size) {
+                let timer;
+                await Promise.race([
+                    Promise.allSettled([...sending]),
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, CLOSE_SEND_TIMEOUT);
+                    })
+                ]);
+                clearTimeout(timer);
+            }
+            closed = true;
+            timers.forEach((timer) => clearTimeout(timer));
+            timers.clear();
+            for (const [chunked, end] of [...channels]) {
+                end();
+                chunked.close();
+            }
+            for (const end of [...peers.values(), ...rooms.values()])
+                end();
+            clients.clear();
+            if (owned)
+                await client?.close();
+            client = undefined;
+        }
+    };
+}