ldap-rest 1.2.1 → 1.3.0

package/dist/src/lib/entitySchema/validator.d.ts

@@ -22,19 +22,76 @@ export declare class EntityValidator {
     private readonly deps;
     constructor(schema: Schema | undefined, deps: EntityValidatorDeps);
     /**
-     * Check a new entry, then convert it in place for the directory.
+     * Check a new entry, then convert it for the directory. Every attribute
+     * the schema declares is named as the schema does, a form the defaults,
+     * the required check and the conversion all read.
      *
      * @param entry entry as the client sent it, `objectClass` included
+     * @returns the entry to write: the one given, or a copy under the schema's
+     *   spellings
      */
-    validateNew(entry: AttributesList): Promise<void>;
+    validateNew(entry: AttributesList): Promise<AttributesList>;
     /**
-     * Check the parts of a change, then convert them in place. No value under
-     * a name is the empty list for the directory layer, which clears the
-     * attribute in a `replace` and refuses it in an `add`.
+     * Check the parts of a change, then convert them. Under a name the schema
+     * declares, no value becomes the empty list, which clears the attribute
+     * in a `replace` and is refused in an `add`; under a name it does not
+     * declare, a `null` is dropped from an `add` and becomes that empty list
+     * in a `replace`.
      *
      * @param changes change as the client sent it
+     * @returns the same change, under the schema's spellings
      */
-    validateChanges(changes: ModifyRequest): Promise<void>;
+    validateChanges(changes: ModifyRequest): Promise<ModifyRequest>;
+    /**
+     * Name every key the schema declares as the schema does, and refuse two
+     * keys naming one attribute. The conversion, the required check and the
+     * defaults look a declared attribute up by its own name: a field they
+     * would leave out is one the client sent under another case or with a
+     * `;binary` option.
+     *
+     * @returns the same attributes, renamed: the map itself when nothing
+     *   changes, a copy renamed otherwise
+     * @throws BadRequestError when two keys name the same attribute
+     */
+    private renameDeclared;
+    /**
+     * {@link renameDeclared} on a list of names, such as a `delete`.
+     *
+     * Two names of one attribute are refused as the routes refuse them: as
+     * the schema declares it, or as this server knows the attribute by its
+     * name, which makes `l;binary` and `L` one attribute.
+     */
+    private renameDeclaredNames;
+    /**
+     * The attribute a name holds, case and option aside: the option is a
+     * transfer syntax, and `l;binary` is the `l` a plain `L` names.
+     */
+    private attributeIdentity;
+    /**
+     * The schema's spelling of a declared attribute, with the `;binary`
+     * option, the only one a write takes, written as the directory writes it.
+     */
+    private schemaSpelling;
+    /**
+     * Drop, in place, the keys a creation or an `add` carries with `null` or
+     * `undefined` under a name the schema does not declare. A declared
+     * attribute is left to the schema, which turns no value into the empty
+     * list, refused for a `required` one; an undeclared one has no such step,
+     * and without a schema none exists. The write would otherwise carry
+     * `[null]`, which ldapts cannot send.
+     */
+    private dropUndeclaredEmpty;
+    /**
+     * Check every value of a creation or of a part of a change, then write the
+     * shape each one is stored in, in place: no value becomes the empty list,
+     * which clears the attribute in a `replace`. A value the schema does not
+     * declare is left as sent on a change, and on a creation as the directory
+     * layer takes it.
+     *
+     * @param values entry of a creation, or `add` / `replace` of a change
+     * @param part the part of a change, undefined for a creation
+     */
+    private checkValues;
     /**
      * Check one value against its attribute's rules: its shape, then the
      * entries a pointer names, then the pattern.

package/dist/src/lib/errors.d.ts

@@ -59,6 +59,61 @@ export declare const errorBody: (err: unknown, message: string) => {
 export declare class ForbiddenError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * An authorization plugin's refusal.
+ *
+ * Its message is for the operator, not for the client: it names the model
+ * and the branch it judged, which the caller may not know of. Its class is
+ * what says an authorization plugin refused, so the 403 is recognised
+ * through the `new Error(\`…\`, { cause })` wrappers along the way — see
+ * {@link isAuthzRefusal} — and the client is told {@link AUTHZ_REFUSED}.
+ */
+export declare class AuthzRefusedError extends ForbiddenError {
+    /**
+     * Read instead of the class and the name: a plugin loaded from `dist` holds
+     * another copy of this module, where `instanceof` answers false, and a
+     * subclass may replace `name`.
+     */
+    readonly authzRefusal: true;
+    constructor(message: string);
+}
+/**
+ * Every error in a chain of `cause`s, the outermost first.
+ *
+ * A plugin wrapping what the directory or an authorization hook threw as
+ * `new Error(\`…\`, { cause: err })` keeps the reason and what it carries:
+ * its class, its status, the database's refusal. The serializers read the
+ * whole chain rather than the wrapper alone.
+ *
+ * @param err what was thrown, which need not be an error
+ * @returns the errors of the chain, the outermost first
+ */
+export declare const errorChain: (err: unknown) => Error[];
+/**
+ * Whether an error is, or wraps through `cause`, an authorization plugin's
+ * refusal.
+ *
+ * Read by the `authzRefusal` marker rather than by class: a plugin loaded
+ * from `dist` while its caller runs from `src` throws a `AuthzRefusedError`
+ * whose `instanceof` answers false, and a subclass that replaces `name`
+ * would escape a name test — the refusal would then be answered as the
+ * wrapper's own error.
+ *
+ * @param err what was thrown
+ * @returns true for a refusal, or for an error wrapping one
+ */
+export declare const isAuthzRefusal: (err: unknown) => boolean;
+/**
+ * The status a thrown thing is answered with.
+ *
+ * The first error from the outside that names one decides: a wrapper names
+ * none, so the error it wraps is read; a layer that translates an inner error
+ * keeps its own status.
+ *
+ * @param err what was thrown
+ * @returns its status code, 500 when it names none
+ */
+export declare const statusCodeOf: (err: unknown) => number;
 /**
  * An identity that names more than one directory entry.
  *
@@ -69,7 +124,7 @@ export declare class ForbiddenError extends HttpError {
  * rather than a `null`: a `null` resolution is what
  * `--authz-unresolved-user allow` lets through unchecked.
  */
-export declare class AmbiguousIdentityError extends ForbiddenError {
+export declare class AmbiguousIdentityError extends AuthzRefusedError {
     identity: string;
     count: number;
     constructor(identity: string, count: number);

package/dist/src/lib/expressFormatedResponses.d.ts

@@ -1,9 +1,6 @@
-/**
- * Standard express responses and express utilities
- * @author Xavier Guimard <xguimard@linagora.com>
- */
 import type { Request, Response } from 'express';
 import type winston from 'winston';
+import { type Refusal } from './errors';
 /**
  * Install the logger, or remove it: a test restores the state it found,
  * which before any `DM` is none.
@@ -21,9 +18,47 @@ export declare const getLogger: () => winston.Logger | undefined;
  */
 export declare const setDebug: (debug: boolean) => void;
 /**
- * The body of a 5xx answer, for the error middleware of `DM` and
- * `serverError` alike. The failure is for the logs: the message names it
- * only under `--debug`.
+ * The sentence a client is told of a client error: an authorization
+ * plugin's refusal says nothing of the branch it judged.
+ *
+ * Any other client error keeps the sentence of the outermost error, the one
+ * the route threw when it gave up: it says what the caller's request was
+ * about, which the `HttpError` several layers down does not.
+ *
+ * @param err what was thrown
+ * @returns the sentence to answer
+ */
+export declare const clientMessageOf: (err: unknown) => string;
+/**
+ * The message of a thrown thing, read the way the log reads it.
+ *
+ * @param err what was thrown
+ * @returns its message, or the value as a string
+ */
+export declare const messageOf: (err: unknown) => string;
+/**
+ * What an error is answered with, for the error middleware of `DM` and
+ * `serverError` alike: one status and one body, wherever the handler called
+ * a helper or threw.
+ *
+ * An authorization plugin's refusal loses its status when a plugin wraps it
+ * as a plain `Error`; it is still a 403, whatever the wrapper says. The
+ * failure of a 5xx is for the logs, and is named in the body only under
+ * `--debug`.
+ *
+ * @param err what failed
+ * @param debug whether to name a failure in the answer
+ * @returns the status and body to answer
+ */
+export declare const errorResponse: (err: unknown, debug?: boolean) => {
+    status: number;
+    body: {
+        error: string;
+    } & Partial<Refusal>;
+};
+/**
+ * The body of a 5xx answer, for every status answered when the failure is
+ * the server's: the message names the failure only under `--debug`.
  *
  * @param err what failed
  * @param debug whether to name the failure; `serverError`'s setting by default
@@ -34,6 +69,13 @@ export declare const serverErrorBody: (err: unknown, debug?: boolean) => {
 };
 export declare const tryMethod: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const tryMethodData: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
+/**
+ * The answer of a route that changed something and returned nothing: the
+ * shape every write route declares as its 200.
+ */
+export declare const WriteResponse: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TBoolean;
+}>;
 export declare const ok: (res: Response, data?: object) => void;
 export declare const created: (res: Response, data?: object) => void;
 export declare const noContent: (res: Response) => void;

package/dist/src/lib/hookBus.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The hooks of the server, typed by `Hooks`, with one calling convention per
+ * kind.
+ *
+ * The three kinds are told apart by what their subscriber answers:
+ * chained hooks get a value and pass it — possibly changed — along the
+ * chain; notified hooks answer nothing, are not waited for, and their
+ * failures are logged; several hooks answer a value each.
+ *
+ * @see docs/plugin-development/hooks.md
+ */
+import type { Hooks } from '../hooks';
+export type HookFn = Function;
+/** A promise, or the value itself */
+type Settled<T> = T extends Promise<infer P> ? P : T;
+/** Whether `F` answers nothing: `void`, or a promise of it */
+export type AnswersVoid<F> = [
+    Settled<F extends (...args: never[]) => infer R ? R : never>
+] extends [void | undefined] ? true : false;
+/** The values of `Hooks` a chain threads: the ones whose answer is a value */
+export type ChainedName = {
+    [K in keyof Hooks]-?: AnswersVoid<NonNullable<Hooks[K]>> extends true ? never : K;
+}[keyof Hooks];
+/** The `Hooks` a notification fires: the ones whose subscriber answers nothing */
+export type NotifiedName = Exclude<keyof Hooks, ChainedName>;
+/** A chained hook is declared with the value it threads */
+export type ChainedNameOf<K extends keyof Hooks> = K extends ChainedName ? K : never;
+/** The arguments a hook expects */
+export type Args<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (...args: infer A) => unknown ? A : never;
+/** What a chained hook threads */
+export type ChainedValue<K extends keyof Hooks> = NonNullable<Hooks[K]> extends (arg: infer A) => unknown ? A : never;
+/**
+ * Record the plugin a hook function belongs to.
+ *
+ * @param fn the registered function
+ * @param plugin the plugin's instance name
+ * @param hook the hook it is registered under
+ */
+export declare const recordHookOwner: (fn: HookFn, plugin: string, hook: string) => void;
+/**
+ * The plugin a hook function belongs to, and the hook it is registered
+ * under, when `registerPlugin` registered it.
+ *
+ * @param fn a hook function
+ * @returns its plugin's instance name and hook name, or undefined
+ */
+export declare const hookOwner: (fn: HookFn) => {
+    plugin: string;
+    hook: string;
+} | undefined;
+/**
+ * Run a hook under its plugin's name and its own, for the lines it logs.
+ *
+ * @param hook the registered function
+ * @param fn its run
+ * @returns what `fn` returns
+ */
+export declare const runAsHookOwner: <T>(hook: HookFn, fn: () => T) => T;
+/**
+ * A hook's list, as `server.hooks` spells it: `undefined` when nothing is
+ * subscribed, a function for one subscriber, a list for several, and
+ * anything else when a test writes a list through the hook and walks it.
+ */
+export type HookValue<K extends keyof Hooks = keyof Hooks> = Hooks[K] | Function[] | undefined;
+/** The functions a subscriber value holds, one or many */
+export declare const asHooks: <K extends keyof Hooks>(value: HookValue<K>) => HookFn[];
+/**
+ * How a flat entity raises its own hooks, see `abstract/ldapFlat.ts`: the
+ * prefix it names them under, added to the suffix of each. They are not
+ * `Hooks`' own, see {@link FlatHookPrefix}.
+ */
+export interface FlatHookBus {
+    /** Thread a value through `{prefix}{suffix}`, as {@link HookBus.chain} */
+    chain<T>(suffix: string, value: T): Promise<T>;
+    /** Notify `{prefix}{suffix}`, as {@link HookBus.notify} */
+    notify(suffix: string, ...args: unknown[]): void;
+}
+export default class HookBus implements FlatHookBus {
+    /**
+     * What `server.hooks` holds, shared by reference. A plugin reaching it
+     * directly is not told by its type whether the hook exists, nor how it
+     * is called; this bus is.
+     */
+    private readonly hooks;
+    private readonly tracked;
+    /**
+     * @param hooks the server's hook lists, shared by reference
+     */
+    constructor(hooks: {
+        [K in keyof Hooks]?: HookValue<K>;
+    });
+    /** Whether anything is subscribed to a hook */
+    has(name: keyof Hooks): boolean;
+    /**
+     * The subscribers of a hook, in the order they run.
+     *
+     * @param name the hook
+     * @returns its subscribers, empty when nothing subscribed
+     */
+    subscribers(name: keyof Hooks): readonly HookFn[];
+    /**
+     * Subscribe a function to a hook, or forget its subscribers when given
+     * none, as a plugin declaring `hooks` would.
+     *
+     * @param name the hook
+     * @param fn what to run, none to unsubscribe every subscriber
+     */
+    set<K extends keyof Hooks>(name: K, ...fn: NonNullable<Hooks[K]>[]): void;
+    /**
+     * Add a subscriber to a hook, after the ones already there.
+     *
+     * @param name the hook
+     * @param fn what to run
+     */
+    subscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Put a subscriber at a given place in a hook's list, as
+     * `registerPlugin` does for an authorization hook.
+     *
+     * @param name the hook
+     * @param fn what to run
+     * @param at its place, the end when past it
+     */
+    insert<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>, at: number): void;
+    /**
+     * Remove a subscriber from a hook, wherever it sits.
+     *
+     * @param name the hook
+     * @param fn the subscriber
+     */
+    unsubscribe<K extends keyof Hooks>(name: K, fn: NonNullable<Hooks[K]>): void;
+    /**
+     * Move a subscriber to the end of its hook's list, keeping it registered,
+     * for a plugin that must run after every other one.
+     *
+     * @param name the hook
+     * @param hook the subscriber
+     * @returns whether it was subscribed to the hook
+     */
+    toLast(name: keyof Hooks, hook: HookFn): boolean;
+    /**
+     * Thread a value through every subscriber of a chained hook, each getting
+     * what the one before answered. The first failure stops the chain and
+     * travels up: a refusal is a refusal, and the caller must not go on as if
+     * the chain had said yes.
+     *
+     * Hooks run outside the request being served: what a hook reads or writes
+     * to validate, complete or keep track of an operation is the server's
+     * (#385). The request is in the arguments of the hooks that judge, which
+     * judge by it; a hook acting as the caller names it.
+     *
+     * @param name the hook
+     * @param value the value to thread
+     * @returns the last value in the chain
+     */
+    chain<K extends keyof Hooks>(name: ChainedNameOf<K>, value: ChainedValue<K>): Promise<ChainedValue<K>>;
+    /**
+     * Notify every subscriber of a hook, one after the other, outside the
+     * request that caused it: they are told what happened, and was judged, and
+     * react as the server — synchronizing, publishing, keeping invariants —
+     * whoever asked.
+     *
+     * Not awaited, and not failed: the write the subscribers react to is done,
+     * and a subscriber's failure is logged and goes no further. `settled`
+     * waits for them.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notify<K extends NotifiedName>(name: K, ...args: Args<K>): void;
+    /**
+     * Run every subscriber of a hook and let their failures go to the caller,
+     * for the rare hook whose subscribers are part of the answer: a logout
+     * token reaches the provider only once what it closes is recorded, so the
+     * failure has to reach the library, which answers 400 and lets the
+     * provider retry.
+     *
+     * Every subscriber runs even when one fails, one after the other as
+     * `notify` runs them, and the first failure is raised once they all have:
+     * stopping at the first would cost the others their turn — a session the
+     * provider considers closed would keep working against the store that
+     * would have killed it.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     */
+    notifyStrict<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Notify, then wait for the subscribers: a caller that has to know the
+     * consequences have run, a test instead of a sleep.
+     *
+     * @param name the hook
+     * @param args what its subscribers are told
+     * @returns once they have returned
+     */
+    notifyAndWait<K extends NotifiedName>(name: K, ...args: Args<K>): Promise<void>;
+    /**
+     * Run every hook the server holds and answer what each gives, in order.
+     * For the hooks nothing decided the answer of: `hello` is a demo of one.
+     *
+     * @param name the hook
+     * @param args what its subscribers are given
+     * @returns one answer per subscriber
+     */
+    call<K extends keyof Hooks>(name: K, ...args: Args<K>): Promise<unknown[]>;
+    /**
+     * A view raising `{prefix}{suffix}` hooks, for an entity whose hooks are
+     * named dynamically.
+     *
+     * @param prefix the entity's prefix
+     * @returns the bus, raising its hooks
+     */
+    prefixed(prefix: string): FlatHookBus;
+    /**
+     * Resolves when every notification started so far has run, the ones
+     * started while waiting included.
+     */
+    settled(): Promise<void>;
+    /**
+     * Write a hook's subscribers the way `server.hooks` spells them: no entry
+     * when nothing is subscribed, the function itself for one subscriber.
+     */
+    private store;
+    private fire;
+}
+export {};

package/dist/src/lib/instanceProviders.d.ts

@@ -1,11 +1,3 @@
-/**
- * @module lib/instanceProviders
- *
- * The two places a workplace instance can be created: the Cloudery, which
- * answers at once and builds the instance afterwards, and the cozy-stack
- * admin API, which builds it before answering.
- */
-import { type RequestInit, type Response } from 'node-fetch';
 /**
  * Reduce a name to what the Cloudery takes in a slug; it refused `_` or `@`
  * with "Slug is invalid". `-` is kept, except at either end where no host

package/dist/src/lib/ldapActions.d.ts

@@ -100,6 +100,8 @@ declare class ldapActions {
     private attrSignatureCache;
     private waitingResolvers;
     private availableConnections;
+    /** Connections being opened, not yet in `connectionPool` */
+    private opening;
     private isCleaningUp;
     /** See {@link declareObjectClasses}. */
     private declaredClasses;
@@ -156,9 +158,14 @@ declare class ldapActions {
         busy: number;
         idle: number;
         waiting: number;
+        opening: number;
         max: number;
     };
     private takeConnection;
+    /** Refuse every queued request with `error` */
+    private refuseWaiters;
+    /** Let one queued request take a place that freed with no connection */
+    private wakeWaiter;
     /**
      * Release a connection back to the pool
      * If there are waiting requests, hand off the connection directly

package/dist/src/lib/parseConfig.d.ts

@@ -17,9 +17,14 @@ export type ConfigEntry = [
 ];
 export declare class ConfigParser {
     private config;
+    /** CLI arguments no entry declared, kept in `Config` by the parser */
+    private unknownArgs;
+    get unknownOptions(): string[];
     constructor(config: ConfigTemplate);
     parse(argv?: string[]): Config;
     private parseCliArgs;
     private getKeyFromCliArg;
 }
