@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/lib/AccessControlRule.d.ts

@@ -0,0 +1,91 @@
+import { BaseObject, type ActionPattern } from '@lakutata/core';
+import { BaseContext, ContextType } from '../context/BaseContext.js';
+import { CLIActionInfo, HTTPActionInfo, ServiceActionInfo } from '../Entrypoint.js';
+import type { ActionInfo } from './ControllerEntrypoint.js';
+/**
+ * An action's own access rule (the `rule` action option): resolve `true` to allow the request, `false` to deny it with
+ * an `AccessDeniedException`; a thrown error denies it with that error.
+ * @param context The request's context.
+ * @param input The action's validated input.
+ * @returns Whether the request is allowed.
+ */
+export type AccessControlRuleHandler<T extends BaseContext<Record<string, any>>> = (context: T, input?: ActionPattern<any>) => Promise<boolean>;
+/**
+ * An access control rule, checked for the actions declared with `acl: true`: give the rule classes to the
+ * entrypoint's `rules` option. For each request to such an action, every rule supporting the request's context type
+ * is created in the request's container (its dependencies injected) and its {@link AccessControlRule.rule} called, in
+ * the order of the option; the first one resolving `false` denies the request with an `AccessDeniedException`, the
+ * first one throwing denies it with its error. A request no rule denies is allowed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {AccessControlRule, buildEntrypoints, ContextType, Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+ * import {DELETE} from 'lakutata/decorator/ctrl'
+ *
+ * //Only the requests of an administrator reach the actions of the "admin" group
+ * class AdminRule extends AccessControlRule<HTTPContext> {
+ *     public get supportContextTypes(): ContextType[] {
+ *         return [ContextType.HTTP]
+ *     }
+ *
+ *     public async rule(): Promise<boolean> {
+ *         if (!this.targetAction.groups.includes('admin')) return true
+ *         return this.context.request.headers['x-role'] === 'admin'
+ *     }
+ * }
+ *
+ * class UserController extends Controller {
+ *     @DELETE('/users/:id', {acl: true, groups: ['admin']})
+ *     public async remove(input: {id: string}): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'admin.app',
+ *     name: 'Admin',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             rules: [AdminRule],
+ *             httpActionGroups: {admin: 'Administration'}
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare abstract class AccessControlRule<T extends BaseContext<Record<string, any>> = BaseContext<Record<string, any>>> extends BaseObject {
+    /**
+     * The request's context.
+     * @protected
+     */
+    protected readonly context: T;
+    /**
+     * The action's validated input.
+     * @protected
+     */
+    protected readonly input: ActionPattern<any>;
+    /**
+     * The descriptions of every action of the request's channel (to check the permissions an action requires against
+     * the others).
+     * @protected
+     */
+    protected readonly actions: HTTPActionInfo[] | ServiceActionInfo[] | CLIActionInfo[];
+    /**
+     * The requested action: its `id`, `name`, `description`, `groups`, `acl`, `rule` and `action`
+     * (`ControllerClass:method`). Its channel's fields (`route`, `command`, `pattern`), `controller`, `method` and
+     * `jsonSchema` are in {@link AccessControlRule.actions}, found by `id`.
+     * @protected
+     */
+    protected readonly targetAction: ActionInfo;
+    /**
+     * The context types of the requests the rule checks (`ContextType.HTTP`…, or the context type of another channel);
+     * for the other requests the rule is created but its {@link AccessControlRule.rule} is not called.
+     */
+    abstract get supportContextTypes(): ContextType[];
+    /**
+     * Check the request.
+     * @returns `true` to let the next rules check the request, `false` to deny it with an `AccessDeniedException`.
+     * @throws {Error} Any error, to deny the request with it.
+     */
+    abstract rule(): Promise<boolean>;
+}

package/dist/cjs/lib/AccessControlRule.js

