@nylorun/runtime 0.9.0-beta → 0.11.0-beta

package/dist/host/execution.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The Host's Durable Session Execution (architecture §6, §12.3, §14.8): one per process,
+ * shared by every Tenant the Host opens.
+ *
+ * - `tenantExecution` is what the Host passes to each Tenant it opens
+ *   (`TenantOpenHooks.execution`): the execution, the `TenantWorkers` registry its handlers
+ *   dispatch through (with `resolve` opening a Tenant on demand when an invocation arrives for
+ *   one that is not open), and the Tenant status hook for stuck invocations.
+ * - `start` serves the Worker endpoint for `--role worker|all` (`infra/workers.ts`) and does
+ *   nothing for `api`, whose wakes, timers and sweep arming go through Restate's ingress.
+ * - `armAll` re-arms every Tenant's sweep at startup. Arming is idempotent, so it is safe on
+ *   every start, and it is what recovers from lost Restate state: the sweep re-wakes `runnable`
+ *   sessions without a live owner (§14.8).
+ * - `disarm` stops a deleted Tenant's sweep.
+ *
+ * **Order at startup.** Call `start` before opening any Tenant. Opening a Tenant arms its
+ * sweep through Restate's ingress, which answers 404 until a Worker has registered the
+ * services, so the open would fail. An api-role process relies on a Worker having registered
+ * them first.
+ *
+ * **One Worker URL.** `start` registers the Worker endpoint (`NYLORUN_WORKER_URL`) with
+ * Restate once. Restate sends new invocations to the latest registered deployment, so
+ * several Workers that each register their own URL do not share load: the last one to start
+ * takes every new invocation. The V1 stack runs a single `runtime` container with
+ * `--role all`. A deployment with several Worker processes (Helm, Cloud) must advertise one
+ * load-balanced `NYLORUN_WORKER_URL` shared by all of them.
+ */
+import type { DurableExecution } from "../execution/types.js";
+import type { Logger } from "../tenant/types.js";
+import { type TenantExecution, type TenantWorker } from "../tenant/worker.js";
+import type { RuntimeRole } from "./stack-config.js";
+export interface CreateHostExecutionOptions {
+    execution: DurableExecution;
+    role: RuntimeRole;
+    /** Finds or opens a Tenant an invocation arrived for that is not open on this process. */
+    resolve: (tenantId: string) => Promise<TenantWorker | undefined>;
+    logger?: Logger;
+    /**
+     * How long one advance may run before its signal aborts and it settles
+     * (`tenant/worker.ts`). Default 50 minutes, below Restate's timeouts.
+     */
+    advanceDeadlineMs?: number;
+    /** How long an aborted advance has to return before it is abandoned. Default 30 s. */
+    advanceGraceMs?: number;
+}
+export interface HostExecution {
+    /** Pass to every Tenant the Host opens (`TenantOpenHooks.execution`). */
+    readonly tenantExecution: TenantExecution;
+    /** Serves the Worker endpoint for the worker and all roles. Idempotent. */
+    start(): Promise<void>;
+    /** Stops serving: aborts running advances and waits for them. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Arms every listed Tenant's sweep (idempotent). Tries them all; rejects with an
+     * `AggregateError` of the failures after logging each.
+     */
+    armAll(tenantIds: readonly string[]): Promise<void>;
+    /** Stops re-arming a deleted Tenant's sweep. */
+    disarm(tenantId: string): Promise<void>;
+}
+export declare function createHostExecution(options: CreateHostExecutionOptions): HostExecution;

package/dist/host/execution.js