+export declare function splitValue(value: string, kind: ArrayKind | undefined, form: 'singular' | 'plural'): string[];
+export declare function parseNumber(value: string): number;
 export declare function parseConfig(config: ConfigEntry[], argv?: string[]): Config;

package/dist/src/lib/route.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @module lib/route
+ * @author Xavier Guimard <xguimard@linagora.com>
+ *
+ * One declaration per HTTP route: its input schemas, the handler that
+ * receives the checked values, and what the OpenAPI document says of it.
+ * @group Libraries
+ */
+import type { Static, TSchema } from '@sinclair/typebox';
+import type { Express, NextFunction, Request, RequestHandler, Response } from 'express';
+export type RouteMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/** What the handler receives for a part it declared no schema for. */
+type Input<T> = T extends TSchema ? Static<T> : unknown;
+/** What a handler receives once its request has been checked. */
+export interface RouteInput<P extends TSchema | undefined, Q extends TSchema | undefined, B extends TSchema | undefined> {
+    req: Request;
+    res: Response;
+    /** Express's own, for a handler that answers a failure itself */
+    next: NextFunction;
+    params: Input<P>;
+    query: Input<Q>;
+    body: Input<B>;
+}
+/**
+ * An answer: its schema, and the sentence the document gives it. A bare
+ * schema is described by its status (`Successful response`, `Bad request`…).
+ */
+export interface RouteResponse {
+    schema: TSchema;
+    description?: string;
+}
+/** A route, as declared and as recorded for the OpenAPI document. */
+export interface RouteDefinition<P extends TSchema | undefined = undefined, Q extends TSchema | undefined = undefined, B extends TSchema | undefined = undefined> {
+    method: RouteMethod;
+    path: string;
+    /** The path parameters, checked and converted from their string form */
+    params?: P;
+    /** The query parameters, checked and converted from their string form */
+    query?: Q;
+    /** The parsed body */
+    body?: B;
+    /**
+     * Whether a caller that does not accept JSON is refused before the handler
+     * (default). A route answering another media type sets it false.
+     */
+    json?: boolean;
+    /** Handlers run before the declaration's, as Express mounts them */
+    middleware?: RequestHandler | RequestHandler[];
+    /** The answers, for the OpenAPI document */
+    responses?: Partial<Record<number, TSchema | RouteResponse>>;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    handler: (input: RouteInput<P, Q, B>) => void | Promise<void>;
+}
+/** A route recorded on an app, with its schemas kept for the document. */
+export type RegisteredRoute = Omit<RouteDefinition<TSchema, TSchema, TSchema>, 'handler' | 'middleware'>;
+/**
+ * The routes `defineRoute` registered on an app, in declaration order.
+ *
+ * @param app the express app the plugin was given
+ * @returns its routes
+ */
+export declare const registeredRoutes: (app: Express) => readonly RegisteredRoute[];
+/** A route Express carries, as the stack spells it. */
+export interface StackRoute {
+    method: string;
+    path: string;
+}
+/**
+ * The routes an app carries that `defineRoute` did not declare.
+ *
+ * The stack is walked at any depth, so a mounted router's routes are seen
+ * too. A route is matched on its method and path, which is what the
+ * declaration records; a router's routes are router-relative (`/nested`,
+ * whatever the mount path), as Express keeps no mount path on a router, and
+ * `app.all` comes back as `_ALL`.
+ *
+ * @param app the express app
+ * @returns the undeclared routes, in stack order
+ */
+export declare const unregisteredRoutes: (app: Express) => StackRoute[];
+/**
+ * Declare an HTTP route.
+ *
+ * The declared schemas are checked before the handler runs; a request that
+ * fails them is a {@link BadRequestError} naming every failing path, so the
+ * middleware answers it as any other client error. The handler receives the
+ * checked values and answers through `res`, as with `asyncHandler`, whose
+ * rejections it still forwards.
+ *
+ * The declaration is recorded on the app, with its schemas, for the OpenAPI
+ * document and for the check that no route escapes it.
+ *
+ * @param app the express app the plugin was given
+ * @param route the declaration
+ */
+export declare const defineRoute: <P extends TSchema | undefined = undefined, Q extends TSchema | undefined = undefined, B extends TSchema | undefined = undefined>(app: Express, route: RouteDefinition<P, Q, B>) => void;
+export {};