@@ -0,0 +1,76 @@
+"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.AccessControlRule = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+/**
+ * An access control rule, checked for the actions declared with `acl: true`: give the rule classes to the
+ * entrypoint's `rules` option. For each request to such an action, every rule supporting the request's context type
+ * is created in the request's container (its dependencies injected) and its {@link AccessControlRule.rule} called, in
+ * the order of the option; the first one resolving `false` denies the request with an `AccessDeniedException`, the
+ * first one throwing denies it with its error. A request no rule denies is allowed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {AccessControlRule, buildEntrypoints, ContextType, Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+ * import {DELETE} from 'lakutata/decorator/ctrl'
+ *
+ * //Only the requests of an administrator reach the actions of the "admin" group
+ * class AdminRule extends AccessControlRule<HTTPContext> {
+ *     public get supportContextTypes(): ContextType[] {
+ *         return [ContextType.HTTP]
+ *     }
+ *
+ *     public async rule(): Promise<boolean> {
+ *         if (!this.targetAction.groups.includes('admin')) return true
+ *         return this.context.request.headers['x-role'] === 'admin'
+ *     }
+ * }
+ *
+ * class UserController extends Controller {
+ *     @DELETE('/users/:id', {acl: true, groups: ['admin']})
+ *     public async remove(input: {id: string}): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'admin.app',
+ *     name: 'Admin',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             rules: [AdminRule],
+ *             httpActionGroups: {admin: 'Administration'}
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+class AccessControlRule extends core_1.BaseObject {
+}
+exports.AccessControlRule = AccessControlRule;
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], AccessControlRule.prototype, "context", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], AccessControlRule.prototype, "input", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Array)
+], AccessControlRule.prototype, "actions", void 0);
+__decorate([
+    (0, di_1.Configurable)(),
+    __metadata("design:type", Object)
+], AccessControlRule.prototype, "targetAction", void 0);

package/dist/cjs/lib/ActionOptions.d.ts

@@ -0,0 +1,67 @@
+import { DTO } from '@lakutata/core';
+import type { AccessControlRuleHandler } from './AccessControlRule.js';
+import { BaseContext } from '../context/BaseContext.js';
+import type { MiddlewareDefinition } from './Middleware.js';
+/**
+ * The options of a controller action, the last argument of the action decorators (`@GET`, `@CLIAction`,
+ * `@ServiceAction`, `@Schedule`…).
+ * @example
+ * ```typescript
+ * import {Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+ * import {type ActionOptions} from '@lakutata/entrypoint/channel'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * //Only the requests carrying the admin token reach the action
+ * const adminOnly: ActionOptions<HTTPContext> = {
+ *     acl: true,
+ *     name: 'listUsers',
+ *     description: 'List the users',
+ *     groups: ['admin'],
+ *     rule: async (context: HTTPContext): Promise<boolean> => context.request.headers.authorization === 'Bearer admin'
+ * }
+ *
+ * class UserController extends Controller {
+ *     @GET('/users', adminOnly)
+ *     public async list(): Promise<string[]> {
+ *         return []
+ *     }
+ * }
+ * ```
+ */
+export declare class ActionOptions<T extends BaseContext<Record<string, any>>> extends DTO {
+    /**
+     * Whether the entrypoint's access control rules are checked for the action; a request they deny fails with an
+     * `AccessDeniedException`. With no rule (or none supporting the request's context type), the access is
+     * allowed.
+     * @default false
+     */
+    acl?: boolean;
+    /**
+     * The action's name, unique within its channel among the controller methods (the addresses of one method may
+     * share it): `ControllerClass:method` when empty.
+     * @default ''
+     */
+    name?: string;
+    /**
+     * The action's description, listed with the action.
+     * @default ''
+     */
+    description?: string;
+    /**
+     * The ids of the action's groups; for HTTP, CLI and service actions each id must be a key of the entrypoint's
+     * action groups option (`httpActionGroups`…), or the entrypoint fails to initialize.
+     * @default []
+     */
+    groups?: string[];
+    /**
+     * The action's own access rule, checked after the entrypoint's rules when `acl` is on, and alone when it is off:
+     * resolving `false` denies the request (`AccessDeniedException`), throwing denies it with the thrown error.
+     */
+    rule?: AccessControlRuleHandler<T>;
+    /**
+     * The action's middlewares, run after the ones of the controller class and before the ones added to the method
+     * by `@UseMiddlewares`.
+     * @default []
+     */
+    middlewares?: MiddlewareDefinition[];
+}

package/dist/cjs/lib/ActionOptions.js

