@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/realtime/socket.d.ts

@@ -0,0 +1,25 @@
+import { ChannelResolver } from './declarations';
+import { RealtimeGrants } from './grants';
+import { RealtimeHub } from './hub';
+import { UpgradeRequest } from '../../core/http/socketResponse';
+import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+import { IncomingMessage } from 'node:http';
+export type SocketDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    raw: IncomingMessage;
+    upgrade: UpgradeRequest;
+    hub: RealtimeHub;
+    resolveChannels: ChannelResolver;
+    grants: RealtimeGrants;
+    allowedOrigins: readonly string[];
+};
+/**
+ * A page's realtime connection as a WebSocket: the same topics, rules and messages as the Server-Sent Events one, in
+ * both directions over one socket. A publish is a frame, not a request — no headers, no second connection, no token
+ * to present: the socket is the credential. Its answer arrives as an `ack` carrying the publish's `id`.
+ *
+ * Refused the way the stream is — a `403` or a `422`, in HTTP, before anything switches — so a page falls back or
+ * reports it exactly as it would there.
+ */
+export declare const handleRealtimeSocket: ({ req, res, raw, upgrade, hub, resolveChannels, grants, allowedOrigins }: SocketDeps) => Promise<void>;

package/dist/modules/realtime/socket.js

@@ -0,0 +1,122 @@
+import { admit, answer, connectionFor, publishFrom } from "./handlers.js";
+import { requestOrigin } from "../../core/requestParser.js";
+import { frameText } from "../../helpers/wsFrame.js";
+//#region src/modules/realtime/socket.ts
+/** The largest frame a page may send: well above the largest message a channel may declare, and bounded. */
+var MAX_FRAME_BYTES = 262144;
+/**
+* What may wait in a socket's buffer for a page that stopped reading. Past it the page is gone in all but name, and
+* holding everything it has not read is how one stalled tab grows a process.
+*/
+var MAX_BUFFERED_BYTES = 1048576;
+/** How often the server asks a socket whether the page behind it is still there — and gives up on one that did not answer the last time. */
+var PING_MS = 25e3;
+var server;
+/**
+* Loaded the first time a page asks for a socket: a server whose pages never do — or that runs behind HTTP/2, where
+* none can — never pays for the module.
+*/
+var socketServer = () => server ??= import("ws").then(({ WebSocketServer: Server }) => new Server({
+	noServer: true,
+	maxPayload: MAX_FRAME_BYTES
+}));
+/**
+* A browser opens a WebSocket to any address, carrying that address's cookies, from any page — CORS does not apply to
+* it. So a socket is refused unless the page that opened it is on this origin, or on one the deployment lists: without
+* this, another site could open a channel restricted to signed-in visitors with a visitor's session and read it.
+* A client that is not a browser sends no `Origin`, and has no visitor's cookies to borrow.
+*/
+var originAllowed = (raw, req, allowed) => {
+	const origin = raw.headers.origin;
+	return origin === void 0 || origin === requestOrigin(req) || allowed.includes(origin);
+};
+/** A frame's text, whichever of the shapes `ws` hands a frame over in. */
+var parse = (frame) => {
+	try {
+		const value = JSON.parse(frameText(frame));
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/** A publish's id, echoed on its `ack`: what the page matches the answer to. Short, and never anything else. */
+var ackId = (id) => typeof id === "number" && Number.isInteger(id) || typeof id === "string" && id.length <= 64 ? id : void 0;
+/**
+* A page's realtime connection as a WebSocket: the same topics, rules and messages as the Server-Sent Events one, in
+* both directions over one socket. A publish is a frame, not a request — no headers, no second connection, no token
+* to present: the socket is the credential. Its answer arrives as an `ack` carrying the publish's `id`.
+*
+* Refused the way the stream is — a `403` or a `422`, in HTTP, before anything switches — so a page falls back or
+* reports it exactly as it would there.
+*/
+var handleRealtimeSocket = async ({ req, res, raw, upgrade, hub, resolveChannels, grants, allowedOrigins }) => {
+	if (!originAllowed(raw, req, allowedOrigins)) {
+		answer(res, {
+			status: 403,
+			error: "A page on another site may not open this",
+			reason: "foreign"
+		});
+		return;
+	}
+	const admission = await admit(req, resolveChannels, grants);
+	if (!admission.ok) {
+		answer(res, admission.answer);
+		return;
+	}
+	const sockets = await socketServer();
+	upgrade.taken = true;
+	res.setStatus(101);
+	sockets.handleUpgrade(raw, upgrade.socket, upgrade.head, (socket) => {
+		const send = (event, data) => {
+			if (socket.readyState !== socket.OPEN) return;
+			if (socket.bufferedAmount > MAX_BUFFERED_BYTES) {
+				socket.terminate();
+				return;
+			}
+			socket.send(JSON.stringify({
+				event,
+				data
+			}));
+		};
+		const connection = connectionFor(admission, send, () => socket.close(1001, "The server is going away"));
+		let alive = true;
+		const heartbeat = setInterval(() => {
+			if (!alive) {
+				socket.terminate();
+				return;
+			}
+			alive = false;
+			socket.ping();
+		}, PING_MS);
+		socket.on("pong", () => {
+			alive = true;
+		});
+		socket.on("message", (frame, binary) => {
+			alive = true;
+			const message = binary ? void 0 : parse(frame);
+			if (!message) return;
+			const id = ackId(message.id);
+			publishFrom(hub, connection, message).then((result) => {
+				if (id !== void 0) send("ack", {
+					id,
+					ok: result.status === 204,
+					status: result.status,
+					...result.reason ? { reason: result.reason } : {}
+				});
+			});
+		});
+		socket.on("close", () => {
+			clearInterval(heartbeat);
+			hub.disconnect(connection);
+		});
+		socket.on("error", () => socket.terminate());
+		send("ready", {
+			connection: connection.id,
+			topics: [...admission.accepted.keys()],
+			refused: admission.refused
+		});
+		hub.connect(connection);
+	});
+};
+//#endregion
+export { handleRealtimeSocket };

package/dist/modules/realtime/socket.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/rsc/handler.d.ts

@@ -1,6 +1,22 @@
 import { TtlCache } from '../../helpers/cache';
 import { PluginManager } from '../../plugins/manager';
 import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * Rewrites the request to the page the browser is actually on.
+ *
+ * A refresh is issued against `/_rsc`, not against `/blog/my-post`, so resolving straight from `req.path` matches
+ * nothing in `schema.pages` and every client-side refresh silently returns no data. The SDK sends the visitor's
+ * location as `?location=`, and route params plus the page parameter are read from that instead.
+ *
+ * What a refresh asks for besides — the next page of a "load more", a search a provider was reloaded with — rides on
+ * the query string beside `location`, and is read over the location's own query. It used to be dropped with the rest
+ * of the endpoint's query, so a provider paged in place was answered its first page every time.
+ *
+ * Reflecting both is safe by construction: the location is matched against this space's own page list, and the rest
+ * is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
+ * is served for a query it was not made for.
+ */
+export declare const withPageLocation: (req: SSRRequest) => SSRRequest;
 /**
  * Handles GET /_rsc requests.
  *

package/dist/modules/rsc/handler.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { resolveDebugAuthorization } from "../../helpers/debugAuthorization.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildRscCacheKey } from "../../helpers/cache/keys.js";
@@ -19,6 +20,8 @@ var meterRsc = async (req, config, spaceId, environment, revision, cached) => {
 		});
 	} catch {}
 };
+/** The endpoint's own parameters: what it is asked about, never input to what it resolves. */
+var ENDPOINT_PARAMS = /* @__PURE__ */ new Set(["location", "ids"]);
 /**
 * Rewrites the request to the page the browser is actually on.
 *
@@ -26,22 +29,26 @@ var meterRsc = async (req, config, spaceId, environment, revision, cached) => {
 * nothing in `schema.pages` and every client-side refresh silently returns no data. The SDK sends the visitor's
 * location as `?location=`, and route params plus the page parameter are read from that instead.
 *
-* Reflecting it is safe by construction: it is matched against this space's own page list, so the worst a forged
-* value can do is resolve a page the same visitor could have loaded directly.
+* What a refresh asks for besides — the next page of a "load more", a search a provider was reloaded with — rides on
+* the query string beside `location`, and is read over the location's own query. It used to be dropped with the rest
+* of the endpoint's query, so a provider paged in place was answered its first page every time.
+*
+* Reflecting both is safe by construction: the location is matched against this space's own page list, and the rest
+* is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
+* is served for a query it was not made for.
 */
 var withPageLocation = (req) => {
 	const location = req.query.location;
 	if (!location || !location.startsWith("/") || location.length > MAX_PAGE_LOCATION) return req;
 	const url = new URL(location, `${req.protocol}://${req.hostname}`);
-	const query = [...url.searchParams.entries()].reduce((acum, [key, value]) => {
-		acum[key] = value;
-		return acum;
-	}, {});
+	const asked = Object.entries(req.query).filter(([key]) => !ENDPOINT_PARAMS.has(key));
+	const query = Object.fromEntries([...url.searchParams.entries(), ...asked]);
+	const search = new URLSearchParams(query).toString();
 	return {
 		...req,
 		path: url.pathname,
-		search: url.search,
-		url: `${url.pathname}${url.search}`,
+		search: search ? `?${search}` : "",
+		url: `${url.pathname}${search ? `?${search}` : ""}`,
 		query
 	};
 };
@@ -112,7 +119,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 			loadOfflineData
 		});
 	} catch (err) {
-		console.error("[RSC] getRscData error:", err);
+		serverLog.error("RSC", "getRscData error", err);
 		res.setStatus(500);
 		res.send(JSON.stringify({ error: "RSC data fetch failed" }));
 		return;
@@ -135,4 +142,4 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 	res.send(payloadStr);
 };
 //#endregion
