@lakutata/entrypoint 3.0.0-beta.0

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

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONRPCProtocol = exports.JSONRPCErrorCode = void 0;
+exports.jsonRPCRequestOfContext = jsonRPCRequestOfContext;
+const core_1 = require("@lakutata/core");
+const ServiceContext_js_1 = require("../../context/ServiceContext.js");
+const ServiceResponseCodec_js_1 = require("../../lib/ServiceResponseCodec.js");
+const ControllerActionNotFoundException_js_1 = require("../../exceptions/ControllerActionNotFoundException.js");
+const EntrypointStoppedException_js_1 = require("../../exceptions/EntrypointStoppedException.js");
+/**
+ * The error codes of the JSON-RPC 2.0 responses sent by {@link jsonRPCServiceEntrypoint}.
+ */
+exports.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}`)
+ *     }
+ * }
+ * ```
+ */
+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_js_1.ControllerActionNotFoundException)
+        return exports.JSONRPCErrorCode.METHOD_NOT_FOUND;
+    if (error instanceof core_1.InvalidValueException)
+        return exports.JSONRPCErrorCode.INVALID_PARAMS;
+    if (error instanceof EntrypointStoppedException_js_1.EntrypointStoppedException)
+        return exports.JSONRPCErrorCode.STOPPING;
+    return exports.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
+ */
+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: exports.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, exports.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, exports.JSONRPCErrorCode.STOPPING, 'The entrypoint is stopping'));
+        let data;
+        try {
+            data = this.pattern(candidate);
+        }
+        catch (error) {
+            return respond(errorResponse(id, error.jsonrpcCode ?? exports.JSONRPCErrorCode.INVALID_PARAMS, error.message));
+        }
+        try {
+            const context = new ServiceContext_js_1.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_js_1.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_js_1.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, exports.JSONRPCErrorCode.PARSE_ERROR, 'The message is not JSON');
+        }
+        if (!Array.isArray(parsed))
+            return await this.one(parsed, dispatch);
+        if (!parsed.length)
+            return errorResponse(null, exports.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 });
+    }
+}
+exports.JSONRPCProtocol = JSONRPCProtocol;

package/dist/cjs/adapter/jsonrpc/JSONRPCServiceEntrypoint.d.ts

@@ -0,0 +1,154 @@
+import { type Server } from 'node:http';
+import type { Readable, Writable } from 'node:stream';
+import type { EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import type { ServiceContext } from '../../context/ServiceContext.js';
+import { type JSONRPCMappingOptions } from './JSONRPCProtocol.js';
+/**
+ * The options of {@link jsonRPCServiceEntrypoint}: its transport, and how the requests map to the service actions (see
+ * {@link JSONRPCMappingOptions}).
+ */
+export type JSONRPCServiceEntrypointOptions = JSONRPCMappingOptions & {
+    /**
+     * The adapter name, to tell apart several service adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The transport of the messages: `'http'` (a `POST` per message), `'websocket'` (a message per WebSocket text
+     * frame, with the events pushed; it needs the optional package `ws`), or `'stdio'` (the process's standard input
+     * and output, for a child process, with the events pushed).
+     * @default 'http'
+     */
+    transport?: 'http' | 'websocket' | 'stdio';
+    /**
+     * The port of the HTTP or WebSocket server; 0 picks a random free port. The entrypoint fails to start when the port
+     * is in use.
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * The host or address of the HTTP or WebSocket server.
+     * @default all the interfaces
+     */
+    host?: string;
+    /**
+     * The path receiving the requests (HTTP) or the connections (WebSocket).
+     * @default '/'
+     */
+    path?: string;
+    /**
+     * The largest message, in bytes. Over HTTP a larger body is answered with 413; over WebSocket the connection is
+     * closed by `ws`; over stdio a larger message is skipped (the rest of its line, or the length its header declares)
+     * and answered with an Invalid Request error without id (`-32600`).
+     * @default 10485760 (10 MiB)
+     */
+    limit?: number;
+    /**
+     * How the messages are delimited on stdio: `'newline'` (one JSON message per line), or `'content-length'` (each
+     * message after a `Content-Length` header and a blank line, as in the Language Server Protocol). The responses and
+     * the notifications are written the same way.
+     * @default 'newline'
+     */
+    framing?: 'newline' | 'content-length';
+    /**
+     * The stream the stdio transport reads.
+     * @default process.stdin
+     */
+    input?: Readable;
+    /**
+     * The stream the stdio transport writes.
+     * @default process.stdout
+     */
+    output?: Writable;
+    /**
+     * What happens when the stdio input ends (the parent process is gone): `'application'` exits the application with
+     * the code 0 once the requests in progress are answered, `'none'` does nothing, or a function run once they are
+     * answered.
+     * @default 'application'
+     */
+    end?: 'application' | 'none' | (() => void | Promise<void>);
+    /**
+     * The interval between the pings of the WebSocket connections, in milliseconds; 0 sends none. A connection that has
+     * not answered a ping by the next one is terminated.
+     * @default 30000
+     */
+    heartbeat?: number;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Run once the HTTP or WebSocket server listens, with the server (to read the port picked for port 0). A failure
+     * fails the entrypoint start. Not called with stdio.
+     */
+    listening?: (server: Server) => void | Promise<void>;
+};
+/**
+ * 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 declare function jsonRPCServiceEntrypoint(options?: JSONRPCServiceEntrypointOptions): EntrypointAdapter<ServiceContext>;