@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/http/serverCore.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The HTTP server every product's dispatcher listens on: a `node:http`
+ * server with the request's span, the baseline headers, the address read
+ * through the mounts, the orchestrator's probes, and the error-to-status
+ * mapping the tests pin — and, in the middle, the product's own answer
+ * (`Answering`). The database browser's server (browserServer.ts) and the
+ * App framework's (server.ts) are each this, with what their product adds.
+ *
+ * Kept whole rather than rebuilt per product, for the reason `createApp`
+ * was pulled out of `main` in the first place: a wiring a product wrote for
+ * itself would be the one its tests prove, and the shared parts — what a
+ * malformed target is answered with, what an error's status is, which
+ * requests a close waits for — would agree only by convention.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { RequestDiagnostics } from '../operations/diagnostics.js';
+import { type AddressMount } from '../../shared/mount.js';
+import { type Bound } from './trust.js';
+/**
+ * The request read through the server's mounts (shared/mount.ts): the base
+ * path taken off `req.url`, which the static files, the App API and Better
+ * Auth read, and the address turned to its inside form on `url`, which every
+ * route reads. False when it was answered: an address outside the base, or
+ * an App's id where it is mounted under another name, names nothing.
+ */
+export declare function routeAddress(req: IncomingMessage, res: ServerResponse, url: URL, mount: AddressMount): boolean;
+/** The requests a server is still answering that its close waits for (`Answering.drains`). */
+export declare const commandOperations: WeakMap<Server<typeof IncomingMessage, typeof ServerResponse>, Set<Promise<void>>>;
+/** What every server is given, whatever its product: where it listens, and the operator's meters. */
+export interface Listening {
+    /**
+     * Read on every request instead of copied, so a caller listening on port 0
+     * can fill the port in once the kernel has chosen one. That matters because
+     * `doorRefusal` compares the `Host` header against it, and a bound record
+     * that disagrees with the socket refuses every write.
+     */
+    readonly bound: Bound;
+    readonly diagnostics?: RequestDiagnostics;
+    /** Whether the server should take traffic now: false while it starts, reloads its policy or shuts down (`/readyz`). */
+    readonly ready?: () => boolean;
+    /** A suite owns the source client and HMR at its shared listener. */
+    readonly sourceClient?: false;
+    /** A suite must drain even disconnected form submissions before closing its App registry. */
+    readonly drainRequests?: true;
+}
+/** A product's part of the server: its addresses, its answer, and the failures it says in its own words. */
+export interface Answering {
+    /** Where requests are served (shared/mount.ts), read per request. */
+    mount(): AddressMount;
+    /** Before the base path is read: a document whose address follows the origin, not the base. True when answered. */
+    outside?(req: IncomingMessage, res: ServerResponse, url: URL): boolean;
+    /** Which App the request is for, as far as its address says, for its span. */
+    served?(url: URL): string | undefined;
+    /** After the probes and before any door: what no product's door holds. True when answered. */
+    ahead?(req: IncomingMessage, res: ServerResponse, url: URL, mount: AddressMount): boolean;
+    /** The request itself. */
+    answer(req: IncomingMessage, res: ServerResponse, url: URL, mount: AddressMount): Promise<void>;
+    /** A failure the product answers in a shape of its own (a command's outcome). True when answered; asked first. */
+    failed?(error: Error, req: IncomingMessage, res: ServerResponse, url: URL): boolean;
+    /** The status of a failure the engine has no status for, where the product has one. */
+    status?(error: Error): number | undefined;
+    /** A failure's body in the product's own words (an App's, which never says a driver's). True when answered. */
+    said?(error: Error, req: IncomingMessage, res: ServerResponse, status: number): boolean;
+    /** Whether a close waits for this request's answer. */
+    drains?(url: URL): boolean;
+}
+/** The server, wired but not listening. */
+export declare function listen(options: Listening, answering: Answering): Server;

package/dist/server/http/serverCore.js