@@ -0,0 +1,69 @@
+import { startWorker, stopWorker } from "../infra/workers.js";
+import { TenantWorkers, } from "../tenant/worker.js";
+/** How many sweep arms `armAll` sends at once. */
+const ARM_CONCURRENCY = 16;
+export function createHostExecution(options) {
+    const { execution, role, logger } = options;
+    const workers = new TenantWorkers({
+        resolve: options.resolve,
+        ...(options.advanceDeadlineMs !== undefined
+            ? { advanceDeadlineMs: options.advanceDeadlineMs }
+            : {}),
+        ...(options.advanceGraceMs !== undefined
+            ? { advanceGraceMs: options.advanceGraceMs }
+            : {}),
+        ...(logger ? { logger } : {}),
+    });
+    const tenantExecution = {
+        execution,
+        workers,
+        ...(execution.stuckInvocations
+            ? {
+                stuckInvocations: (tenantId) => execution.stuckInvocations(tenantId),
+            }
+            : {}),
+    };
+    let started;
+    return {
+        tenantExecution,
+        async start() {
+            started ??= startWorker({ role, execution, handlers: workers.handlers });
+            try {
+                await started;
+            }
+            catch (error) {
+                started = undefined;
+                throw error;
+            }
+        },
+        async stop() {
+            const handle = await started?.catch(() => undefined);
+            if (handle)
+                await stopWorker(handle);
+        },
+        async armAll(tenantIds) {
+            const queue = [...new Set(tenantIds)];
+            const failures = [];
+            const next = async () => {
+                for (let id = queue.shift(); id !== undefined; id = queue.shift()) {
+                    try {
+                        await execution.armSweep(id);
+                    }
+                    catch (error) {
+                        failures.push(error);
+                        logger?.warn("tenant sweep arm failed", {
+                            tenantId: id,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(ARM_CONCURRENCY, queue.length) }, next));
+            if (failures.length > 0)
+                throw new AggregateError(failures, `Arming ${failures.length} Tenant sweep(s) failed`);
+        },
+        async disarm(tenantId) {
+            await execution.disarmSweep(tenantId);
+        },
+    };
+}

package/dist/host/http.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type ErrorCode, type ProtocolRange } from "@nylorun/core/compatibility";
+export declare const OPAQUE_NOT_FOUND: {
+    status: "rejected";
+    code: "not_found";
+    message: string;
+};
+export declare const EXIT_PORT_IN_USE = 98;
+export declare const EXIT_NON_LOOPBACK = 99;
+export declare class HostListenError extends Error {
+    readonly exitCode: number;
+    readonly cause?: unknown;
+    constructor(message: string, exitCode: number, cause?: unknown);
+}
+export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
+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;
+/**
+ * D§11 Host allowlist: loopback forms with the listening port, plus the
+ * configured host when `allowNonLoopback` is set.
+ *
+ * An explicit `allowedHosts` list (container mode) replaces that rule: only
+ * those exact `name:port` values are accepted.
+ */
+export declare function isAllowedRequestHost(hostHeader: string | undefined, options: {
+    port: number;
+    host: string;
+    allowNonLoopback?: boolean;
+    allowedHosts?: readonly string[];
+}): boolean;
+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;
+/** Redact path parameters after `/v1/sessions/` for Host logs. */
+export declare function redactRoutePath(pathname: string): string;
+export declare function readBearer(authorization: string | undefined): string | undefined;
+export declare function readJsonBody(request: import("node:http").IncomingMessage, limit?: number): Promise<unknown>;
+export declare function isLoopbackHost(host: string): boolean;

package/dist/host/http.js

@@ -0,0 +1,142 @@
+import { HOST_PROTOCOL, } from "@nylorun/core/compatibility";
+export const OPAQUE_NOT_FOUND = {
+    status: "rejected",
+    code: "not_found",
+    message: "Not found",
+};
+export const EXIT_PORT_IN_USE = 98;
+export const EXIT_NON_LOOPBACK = 99;
+export class HostListenError extends Error {
+    exitCode;
+    cause;
+    constructor(message, exitCode, cause) {
+        super(message);
+        this.exitCode = exitCode;
+        this.cause = cause;
+        this.name = "HostListenError";
+    }
+}
+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.end(payload);
+}
+export function sendRejected(response, status, code, message, details) {
+    const body = { status: "rejected", code, message };
+    if (details !== undefined)
+        body.details = details;
+    sendJson(response, status, body);
+}
+export function sendOpaqueNotFound(response) {
+    sendJson(response, 404, OPAQUE_NOT_FOUND);
+}
+export function sendProtocolRejected(response, protocol = HOST_PROTOCOL) {
+    sendJson(response, 426, {
+        status: "rejected",
+        code: "protocol_unsupported",
+        protocol: {
+            min: protocol.min,
+            max: protocol.max,
+            features: [...protocol.features],
+        },
+    });
+}
+/**
+ * D§11 Host allowlist: loopback forms with the listening port, plus the
+ * configured host when `allowNonLoopback` is set.
+ *
+ * An explicit `allowedHosts` list (container mode) replaces that rule: only
+ * those exact `name:port` values are accepted.
+ */
+export function isAllowedRequestHost(hostHeader, options) {
+    if (hostHeader === undefined)
+        return false;
+    const normalized = hostHeader.trim().toLowerCase();
+    if (options.allowedHosts !== undefined) {
+        return options.allowedHosts.some((entry) => entry.trim().toLowerCase() === normalized);
+    }
+    const port = String(options.port);
+    const allowed = new Set([
+        `127.0.0.1:${port}`,
+        `localhost:${port}`,
+        `[::1]:${port}`,
+    ]);
+    if (options.allowNonLoopback) {
+        const configured = options.host.trim().toLowerCase();
+        if (configured.includes(":") && !configured.startsWith("[")) {
+            allowed.add(`[${configured}]:${port}`);
+        }
+        else {
+            allowed.add(`${configured}:${port}`);
+        }
+    }
+    return allowed.has(normalized);
+}
+export function isJsonContentType(value) {
+    if (value === undefined)
+        return false;
+    const media = value.split(";")[0].trim().toLowerCase();
+    return media === "application/json";
+}
+/** True when the request carries a body (Content-Length > 0 or chunked). */
+export function requestHasBody(request) {
+    const te = request.headers["transfer-encoding"];
+    const transfer = Array.isArray(te) ? te.join(",") : te;
+    if (transfer && transfer.toLowerCase() !== "identity")
+        return true;
+    const cl = request.headers["content-length"];
+    const raw = Array.isArray(cl) ? cl[0] : cl;
+    if (raw === undefined)
+        return false;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0;
+}
+/** Redact path parameters after `/v1/sessions/` for Host logs. */
+export function redactRoutePath(pathname) {
+    const parts = pathname.split("/");
+    // ["", "v1", "sessions", "<id>", ...]
+    if (parts[1] === "v1" && parts[2] === "sessions" && parts.length > 3) {
+        return `/v1/sessions/:id${parts.length > 4 ? "/…" : ""}`;
+    }
+    return pathname;
+}
+export function readBearer(authorization) {
+    if (!authorization)
+        return undefined;
+    const match = /^Bearer\s+(\S+)/i.exec(authorization.trim());
+    return match?.[1];
+}
+export async function readJsonBody(request, limit = 1024 * 1024) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.length;
+        if (size > limit) {
+            const error = new Error("Request too large");
+            error.status = 413;
+            throw error;
+        }
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        const error = new Error("Invalid JSON");
+        error.status = 400;
+        throw error;
+    }
+}
+export function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return (normalized === "127.0.0.1" ||
+        normalized === "::1" ||
+        normalized === "localhost");
+}

