@plitzi/sdk-server 0.37.1 → 0.37.3

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;

package/dist/modules/runtime/runner.js

@@ -0,0 +1,38 @@
+import { ActionRefusal } from "../actions/runtime/errors.js";
+import { changeKv } from "../actions/runtime/kvChange.js";
+import { requestFromWire, responseOf, wireResponseFrom, wireResponseOf } from "../functions/capabilities.js";
+import { FunctionFailure } from "../functions/protocol.js";
+import { createFunctionsDriver, describeFunctions } from "../functions/driver.js";
+//#region src/modules/runtime/runner.ts
+/** A refusal, however it was made: the platform's class, or a bundle's own copy of it — known by its name. */
+var isRefusal = (error) => error instanceof Error && error.name === "ActionRefusal";
+/**
+* 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.
+*/
+var createRuntimeRunner = (definition = {}) => ({
+	describe: () => Promise.resolve(describeFunctions(definition)),
+	invoke: async ({ invocation, answer, signal }) => {
+		const driver = createFunctionsDriver({
+			call: answer,
+			signal,
+			responseOf: (wire) => responseOf(wireResponseFrom(wire)),
+			requestOf: requestFromWire,
+			wireOfResponse: async (response) => response instanceof Response ? wireResponseOf(response) : void 0,
+			changeKv,
+			refusal: (message) => new ActionRefusal(message)
+		});
+		try {
+			return await driver.invoke(definition, invocation);
+		} catch (error) {
+			if (isRefusal(error)) throw new FunctionFailure("refused", error.message);
+			throw error;
+		}
+	}
+});
+//#endregion
+export { createRuntimeRunner };

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

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

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

@@ -0,0 +1,50 @@
+import { SpaceRuntime, SpaceRuntimeContext, SpaceRuntimeEndpoint } from './contract';
+import { SSRContext, Stage } from '../../core/http/types';
+import { FunctionsDefinition } from '../functions/contract';
+/** A runtime's endpoints answered in this process — self-hosting — exactly as the platform forwards them to its own. */
+export declare const runtimeEndpointsStage: (endpoints: Record<string, SpaceRuntimeEndpoint>) => Stage<SSRContext>;
+/** A runtime on a server of its own: what `createServer` is handed of it, and how to stop it. */
+export type ServedRuntime = {
+    /** Its tasks and routes, for `functions.native`. */
+    native: FunctionsDefinition[];
+    /** Its endpoints, for `preAuth` — they gate themselves, as the platform's forwarding does. */
+    stage: Stage<SSRContext>;
+    close: () => Promise<void>;
+};
+/**
+ * A space runtime served by a self-hosted server instead of the platform: started here, its functions loaded natively
+ * and its endpoints answered by a stage — the same module the platform runs as a runtime of the space.
+ */
+export declare const serveRuntime: (runtime: SpaceRuntime, context: SpaceRuntimeContext) => Promise<ServedRuntime>;
+/** Where a space's runtime is, for the page server to forward its endpoints to. */
+export type RuntimeTarget = {
+    /** Its base URL — `http://10.0.4.7:8791`. */
+    url: string;
+    /** What it is presented, as `Authorization: Bearer <secret>`. */
+    secret: string;
+    /** The paths it answers — what it described when it started. */
+    endpoints: readonly string[];
+};
+export type RuntimeProxyConfig = {
+    /** The runtime serving a space and environment — or none, for a space the platform serves alone. */
+    lookup: (space: {
+        spaceId: number;
+        environment: string;
+    }) => Promise<RuntimeTarget | undefined>;
+    /**
+     * Told each time a request is forwarded to a space's runtime — not for every request of the space, most of which are
+     * its pages: what counts as a runtime being used, for a deployment that stops the ones nobody uses.
+     */
+    onForward?: (space: {
+        spaceId: number;
+        environment: string;
+        endpoint: string;
+    }) => void;
+};
+/**
+ * The page server forwarding a space's endpoints to its runtime: the request as it came, streamed both ways — an agent's
+ * event stream included — without the visitor's cookies or `Authorization`, and with who asked in `X-Forwarded-*`.
+ *
+ * A data stage: after the auth chain, so the space is known, and before the space's `/api/` routes and its pages.
+ */
+export declare const createRuntimeProxyStage: ({ lookup, onForward }: RuntimeProxyConfig) => Stage<SSRContext>;

package/dist/modules/runtime/stages.js

