@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/adapter/jsonrpc/JSONRPCProtocol.js

@@ -0,0 +1,182 @@
+import { InvalidValueException } from '@lakutata/core';
+import { ServiceContext } from '../../context/ServiceContext.js';
+import { ServiceResponseCodec } from '../../lib/ServiceResponseCodec.js';
+import { ControllerActionNotFoundException } from '../../exceptions/ControllerActionNotFoundException.js';
+import { EntrypointStoppedException } from '../../exceptions/EntrypointStoppedException.js';
+/**
+ * The error codes of the JSON-RPC 2.0 responses sent by {@link jsonRPCServiceEntrypoint}.
+ */
+export const JSONRPCErrorCode = {
+    /**
+     * The message is not valid JSON.
+     */
+    PARSE_ERROR: -32700,
+    /**
+     * The message is not a JSON-RPC 2.0 request (or is an empty batch, or the HTTP request is not a `POST` to the path).
+     */
+    INVALID_REQUEST: -32600,
+    /**
+     * No service action matches the request (`ControllerActionNotFoundException`).
+     */
+    METHOD_NOT_FOUND: -32601,
+    /**
+     * The params are given by position without the `positionalParams` option, or fail the action's input validation
+     * (`InvalidValueException`).
+     */
+    INVALID_PARAMS: -32602,
+    /**
+     * Reserved by the specification for the internal errors; the adapter does not send it.
+     */
+    INTERNAL_ERROR: -32603,
+    /**
+     * Any other error thrown by an action (in the server error range, -32000 to -32099), with the whole error object as
+     * the error's `data`.
+     */
+    SERVER_ERROR: -32000,
+    /**
+     * The entrypoint is stopping and refuses the new requests (`EntrypointStoppedException`).
+     */
+    STOPPING: -32001
+};
+/**
+ * Get the JSON-RPC request behind a service action's request, when {@link jsonRPCServiceEntrypoint} serves it (to
+ * tell a notification from a request, or read the transport).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The request's method, id and transport, or `undefined` when another adapter serves the request.
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {jsonRPCRequestOfContext, type JSONRPCRequestInfo} from 'lakutata/adapter/jsonrpc'
+ *
+ * class LogController extends Controller {
+ *     //{"jsonrpc": "2.0", "method": "log.write", "params": {"line": "started"}}: a notification, no id
+ *     @ServiceAction({method: 'log.write'})
+ *     public async write(input: {line: string}): Promise<void> {
+ *         const request: JSONRPCRequestInfo | undefined = jsonRPCRequestOfContext(this.context as ServiceContext)
+ *         console.log(`${request?.transport}: ${input.line}`)
+ *     }
+ * }
+ * ```
+ */
+export function jsonRPCRequestOfContext(context) {
+    return context.jsonrpc;
+}
+/**
+ * An error of JSON-RPC
+ * @param id
+ * @param code
+ * @param message
+ * @param data
+ */
+function errorResponse(id, code, message, data) {
+    return { jsonrpc: '2.0', id: id, error: { code: code, message: message, ...data === undefined ? {} : { data: data } } };
+}
+/**
+ * The code of an error of an action
+ * @param error
+ */
+function errorCode(error) {
+    if (error instanceof ControllerActionNotFoundException)
+        return JSONRPCErrorCode.METHOD_NOT_FOUND;
+    if (error instanceof InvalidValueException)
+        return JSONRPCErrorCode.INVALID_PARAMS;
+    if (error instanceof EntrypointStoppedException)
+        return JSONRPCErrorCode.STOPPING;
+    return JSONRPCErrorCode.SERVER_ERROR;
+}
+/**
+ * The requests of JSON-RPC 2.0 dispatched to the service actions: the single ones, the batches, the notifications (no
+ * response); their methods given to the patterns of the actions
+ */
+export class JSONRPCProtocol {
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * The pattern and the input of the action of a request
+     * @param request
+     * @protected
+     */
+    pattern(request) {
+        if (this.options.toPattern)
+            return this.options.toPattern(request.method, request.params);
+        const field = this.options.methodField ?? 'method';
+        if (Array.isArray(request.params)) {
+            if (!this.options.positionalParams)
+                throw Object.assign(new Error('The params by position are not accepted: give them by name (an object)'), { jsonrpcCode: JSONRPCErrorCode.INVALID_PARAMS });
+            return { [this.options.positionalParams]: request.params, [field]: request.method };
+        }
+        return { ...request.params ?? {}, [field]: request.method };
+    }
+    /**
+     * The response of a request (none for a notification)
+     * @param request
+     * @param dispatch
+     * @protected
+     */
+    async one(request, dispatch) {
+        const candidate = request;
+        const id = typeof candidate?.id === 'string' || typeof candidate?.id === 'number' ? candidate.id : null;
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate) || candidate.jsonrpc !== '2.0' || typeof candidate.method !== 'string'
+            || (candidate.params !== undefined && (candidate.params === null || typeof candidate.params !== 'object'))
+            || (candidate.id !== undefined && candidate.id !== null && typeof candidate.id !== 'string' && typeof candidate.id !== 'number')) {
+            return errorResponse(id, JSONRPCErrorCode.INVALID_REQUEST, 'The request is not a request of JSON-RPC 2.0');
+        }
+        const notification = !('id' in candidate);
+        const respond = (response) => notification ? undefined : response;
+        if (dispatch.stopping())
+            return respond(errorResponse(id, JSONRPCErrorCode.STOPPING, 'The entrypoint is stopping'));
+        let data;
+        try {
+            data = this.pattern(candidate);
+        }
+        catch (error) {
+            return respond(errorResponse(id, error.jsonrpcCode ?? JSONRPCErrorCode.INVALID_PARAMS, error.message));
+        }
+        try {
+            const context = new ServiceContext({
+                data: data,
+                clientId: dispatch.clientId,
+                jsonrpc: { method: candidate.method, id: candidate.id, transport: dispatch.transport },
+                ...dispatch.extra ?? {}
+            });
+            //A StatusResult sent as its data (a file or an event stream cannot be sent: an error)
+            const result = ServiceResponseCodec.payload(await dispatch.runtime.dispatch(context, { signal: dispatch.signal }));
+            return respond({ jsonrpc: '2.0', id: id, result: result === undefined ? null : result });
+        }
+        catch (error) {
+            //The error of the action: its message, the whole error as its data (as the other service adapters give it)
+            return respond(errorResponse(id, errorCode(error), error?.message || String(error), ServiceResponseCodec.encodeError(error).error));
+        }
+    }
+    /**
+     * The response of a message (a request, a batch): undefined when there is none (notifications)
+     * @param message its text
+     * @param dispatch
+     */
+    async handle(message, dispatch) {
+        let parsed;
+        try {
+            parsed = JSON.parse(message);
+        }
+        catch {
+            return errorResponse(null, JSONRPCErrorCode.PARSE_ERROR, 'The message is not JSON');
+        }
+        if (!Array.isArray(parsed))
+            return await this.one(parsed, dispatch);
+        if (!parsed.length)
+            return errorResponse(null, JSONRPCErrorCode.INVALID_REQUEST, 'The batch is empty');
+        const responses = await Promise.all(parsed.map((request) => this.one(request, dispatch)));
+        const answered = responses.filter((response) => !!response);
+        return answered.length ? answered : undefined;
+    }
+    /**
+     * A notification sent to a client (an event pushed)
+     * @param event
+     * @param args
+     */
+    static notification(event, args) {
+        return JSON.stringify({ jsonrpc: '2.0', method: event, params: args });
+    }
+}

