@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/host/create-host.js

@@ -1,42 +1,13 @@
 import { createServer, } from "node:http";
-import { createHash, timingSafeEqual } from "node:crypto";
-import { checkCompatibility, HOST_PROTOCOL, isTenantId, PROTOCOL_HEADER, TENANT_HEADER, } from "@nylorun/core/compatibility";
-import { AdminStatusSchema, CreateTenantRequestSchema, } from "@nylorun/core/contracts";
-import { TenantBusyError, TenantConflictError, } from "../tenant/quarantine.js";
-import { TenantNotFoundError, } from "../tenant/types.js";
-import { EXIT_NON_LOOPBACK, EXIT_PORT_IN_USE, HostListenError, isAllowedRequestHost, isJsonContentType, isLoopbackHost, readBearer, readJsonBody, redactRoutePath, requestHasBody, sendJson, sendOpaqueNotFound, sendProtocolRejected, sendRejected, } from "./http.js";
+import { getRequestListener, RequestError } from "@hono/node-server";
+import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
+import { AdminStatusSchema } from "@nylorun/core/contracts";
+import { adminDocument } from "../api/openapi.js";
+import { createAdminApi } from "./admin-api.js";
+import { createHostApp } from "./app.js";
+import { EXIT_NON_LOOPBACK, EXIT_PORT_IN_USE, headerValue, HostListenError, isAllowedRequestHost, isLoopbackHost, pathnameIsLogged, redactRoutePath, rejectedResponse, sendRejected, } from "./http.js";
 import { RUNTIME_VERSION } from "../version.js";