-export { handleRsc };
+export { handleRsc, withPageLocation };

package/dist/modules/rsc/handler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/rsc/resolveRscData.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { matchRscPage } from "./matchRscPage.js";
 import { collectServerElements } from "@plitzi/sdk-shared/schema/serverElements";
 //#region src/modules/rsc/resolveRscData.ts
@@ -52,7 +53,7 @@ var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, reso
 		}), timeoutMs, `element ${element.id}`)
 	})))).reduce((acum, result, index) => {
 		if (result.status === "rejected") {
-			console.error(`[RSC] element ${targets[index].id} failed to resolve:`, result.reason);
+			serverLog.error("RSC", `element ${targets[index].id} failed to resolve`, result.reason);
 			return acum;
 		}
 		if (result.value.data !== void 0) acum[result.value.id] = result.value.data;

package/dist/modules/runtime/bundle.d.ts

@@ -0,0 +1,24 @@
+import { SpaceRuntime } from './contract';
+/** A packed runtime at most this big: its code and every dependency, not its data. */
+export declare const MAX_RUNTIME_BUNDLE_BYTES: number;
+/** A bundle's id: what its bytes are, so the same code packed twice is one bundle. */
+export declare const runtimeBundleId: (bytes: Uint8Array) => string;
+/**
+ * A runtime's module packed to travel: bundled for Node with every dependency it imports — but the platform's packages
+ * and React, which the host provides, so there is one copy of each — and gzipped. `entry` is the module whose default
+ * export is `defineRuntime(…)`.
+ */
+export declare const packRuntime: (entry: string) => Promise<Uint8Array>;
+/**
+ * What a packed runtime holds, read without running any of it — what a platform checks a bundle with before keeping it.
+ * Throws, saying why, for bytes that are not one.
+ */
+export declare const inspectRuntime: (bytes: Uint8Array) => {
+    entry: string;
+    files: string[];
+};
+/**
+ * A packed runtime written into `dir` and imported: its module's default export. `dir` must be inside the host's own
+ * project, so the packages the bundle leaves to the host resolve to the host's — one copy of each.
+ */
+export declare const loadRuntime: (bytes: Uint8Array, dir: string) => Promise<SpaceRuntime>;

package/dist/modules/runtime/bundle.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import esbuild from "esbuild";
+import { pathToFileURL } from "node:url";
+import fs from "node:fs/promises";
+import { gunzipSync, gzipSync } from "node:zlib";
+//#region src/modules/runtime/bundle.ts
+/** What the runtime's host provides, and a bundle must not carry a copy of: the platform's packages and React. */
+var PROVIDED = [
+	"@plitzi/*",
+	"react",
+	"react-dom",
+	"react/*",
+	"react-dom/*"
+];
+/** A packed runtime at most this big: its code and every dependency, not its data. */
+var MAX_RUNTIME_BUNDLE_BYTES = 33554432;
+var FORMAT = 1;
+var ENTRY = "runtime.mjs";
+/** A bundle's id: what its bytes are, so the same code packed twice is one bundle. */
+var runtimeBundleId = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/**
+* A runtime's module packed to travel: bundled for Node with every dependency it imports — but the platform's packages
+* and React, which the host provides, so there is one copy of each — and gzipped. `entry` is the module whose default
+* export is `defineRuntime(…)`.
+*/
+var packRuntime = async (entry) => {
+	const result = await esbuild.build({
+		entryPoints: [entry],
+		bundle: true,
+		platform: "node",
+		format: "esm",
+		target: "node22",
+		external: PROVIDED,
+		outdir: "runtime",
+		entryNames: "runtime",
+		outExtension: { ".js": ".mjs" },
+		banner: { js: "import { createRequire as __plitziRequire } from \"node:module\"; const require = __plitziRequire(import.meta.url);" },
+		splitting: false,
+		logLevel: "warning",
+		write: false
+	});
+	const files = Object.fromEntries(result.outputFiles.map((output) => [path.basename(output.path), Buffer.from(output.contents).toString("base64")]));
+	if (!(ENTRY in files)) throw new Error(`Packing ${entry} produced no ${ENTRY}`);
+	const bytes = gzipSync(JSON.stringify({
+		format: FORMAT,
+		entry: ENTRY,
+		files
+	}));
+	if (bytes.byteLength > 33554432) throw new Error(`A runtime is at most ${String(MAX_RUNTIME_BUNDLE_BYTES / 1024 / 1024)} MB packed; this one is ${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB`);
+	return new Uint8Array(bytes);
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A packed runtime read back — refused whole when it is not one. */
+var unpack = (bytes) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(gunzipSync(bytes).toString("utf8"));
+	} catch {
+		throw new Error("Not a packed runtime: it is not gzipped JSON");
+	}
+	if (!isRecord(parsed) || parsed.format !== FORMAT || typeof parsed.entry !== "string" || !isRecord(parsed.files)) throw new Error(`Not a packed runtime of format ${String(FORMAT)}`);
+	const files = {};
+	Object.entries(parsed.files).forEach(([name, content]) => {
+		if (typeof content !== "string" || name !== path.basename(name) || name.startsWith(".")) throw new Error(`"${name}" is not a file a packed runtime can hold`);
+		files[name] = content;
+	});
+	if (!(parsed.entry in files)) throw new Error(`A packed runtime's entry, ${parsed.entry}, is not among its files`);
+	return {
+		format: FORMAT,
+		entry: parsed.entry,
+		files
+	};
+};
+/**
+* What a packed runtime holds, read without running any of it — what a platform checks a bundle with before keeping it.
+* Throws, saying why, for bytes that are not one.
+*/
+var inspectRuntime = (bytes) => {
+	if (bytes.byteLength > 33554432) throw new Error(`A runtime is at most ${String(MAX_RUNTIME_BUNDLE_BYTES / 1024 / 1024)} MB packed`);
+	const { entry, files } = unpack(bytes);
+	return {
+		entry,
+		files: Object.keys(files)
+	};
+};
+var isRuntime = (value) => isRecord(value) && typeof value.start === "function";
+/**
+* A packed runtime written into `dir` and imported: its module's default export. `dir` must be inside the host's own
+* project, so the packages the bundle leaves to the host resolve to the host's — one copy of each.
+*/
+var loadRuntime = async (bytes, dir) => {
+	const { entry, files } = unpack(bytes);
+	await fs.mkdir(dir, { recursive: true });
+	await Promise.all(Object.entries(files).map(([name, content]) => fs.writeFile(path.join(dir, name), Buffer.from(content, "base64"))));
+	const loaded = await import(pathToFileURL(path.join(dir, entry)).href);
+	const runtime = isRecord(loaded) ? loaded.default : void 0;
+	if (!isRuntime(runtime)) throw new Error("A runtime module exports its runtime by default: export default defineRuntime({ start: … })");
+	return runtime;
+};
+//#endregion
+export { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, packRuntime, runtimeBundleId };

package/dist/modules/runtime/contract.d.ts

@@ -0,0 +1,37 @@
+import { FunctionsDefinition } from '../functions/contract';
+/** What a runtime starts with. */
+export type SpaceRuntimeContext = {
+    /** Its variables: those the platform keeps for it (`REDIS_URL`…), or a self-hosted server's own environment. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** Where people reach the space — what a link written for a person, or an agent, is handed. */
+    publicUrl: string;
+};
+/**
+ * A path of the space's own answered by the runtime: a web handler, streaming if it likes — an agent's endpoint, a
+ * webhook that speaks a protocol of its own. The visitor's cookies and `Authorization` never reach it: the host's are
+ * the platform's.
+ */
+export type SpaceRuntimeEndpoint = (request: Request) => Response | Promise<Response>;
+/** What a started runtime is made of. */
+export type SpaceRuntimeParts = {
+    /** Its tasks and `/api/` routes, run with a `ctx` that is the platform's — the space's `kv`, its channels, its key. */
+    functions?: FunctionsDefinition;
+    /** Paths it answers itself, each with everything beneath it (`/mcp` answers `/mcp/…`) — see {@link endpointProblem}. */
+    endpoints?: Record<string, SpaceRuntimeEndpoint>;
+    /** Called when it is stopped: close what `start` opened. */
+    close?: () => Promise<void>;
+};
+/**
+ * A space's own server code, run as code of its own — Node, its dependencies, its connections — beside the platform
+ * that serves the space: a runtime of the space, where the sandbox's functions are not enough. `start` is handed its
+ * variables and answers what it serves.
+ */
+export type SpaceRuntime = {
+    start: (context: SpaceRuntimeContext) => SpaceRuntimeParts | Promise<SpaceRuntimeParts>;
+};
+/** Declares a space runtime — an identity, for the types: `export default defineRuntime({ start: … })`. */
+export declare const defineRuntime: (runtime: SpaceRuntime) => SpaceRuntime;
+/** Why a path cannot be an endpoint — or nothing, for one that can. */
+export declare const endpointProblem: (path: string) => string | undefined;
+/** The endpoint a request's path belongs to: exactly it, or beneath it — the longest that does. */
+export declare const endpointFor: (paths: readonly string[], path: string) => string | undefined;

package/dist/modules/runtime/contract.js

@@ -0,0 +1,21 @@
+import { FUNCTION_ROUTES_PREFIX } from "@plitzi/sdk-shared/actions";
+//#region src/modules/runtime/contract.ts
+/** Declares a space runtime — an identity, for the types: `export default defineRuntime({ start: … })`. */
+var defineRuntime = (runtime) => runtime;
+/** The paths the server answers itself, which no endpoint may take: its routes, its own endpoints and sign-in. */
+var RESERVED = [
+	FUNCTION_ROUTES_PREFIX,
+	"/_",
+	"/auth",
+	"/.well-known"
+];
+/** Why a path cannot be an endpoint — or nothing, for one that can. */
+var endpointProblem = (path) => {
+	if (!/^\/[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*$/.test(path)) return `"${path}" is not an endpoint path: it starts with "/" and is made of plain segments`;
+	const taken = RESERVED.find((prefix) => path === prefix || path.startsWith(prefix.endsWith("_") ? prefix : `${prefix}/`));
+	if (taken) return `"${path}" is the server's own (${taken}): an endpoint takes a path of the space's`;
+};
+/** The endpoint a request's path belongs to: exactly it, or beneath it — the longest that does. */
+var endpointFor = (paths, path) => paths.filter((candidate) => path === candidate || path.startsWith(`${candidate}/`)).sort((a, b) => b.length - a.length)[0];
+//#endregion
+export { defineRuntime, endpointFor, endpointProblem };

package/dist/modules/runtime/entry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/runtime/host.d.ts

@@ -0,0 +1,38 @@
+import { SpaceRuntime } from './contract';
+import { AddressInfo } from 'node:net';
+/** What the platform reads of a started runtime: its functions' manifest, and the paths it answers itself. */
+export type SpaceRuntimeDescription = {
+    functions: Record<string, unknown>;
+    endpoints: string[];
+};
+/** Where a started runtime says what it serves — under `/_`, which no endpoint may take. */
+export declare const RUNTIME_DESCRIBE_PATH = "/_describe";
+/** The headers of the platform's, which a runtime's endpoint never sees. */
+export declare const PLATFORM_HEADERS: string[];
+export type SpaceRuntimeHostOptions = {
+    runtime: SpaceRuntime;
+    /** What the platform presents — `Authorization: Bearer <secret>` — on its calls and on the requests it forwards. */
+    secret: string;
+    port?: number;
+    host?: string;
+    /** The runtime's variables. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** Where people reach the space. */
+    publicUrl: string;
+    /**
+     * Where the space is reached from inside the network this runtime runs in — the platform's ingress, over plain HTTP.
+     * Given, the runtime's requests to its own space go there rather than out to the edge and back (`reachSpaceInside`).
+     */
+    insideUrl?: string | undefined;
+};
+export type SpaceRuntimeHost = {
+    address: () => AddressInfo;
+    close: () => Promise<void>;
+};
+/**
+ * A space runtime, started and served: its tasks and routes over the functions runners' protocol (the platform invokes
+ * them and answers every `ctx` call), and its endpoints as plain HTTP the platform forwards — both behind one secret,
+ * since the only caller is the platform. The process is the space's alone: what its code can reach is this process
+ * and the network it is given, never the platform's database or keys.
+ */
+export declare const startSpaceRuntime: ({ runtime, secret, port, host, env, publicUrl, insideUrl }: SpaceRuntimeHostOptions) => Promise<SpaceRuntimeHost>;

package/dist/modules/runtime/host.js

@@ -0,0 +1,68 @@
+import { describeFunctions } from "../functions/driver.js";
+import { startFunctionsRunnerService } from "../functions/runner/service.js";
+import { endpointFor, endpointProblem } from "./contract.js";
+import { reachSpaceInside } from "./inside.js";
+import { createRuntimeRunner } from "./runner.js";
+import { webRequestOf, writeWebResponse } from "../../core/http/webExchange.js";
+//#region src/modules/runtime/host.ts
+/** Where a started runtime says what it serves — under `/_`, which no endpoint may take. */
+var RUNTIME_DESCRIBE_PATH = "/_describe";
+/** The headers of the platform's, which a runtime's endpoint never sees. */
+var PLATFORM_HEADERS = ["authorization", "cookie"];
+/**
+* A space runtime, started and served: its tasks and routes over the functions runners' protocol (the platform invokes
+* them and answers every `ctx` call), and its endpoints as plain HTTP the platform forwards — both behind one secret,
+* since the only caller is the platform. The process is the space's alone: what its code can reach is this process
+* and the network it is given, never the platform's database or keys.
+*/
+var startSpaceRuntime = async ({ runtime, secret, port = 8791, host = "0.0.0.0", env, publicUrl, insideUrl }) => {
+	if (insideUrl) await reachSpaceInside({
+		publicUrl,
+		insideUrl
+	});
+	const parts = await runtime.start({
+		env,
+		publicUrl
+	});
+	const endpoints = parts.endpoints ?? {};
+	const paths = Object.keys(endpoints);
+	const problems = paths.flatMap((path) => endpointProblem(path) ?? []);
+	if (problems.length > 0) {
+		await parts.close?.();
+		throw new Error(problems.join("; "));
+	}
+	const description = {
+		functions: describeFunctions(parts.functions ?? {}),
+		endpoints: paths
+	};
+	const service = await startFunctionsRunnerService({
+		secret,
+		port,
+		host,
+		runner: createRuntimeRunner(parts.functions),
+		http: async (req, res) => {
+			const url = new URL(req.url ?? "/", publicUrl);
+			if (req.method === "GET" && url.pathname === "/_describe") {
+				res.writeHead(200, { "content-type": "application/json" });
+				res.end(JSON.stringify(description));
+				return true;
+			}
+			const endpoint = endpointFor(paths, url.pathname);
+			const answer = endpoint ? endpoints[endpoint] : void 0;
+			if (!answer) return false;
+			const left = new AbortController();
+			res.once("close", () => left.abort());
+			await writeWebResponse(res, await answer(await webRequestOf(req, url.href, PLATFORM_HEADERS)), left.signal);
+			return true;
+		}
+	});
+	return {
+		address: service.address,
+		close: async () => {
+			await service.close();
+			await parts.close?.();
+		}
+	};
+};
+//#endregion
+export { PLATFORM_HEADERS, RUNTIME_DESCRIBE_PATH, startSpaceRuntime };

package/dist/modules/runtime/inside.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The space's own public address, reached from inside the network this runtime runs in: every request this process
+ * makes to the space's host — `fetch` and `WebSocket` alike, which share Node's dispatcher — connects to `insideUrl`
+ * instead, over plain HTTP, the space's host and the public protocol kept (`X-Forwarded-Proto`). It is the path a
+ * request takes once past the edge, without leaving to come back through it; the space's code keeps writing its public
+ * address, and nothing else it reaches changes.
+ *
+ * `undici` is imported here, when a runtime asks, and never with the module: loading the package installs a global
+ * dispatcher of its own, and this entry is loaded by the platform's page server too (`createRuntimeProxyStage`), whose
+ * every `fetch` must stay Node's.
+ */
+export declare const reachSpaceInside: ({ publicUrl, insideUrl }: {
+    publicUrl: string;
+    insideUrl: string;
+}) => Promise<void>;

package/dist/modules/runtime/inside.js

@@ -0,0 +1,47 @@
+import net from "node:net";
+//#region src/modules/runtime/inside.ts
+/** Headers as a dispatch carries them — a record, name/value pairs flattened into one list, or pairs — plus one more. */
+var withHeader = (headers, name, value) => {
+	const entries = [];
+	if (Array.isArray(headers)) for (let index = 0; index < headers.length; index += 2) entries.push([headers[index], headers[index + 1]]);
+	else if (headers && Symbol.iterator in headers) entries.push(...headers);
+	else if (headers) entries.push(...Object.entries(headers));
+	return {
+		...Object.fromEntries(entries),
+		[name]: value
+	};
+};
+/**
+* The space's own public address, reached from inside the network this runtime runs in: every request this process
+* makes to the space's host — `fetch` and `WebSocket` alike, which share Node's dispatcher — connects to `insideUrl`
+* instead, over plain HTTP, the space's host and the public protocol kept (`X-Forwarded-Proto`). It is the path a
+* request takes once past the edge, without leaving to come back through it; the space's code keeps writing its public
+* address, and nothing else it reaches changes.
+*
+* `undici` is imported here, when a runtime asks, and never with the module: loading the package installs a global
+* dispatcher of its own, and this entry is loaded by the platform's page server too (`createRuntimeProxyStage`), whose
+* every `fetch` must stay Node's.
+*/
+var reachSpaceInside = async ({ publicUrl, insideUrl }) => {
+	const outside = new URL(publicUrl);
+	const inside = new URL(insideUrl);
+	if (inside.protocol !== "http:") throw new Error(`A space is reached from inside over plain HTTP, not ${inside.protocol} (${insideUrl})`);
+	const { Agent, buildConnector, setGlobalDispatcher } = await import("undici");
+	const port = Number(inside.port || 80);
+	const protocol = outside.protocol.replace(":", "");
+	const connect = buildConnector({});
+	setGlobalDispatcher(new Agent({ connect: (options, callback) => {
+		if (options.hostname !== outside.hostname) {
+			connect(options, callback);
+			return;
+		}
+		const socket = net.connect(port, inside.hostname);
+		socket.once("connect", () => callback(null, socket));
+		socket.once("error", (error) => callback(error, null));
+	} }).compose((dispatch) => (options, handler) => dispatch(new URL(String(options.origin)).hostname === outside.hostname ? {
+		...options,
+		headers: withHeader(options.headers, "x-forwarded-proto", protocol)
+	} : options, handler)));
+};
+//#endregion
+export { reachSpaceInside };

package/dist/modules/runtime/inside.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/runtime/runner.d.ts

@@ -0,0 +1,11 @@
+import { FunctionsDefinition } from '../functions/contract';
+import { FunctionRunner } from '../functions/protocol';
+/**
+ * A runtime's functions as a runner: the same protocol as the sandbox's, answered by code loaded in this process. The
+ * driver is the sandbox's own (`createFunctionsDriver`), so a task behaves the same in both — its `ctx` is calls to the
+ * platform, `ctx.kv.change` the same loop, a refusal the same answer. What it does not share is the isolate: there are
+ * no limits here but the platform's clock, since this process is the space's alone.
+ *
+ * The bundle a request names is not asked for: the code is the one this runtime was started with.
+ */
+export declare const createRuntimeRunner: (definition?: FunctionsDefinition) => FunctionRunner;