@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/adapter/electron/ElectronIPCServiceEntrypoint.js

@@ -0,0 +1,249 @@
+"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.ipcEventOfContext = ipcEventOfContext;
+exports.electronIPCServiceEntrypoint = electronIPCServiceEntrypoint;
+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 IPC event of a service action's request, when {@link electronIPCServiceEntrypoint} serves it (to reach the
+ * invoking renderer or frame).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The IPC event (Electron's `IpcMainInvokeEvent`, typed as `Event`), or `undefined` when another adapter serves
+ * the request.
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ipcEventOfContext} from 'lakutata/adapter/electron'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import type {IpcMainInvokeEvent} from 'electron'
+ *
+ * class WindowController extends Controller {
+ *     //ipcRenderer.invoke('lakutata:service', {cmd: 'window.url'})
+ *     @ServiceAction({cmd: 'window.url'})
+ *     public async url(): Promise<string | undefined> {
+ *         return ipcEventOfContext<IpcMainInvokeEvent>(this.context as ServiceContext)?.sender.getURL()
+ *     }
+ * }
+ * ```
+ */
+function ipcEventOfContext(context) {
+    return context.event;
+}
+/**
+ * The ipcMain of the main process of Electron
+ */
+async function loadIPCMain() {
+    let ipcMain;
+    try {
+        //Electron is not a dependency: it is loaded where it runs
+        const electronModule = 'electron';
+        const electron = await Promise.resolve(`${electronModule}`).then(s => __importStar(require(s)));
+        ipcMain = electron.ipcMain ?? electron.default?.ipcMain;
+    }
+    catch {
+        ipcMain = undefined;
+    }
+    if (!ipcMain)
+        throw new Error('electronIPCServiceEntrypoint runs in the main process of Electron (or is given its ipcMain)');
+    return ipcMain;
+}
+/**
+ * Create a service adapter of an entrypoint served over Electron's IPC, in the main process. It needs the optional
+ * peer dependency `electron`: without the `ipcMain` option, the entrypoint fails to start outside Electron's main
+ * process.
+ *
+ * A renderer invokes the channel with the action's pattern and input, and optionally its client id:
+ * `ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId)`. The invocation resolves to
+ * `{success, error, payload}` (see `ServiceResponseCodec`): `payload` is the result, or `error` the whole error object
+ * when the action failed (no matching action, validation…).
+ *
+ * Each page is a client, identified by the id it gives (a non-empty string of at most 200 characters), which its
+ * requests carry as `ServiceContext.clientId`. A page registers by sending its id on `<channel>:subscribe` (or with
+ * any invocation giving it); a page reloaded in the same frame replaces its previous id. The events pushed by
+ * `Entrypoint.notify` and `Entrypoint.broadcast` are sent to the page's frame on `<channel>:event` with the event name
+ * and its arguments array. A destroyed renderer drops its clients.
+ *
+ * When a renderer is destroyed, its requests in progress are aborted (their abort signal fires). When the entrypoint
+ * stops, the new invocations resolve to an `EntrypointStoppedException` error; once the requests in progress end, the
+ * IPC handlers are removed.
+ * @param options The adapter options; by default it serves the channel `'lakutata:service'` on Electron's `ipcMain`.
+ * @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 {electronIPCServiceEntrypoint} from 'lakutata/adapter/electron'
+ * import type {IpcRenderer, IpcRendererEvent} from 'electron'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * //In the main process
+ * Application.run({
+ *     id: 'desktop.app',
+ *     name: 'Desktop',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: electronIPCServiceEntrypoint()
+ *         })
+ *     }
+ * })
+ *
+ * //In the preload script of a window
+ * declare const ipcRenderer: IpcRenderer
+ * const clientId: string = crypto.randomUUID()
+ * //The events pushed by entrypoint.notify(clientId, 'progress', 50)
+ * ipcRenderer.on('lakutata:service:event', (event: IpcRendererEvent, name: string, args: unknown[]): void => console.log(name, ...args))
+ * ipcRenderer.send('lakutata:service:subscribe', clientId)
+ * //{success: true, error: null, payload: 'hi'}
+ * console.log(await ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId))
+ * ```
+ */
+function electronIPCServiceEntrypoint(options = {}) {
+    const channel = options.channel ?? 'lakutata:service';
+    const eventChannel = `${channel}:event`;
+    const subscribeChannel = `${channel}:subscribe`;
+    let ipcMain;
+    let stopping = false;
+    //The clients by their ids, the renderers whose destruction removes their clients
+    const clients = new Map();
+    const watched = new WeakSet();
+    /**
+     * Register the client of a page, by the id it gives (the one of the page loaded: a page loaded again in the main
+     * frame of its window replaces its client); undefined without id
+     * @param event
+     * @param clientId
+     */
+    const register = (event, clientId) => {
+        if (typeof clientId !== 'string' || !clientId || clientId.length > 200)
+            return undefined;
+        if (clients.get(clientId)?.sender === event.sender)
+            return clientId;
+        const frame = event.processId !== undefined && event.frameId !== undefined ? [event.processId, event.frameId] : undefined;
+        const main = !event.senderFrame?.parent;
+        for (const [id, client] of clients) {
+            const sameFrame = !!frame && !!client.frame && client.frame[0] === frame[0] && client.frame[1] === frame[1];
+            if (client.sender === event.sender && (sameFrame || (main && client.main)))
+                clients.delete(id);
+        }
+        clients.set(clientId, { sender: event.sender, frame: frame, main: main });
+        if (!watched.has(event.sender)) {
+            watched.add(event.sender);
+            event.sender.once('destroyed', () => {
+                for (const [id, client] of clients)
+                    if (client.sender === event.sender)
+                        clients.delete(id);
+            });
+        }
+        return clientId;
+    };
+    /**
+     * Send an event to a client, in its frame
+     * @param clientId
+     * @param client
+     * @param event
+     * @param args
+     */
+    const send = (clientId, client, event, args) => {
+        if (client.sender.isDestroyed?.()) {
+            clients.delete(clientId);
+            return false;
+        }
+        if (client.frame && client.sender.sendToFrame)
+            client.sender.sendToFrame(client.frame, eventChannel, event, args);
+        else if (client.sender.send)
+            client.sender.send(eventChannel, event, args);
+        else
+            return false;
+        return true;
+    };
+    return {
+        channel: 'service',
+        definition: BuiltinChannels_js_1.ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            ipcMain = options.ipcMain ?? await loadIPCMain();
+            ipcMain.on?.(subscribeChannel, (event, clientId) => register(event, clientId));
+            ipcMain.handle(channel, async (event, data, clientId) => {
+                if (stopping)
+                    return ServiceResponseCodec_js_1.ServiceResponseCodec.encodeError(new EntrypointStoppedException_js_1.EntrypointStoppedException('The entrypoint is stopping'));
+                //The request is aborted when its renderer is destroyed
+                const request = new AbortController();
+                const abort = () => request.abort();
+                event.sender.once('destroyed', abort);
+                try {
+                    const context = new ServiceContext_js_1.ServiceContext({ data: data && typeof data === 'object' ? data : {}, event: event, clientId: register(event, clientId) });
+                    return ServiceResponseCodec_js_1.ServiceResponseCodec.encode(await runtime.dispatch(context, { signal: request.signal }), false);
+                }
+                catch (error) {
+                    return ServiceResponseCodec_js_1.ServiceResponseCodec.encodeError(error);
+                }
+                finally {
+                    (event.sender.off ?? event.sender.removeListener)?.call(event.sender, 'destroyed', abort);
+                }
+            });
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+        },
+        close: () => {
+            ipcMain?.removeHandler(channel);
+            ipcMain?.removeAllListeners?.(subscribeChannel);
+            clients.clear();
+        },
+        notify: (clientId, event, args) => {
+            const client = clients.get(clientId);
+            return !!client && send(clientId, client, event, args);
+        },
+        broadcast: (event, args) => {
+            let sent = 0;
+            for (const [clientId, client] of [...clients])
+                if (send(clientId, client, event, args))
+                    sent++;
+            return sent;
+        }
+    };
+}

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.d.ts