-function hashUtf8(value) {
-    return createHash("sha256").update(value, "utf8").digest();
-}
-/** 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 = hashUtf8(presented);
-    const b = hashUtf8(adminKey);
-    return a.length === b.length && timingSafeEqual(a, b);
-}
-function headerValue(headers, name) {
-    const raw = headers[name.toLowerCase()];
-    if (Array.isArray(raw))
-        return raw[0];
-    return raw;
-}
-function parseProtocolVersion(raw) {
-    if (raw === undefined)
-        return undefined;
-    const trimmed = raw.trim();
-    if (!/^\d+$/.test(trimmed))
-        return undefined;
-    return Number(trimmed);
-}
-function protocolAccepted(raw) {
-    const version = parseProtocolVersion(raw);
-    if (version === undefined)
-        return false;
-    return checkCompatibility({ version, required: [] }, HOST_PROTOCOL).ok;
-}
+export { adminKeyMatches } from "./http.js";
 export function createHost(options) {
     const { hostRoot, module, config, credentials, logger, coreVersion, } = options;
     const pid = options.pid ?? process.pid;
@@ -46,6 +17,11 @@ export function createHost(options) {
     let server;
     let url = "";
     let listenPort = bindPort;
+    const operator = options.operator;
+    let operatorServer;
+    let operatorPort = operator?.port ?? 0;
+    let adminUrl = "";
+    const mainRole = operator ? "public" : "combined";
     let closing = false;
     let closePromise;
     const adminStatusBody = async () => {
@@ -68,276 +44,87 @@ export function createHost(options) {
             },
         });
     };
-    const requireAdmin = (request, response) => {
-        const token = readBearer(headerValue(request.headers, "authorization"));
-        if (!adminKeyMatches(token, credentials.adminKey)) {
-            sendOpaqueNotFound(response);
-            return false;
-        }
-        return true;
-    };
-    const handleAdmin = async (request, response, urlObj, segments) => {
-        const method = request.method ?? "GET";
-        // /v1/admin/...
-        if (segments[2] === "tenants") {
-            if (segments.length === 3 && method === "GET") {
-                const tenants = await module.list();
-                return sendJson(response, 200, tenants);
-            }
-            if (segments.length === 3 && method === "POST") {
-                const body = CreateTenantRequestSchema.parse(await readJsonBody(request));
-                try {
-                    const result = await module.create({
-                        tenantId: body.tenantId,
-                        name: body.name,
-                        principalId: body.principalId,
-                        credentialHash: body.credentialHash,
-                        idempotencyKey: body.idempotencyKey,
-                        ...(body.studioCredentialHash
-                            ? { studioCredentialHash: body.studioCredentialHash }
-                            : {}),
-                        ...(body.derivedPrincipals?.length
-                            ? { derivedPrincipals: body.derivedPrincipals }
-                            : {}),
-                    });
-                    return sendJson(response, result.created ? 201 : 200, result.envelope);
-                }
-                catch (error) {
-                    const code = error.code;
-                    if (error instanceof TenantConflictError ||
-                        error.name === "TenantConflictError" ||
-                        code === "conflict" ||
-                        code === "tenant_conflict") {
-                        return sendRejected(response, 409, "tenant_conflict", error instanceof Error ? error.message : "Tenant conflict");
-                    }
-                    throw error;
-                }
-            }
-            if (segments.length === 4 && segments[3]) {
-                const id = segments[3];
-                if (method === "GET") {
-                    const status = await module.status(id);
-                    if (!status)
-                        return sendOpaqueNotFound(response);
-                    return sendJson(response, 200, status);
-                }
-                if (method === "DELETE") {
-                    const activeWork = urlObj.searchParams.get("activeWork") ?? "refuse";
-                    if (activeWork !== "refuse" &&
-                        activeWork !== "drain" &&
-                        activeWork !== "cancel") {
-                        return sendJson(response, 400, {
-                            status: "rejected",
-                            code: "invalid_request",
-                            message: "activeWork must be refuse, drain, or cancel",
-                        });
-                    }
-                    try {
-                        await module.delete(id, activeWork);
-                        response.writeHead(204);
-                        response.end();
-                        return;
-                    }
-                    catch (error) {
-                        if (error instanceof TenantNotFoundError)
-                            return sendOpaqueNotFound(response);
-                        const code = error.code;
-                        if (error instanceof TenantBusyError ||
-                            error.name === "TenantBusyError" ||
-                            code === "active_work" ||
-                            code === "conflict") {
-                            return sendRejected(response, 409, "active_work", error instanceof Error ? error.message : "Active work");
-                        }
-                        throw error;
-                    }
-                }
-            }
-        }
-        // D12: /v1/admin/status and /v1/admin/host share one handler.
-        if ((segments[2] === "host" || segments[2] === "status") &&
-            segments.length === 3 &&
-            method === "GET") {
-            return sendJson(response, 200, await adminStatusBody());
-        }
-        if (segments[2] === "host" &&
-            segments.length === 4 &&
-            segments[3] === "shutdown" &&
-            method === "POST") {
-            sendJson(response, 200, { status: "shutting_down" });
-            void close();
-            return;
-        }
-        return sendRejected(response, 404, "not_found", "Route not found");
-    };
-    const handle = async (request, response) => {
-        const started = Date.now();
-        let tenantId;
-        let statusCode = 500;
-        try {
-            const urlObj = new URL(request.url ?? "/", "http://runtime.local");
-            const pathname = urlObj.pathname;
-            // D§11: Host, Origin, then Content-Type — before any other processing.
-            const hostHeader = headerValue(request.headers, "host");
-            if (!isAllowedRequestHost(hostHeader, {
-                port: listenPort,
-                host: config.host,
-                allowNonLoopback: config.allowNonLoopback,
-                ...(containerListen
-                    ? { allowedHosts: containerListen.allowedHosts }
-                    : {}),
-            })) {
-                sendRejected(response, 421, "host_rejected", "Host header is not an allowed loopback or configured address");
-                statusCode = 421;
-                return;
-            }
-            if (headerValue(request.headers, "origin") !== undefined) {
-                sendRejected(response, 403, "origin_rejected", "Browser Origin headers are not accepted");
-                statusCode = 403;
-                return;
-            }
-            if (requestHasBody(request) &&
-                !isJsonContentType(headerValue(request.headers, "content-type"))) {
-                sendRejected(response, 415, "unsupported_media_type", "Request bodies must use application/json");
-                statusCode = 415;
-                return;
-            }
-            if (pathname === "/health") {
-                sendJson(response, 200, {
-                    status: "ok",
-                    service: "nylorun-runtime",
-                    version: RUNTIME_VERSION,
-                    protocol: {
-                        min: HOST_PROTOCOL.min,
-                        max: HOST_PROTOCOL.max,
-                        features: [...HOST_PROTOCOL.features],
-                    },
-                    coreVersion,
-                    hostId: config.hostId,
-                    pid,
-                });
-                statusCode = 200;
-                return;
-            }
-            if (pathname === "/ready") {
-                const listener = Boolean(server?.listening);
-                const discovery = module.started;
-                const infra = await options.readiness?.();
-                const ready = listener && discovery && !closing && (infra?.ok ?? true);
-                sendJson(response, ready ? 200 : 503, {
-                    status: ready ? "ready" : "not_ready",
-                    service: "nylorun-runtime",
-                    checks: { listener, discovery, ...infra?.checks },
-                });
-                statusCode = ready ? 200 : 503;
-                return;
-            }
-            const segments = pathname.split("/").filter(Boolean);
-            const isAdmin = segments[0] === "v1" && segments[1] === "admin";
-            if (isAdmin) {
-                const protocolHeader = headerValue(request.headers, PROTOCOL_HEADER);
-                if (!protocolAccepted(protocolHeader)) {
-                    sendProtocolRejected(response);
-                    statusCode = 426;
-                    return;
-                }
-                if (!requireAdmin(request, response)) {
-                    statusCode = 404;
-                    return;
-                }
-                await handleAdmin(request, response, urlObj, segments);
-                statusCode = response.statusCode || 200;
-                return;
-            }
-            // Tenant-scoped routes: header pattern → protocol → resolve → Tenant handle.
-            const tenantHeader = headerValue(request.headers, TENANT_HEADER);
-            if (tenantHeader === undefined || tenantHeader.trim() === "") {
-                sendJson(response, 400, {
-                    status: "rejected",
-                    code: "invalid_request",
-                    message: `${TENANT_HEADER} header is required`,
-                });
-                statusCode = 400;
-                return;
-            }
-            if (!isTenantId(tenantHeader)) {
-                sendJson(response, 400, {
-                    status: "rejected",
-                    code: "invalid_request",
-                    message: `${TENANT_HEADER} header is malformed`,
-                });
-                statusCode = 400;
-                return;
-            }
-            tenantId = tenantHeader;
-            const protocolHeader = headerValue(request.headers, PROTOCOL_HEADER);
-            if (!protocolAccepted(protocolHeader)) {
-                sendProtocolRejected(response);
-                statusCode = 426;
-                return;
-            }
-            const resolution = await module.resolve(tenantId);
-            if (resolution.kind !== "open") {
-                if (resolution.kind === "quarantined") {
-                    logger.warn("tenant_quarantined", {
-                        tenantId,
-                        code: resolution.quarantine.code,
-                        repair: resolution.quarantine.repair,
-                    });
-                }
-                sendOpaqueNotFound(response);
-                statusCode = 404;
-                return;
-            }
-            await resolution.handle.handle(request, response, urlObj);
-            statusCode = response.statusCode || 200;
-        }
-        catch (error) {
-            const status = error.status;
-            if (typeof status === "number" && status >= 400 && status < 600) {
-                sendJson(response, status, {
-                    status: "rejected",
-                    code: status === 400 ? "invalid_request" : "request_rejected",
-                    message: error instanceof Error ? error.message : "Request rejected",
-                });
-                statusCode = status;
-            }
-            else if (error &&
-                typeof error === "object" &&
-                "name" in error &&
-                error.name === "ZodError") {
-                sendJson(response, 400, {
-                    status: "rejected",
-                    code: "invalid_request",
-                    message: "Invalid request body",
-                });
-                statusCode = 400;
-            }
-            else {
-                logger.error("request_failed", {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-                if (!response.headersSent) {
-                    sendJson(response, 500, {
-                        status: "rejected",
-                        code: "internal_error",
-                        message: "Internal error",
-                    });
-                }
-                statusCode = 500;
-            }
-        }
-        finally {
-            if (pathnameIsLogged(request.url)) {
+    const adminApi = createAdminApi({
+        module,
+        status: adminStatusBody,
+        shutdown: () => void close(),
+        document: adminDocument,
+    });
+    const app = createHostApp({
+        module,
+        logger,
+        hostId: config.hostId,
+        adminKey: credentials.adminKey,
+        coreVersion,
+        pid,
+        browserAccess: options.browserAccess === true,
+        ...(options.readiness ? { readiness: options.readiness } : {}),
+        listening: () => Boolean(server?.listening) && (!operator || Boolean(operatorServer?.listening)),
+        closing: () => closing,
+        admin: async (request, node) => await adminApi.fetch(request, node),
+    });
+    /** Where a listener's requests go once their `Host` header checks out. */
+    const pipeline = (role) => getRequestListener(async (request, node) => alreadySent(await app.fetch(request, { ...node, role })), {
+        // The Runtime runs inside other processes (`startEphemeralRuntime`): leave their
+        // `Request` and `Response` alone.
+        overrideGlobalObjects: false,
+        // A request target `@hono/node-server` cannot make a URL of, such as `*`.
+        errorHandler: (error) => {
+            if (error instanceof RequestError)
+                return rejectedResponse(400, "invalid_request", "Invalid request target");
+            logger.error("request_failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return rejectedResponse(500, "internal_error", "Internal error");
+        },
+    });
+    /** The `Host` values a listener accepts. */
+    const hostAllowed = (role, hostHeader) => role === "operator"
+        ? isAllowedRequestHost(hostHeader, {
+            port: operatorPort,
+            host: operator.host,
+            allowNonLoopback: false,
+            ...(operator.allowedHosts ? { allowedHosts: operator.allowedHosts } : {}),
+        })
+        : isAllowedRequestHost(hostHeader, {
+            port: listenPort,
+            host: config.host,
+            allowNonLoopback: config.allowNonLoopback,
+            ...(containerListen ? { allowedHosts: containerListen.allowedHosts } : {}),
+        });
+    /** Responses not yet finished; shutdown ends the streams among them. */
+    const inFlight = new Set();
+    const serve = (role) => {
+        const next = pipeline(role);
+        return (req, res) => {
+            const started = Date.now();
+            inFlight.add(res);
+            res.once("close", () => inFlight.delete(res));
+            // D§11: `Host` first, before anything reads the request.
+            if (hostAllowed(role, headerValue(req, "host")))
+                return void next(req, res);
+            sendRejected(res, 421, "host_rejected", "Host header is not an allowed loopback or configured address");
+            if (pathnameIsLogged(req.url))
                 logger.info("request", {
-                    status: statusCode,
-                    tenantId,
+                    status: 421,
                     durationMs: Date.now() - started,
-                    path: redactRoutePath(new URL(request.url ?? "/", "http://runtime.local").pathname),
-                    method: request.method,
+                    path: redactRoutePath(new URL(req.url ?? "/", "http://runtime.local").pathname),
+                    method: req.method,
                 });
-            }
-        }
+        };
     };
