@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/Entrypoint.js

@@ -0,0 +1,998 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Entrypoint = exports.buildEntrypoints = exports.buildServiceEntrypoint = exports.buildHTTPEntrypoint = exports.buildCLIEntrypoint = exports.ScheduleContext = exports.ServiceContext = exports.HTTPContext = exports.CLIContext = exports.BaseContext = exports.ContextType = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const ControllerEntrypoint_js_1 = require("./lib/ControllerEntrypoint.js");
+const Controller_js_1 = require("./lib/Controller.js");
+const utils_1 = require("@lakutata/utils");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const DuplicateActionNameException_js_1 = require("./exceptions/DuplicateActionNameException.js");
+const AccessControl_js_1 = require("./lib/AccessControl.js");
+const AccessControlRule_js_1 = require("./lib/AccessControlRule.js");
+const InvalidActionGroupException_js_1 = require("./exceptions/InvalidActionGroupException.js");
+const Middleware_js_1 = require("./lib/Middleware.js");
+const Channel_js_1 = require("./channel/Channel.js");
+const EntrypointAdapter_js_1 = require("./channel/EntrypointAdapter.js");
+const InvalidEntrypointAdapterException_js_1 = require("./exceptions/InvalidEntrypointAdapterException.js");
+const EntrypointStoppedException_js_1 = require("./exceptions/EntrypointStoppedException.js");
+require("./channel/BuiltinChannels.js");
+var BaseContext_js_1 = require("./context/BaseContext.js");
+Object.defineProperty(exports, "ContextType", { enumerable: true, get: function () { return BaseContext_js_1.ContextType; } });
+Object.defineProperty(exports, "BaseContext", { enumerable: true, get: function () { return BaseContext_js_1.BaseContext; } });
+var CLIContext_js_1 = require("./context/CLIContext.js");
+Object.defineProperty(exports, "CLIContext", { enumerable: true, get: function () { return CLIContext_js_1.CLIContext; } });
+var HTTPContext_js_1 = require("./context/HTTPContext.js");
+Object.defineProperty(exports, "HTTPContext", { enumerable: true, get: function () { return HTTPContext_js_1.HTTPContext; } });
+var ServiceContext_js_1 = require("./context/ServiceContext.js");
+Object.defineProperty(exports, "ServiceContext", { enumerable: true, get: function () { return ServiceContext_js_1.ServiceContext; } });
+var ScheduleContext_js_1 = require("./context/ScheduleContext.js");
+Object.defineProperty(exports, "ScheduleContext", { enumerable: true, get: function () { return ScheduleContext_js_1.ScheduleContext; } });
+/**
+ * Type a CLI entrypoint in the style of lakutata 2.x; the function is returned as it is.
+ * @param entrypoint The function the entrypoint calls when it starts, with the module, the commands, the request
+ * handler and the destroyer registrar.
+ * @returns The same function, to give to the `cli` option of {@link buildEntrypoints}.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCLIEntrypoint, buildEntrypoints, CLIContext, Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction} from 'lakutata/decorator/ctrl'
+ *
+ * class VersionController extends Controller {
+ *     @CLIAction('version')
+ *     public async version(): Promise<string> {
+ *         return '1.0.0'
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'tool.app',
+ *     name: 'Tool',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [VersionController],
+ *             //Run the command given as the first argument once the entrypoint starts
+ *             cli: buildCLIEntrypoint(async (module, cliMap, handler): Promise<void> => {
+ *                 const command: string = process.argv[2] ?? 'version'
+ *                 if (cliMap.has(command)) console.log(await handler(new CLIContext({command: command, data: {}})))
+ *             })
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+const buildCLIEntrypoint = (entrypoint) => entrypoint;
+exports.buildCLIEntrypoint = buildCLIEntrypoint;
+/**
+ * Type an HTTP entrypoint in the style of lakutata 2.x; the function is returned as it is.
+ * @param entrypoint The function the entrypoint calls when it starts, with the module, the routes, the request handler
+ * and the destroyer registrar.
+ * @returns The same function, to give to the `http` option of {@link buildEntrypoints}.
+ * @example
+ * ```typescript
+ * import {createServer, type Server} from 'node:http'
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, buildHTTPEntrypoint, Controller, HTTPContext} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class HealthController extends Controller {
+ *     @GET('/health')
+ *     public async health(): Promise<{status: string}> {
+ *         return {status: 'ok'}
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'api.app',
+ *     name: 'API',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [HealthController],
+ *             http: buildHTTPEntrypoint((module, routeMap, handler, registerDestroy): void => {
+ *                 const server: Server = createServer(async (request, response): Promise<void> => {
+ *                     const route: string = (request.url ?? '/').split('?')[0]
+ *                     const method: string = request.method ?? 'GET'
+ *                     if (!routeMap.get(route)?.has(method)) {
+ *                         response.writeHead(404).end()
+ *                         return
+ *                     }
+ *                     const abortController: AbortController = new AbortController()
+ *                     response.on('close', (): void => abortController.abort())
+ *                     try {
+ *                         const context: HTTPContext = new HTTPContext({route, method, request, response, data: {}})
+ *                         response.end(JSON.stringify(await handler(context, abortController)))
+ *                     } catch (error) {
+ *                         response.writeHead(500).end((error as Error).message)
+ *                     }
+ *                 }).listen(3000)
+ *                 registerDestroy((): Promise<void> => new Promise((resolve): void => void server.close((): void => resolve())))
+ *             })
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+const buildHTTPEntrypoint = (entrypoint) => entrypoint;
+exports.buildHTTPEntrypoint = buildHTTPEntrypoint;
+/**
+ * Type a service entrypoint in the style of lakutata 2.x; the function is returned as it is.
+ * @param entrypoint The function the entrypoint calls when it starts, with the module, the request handler and the
+ * destroyer registrar.
+ * @returns The same function, to give to the `service` option of {@link buildEntrypoints}.
+ * @example
+ * ```typescript
+ * import {EventEmitter} from 'node:events'
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, buildServiceEntrypoint, Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * declare const bus: EventEmitter
+ *
+ * class MathController extends Controller {
+ *     @ServiceAction({ctrl: 'math', act: 'add'})
+ *     public async add(input: {a: number, b: number}): Promise<number> {
+ *         return input.a + input.b
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'math.app',
+ *     name: 'Math',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [MathController],
+ *             //Each message of the bus is a request: its data matched against the patterns of the actions
+ *             service: buildServiceEntrypoint((module, handler, registerDestroy): void => {
+ *                 const listener = async (data: Record<string, any>, reply: (result: unknown) => void): Promise<void> => {
+ *                     reply(await handler(new ServiceContext({data: data})))
+ *                 }
+ *                 bus.on('request', listener)
+ *                 registerDestroy((): void => void bus.off('request', listener))
+ *             })
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+const buildServiceEntrypoint = (entrypoint) => entrypoint;
+exports.buildServiceEntrypoint = buildServiceEntrypoint;
+/**
+ * Type the options of the {@link Entrypoint} component; they are returned as they are. The applications of the
+ * `lakutata` package declare the entrypoint as the component `entrypoint`: give these options to it.
+ * @param options The controllers, middlewares, access rules and the adapters of each channel.
+ * @returns The same options, to declare as the `entrypoint` component.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+ * import {GET, POST, Schedule} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ *
+ * class CreateOrderDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public product: string
+ * }
+ *
+ * class OrderController extends Controller {
+ *     @GET('/orders', {name: 'listOrders', groups: ['orders']})
+ *     public async list(): Promise<string[]> {
+ *         return []
+ *     }
+ *
+ *     @POST('/orders', CreateOrderDTO, {name: 'createOrder', groups: ['orders']})
+ *     public async create(input: CreateOrderDTO): Promise<{product: string}> {
+ *         return {product: input.product}
+ *     }
+ *
+ *     @Schedule('0 * * * *')
+ *     public async purge(): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'shop.app',
+ *     name: 'Shop',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [OrderController],
+ *             httpActionGroups: {orders: 'Orders'},
+ *             shutdownTimeout: 10000,
+ *             http: expressHTTPEntrypoint({port: 3000}),
+ *             schedule: scheduleEntrypoint()
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+const buildEntrypoints = (options) => options;
+exports.buildEntrypoints = buildEntrypoints;
+/**
+ * The promises of the requests in progress (a request is in progress before its promise is created)
+ * @param requests
+ */
+function promises(requests) {
+    return [...requests].map((request) => request.promise).filter((promise) => !!promise);
+}
+//The settlement of an aborted request
+const ABORTED = Symbol('ABORTED');
+//The options of the entrypoint which are not adapters
+const ENTRYPOINT_OPTIONS = new Set(['class', 'id', 'controllers', 'middlewares', 'rules', 'shutdownTimeout', 'cliActionGroups', 'httpActionGroups', 'serviceActionGroups']);
+//The channels accepting the callbacks of 2.x
+const LEGACY_CHANNELS = new Set(['cli', 'http', 'service']);
+/**
+ * The entrypoint component: it serves the controllers' actions to the requests of every channel (HTTP, CLI, service,
+ * schedule, and the channels of other packages), each received by the adapters configured for its channel.
+ *
+ * The applications of the `lakutata` package declare it as the component `entrypoint`: configure it with
+ * {@link buildEntrypoints}. When it initializes, it registers the controllers and checks their actions (their groups and
+ * the uniqueness of their names); then, in its startup, it starts the adapters in order (the objects their hooks get may
+ * inject the entrypoint; the objects getting the entrypoint wait for its adapters); it is ready (the adapters acting on
+ * their own, such as the schedules, begin) once the application has launched. Each request runs in a scope of its own: its middlewares,
+ * then a new controller instance receiving its context and signal, the validation of its input, the access control
+ * and the action; the scope is destroyed when the request ends.
+ *
+ * When it is destroyed, it stops the adapters in reverse order: each stops receiving requests, the requests in progress
+ * get `shutdownTimeout` milliseconds to complete and are then aborted (failing with an `EntrypointStoppedException`),
+ * and the adapter is closed.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {buildEntrypoints, Controller, Entrypoint, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {GET, ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ *
+ * class ChatController extends Controller {
+ *     @Inject('entrypoint')
+ *     protected readonly entrypoint: Entrypoint
+ *
+ *     //Served over HTTP: GET /rooms
+ *     @GET('/rooms')
+ *     public async rooms(): Promise<string[]> {
+ *         return ['general']
+ *     }
+ *
+ *     //Served over Socket.IO, the message pushed to every client
+ *     @ServiceAction({act: 'say'})
+ *     public async say(input: {text: string}): Promise<number> {
+ *         const from: string | undefined = (this.context as ServiceContext).clientId
+ *         return this.entrypoint.broadcast('message', from, input.text)
+ *     }
+ * }
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'chat.app',
+ *         name: 'Chat',
+ *         components: {
+ *             entrypoint: buildEntrypoints({
+ *                 controllers: [ChatController],
+ *                 http: expressHTTPEntrypoint({port: 3000}),
+ *                 service: socketIOServiceEntrypoint({port: 3001})
+ *             })
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const entrypoint: Entrypoint = await app.getObject<Entrypoint>('entrypoint')
+ *         console.log(entrypoint.getHttpActions().actions.map(action => action.route)) //['/rooms']
+ *     })
+ * ```
+ */
+let Entrypoint = class Entrypoint extends core_1.Component {
+    constructor() {
+        super(...arguments);
+        /**
+         * The class running the access control of the actions declared with `acl: true` or a `rule`; a subclass of the
+         * entrypoint may replace it with a subclass of {@link AccessControl}.
+         * @protected
+         */
+        this.accessControl = AccessControl_js_1.AccessControl;
+        this.#channels = new Map();
+        this.#started = [];
+        this.#resolveReady = () => undefined;
+        /**
+         * Resolved once the adapters started and the application launched
+         */
+        this.#ready = new Promise((resolve) => {
+            this.#resolveReady = resolve;
+        });
+        /**
+         * The adapters to start, once the entrypoint is initialized
+         */
+        this.#adapters = [];
+    }
+    /**
+     * Whether an option which is not a configurable property is accepted: the adapters given under a channel's key,
+     * and the 2.x entrypoint functions under `cli`, `http` and `service`. The container calls it when it checks the
+     * component's options.
+     * @param name The option's key.
+     * @param value The option's value: one item or an array.
+     * @returns `true` when every item is an adapter, or a function under a 2.x channel's key.
+     */
+    static acceptsOption(name, value) {
+        const items = Array.isArray(value) ? value : [value];
+        return items.every((item) => (0, EntrypointAdapter_js_1.isEntrypointAdapter)(item) || (typeof item === 'function' && LEGACY_CHANNELS.has(name)));
+    }
+    #channels;
+    #started;
+    #stopping;
+    #resolveReady;
+    /**
+     * Resolved once the adapters started and the application launched
+     */
+    #ready;
+    /**
+     * The adapters to start, once the entrypoint is initialized
+     */
+    #adapters;
+    /**
+     * Register the controllers and the middleware classes and check the actions: once initialized, the entrypoint can be
+     * got by the other objects (its actions listed by `getHttpActions()`…), the adapters start in {@link startup}.
+     * @throws {InvalidMiddlewareException} When a middleware is neither a function nor a {@link Middleware} subclass.
+     * @throws {InvalidEntrypointAdapterException} When an option is neither an entrypoint option nor an adapter of its
+     * channel.
+     * @throws {InvalidActionGroupException} When an action is in a group missing from its channel's action groups.
+     * @throws {DuplicateActionNameException} When two actions of a channel have the same name.
+     * @protected
+     */
+    async init() {
+        (0, Middleware_js_1.validateMiddlewares)(this.middlewares);
+        const adapters = this.#adapters = this.configuredAdapters();
+        await Promise.all(this.controllers.map((controllerConstructor) => {
+            (0, ControllerEntrypoint_js_1.bindControllerToComponent)(this, controllerConstructor);
+            return this.container.register(controllerConstructor);
+        }));
+        (0, ControllerEntrypoint_js_1.getComponentControllerActionMap)(this).forEach((actions, channel) => this.#channels.set(channel, this.createChannelState((0, Channel_js_1.getChannel)(channel), actions)));
+        this.checkActions('CLI', this.#channels.get('cli')?.infos, this.cliActionGroups, 'cliActionGroups');
+        this.checkActions('HTTP', this.#channels.get('http')?.infos, this.httpActionGroups, 'httpActionGroups');
+        this.checkActions('Service', this.#channels.get('service')?.infos, this.serviceActionGroups, 'serviceActionGroups');
+        for (const [name, state] of this.#channels)
+            if (!LEGACY_CHANNELS.has(name))
+                this.checkActions(name, state.infos);
+        //The middleware classes are created in the container of each request
+        const middlewareClasses = new Set();
+        const addMiddlewareClasses = (middlewares) => middlewares.filter(Middleware_js_1.isMiddlewareClass).forEach((middlewareClass) => middlewareClasses.add(middlewareClass));
+        addMiddlewareClasses(this.middlewares);
+        this.#channels.forEach((state) => state.entries.forEach((entry) => addMiddlewareClasses(entry.middlewares)));
+        adapters.forEach((adapter) => addMiddlewareClasses((0, Middleware_js_1.validateMiddlewares)(adapter.middlewares ?? [])));
+        await Promise.all([...middlewareClasses].map((middlewareClass) => this.container.register(middlewareClass)));
+    }
+    /**
+     * Start the adapters in order, once the entrypoint is initialized: the objects their hooks get (an authenticator of
+     * the requests adding its middleware to an HTTP server) may inject the entrypoint. The objects getting the
+     * entrypoint wait for the adapters, and fail when one fails to start (a port in use).
+     * @protected
+     */
+    async startup() {
+        for (const adapter of this.#adapters)
+            await this.startAdapter(adapter);
+    }
+    /**
+     * Mark the entrypoint ready: the application has launched (in a bare container, once its adapters started).
+     * @protected
+     */
+    async launched() {
+        this.#resolveReady();
+    }
+    /**
+     * Stop the adapters, before the scopes of the requests in progress and the controllers are destroyed (see
+     * {@link Entrypoint.stopAdapters}).
+     * @protected
+     */
+    async beforeDestroy() {
+        await this.stopAdapters();
+    }
+    /**
+     * Stop the adapters in reverse order, once (a second call returns the same promise): each adapter stops receiving
+     * requests, its requests in progress get `shutdownTimeout` milliseconds before they are aborted, then it is closed.
+     * Every adapter is stopped even when another fails.
+     * @returns Resolves once every adapter is closed.
+     * @throws {AggregateError} When several adapters failed to stop or close; a single failure is thrown as it is.
+     * @protected
+     */
+    stopAdapters() {
+        this.#stopping ??= (async () => {
+            const errors = [];
+            for (const started of [...this.#started].reverse()) {
+                try {
+                    await started.adapter.stop?.();
+                }
+                catch (e) {
+                    errors.push(e);
+                }
+                await this.drain(started);
+                try {
+                    await started.adapter.close?.();
+                }
+                catch (e) {
+                    errors.push(e);
+                }
+            }
+            this.#started = [];
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length)
+                throw new AggregateError(errors, 'Failed to stop the entrypoint adapters');
+        })();
+        return this.#stopping;
+    }
+    /**
+     * The adapters of the options: every option which is not an entrypoint option is a channel's key; a 2.x entrypoint
+     * function is wrapped in an adapter, the channel of an adapter carrying its definition is defined.
+     * @returns The adapters, in the order of the options.
+     * @throws {InvalidEntrypointAdapterException} When an adapter is given under another channel's key, its channel is
+     * not defined, or the option is neither an adapter nor a 2.x function of `cli`, `http` or `service`.
+     * @protected
+     */
+    configuredAdapters() {
+        const records = this.getConfigurableRecords();
+        const adapters = [];
+        for (const [key, value] of Object.entries(records)) {
+            if (ENTRYPOINT_OPTIONS.has(key) || value === undefined || value === null)
+                continue;
+            for (const item of Array.isArray(value) ? value : [value]) {
+                if (typeof item === 'function' && LEGACY_CHANNELS.has(key)) {
+                    adapters.push(this.legacyAdapter(key, item));
+                }
+                else if ((0, EntrypointAdapter_js_1.isEntrypointAdapter)(item)) {
+                    if (item.channel !== key)
+                        throw new InvalidEntrypointAdapterException_js_1.InvalidEntrypointAdapterException('The option "{key}" is given an adapter of the channel "{channel}"', { key: key, channel: item.channel });
+                    if (item.definition)
+                        (0, Channel_js_1.defineChannel)(item.definition);
+                    if (!(0, Channel_js_1.hasChannel)(key))
+                        throw new InvalidEntrypointAdapterException_js_1.InvalidEntrypointAdapterException('The channel "{key}" of an adapter is not defined', { key: key });
+                    adapters.push(item);
+                }
+                else {
+                    throw new InvalidEntrypointAdapterException_js_1.InvalidEntrypointAdapterException('The option "{key}" is not an entrypoint option nor an adapter', { key: key });
+                }
+            }
+        }
+        return adapters;
+    }
+    /**
+     * Wrap a 2.x entrypoint function in an adapter: it is called when the adapter starts, in the entrypoint's
+     * {@link startup} (the entrypoint initialized: the objects it gets may inject the entrypoint, as in 2.x), and the
+     * promise of an asynchronous builder is awaited — its failure fails the entrypoint's startup, so the application's
+     * launch (2.x did not await it: the application launched without its server, the failure an unhandled rejection).
+     * Its registered destroyers run when the adapter stops.
+     * @param channel The channel: `cli`, `http` or `service`.
+     * @param callback The {@link CLIEntrypoint}, {@link HTTPEntrypoint} or {@link ServiceEntrypoint}.
+     * @returns The adapter.
+     * @protected
+     */
+    legacyAdapter(channel, callback) {
+        const destroyers = [];
+        const registerDestroy = (destroyer) => destroyers.push(destroyer);
+        return {
+            channel: channel,
+            start: async (runtime) => {
+                const handler = (context, abortController) => runtime.dispatch(context, { signal: abortController?.signal });
+                const run = () => {
+                    switch (channel) {
+                        case 'http': {
+                            const routeMap = new Map();
+                            for (const action of runtime.actions) {
+                                const methods = routeMap.get(action.address.route) ?? new Set();
+                                routeMap.set(action.address.route, methods.add(action.address.method));
+                            }
+                            return callback(runtime.module, routeMap, handler, registerDestroy);
+                        }
+                        case 'cli':
+                            return callback(runtime.module, (0, EntrypointAdapter_js_1.commandMap)(runtime.actions), handler, registerDestroy);
+                        default:
+                            return callback(runtime.module, handler, registerDestroy);
+                    }
+                };
+                await run();
+            },
+            stop: async () => {
+                await Promise.all(destroyers.map((destroyer) => Promise.resolve(destroyer())));
+            }
+        };
+    }
+    /**
+     * Collect the actions of a channel: their descriptions, their middlewares and the channel's lookup.
+     * @param definition The channel.
+     * @param actions The actions bound to the entrypoint for the channel, by address.
+     * @returns The channel's state.
+     * @protected
+     */
+    createChannelState(definition, actions) {
+        const entries = [];
+        const infos = new Map();
+        actions.forEach((details) => {
+            const info = {
+                id: details.id,
+                acl: details.acl,
+                name: details.name,
+                description: details.description,
+                groups: details.groups,
+                controller: details.constructor.className,
+                method: details.method.toString(),
+                jsonSchema: details.jsonSchema,
+                ...definition.describe(details.pattern)
+            };
+            infos.set(details.id, info);
+            entries.push({
+                details: details,
+                info: info,
+                address: { ...info, address: details.pattern, dto: details.dtoConstructor, returnSchema: (0, dto_1.getMethodReturnSchema)(details.constructor.prototype, (0, utils_1.As)(details.method)) },
+                middlewares: [
+                    ...(0, Middleware_js_1.getClassMiddlewares)(details.constructor),
+                    ...details.middlewares,
+                    ...(0, Middleware_js_1.getMethodMiddlewares)(details.constructor, (0, utils_1.As)(details.method))
+                ]
+            });
+        });
+        return { definition: definition, entries: entries, infos: infos, matcher: definition.createMatcher(entries) };
+    }
+    /**
+     * Check a channel's actions: their groups are defined (when the channel has action groups) and their names unique.
+     * @param type The channel's name used in the error messages (`HTTP`, `CLI`…).
+     * @param actionInfoMap The channel's action descriptions by id; nothing is checked when it is `undefined`.
+     * @param actionGroups The channel's action groups; the groups are not checked without them.
+     * @param option The option holding the action groups, named in the error message.
+     * @throws {InvalidActionGroupException} When an action is in a group missing from `actionGroups`.
+     * @throws {DuplicateActionNameException} When two actions have the same name.
+     * @protected
+     */
+    checkActions(type, actionInfoMap, actionGroups, option) {
+        if (!actionInfoMap)
+            return;
+        if (actionGroups) {
+            const invalidGroupIds = this.findInvalidActionGroupIds(actionInfoMap, actionGroups);
+            if (invalidGroupIds.length)
+                throw new InvalidActionGroupException_js_1.InvalidActionGroupException('Found {type} action groups are not defined in {option}: {groupIds}', {
+                    type: type,
+                    option: option,
+                    groupIds: invalidGroupIds
+                });
+        }
+        const duplicateNames = this.findDuplicateActionNames(actionInfoMap);
+        if (duplicateNames.length)
+            throw new DuplicateActionNameException_js_1.DuplicateActionNameException('Duplicate {type} action names found: {names}', {
+                type: type,
+                names: duplicateNames
+            });
+    }
+    /**
+     * Start an adapter, giving it the runtime of its channel (its actions and the dispatch functions).
+     * @param adapter The adapter.
+     * @throws {InvalidChannelException} When the adapter's channel is not defined.
+     * @protected
+     */
+    async startAdapter(adapter) {
+        const definition = (0, Channel_js_1.getChannel)(adapter.channel);
+        let state = this.#channels.get(definition.name);
+        if (!state) {
+            state = this.createChannelState(definition, new Map());
+            this.#channels.set(definition.name, state);
+        }
+        const started = { adapter: adapter, inflight: new Set() };
+        const channelState = state;
+        const runners = new Map();
+        const outerMiddlewares = [...this.middlewares, ...(adapter.middlewares ?? [])];
+        const runnerOf = (entry) => {
+            let runner = runners.get(entry);
+            if (!runner) {
+                runner = (0, Middleware_js_1.composeMiddlewares)([...outerMiddlewares, ...entry.middlewares], (invocation) => this.runAction(entry.details, invocation));
+                runners.set(entry, runner);
+            }
+            return runner;
+        };
+        const entriesByAddress = new Map(channelState.entries.map((entry) => [entry.address, entry]));
+        const runtime = {
+            channel: definition,
+            module: this.getModule(),
+            actions: channelState.entries.map((entry) => entry.address),
+            ready: this.#ready,
+            controllers: [...this.controllers],
+            getObject: (target) => this.getObject(target),
+            dispatch: async (context, options = {}) => {
+                const match = channelState.matcher.match(context);
+                if (!match)
+                    throw definition.notFound(context);
+                const entry = (0, utils_1.As)(match.entry);
+                definition.prepare?.(entry, context);
+                return this.dispatch(started, entry, runnerOf(entry), context, { ...options, params: { ...match.params, ...options.params } });
+            },
+            dispatchTo: async (action, context, options = {}) => {
+                const entry = entriesByAddress.get(action);
+                if (!entry)
+                    throw definition.notFound(context);
+                return this.dispatch(started, entry, runnerOf(entry), context, options);
+            }
+        };
+        await adapter.start(runtime);
+        this.#started.push(started);
+    }
+    /**
+     * Wait for a stopped adapter's requests in progress; abort the ones still running after `shutdownTimeout`
+     * milliseconds with an {@link EntrypointStoppedException}.
+     * @param started The adapter and its requests in progress.
+     * @protected
+     */
+    async drain(started) {
+        if (!started.inflight.size)
+            return;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.shutdownTimeout);
+        });
+        await Promise.race([Promise.allSettled(promises(started.inflight)), timeout]);
+        clearTimeout(timer);
+        const pending = [...started.inflight];
+        pending.forEach((request) => request.abortController.abort(new EntrypointStoppedException_js_1.EntrypointStoppedException('The entrypoint stopped before the request completed')));
+        //The aborted requests settle at once
+        await Promise.allSettled(promises(pending));
+    }
+    /**
+     * Run an action in its request's container: create the controller with the request's context and signal, validate
+     * the input (the request's data, overridden by the address parameters), check the access and call the action
+     * method with the validated input.
+     * @param details The action.
+     * @param invocation The request.
+     * @returns The action's result.
+     * @throws {Error} The input validation error, the access control's denial ({@link AccessDeniedException} or the
+     * rule's error), or the action's error.
+     * @protected
+     */
+    async runAction(details, invocation) {
+        const { context, container, params } = invocation;
+        //The controller of the request, shared by the objects of the request
+        const controller = await container.getShared(details.constructor, { context: context, signal: invocation.signal });
+        //The parameters of the address take precedence over the data of the request
+        const data = params && Object.keys(params).length ? { ...context.data, ...params } : context.data;
+        //The input is detached from the context, whose values are proxies validating their changes
+        const input = (0, utils_1.cloneDeep)(await this.validateInput(details.dtoConstructor, data, context.locale));
+        await this.runAccessControl(this.rules, container, (0, utils_1.As)(context), input, details);
+        return await controller.getMethod((0, utils_1.As)(details.method))(input);
+    }
+    /**
+     * Validate an action's input. An invalid input of a request with a language is validated again in it, so the
+     * error is in that language (a valid input is validated once, with the default settings).
+     * @param dtoConstructor The action's DTO.
+     * @param data The input to validate.
+     * @param locale The request's language (`context.locale`).
+     * @returns The validated input, with its defaults and conversions applied.
+     * @throws {Error} The validation error.
+     * @protected
+     */
+    async validateInput(dtoConstructor, data, locale) {
+        try {
+            return await dtoConstructor.validateAsync(data);
+        }
+        catch (error) {
+            if (!locale)
+                throw error;
+            return await dtoConstructor.validateAsync(data, { errors: { language: locale } });
+        }
+    }
+    /**
+     * Dispatch a request to an action in a new request container, tracked as in progress for its adapter until it
+     * ends. A request whose signal is already aborted is not run and resolves to `undefined`.
+     * @param started The adapter receiving the request.
+     * @param entry The action.
+     * @param runner The action's middleware pipeline.
+     * @param context The request's context.
+     * @param options The request's abort signal and address parameters.
+     * @returns The action's result, `undefined` when the request is aborted by its client.
+     * @protected
+     */
+    async dispatch(started, entry, runner, context, options) {
+        //An already aborted request is not executed at all
+        if (options.signal?.aborted)
+            return;
+        const request = { abortController: new AbortController() };
+        const abortRequest = () => request.abortController.abort();
+        options.signal?.addEventListener('abort', abortRequest, { once: true });
+        started.inflight.add(request);
+        try {
+            request.promise = this.execute(entry, runner, context, request.abortController.signal, options.params);
+            return await request.promise;
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abortRequest);
+            started.inflight.delete(request);
+        }
+    }
+    /**
+     * Execute a request in a new request container, destroyed when it ends. An aborted request settles at once: its
+     * container is destroyed and its result or error dropped.
+     * @param entry The action.
+     * @param runner The action's middleware pipeline.
+     * @param context The request's context.
+     * @param signal The request's abort signal.
+     * @param params The parameters taken from the request's address.
+     * @returns The action's result, `undefined` when the request is aborted by its client.
+     * @throws {EntrypointStoppedException} When the request is aborted because the entrypoint stopped.
+     * @protected
+     */
+    async execute(entry, runner, context, signal, params) {
+        const runtimeContainer = this.createScope();
+        let isAborted = false;
+        let settleAborted = utils_1.DevNull;
+        const aborted = new Promise((resolve) => {
+            settleAborted = () => resolve(ABORTED);
+        });
+        //Aborting destroys the request scope right away (container destruction is idempotent) and settles the request
+        const abortHandler = () => {
+            isAborted = true;
+            runtimeContainer.destroy().catch(utils_1.DevNull);
+            settleAborted();
+        };
+        signal.addEventListener('abort', abortHandler, { once: true });
+        try {
+            const running = runner({
+                context: (0, utils_1.As)(context),
+                action: (0, utils_1.As)(entry.info),
+                container: runtimeContainer,
+                signal: signal,
+                params: params
+            });
+            //The action of an aborted request may still fail, its error is dropped
+            running.catch(utils_1.DevNull);
+            const result = await Promise.race([running, aborted]);
+            if (!isAborted)
+                return result;
+        }
+        catch (e) {
+            if (!isAborted)
+                throw e;
+        }
+        finally {
+            //The request scope is always destroyed once the dispatch ends, its destruction never rejects
+            signal.removeEventListener('abort', abortHandler);
+            runtimeContainer.destroy().catch(utils_1.DevNull);
+        }
+        //A request aborted by the stop of the entrypoint fails, a request aborted by its client has no result
+        if (signal.reason instanceof EntrypointStoppedException_js_1.EntrypointStoppedException)
+            throw signal.reason;
+        return undefined;
+    }
+    /**
+     * The descriptions of a channel's actions.
+     * @param channel The channel's name.
+     * @returns The descriptions, empty when the channel has no actions.
+     * @protected
+     */
+    actionInfos(channel) {
+        return (0, utils_1.As)([...(this.#channels.get(channel)?.infos.values() ?? [])]);
+    }
+    /**
+     * The descriptions of the HTTP actions.
+     * @protected
+     */
+    get HTTP_ACTIONS() {
+        return this.actionInfos('http');
+    }
+    /**
+     * The descriptions of the service actions.
+     * @protected
+     */
+    get SERVICE_ACTIONS() {
+        return this.actionInfos('service');
+    }
+    /**
+     * The descriptions of the CLI actions.
+     * @protected
+     */
+    get CLI_ACTIONS() {
+        return this.actionInfos('cli');
+    }
+    /**
+     * The actions of a channel, with the groups they belong to.
+     * @param channel The channel's name.
+     * @param actionGroups The group names by id.
+     * @returns The actions and their groups.
+     * @protected
+     */
+    getEntrypointActions(channel, actionGroups = {}) {
+        const groupMap = new Map();
+        const actions = this.actionInfos(channel);
+        actions.forEach((action) => {
+            action.groups.forEach((groupId) => {
+                if (!groupMap.has(groupId))
+                    groupMap.set(groupId, {
+                        id: groupId,
+                        name: actionGroups[groupId],
+                        actions: []
+                    });
+                groupMap.get(groupId)?.actions.push(action);
+            });
+        });
+        return {
+            groups: [...groupMap.values()],
+            actions: actions
+        };
+    }
+    /**
+     * The group ids used by the actions but missing from the action groups.
+     * @param actionInfoMap The action descriptions by id.
+     * @param actionGroups The group names by id.
+     * @returns The missing group ids, each once.
+     * @protected
+     */
+    findInvalidActionGroupIds(actionInfoMap, actionGroups) {
+        const notfoundGroupIdSet = new Set();
+        actionInfoMap.forEach((action) => action.groups.forEach((groupId) => {
+            if (actionGroups[groupId] === undefined)
+                notfoundGroupIdSet.add(groupId);
+        }));
+        return [...notfoundGroupIdSet];
+    }
+    /**
+     * The names shared by the actions of several controller methods (the addresses of one method, such as its two
+     * routes, share its name).
+     * @param actionInfoMap The action descriptions by id.
+     * @returns The duplicate names, each once.
+     * @protected
+     */
+    findDuplicateActionNames(actionInfoMap) {
+        const methods = new Map();
+        const duplicates = new Set();
+        actionInfoMap.forEach((action) => {
+            const method = `${action.controller}:${action.method}`;
+            const seen = methods.get(action.name);
+            if (seen === undefined)
+                methods.set(action.name, method);
+            else if (seen !== method)
+                duplicates.add(action.name);
+        });
+        return [...duplicates];
+    }
+    /**
+     * Check the access to an action with {@link Entrypoint.accessControl}.
+     * @param rules The access control rule classes.
+     * @param runtimeContainer The request's container, where the rules are created.
+     * @param context The request's context.
+     * @param input The validated input.
+     * @param details The action.
+     * @throws {AccessDeniedException} When a rule denies the access (or the error a rule throws).
+     * @protected
+     */
+    async runAccessControl(rules, runtimeContainer, context, input, details) {
+        const [allowed, exception] = await this.accessControl.run(rules, runtimeContainer, context, input, details, (type) => {
+            const channel = (0, Channel_js_1.getChannelByContextType)(type);
+            return channel ? this.actionInfos(channel.name) : [];
+        });
+        if (!allowed)
+            throw exception;
+    }
+    /**
+     * Push an event to a client of the adapters which have clients (an Electron window's renderer, a Socket.IO
+     * socket); its listeners receive the arguments. The client of a service request is its `context.clientId`.
+     * @param clientId The client's id.
+     * @param event The event's name.
+     * @param args The arguments given to the client's listeners.
+     * @returns Whether an adapter has the client; `false` when it is gone or no adapter has clients.
+     */
+    notify(clientId, event, ...args) {
+        let notified = false;
+        for (const { adapter } of this.#started)
+            if (adapter.notify?.(clientId, event, args))
+                notified = true;
+        return notified;
+    }
+    /**
+     * Push an event to every client of the adapters which have clients (Electron windows, Socket.IO sockets); their
+     * listeners receive the arguments.
+     * @param event The event's name.
+     * @param args The arguments given to the clients' listeners.
+     * @returns The number of clients the event was pushed to.
+     */
+    broadcast(event, ...args) {
+        let clients = 0;
+        for (const { adapter } of this.#started)
+            clients += adapter.broadcast?.(event, args) ?? 0;
+        return clients;
+    }
+    /**
+     * The HTTP action groups configured by the `httpActionGroups` option.
+     * @returns The group names by id.
+     */
+    getHttpActionGroups() {
+        return this.httpActionGroups;
+    }
+    /**
+     * The service action groups configured by the `serviceActionGroups` option.
+     * @returns The group names by id.
+     */
+    getServiceActionGroups() {
+        return this.serviceActionGroups;
+    }
+    /**
+     * The CLI action groups configured by the `cliActionGroups` option.
+     * @returns The group names by id.
+     */
+    getCliActionGroups() {
+        return this.cliActionGroups;
+    }
+    /**
+     * The HTTP actions, with the groups they belong to (named after `httpActionGroups`).
+     * @returns The actions and their groups.
+     */
+    getHttpActions() {
+        return this.getEntrypointActions('http', this.httpActionGroups);
+    }
+    /**
+     * The service actions, with the groups they belong to (named after `serviceActionGroups`).
+     * @returns The actions and their groups.
+     */
+    getServiceActions() {
+        return this.getEntrypointActions('service', this.serviceActionGroups);
+    }
+    /**
+     * The CLI actions, with the groups they belong to (named after `cliActionGroups`).
+     * @returns The actions and their groups.
+     */
+    getCliActions() {
+        return this.getEntrypointActions('cli', this.cliActionGroups);
+    }
+    /**
+     * The actions of any channel, with the groups they belong to; the groups have no name (use the methods of the
+     * built-in channels, such as {@link Entrypoint.getHttpActions}, for named groups).
+     * @param channel The channel's name (`http`, `cli`, `service`, `schedule`, or a channel of another package).
+     * @returns The actions and their groups, empty when the channel has no actions.
+     */
+    getActions(channel) {
+        return this.getEntrypointActions(channel);
+    }
+};
+exports.Entrypoint = Entrypoint;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.Class(Controller_js_1.Controller)).optional().default([])),
+    __metadata("design:type", Array)
+], Entrypoint.prototype, "controllers", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.Function()).optional().default([])),
+    __metadata("design:type", Array)
+], Entrypoint.prototype, "middlewares", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.Class(AccessControlRule_js_1.AccessControlRule)).optional().default([])),
+    __metadata("design:type", Array)
+], Entrypoint.prototype, "rules", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().min(0).optional().default(30000)),
+    __metadata("design:type", Number)
+], Entrypoint.prototype, "shutdownTimeout", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.String()).optional().default({})),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "cliActionGroups", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.String()).optional().default({})),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "httpActionGroups", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.String()).optional().default({})),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "serviceActionGroups", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "cli", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "http", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], Entrypoint.prototype, "service", void 0);
+exports.Entrypoint = Entrypoint = __decorate([
+    (0, di_1.Singleton)()
+], Entrypoint);