package/dist/host/index.d.ts

@@ -0,0 +1,8 @@
+export type { HostConfigFile, HostCredentialsFile, } from "./config.js";
+export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./environment.js";
+export { createHost, adminKeyMatches, type CreateHostOptions, type HostServer } from "./create-host.js";
+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 { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, HostListenError, OPAQUE_NOT_FOUND, } from "./http.js";

package/dist/host/index.js

@@ -0,0 +1,7 @@
+export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./environment.js";
+export { createHost, adminKeyMatches } from "./create-host.js";
+export { createHostLogger } from "./logger.js";
+export { configForFactory } from "./config-for.js";
+export { createHostExecution, } from "./execution.js";
+export { parseStackConfig, StackConfigError, } from "./stack-config.js";
+export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, HostListenError, OPAQUE_NOT_FOUND, } from "./http.js";

package/dist/host/logger.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from "../tenant/types.js";
+/** Host logger: JSON lines to stdout (CLI redirects to `runtime.log`). */
+export declare function createHostLogger(write?: (line: string) => void): Logger;

package/dist/host/logger.js

@@ -0,0 +1,18 @@
+/** Host logger: JSON lines to stdout (CLI redirects to `runtime.log`). */
+export function createHostLogger(write = (line) => {
+    process.stdout.write(`${line}\n`);
+}) {
+    const emit = (level, message, fields) => {
+        write(JSON.stringify({
+            level,
+            message,
+            time: new Date().toISOString(),
+            ...fields,
+        }));
+    };
+    return {
+        info: (message, fields) => emit("info", message, fields),
+        warn: (message, fields) => emit("warn", message, fields),
+        error: (message, fields) => emit("error", message, fields),
+    };
+}