@@ -0,0 +1,177 @@
+/**
+ * The HTTP server every product's dispatcher listens on: a `node:http`
+ * server with the request's span, the baseline headers, the address read
+ * through the mounts, the orchestrator's probes, and the error-to-status
+ * mapping the tests pin — and, in the middle, the product's own answer
+ * (`Answering`). The database browser's server (browserServer.ts) and the
+ * App framework's (server.ts) are each this, with what their product adds.
+ *
+ * Kept whole rather than rebuilt per product, for the reason `createApp`
+ * was pulled out of `main` in the first place: a wiring a product wrote for
+ * itself would be the one its tests prove, and the shared parts — what a
+ * malformed target is answered with, what an error's status is, which
+ * requests a close waits for — would agree only by convention.
+ */
+import { createServer } from 'node:http';
+import { SOURCE_CLIENT, attachDevClient } from '../devclient.js';
+import { applyServerTimeouts } from '../serverTimeouts.js';
+import { Refusal, WriteConflict } from '../../adapters/adapter.js';
+import { HttpSourceError } from '../../adapters/http/egress.js';
+import { isPoolBusy } from '../../adapters/poolMetrics.js';
+import { withAdmission } from '../../adapters/poolAdmission.js';
+import { AppAccessDenied } from '../columnGrants.js';
+import { wrongTypeValue } from '../constraints.js';
+import { PathError } from '../../shared/view.js';
+import { inward } from '../../shared/mount.js';
+import { arrivedUrls } from './context.js';
+import { probe } from './probes.js';
+import { reportRefusal } from './refusalReport.js';
+import { HttpError, send, sendBusy } from './reply.js';
+import { routedPath, servedApp, traceRequest } from './traceRequest.js';
+import { setBaselineHeaders } from './baselineHeaders.js';
+import { forwardedClient } from './trust.js';
+import { timeRequests } from '../../adapters/telemetry/serverTiming.js';
+/* From source, Vite's modules are addressed from the root whatever the base
+   (devclient.ts): its own paths and the client's files, never a page, the
+   API or the host modules. */
+const devModule = (path) => !/^\/(?:api|_mistri)(?:\/|$)/.test(path) && (/^\/(?:@|node_modules\/)/.test(path) || /\.[A-Za-z0-9]+$/.test(path));
+/**
+ * The request read through the server's mounts (shared/mount.ts): the base
+ * path taken off `req.url`, which the static files, the App API and Better
+ * Auth read, and the address turned to its inside form on `url`, which every
+ * route reads. False when it was answered: an address outside the base, or
+ * an App's id where it is mounted under another name, names nothing.
+ */
+export function routeAddress(req, res, url, mount) {
+    if (mount.base) {
+        const under = url.pathname === mount.base || url.pathname.startsWith(`${mount.base}/`);
+        if (!under) {
+            if (SOURCE_CLIENT && devModule(url.pathname))
+                return true;
+            res
+                .writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' })
+                .end(`Not found: this server is served under ${mount.base}.\n`);
+            return false;
+        }
+        arrivedUrls.set(req, req.url ?? '/');
+        req.url = (url.pathname.slice(mount.base.length) || '/') + url.search;
+    }
+    const inside = inward(mount, url.pathname);
+    if (inside === undefined) {
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }).end('Not found.\n');
+        return false;
+    }
+    url.pathname = inside;
+    return true;
+}
+/** The requests a server is still answering that its close waits for (`Answering.drains`). */
+export const commandOperations = new WeakMap();
+/**
+ * A failure's status. A path that does not resolve is the caller's mistake,
+ * not the server's, and a 500 would have the client report it as an outage
+ * rather than as the typo it is. Same for anything that named its own status
+ * on the way up.
+ */
+function statusOf(err, answering) {
+    if (err instanceof HttpError)
+        return err.status;
+    if (err instanceof AppAccessDenied)
+        return 403;
+    const own = answering.status?.(err);
+    if (own !== undefined)
+        return own;
+    if (err instanceof WriteConflict)
+        return 409;
+    /* A path that does not resolve, an adapter that will not carry out the
+       request and a value its column cannot hold (words searched in a number)
+       are all the caller's mistake, and a 500 tells them to go and look at the
+       server. */
+    if (err instanceof PathError || err instanceof Refusal || wrongTypeValue(err))
+        return 400;
+    // An API behind an HTTP connection failed; this server did not.
+    if (err instanceof HttpSourceError)
+        return 502;
+    return 500;
+}
+/** The server, wired but not listening. */
+export function listen(options, answering) {
+    const pending = new Set();
+    /* The span of each request (traceRequest.ts) names its route from the
+       address after routeAddress has read it inward, never as the browser
+       spelled it: under a base path or a root mount it is the same route. */
+    const server = createServer((req, res) => 
+    /* Its pool checkouts wait in line as its client's until its session names
+       the account (adapters/poolAdmission.ts, http/door.ts). */
+    traceRequest(req, res, () => withAdmission(forwardedClient(req, options.bound.trustedProxies), () => {
+        options.diagnostics?.observe(req, res);
+        setBaselineHeaders(req, res, options.bound.trustedProxies);
+        // Node accepts request targets that URL cannot parse. Refuse them before
+        // dispatch, and reuse this parse in error mapping and drain tracking too.
+        let url;
+        try {
+            url = new URL(req.url ?? '/', 'http://localhost');
+        }
+        catch {
+            return send(res, 400, { error: 'Invalid request target.' });
+        }
+        const mount = answering.mount();
+        if (answering.outside?.(req, res, url))
+            return routedPath(req, url.pathname);
+        // An address outside the base, or an App's id where it is not mounted, names no route: its span says so.
+        if (!routeAddress(req, res, url, mount))
+            return routedPath(req, undefined);
+        routedPath(req, url.pathname);
+        if (answering.served)
+            servedApp(req, answering.served(url));
+        // The orchestrator's probes, before any door: they are no product's.
+        if (probe(req, res, url.pathname, options.ready) || answering.ahead?.(req, res, url, mount))
+            return;
+        const operation = answering.answer(req, res, url, mount).catch((err) => {
+            if (answering.failed?.(err, req, res, url))
+                return;
+            /* The client left: its request was cut off mid-body, or it closed the
+           socket before the answer, and what failed was the read it no longer
+           waits for. Nobody can be answered and nothing went wrong on this
+           side, so it is not a 500 on the operator's terminal: the request's
+           span still says it was aborted (traceRequest.ts). */
+            if (clientLeft(req, res, err)) {
+                res.destroy();
+                return;
+            }
+            /* The pool had no connection to give within its budget: the server is
+           busy, which is neither the caller's mistake nor a failure, and a 500
+           after ten seconds said both. Answered now, with when to come back. */
+            if (isPoolBusy(err) && !res.headersSent) {
+                reportRefusal(req, 503, 'server_busy', err.message, err);
+                return sendBusy(res, {}, false, err);
+            }
+            const status = statusOf(err, answering);
+            if (answering.said?.(err, req, res, status))
+                return;
+            reportRefusal(req, status, undefined, err.message, err);
+            send(res, status, { error: err.message });
+        });
+        if (options.drainRequests || answering.drains?.(url)) {
+            pending.add(operation);
+            void operation.finally(() => pending.delete(operation));
+        }
+    })));
+    commandOperations.set(server, pending);
+    if (SOURCE_CLIENT && options.sourceClient !== false)
+        attachDevClient(server);
+    /* Explicit, rather than Node's defaults; serverTimeouts.ts says why. */
+    /* Outermost, so a request's timing covers every listener above (serverTiming.ts); nothing when off. */
+    timeRequests(server);
+    applyServerTimeouts(server);
+    return server;
+}
+/** Whether a request failed only because its client went away. */
+function clientLeft(req, res, error) {
+    if (res.headersSent)
+        return false;
+    const gone = req.destroyed || res.destroyed || res.writableEnded;
+    const code = error?.code;
+    const stopped = error instanceof Error &&
+        (error.name === 'StatementStopped' || error.name === 'AbortError' || (error.message === 'aborted' && code === 'ECONNRESET'));
+    return gone && (stopped || code === 'ECONNRESET' || code === 'ERR_STREAM_PREMATURE_CLOSE');
+}

