ldap-rest 1.2.1 → 2.0.0

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

@@ -1,12 +1,16 @@
+/**
+ * LDAP low-level library
+ * @author Xavier Guimard <xguimard@linagora.com>
+ */
 import type { Request } from 'express';
-import type { ClientOptions, SearchResult, SearchOptions } from 'ldapts';
+import type { SearchResult, SearchOptions } from 'ldapts';
 import type winston from 'winston';
 import pLimit from 'p-limit';
 import { type Config } from '../config/args';
 import { type DM } from '../bin';
 import type { Hooks } from '../hooks';
 import { type ChangeContext } from './changeContext';
-import { SchemaIndex } from './ldapSchema';
+import type { SchemaIndex } from './ldapSchema';
 export type AttributeValue = Buffer | Buffer[] | string[] | string;
 export type AttributesList = Record<string, AttributeValue>;
 export type LdapList = Record<string, AttributesList>;
@@ -68,148 +72,34 @@ export interface ModifyOptions {
 type AuthorizedHook = 'ldapaddrequest' | 'ldapmodifyrequest' | 'ldapdeleterequest' | 'ldaprenamerequest';
 declare class ldapActions {
     config: Config;
-    options: ClientOptions;
-    dn: string;
-    pwd: string;
     base: string;
     parent: DM;
     logger: winston.Logger;
-    private searchCache;
-    private cacheEnabled;
-    /**
-     * How many writes this instance has made since it was built.
-     *
-     * A read can be overtaken by a write: the write lands and `invalidateCache`
-     * finds nothing to drop, because the read has not stored its answer yet —
-     * and the read then stores what it read *before* the write, an entry
-     * nothing will drop until its TTL runs out. `search()` remembers the count
-     * it started at and stores only if no write happened in between, so a read
-     * a write overtook costs a cache entry, never a stale answer.
-     *
-     * The count is per instance and per write, not per DN: a write to another
-     * branch keeps a concurrent read out of the cache too. That is hit rate
-     * given up, not freshness.
-     */
-    private cacheGeneration;
+    private cache;
     queryLimit: ReturnType<typeof pLimit>;
-    private connectionPool;
-    private poolSize;
-    private connectionTtl;
-    private ldapUrls;
-    private currentUrlIndex;
-    private attrSignatureCache;
-    private waitingResolvers;
-    private availableConnections;
-    private isCleaningUp;
-    /** See {@link declareObjectClasses}. */
-    private declaredClasses;
-    private schemaCache?;
-    private schemaLoading?;
-    /** Whether the last schema read failed, so a failure is logged once. */
-    private schemaUnavailable;
-    /**
-     * How this server spells attribute names, by name in lower case: the
-     * configuration's, then the loaded schemas'. See {@link canonicalName}.
-     */
-    private spellings;
-    /** The first name given for each attribute type, to warn of another. */
-    private spelledTypes;
-    /** Class problems already reported, per entry. See {@link warnOnce}. */
-    private classWarnings;
+    private pool;
+    private schema;
+    private caller;
     constructor(server: DM);
-    /**
-     * Create a new LDAP connection with failover support
-     */
-    private createConnection;
-    /**
-     * Clean up expired connections from the pool
-     * Uses a flag to prevent concurrent cleanup operations
-     */
-    private cleanupExpiredConnections;
-    /**
-     * Ask the directory for its root DSE on a connection of its own, bound
-     * as the server and closed after: the readiness probe. Neither the pool
-     * nor the search cache nor the hooks answer for a directory that does
-     * not, and a directory that stops answering holds nothing of the pool.
-     * The URLs are tried as `createConnection` tries them.
-     *
-     * @param timeoutMs how long the connection, the bind and the search may
-     *   each take; the client closes the socket when it passes
-     * @throws when no URL answers in time
-     */
+    /** See {@link LdapPool.ping}. */
     ping(timeoutMs: number): Promise<void>;
-    /** Set by `close`: no connection is handed out any more */
-    private closed;
-    /**
-     * Close every pooled connection, the ones in use included: an operation
-     * still running on one is rejected by the client, and a waiter is refused
-     * rather than kept.
-     */
+    /** See {@link LdapPool.close}. */
     close(): Promise<void>;
-    /**
-     * Acquire a connection from the pool or create a new one
-     * Optimized for O(1) lookup using separate available connections queue
-     */
-    private acquireConnection;
     /** The pool as it is, for the metrics */
     poolStats(): {
         busy: number;
         idle: number;
         waiting: number;
+        opening: number;
         max: number;
     };
-    private takeConnection;
-    /**
-     * Release a connection back to the pool
-     * If there are waiting requests, hand off the connection directly
-     */
-    private releaseConnection;
-    /**
-     * Get a sorted signature for attribute list, using cache for performance
-     */
-    private getAttributeSignature;
-    /**
-     * Generate cache key for LDAP search
-     *
-     * Every option that changes the answer belongs in here, or a search that
-     * asked for more is served what a search that asked for less got: the
-     * requested attributes above all, but also the ones that change the shape
-     * of what comes back. `timeLimit` is deliberately absent — it bounds how
-     * long the server may spend, not what it returns.
-     */
-    private getCacheKey;
     /**
      * Drop every cached read of `dn`, and of everything below it.
      *
      * Called after each write, so the next read of what just changed goes to
-     * the directory. Two things this does that a `key.startsWith(dn)` test did
-     * not: it compares DNs the way the directory does (see {@link foldDn}), so
-     * a write spelling a DN differently from the read that cached it still
-     * drops it; and it drops the subtree, because `rename()` and `move()`
-     * re-parent a whole branch in one operation — renaming an organization
-     * changes the DN of every entry under it — leaving the cached reads of
-     * those children filed under DNs that no longer exist. A leaf has nothing
-     * below it and the extra test costs nothing.
+     * the directory. See {@link SearchCache.invalidate}.
      */
     invalidateCache(dn: string): void;
-    /**
-     * Drop every cached read holding a value that names `dn`, or an entry
-     * below it.
-     *
-     * The directory mirrors some writes onto other entries than the one
-     * written: the `memberof` overlay keeps each member's `memberOf` in step
-     * with the group's `member` / `uniqueMember`, and `refint` rewrites or
-     * removes the references to an entry renamed or deleted. Those entries'
-     * cached reads are what {@link invalidateCache} cannot find, and they name
-     * the entry written: the members of a group name it in their `memberOf`.
-     * A member a write adds names it only once the write has landed; the
-     * caller drops those by their own DN.
-     *
-     * Every attribute is looked at, not `memberOf` alone: which attributes an
-     * overlay maintains is the deployment's configuration. A read naming `dn`
-     * for another reason is dropped too, which costs a miss.
-     */
-    private invalidateReferences;
     /**
      * The directory as the server itself, with no request behind it.
      *
@@ -242,20 +132,7 @@ declare class ldapActions {
      * hooks always see it. See {@link RequestBoundLdap}.
      */
     forRequest(req: Request): RequestBoundLdap;
-    /**
-     * Whether the caller of a request can read an entry.
-     *
-     * For a route that finds an entry as the server — by an attribute, across
-     * branches — and then answers about it: an entry the caller cannot read
-     * must get the answer an entry that is not there gets, or the route tells
-     * them what the directory holds where they cannot read. Refused or
-     * filtered out by an authorization plugin, the entry reads as absent.
-     * Without a request, as for any operation, nobody judges.
-     *
-     * @param dn the entry
-     * @param req the request whose caller asks
-     * @returns whether a read of the entry, as that caller, finds it
-     */
+    /** See {@link CallerView.readableBy}. */
     readableBy(dn: string, req?: Request): Promise<boolean>;
     /**
      * Have the authorization plugins judge an operation, without making it.
@@ -277,134 +154,27 @@ declare class ldapActions {
      * @throws the refusal of the first authorization plugin refusing
      */
     authorize<H extends AuthorizedHook>(hook: H, args: Parameters<NonNullable<Hooks[H]>>[0]): Promise<void>;
-    /**
-     * Declare the object classes an entity gives the entries of its branch.
-     *
-     * An entry created by another tool may lack some of them, and a class it
-     * lacks can forbid an attribute written here: the organization link of an
-     * account made as a bare `inetOrgPerson` is refused by the directory. A
-     * modify writing such an attribute adds the auxiliary class that allows
-     * it, see {@link classRepair}.
-     *
-     * @param base branch holding the entity's entries
-     * @param classes object classes the entity's schema declares; a schema
-     * file may give a single one as a string
-     * @param includeBase whether the base is itself one of the entries, as the
-     * top organization is
-     */
+    /** See {@link DirectorySchema.declareObjectClasses}. */
     declareObjectClasses(base: string, classes: string[] | string, includeBase?: boolean): void;
-    /**
-     * The classes declared for the branch holding a DN. Several entities may
-     * share a branch — the shipped `users`, `posixAccounts` and
-     * `sshPublicKeys` schemas all live in `ou=users` — so every declaration at
-     * the deepest matching base counts.
-     */
-    private declaredFor;
-    /**
-     * Log a class problem of an entry once, not on every write to it: nothing
-     * an administrator can do stops a sync job from touching it again.
-     */
-    private warnOnce;
-    /**
-     * The auxiliary classes a modify needs added: for each attribute it writes
-     * that the entry's classes do not allow, a class declared for its branch
-     * or by the writer that allows it, provided the entry holds or receives
-     * that class's mandatory attributes once the change is applied.
-     *
-     * Only what the write needs is added. Entities sharing a branch declare
-     * classes that are not all meant for every entry: `shadowAccount` is not
-     * something every account should be given because it sits in `ou=users`.
-     * And a write that the directory would have accepted is never changed.
-     *
-     * Nothing is added when the change names `objectClass` itself, and a
-     * schema or entry that cannot be read skips the repair.
-     *
-     * @param dn entry being modified
-     * @param changes the modification, after the hooks
-     * @param extra classes the writer declares, see {@link ModifyOptions}
-     * @returns names of the classes to add, or `allowed` when the entry's
-     * classes take the change as it is
-     */
-    private classRepair;
-    /**
-     * DN of the subschema entry the root DSE advertises, or the conventional
-     * `cn=Subschema` when it advertises none.
-     */
+    /** See {@link DirectorySchema.subschemaDn}. */
     subschemaDn(): Promise<string>;
-    /**
-     * The directory schema, kept for `--ldap-raw-schema-cache-ttl`: it is
-     * large and changes rarely. The raw browser and the object class repair
-     * share it, and concurrent callers share a single read.
-     *
-     * @returns indexed schema
-     */
+    /** See {@link DirectorySchema.schemaIndex}. */
     schemaIndex(): Promise<SchemaIndex>;
-    /**
-     * Say how this server spells attribute names: a schema loaded by a plugin
-     * names its attributes as the plugins compare them. The first spelling of
-     * a name wins.
-     *
-     * @param names attribute names
-     */
+    /** See {@link DirectorySchema.knowAttributeNames}. */
     knowAttributeNames(names: Iterable<string>): void;
-    /**
-     * Name each attribute of a write as this server does, in place.
-     *
-     * The directory takes `MAIL`, `rfc822Mailbox` and `0.9.2342.19200300.100.1.3`
-     * for `mail`, while the authorization plugins and the hooks look for
-     * `mail`: a write naming the organization link by its OID was judged as
-     * if it left the link alone. Each name is resolved through the directory
-     * schema — case, aliases, OIDs — and written as the configuration or a
-     * loaded schema spells it, or as the directory declares it first.
-     *
-     * An option names a value of its own (`member;lang-en` is not `member` to
-     * the hooks guarding `member`), and is refused, `;binary` aside. Two names
-     * for one attribute in one part of a write are refused too: on a modify
-     * the directory applies both, and only one would have been judged.
-     *
-     * Without the schema, the case is still set, and a name given as an OID,
-     * which nothing here could resolve, is refused. So is, with or without
-     * it, a name that is neither a descriptor nor a numeric OID.
-     *
-     * @param entry attributes of an add, or one part of a modify
-     * @throws BadRequestError on an option, on a name that describes no
-     * attribute, or on one attribute named twice
-     */
+    /** See {@link DirectorySchema.canonicalAttributes}. */
     canonicalAttributes(entry: AttributesList | undefined): Promise<void>;
-    /**
-     * {@link canonicalAttributes} for every part of a modify, in place.
-     *
-     * @param changes the modify
-     * @throws BadRequestError as {@link canonicalAttributes}
-     */
+    /** See {@link DirectorySchema.canonicalChanges}. */
     canonicalChanges(changes: ModifyRequest | undefined): Promise<void>;
-    /**
-     * The names of one part of a write, as {@link canonicalAttributes} writes
-     * them.
-     */
-    private canonicalNames;
-    /**
-     * One attribute description, named as this server does.
-     *
-     * @param key the name as written, options included
-     * @param index the directory schema, when it could be read
-     */
-    private canonicalName;
-    /**
-     * Hand a search result to `ldapsearchfilter`, which may drop entries the
-     * caller is not allowed to see.
-     *
-     * Applied on every return path of `search`, and deliberately after the
-     * cache: `ldapsearchresult` fires before caching and knows no request, so
-     * what it removed for one caller would be served to the next. A paginated
-     * search is filtered chunk by chunk, as it is consumed.
-     */
+    /** See {@link CallerView.filter}. */
     private filterForCaller;
     search(options: SearchOptions, base?: string, req?: Request): Promise<SearchResult | AsyncGenerator<SearchResult>>;
     /**
-     * Wrap paginated search to ensure connection is released when done
+     * A paged search, opened on its first page: a generator that is never
+     * started holds no connection. The pool is taken here, in the generator
+     * body, not by `search()`.
      */
-    private wrapPaginatedSearch;
+    private pagedSearch;
     add(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
     modify(dn: string, changes: ModifyRequest, req?: Request, options?: ModifyOptions): Promise<boolean>;
     private applyModify;

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

@@ -9,17 +9,46 @@ export type ArrayKind = 'identifiers' | 'dns' | 'phrases';
 export type ConfigEntry = [
     string,
     string,
-    (string | string[] | boolean | number | Record<string, any>),
+    // env value
+    string | string[] | boolean | number | Record<string, any>,
     ('string' | 'number' | 'boolean' | 'array' | 'json' | null | undefined)?,
     (string | null | undefined)?,
     ArrayKind?,
-    boolean?
+    boolean?,
+    (string[] | null | undefined)?,
+    (string[] | null | undefined)?
 ];
 export declare class ConfigParser {
     private config;
+    /** CLI arguments no entry declared, kept in `Config` by the parser */
+    private unknownArgs;
+    /** Deprecated names the configuration used, reported once each */
+    private readonly deprecated;
+    get unknownOptions(): string[];
+    /** Names read through a deprecated alias, for the server to warn about */
+    get deprecationWarnings(): string[];
+    private warnOnce;
+    /** The entry a CLI name stands for, whether canonical or a deprecated alias */
+    private findEntry;
+    /**
+     * The environment variable an entry reads: its own, or a deprecated alias
+     * when that one is set and its own is not.
+     */
+    private envNameOf;
+    /**
+     * Whether a variable value counts as set. An empty value is unset for the
+     * types that read it as nothing: a compose file expands an unset
+     * `${VAR:-}` to one. For a string or a boolean, an empty value means
+     * something and stays set.
+     */
+    private environmentIsSet;
     constructor(config: ConfigTemplate);
+    /** A deprecated name must not shadow a declared one, or be declared twice */
+    private checkAliases;
     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 {};

package/dist/src/lib/services/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed services between plugins: a token names the interface a consumer
+ * reads and the instance a provider offers, so the compiler checks both.
+ *
+ * @see docs/plugin-development/services.md
+ */
+declare const serviceType: unique symbol;
+/**
+ * What identifies a service: a name for the logs, and the interface it
+ * answers. The type is carried by a phantom property and never exists at
+ * runtime; the object itself is the registry key.
+ */
+export interface ServiceToken<T> {
+    /** Names the service in the logs */
+    readonly name: string;
+    /** Type only, never set: carries the interface a consumer reads */
+    readonly [serviceType]?: T;
+    /**
+     * Bind the instance providing this service, as a plugin's `provides`
+     * declares. The argument must answer the interface the token names.
+     *
+     * @param provider the plugin instance providing the service
+     * @returns the token and its provider
+     */
+    with(provider: T): ServiceProvider<T>;
+}
+/** A token with the instance providing it, as a plugin declares them. */
+export interface ServiceProvider<T> {
+    readonly token: ServiceToken<T>;
+    readonly service: T;
+}
+/**
+ * Declare a service.
+ *
+ * Declare a token once, in a module both the provider and its consumers
+ * import: the object is the registry key, and a second declaration under the
+ * same name would be another service. The name only identifies it in the
+ * logs.
+ *
+ * @param name the service name
+ * @returns the token, carrying its interface
+ */
+export declare const serviceToken: <T>(name: string) => ServiceToken<T>;
+/** What `DM.services` holds: the provided instance for each token. */
+export type ServiceMap = Map<ServiceToken<unknown>, unknown>;
+/**
+ * The instance provided for a token, when a plugin provides it.
+ *
+ * A provider always answers something: `undefined` means nobody provides it.
+ *
+ * @param services the server's registry
+ * @param token the service wanted
+ * @returns the provided instance, or undefined
+ */
+export declare const providedService: <T>(services: ReadonlyMap<ServiceToken<unknown>, unknown>, token: ServiceToken<T>) => T | undefined;
+export {};