package/dist/host/main.d.ts

@@ -0,0 +1,3 @@
+import { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK } from "./http.js";
+export declare function main(): Promise<void>;
+export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK };

package/dist/host/main.js

@@ -0,0 +1,201 @@
+/**
+ * Runtime Host process entry (`@nylorun/runtime/server`).
+ *
+ * Reads `NYLORUN_HOME` (falls back to `~/.nylorun`), and hands an environment
+ * snapshot and argv to `parseStackConfig` (container listen mode, `--role`,
+ * stack endpoints). Absolute Host root is resolved once and passed down.
+ *
+ * Composition: `createInfra` builds the Postgres pool, Durable Session
+ * Execution and Durable Streams from the endpoints; `createHostExecution`
+ * shares one execution across the Tenants; the Tenant store is Postgres
+ * (`NYLORUN_DATABASE_URL`, required); `/ready` reports the infrastructure
+ * checks. See the startup order in `main()`. Tests compose a Host without this
+ * entry, with `createHost` and an injected Tenant module.
+ */
+import { readFileSync, mkdirSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { hostPaths, trashSqliteTenants } from "../tenant/paths.js";
+import { createTenantModule } from "../tenant/module.js";
+import { createPostgresTenantStore } from "../tenant/store-pg.js";
+import { openTenantRuntime } from "../tenant/runtime.js";
+import { createTenantStreams, deleteTenantStreams } from "../tenant/streams.js";
+import { configForFactory } from "./config-for.js";
+import { createHost } from "./create-host.js";
+import { createHostExecution } from "./execution.js";
+import { baselineEnvironment } from "./environment.js";
+import { HostListenError, EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, } from "./http.js";
+import { createHostLogger } from "./logger.js";
+import { describeEndpoints, parseStackConfig } from "./stack-config.js";
+import { createExecution, createInfra } from "../infra/index.js";
+const nodeRequire = createRequire(import.meta.url);
+function coreVersion() {
+    try {
+        return nodeRequire("@nylorun/core/package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function loadJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function resolveHostRoot() {
+    const fromEnv = process.env.NYLORUN_HOME;
+    const root = fromEnv && fromEnv.length > 0 ? fromEnv : resolve(homedir(), ".nylorun");
+    return resolve(root);
+}
+export async function main() {
+    const stack = parseStackConfig(process.env, process.argv.slice(2));
+    const hostRoot = resolveHostRoot();
+    const paths = hostPaths(hostRoot);
+    mkdirSync(paths.home, { recursive: true });
+    mkdirSync(paths.tmp, { recursive: true });
+    mkdirSync(paths.tenants, { recursive: true });
+    if (!existsSync(paths.config)) {
+        throw new Error(`Missing host.json at ${paths.config}; run \`nylorun start\` first`);
+    }
+    if (!existsSync(paths.credentials)) {
+        throw new Error(`Missing host-credentials.json at ${paths.credentials}; run \`nylorun start\` first`);
+    }
+    // Tenants are Postgres schemas. Only a Host outside a container (a local
+    // development Host) may run without S2, on in-process streams.
+    if (!stack.endpoints.databaseUrl) {
+        throw new Error("NYLORUN_DATABASE_URL is required: the Postgres URL of the Session Store (`nylorun start` sets it)");
+    }
+    if (stack.listen && !stack.endpoints.s2Endpoint) {
+        throw new Error("NYLORUN_S2_ENDPOINT is required in container mode: the S2 endpoint of Durable Streams (`nylorun start` sets it)");
+    }
+    const config = loadJson(paths.config);
+    const credentials = loadJson(paths.credentials);
+    const logger = createHostLogger();
+    logger.info("host_stack_config", {
+        role: stack.role,
+        mode: stack.listen ? "container" : "local",
+        endpoints: describeEndpoints(stack.endpoints),
+    });
+    // Tenants from the SQLite Runtime are not migrated: move them out of the way.
+    trashSqliteTenants(hostRoot, logger);
+    const infra = createInfra(stack, { logger });
+    const database = infra.database;
+    if (!database)
+        throw new Error("NYLORUN_DATABASE_URL did not yield a Postgres pool");
+    const baseline = baselineEnvironment(process.env);
+    // A Tenant that should answer with the fixture model carries the Tenant
+    // setting (`tenant/model-setting.ts`); the Host has no fixture mode.
+    const configFor = configForFactory({
+        hostRoot,
+        hostConfig: config,
+        logger,
+        baseline,
+    });
+    // One Durable Session Execution for every Tenant this process opens: Restate
+    // when its endpoints are set, else the in-process memory execution. An
+    // invocation for a Tenant that is not open here opens it on demand.
+    const hostExecution = createHostExecution({
+        execution: infra.execution ?? createExecution(stack),
+        role: stack.role,
+        resolve: (tenantId) => module.worker(tenantId),
+        logger,
+    });
+    // Durable Streams: S2 when configured (always in container mode). Without
+    // them (a local Host only) each Tenant keeps in-process streams, whose history
+    // does not survive a restart.
+    const streams = infra.streams;
+    const store = createPostgresTenantStore({
+        hostRoot,
+        sql: database,
+        configFor,
+        logger,
+        openRuntime: (tenantConfig, opened) => openTenantRuntime(tenantConfig, {
+            execution: hostExecution.tenantExecution,
+            ...(streams ? { streams } : {}),
+            ...opened,
+        }),
+    });
+    const module = createTenantModule({
+        store,
+        logger,
+        // A new Tenant's basin is created with it (opening it repairs a failure);
+        // a deleted Tenant's sweep stops re-arming and its basin goes.
+        ...(streams
+            ? { onCreated: (tenantId) => createTenantStreams(streams, tenantId) }
+            : {}),
+        onDeleted: async (tenantId) => {
+            const failed = (await Promise.allSettled([
+                hostExecution.disarm(tenantId),
+                ...(streams ? [deleteTenantStreams(streams, tenantId)] : []),
+            ])).flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+            if (failed.length > 0)
+                throw new AggregateError(failed, "Deleted Tenant cleanup failed");
+        },
+    });
+    const options = {
+        hostRoot,
+        module,
+        config,
+        credentials,
+        logger,
+        coreVersion: coreVersion(),
+        ...(stack.listen ? { listen: stack.listen } : {}),
+        ...(stack.publicUrl ? { publicUrl: stack.publicUrl } : {}),
+        ...(infra.readiness ? { readiness: infra.readiness } : {}),
+        // SIGTERM and POST /v1/admin/host/shutdown both close the Host this way:
+        // stop the Worker, close the Tenants, then end the infrastructure clients.
+        shutdown: {
+            beforeTenants: () => hostExecution.stop(),
+            afterTenants: () => infra.close(),
+        },
+    };
+    const host = createHost(options);
+    // Startup order. The Worker starts first: opening a Tenant arms its sweep
+    // through Restate's ingress, which answers 404 until a Worker has registered
+    // the services, so no Tenant may open before `start` (the listener opens
+    // Tenants on demand). An api-role process serves no Worker endpoint, so it
+    // can open Tenants only once some Worker process has registered. Container
+    // mode runs one `--role all` process, which registers here. Then the
+    // listener starts (and marks discovery done), and every listed Tenant's
+    // sweep is re-armed, which recovers wakes lost with Restate's state (§14.8).
+    try {
+        await hostExecution.start();
+        await host.listen();
+    }
+    catch (error) {
+        await hostExecution.stop().catch(() => undefined);
+        await infra.close();
+        if (error instanceof HostListenError) {
+            logger.error("listen_failed", {
+                message: error.message,
+                exitCode: error.exitCode,
+            });
+            process.exitCode = error.exitCode;
+            return;
+        }
+        throw error;
+    }
+    const tenants = await module.list();
+    await hostExecution
+        .armAll(tenants.filter((t) => t.state === "open").map((t) => t.id))
+        .catch((error) => logger.warn("tenant_sweeps_not_armed", {
+        message: error instanceof Error ? error.message : String(error),
+    }));
+    logger.info("host_ready", {
+        url: host.url,
+        hostId: config.hostId,
+        tenants: tenants.length,
+    });
+    void host.closed.then(() => process.exit(0));
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => void host.close());
+    }
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    if (error instanceof HostListenError) {
+        process.exit(error.exitCode);
+    }
+    process.exit(1);
+});
+export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK };

