ldap-rest 1.1.0 → 1.2.0

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

@@ -0,0 +1,64 @@
+import type { AttributesList, AttributeValue, ModifyRequest } from '../ldapActions';
+import type { Schema } from '../../config/schema';
+export interface EntityValidatorDeps {
+    /**
+     * Tells whether a DN names an entry. Asked as the server: a reference to
+     * an entry the caller cannot read is still a valid reference.
+     */
+    entryExists: (dn: string) => Promise<boolean>;
+    /** Asked whether a `generated` attribute will be filled after validation */
+    loadedPlugins: Record<string, unknown>;
+    /** Names the entity in the messages */
+    singularName: string;
+}
+/**
+ * Enforces an entity schema on what a client sends: the entry of a creation
+ * and the parts of a change. Every refusal is a `BadRequestError`.
+ *
+ * See `docs/client-development/schemas/README.md` for the rules.
+ */
+export declare class EntityValidator {
+    private readonly schema;
+    private readonly deps;
+    constructor(schema: Schema | undefined, deps: EntityValidatorDeps);
+    /**
+     * Check a new entry, then convert it in place for the directory.
+     *
+     * @param entry entry as the client sent it, `objectClass` included
+     */
+    validateNew(entry: AttributesList): Promise<void>;
+    /**
+     * 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`.
+     *
+     * @param changes change as the client sent it
+     */
+    validateChanges(changes: ModifyRequest): Promise<void>;
+    /**
+     * Check one value against its attribute's rules: its shape, then the
+     * entries a pointer names, then the pattern.
+     *
+     * @param field attribute name, as the client wrote it
+     * @param value value sent; no value clears the attribute
+     * @returns the value in the shape of the type: one value for a
+     *   single-valued attribute, a list for an `array`
+     */
+    validateValue(field: string, value: AttributeValue | null | undefined): Promise<AttributeValue | null | undefined>;
+    /**
+     * The schema's definition of an attribute, under any case.
+     *
+     * @throws BadRequestError for a name a strict schema does not declare
+     */
+    private attribute;
+}
+/**
+ * Write every fixed attribute with a default as the schema says, whatever
+ * the request carried. `objectClass` is left to the entity's configuration.
+ * Run on the entry an authorization judges, so that it judges the entry
+ * written.
+ *
+ * @param schema entity schema, nothing to apply without one
+ * @param entry entry about to be created, changed in place
+ */
+export declare function applyFixedDefaults(schema: Schema | undefined, entry: AttributesList): void;

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

@@ -13,6 +13,25 @@ import type winston from 'winston';
 export declare const setLogger: (logger: winston.Logger | undefined) => void;
 /** @returns the installed logger, or undefined before any `DM` exists */
 export declare const getLogger: () => winston.Logger | undefined;
