@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.d.ts

@@ -0,0 +1,117 @@
+import { type IncomingMessage, type Server } from 'node:http';
+import type { EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import { ServiceContext } from '../../context/ServiceContext.js';
+/**
+ * The options of {@link httpServiceEntrypoint}.
+ */
+export type HTTPServiceEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several service adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The port the server listens on; 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 the server listens on.
+     * @default all the interfaces
+     */
+    host?: string;
+    /**
+     * The path receiving the requests (POST). The event stream is served on `events` under it (`/api` → `/api/events`).
+     * @default '/'
+     */
+    path?: string;
+    /**
+     * The largest request body, in bytes; a larger one is answered with 413 and an error response.
+     * @default 10485760 (10 MiB)
+     */
+    limit?: number;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Run once the server listens, with the server (to read the port picked for port 0). A failure fails the entrypoint
+     * start.
+     */
+    listening?: (server: Server) => void | Promise<void>;
+};
+/**
+ * Get the HTTP request carrying a service action's request, when {@link httpServiceEntrypoint} serves it (to read its
+ * headers, its remote address…).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The Node.js HTTP request, or `undefined` when another adapter serves the request.
+ * @example
+ * ```typescript
+ * import {Controller, httpRequestOfContext, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class WhoAmIController extends Controller {
+ *     @ServiceAction({cmd: 'whoami'})
+ *     public async whoami(): Promise<string | undefined> {
+ *         return httpRequestOfContext(this.context as ServiceContext)?.socket.remoteAddress
+ *     }
+ * }
+ * ```
+ */
+export declare function httpRequestOfContext(context: ServiceContext): IncomingMessage | undefined;
+/**
+ * Create a service adapter of an entrypoint served over plain HTTP, handy to call the service actions from tools such
+ * as curl or Postman during development. It needs no optional dependency.
+ *
+ * A request is a `POST` to the path whose JSON body holds the action's pattern and input (`{"cmd": "echo", "text":
+ * "hi"}`). The response is always 200 with the body `{success, error, payload}` (see `ServiceResponseCodec`): `payload`
+ * is the result, or `error` the whole error object when the action failed (no matching action, validation…). A body that
+ * is not JSON or exceeds `limit` is answered with 400 and an error body; any other method or path with 404. The CORS
+ * headers allow any origin.
+ *
+ * The events pushed to the clients (`Entrypoint.notify`, `Entrypoint.broadcast`) are streamed as Server-Sent Events by
+ * `GET <path>/events`: each event's name is the SSE event, its arguments the JSON array of its data. A client gives its
+ * id in the `id` header or the `id` query parameter (at most 200 characters), the same on its requests so that they
+ * carry it as `ServiceContext.clientId`; without one, the stream assigns a random id, sent first as the `client` event.
+ * The streams receive a keep-alive comment every 15 seconds.
+ *
+ * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
+ * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
+ * streams are closed and the server shuts down.
+ * @param options The adapter options; by default it listens 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, httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'echo.service',
+ *     name: 'Echo',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: httpServiceEntrypoint({port: 3000, path: '/rpc'})
+ *         })
+ *     }
+ * })
+ *
+ * //A client: the response is {"success": true, "error": null, "payload": "hi"}
+ * const response: Response = await fetch('http://localhost:3000/rpc', {
+ *     method: 'POST',
+ *     headers: {'Content-Type': 'application/json', 'id': 'client-1'},
+ *     body: JSON.stringify({cmd: 'echo', text: 'hi'})
+ * })
+ * console.log(await response.json())
+ * //The events pushed to client-1: GET http://localhost:3000/rpc/events?id=client-1 (text/event-stream)
+ * ```
+ */
+export declare function httpServiceEntrypoint(options?: HTTPServiceEntrypointOptions): EntrypointAdapter<ServiceContext>;

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpRequestOfContext = httpRequestOfContext;
+exports.httpServiceEntrypoint = httpServiceEntrypoint;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const ServiceContext_js_1 = require("../../context/ServiceContext.js");
+const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
+const ServiceResponseCodec_js_1 = require("../../lib/ServiceResponseCodec.js");
+const EntrypointStoppedException_js_1 = require("../../exceptions/EntrypointStoppedException.js");
+/**
+ * Get the HTTP request carrying a service action's request, when {@link httpServiceEntrypoint} serves it (to read its
+ * headers, its remote address…).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The Node.js HTTP request, or `undefined` when another adapter serves the request.
+ * @example
+ * ```typescript
+ * import {Controller, httpRequestOfContext, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class WhoAmIController extends Controller {
+ *     @ServiceAction({cmd: 'whoami'})
+ *     public async whoami(): Promise<string | undefined> {
+ *         return httpRequestOfContext(this.context as ServiceContext)?.socket.remoteAddress
+ *     }
+ * }
+ * ```
+ */
+function httpRequestOfContext(context) {
+    return context.request;
+}
+/**
+ * The headers of the responses: the tools of the browsers may call the adapter (the development of the applications)
+ */
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, id'
+};
+/**
+ * The id of the client of a request: its header id, its query id
+ * @param request
+ * @param url
+ */
+function clientIdOf(request, url) {
+    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;
+}
+/**
+ * Write a response of JSON
+ * @param response
+ * @param status
+ * @param body
+ */
+function reply(response, status, body) {
+    if (response.headersSent || response.writableEnded)
+        return;
+    response.writeHead(status, { ...CORS_HEADERS, 'Content-Type': 'application/json; charset=utf-8' }).end(JSON.stringify(body));
+}
+/**
+ * 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`), { statusCode: 413 });
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Create a service adapter of an entrypoint served over plain HTTP, handy to call the service actions from tools such
+ * as curl or Postman during development. It needs no optional dependency.
+ *
+ * A request is a `POST` to the path whose JSON body holds the action's pattern and input (`{"cmd": "echo", "text":
+ * "hi"}`). The response is always 200 with the body `{success, error, payload}` (see `ServiceResponseCodec`): `payload`
+ * is the result, or `error` the whole error object when the action failed (no matching action, validation…). A body that
+ * is not JSON or exceeds `limit` is answered with 400 and an error body; any other method or path with 404. The CORS
+ * headers allow any origin.
+ *
+ * The events pushed to the clients (`Entrypoint.notify`, `Entrypoint.broadcast`) are streamed as Server-Sent Events by
+ * `GET <path>/events`: each event's name is the SSE event, its arguments the JSON array of its data. A client gives its
+ * id in the `id` header or the `id` query parameter (at most 200 characters), the same on its requests so that they
+ * carry it as `ServiceContext.clientId`; without one, the stream assigns a random id, sent first as the `client` event.
+ * The streams receive a keep-alive comment every 15 seconds.
+ *
+ * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
+ * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
+ * streams are closed and the server shuts down.
+ * @param options The adapter options; by default it listens 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, httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'echo.service',
+ *     name: 'Echo',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: httpServiceEntrypoint({port: 3000, path: '/rpc'})
+ *         })
+ *     }
+ * })
+ *
+ * //A client: the response is {"success": true, "error": null, "payload": "hi"}
+ * const response: Response = await fetch('http://localhost:3000/rpc', {
+ *     method: 'POST',
+ *     headers: {'Content-Type': 'application/json', 'id': 'client-1'},
+ *     body: JSON.stringify({cmd: 'echo', text: 'hi'})
+ * })
+ * console.log(await response.json())
+ * //The events pushed to client-1: GET http://localhost:3000/rpc/events?id=client-1 (text/event-stream)
+ * ```
+ */
+function httpServiceEntrypoint(options = {}) {
+    const base = (options.path ?? '/').replace(/\/+$/, '');
+    const requestPath = base || '/';
+    const eventsPath = `${base}/events`;
+    const limit = options.limit ?? 10 * 1024 * 1024;
+    let server;
+    let stopping = false;
+    let keepAlive;
+    //The event streams of each client (a client may listen several times)
+    const clients = new Map();
+    /**
+     * Write an event to a stream
+     * @param stream
+     * @param event
+     * @param args
+     */
+    const write = (stream, event, args) => {
+        stream.write(`event: ${event.replace(/[\r\n]+/g, ' ')}\ndata: ${JSON.stringify(args)}\n\n`);
+    };
+    /**
+     * Stream the events of a client
+     * @param request
+     * @param response
+     * @param url
+     */
+    const listen = (request, response, url) => {
+        const clientId = clientIdOf(request, url) ?? (0, node_crypto_1.randomUUID)();
+        response.writeHead(200, { ...CORS_HEADERS, 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
+        //Its id, given to the requests of the client (their header id)
+        write(response, 'client', [clientId]);
+        if (!clients.has(clientId))
+            clients.set(clientId, new Set());
+        clients.get(clientId).add(response);
+        request.once('close', () => {
+            clients.get(clientId)?.delete(response);
+            if (!clients.get(clientId)?.size)
+                clients.delete(clientId);
+        });
+    };
+    /**
+     * Answer a request of an action
+     * @param runtime
+     * @param request
+     * @param response
+     * @param url
+     */
+    const invoke = async (runtime, request, response, url) => {
+        if (stopping)
+            return reply(response, 200, ServiceResponseCodec_js_1.ServiceResponseCodec.encodeError(new EntrypointStoppedException_js_1.EntrypointStoppedException('The entrypoint is stopping')));
+        //Aborted when its client leaves before its response
+        const aborted = new AbortController();
+        response.once('close', () => {
+            if (!response.writableFinished)
+                aborted.abort();
+        });
+        let data;
+        try {
+            const body = await readBody(request, limit);
+            data = body ? JSON.parse(body) : {};
+        }
+        catch (error) {
+            //413 for a body larger than the limit, 400 for a body which is not JSON
+            return reply(response, error.statusCode ?? 400, ServiceResponseCodec_js_1.ServiceResponseCodec.encodeError(error instanceof SyntaxError ? new Error('The body of the request is not JSON') : error));
+        }
+        let result;
+        try {
+            const context = new ServiceContext_js_1.ServiceContext({ data: data && typeof data === 'object' ? data : {}, request: request, clientId: clientIdOf(request, url) });
+            result = ServiceResponseCodec_js_1.ServiceResponseCodec.encode(await runtime.dispatch(context, { signal: aborted.signal }), false);
+        }
+        catch (error) {
+            result = ServiceResponseCodec_js_1.ServiceResponseCodec.encodeError(error);
+        }
+        reply(response, 200, result);
+    };
+    return {
+        channel: 'service',
+        definition: BuiltinChannels_js_1.ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            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 === 'GET' && url.pathname === eventsPath)
+                    return listen(request, response, url);
+                if (request.method === 'POST' && url.pathname === requestPath)
+                    return void invoke(runtime, request, response, url);
+                reply(response, 404, { success: false, error: { message: `POST ${requestPath} invokes the actions, GET ${eventsPath} streams their events` }, payload: null });
+            });
+            //The event streams kept open by the proxies
+            keepAlive = setInterval(() => clients.forEach((streams) => streams.forEach((stream) => stream.write(': keep-alive\n\n'))), 15000);
+            keepAlive.unref();
+            await new Promise((resolve, reject) => {
+                server.once('error', reject).listen(options.port ?? 3000, options.host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            await options.listening?.(server);
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+        },
+        close: async () => {
+            clearInterval(keepAlive);
+            clients.forEach((streams) => streams.forEach((stream) => stream.end()));
+            clients.clear();
+            if (!server)
+                return;
+            const closing = new Promise((resolve) => void server.close(() => resolve()));
+            server.closeAllConnections();
+            await closing;
+        },
+        notify: (clientId, event, args) => {
+            const streams = clients.get(clientId);
+            streams?.forEach((stream) => write(stream, event, args));
+            return !!streams?.size;
+        },
+        broadcast: (event, args) => {
+            clients.forEach((streams) => streams.forEach((stream) => write(stream, event, args)));
+            return clients.size;
+        }
+    };
+}

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

@@ -0,0 +1,194 @@
+import type { ChannelRuntime } from '../../channel/EntrypointAdapter.js';
+import { ServiceContext } from '../../context/ServiceContext.js';
+/**
+ * The error codes of the JSON-RPC 2.0 responses sent by {@link jsonRPCServiceEntrypoint}.
+ */
+export declare const JSONRPCErrorCode: {
+    /**
+     * The message is not valid JSON.
+     */
+    readonly 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).
+     */
+    readonly INVALID_REQUEST: -32600;
+    /**
+     * No service action matches the request (`ControllerActionNotFoundException`).
+     */
+    readonly METHOD_NOT_FOUND: -32601;
+    /**
+     * The params are given by position without the `positionalParams` option, or fail the action's input validation
+     * (`InvalidValueException`).
+     */
+    readonly INVALID_PARAMS: -32602;
+    /**
+     * Reserved by the specification for the internal errors; the adapter does not send it.
+     */
+    readonly 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`.
+     */
+    readonly SERVER_ERROR: -32000;
+    /**
+     * The entrypoint is stopping and refuses the new requests (`EntrypointStoppedException`).
+     */
+    readonly STOPPING: -32001;
+};
+/**
+ * A JSON-RPC 2.0 request, as a client sends it. Without an `id`, it is a notification: the action runs but no response
+ * is sent.
+ */
+export type JSONRPCRequest = {
+    /**
+     * The protocol version, always `'2.0'`.
+     */
+    jsonrpc: '2.0';
+    /**
+     * The method, mapped to the service action's pattern (see `JSONRPCMappingOptions`).
+     */
+    method: string;
+    /**
+     * The params: by name (an object, merged into the action's input), or by position (an array, accepted only with the
+     * `positionalParams` option).
+     */
+    params?: Record<string, unknown> | unknown[];
+    /**
+     * The request id, echoed in its response; omitted for a notification.
+     */
+    id?: string | number | null;
+};
+/**
+ * A JSON-RPC 2.0 response, as the adapter sends it: either `result` or `error`.
+ */
+export type JSONRPCResponse = {
+    /**
+     * The protocol version, always `'2.0'`.
+     */
+    jsonrpc: '2.0';
+    /**
+     * The id of the request answered; `null` when it could not be read (a parse error, an invalid request).
+     */
+    id: string | number | null;
+    /**
+     * The action's result, `null` when it returned nothing.
+     */
+    result?: unknown;
+    /**
+     * The error: its code (see {@link JSONRPCErrorCode}), its message, and for an action's error the whole error object as
+     * `data`.
+     */
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+/**
+ * How {@link jsonRPCServiceEntrypoint} maps a JSON-RPC request to a service action's pattern and input.
+ */
+export type JSONRPCMappingOptions = {
+    /**
+     * The pattern field receiving the request's method: with `'method'`, `{"method": "user.get", "params": {"id": 1}}`
+     * is dispatched as `{method: 'user.get', id: 1}`, the action declared with `@ServiceAction({method: 'user.get'})`.
+     * @default 'method'
+     */
+    methodField?: string;
+    /**
+     * Build the pattern and the input of a request's action from its method and its params, replacing `methodField` and
+     * `positionalParams`. A thrown error answers the request with `INVALID_PARAMS`.
+     */
+    toPattern?: (method: string, params: Record<string, unknown> | unknown[] | undefined) => Record<string, unknown>;
+    /**
+     * The input field receiving the params given by position (an array): with `'args'`, `{"method": "sum", "params":
+     * [1, 2]}` is dispatched as `{method: 'sum', args: [1, 2]}`.
+     * @default none: the params by position are refused with `INVALID_PARAMS`
+     */
+    positionalParams?: string;
+};
+/**
+ * The JSON-RPC request behind a service action's request, as {@link jsonRPCRequestOfContext} returns it.
+ */
+export type JSONRPCRequestInfo = {
+    /**
+     * The request's method.
+     */
+    method: string;
+    /**
+     * The request's id; `undefined` for a notification (no response is sent).
+     */
+    id: string | number | null | undefined;
+    /**
+     * The transport the request came through.
+     */
+    transport: 'http' | 'websocket' | 'stdio';
+};
+/**
+ * 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 declare function jsonRPCRequestOfContext(context: ServiceContext): JSONRPCRequestInfo | undefined;
+/**
+ * The context of a dispatch of a request
+ */
+export type JSONRPCDispatch = {
+    runtime: ChannelRuntime<ServiceContext>;
+    transport: JSONRPCRequestInfo['transport'];
+    clientId?: string;
+    /**
+     * The properties added to the contexts (the request of HTTP, the socket)
+     */
+    extra?: Record<string, unknown>;
+    signal?: AbortSignal;
+    stopping: () => boolean;
+};
+/**
+ * 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 declare class JSONRPCProtocol {
+    protected readonly options: JSONRPCMappingOptions;
+    constructor(options?: JSONRPCMappingOptions);
+    /**
+     * The pattern and the input of the action of a request
+     * @param request
+     * @protected
+     */
+    protected pattern(request: JSONRPCRequest): Record<string, unknown>;
+    /**
+     * The response of a request (none for a notification)
+     * @param request
+     * @param dispatch
+     * @protected
+     */
+    protected one(request: unknown, dispatch: JSONRPCDispatch): Promise<JSONRPCResponse | undefined>;
+    /**
+     * The response of a message (a request, a batch): undefined when there is none (notifications)
+     * @param message its text
+     * @param dispatch
+     */
+    handle(message: string, dispatch: JSONRPCDispatch): Promise<JSONRPCResponse | JSONRPCResponse[] | undefined>;
+    /**
+     * A notification sent to a client (an event pushed)
+     * @param event
+     * @param args
+     */
+    static notification(event: string, args: unknown[]): string;
+}