package/dist/esm/adapter/jsonrpc/JSONRPCServiceEntrypoint.js

@@ -0,0 +1,361 @@
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { ServiceChannel } from '../../channel/BuiltinChannels.js';
+import { JSONRPCErrorCode, JSONRPCProtocol } from './JSONRPCProtocol.js';
+import { applicationOf } from '../../lib/ApplicationOf.js';
+/**
+ * The headers of the responses of HTTP: the tools of the browsers may call the adapter
+ */
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, id'
+};
+/**
+ * The id of the client of a request of HTTP (its header id, its query id)
+ * @param request
+ */
+function clientIdOf(request) {
+    const url = new URL(request.url ?? '/', 'http://localhost');
+    const given = request.headers.id ?? url.searchParams.get('id');
+    const id = Array.isArray(given) ? given[0] : given ?? undefined;
+    return id && id.length <= 200 ? id : undefined;
+}
+/**
+ * The body of a request, up to a limit
+ * @param request
+ * @param limit
+ */
+async function readBody(request, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > limit)
+            throw Object.assign(new Error(`The body of the request is larger than ${limit} bytes`), { status: 413 });
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * The messages of a stream framed by lines, or by their Content-Length headers. A message larger than the limit is
+ * skipped (the rest of its line, or the length its header declares, keeping the framing) and reported
+ * @param input
+ * @param framing
+ * @param limit
+ * @param receive
+ * @param ended
+ * @param oversized
+ */
+function readMessages(input, framing, limit, receive, ended, oversized) {
+    let buffer = Buffer.alloc(0);
+    //The bytes of an oversized message still to skip (content-length), or its line being skipped (newline)
+    let skipping = 0;
+    let skippingLine = false;
+    const onData = (chunk) => {
+        buffer = Buffer.concat([buffer, typeof chunk === 'string' ? Buffer.from(chunk) : chunk]);
+        for (;;) {
+            if (skipping) {
+                const skipped = Math.min(skipping, buffer.length);
+                buffer = buffer.subarray(skipped);
+                skipping -= skipped;
+                if (skipping)
+                    break;
+            }
+            if (framing === 'newline') {
+                const end = buffer.indexOf(0x0a);
+                if (end < 0) {
+                    //A line growing over the limit: skipped up to its end
+                    if (buffer.length > limit) {
+                        buffer = Buffer.alloc(0);
+                        if (!skippingLine)
+                            oversized();
+                        skippingLine = true;
+                    }
+                    break;
+                }
+                const tooLarge = skippingLine || end > limit;
+                const line = tooLarge ? '' : buffer.subarray(0, end).toString('utf8').trim();
+                buffer = buffer.subarray(end + 1);
+                if (tooLarge && !skippingLine)
+                    oversized();
+                skippingLine = false;
+                if (line)
+                    receive(line);
+                continue;
+            }
+            const headerEnd = buffer.indexOf('\r\n\r\n');
+            if (headerEnd < 0) {
+                //No header of a message: what is not one is dropped, its end kept (a part of the next header)
+                if (buffer.length > limit)
+                    buffer = buffer.subarray(buffer.length - 3);
+                break;
+            }
+            const length = Number(buffer.subarray(0, headerEnd).toString('ascii').match(/content-length:\s*(\d+)/i)?.[1] ?? NaN);
+            if (!Number.isFinite(length)) {
+                //Not a header of a message: skipped
+                buffer = buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            if (length > limit) {
+                //Its content skipped as it arrives
+                buffer = buffer.subarray(headerEnd + 4);
+                skipping = length;
+                oversized();
+                continue;
+            }
+            if (buffer.length < headerEnd + 4 + length)
+                break;
+            receive(buffer.subarray(headerEnd + 4, headerEnd + 4 + length).toString('utf8'));
+            buffer = buffer.subarray(headerEnd + 4 + length);
+        }
+    };
+    input.on('data', onData);
+    input.once('end', ended);
+    return () => {
+        input.off('data', onData);
+        input.off('end', ended);
+    };
+}
+/**
+ * Create a service adapter of an entrypoint served over JSON-RPC 2.0, on HTTP, WebSocket or stdio. Only the WebSocket
+ * transport needs an optional peer dependency, `ws`; without it, the entrypoint fails to start.
+ *
+ * A request's method and named params become the service action's pattern and input: by default
+ * `{"method": "user.get", "params": {"id": 1}}` is dispatched as `{method: 'user.get', id: 1}` (see
+ * {@link JSONRPCMappingOptions} for the other mappings). The batches are answered with an array of responses, the
+ * notifications (no `id`) run without a response. The action's result is the response's `result` (`null` for none);
+ * its error becomes a JSON-RPC error (see {@link JSONRPCErrorCode}): `METHOD_NOT_FOUND`, `INVALID_PARAMS` for a failed
+ * validation, otherwise `SERVER_ERROR` with the whole error object as its `data`.
+ *
+ * Over HTTP, a message is the body of a `POST` to the path, answered with 200 and the JSON response (204 when it held
+ * only notifications); any other method or path is answered with 404, and the CORS headers allow any origin. Over
+ * WebSocket and stdio, the events pushed by `Entrypoint.notify` and `Entrypoint.broadcast` are sent as notifications,
+ * `{"jsonrpc": "2.0", "method": event, "params": args}`. The client id carried by `ServiceContext.clientId` is the `id`
+ * header or `id` query parameter of the HTTP request or of the WebSocket connection (at most 200 characters; a random
+ * one for a WebSocket connection without it), and `'stdio'` on stdio.
+ *
+ * When an HTTP client disconnects before its response, the action's abort signal fires. When the entrypoint stops,
+ * stdio stops reading, the new requests are answered with `STOPPING`, and once the requests in progress are answered
+ * the WebSocket connections are closed (code 1001) and the server shuts down.
+ * @param options The adapter options; by default it serves HTTP on port 3000 of all the interfaces, on the path `/`.
+ * @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 {jsonRPCServiceEntrypoint} from 'lakutata/adapter/jsonrpc'
+ * import WebSocket from 'ws'
+ *
+ * class UserController extends Controller {
+ *     @ServiceAction({method: 'user.get'})
+ *     public async get(input: {id: number}): Promise<{id: number, name: string}> {
+ *         return {id: input.id, name: 'Ada'}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'user.service',
+ *     name: 'Users',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             service: [
+ *                 //POST http://localhost:3000/rpc
+ *                 jsonRPCServiceEntrypoint({name: 'rpc-http', port: 3000, path: '/rpc'}),
+ *                 //ws://localhost:3001/rpc, with the events pushed
+ *                 jsonRPCServiceEntrypoint({name: 'rpc-ws', transport: 'websocket', port: 3001, path: '/rpc'})
+ *             ]
+ *         })
+ *     }
+ * })
+ *
+ * //An HTTP client: {"jsonrpc": "2.0", "id": 1, "result": {"id": 1, "name": "Ada"}}
+ * const response: Response = await fetch('http://localhost:3000/rpc', {
+ *     method: 'POST',
+ *     headers: {'Content-Type': 'application/json'},
+ *     body: JSON.stringify({jsonrpc: '2.0', id: 1, method: 'user.get', params: {id: 1}})
+ * })
+ * console.log(await response.json())
+ *
+ * //A WebSocket client, identified as client-1: the responses and the notifications arrive as messages
+ * const socket: WebSocket = new WebSocket('ws://localhost:3001/rpc?id=client-1')
+ * socket.on('open', (): void => socket.send(JSON.stringify({jsonrpc: '2.0', id: 2, method: 'user.get', params: {id: 2}})))
+ * socket.on('message', (data: WebSocket.RawData): void => console.log(JSON.parse(data.toString())))
+ * ```
+ */
+export function jsonRPCServiceEntrypoint(options = {}) {
+    const transport = options.transport ?? 'http';
+    const protocol = new JSONRPCProtocol(options);
+    const limit = options.limit ?? 10 * 1024 * 1024;
+    const path = (options.path ?? '/').replace(/(.)\/+$/, '$1');
+    let stopping = false;
+    let server;
+    let webSocketServer;
+    let stopReading;
+    let heartbeat;
+    //The connections of each client (WebSocket), the output of stdio
+    const clients = new Map();
+    const inProgress = new Set();
+    const addClient = (clientId, send) => {
+        if (!clients.has(clientId))
+            clients.set(clientId, new Set());
+        clients.get(clientId).add(send);
+        return () => {
+            clients.get(clientId)?.delete(send);
+            if (!clients.get(clientId)?.size)
+                clients.delete(clientId);
+        };
+    };
+    /**
+     * Answer a message
+     * @param runtime
+     * @param message
+     * @param dispatch
+     * @param send
+     */
+    const answer = (runtime, message, dispatch, send) => {
+        const handled = protocol.handle(message, { ...dispatch, runtime: runtime, transport: transport, stopping: () => stopping })
+            .then((response) => {
+            if (response)
+                send(JSON.stringify(response));
+        })
+            .catch(() => undefined);
+        inProgress.add(handled);
+        void handled.finally(() => inProgress.delete(handled));
+        return handled;
+    };
+    const listen = async (target) => {
+        await new Promise((resolve, reject) => {
+            target.once('error', reject).listen(options.port ?? 3000, options.host, () => {
+                target.off('error', reject);
+                resolve();
+            });
+        });
+        await options.listening?.(target);
+    };
+    return {
+        channel: 'service',
+        definition: ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            if (transport === 'stdio') {
+                const output = options.output ?? process.stdout;
+                const write = (message) => output.write(options.framing === 'content-length' ? `Content-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}` : `${message}\n`);
+                addClient('stdio', write);
+                const ended = () => {
+                    const mode = options.end ?? 'application';
+                    //The requests in progress answered first
+                    void Promise.allSettled([...inProgress]).then(async () => {
+                        if (typeof mode === 'function')
+                            return await mode();
+                        if (mode === 'application')
+                            applicationOf(runtime.module)?.exit(0);
+                    });
+                };
+                //A message over the limit: an Invalid Request error, without id (it is not read)
+                const oversized = () => write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: JSONRPCErrorCode.INVALID_REQUEST, message: `The message is larger than ${limit} bytes` } }));
+                stopReading = readMessages(options.input ?? process.stdin, options.framing ?? 'newline', limit, (message) => void answer(runtime, message, { clientId: 'stdio' }, write), ended, oversized);
+                return;
+            }
+            if (transport === 'http') {
+                server = createServer((request, response) => {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    if (request.method === 'OPTIONS')
+                        return void response.writeHead(204, CORS_HEADERS).end();
+                    if (request.method !== 'POST' || url.pathname !== path) {
+                        return void response.writeHead(404, { ...CORS_HEADERS, 'Content-Type': 'application/json' }).end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: `POST ${path} receives the requests of JSON-RPC 2.0` } }));
+                    }
+                    const aborted = new AbortController();
+                    response.once('close', () => {
+                        if (!response.writableFinished)
+                            aborted.abort();
+                    });
+                    readBody(request, limit).then((body) => {
+                        void answer(runtime, body, { clientId: clientIdOf(request), extra: { request: request }, signal: aborted.signal }, (message) => {
+                            response.writeHead(200, { ...CORS_HEADERS, 'Content-Type': 'application/json; charset=utf-8' }).end(message);
+                        }).then(() => {
+                            //Only notifications: no content
+                            if (!response.headersSent)
+                                response.writeHead(204, CORS_HEADERS).end();
+                        });
+                    }, (error) => {
+                        response.writeHead(error.status ?? 400, { ...CORS_HEADERS, 'Content-Type': 'application/json' }).end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: error.message } }));
+                    });
+                });
+                return await listen(server);
+            }
+            //WebSocket: the server of ws (an optional dependency)
+            let ws;
+            try {
+                ws = await import('ws');
+            }
+            catch {
+                throw new Error('The WebSocket transport of jsonRPCServiceEntrypoint needs the package ws (npm install ws)');
+            }
+            server = createServer((_request, response) => void response.writeHead(426, { 'Content-Type': 'text/plain' }).end('A WebSocket connection is expected'));
+            webSocketServer = new ws.WebSocketServer({ server: server, path: path, maxPayload: limit });
+            //Whether each connection answered the last ping
+            const alive = new WeakMap();
+            webSocketServer.on('connection', (socket, request) => {
+                const clientId = clientIdOf(request) ?? randomUUID();
+                const send = (message) => {
+                    if (socket.readyState === 1)
+                        socket.send(message);
+                };
+                const remove = addClient(clientId, send);
+                socket.on('message', (data, isBinary) => {
+                    if (isBinary)
+                        return;
+                    void answer(runtime, Buffer.isBuffer(data) ? data.toString('utf8') : Array.isArray(data) ? Buffer.concat(data).toString('utf8') : Buffer.from(data).toString('utf8'), { clientId: clientId, extra: { socket: socket, request: request } }, send);
+                });
+                socket.on('close', remove);
+                socket.on('error', () => undefined);
+                socket.on('pong', () => alive.set(socket, true));
+                alive.set(socket, true);
+            });
+            //The connections which do not answer the pings closed (the ones a proxy dropped)
+            const interval = options.heartbeat ?? 30000;
+            if (interval > 0) {
+                heartbeat = setInterval(() => webSocketServer?.clients.forEach((socket) => {
+                    if (!alive.get(socket))
+                        return socket.terminate();
+                    alive.set(socket, false);
+                    socket.ping();
+                }), interval);
+                heartbeat.unref();
+            }
+            await listen(server);
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+            stopReading?.();
+        },
+        close: async () => {
+            clearInterval(heartbeat);
+            await Promise.allSettled([...inProgress]);
+            clients.clear();
+            if (webSocketServer) {
+                webSocketServer.clients.forEach((socket) => socket.close(1001, 'The service stops'));
+                await new Promise((resolve) => webSocketServer.close(() => resolve()));
+            }
+            if (!server)
+                return;
+            const closing = new Promise((resolve) => void server.close(() => resolve()));
+            server.closeAllConnections();
+            await closing;
+        },
+        notify: (clientId, event, args) => {
+            const connections = clients.get(clientId);
+            connections?.forEach((send) => send(JSONRPCProtocol.notification(event, args)));
+            return !!connections?.size;
+        },
+        broadcast: (event, args) => {
+            clients.forEach((connections) => connections.forEach((send) => send(JSONRPCProtocol.notification(event, args))));
+            return clients.size;
+        }
+    };
+}