@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

package/transpiled/RPC/Dispatcher.js

@@ -0,0 +1,103 @@
+import { console } from 'openspan';
+import * as http from '../HTTP/index.js';
+import { schemas } from '@toa.io/definitions/extensions.exposition';
+import { BATCH } from '@toa.io/definitions/extensions.exposition';
+import { address, split } from './names.js';
+import { fork } from './Context.js';
+import { BATCH_TOO_LARGE, INVALID_REQUEST, PARSE, failure, of, response } from './errors.js';
+import { VERSION } from './types.js';
+/**
+ * JSON-RPC, as the calls a request carries.
+ *
+ * It clones the context per call and hands each clone back to the gateway: it holds no
+ * tree, no index and no knowledge of routing. Whether a name resolves, what it resolves
+ * to, and what the directives of that route do are answered by the same `route` an
+ * ordinary request goes through.
+ */
+export class Dispatcher {
+    batch;
+    constructor(options) {
+        this.batch = options.batch ?? BATCH;
+    }
+    async dispatch(context, route) {
+        if (context.request.method !== 'POST')
+            throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }));
+        const envelope = await this.read(context);
+        const batched = Array.isArray(envelope);
+        const calls = batched ? envelope : [envelope];
+        if (calls.length === 0)
+            throw new http.BadRequest(response(null, failure(INVALID_REQUEST, 'A request carries at least one call')));
+        if (calls.length > this.batch)
+            throw new http.BadRequest(response(null, failure(BATCH_TOO_LARGE, `A request carries at most ${this.batch} calls`)));
+        const answers = [];
+        // one after another: a request the caller writes should not become a fan-out they own
+        for (const call of calls) {
+            const answer = await this.answer(call, context, route);
+            if (answer !== null)
+                answers.push(answer);
+        }
+        // every call was a notification, and a notification is answered by not answering
+        if (answers.length === 0)
+            return { status: NO_CONTENT };
+        // a reply assembled from several is not one of them, and is not stored as if it were
+        return {
+            status: OK,
+            body: batched ? answers : answers[0],
+            headers: new Headers({ 'cache-control': 'no-store' })
+        };
+    }
+    async answer(input, context, route) {
+        const invalid = schemas.call.fit(input);
+        // it may have carried an id, but nothing about it is trustworthy enough to answer to
+        if (invalid !== null)
+            return response(null, failure(INVALID_REQUEST, invalid.message));
+        return await this.call(input, context, route);
+    }
+    async call(call, context, route) {
+        const notification = call.id === undefined;
+        try {
+            const params = call.params ?? {};
+            const { path, verb, variables } = address(call.method, params);
+            const { query, input } = split(params, variables);
+            const clone = fork(context, path, verb, query, input);
+            // one span per call, so what the directives of that call open has somewhere to hang
+            const message = await console.span({ name: call.method, attributes: { id: call.id } }, async () => await route(clone));
+            // what `io:output` restricts, over this call's reply rather than the envelope
+            await http.shape(clone, message);
+            if (notification)
+                return null;
+            return { jsonrpc: VERSION, id: call.id, result: message.body ?? null };
+        }
+        catch (exception) {
+            /*
+             * A credential belongs to the request. Refusing one call for it would leave the
+             * reply a 200, and the challenge that tells a client where to authenticate is
+             * attached to a 401 — so the whole envelope is refused instead.
+             */
+            if (exception instanceof http.Unauthorized)
+                throw exception;
+            if (notification) {
+                console.debug('Notification failed', {
+                    method: call.method,
+                    error: of(exception)
+                });
+                return null;
+            }
+            return { jsonrpc: VERSION, id: call.id, error: of(exception) };
+        }
+    }
+    /** A body the decoder refuses is a parse error; a media type it does not know is not. */
+    async read(context) {
+        try {
+            return await context.body();
+        }
+        catch (exception) {
+            if (exception instanceof http.BadRequest)
+                throw new http.BadRequest(response(null, failure(PARSE, 'Parse error')));
+            throw exception;
+        }
+    }
+}
+const OK = 200;
+const NO_CONTENT = 204;
+//# sourceMappingURL=Dispatcher.js.map

package/transpiled/RPC/Dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.js","sourceRoot":"","sources":["../../source/RPC/Dispatcher.ts"],"names":[],"mappings":"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"}

