@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.300

package/transpiled/HTTP/index.js

@@ -1,20 +1,7 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./Server"), exports);
-__exportStar(require("./messages"), exports);
-__exportStar(require("./exceptions"), exports);
+export * from './Server.js';
+export * from './messages.js';
+export * from './exceptions.js';
+export * from './Context.js';
+export * from './types.js';
+export * from './Probe.js';
 //# sourceMappingURL=index.js.map

package/transpiled/HTTP/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/HTTP/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAwB;AACxB,6CAA0B;AAC1B,+CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/HTTP/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}

package/transpiled/HTTP/messages.d.ts

@@ -1,33 +1,41 @@
-/// <reference types="node" />
-import { type IncomingHttpHeaders } from 'node:http';
-import { type Request, type Response } from 'express';
-import type { ParsedQs } from 'qs';
-import type { Format } from './formats';
-export declare function write(request: IncomingMessage, response: Response, message: OutgoingMessage): void;
-export declare function read(request: Request): Promise<any>;
-export interface IncomingMessage extends Request {
-    method: string;
-    path: string;
-    url: string;
-    headers: IncomingHttpHeaders;
-    query: Query;
-    parse: <T>() => Promise<T>;
-    encoder: Format | null;
-    subtype: string | null;
-    pipelines: {
-        body: Array<(input: unknown) => unknown>;
-        response: Array<(output: OutgoingMessage) => void>;
-    };
-}
+import { Readable } from 'node:stream';
+import type { Context } from './Context.js';
+import type { ServerResponse } from './types.js';
+/**
+ * Applies what the request accumulated in `pipelines.response` — an `io:output` restriction,
+ * a `vary` a `map` directive owes. Separate from `write` because a message is not always
+ * written: one call of several produces a value the reply is assembled from.
+ */
+export declare function shape(context: Context, message: OutgoingMessage): Promise<void>;
+export declare function write(context: Context, response: ServerResponse, message: OutgoingMessage): Promise<void>;
+export declare function read(context: Context): Promise<any>;
+/**
+ * Frames an object stream as `multipart/*`: an `ACK` part, the parts themselves, then `FIN`.
+ * The body is a `Readable`; `write` reached here by testing it.
+ */
+export declare function multipart(message: OutgoingMessage, context: Context, response: ServerResponse): Readable;
 export interface OutgoingMessage {
     status?: number;
     headers?: Headers;
     body?: any;
+    /** what the reply carries for a cache to validate by; the `cache` family sets the headers */
+    version?: number;
+    modified?: number | string;
+    /**
+     * Built by the gateway rather than returned by an operation, as a request is `authentic`
+     * when it was made by one: what is in it is the gateway's own, and the checks that answer
+     * for what an operation returns have nothing to say about it.
+     */
+    authentic?: boolean;
 }