@@ -0,0 +1,172 @@
+import { type Express, type Request, type RequestHandler } from 'express';
+import { type Server, type ServerOptions } from 'node:http';
+import type { Module } from '@lakutata/core';
+import type { EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import { HTTPContext } from '../../context/HTTPContext.js';
+import { ExpressResponder } from './Responders.js';
+/**
+ * What the `before` hook of {@link expressHTTPEntrypoint} receives besides the express application: the entrypoint's
+ * module, the HTTP server (not listening yet) and the routes the actions will occupy.
+ */
+export type ExpressHookContext = {
+    /**
+     * The module owning the entrypoint, to get the application's objects from (`await module.getObject('db')`).
+     */
+    readonly module: Module;
+    /**
+     * The HTTP server serving the express application. It does not listen yet when the hook runs; attach other servers
+     * to it there (such as a socket.io server, see the `server` option of `socketIOServiceEntrypoint`).
+     */
+    readonly server: Server;
+    /**
+     * Each action route mapped to its HTTP methods, in lower case as declared (`'/users/:id'` → `{'get', 'delete'}`).
+     */
+    readonly routes: Map<string, Set<string>>;
+    /**
+     * The first segment of each action route (`'/device'`, `'/user'`…). A route starting with a parameter (`/:id`)
+     * adds none.
+     */
+    readonly actionPrefixes: string[];
+    /**
+     * Tell whether a request path belongs to the actions: it equals one of the action prefixes or starts with one
+     * followed by `/`.
+     */
+    readonly isActionPath: (requestPath: string) => boolean;
+};
+/**
+ * The options of {@link expressHTTPEntrypoint}.
+ */
+export type ExpressHTTPEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several HTTP 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 80
+     */
+    port?: number;
+    /**
+     * The host or address the server listens on.
+     * @default all the interfaces
+     */
+    host?: string;
+    /**
+     * The options of the Node.js HTTP server (`keepAliveTimeout`, `headersTimeout`, `requestTimeout`, in milliseconds…).
+     */
+    server?: ServerOptions & {
+        keepAliveTimeout?: number;
+        headersTimeout?: number;
+        requestTimeout?: number;
+    };
+    /**
+     * An existing express application to add the action routes to.
+     * @default a new express application
+     */
+    app?: Express;
+    /**
+     * The JSON and URL-encoded body parsers, with their size limit (bytes, or a text such as `'5mb'`); a larger body is
+     * answered with an error (413). `false` installs no parser, leaving the parsing to the application. The parsers are
+     * installed after the `before` hook, so the middlewares added there do not see a parsed body.
+     * @default {limit: '1mb'}
+     */
+    body?: false | {
+        limit?: string | number;
+    };
+    /**
+     * Build an action's input from a request. The route parameters are always merged over its result.
+     * @default the query parameters, then the properties of an object body over them
+     */
+    input?: (request: Request) => Record<string, unknown>;
+    /**
+     * How the results and the errors of the actions are written.
+     * @default JSONResponder
+     */
+    respond?: ExpressResponder;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Run before the action routes are added, to add the application's own express middlewares and routes (they take
+     * precedence over the actions). A failure fails the entrypoint start.
+     */
+    before?: (app: Express, context: ExpressHookContext) => void | Promise<void>;
+    /**
+     * The handler of the requests that match no action and whose path is outside the action prefixes, such as the pages
+     * of a web application (see {@link staticUI}). The unmatched requests inside the action prefixes, and all of them
+     * without a fallback, are answered with a `RouteNotFoundException` (404).
+     */
+    fallback?: RequestHandler;
+    /**
+     * Run when the adapter stops, after the server is closed.
+     */
+    stop?: () => void | Promise<void>;
+    /**
+     * The interval between the comments keeping the event streams (`EventsResult`) alive through the proxies, in
+     * milliseconds.
+     * @default 15000
+     */
+    heartbeat?: number;
+};
+/**
+ * Create the HTTP adapter of an entrypoint served by an express application: each HTTP action (`@GET`, `@POST`,
+ * `@HTTPAction`…) becomes an express route. It needs the optional peer dependency `express`.
+ *
+ * An action's input is the request's query and body (see the `input` option) with the route parameters merged over
+ * them. Its result is written by the responder (JSON by default, 204 for no result); a `StatusResult` sets the status
+ * and the headers, a `FileResult` sends a file, a buffer or a stream (304 when its ETag matches `If-None-Match`), and an
+ * `EventsResult` streams Server-Sent Events. An action that writes the response itself (through
+ * `HTTPContext.response`) is left alone. The errors are written by the responder with their status (400 for the
+ * validation failures, 500 by default).
+ *
+ * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
+ * entrypoint stops, the server stops accepting connections, the event streams end, and the requests in progress are
+ * given up to one second after they settle to send their responses before the remaining connections are closed.
+ * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
+ * application.
+ * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET, POST} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class UserController extends Controller {
+ *     //GET /users/1?verbose=true: the route parameter id merged over the query
+ *     @GET('/users/:id')
+ *     public async get(input: {id: string, verbose?: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ *
+ *     //POST /users with the JSON body {"name": "Ada"}
+ *     @POST('/users')
+ *     public async create(input: {name: string}): Promise<{name: string}> {
+ *         return {name: input.name}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 body: {limit: '5mb'},
+ *                 //The application's own routes, before the actions
+ *                 before: (app): void => {
+ *                     app.get('/health', (request, response): void => void response.send('ok'))
+ *                 },
+ *                 //The pages of the UI built in ./ui/dist, for the paths outside /users
+ *                 fallback: staticUI('./ui/dist')
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function expressHTTPEntrypoint(options?: ExpressHTTPEntrypointOptions): EntrypointAdapter<HTTPContext>;