@@ -0,0 +1,67 @@
+"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.ActionOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * The options of a controller action, the last argument of the action decorators (`@GET`, `@CLIAction`,
+ * `@ServiceAction`, `@Schedule`…).
+ * @example
+ * ```typescript
+ * import {Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+ * import {type ActionOptions} from '@lakutata/entrypoint/channel'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * //Only the requests carrying the admin token reach the action
+ * const adminOnly: ActionOptions<HTTPContext> = {
+ *     acl: true,
+ *     name: 'listUsers',
+ *     description: 'List the users',
+ *     groups: ['admin'],
+ *     rule: async (context: HTTPContext): Promise<boolean> => context.request.headers.authorization === 'Bearer admin'
+ * }
+ *
+ * class UserController extends Controller {
+ *     @GET('/users', adminOnly)
+ *     public async list(): Promise<string[]> {
+ *         return []
+ *     }
+ * }
+ * ```
+ */
+class ActionOptions extends core_1.DTO {
+}
+exports.ActionOptions = ActionOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional().default(false)),
+    __metadata("design:type", Boolean)
+], ActionOptions.prototype, "acl", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().allow('').optional().default('')),
+    __metadata("design:type", String)
+], ActionOptions.prototype, "name", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().allow('').optional().default('')),
+    __metadata("design:type", String)
+], ActionOptions.prototype, "description", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.String()).optional().default([])),
+    __metadata("design:type", Array)
+], ActionOptions.prototype, "groups", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Function().optional()),
+    __metadata("design:type", Function)
+], ActionOptions.prototype, "rule", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Function()).optional().default([])),
+    __metadata("design:type", Array)
+], ActionOptions.prototype, "middlewares", void 0);

package/dist/cjs/lib/ActionResult.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The base of the results an action returns to describe its output beyond its data (a status, headers, a file, an
+ * event stream): {@link StatusResult}, {@link FileResult}, {@link EventsResult}, built with `Result`. The HTTP and CLI
+ * adapters output the results they support, and the `data` of the others; the service adapters (Socket.IO, JSON-RPC,
+ * Electron IPC, the HTTP service, gRPC, NATS) send the `data` of a `StatusResult` and answer a `FileResult` or an
+ * `EventsResult` with an error.
+ * @example
+ * ```typescript
+ * import {ActionResult} from 'lakutata/com/entrypoint'
+ *
+ * //A result carrying a page of items, an adapter of its own may output its paging
+ * export class PageResult<T> extends ActionResult {
+ *     constructor(public readonly items: T[], public readonly next?: string) {
+ *         super()
+ *     }
+ *
+ *     public get data(): T[] {
+ *         return this.items
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class ActionResult {
+    /**
+     * The result's data: what the adapters not supporting the result output.
+     */
+    abstract get data(): unknown;
+}

package/dist/cjs/lib/ActionResult.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionResult = void 0;
+/**
+ * The base of the results an action returns to describe its output beyond its data (a status, headers, a file, an
+ * event stream): {@link StatusResult}, {@link FileResult}, {@link EventsResult}, built with `Result`. The HTTP and CLI
+ * adapters output the results they support, and the `data` of the others; the service adapters (Socket.IO, JSON-RPC,
+ * Electron IPC, the HTTP service, gRPC, NATS) send the `data` of a `StatusResult` and answer a `FileResult` or an
+ * `EventsResult` with an error.
+ * @example
+ * ```typescript
+ * import {ActionResult} from 'lakutata/com/entrypoint'
+ *
+ * //A result carrying a page of items, an adapter of its own may output its paging
+ * export class PageResult<T> extends ActionResult {
+ *     constructor(public readonly items: T[], public readonly next?: string) {
+ *         super()
+ *     }
+ *
+ *     public get data(): T[] {
+ *         return this.items
+ *     }
+ * }
+ * ```
+ */
+class ActionResult {
+}
+exports.ActionResult = ActionResult;

package/dist/cjs/lib/ApplicationOf.d.ts

@@ -0,0 +1,6 @@
+import { Application } from '@lakutata/core';
+/**
+ * The application a module belongs to (undefined out of an application: a container of the tests)
+ * @param module
+ */
+export declare function applicationOf(module: unknown): Application | undefined;

package/dist/cjs/lib/ApplicationOf.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applicationOf = applicationOf;
+const core_1 = require("@lakutata/core");
+/**
+ * The application a module belongs to (undefined out of an application: a container of the tests)
+ * @param module
+ */
+function applicationOf(module) {
+    let target = module;
+    while (target && !(target instanceof core_1.Application))
+        target = target.getParent?.();
+    return target;
+}

package/dist/cjs/lib/Controller.d.ts

@@ -0,0 +1,59 @@
+import { Provider } from '@lakutata/core';
+import { CLIContext } from '../context/CLIContext.js';
+import { HTTPContext } from '../context/HTTPContext.js';
+import { ServiceContext } from '../context/ServiceContext.js';
+import { BaseContext } from '../context/BaseContext.js';
+/**
+ * The names of a controller's own members (the ones {@link Controller} does not declare): the methods an action
+ * decorator may be applied to.
+ */
+export type ControllerProperty<ClassPrototype extends Controller> = Exclude<keyof ClassPrototype, keyof Controller>;
+/**
+ * The base class of the controllers: classes whose methods, decorated with the action decorators (`@GET`, `@POST`…,
+ * `@CLIAction`, `@ServiceAction`, `@Schedule`), serve the entrypoint's requests. Give the controller classes to the
+ * entrypoint's `controllers` option.
+ *
+ * A controller is scoped: each request creates its own instance in the request's container, with the request's
+ * context and abort signal, and destroys it when the request ends; its injected providers are scoped to the request
+ * too. An action method receives its input (the request's data merged with the address parameters, validated by the
+ * action's DTO, its defaults applied) and returns the result the adapter outputs; the actions declared in a parent
+ * class are served by the registered subclasses.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller, HTTPContext} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ *
+ * class FindUserDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public id: string
+ * }
+ *
+ * class UserController extends Controller {
+ *     //The same action over HTTP (GET /users/:id), the CLI (user-get --id 1) and the services ({act: 'user.get', id})
+ *     @GET('/users/:id', FindUserDTO)
+ *     @CLIAction('user-get', FindUserDTO)
+ *     @ServiceAction({act: 'user.get'}, FindUserDTO)
+ *     public async get(input: FindUserDTO): Promise<{id: string, via: string}> {
+ *         this.signal?.throwIfAborted()
+ *         const via: string = this.context instanceof HTTPContext ? this.context.request.headers['user-agent'] ?? 'http' : this.context.type
+ *         return {id: input.id, via: via}
+ *     }
+ * }
+ * ```
+ */
+export declare class Controller extends Provider {
+    /**
+     * The request's context: an {@link HTTPContext}, {@link CLIContext}, {@link ServiceContext}, or the context of
+     * another channel (`ScheduleContext`…); check its `type` or its class to tell them apart.
+     * @protected
+     */
+    protected readonly context: CLIContext | HTTPContext | ServiceContext | BaseContext;
+    /**
+     * Aborts when the request is aborted: its client gone (the HTTP connection closed, the gRPC call cancelled), its
+     * deadline passed, or the entrypoint stopping. Long-running actions should stop then: their result is dropped.
+     * @protected
+     */
+    protected readonly signal?: AbortSignal;
+}