package/dist/host/stack-config.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Stack configuration for the Runtime process, parsed from an environment
+ * snapshot and argv. Pure: `host/main.ts` passes the process environment and
+ * arguments; nothing here reads ambient state.
+ *
+ * Two listen modes:
+ * - **local** (no `NYLORUN_LISTEN_*` / `NYLORUN_ALLOWED_HOSTS`): the Host binds
+ *   what `host.json` names, loopback only unless `allowNonLoopback`.
+ * - **container**: the Host binds `NYLORUN_LISTEN_HOST:NYLORUN_LISTEN_PORT`
+ *   (default `0.0.0.0:4000`) and accepts only the `Host` headers in
+ *   `NYLORUN_ALLOWED_HOSTS`, plus the loopback forms of the listen port for
+ *   probes from inside the container.
+ *
+ * The Postgres, Restate and S2 endpoints are parsed and validated here;
+ * `infra/*` builds the clients from them.
+ */
+export type RuntimeRole = "api" | "worker" | "all";
+export declare const RUNTIME_ROLES: readonly RuntimeRole[];
+export declare const DEFAULT_CONTAINER_LISTEN_HOST = "0.0.0.0";
+export declare const DEFAULT_CONTAINER_LISTEN_PORT = 4000;
+export interface ContainerListen {
+    /** Bind address, e.g. `0.0.0.0`. */
+    host: string;
+    port: number;
+    /**
+     * Exact `Host` header values accepted (lowercase `name:port`). Replaces the
+     * loopback-only rule.
+     */
+    allowedHosts: readonly string[];
+}
+export interface StackEndpoints {
+    databaseUrl?: string;
+    restateIngressUrl?: string;
+    restateAdminUrl?: string;
+    workerUrl?: string;
+    s2Endpoint?: string;
+    s2Token?: string;
+    workspaceStoreUrl?: string;
+    /**
+     * Restate request-identity public keys (`publickeyv1_...`) the Worker
+     * endpoint accepts, from `NYLORUN_RESTATE_IDENTITY_KEY` (comma-separated
+     * during a rotation). Unset means the endpoint accepts unsigned requests.
+     */
+    restateIdentityKeys?: string[];
+}
+export interface StackConfig {
+    role: RuntimeRole;
+    /** Present in container mode; absent means bind what host.json names. */
+    listen?: ContainerListen;
+    endpoints: StackEndpoints;
+    /**
+     * The URL clients use to reach this Host (`NYLORUN_PUBLIC_URL`), reported by
+     * `/v1/admin/status`. In container mode the bind address (`0.0.0.0:4000`)
+     * means nothing outside the container.
+     */
+    publicUrl?: string;
+}
+export declare class StackConfigError extends Error {
+    constructor(message: string);
+}
+type EnvSnapshot = Readonly<Record<string, string | undefined>>;
+export declare function parseRole(argv: readonly string[]): RuntimeRole;
+/**
+ * Normalize one `Host` header allowlist entry to lowercase `name:port`.
+ * IPv6 literals must be bracketed (`[::1]:4000`).
+ */
+export declare function normalizeAllowedHost(name: string, entry: string): string;
+/** Parse the stack configuration; throws `StackConfigError` naming the variable. */
+export declare function parseStackConfig(env: EnvSnapshot, argv: readonly string[]): StackConfig;
+/** Endpoint summary for logs: which endpoints are set, never their values. */
+export declare function describeEndpoints(endpoints: StackEndpoints): string[];
+export {};