package/dist/server/http/traceRequest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The span of one HTTP request, as the semantic conventions name it:
+ * `GET /api/query`, kind server, with the method, the route template and the
+ * status. The route is a template the server declares, never the path the
+ * browser sent: a tablewalk path can carry a whole query (`/demo/invoice
+ * total > 500`), a record id or a public slug.
+ *
+ * An incoming W3C `traceparent` makes the request a child of its caller's
+ * trace. For the dev observer (and only then) the raw exchange is kept as
+ * local detail: the path, the headers, and the bodies both ways, bounded.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Run a request's handling inside its span, ended when the response closes. */
+export declare function traceRequest(req: IncomingMessage, res: ServerResponse, handle: () => void): void;
+/** The App a request was served for, by its id: what the observer lists a request under. */
+export declare function servedApp(req: IncomingMessage, appId: string | undefined): void;
+/**
+ * The request's address as the routes read it — the base path off, an App
+ * at the root read back to `/{app}/…` (shared/mount.ts) — names its span.
+ * The observer's own requests and the orchestrator's probes are dropped here:
+ * the first would observe itself, the second is a heartbeat every few seconds.
+ */
+export declare function routedPath(req: IncomingMessage, path: string | undefined): void;
+/**
+ * Give a server built elsewhere (the tenant servers) what `createApp` gives
+ * its own: a span per request, and the reserved addresses — the
+ * orchestrator's probes and the dev observer — answered before its handler.
+ * Wraps the handler already registered, so the server's own code is unchanged.
+ */
+export declare function platformRequests(server: import('node:http').Server, reserved: (req: IncomingMessage, res: ServerResponse) => boolean): void;