+    /** Binds `listening`; once bound, a listener error is logged rather than lost. */
+    const bindListener = (listening, port, host) => 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", (error) => logger.error("listener_error", { error: error.message }));
+            resolve();
+        });
+    });
     async function listen() {
         if (server)
             throw new Error("Already listening");
@@ -348,27 +135,35 @@ export function createHost(options) {
             !isLoopbackHost(config.host)) {
             throw new HostListenError(`Refusing to bind non-loopback host ${config.host} without allowNonLoopback`, EXIT_NON_LOOPBACK);
         }
-        server = createServer((req, res) => {
-            void handle(req, res);
-        });
-        await new Promise((resolve, reject) => {
-            server.once("error", (error) => {
-                if (error.code === "EADDRINUSE") {
-                    reject(new HostListenError(`Port ${bindPort} on ${bindHost} is already in use`, EXIT_PORT_IN_USE, error));
-                    return;
-                }
-                reject(error);
-            });
-            server.listen(bindPort, bindHost, resolve);
-        });
+        if (operator && !containerListen && !isLoopbackHost(operator.host))
+            throw new HostListenError(`Refusing to bind the operator listener on non-loopback host ${operator.host}`, EXIT_NON_LOOPBACK);
+        server = createServer(serve(mainRole));
+        await bindListener(server, bindPort, bindHost);
         const address = server.address();
         listenPort =
             typeof address === "object" && address ? address.port : bindPort;
         url = `http://${bindHost}:${listenPort}`;
+        adminUrl = url;
+        if (operator) {
+            operatorServer = createServer(serve("operator"));
+            await bindListener(operatorServer, operator.port, operator.host).catch(async (error) => {
+                // Leave nothing half-open: the main listener closes too.
+                await new Promise((resolve) => server.close(() => resolve()));
+                server = undefined;
+                throw error;
+            });
+            const operatorAddress = operatorServer.address();
+            operatorPort =
+                typeof operatorAddress === "object" && operatorAddress
+                    ? operatorAddress.port
+                    : operator.port;
+            adminUrl = `http://${operator.host}:${operatorPort}`;
+        }
         await module.start();
         logger.info("host_listening", {
             hostId: config.hostId,
             url,
+            ...(operator ? { adminUrl } : {}),
             pid,
         });
     }