@@ -0,0 +1,117 @@
+import { clientIp, requestOrigin } from "../../core/requestParser.js";
+import { endpointFor, endpointProblem } from "./contract.js";
+import { webRequestOf, writeWebResponse } from "../../core/http/webExchange.js";
+import { PLATFORM_HEADERS } from "./host.js";
+import http from "node:http";
+import https from "node:https";
+//#region src/modules/runtime/stages.ts
+var originOf = (ctx) => requestOrigin(ctx.req) || `${ctx.req.protocol}://${ctx.req.hostname}`;
+/** A runtime's endpoints answered in this process — self-hosting — exactly as the platform forwards them to its own. */
+var runtimeEndpointsStage = (endpoints) => {
+	const paths = Object.keys(endpoints);
+	const problems = paths.flatMap((path) => endpointProblem(path) ?? []);
+	if (problems.length > 0) throw new Error(problems.join("; "));
+	return async (ctx) => {
+		const endpoint = endpointFor(paths, ctx.req.path);
+		const answer = endpoint ? endpoints[endpoint] : void 0;
+		if (!endpoint || !answer) return false;
+		ctx.operation = `endpoint ${endpoint}`;
+		const request = await webRequestOf(ctx.raw, `${originOf(ctx)}${ctx.raw.url ?? ctx.req.path}`, PLATFORM_HEADERS);
+		await writeWebResponse(ctx.rawRes, await answer(request), ctx.signal);
+		return true;
+	};
+};
+/**
+* A space runtime served by a self-hosted server instead of the platform: started here, its functions loaded natively
+* and its endpoints answered by a stage — the same module the platform runs as a runtime of the space.
+*/
+var serveRuntime = async (runtime, context) => {
+	const parts = await runtime.start(context);
+	return {
+		native: parts.functions ? [parts.functions] : [],
+		stage: runtimeEndpointsStage(parts.endpoints ?? {}),
+		close: async () => {
+			await parts.close?.();
+		}
+	};
+};
+var HOP_BY_HOP = [
+	"connection",
+	"keep-alive",
+	"transfer-encoding",
+	"upgrade"
+];
+/** The query parameter a platform credential rides in (`credentials.ts`): never forwarded either. */
+var PLATFORM_QUERY_CREDENTIAL = "access-token";
+/** Never forwarded to a runtime: one hop's, and the platform's — the visitor's session is not the runtime's to hold. */
+var NOT_FORWARDED = /* @__PURE__ */ new Set([
+	...HOP_BY_HOP,
+	...PLATFORM_HEADERS,
+	"host"
+]);
+/** Never answered from one: the host's cookies are the platform's, as a function route's are. */
+var NOT_ANSWERED = /* @__PURE__ */ new Set([...HOP_BY_HOP, "set-cookie"]);
+/**
+* The page server forwarding a space's endpoints to its runtime: the request as it came, streamed both ways — an agent's
+* event stream included — without the visitor's cookies or `Authorization`, and with who asked in `X-Forwarded-*`.
+*
+* A data stage: after the auth chain, so the space is known, and before the space's `/api/` routes and its pages.
+*/
+var createRuntimeProxyStage = ({ lookup, onForward }) => async (ctx) => {
+	const { spaceId, environment = "main" } = ctx.req.ctx.spaceDeployment ?? {};
+	if (typeof spaceId !== "number") return false;
+	const target = await lookup({
+		spaceId,
+		environment
+	});
+	const endpoint = target ? endpointFor(target.endpoints, ctx.req.path) : void 0;
+	if (!target || !endpoint) return false;
+	ctx.operation = `runtime ${endpoint}`;
+	onForward?.({
+		spaceId,
+		environment,
+		endpoint
+	});
+	const headers = {};
+	Object.entries(ctx.raw.headers).forEach(([name, value]) => {
+		if (!name.startsWith(":") && !NOT_FORWARDED.has(name) && value !== void 0) headers[name] = value;
+	});
+	headers.authorization = `Bearer ${target.secret}`;
+	headers["x-forwarded-host"] = ctx.req.hostname;
+	headers["x-forwarded-proto"] = ctx.req.protocol;
+	headers["x-forwarded-for"] = clientIp(ctx.raw, ctx.req);
+	const url = new URL(ctx.raw.url ?? ctx.req.path, target.url);
+	url.searchParams.delete(PLATFORM_QUERY_CREDENTIAL);
+	await new Promise((resolve) => {
+		const upstream = (url.protocol === "https:" ? https : http).request(url, {
+			method: ctx.raw.method,
+			headers
+		});
+		const unreachable = () => {
+			if (!ctx.rawRes.headersSent) {
+				ctx.rawRes.writeHead(502, { "content-type": "application/json" });
+				ctx.rawRes.end(JSON.stringify({ error: "This space’s runtime is not answering" }));
+			} else ctx.rawRes.end();
+			resolve();
+		};
+		ctx.signal.addEventListener("abort", () => upstream.destroy(), { once: true });
+		upstream.on("error", unreachable);
+		upstream.on("response", (answer) => {
+			const answered = {};
+			Object.entries(answer.headers).forEach(([name, value]) => {
+				if (!NOT_ANSWERED.has(name) && value !== void 0) answered[name] = value;
+			});
+			ctx.rawRes.writeHead(answer.statusCode ?? 502, answered);
+			answer.on("data", (chunk) => ctx.rawRes.write(chunk));
+			answer.on("end", () => {
+				ctx.rawRes.end();
+				resolve();
+			});
+			answer.on("error", unreachable);
+		});
+		ctx.raw.pipe(upstream);
+	});
+	return true;
+};
+//#endregion
+export { createRuntimeProxyStage, runtimeEndpointsStage, serveRuntime };