package/dist/cjs/lib/Controller.js

@@ -0,0 +1,64 @@
+"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.Controller = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const BaseContext_js_1 = require("../context/BaseContext.js");
+/**
+ * The base class of the controllers: classes whose methods, decorated with the action decorators (`@GET`, `@POST`…,
+ * `@CLIAction`, `@ServiceAction`, `@Schedule`), serve the entrypoint's requests. Give the controller classes to the
+ * entrypoint's `controllers` option.
+ *
+ * A controller is scoped: each request creates its own instance in the request's container, with the request's
+ * context and abort signal, and destroys it when the request ends; its injected providers are scoped to the request
+ * too. An action method receives its input (the request's data merged with the address parameters, validated by the
+ * action's DTO, its defaults applied) and returns the result the adapter outputs; the actions declared in a parent
+ * class are served by the registered subclasses.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller, HTTPContext} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ *
+ * class FindUserDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public id: string
+ * }
+ *
+ * class UserController extends Controller {
+ *     //The same action over HTTP (GET /users/:id), the CLI (user-get --id 1) and the services ({act: 'user.get', id})
+ *     @GET('/users/:id', FindUserDTO)
+ *     @CLIAction('user-get', FindUserDTO)
+ *     @ServiceAction({act: 'user.get'}, FindUserDTO)
+ *     public async get(input: FindUserDTO): Promise<{id: string, via: string}> {
+ *         this.signal?.throwIfAborted()
+ *         const via: string = this.context instanceof HTTPContext ? this.context.request.headers['user-agent'] ?? 'http' : this.context.type
+ *         return {id: input.id, via: via}
+ *     }
+ * }
+ * ```
+ */
+let Controller = class Controller extends core_1.Provider {
+};
+exports.Controller = Controller;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.InstanceOf(BaseContext_js_1.BaseContext).required()),
+    __metadata("design:type", Object)
+], Controller.prototype, "context", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.InstanceOf(AbortSignal).optional()),
+    __metadata("design:type", AbortSignal)
+], Controller.prototype, "signal", void 0);
+exports.Controller = Controller = __decorate([
+    (0, di_1.Scoped)(true)
+], Controller);