@@ -393,13 +188,40 @@ export function createHost(options) {
         closePromise = (async () => {
             closing = true;
             logger.info("host_shutdown", { hostId: config.hostId });
-            if (server) {
-                await new Promise((resolve) => {
-                    server.close(() => resolve());
-                    server.closeIdleConnections?.();
-                });
-                server = undefined;
+            const listeners = [server, operatorServer].filter((listening) => listening !== undefined);
+            const stopped = Promise.all(listeners.map((listening) => new Promise((resolve) => {
+                listening.close(() => resolve());
+                listening.closeIdleConnections();
+            })));
+            // A stream never finishes by itself, and a listener closes only once every connection
+            // has: end the streams, close their connections once idle, let other requests finish,
+            // then cut what is left.
+            const streams = [...inFlight].filter(isStreaming);
+            void Promise.all(streams.map((response) => {
+                const done = new Promise((resolve) => response.once("close", resolve));
+                response.end();
+                return done;
+            })).then(() => {
+                for (const listening of listeners)
+                    listening.closeIdleConnections();
+            });
+            let grace;
+            const graceful = await Promise.race([
+                stopped.then(() => true),
+                new Promise((resolve) => {
+                    grace = setTimeout(() => resolve(false), SHUTDOWN_GRACE_MS);
+                    grace.unref();
+                }),
+            ]);
+            clearTimeout(grace);
+            if (!graceful) {
+                logger.warn("host_shutdown_forced", { openResponses: inFlight.size });
+                for (const listening of listeners)
+                    listening.closeAllConnections();
+                await stopped;
             }
+            server = undefined;
+            operatorServer = undefined;
             await step("beforeTenants", options.shutdown?.beforeTenants);
             await step("tenants", () => module.close());
             await step("afterTenants", options.shutdown?.afterTenants);
@@ -413,11 +235,30 @@ export function createHost(options) {
         get url() {
             return url;
         },
+        get adminUrl() {
+            return adminUrl;
+        },
     };
 }
-function pathnameIsLogged(rawUrl) {
-    if (!rawUrl)
-        return true;
-    const pathname = new URL(rawUrl, "http://runtime.local").pathname;
-    return pathname !== "/health" && pathname !== "/ready";
+/**
+ * An answer already written to the Node response. `@hono/node-server` skips writing one that
+ * says so in its headers, unless it is its own `Response` class, which a process that ran its
+ * `serve()` has as the global one: it writes those again. This is never that class.
+ */
+const SENT = {
+    status: 200,
+    headers: new Headers({ "x-hono-already-sent": "true" }),
+    body: null,
+};
+function alreadySent(response) {
+    return response.headers.has("x-hono-already-sent") ? SENT : response;
+}
+/** How long shutdown waits for requests in progress before closing their connections. */
+const SHUTDOWN_GRACE_MS = 10_000;
+/**
+ * A response that has started and not ended is a stream: JSON answers are written and ended
+ * at once. (`getHeader` cannot tell, since streams pass their headers to `writeHead`.)
+ */
+function isStreaming(response) {
+    return response.headersSent && !response.writableEnded;
 }

package/dist/host/http.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, 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";
@@ -13,9 +14,12 @@ export declare class HostListenError extends Error {
     constructor(message: string, exitCode: number, cause?: unknown);
 }
 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 +36,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;