package/transpiled/RPC/errors.d.ts

@@ -0,0 +1,18 @@
+import { type Failure, type Response } from './types.ts';
+export declare const PARSE = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL = -32603;
+export declare const FORBIDDEN = -32000;
+export declare const REFUSED = -32001;
+export declare const BATCH_TOO_LARGE = -32002;
+export declare function failure(code: number, message: string, data?: unknown): Failure;
+export declare function response(id: string | number | null, error: Failure): Response;
+/**
+ * What an exception says as a JSON-RPC error.
+ *
+ * The readable text is `body`, never `message`: `http.Exception` calls `super()` with no
+ * argument, so every one of them carries an empty `message`.
+ */
+export declare function of(exception: unknown): Failure;

package/transpiled/RPC/errors.js

@@ -0,0 +1,67 @@
+import * as http from '../HTTP/index.js';
+import { VERSION } from './types.js';
+/*
+ * The five the specification fixes (JSON-RPC 2.0 §5.1). A client reads these the same
+ * whoever answers.
+ */
+export const PARSE = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL = -32603;
+/*
+ * Ours. The specification reserves -32000 to -32099 for implementation-defined server
+ * errors and defines nothing in it, so these mean nothing outside Toa — which is why
+ * `REFUSED` carries the operation's own code in `data`.
+ */
+export const FORBIDDEN = -32000;
+export const REFUSED = -32001;
+export const BATCH_TOO_LARGE = -32002;
+export function failure(code, message, data) {
+    const value = { code, message };
+    if (data !== undefined)
+        value.data = data;
+    return value;
+}
+export function response(id, error) {
+    return { jsonrpc: VERSION, id, error };
+}
+/**
+ * What an exception says as a JSON-RPC error.
+ *
+ * The readable text is `body`, never `message`: `http.Exception` calls `super()` with no
+ * argument, so every one of them carries an empty `message`.
+ */
+export function of(exception) {
+    if (exception instanceof http.UnprocessableEntity)
+        return refusal(exception);
+    if (exception instanceof http.NotFound || exception instanceof http.MethodNotAllowed)
+        return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'));
+    if (exception instanceof http.Forbidden)
+        return failure(FORBIDDEN, text(exception, 'Forbidden'));
+    if (exception instanceof http.BadRequest)
+        return failure(INVALID_PARAMS, text(exception, 'Invalid params'));
+    // a conflict, a precondition, a throttle: the call was refused, and by what is worth saying
+    if (exception instanceof http.ClientError)
+        return failure(REFUSED, text(exception, 'Refused'), { status: exception.status });
+    return failure(INTERNAL, 'Internal error');
+}
+/**
+ * An operation that declares its errors answers with one rather than throwing, and the
+ * reply contract states `{ code, message? }` — the message optional. The number says the
+ * operation refused; `data.code` says what it refused with, and is what a caller branches on.
+ */
+function refusal(exception) {
+    const body = exception.body;
+    if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
+        return failure(REFUSED, text(exception, 'Refused'));
+    const code = body.code;
+    const message = typeof body.message === 'string' && body.message !== '' ? body.message : code;
+    return failure(REFUSED, message, { code });
+}
+function text(exception, fallback) {
+    return typeof exception.body === 'string' && exception.body !== ''
+        ? exception.body
+        : fallback;
+}
+//# sourceMappingURL=errors.js.map