package/dist/modules/ssr/Component.d.ts

@@ -9,13 +9,12 @@ export type ComponentProps = {
     ssrResult?: SSRRenderResult;
     sdkDevToolsStylePath?: string;
     debugMode?: boolean;
-    /** Forced on when the metering adapter degrades this render; otherwise left to the SDK's own default so the
-     *  markup here matches what the browser hydrates with. */
-    branding?: boolean;
-    /** The same degraded render, as the reason: the account behind this space is over its quota. */
+    /** Set when the metering adapter degrades this render: the account behind this space is over its quota. */
     overQuota?: boolean;
     /** The theme this document was rendered with, from the visitor's cookie. See `prepareRender`. */
     theme?: Theme;
+    /** The kept state the first paint depends on (`settings.paintedState`), from the visitor's cookie. */
+    state?: Record<string, unknown>;
 };
-declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, debugMode, branding, overQuota, theme }: ComponentProps) => import("react").JSX.Element;
+declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, debugMode, overQuota, theme, state }: ComponentProps) => import('react').JSX.Element;
 export default Component;

package/dist/modules/ssr/Component.js

@@ -1,7 +1,7 @@
 import PlitziSdk from "@plitzi/plitzi-sdk";
 import { jsx } from "react/jsx-runtime";
 //#region src/modules/ssr/Component.tsx
-var Component = ({ server, renderMode = "raw", previewMode = true, offlineData, environment = "main", plugins, ssrResult, sdkDevToolsStylePath, debugMode = false, branding, overQuota, theme }) => {
+var Component = ({ server, renderMode = "raw", previewMode = true, offlineData, environment = "main", plugins, ssrResult, sdkDevToolsStylePath, debugMode = false, overQuota, theme, state }) => {
 	const serverWithResult = {
 		...server,
 		ssr: {
@@ -18,9 +18,9 @@ var Component = ({ server, renderMode = "raw", previewMode = true, offlineData,
 		offlineData,
 		sdkDevToolsStylePath,
 		debugMode,
-		...branding === void 0 ? {} : { branding },
 		...overQuota === void 0 ? {} : { overQuota },
 		...theme === void 0 ? {} : { theme },
+		...state === void 0 ? {} : { state },
 		children: plugins && Object.keys(plugins).map((key) => /* @__PURE__ */ jsx(PlitziSdk.Plugin, {
 			renderType: key,
 			component: plugins[key].component,

package/dist/modules/ssr/handler.js

@@ -46,7 +46,7 @@ var renderSSR = async (req, res, config, renderFn, pluginManager, caches) => {
 			res.setHeader("X-Cache", "HIT");
 			if (devMode) res.setHeader("Server-Timing", "html;desc=\"cache-hit\";dur=0");
 			await meterPage(req, config, spaceId, environment, revision, true);
-			res.send(cached);
+			res.send(cached.html, { compressed: cached.compressed });
 			return;
 		}
 	}
@@ -63,7 +63,15 @@ var renderSSR = async (req, res, config, renderFn, pluginManager, caches) => {
 		metrics.log(`${req.method} ${req.path}`);
 	}
 	if (applySSRResult(res, result)) return;
-	if (htmlCache && cacheKey && body !== void 0 && cacheable) htmlCache.set(cacheKey, body);
+	if (htmlCache && cacheKey && body !== void 0 && cacheable) {
+		const page = {
+			html: body,
+			compressed: {}
+		};
+		htmlCache.set(cacheKey, page);
+		res.send(body, { compressed: page.compressed });
+		return;
+	}
 	res.send(body ?? "");
 };
 //#endregion

package/dist/modules/ssr/loadPluginComponents.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { pathToFileURL } from "node:url";
 //#region src/modules/ssr/loadPluginComponents.ts
 /** Module-level cache: the bundle's stamped identity → loaded React component. */
@@ -56,7 +57,7 @@ var loadPluginComponents = async (entries, inlineComponents) => {
 			component = mod.default ?? mod;
 			componentCache.set(cacheKey, component);
 		} catch (err) {
-			console.warn(`[SSR] Plugin "${e.keyName}" cannot be imported server-side, falling back to client rendering:`, err.message);
+			serverLog.warn("SSR", `Plugin "${e.keyName}" cannot be imported server-side, falling back to client rendering`, err);
 			failedImports.add(filePath);
 			return;
 		}