@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/host/gates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The gates service's process (blueprint §15, §19): one listener serving the Model Gate's and
+ * the Tool Gate's routes (`api/gate/routes.ts`), behind the same `Host` check as the Runtime's
+ * listeners.
+ * It opens no Tenant runtime, no Restate endpoint and no stream relay, and runs no migration;
+ * it needs only the Postgres pool and the Host's tenant directory (read-only).
+ *
+ * Nothing is written while a model call runs, so the server's request timeout sits above the
+ * gate's longest call. Closing stops accepting calls, lets running ones finish for up to
+ * `drainMs`, then aborts them (their providers' requests with them).
+ */
+import { type Server } from "node:http";
+import { type InflightCallsOptions } from "../gates/inflight.js";
+import type { openMcpServer } from "../mcp/connect.js";
+import type { OutboundPolicy } from "../tenant/outbound.js";
+import type { ModelCallSettings } from "../gates/model-gate.js";
+import { type TenantVaults } from "../gates/tenant-vaults.js";
+import type { PostgresClient } from "../store/postgres/connect.js";
+import type { Logger } from "../tenant/types.js";
+import type { GatesConfig } from "./stack-config.js";
+/** Above the gate's 600 s provider request timeout and the loop's 630 s client timeout. */
+export declare const GATES_REQUEST_TIMEOUT_MS = 660000;
+export interface StartGatesOptions {
+    readonly gates: GatesConfig;
+    readonly logger: Logger;
+    /** The Host root, for the Tenant's vault key. Required unless `vaults` is given. */
+    readonly hostRoot?: string;
+    /** The pool for the Tenant's vault and readiness. Required unless `vaults` is given. */
+    readonly database?: PostgresClient;
+    /** Replaces the Postgres-backed Tenant vault (tests). */
+    readonly vaults?: TenantVaults;
+    /** Retries and timeouts of model calls (tests). */
+    readonly settings?: ModelCallSettings;
+    /** Largest model call body (tests). */
+    readonly maxBodyBytes?: number;
+    /** How long `close` lets running calls finish. Default 10 s. */
+    readonly drainMs?: number;
+    /** How long keyed outcomes are kept, and how many (tests). */
+    readonly inflight?: InflightCallsOptions;
+    /** How the gate may call Action endpoints (`NYLORUN_ENDPOINT_*`). Default: no limits. */
+    readonly delivery?: OutboundPolicy;
+    /** How long an MCP connection may sit unused. Default `GATE_MCP_IDLE_MS`. */
+    readonly mcpIdleMs?: number;
+    /** Tests replace how a remote MCP server is opened. */
+    readonly openMcp?: typeof openMcpServer;
+    /**
+     * Serve the keys service too (`--service gates,keys`, F4.2): vault writes and token signing
+     * with the Tenant's vault key. The gateway is then not ready until the key file is there.
+     */
+    readonly keys?: boolean;
+}
+export interface GatesServer {
+    /** Where the gate listens, e.g. `http://0.0.0.0:4100`. */
+    readonly url: string;
+    readonly server: Server;
+    close(): Promise<void>;
+}
+export declare function startGates(options: StartGatesOptions): Promise<GatesServer>;

package/dist/host/gates.js

@@ -0,0 +1,127 @@
+/**
+ * The gates service's process (blueprint §15, §19): one listener serving the Model Gate's and
+ * the Tool Gate's routes (`api/gate/routes.ts`), behind the same `Host` check as the Runtime's
+ * listeners.
+ * It opens no Tenant runtime, no Restate endpoint and no stream relay, and runs no migration;
+ * it needs only the Postgres pool and the Host's tenant directory (read-only).
+ *
+ * Nothing is written while a model call runs, so the server's request timeout sits above the
+ * gate's longest call. Closing stops accepting calls, lets running ones finish for up to
+ * `drainMs`, then aborts them (their providers' requests with them).
+ */
+import { createServer } from "node:http";
+import { getRequestListener } from "@hono/node-server";
+import { createGatesApp } from "../api/gate/routes.js";
+import { createModelCallHandler } from "../gates/handler.js";
+import { createInflightCalls } from "../gates/inflight.js";
+import { createMcpHandler, GATE_MCP_IDLE_MS } from "../gates/mcp-handler.js";
+import { createToolCalls } from "../gates/tool-calls.js";
+import { existsSync } from "node:fs";
+import { tenantPaths } from "../tenant/paths.js";
+import { createTenantVaults } from "../gates/tenant-vaults.js";
+import { probeDatabase } from "../infra/database.js";
+import { bindListener, headerValue, isAllowedRequestHost, sendRejected } from "./http.js";
+/** Above the gate's 600 s provider request timeout and the loop's 630 s client timeout. */
+export const GATES_REQUEST_TIMEOUT_MS = 660_000;
+export async function startGates(options) {
+    const { gates, logger, database } = options;
+    let vaults = options.vaults;
+    if (!vaults) {
+        if (!database || options.hostRoot === undefined)
+            throw new Error("startGates needs the Postgres pool and the Host root");
+        vaults = createTenantVaults({ sql: database, hostRoot: options.hostRoot });
+    }
+    const inflight = createInflightCalls(options.inflight);
+    const mcpIdleMs = options.mcpIdleMs ?? GATE_MCP_IDLE_MS;
+    const mcp = createMcpHandler({
+        vaults,
+        logger,
+        idleMs: mcpIdleMs,
+        ...(options.openMcp ? { open: options.openMcp } : {}),
+    });
+    const toolCalls = createToolCalls({
+        vaults,
+        mcp,
+        logger,
+        ...(options.inflight ? { inflight: options.inflight } : {}),
+    });
+    const sweep = setInterval(() => void mcp.sweep(), Math.max(1_000, Math.min(mcpIdleMs, 60_000)));
+    sweep.unref();
+    const prune = setInterval(() => void toolCalls.prune(), 60 * 60_000);
+    prune.unref();
+    const app = createGatesApp({
+        token: gates.token,
+        inflight,
+        modelGate: createModelCallHandler({
+            vaults,
+            logger,
+            ...(options.settings ? { settings: options.settings } : {}),
+        }),
+        ready: async () => {
+            // The keys service needs the vault key, which `nylorun start` writes; it never creates one.
+            if (options.keys && options.hostRoot !== undefined && !existsSync(tenantPaths(options.hostRoot).kek))
+                return false;
+            if (!database)
+                return true;
+            try {
+                await probeDatabase(database, AbortSignal.timeout(2000));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        ...(options.maxBodyBytes !== undefined ? { maxBodyBytes: options.maxBodyBytes } : {}),
+        mcp,
+        toolCalls,
+        delivery: options.delivery ?? {},
+        logger,
+        ...(options.keys ? { keys: async () => (await vaults.open()).keys() } : {}),
+    });
+    const listener = getRequestListener(app.fetch);
+    const inFlight = new Set();
+    // The configured Host values, plus the loopback forms of the port actually bound (probes
+    // from inside the container; port 0 in tests).
+    let allowedHosts = gates.listen.allowedHosts;
+    const server = createServer((req, res) => {
+        if (!isAllowedRequestHost(headerValue(req, "host"), {
+            port: gates.listen.port,
+            host: gates.listen.host,
+            allowedHosts,
+        }))
+            return sendRejected(res, 421, "host_rejected", "Host header is not an allowed address of the gateway");
+        inFlight.add(res);
+        res.once("close", () => inFlight.delete(res));
+        void listener(req, res);
+    });
+    server.requestTimeout = GATES_REQUEST_TIMEOUT_MS;
+    await bindListener(server, gates.listen.port, gates.listen.host, (error) => logger.error("listener_error", { error: error.message }));
+    const port = server.address().port;
+    allowedHosts = [
+        ...new Set([...allowedHosts, `localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`]),
+    ];
+    const url = `http://${gates.listen.host.includes(":") ? `[${gates.listen.host}]` : gates.listen.host}:${port}`;
+    let closing;
+    return {
+        url,
+        server,
+        close() {
+            closing ??= (async () => {
+                const closed = new Promise((resolve) => server.close(() => resolve()));
+                server.closeIdleConnections();
+                const deadline = Date.now() + (options.drainMs ?? 10_000);
+                while (inFlight.size > 0 && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+                // Closing a running call's connection aborts an unkeyed one; keyed calls stop here.
+                server.closeAllConnections();
+                inflight.close();
+                toolCalls.close();
+                clearInterval(sweep);
+                clearInterval(prune);
+                await mcp.closeAll();
+                await closed;
+            })();
+            return closing;
+        },
+    };
+}

package/dist/host/http.d.ts

@@ -1,4 +1,5 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import { jsonResponse } from "../api/http/respond.js";
 import { type ErrorCode, type ProtocolRange } from "@nylorun/core/compatibility";
 export declare const OPAQUE_NOT_FOUND: {
     status: "rejected";
@@ -12,10 +13,18 @@ export declare class HostListenError extends Error {
     readonly cause?: unknown;
     constructor(message: string, exitCode: number, cause?: unknown);
 }
+/**
+ * Binds `listening` on `host:port`. A port in use rejects with `HostListenError` (exit 98);
+ * once bound, a listener error goes to `onError` rather than being lost.
+ */
+export declare function bindListener(listening: Server, port: number, host: string, onError: (error: Error) => void): Promise<void>;
 export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
+/** `sendJson` as a Response, byte for byte (with any extra headers): the Host's answers. */
+export { jsonResponse };
 export declare function sendRejected(response: ServerResponse, status: number, code: ErrorCode, message: string, details?: unknown): void;
-export declare function sendOpaqueNotFound(response: ServerResponse): void;
-export declare function sendProtocolRejected(response: ServerResponse, protocol?: ProtocolRange): void;
+export declare function rejectedResponse(status: number, code: ErrorCode, message: string, details?: unknown): Response;
+export declare function opaqueNotFoundResponse(): Response;
+export declare function protocolRejectedResponse(protocol?: ProtocolRange): Response;
 /**
  * D§11 Host allowlist: loopback forms with the listening port, plus the
  * configured host when `allowNonLoopback` is set.
@@ -32,8 +41,15 @@ export declare function isAllowedRequestHost(hostHeader: string | undefined, opt
 export declare function isJsonContentType(value: string | undefined): boolean;
 /** True when the request carries a body (Content-Length > 0 or chunked). */
 export declare function requestHasBody(request: IncomingMessage): boolean;
+/** `/health` and `/ready` are polled; the request log leaves them out. */
+export declare function pathnameIsLogged(rawUrl: string | undefined): boolean;
 /** Redact path parameters after `/v1/sessions/` for Host logs. */
 export declare function redactRoutePath(pathname: string): string;
+/** Constant-time comparison of SHA-256 digests of the presented and stored admin keys. */
+export declare function adminKeyMatches(presented: string | undefined, adminKey: string): boolean;
+/** A request header's first value. */
+export declare function headerValue(incoming: IncomingMessage, name: string): string | undefined;
 export declare function readBearer(authorization: string | undefined): string | undefined;
-export declare function readJsonBody(request: import("node:http").IncomingMessage, limit?: number): Promise<unknown>;
+/** A JSON request body, capped at `limit` bytes (413); `undefined` when there is none. */
+export declare function readJsonBody(request: Request, limit?: number): Promise<unknown>;
 export declare function isLoopbackHost(host: string): boolean;

package/dist/host/http.js

@@ -1,3 +1,5 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { jsonResponse } from "../api/http/respond.js";
 import { HOST_PROTOCOL, } from "@nylorun/core/compatibility";
 export const OPAQUE_NOT_FOUND = {
     status: "rejected",
@@ -16,26 +18,45 @@ export class HostListenError extends Error {
         this.name = "HostListenError";
     }
 }
+/**
+ * Binds `listening` on `host:port`. A port in use rejects with `HostListenError` (exit 98);
+ * once bound, a listener error goes to `onError` rather than being lost.
+ */
+export function bindListener(listening, port, host, onError) {
+    return new Promise((resolve, reject) => {
+        const failed = (error) => reject(error.code === "EADDRINUSE"
+            ? new HostListenError(`Port ${port} on ${host} is already in use`, EXIT_PORT_IN_USE, error)
+            : error);
+        listening.once("error", failed);
+        listening.listen(port, host, () => {
+            listening.off("error", failed);
+            listening.on("error", onError);
+            resolve();
+        });
+    });
+}
 export function sendJson(response, status, body) {
     const payload = JSON.stringify(body);
     // No Access-Control-* headers (D§11).
-    response.writeHead(status, {
-        "content-type": "application/json",
-        "content-length": Buffer.byteLength(payload),
-    });
+    response.writeHead(status, jsonHeaders(payload));
     response.end(payload);
 }
-export function sendRejected(response, status, code, message, details) {
+/** `sendJson` as a Response, byte for byte (with any extra headers): the Host's answers. */
+export { jsonResponse };
+function jsonHeaders(payload) {
+    return {
+        "content-type": "application/json",
+        "content-length": String(Buffer.byteLength(payload)),
+    };
+}
+function rejection(code, message, details) {
     const body = { status: "rejected", code, message };
     if (details !== undefined)
         body.details = details;
-    sendJson(response, status, body);
+    return body;
 }
-export function sendOpaqueNotFound(response) {
-    sendJson(response, 404, OPAQUE_NOT_FOUND);
-}
-export function sendProtocolRejected(response, protocol = HOST_PROTOCOL) {
-    sendJson(response, 426, {
+function protocolRejection(protocol) {
+    return {
         status: "rejected",
         code: "protocol_unsupported",
         protocol: {
@@ -43,7 +64,19 @@ export function sendProtocolRejected(response, protocol = HOST_PROTOCOL) {
             max: protocol.max,
             features: [...protocol.features],
         },
-    });
+    };
+}
+export function sendRejected(response, status, code, message, details) {
+    sendJson(response, status, rejection(code, message, details));
+}
+export function rejectedResponse(status, code, message, details) {
+    return jsonResponse(status, rejection(code, message, details));
+}
+export function opaqueNotFoundResponse() {
+    return jsonResponse(404, OPAQUE_NOT_FOUND);
+}
+export function protocolRejectedResponse(protocol = HOST_PROTOCOL) {
+    return jsonResponse(426, protocolRejection(protocol));
 }
 /**
  * D§11 Host allowlist: loopback forms with the listening port, plus the
@@ -95,6 +128,13 @@ export function requestHasBody(request) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0;
 }
+/** `/health` and `/ready` are polled; the request log leaves them out. */
+export function pathnameIsLogged(rawUrl) {
+    if (!rawUrl)
+        return true;
+    const pathname = new URL(rawUrl, "http://runtime.local").pathname;
+    return pathname !== "/health" && pathname !== "/ready";
+}
 /** Redact path parameters after `/v1/sessions/` for Host logs. */
 export function redactRoutePath(pathname) {
     const parts = pathname.split("/");
@@ -104,34 +144,52 @@ export function redactRoutePath(pathname) {
     }
     return pathname;
 }
+/** Constant-time comparison of SHA-256 digests of the presented and stored admin keys. */
+export function adminKeyMatches(presented, adminKey) {
+    if (presented === undefined)
+        return false;
+    const a = createHash("sha256").update(presented, "utf8").digest();
+    const b = createHash("sha256").update(adminKey, "utf8").digest();
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** A request header's first value. */
+export function headerValue(incoming, name) {
+    const raw = incoming.headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0];
+    return raw;
+}
 export function readBearer(authorization) {
     if (!authorization)
         return undefined;
     const match = /^Bearer\s+(\S+)/i.exec(authorization.trim());
     return match?.[1];
 }
+/** A JSON request body, capped at `limit` bytes (413); `undefined` when there is none. */
 export async function readJsonBody(request, limit = 1024 * 1024) {
+    if (request.body === null)
+        return undefined;
     const chunks = [];
     let size = 0;
-    for await (const chunk of request) {
-        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buf.length;
+    const reader = request.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
         if (size > limit) {
-            const error = new Error("Request too large");
-            error.status = 413;
-            throw error;
+            await reader.cancel();
+            throw Object.assign(new Error("Request too large"), { status: 413 });
         }
-        chunks.push(buf);
+        chunks.push(value);
     }
-    if (chunks.length === 0)
+    if (size === 0)
         return undefined;
     try {
         return JSON.parse(Buffer.concat(chunks).toString("utf8"));
     }
     catch {
-        const error = new Error("Invalid JSON");
-        error.status = 400;
-        throw error;
+        throw Object.assign(new Error("Invalid JSON"), { status: 400 });
     }
 }
 export function isLoopbackHost(host) {

package/dist/host/index.d.ts

@@ -4,5 +4,5 @@ export { createHost, adminKeyMatches, type CreateHostOptions, type HostServer }
 export { createHostLogger } from "./logger.js";
 export { configForFactory } from "./config-for.js";
 export { createHostExecution, type CreateHostExecutionOptions, type HostExecution, } from "./execution.js";
-export { parseStackConfig, StackConfigError, type ContainerListen, type RuntimeRole, type StackConfig, type StackEndpoints, } from "./stack-config.js";
+export { parseStackConfig, StackConfigError, type ContainerListen, type RuntimeRole, type RuntimeService, type RuntimeServices, type StackConfig, type StackEndpoints, } from "./stack-config.js";
 export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, HostListenError, OPAQUE_NOT_FOUND, } from "./http.js";