+/**
+ * Whether `serverError` names the failure in its answer: the `--debug` of
+ * the server, installed as its logger is.
+ *
+ * @param debug true to name the failure in the response
+ */
+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`.
+ *
+ * @param err what failed
+ * @param debug whether to name the failure; `serverError`'s setting by default
+ */
+export declare const serverErrorBody: (err: unknown, debug?: boolean) => {
+    error: string;
+    message: string;
+};
 export declare const tryMethod: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const tryMethodData: (res: Response, method: Function, ...args: unknown[]) => Promise<void>;
 export declare const ok: (res: Response, data?: object) => void;

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

@@ -0,0 +1,63 @@
+import type { Express } from 'express';
+import type { MaybePromise } from '../hooks';
+/** What a plugin answers about the resources it depends on */
+export type HealthStatus = 'ok' | 'degraded';
+/** The paths of the two probes, served before authentication */
+export declare const HEALTH_PATHS: readonly ["/healthz", "/readyz"];
+/** How long one readiness answer serves */
+export declare const PROBE_TTL_MS = 5000;
+/**
+ * How long a readiness answer may take, the directory and every plugin
+ * asked at once: under the 3 s a kubelet waits, so that a hanging resource
+ * is reported, not timed out
+ */
+export declare const PROBE_TIMEOUT_MS = 2000;
+/** What the readiness probe reads of the server */
+export interface Probed {
+    /** Every plugin loaded and the composition checked */
+    readonly composed: boolean;
+    /** Told to stop: what is in flight finishes, nothing new is taken */
+    readonly stopping: boolean;
+    readonly ldap: {
+        ping: (timeoutMs: number) => Promise<void>;
+    };
+    readonly loadedPlugins: {
+        [name: string]: {
+            health?: () => MaybePromise<HealthStatus>;
+        };
+    };
+}
+export interface Readiness {
+    /** `starting`, `stopping` and `unavailable` answer 503, the two others 200 */
+    status: 'starting' | 'stopping' | 'ok' | 'degraded' | 'unavailable';
+    ldap?: 'ok' | 'failed';
+    /** The plugins implementing `health()`; `failed` when it threw or hung */
+    plugins?: {
+        [name: string]: HealthStatus | 'failed';
+    };
+}
+/**
+ * Tell whether the server can serve: loaded, with a directory that answers.
+ * A plugin's resource being down degrades the answer without failing it,
+ * so that one broken outbound service does not take every replica out of
+ * rotation.
+ *
+ * One answer serves `PROBE_TTL_MS`, and the probes arriving while it is
+ * made share it: a probe every few seconds from every replica, or a flood
+ * on an unauthenticated route, must not become a load on the directory nor
+ * on what the plugins ask.
+ *
+ * @param server what is probed
+ * @param now the moment, for the answer's age
+ * @param timeoutMs how long the whole answer may take
+ */
+export declare function readiness(server: Probed, now?: number, timeoutMs?: number): Promise<Readiness>;
+/**
+ * Serve `GET /healthz`, which answers as long as the process serves, and
+ * `GET /readyz`, which answers 200 when `readiness` says the server can
+ * serve. Both are outside the API prefix and carry no identity.
+ *
+ * @param app the application, before its authentication
+ * @param server what the readiness probe reads
+ */
+export declare function mountHealth(app: Express, server: Probed): void;

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

@@ -69,6 +69,8 @@ export interface InstanceProvider {
 declare abstract class HttpProvider {
     protected readonly domain: string;
     protected readonly timeout: number;
+    /** The `target` label of this provider's calls in the outbound metrics */
+    protected abstract readonly target: string;
     constructor(domain: string, timeout: number);
     address(request: InstanceRequest): string;
     protected call(url: string, init?: RequestInit): Promise<Response>;
@@ -79,6 +81,7 @@ export declare class ClouderyProvider extends HttpProvider implements InstancePr
     private readonly url;
     private readonly token;
     private readonly offer;
+    protected readonly target = "cloudery";
     constructor(url: string, token: string, domain: string, offer: string, timeout: number);
     private headers;
     create(request: InstanceRequest): Promise<undefined>;
@@ -97,6 +100,7 @@ export declare class CozyStackProvider extends HttpProvider implements InstanceP
     private readonly url;
     private readonly context;
     private readonly apps;
+    protected readonly target = "cozy-stack";
     private readonly auth;
     constructor(url: string, user: string, passphrase: string, domain: string, context: string, apps: string, timeout: number);
     private headers;

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

@@ -126,11 +126,39 @@ declare class ldapActions {
      * 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
+     */
+    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.
+     */
+    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;
+        max: number;
+    };
+    private takeConnection;
     /**
      * Release a connection back to the pool
      * If there are waiting requests, hand off the connection directly

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

@@ -0,0 +1,44 @@
+/**
+ * What the server measures of itself, for `core/metrics` to expose; see
+ * docs/usage/operations.md#metrics
+ * @module lib/metrics
+ */
+import type { Request } from 'express';
+import { Counter, Histogram, Registry } from 'prom-client';
+/** The instruments below register here; `core/metrics` adds its own */
+export declare const registry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+export declare const httpRequestDuration: Histogram<"status" | "method" | "route">;
+export type LdapOperation = 'bind' | 'search' | 'add' | 'modify' | 'rename' | 'delete';
+export declare const ldapOperationDuration: Histogram<"operation" | "result">;
+export declare const ldapPoolWait: Histogram<string>;
+export declare const ldapSearchCache: Counter<"result">;
+export declare const hookFailures: Counter<"plugin" | "hook">;
+export declare const outboundRequestDuration: Histogram<"status" | "target">;
+export declare const unhandledRejections: Counter<string>;
+/**
+ * The `result` label of a directory call that threw: a refusal is the
+ * directory answering, by its result code (32 for an entry that is not
+ * there); `error` is for not answering.
+ */
+export declare const ldapResult: (err: unknown) => string;
+/** @returns the seconds since `started`, a `process.hrtime.bigint()` */
+export declare const secondsSince: (started: bigint) => number;
+/**
+ * Time a directory call into the operation histogram, whatever becomes of
+ * it.
+ */
+export declare function timedLdap<T>(operation: LdapOperation, call: () => Promise<T>): Promise<T>;
+/**
+ * Time a call to another service into the outbound histogram, to its
+ * answer's headers: the body is read by the caller, at its own pace.
+ */
+export declare function timedOutbound<T extends {
+    status: number;
+}>(target: string, call: () => Promise<T>): Promise<T>;
+/**
+ * The template of the route that answered, never the URL: a label per URL
+ * would grow without bound. See docs/usage/operations.md#metrics.
+ *
+ * @returns the template, `none` when no route matched
+ */
+export declare const routeTemplate: (req: Request) => string;

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

@@ -21,3 +21,43 @@ export declare function outsideRequest<T>(fn: () => T): T;
  * @returns the request, or undefined outside any, or as the server
  */
 export declare function currentRequest(): Request | undefined;
+/** What a log line carries beside what it says */
+export interface LogContext {
+    /** The request being served */
+    requestId?: string;
+    /** The plugin whose hook is running */
+    plugin?: string;
+    /** That hook */
+    op?: string;
+}
+/**
+ * Run something that outlives the request being served, a connection
+ * opened for the pool or a client kept for the process: its operations are
+ * judged by nobody, and what it logs later is nobody's request.
+ *
+ * @param fn what to run
+ * @returns what it returns
+ */
+export declare function outsideAnyRequest<T>(fn: () => T): T;
+/**
+ * Serve a request with its log context: what runs inside, synchronously or
+ * not, logs with it.
+ *
+ * @param context what the lines carry
+ * @param fn what serves the request
+ * @returns what `fn` returns
+ */
+export declare function runWithLogContext<T>(context: LogContext, fn: () => T): T;
+/**
+ * Run a hook: what it logs names its plugin and itself, under the request
+ * being served; a hook no plugin registered names none, even inside
+ * another's.
+ *
+ * @param plugin the plugin's instance name, none for an unregistered hook
+ * @param op the hook
+ * @param fn the hook's run
+ * @returns what `fn` returns
+ */
+export declare function runAsPlugin<T>(plugin: string | undefined, op: string | undefined, fn: () => T): T;
+/** The log context of what is running, if any: request, plugin, hook */
+export declare function currentLogContext(): LogContext | undefined;

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

@@ -0,0 +1,20 @@
+export type ShutdownCallback = () => void | Promise<void>;
+/**
+ * How long the shutdown callbacks get before the signal is raised again.
+ * The binary sets it from `--shutdown-timeout`.
+ */
+export declare const shutdownTimeout: {
+    ms: number;
+};
+/**
+ * Run a callback when the process is told to stop. The first registration
+ * installs the signal listeners; a callback registered while the shutdown
+ * runs is awaited with the others.
+ *
+ * Once every callback has settled, or the timeout has passed, the signal is
+ * raised again for its default action, unless another listener is there to
+ * decide.
+ *
+ * @param cb what to run, awaited when it answers a promise
+ */
+export declare function registerProcessShutdown(cb: ShutdownCallback): void;

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

@@ -0,0 +1,33 @@
+/**
+ * Where the static plugins serve a schema file, for another plugin to
+ * announce it
+ * @module lib/staticFiles
+ */
+import type { DM } from '../bin';
+/** A static plugin, as another plugin asks it where it serves a file */
+export interface StaticFiles {
+    schemaUrlOf(file: string): string | undefined;
+    servedPath(): string;
+}
+/** Told by its methods, not its class: another copy of ldap-rest has its own */
+export declare const isStaticFiles: (plugin: unknown) => plugin is StaticFiles;
+/**
+ * The static plugins loaded, whatever their class or name: one loaded under
+ * another name, or with a name or a directory of its own, serves files
+ * elsewhere or not at all. The one registered as `static` comes first; one
+ * whose path an earlier plugin took, lies under it or holds it, is left
+ * out, the earlier one's routes answering first.
+ *
+ * @param server the server whose plugins are asked
+ * @returns the plugins, in the order to ask them
+ */
+export declare function staticPlugins(server: Pick<DM, 'loadedPlugins'>): StaticFiles[];
+/**
+ * URL a static plugin serves a schema file at, merged, asked of
+ * {@link staticPlugins} in their order
+ *
+ * @param server the server whose plugins are asked
+ * @param file the file, as the plugin announcing it reads it
+ * @returns its URL, or undefined when no static plugin serves it merged
+ */
+export declare function staticSchemaUrl(server: Pick<DM, 'loadedPlugins'>, file: string): string | undefined;

package/dist/src/lib/storage/store.d.ts

@@ -26,6 +26,7 @@
  * @group Libraries
  */
 import type winston from 'winston';
+import type { HealthStatus } from '../health';
 /** What a backend keeps: a value, and when it stops counting. */
 export interface StoredRecord {
     value: string;
@@ -45,6 +46,11 @@ export default abstract class Store {
     protected abstract drop(key: string): Promise<void>;
     /** Drop every expired record. Returns how many went. */
     abstract sweep(): Promise<number>;
+    /**
+     * Whether the backend answers, asked by the readiness probe; a backend
+     * with a resource of its own asks it and throws when it does not answer.
+     */
+    health(): Promise<HealthStatus>;
     /**
      * The key a backend actually sees, namespaced so two consumers cannot
      * collide.
@@ -72,6 +78,8 @@ export default abstract class Store {
      * operator reads it, instead of the first request that needs the store.
      */
     open(): Promise<void>;
+    /** Set by `close`: a backend opens nothing past it */
+    protected closed: boolean;
     /** Stop sweeping and let go of any connection. */
     close(): Promise<void>;
     /**

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

@@ -22,6 +22,15 @@ export declare function getCompiledRegex(pattern: string, flags?: string): RegEx
  * @returns The escaped string safe for use in RegExp
  */
 export declare function escapeRegex(str: string): string;
+/**
+ * Run a hook under its plugin's name and its own, for the lines it logs:
+ * what `launchHooks` does, for a caller walking the hooks itself.
+ *
+ * @param hook the registered function
+ * @param fn its run
+ * @returns what `fn` returns
+ */
+export declare const runAsHookOwner: <T>(hook: Function, fn: () => T) => T;
 export declare const launchHooks: (hooks: Function[] | undefined, ...args: unknown[]) => Promise<void>;
 /**
  * Record the plugin a hook function belongs to.

package/dist/src/logger/winston.d.ts

@@ -5,4 +5,8 @@ declare module 'winston' {
         notice: winston.LeveledLogMethod;
     }
 }
+/**
+ * @throws when `--logger` names no known logger, or `--logger file` has no
+ * file: never a file nobody asked for
+ */
 export declare const buildLogger: (config: Config) => winston.Logger;

package/dist/src/plugins/ldap/groups.d.ts

@@ -14,6 +14,7 @@ import type { Hooks } from '../../hooks';
 import type ldapActions from '../../lib/ldapActions';
 import type { AttributesList, AttributeValue, LdapList, ModifyRequest } from '../../lib/ldapActions';
 import type { Schema } from '../../config/schema';
+import { EntityValidator } from '../../lib/entitySchema/validator';
 export interface postAdd {
     cn?: string;
     [key: string]: AttributeValue | undefined;
@@ -308,9 +309,23 @@ export default class LdapGroups extends DmPlugin {
      * @returns nothing, throw if error
      */
     validateMembers(dn: string, members: string[], req?: Request): Promise<void>;
-    validateNewGroup(dn: string, entry: AttributesList): Promise<boolean>;
-    validateChanges(dn: string, changes: ModifyRequest): Promise<boolean>;
-    _validateOneChange(field: string, value: AttributeValue | null): Promise<boolean>;
+    /**
+     * Check a new group's entry, after the `ldapgroupvalidatenew` hooks, and
+     * convert it in place.
+     *
+     * @returns the entry the hooks handed on; `addGroup` writes its
+     *   attributes over the entry it judged, the members aside
+     */
+    validateNewGroup(dn: string, entry: AttributesList): Promise<AttributesList>;
+    /**
+     * Check a change, after the `ldapgroupvalidatechanges` hooks, and convert
+     * it in place.
+     *
+     * @returns the change the hooks handed on
+     */
+    validateChanges(dn: string, changes: ModifyRequest): Promise<ModifyRequest>;
+    /** The schema's rules; the pointer lookups run as the server */
+    validator(): EntityValidator;
     /**
      * Provide configuration for config API
      */

package/dist/src/plugins/ldap/organizations.d.ts

@@ -2,7 +2,7 @@ import type { Express, Request, Response } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import { DM } from '../../bin';
 import { Hooks } from '../../hooks';
-import { AttributesList, AttributeValue, ModifyRequest } from '../../lib/ldapActions';
+import { AttributesList, ModifyRequest } from '../../lib/ldapActions';
 import type { Schema } from '../../config/schema';
 /**
  * Shared OpenAPI schemas surfaced by this plugin. Picked up by
@@ -231,10 +231,8 @@ export default class LdapOrganizations extends DmPlugin {
     private linkedEntities;
     addOrganization(dn: string, entry: AttributesList, req?: Request): Promise<boolean>;
     modifyOrganization(dn: string, changes: ModifyRequest, req?: Request): Promise<boolean>;
-    validateNewOrganization(dn: string, entry: AttributesList): Promise<boolean>;
-    invalidValueMessage(field: string): string;
-    validateChanges(dn: string, changes: ModifyRequest): Promise<boolean>;
-    _validateOneChange(field: string, value: AttributeValue | null): Promise<boolean>;
+    /** The schema's rules; the pointer lookups run as the server */
+    private validator;
     /**
      * Tell whether a DN names an existing entry.
      *

package/dist/src/plugins/metrics.d.ts

@@ -0,0 +1,17 @@
+import type { Express } from 'express';
+import DmPlugin from '../abstract/plugin';
+import type { DM } from '../bin';
+export default class Metrics extends DmPlugin {
+    name: string;
+    /** The gauges read at scrape time and the process metrics */
+    private readonly own;
+    private readonly exposed;
+    private listener?;
+    constructor(server: DM);
+    /** Open the listener; the server does not start on a port it cannot take */
+    api(_app: Express): Promise<void>;
+    /** @returns the port the metrics are served on, once `api` opened it */
+    port(): number | undefined;
+    private answer;
+    close(): Promise<void>;
+}

package/dist/src/plugins/rabbitmq.d.ts

@@ -19,6 +19,7 @@
  */
 import DmPlugin from '../abstract/plugin';
 import type { DM } from '../bin';
+import type { HealthStatus } from '../lib/health';
 /** JSON-serialisable message payload. */
 export type RabbitMessage = Record<string, unknown>;
 /** Async handler invoked for each consumed message. */
@@ -46,6 +47,18 @@ interface RabbitClient {
     subscribe(exchange: string, routingKey: string, queue: string, handler: RabbitMessageHandler, options?: SubscribeOptions): Promise<void>;
     unsubscribe(queue: string): Promise<void>;
     close(clearSubscriptions?: boolean): Promise<void>;
+    isConnected(): boolean;
+}
+/** The logging contract of `@linagora/rabbitmq-client`: message first, then a context */
+interface ClientLogger {
+    debug(message: string, context?: unknown): void;
+    info(message: string, context?: unknown): void;
+    warn(message: string, context?: unknown): void;
+    error(message: string, context?: unknown): void;
+}
+interface RabbitClientOptions {
+    url: string;
+    logger: ClientLogger;
 }
 export default class RabbitMq extends DmPlugin {
     name: string;
@@ -59,6 +72,13 @@ export default class RabbitMq extends DmPlugin {
      * the broker is reachable — the connection is still lazy.
      */
     isAvailable(): boolean;
+    /**
+     * Degraded when a broker is configured and no connection to it stands:
+     * the state as it is, nothing opened for the probe, which would run the
+     * client's connection attempts on every probe while the broker is away.
+     * A plugin without a broker has nothing to report.
+     */
+    health(): HealthStatus;
     /**
      * Publish a JSON message to a topic exchange. No-op (returns silently) when
      * no broker is configured or the client is unavailable.
@@ -89,6 +109,22 @@ export default class RabbitMq extends DmPlugin {
      * retry policy in `getClient()` can be tested without a live broker.
      */
     protected connect(): Promise<RabbitClient>;
-    private registerShutdown;
+    /**
+     * Build and initialise a client of the given class: a test hands in a stub
+     * to see what the client is built with.
+     */
+    protected open(Client: new (options: RabbitClientOptions) => unknown): Promise<RabbitClient>;
+    /**
+     * The client's lines go through the plugin's logger, under its name, so
+     * they follow `--logger` and `--log-level`; without one the client writes
+     * to the console. An `Error` in the context is written as text: the JSON
+     * format keeps only its enumerable fields, which for a channel error is
+     * the code without the broker's message.
+     */
+    private clientLogger;
+    /** Set by `close`: a publish of what outlives the drain opens nothing */
+    private closed;
+    /** Close the broker connection; nothing opens one after */
+    close(): Promise<void>;
 }
 export {};

package/dist/src/plugins/static.d.ts

@@ -65,6 +65,18 @@ export default class Static extends DmPlugin {
      * @returns its URL, or undefined when this plugin does not serve it
      */
     urlOf(file: string): string | undefined;
+    /**
+     * The URL its schema routes serve a schema file at, merged with what it
+     * extends and its placeholders replaced, for another plugin to announce
+     * it: one of the configuration's schema files it serves, or a file its
+     * `schemas/` directory reaches, through a link included. One that
+     * express.static would send as it stands, outside `schemas/` or not named
+     * `.json`, has none.
+     *
+     * @param file the schema file, as the other plugin reads it
+     * @returns its URL, or undefined when its schema routes do not serve it
+     */
+    schemaUrlOf(file: string): string | undefined;
     /** The path it serves under, which an earlier plugin may have taken */
     servedPath(): string;
     /**

package/dist/src/plugins/storage/file.d.ts

@@ -1,5 +1,6 @@
 import type winston from 'winston';
 import Store, { type StoredRecord } from '../../lib/storage/store';
+import type { HealthStatus } from '../../lib/health';
 export default class FileStore extends Store {
     name: string;
     private dir;
@@ -8,6 +9,9 @@ export default class FileStore extends Store {
     constructor(logger: winston.Logger, dir: string, abandonedAfterSeconds: number);
     /** The directory is created on demand, readable by this user alone. */
     ready(): Promise<void>;
+    open(): Promise<void>;
+    /** A directory this user may write a record in: entered and written */
+    health(): Promise<HealthStatus>;
     private path;
     /** `<deadline> <key>\n<value>` — the deadline first, so a short read still has it. */
     private static encode;

package/dist/src/plugins/storage/postgres.d.ts

@@ -1,19 +1,6 @@
-/**
- * @module plugins/storage/postgres
- *
- * A keyed store kept in one PostgreSQL table.
- *
- * `pg` is an optional dependency, loaded when this backend is chosen: a
- * deployment that keeps its records elsewhere never needs it installed.
- *
- * The key is kept verbatim, split into the consumer's namespace and its own
- * key: a `text` column has no reason to hash it the way a DN or a file name
- * must, so a `SELECT` says what a record is about.
- *
- * @group Plugins
- */
 import type winston from 'winston';
 import Store, { type StoredRecord } from '../../lib/storage/store';
+import { type HealthStatus } from '../../lib/health';
 type Pg = typeof import('pg');
 export default class PostgresStore extends Store {
     name: string;
@@ -26,6 +13,12 @@ export default class PostgresStore extends Store {
     /** Split out so a test can stand in for a missing package. */
     protected driver(): Promise<Pg>;
     open(): Promise<void>;
+    /**
+     * On a client of its own, closed after, with the budget as its timeouts:
+     * a query the pool never got an answer to would hold one of its
+     * connections for as long as the socket lives
+     */
+    health(): Promise<HealthStatus>;
     close(): Promise<void>;
     /**
      * The pool, once the table is known to be there. A failure is not kept:

package/dist/src/plugins/storage/valkey.d.ts

@@ -1,20 +1,6 @@
-/**
- * @module plugins/storage/valkey
- *
- * A keyed store kept in Valkey, or Redis.
- *
- * `iovalkey` is an optional dependency, loaded when this backend is chosen: a
- * deployment that keeps its records elsewhere never needs it installed.
- *
- * The only backend that expires its own records, so it has nothing to sweep.
- * The value still carries its deadline, in the shape the LDAP store uses:
- * reads judge expiry by it, as with every other backend, and the TTL only
- * reclaims the memory.
- *
- * @group Plugins
- */
 import type winston from 'winston';
 import Store, { type StoredRecord } from '../../lib/storage/store';
+import type { HealthStatus } from '../../lib/health';
 type IoValkey = typeof import('iovalkey');
 export default class ValkeyStore extends Store {
     name: string;
@@ -27,6 +13,7 @@ export default class ValkeyStore extends Store {
     /** Split out so a test can stand in for a missing package. */
     protected driver(): Promise<IoValkey>;
     open(): Promise<void>;
+    health(): Promise<HealthStatus>;
     close(): Promise<void>;
     /**
      * The client, once connected. A failed first connection is not kept: the