@lakutata/entrypoint 3.0.0-beta.0

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

@@ -0,0 +1,397 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonRPCServiceEntrypoint = jsonRPCServiceEntrypoint;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
+const JSONRPCProtocol_js_1 = require("./JSONRPCProtocol.js");
+const ApplicationOf_js_1 = require("../../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())))
+ * ```
+ */
+function jsonRPCServiceEntrypoint(options = {}) {
+    const transport = options.transport ?? 'http';
+    const protocol = new JSONRPCProtocol_js_1.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: BuiltinChannels_js_1.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')
+                            (0, ApplicationOf_js_1.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: JSONRPCProtocol_js_1.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 = (0, node_http_1.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 Promise.resolve().then(() => __importStar(require('ws')));
+            }
+            catch {
+                throw new Error('The WebSocket transport of jsonRPCServiceEntrypoint needs the package ws (npm install ws)');
+            }
+            server = (0, node_http_1.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) ?? (0, node_crypto_1.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_js_1.JSONRPCProtocol.notification(event, args)));
+            return !!connections?.size;
+        },
+        broadcast: (event, args) => {
+            clients.forEach((connections) => connections.forEach((send) => send(JSONRPCProtocol_js_1.JSONRPCProtocol.notification(event, args))));
+            return clients.size;
+        }
+    };
+}

package/dist/cjs/adapter/schedule/ScheduleEntrypoint.d.ts

@@ -0,0 +1,86 @@
+import type { ChannelActionInfo, EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import { ScheduleContext } from '../../context/ScheduleContext.js';
+/**
+ * The options of {@link scheduleEntrypoint}.
+ */
+export type ScheduleEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several schedule adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The middlewares of this adapter's runs, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Called when a run fails (the action, a middleware or the access control threw), with the error, the action and
+     * the run's context. A failed run does not stop the next ones.
+     * @default the error is written to the application's `log` component (`console.error` without one)
+     */
+    onError?: (error: unknown, action: ChannelActionInfo, context: ScheduleContext) => void | Promise<void>;
+    /**
+     * Called when a run is skipped, with the action, the time the run was due and why: `'overlap'` when the action's
+     * previous run is still in progress (an action without `overlap: true`), `'exclusive'` when another instance of the
+     * application holds the run's lock (an `exclusive` action). An error it throws is written to the application's
+     * `log` component; the schedule goes on.
+     */
+    onSkip?: (action: ChannelActionInfo, scheduledAt: Date, reason: 'overlap' | 'exclusive') => void;
+};
+/**
+ * Create the schedule adapter of an entrypoint: it runs the controller actions declared with `@Schedule`, which never
+ * run without it. It needs no optional dependency.
+ *
+ * The runs begin once the application has launched (all its objects, its bootstrap and the other adapters are ready).
+ * Each run is dispatched like a request: a new controller in its own scope, the middlewares and the access control, a
+ * {@link ScheduleContext} giving the schedule, the time the run was due and its number. An interval keeps its pace:
+ * the runs missed while the process was suspended are skipped, not caught up. An action whose previous run is still in
+ * progress skips its run unless it allows `overlap`.
+ *
+ * An `exclusive` action runs in one instance of the application at a time: each run first tries to acquire a lock
+ * named `schedule:<key>` (the `key` of its `exclusive` option, the action name by default) from the mutex component
+ * (the `Mutex` of `lakutata/com/mutex`, named `mutex` by default), and is skipped when another
+ * instance holds it; the lock is kept after the run for half of its period (30 seconds at most) so that the instances
+ * whose clocks are late skip it too. An exclusive action whose mutex component cannot be resolved never runs (the
+ * error is logged).
+ *
+ * When the entrypoint stops, no new run starts, the kept locks are released and the entrypoint waits for the runs in
+ * progress (aborting them after its `shutdownTimeout`).
+ * @param options The adapter options.
+ * @returns The adapter, to give to the `schedule` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller, ScheduleContext, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+ * import {Schedule} from 'lakutata/decorator/ctrl'
+ *
+ * class MaintenanceController extends Controller {
+ *     //Every 5 minutes, and once the application launched
+ *     @Schedule({every: '5m', immediate: true})
+ *     public async purge(): Promise<void> {
+ *         const context: ScheduleContext = this.context as ScheduleContext
+ *         console.log(`Run ${context.run}, due at ${context.scheduledAt.toISOString()}`)
+ *     }
+ *
+ *     //Every day at 03:00 in Shanghai
+ *     @Schedule({cron: '0 3 * * *', timezone: 'Asia/Shanghai'})
+ *     public async report(): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'worker.app',
+ *     name: 'Worker',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [MaintenanceController],
+ *             schedule: scheduleEntrypoint({
+ *                 onError: (error, action): void => console.error(`${action.name} failed`, error),
+ *                 onSkip: (action, scheduledAt, reason): void => console.warn(`${action.name} skipped (${reason})`)
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function scheduleEntrypoint(options?: ScheduleEntrypointOptions): EntrypointAdapter<ScheduleContext>;