package/transpiled/RPC/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../source/RPC/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,EAAE,OAAO,EAA+B,MAAM,YAAY,CAAA;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAK,CAAA;AAC3B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,CAAA;AACrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAK,CAAA;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,CAAA;AACpC,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAA;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAA;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAK,CAAA;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,CAAA;AAErC,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,OAAe,EAAE,IAAc;IACnE,MAAM,KAAK,GAAY,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;IAExC,IAAI,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAA;IAEzC,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,EAA0B,EAAE,KAAc;IACjE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,EAAE,CAAC,SAAkB;IACnC,IAAI,SAAS,YAAY,IAAI,CAAC,mBAAmB;QAAE,OAAO,OAAO,CAAC,SAAS,CAAC,CAAA;IAE5E,IAAI,SAAS,YAAY,IAAI,CAAC,QAAQ,IAAI,SAAS,YAAY,IAAI,CAAC,gBAAgB;QAClF,OAAO,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAA;IAEvE,IAAI,SAAS,YAAY,IAAI,CAAC,SAAS;QACrC,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAA;IAEzD,IAAI,SAAS,YAAY,IAAI,CAAC,UAAU;QACtC,OAAO,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAA;IAEnE,4FAA4F;IAC5F,IAAI,SAAS,YAAY,IAAI,CAAC,WAAW;QACvC,OAAO,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAA;IAEnF,OAAO,OAAO,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAA;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,SAAmC;IAClD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAA;IAE3B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAC5E,OAAO,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAA;IAErD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAc,CAAA;IAChC,MAAM,OAAO,GACX,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;IAE/E,OAAO,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,IAAI,CAAC,SAAyB,EAAE,QAAgB;IACvD,OAAO,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,KAAK,EAAE;QAChE,CAAC,CAAC,SAAS,CAAC,IAAI;QAChB,CAAC,CAAC,QAAQ,CAAA;AACd,CAAC"}

package/transpiled/RPC/index.d.ts

@@ -0,0 +1 @@
+export { Dispatcher } from './Dispatcher.ts';

package/transpiled/RPC/index.js

@@ -0,0 +1,2 @@
+export { Dispatcher } from './Dispatcher.js';
+//# sourceMappingURL=index.js.map

package/transpiled/RPC/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/RPC/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/transpiled/RPC/names.d.ts

@@ -0,0 +1,31 @@
+import type { Segment } from '../RTD/segment.ts';
+import { type Params } from './types.ts';
+/**
+ * What a name resolves to: the path the call is made at, and the verb it is made with.
+ *
+ * A name is the route template with its variables marked and the verb appended as a segment
+ * of its own — `pots._id.GET`. The revision names the characters a tool's name may hold, and
+ * `/` is not among them, so segments are joined by `.` — which a segment cannot hold either,
+ * so nothing in a name can be mistaken for anything else, and the verb is always last.
+ */
+export interface Address {
+    path: string;
+    verb: string;
+    /** the `params` the path took, which are therefore not the operation's input */
+    variables: string[];
+}
+export declare function address(method: string, params: Params): Address;
+/**
+ * What the call carries, as a request carries it: the path took its variables, `query` is
+ * the querystring, and the rest is the body.
+ */
+export declare function split(params: Params, variables: string[]): {
+    query?: Params;
+    input?: Params;
+};
+/** The name of a method on this route, or nothing where the route has none. */
+export declare function name(segments: Segment[], verb: string): string | null;
+/** The segment that leaves a route unnameable, as it was declared, or nothing where none does. */
+export declare function refusal(segments: Segment[]): string | null;
+/** The route as it was declared, which is how a message about it should read. */
+export declare function template(segments: Segment[]): string;

package/transpiled/RPC/names.js

