@toa.io/extensions.exposition 1.0.0-alpha.34 → 1.0.0-alpha.340

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

package/transpiled/RTD/Method.d.ts

@@ -1,9 +1,30 @@
-import type { Endpoint } from './Endpoint';
-import type { Directives } from './Directives';
+import type { Parameter } from './Match.ts';
+import type { Endpoint } from './Endpoint.ts';
+import type { Directives } from './Directives.ts';
+import type { Context } from '../HTTP/index.ts';
+import type { Introspection } from '../Introspection.ts';
 export declare class Method {
+    #private;
     readonly endpoint: Endpoint | null;
     readonly directives: Directives;
     constructor(endpoint: Endpoint | null, directives: Directives);
+    /**
+     * What this method says about itself, as its directives leave it, or nothing where they
+     * refuse this caller. A method of no endpoint — one a directive answers on its own —
+     * states nothing of its own, and its directives still have their say.
+     */
+    explain(context: Context, parameters: Parameter[]): Promise<Introspection | null>;
+    /**
+     * What the method is, which is the route's and not the caller's: the operation's own
+     * description, what the directives fill in, and what a hidden method answers instead,
+     * which is nothing. Built once and answered to everyone admitted, so whoever reads it
+     * reads it and leaves it as it is.
+     *
+     * Under no key: a branch that changes is merged as methods of its own, and this one is
+     * dropped with the node that holds it.
+     */
+    describe(parameters: Parameter[]): Promise<Introspection | null>;
+    private build;
     close(): Promise<void>;
 }
 export type Methods = Record<string, Method>;

package/transpiled/RTD/Method.js

@@ -1,16 +1,43 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Method = void 0;
-class Method {
+import { order } from '../Introspection.js';
+export class Method {
     endpoint;
     directives;
+    /** What this method is, built on the first answer that describes it. See `described`. */
+    #description;
     constructor(endpoint, directives) {
         this.endpoint = endpoint;
         this.directives = directives;
     }
+    /**
+     * What this method says about itself, as its directives leave it, or nothing where they
+     * refuse this caller. A method of no endpoint — one a directive answers on its own —
+     * states nothing of its own, and its directives still have their say.
+     */
+    async explain(context, parameters) {
+        if (!(await this.directives.admits(context)))
+            return null;
+        return await this.describe(parameters);
+    }
+    /**
+     * What the method is, which is the route's and not the caller's: the operation's own
+     * description, what the directives fill in, and what a hidden method answers instead,
+     * which is nothing. Built once and answered to everyone admitted, so whoever reads it
+     * reads it and leaves it as it is.
+     *
+     * Under no key: a branch that changes is merged as methods of its own, and this one is
+     * dropped with the node that holds it.
+     */
+    async describe(parameters) {
+        this.#description ??= this.build(parameters);
+        return await this.#description;
+    }
+    async build(parameters) {
+        const introspection = this.endpoint === null ? {} : await this.endpoint.explain(parameters);
+        const described = this.directives.describe(introspection);
+        return described === null ? null : order(described);
+    }
     async close() {
         await this.endpoint?.close();
     }
 }
-exports.Method = Method;
 //# sourceMappingURL=Method.js.map

package/transpiled/RTD/Method.js.map

@@ -1 +1 @@
-{"version":3,"file":"Method.js","sourceRoot":"","sources":["../../source/RTD/Method.ts"],"names":[],"mappings":";;;AAGA,MAAa,MAAM;IACD,QAAQ,CAAiB;IACzB,UAAU,CAAY;IAEtC,YAAoB,QAAyB,EAAE,UAAsB;QACnE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9B,CAAC;CACF;AAZD,wBAYC"}
+{"version":3,"file":"Method.js","sourceRoot":"","sources":["../../source/RTD/Method.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAG3C,MAAM,OAAO,MAAM;IACD,QAAQ,CAAiB;IACzB,UAAU,CAAY;IAEtC,yFAAyF;IACzF,YAAY,CAAgC;IAE5C,YAAmB,QAAyB,EAAE,UAAsB;QAClE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,OAAO,CAClB,OAAgB,EAChB,UAAuB;QAEvB,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;QAEzD,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;IACxC,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,QAAQ,CAAC,UAAuB;QAC3C,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QAE5C,OAAO,MAAM,IAAI,CAAC,YAAY,CAAA;IAChC,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,UAAuB;QACzC,MAAM,aAAa,GACjB,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QAEvE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAA;QAEzD,OAAO,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IACrD,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9B,CAAC;CACF"}

package/transpiled/RTD/Node.d.ts

@@ -1,19 +1,59 @@
-import { type Route } from './Route';
-import { type Methods } from './Method';
-import { type Match, type Parameter } from './Match';
+import { type Route } from './Route.ts';
+import { type Method, type Methods } from './Method.ts';
+import { type Match, type Parameter } from './Match.ts';
+import type { Segment } from './segment.ts';
+import type { Context } from '../HTTP/index.ts';
+import { type Described } from '../directives/help/index.ts';
+import type { Introspection } from '../Introspection.ts';
 export declare class Node {
     intermediate: boolean;
+    forward: string | null;
+    expiration: number;
     methods: Methods;
     private readonly protected;
     private routes;
     constructor(routes: Route[], methods: Methods, properties: Properties);
-    match(fragments: string[], parameters?: Parameter[]): Match | null;
-    merge(node: Node): void;
+    match(fragments: string[], parameters?: Parameter[], segments?: Segment[]): Match | null;
+    /**
+     * Returns the nodes the merged branch has landed on, so that its expiration
+     * can later be extended without rebuilding anything.
+     */
+    merge(node: Node): Node[];
+    touch(expiration: number): void;
+    /**
+     * Every method under this node, with the template it answers at.
+     *
+     * An intermediate node is skipped: it is never what a path matches, because its `/` route
+     * answers at the same place and is reached instead. The trunk is the exception `match`
+     * makes for it — `'/'` answers the trunk itself, whatever it holds.
+     */
+    walk(segments: Segment[], trunk?: boolean): Generator<Mount>;
+    /**
+     * What this resource is, and every method of it this caller may reach, in the order they
+     * were declared. The two are answered apart because only the methods are `Allow`.
+     */
+    explain(context: Context, parameters: Parameter[]): Promise<Explained>;
     private replace;
     private append;
-    private mergeRoute;
+    private route;
+    private nodes;
     private sort;
 }
+/** What a resource says of itself, and what it serves. */
+export interface Explained {
+    described: Described | null;
+    methods: Record<string, Introspection>;
+}
+/** A method, and the route template it is reached by. */
+export interface Mount {
+    segments: Segment[];
+    verb: string;
+    method: Method;
+    /** what the method is mounted on, which is what says whether it is still served */
+    node: Node;
+}
 export interface Properties {
     protected: boolean;
+    forward?: string;
+    expiration?: number;
 }