package/dist/server/http/traceRequest.js

@@ -0,0 +1,224 @@
+import { observing, parseTraceparent, startSpan, tracing, withSpan } from '../../adapters/telemetry/trace.js';
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+/* Every fixed API path the servers answer, as themselves. Anything else under
+   /api/ keeps only word-like leading segments: a key never becomes a label. */
+const API = new Set([
+    '/api/connections',
+    '/api/connections/test',
+    '/api/connections/demo',
+    '/api/connections/update',
+    '/api/connections/remove',
+    '/api/connections/save',
+    '/api/connections/select',
+    '/api/connections/refresh',
+    '/api/whoami',
+    '/api/app',
+    '/api/app/live',
+    '/api/schema',
+    '/api/ddl',
+    '/api/views',
+    '/api/queries',
+    '/api/layouts',
+    '/api/pages',
+    '/api/pages/relations',
+    '/api/pages/suggested',
+    '/api/pages/saved',
+    '/api/pages/save',
+    '/api/filters',
+    '/api/filters/save',
+    '/api/agent/tools',
+    '/api/agent/call',
+    '/api/query',
+    '/api/run',
+    '/api/breakdown',
+    '/api/breakdowns',
+    '/api/view/run',
+    '/api/view/compile',
+    '/api/count',
+    '/api/counts',
+    '/api/export',
+    '/api/references',
+    '/api/pages/plan',
+    '/api/pages/load',
+    '/api/http/operations',
+    '/api/http/operation',
+    '/api/update',
+    '/api/insert',
+    '/api/delete',
+    '/api/revert',
+    '/api/sql',
+    '/api/commands/execute',
+    '/api/commands/status',
+    '/api/commands/prepare',
+    '/api/commands/availability',
+    '/api/import',
+    '/api/file/upload',
+    '/api/record',
+    '/api/history',
+    '/api/inbox',
+    '/api/operations/readiness',
+    '/api/operations/support',
+]);
+/** The route template a path is reported under. */
+function routeTemplate(path) {
+    if (API.has(path))
+        return path;
+    if (path === '/api/auth' || path.startsWith('/api/auth/'))
+        return '/api/auth/*';
+    if (path.startsWith('/api/')) {
+        const words = path
+            .split('/')
+            .slice(2, 4)
+            .filter((segment) => /^[a-z][a-z_-]{0,31}$/.test(segment));
+        return `/api/${words.length ? `${words.join('/')}/` : ''}*`;
+    }
+    if (path === '/healthz' || path === '/readyz')
+        return path;
+    if (path.startsWith('/_mistri/'))
+        return '/_mistri/*';
+    // A file: the client's modules and assets, Vite's own paths in dev.
+    if (/\.[a-z0-9]{1,8}$/i.test(path) || path.startsWith('/@') || path.startsWith('/node_modules/'))
+        return '/{asset}';
+    return '/{page}';
+}
+/** Local detail is capped per body: enough to read a command's input, never a whole export. */
+const BODY_CAP = 64 * 1024;
+/** Keep what a request sent and was sent back, for the dev observer. */
+function keepExchange(req, res, span) {
+    const sent = [];
+    let sentSize = 0;
+    const push = req.push;
+    // The parser hands the body to `push`, whoever reads it and however: tapping here never changes how it flows.
+    req.push = function (chunk, encoding) {
+        if (chunk && sentSize < BODY_CAP) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), encoding);
+            sent.push(buffer.subarray(0, BODY_CAP - sentSize));
+            sentSize += buffer.length;
+        }
+        return push.call(this, chunk, encoding);
+    };
+    const answered = [];
+    let answeredSize = 0;
+    const keep = (chunk, encoding) => {
+        if (!chunk || typeof chunk === 'function' || answeredSize >= BODY_CAP)
+            return;
+        const buffer = Buffer.isBuffer(chunk)
+            ? chunk
+            : chunk instanceof Uint8Array
+                ? Buffer.from(chunk)
+                : Buffer.from(String(chunk), typeof encoding === 'string' ? encoding : 'utf8');
+        answered.push(buffer.subarray(0, BODY_CAP - answeredSize));
+        answeredSize += buffer.length;
+    };
+    const write = res.write, end = res.end;
+    res.write = function (chunk, ...rest) {
+        keep(chunk, rest[0]);
+        return write.call(this, chunk, ...rest);
+    };
+    res.end = function (chunk, ...rest) {
+        keep(chunk, rest[0]);
+        return end.call(this, chunk, ...rest);
+    };
+    return () => {
+        const type = String(res.getHeader('content-type') ?? '');
+        const encoded = res.getHeader('content-encoding');
+        const readable = /json|text|javascript|xml|form/i.test(type) && !encoded;
+        span.detail(() => ({
+            request: {
+                method: req.method,
+                url: req.url,
+                headers: { ...req.headers },
+                ...(sentSize ? { body: Buffer.concat(sent).toString('utf8'), bodyBytes: sentSize, truncated: sentSize > BODY_CAP } : {}),
+            },
+            response: {
+                status: res.statusCode,
+                headers: res.getHeaders(),
+                ...(answeredSize
+                    ? readable
+                        ? { body: Buffer.concat(answered).toString('utf8'), bodyBytes: answeredSize, truncated: answeredSize > BODY_CAP }
+                        : { bodyBytes: answeredSize, body: `(${encoded ? `${encoded}-encoded ` : ''}${type || 'untyped'} body not shown)` }
+                    : {}),
+            },
+        }));
+    };
+}
+/** Run a request's handling inside its span, ended when the response closes. */
+export function traceRequest(req, res, handle) {
+    if (!tracing())
+        return handle();
+    const method = METHODS.has(req.method ?? '') ? req.method : '_OTHER';
+    // Named for now as the browser spelled it; `routedPath` renames it once the address is read inward.
+    const route = routeTemplate((req.url ?? '/').split('?')[0]);
+    const span = startSpan(`${method} ${route}`, {
+        kind: 'server',
+        remote: parseTraceparent(req.headers.traceparent, req.headers.tracestate),
+        attributes: { 'http.request.method': method, 'http.route': route, 'url.scheme': 'http', 'network.protocol.version': req.httpVersion },
+    });
+    requests.set(req, { span, method });
+    const exchange = observing() ? keepExchange(req, res, span) : undefined;
+    if (observing() && !res.headersSent)
+        res.setHeader('x-mistri-trace', span.traceId);
+    res.once('close', () => {
+        const status = res.headersSent ? res.statusCode : undefined;
+        if (status !== undefined)
+            span.setAttribute('http.response.status_code', status);
+        /* A request the browser gave up on — a navigation away, a superseded
+           fetch — is not a failure of the server's: said as aborted, apart from errors. */
+        if (status === undefined || !res.writableFinished)
+            span.setAttribute('mistri.request.aborted', true);
+        else if (status >= 500)
+            span.fail(String(status));
+        exchange?.();
+        span.end();
+    });
+    withSpan(span, handle);
+}
+const requests = new WeakMap();
+const VITE_PATH = /^\/(?:@vite\/|@react-refresh|@fs\/|@id\/|node_modules\/)/;
+/** The App a request was served for, by its id: what the observer lists a request under. */
+export function servedApp(req, appId) {
+    if (appId)
+        requests.get(req)?.span.setAttribute('mistri.app.id', appId);
+}
+/**
+ * The request's address as the routes read it — the base path off, an App
+ * at the root read back to `/{app}/…` (shared/mount.ts) — names its span.
+ * The observer's own requests and the orchestrator's probes are dropped here:
+ * the first would observe itself, the second is a heartbeat every few seconds.
+ */
+export function routedPath(req, path) {
+    const traced = requests.get(req);
+    if (!traced)
+        return;
+    if (path === undefined) {
+        traced.span.rename(`${traced.method} /{unrouted}`);
+        traced.span.setAttribute('http.route', '/{unrouted}');
+        return;
+    }
+    if (path.startsWith('/_mistri/') || path === '/healthz' || path === '/readyz') {
+        traced.span.discard();
+        return;
+    }
+    /* Vite's own paths in dev (`/@vite/client`, `/@react-refresh`) are files
+       as the browser asked for them, whatever an App at the root reads them as. */
+    const route = VITE_PATH.test((req.url ?? '/').split('?')[0]) ? '/{asset}' : routeTemplate(path);
+    traced.span.rename(`${traced.method} ${route}`);
+    traced.span.setAttribute('http.route', route);
+}
+/**
+ * Give a server built elsewhere (the tenant servers) what `createApp` gives
+ * its own: a span per request, and the reserved addresses — the
+ * orchestrator's probes and the dev observer — answered before its handler.
+ * Wraps the handler already registered, so the server's own code is unchanged.
+ */
+export function platformRequests(server, reserved) {
+    const listeners = server.listeners('request');
+    server.removeAllListeners('request');
+    for (const listener of listeners) {
+        server.on('request', (req, res) => traceRequest(req, res, () => {
+            routedPath(req, (req.url ?? '/').split('?')[0]);
+            if (!reserved(req, res))
+                listener.call(server, req, res);
+        }));
+    }
+}