@@ -0,0 +1,121 @@
+import * as http from '../HTTP/index.js';
+import { verbs } from '../RTD/syntax/index.js';
+import { QUERY } from './types.js';
+export function address(method, params) {
+    const parts = method.split(SEPARATOR);
+    const verb = parts.pop();
+    if (!verbs.has(verb))
+        throw new http.NotFound(`'${method}' names no method`);
+    const variables = [];
+    const fragments = [];
+    for (const part of parts) {
+        const key = parameter(part);
+        if (key === null) {
+            fragments.push(literal(part, method));
+            continue;
+        }
+        if (part !== TAIL && !NAMEABLE.test(key))
+            throw new http.NotFound(`'${method}' names no procedure`);
+        const value = params[key];
+        if (value === undefined || value === null)
+            throw new http.BadRequest(`'${method}' requires the parameter '${key}'`);
+        const fragment = String(value);
+        // `__` stands for the rest of the path and may carry separators; a variable is one segment
+        if (!(part === TAIL ? TAILED : OPAQUE).test(fragment))
+            throw new http.BadRequest(`The parameter '${key}' cannot be a path of its own`);
+        variables.push(key);
+        fragments.push(fragment);
+    }
+    // a route is matched with its trailing slash, and the trunk is the bare one
+    const path = fragments.length === 0 ? '/' : `/${fragments.join('/')}/`;
+    return { path, verb, variables };
+}
+/**
+ * What the call carries, as a request carries it: the path took its variables, `query` is
+ * the querystring, and the rest is the body.
+ */
+export function split(params, variables) {
+    const input = {};
+    let query;
+    for (const [key, value] of Object.entries(params)) {
+        if (variables.includes(key))
+            continue;
+        if (key !== QUERY) {
+            input[key] = value;
+            continue;
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new http.BadRequest(`'${QUERY}' must be an object`);
+        query = value;
+    }
+    // an absent body is what a request without one has, and the mapping fills it as it does
+    return { query, input: Object.keys(input).length === 0 ? undefined : input };
+}
+/** The parameter a part reads, or nothing where the part is a literal segment. */
+function parameter(part) {
+    if (part === TAIL)
+        return WILDCARD;
+    return part[0] === VARIABLE ? part.slice(1) : null;
+}
+/** A segment a name cannot spell is a segment no name has, so this one names nothing. */
+function literal(part, method) {
+    if (!NAMEABLE.test(part))
+        throw new http.NotFound(`'${method}' names no procedure`);
+    return part;
+}
+/** The name of a method on this route, or nothing where the route has none. */
+export function name(segments, verb) {
+    const parts = [];
+    for (const segment of segments) {
+        const part = component(segment);
+        if (part === null)
+            return null;
+        parts.push(part);
+    }
+    parts.push(verb);
+    return parts.join(SEPARATOR);
+}
+/** The segment that leaves a route unnameable, as it was declared, or nothing where none does. */
+export function refusal(segments) {
+    for (const segment of segments)
+        if (component(segment) === null)
+            return declared(segment);
+    return null;
+}
+function component(segment) {
+    if (segment.fragment !== null)
+        return NAMEABLE.test(segment.fragment) ? segment.fragment : null;
+    if (segment.wildcard === true)
+        return TAIL;
+    // it stands for a segment the caller cannot name, so there is nothing to substitute
+    if (segment.placeholder === null)
+        return null;
+    return NAMEABLE.test(segment.placeholder) ? VARIABLE + segment.placeholder : null;
+}
+/** The route as it was declared, which is how a message about it should read. */
+export function template(segments) {
+    return '/' + segments.map(declared).join('/');
+}
+function declared(segment) {
+    if (segment.fragment !== null)
+        return segment.fragment;
+    if (segment.wildcard === true)
+        return '**';
+    return segment.placeholder === null ? '*' : ':' + segment.placeholder;
+}
+const SEPARATOR = '.';
+const VARIABLE = '_';
+const TAIL = '__';
+/** How the RTD names the rest of a path, wherever a parameter of it is read. */
+const WILDCARD = '**';
+/**
+ * What a segment may hold to have a name. `_` is the convention's own, and every other
+ * character a client leaves alone is here: a client shows a model the name with the rest
+ * turned into `_`, and two names must not become one.
+ */
+const NAMEABLE = /^[A-Za-z0-9-]+$/;
+/** A segment ends at what divides or ends a path. */
+const OPAQUE = /^[^/?#]*$/;
+/** A tail is several segments, so it keeps the divider and loses only what ends a path. */
+const TAILED = /^[^?#]*$/;
+//# sourceMappingURL=names.js.map

package/transpiled/RPC/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../source/RPC/names.ts"],"names":[],"mappings":"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"}

package/transpiled/RPC/types.d.ts

@@ -0,0 +1,27 @@
+/** The version every call and every response states. */
+export declare const VERSION = "2.0";
+/**
+ * The member `params` reserves for what a querystring would carry. An operation's input is
+ * free to have an `id` or a `limit` of its own, so the two cannot share one object.
+ */
+export declare const QUERY = "query";
+export type Params = Record<string, unknown>;
+export interface Call {
+    jsonrpc: string;
+    method: string;
+    params?: Params;
+    /** Absent makes this a notification: it runs, and nothing is returned for it. */
+    id?: string | number;
+}
+export interface Response {
+    jsonrpc: string;
+    /** `null` where the request was not readable enough to carry one. */
+    id: string | number | null;
+    result?: unknown;
+    error?: Failure;
+}
+export interface Failure {
+    code: number;
+    message: string;
+    data?: unknown;
+}

package/transpiled/RPC/types.js

@@ -0,0 +1,8 @@
+/** The version every call and every response states. */
+export const VERSION = '2.0';
+/**
+ * The member `params` reserves for what a querystring would carry. An operation's input is
+ * free to have an `id` or a `limit` of its own, so the two cannot share one object.
+ */
+export const QUERY = 'query';
+//# sourceMappingURL=types.js.map

package/transpiled/RPC/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/RPC/types.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,CAAA;AAE5B;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAA"}

package/transpiled/RTD/Context.d.ts

@@ -1,6 +1,6 @@
-import { type DirectiveFactory } from './Directives';
-import { type EndpointsFactory } from './Endpoint';
-import type { Directive } from './syntax';
+import { type DirectiveFactory } from './Directives.ts';
+import { type EndpointsFactory } from './Endpoint.ts';
+import type { Directive } from './syntax/index.ts';
 export interface Context<TExtension = any> {
     readonly protected: boolean;
     readonly endpoints: EndpointsFactory;
@@ -8,5 +8,7 @@ export interface Context<TExtension = any> {
         readonly factory: DirectiveFactory;
         stack: Directive[];
     };
-    readonly extension?: TExtension;
+    /** The route being built, accumulated on the way down and restored on the way up. */
+    path: string;
+    readonly extension: TExtension;
 }

package/transpiled/RTD/Context.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Context.js.map

package/transpiled/RTD/Directives.d.ts

@@ -1,22 +1,105 @@
-import type { Parameter } from './Match';
-import type * as syntax from './syntax';
-import type { Context, OutgoingMessage } from '../HTTP';
-import type { Output } from '../io';
+import type { Parameter } from './Match.ts';
+import type * as syntax from './syntax/index.ts';
+import type { Context, OutgoingMessage, Options } from '../HTTP/index.ts';
+import type { Output } from '../io.ts';
+import type { Introspection } from '../Introspection.ts';
+import type { extensions } from '@toa.io/core/types';
+type Host = extensions.Host;
 export interface Directives {
-    preflight: (context: Context, parameters: Parameter[]) => Promise<Output>;
+    /**
+     * The directives of one family on this method, or nothing where it declares none of it.
+     * For a consumer of a declaration rather than of a stage: what a method is published as
+     * is stated on the route, and read where the publishing happens.
+     */
+    declared: <T>(family: string) => T[] | undefined;
+    precall: (context: Context, parameters: Parameter[]) => Promise<Output>;
+    /**
+     * Whether this caller is told of the method at all. Asked per request, which is the one
+     * thing about a description that depends on who is asking.
+     */
+    admits: (context: Context) => Promise<boolean>;
+    /**
+     * What this route's directives make of what its method says about itself. No caller: what
+     * a family describes is what the route declares, so the answer is the same for everyone
+     * who is admitted, and is built once.
+     */
+    describe: (introspection: Introspection) => Introspection | null;
     settle: (context: Context, response: OutgoingMessage) => Promise<void>;
+    dispose: () => void;
 }
 export interface DirectiveFactory {
-    create: (directives: syntax.Directive[]) => Directives;
+    create: (directives: syntax.Directive[], route: string) => Directives;
+    /** Whether this declaration is carried into the nodes below the one it is on. */
+    inheritable: (directive: syntax.Directive) => boolean;
+    /** Runs every family's `preflight`, which is request-scoped and needs no node. */
+    preflight: (context: Context) => Promise<void>;
+    /** Runs every family's `depart`, the counterpart of `preflight`. */
+    depart: (context: Context, response: OutgoingMessage) => Promise<void>;
+    dispose: () => void;
 }
 export interface DirectiveSet {
     family: DirectiveFamily;
     directives: any[];
+    /** qualified directive names, e.g. `auth:id` */
+    names?: string[];
 }
 export interface DirectiveFamily<TDirective = any, TExtension = any> {
     readonly name: string;
     readonly mandatory: boolean;
+    /**
+     * Whether a declaration applies to everything below the node it is on, as every directive
+     * does unless it says otherwise. A family that describes what one node *is* sets this
+     * `false`: inherited, it would say the same thing of every resource under it.
+     */
+    readonly inherited?: boolean;
     create: (name: string, ...rest: any[]) => TDirective;
-    preflight?: (directives: TDirective[], request: Context & TExtension, parameters: Parameter[]) => Output | Promise<Output>;
+    /**
+     * Called once per gateway with what the host provides and how the gateway is configured,
+     * before any directive is created.
+     */
+    mount?: (host: Host, options: Options) => void;
+    /**
+     * Puts the directives of one route in the order they must run in. Called once, when
+     * the set is built — the order cannot depend on the request.
+     */
+    arrange?: (directives: TDirective[]) => void;
+    /**
+     * Request-scoped, before anything is routed. It takes no directives: no node is known
+     * yet, and a request that carries several calls has no single node at all. What a
+     * directive declares is call-scoped by definition, so only what a family does on its
+     * own behalf — authenticating a credential — belongs here. It answers nothing: a stage
+     * that runs before a route is known has no reply to make, and refuses by throwing.
+     */
+    preflight?: (request: Context & TExtension) => void | Promise<void>;
+    /** Call-scoped, with what the node declares. Runs once per call. */
+    precall?: (directives: TDirective[], request: Context & TExtension, parameters: Parameter[]) => Output | Promise<Output>;
+    /**
+     * Whether this caller is told of the method at all — `auth` alone has anything to say
+     * here. A family that does not implement it admits everyone; `false` takes the method
+     * out of every answer that describes it.
+     *
+     * Apart from `explain` because it is the one part of describing a method that depends on
+     * the caller: what is described is then built once and answered to all of them.
+     */
+    admits?: (directives: TDirective[], request: Context & TExtension) => Promise<boolean>;
+    /**
+     * What this family's directives make of what the method says about itself, which is
+     * what `OPTIONS` answers and what a tool is described by. `null` hides it: the method is
+     * described to nobody, whoever asks.
+     *
+     * There is no request here — no route variable has a value, no body has arrived, and no
+     * caller is known — so a directive that can only tell from one hands back what it was
+     * given.
+     */
+    explain?: (directives: TDirective[], introspection: Introspection) => Introspection | null;
+    /** Call-scoped, on the message that call produced. */
     settle?: (directives: TDirective[], request: Context & TExtension, response: OutgoingMessage) => void | Promise<void>;
+    /**
+     * Request-scoped, on the message going back — the counterpart of `preflight`, and
+     * likewise without directives. A reply the whole request carries, such as a re-issued
+     * credential, is written here rather than by a call that would not own it.
+     */
+    depart?: (request: Context & TExtension, response: OutgoingMessage) => void | Promise<void>;
+    dispose?: (directives: TDirective[]) => void;
 }
+export {};

package/transpiled/RTD/Directives.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Directives.js.map

package/transpiled/RTD/Endpoint.d.ts

@@ -1,9 +1,16 @@
-import { type Context } from './Context';
-import type * as http from '../HTTP';
-import type * as syntax from './syntax';
-import type * as RTD from './index';
+import { type Context } from './Context.ts';
+import type * as http from '../HTTP/index.ts';
+import type * as syntax from './syntax/index.ts';
+import type * as RTD from './index.ts';
+import type { Introspection, Schema } from '../Introspection.ts';
 export interface Endpoint {
     call: (context: http.Context, parameters: RTD.Parameter[]) => Promise<http.OutgoingMessage>;
+    explain: (parameters: RTD.Parameter[]) => Promise<Introspection>;
+    /**
+     * What picks the records a call is about — `criteria`, `sort` and the rest. Stated as
+     * `selection` on the method, because it is not a parameter the resource declares.
+     */
+    selection: () => Record<string, Schema> | null;
     close: () => Promise<void>;
 }
 export interface EndpointsFactory {

package/transpiled/RTD/Endpoint.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Endpoint.js.map

package/transpiled/RTD/Match.d.ts

@@ -1,7 +1,13 @@
-import { type Node } from './Node';
+import { type Node } from './Node.ts';
 export interface Match {
     node: Node;
     parameters: Parameter[];
+    /**
+     * The path that was matched, with placeholders as declared — `/users/:id/` and not
+     * `/users/42/`. A metric labels a request by it, because a URL is unbounded and a series per
+     * URL is a series per caller.
+     */
+    route: string;
 }
 export interface Parameter {
     name: string;

package/transpiled/RTD/Match.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Match.js.map