-export interface Query extends ParsedQs {
+export interface Query {
+    [key: string]: string | number | undefined;
     id?: string;
     criteria?: string;
+    search?: string;
+    sample?: number;
     sort?: string;
     omit?: string;
     limit?: string;
+    version?: number;
 }

package/transpiled/HTTP/messages.js

@@ -1,75 +1,191 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.read = exports.write = void 0;
-const node_stream_1 = require("node:stream");
-const streams_1 = require("@toa.io/streams");
-const formats_1 = require("./formats");
-const exceptions_1 = require("./exceptions");
-function write(request, response, message) {
-    for (const transform of request.pipelines.response)
-        transform(message);
-    message.headers?.forEach((value, key) => response.set(key, value));
-    if (message.body instanceof node_stream_1.Readable)
-        stream(message, request, response);
+import { readFileSync } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import * as contentType from 'content-type';
+import { console } from 'openspan';
+import { decoders } from './formats/index.js';
+import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js';
+import { environment } from '@toa.io/generic';
+const context = environment.get('TOA_CONTEXT');
+const env = environment.get('TOA_ENV');
+/*
+ * What answered, on every reply: the build of the gateway, and the context and environment
+ * it was deployed with. Under a name of its own rather than `server`, which a CDN in front
+ * takes for itself — Cloudflare pins it to `cloudflare` and refuses to let a rule set it,
+ * so a gateway that said it there said it to nobody. A name like `ray`'s, and it survives
+ * the same hop `ray` does.
+ */
+const exposition = `${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
+    ((context === undefined ? '' : ` ${context}`) + (env === undefined ? '' : `/${env}`));
+/**
+ * Applies what the request accumulated in `pipelines.response` — an `io:output` restriction,
+ * a `vary` a `map` directive owes. Separate from `write` because a message is not always
+ * written: one call of several produces a value the reply is assembled from.
+ */
+export async function shape(context, message) {
+    for (const transform of context.pipelines.response)
+        await transform(message);
+}
+export async function write(context, response, message) {
+    await shape(context, message);
+    if (message?.status !== undefined)
+        response.statusCode = message.status;
+    response.setHeader('exposition', exposition);
+    message.headers?.forEach((value, key) => response.setHeader(key, value));
+    context.timing.append(response);
+    if (response.destroyed) {
+        console.warn('Request destroyed prematurely', { path: context.url.pathname });
+        return;
+    }
+    response.on('error', (exception) => console.warn('HTTP response error', { path: context.url.pathname, exception }));
+    if (message.body instanceof Readable)
+        stream(message, context, response);
     else
-        send(message, request, response);
+        send(message, context, response);
 }
-exports.write = write;
-async function read(request) {
-    const type = request.headers['content-type'];
-    if (type === undefined)
+export async function read(context) {
+    const header = context.request.headers['content-type'];
+    if (header === undefined)
         return undefined;
-    if (!(type in formats_1.formats))
-        throw new exceptions_1.UnsupportedMediaType();
-    const format = formats_1.formats[type];
-    const buf = await (0, streams_1.buffer)(request);
+    const { type, parameters } = contentType.parse(header);
+    if (!(type in decoders))
+        throw new UnsupportedMediaType();
+    const format = decoders[type];
+    const buf = await context.buffer();
     try {
-        return format.decode(buf);
+        return format.decode(buf, parameters.charset);
     }
-    catch {
-        throw new exceptions_1.BadRequest();
+    catch (error) {
+        console.debug('Failed to decode message', {
+            path: context.url.pathname,
+            error: error?.toString?.()
+        });
+        throw new BadRequest();
     }
 }
-exports.read = read;
-function send(message, request, response) {
+function send(message, context, response) {
     if (message.body === undefined || message.body === null) {
+        // a HEAD reply carries no body but must still report the length a GET would
+        // have returned, so a length already set by a directive is left alone
+        if (!response.hasHeader('content-length'))
+            response.setHeader('content-length', '0');
         response.end();
         return;
     }
-    if (request.encoder === null)
-        throw new exceptions_1.NotAcceptable();
-    const buf = request.encoder.encode(message.body);
-    response
-        .set('content-type', request.encoder.type)
-        .append('vary', 'accept')
-        .end(buf);
+    if (context.encoder === null)
+        throw new NotAcceptable();
+    const buf = context.encoder.encode(message.body);
+    response.setHeader('content-type', context.encoder.type);
+    response.setHeader('content-length', buf.length.toString());
+    response.appendHeader('vary', 'accept');
+    response.end(buf);
 }
-function stream(message, request, response) {
+function stream(message, context, response) {
     const encoded = message.headers !== undefined && message.headers.has('content-type');
-    if (encoded)
-        pipe(message, response);
-    else
-        multipart(message, request, response);
-    message.body.on('error', (e) => {
-        console.error(e);
-        response.end();
-    });
+    const source = encoded ? message.body : multipart(message, context, response);
+    // not awaited: a reply that streams is written long after the request is answered, and a
+    // realtime subscription outlives the span the reply was produced in
+    //
+    // `pipeline` carries an error to every stage and destroys them. `pipe` leaves the stages it
+    // built behind, and an `error` on a stream nobody listens to is an uncaught exception.
+    pipeline(source, response).catch((exception) => console.warn('Message stream error', { path: context.url.pathname, exception }));
 }
-function pipe(message, response) {
-    message.headers?.forEach((value, key) => response.set(key, value));
-    message.body.pipe(response);
+/**
+ * Frames an object stream as `multipart/*`: an `ACK` part, the parts themselves, then `FIN`.
+ * The body is a `Readable`; `write` reached here by testing it.
+ */
+export function multipart(message, context, response) {
+    if (context.encoder === null)
+        throw new NotAcceptable();
+    const encoder = context.encoder;
+    response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`);
+    return new Framing(message.body, encoder, context.signal);
 }
-function multipart(message, request, response) {
-    if (request.encoder === null)
-        throw new exceptions_1.NotAcceptable();
-    const encoder = request.encoder;
-    response.set('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`);
-    message.body
-        .map((part) => Buffer.concat([CUT, encoder.encode(part)]))
-        .on('end', () => response.end(FINALCUT))
-        .pipe(response);
+/**
+ * A part is pulled when the reader takes one, so a slow reader holds the body back.
+ *
+ * Not a generator under `Readable.from`: that one's `return()` waits behind the `next()` it is
+ * suspended in, and a body destroyed with its reply would live on until its next part — a
+ * subscription's, until its next heartbeat. Destroyed, this destroys the body at once.
+ *
+ * Aborted, it ends with `FIN` instead of being cut: the gateway is stopping, and the reader is
+ * told the stream is over rather than left to find out.
+ */
+class Framing extends Readable {
+    body;
+    parts;
+    encoder;
+    signal;
+    pulling = false;
+    stopping = false;
+    finished = false;
+    constructor(body, encoder, signal) {
+        super();
+        this.body = body;
+        this.encoder = encoder;
+        this.signal = signal;
+        this.parts = body[Symbol.asyncIterator]();
+        this.push(Buffer.concat([CUT, CRLF, encoder.encode('ACK'), CRLF, CUT]));
+        if (signal.aborted)
+            this.stop();
+        else
+            signal.addEventListener('abort', this.stop, { once: true });
+    }
+    _read() {
+        if (this.pulling || this.finished)
+            return;
+        this.pulling = true;
+        this.pull().catch((error) => this.destroy(error));
+    }
+    _destroy(error, callback) {
+        this.signal.removeEventListener('abort', this.stop);
+        this.body.destroy();
+        callback(error);
+    }
+    async pull() {
+        let result;
+        try {
+            result = await this.parts.next();
+        }
+        catch (error) {
+            // the body was destroyed by `stop`, and that is not an error of the stream
+            if (this.stopping) {
+                this.finish();
+                return;
+            }
+            throw error;
+        }
+        finally {
+            this.pulling = false;
+        }
+        if (result.done === true || this.stopping)
+            this.finish();
+        else
+            this.push(Buffer.concat([
+                CRLF /* indicates no boundary headers */,
+                this.encoder.encode(result.value),
+                CRLF,
+                CUT
+            ]));
+    }
+    stop = () => {
+        this.stopping = true;
+        this.body.destroy();
+        // a pull in flight finishes on its own once the body is gone
+        if (!this.pulling)
+            this.finish();
+    };
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.signal.removeEventListener('abort', this.stop);
+        this.push(Buffer.concat([CRLF, this.encoder.encode('FIN'), CRLF, FINALCUT]));
+        this.push(null);
+    }
 }
 const BOUNDARY = 'cut';
 const CUT = Buffer.from(`--${BOUNDARY}\r\n`);
+const CRLF = Buffer.from('\r\n');
 const FINALCUT = Buffer.from(`--${BOUNDARY}--`);
 //# sourceMappingURL=messages.js.map

package/transpiled/HTTP/messages.js.map

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

package/transpiled/HTTP/types.d.ts

@@ -0,0 +1,37 @@
+import type { Readable, Writable } from 'node:stream';
+import type { OutgoingHttpHeaders } from 'node:http';
+import type { IncomingHttpHeaders } from 'node:http2';
+/**
+ * What Exposition requires of a request. Both `http.IncomingMessage` and
+ * `http2.Http2ServerRequest` satisfy it, so the pipeline is written once.
+ */
+export interface IncomingMessage extends Readable {
+    url: string;
+    method: string;
+    complete: boolean;
+    headers: IncomingHeaders;
+    socket: {
+        remoteAddress?: string | undefined;
+    };
+}
+/**
+ * What Exposition requires of a response.
+ *
+ * `setHeader` and `appendHeader` return `void` because `Http2ServerResponse` returns
+ * nothing from them, so neither can be chained.
+ */
+export interface ServerResponse extends Writable {
+    statusCode: number;
+    writableEnded: boolean;
+    setHeader: (name: string, value: number | string | string[]) => void;
+    appendHeader: (name: string, value: string | string[]) => void;
+    hasHeader: (name: string) => boolean;
+    writeHead: (status: number, headers?: OutgoingHttpHeaders) => ServerResponse;
+}
+/**
+ * HTTP/2's header map: HTTP/1.1's, plus the pseudo-headers. `:authority` is typed here
+ * so the authority can be read without narrowing at every call site.
+ */
+export type IncomingHeaders = IncomingHttpHeaders;
+/** `h2c` is cleartext HTTP/2: there is no in-process TLS to negotiate ALPN with. */
+export type Protocol = 'h1' | 'h2c';

package/transpiled/HTTP/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/transpiled/HTTP/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/HTTP/types.ts"],"names":[],"mappings":""}

package/transpiled/Interception.d.ts

@@ -1,9 +1,14 @@
-import type { Input, Output } from './io';
+import type * as http from './HTTP/index.js';
+import type { Input, Output } from './io.js';
 export declare class Interception implements Interceptor {
     private readonly interceptors;
-    constructor(interceptors: Interceptor[]);
+    constructor(interceptors: Interceptor[], options: http.Options);
     intercept(input: Input): Promise<Output>;
 }
 export interface Interceptor {
     intercept: (input: Input) => Output | Promise<Output>;
+    /** Discards whatever the interceptor accumulated while serving. */
+    reset?: () => void;
+    /** What the annotation says, for an interceptor that answers from it. */
+    mount?: (options: http.Options) => void;
 }

package/transpiled/Interception.js

@@ -1,10 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Interception = void 0;
-class Interception {
+export class Interception {
     interceptors;
-    constructor(interceptors) {
+    constructor(interceptors, options) {
         this.interceptors = interceptors;
+        // interceptors are module singletons, so a second gateway in one process —
+        // which is how the features run — would otherwise inherit the first one's state
+        for (const interceptor of interceptors) {
+            interceptor.reset?.();
+            interceptor.mount?.(options);
+        }
     }
     async intercept(input) {
         for (const interceptor of this.interceptors) {
@@ -15,5 +18,4 @@ class Interception {
         return null;
     }
 }
-exports.Interception = Interception;
 //# sourceMappingURL=Interception.js.map

package/transpiled/Interception.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interception.js","sourceRoot":"","sources":["../source/Interception.ts"],"names":[],"mappings":";;;AAEA,MAAa,YAAY;IACN,YAAY,CAAe;IAE5C,YAAoB,YAA2B;QAC7C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAEM,KAAK,CAAC,SAAS,CAAE,KAAY;QAClC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAEjD,IAAI,MAAM,KAAK,IAAI;gBACjB,OAAO,MAAM,CAAA;QACjB,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAjBD,oCAiBC"}
+{"version":3,"file":"Interception.js","sourceRoot":"","sources":["../source/Interception.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,YAAY;IACN,YAAY,CAAe;IAE5C,YAAmB,YAA2B,EAAE,OAAqB;QACnE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAEhC,2EAA2E;QAC3E,gFAAgF;QAChF,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,WAAW,CAAC,KAAK,EAAE,EAAE,CAAA;YACrB,WAAW,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,KAAY;QACjC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAEjD,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAA;QACpC,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/transpiled/Introspection.d.ts

@@ -0,0 +1,98 @@
+import type { Remote } from '@toa.io/core';
+import type { Context } from './HTTP/index.js';
+export interface Introspection {
+    /**
+     * What the route states this method is. The operation states what it is too, and that is
+     * not this: an operation is written without knowledge of any route, and a method is an
+     * operation and a route together — the same operation mounted twice is two methods, and
+     * one sentence cannot be true of both. The operation's own is for the Introspection.
+     */
+    description?: string;
+    /** what a person is shown where a client lists this method, which a name is not */
+    title?: string;
+    /**
+     * whether reaching it takes nothing at all — `auth:anonymous`. Said rather than left
+     * unsaid, because it is also what refuses a caller presenting a credential: a client
+     * cannot know that from an answer that says nothing.
+     */
+    anonymous?: boolean;
+    /** whether reaching it takes being someone, whoever — `auth:anyone` and its like */
+    authenticated?: boolean;
+    /** whether reaching it is being the identity it is about — `auth:id` */
+    private?: boolean;
+    /** whether reaching it takes a role — `auth:role` */
+    protected?: boolean;
+    /** and whether that role is one of the `system` scope */
+    system?: boolean;
+    /**
+     * Whether making this call twice changes state once — the operation declares
+     * [`once`](/documentation/inbox.md). What it means for a client is that a retry it is not
+     * sure about is safe to make, under an `idempotency-key` it repeats.
+     *
+     * Read off the operation rather than off the route: it is the operation that records the
+     * call, and the same one mounted twice is as safe under either.
+     */
+    once?: boolean;
+    /** whether the route publishes this method to a model — [`mcp:tool`](mcp.md) */
+    mcp?: boolean;
+    route?: Record<string, Schema>;
+    query?: Record<string, Schema>;
+    /**
+     * What picks the records a call is about — `criteria`, `sort`, `limit`, `omit`, `search`.
+     * Not the parameters the resource declares: those are `query`. Absent where the method
+     * is not queryable.
+     */
+    selection?: Record<string, Schema>;
+    /** what the body is, where it is a file rather than a value — [`octets:put`](octets.md) */
+    octets?: Octets;
+    input?: Schema;
+    output?: Schema;
+    errors?: string[];
+}
+/** What sending a file to a resource takes, which is not something a schema states. */
+export interface Octets {
+    /** what may be sent, in the syntax of an `accept` header; anything where unstated */
+    accept?: string;
+    /** the largest body it takes, as it is written and as a refusal reports it */
+    limit: string;
+    /**
+     * Whether the reply arrives as a stream of parts rather than as one object: a workflow
+     * runs on what was stored, and each step answers as it finishes. The first part is the
+     * entry itself, which is what a caller that wants nothing else reads and stops.
+     */
+    stream?: boolean;
+}
+export type Schema = Awaited<ReturnType<Remote['explain']>>['input'];
+/**
+ * The same request, as a description of a resource rather than a call to one. A directive
+ * that answers differently to the two reads `exploratory` — `Anonymous` is the one that
+ * does, because the rule refusing a credential at an `anonymous` route is about a reply a
+ * cache would hold, and a description is not one.
+ */
+export declare function describing(context: Context): Context;
+/**
+ * The same, in the order the shape states — whatever order the families that filled it ran
+ * in. What a resource says about itself is read, so it is written the way it is documented.
+ */
+export declare function order(introspection: Introspection): Introspection;
+/**
+ * The schema of one input property, taken out of it: a property another family fills is
+ * not the caller's to send, and what took it says where it comes from instead.
+ */
+export declare function take(carrier: Carrier, property: string): Schema | undefined;
+/**
+ * A schema restricted to the properties a whitelist admits, and an array's items where it
+ * describes an array. What is not an object of properties is left alone: a whitelist has
+ * nothing to say about a string.
+ */
+export declare function restrict(schema: Schema | undefined, allowed: Set<string>): Schema | undefined;
+/**
+ * What a schema is read as here: the keywords these narrow, and whatever else it carries.
+ * `Schema` as core declares it requires `properties`, which a schema of a string has not,
+ * so the two are cast through rather than assigned.
+ */
+/** Whatever states an input: an explanation as the operation gave it, or as a route left it. */
+interface Carrier {
+    input?: Schema;
+}
+export {};