@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/functions-api.d.ts

@@ -0,0 +1,281 @@
+/**
+ * The `kv` tasks' own view: values rather than strings, and a TTL that means what a caller expects.
+ *
+ * Built by `createKvStore` over an {@link ActionKvAdapter}, and then narrowed to one space by `namespaceKv`. A
+ * task never sees an adapter.
+ */
+declare type ActionKvStore = {
+    get: (key: string) => Promise<unknown>;
+    set: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    increment: (key: string, amount: number, ttlSeconds?: number) => Promise<number>;
+    /**
+     * Writes `next` only if the key still holds `expected` — the value `get` answered — or, with `expected` undefined,
+     * only if it holds nothing. Answers whether it wrote: read, change, and write back with this, and a writer that
+     * lost the race is told so instead of undoing the other.
+     */
+    swap: (key: string, expected: unknown, next: unknown, ttlSeconds?: number) => Promise<boolean>;
+    /**
+     * Puts `entry` in the list — replacing the one with its id — keeping the highest `keep` by score, and answers what
+     * that dropped, for whatever it named to be let go of too. A list has no lifetime: it lives until its entries are
+     * removed.
+     */
+    listPut: (list: string, entry: KvListEntry, options?: KvListPutOptions) => Promise<KvListPut>;
+    listRange: (list: string, range?: KvListRange) => Promise<KvListEntry[]>;
+    /** Takes the entry with `id` out of the list, and answers whether it was there. */
+    listRemove: (list: string, id: string) => Promise<boolean>;
+    /**
+     * Reads the key, hands its value to `change` and writes back what that answers — reading and asking again when
+     * somebody wrote in between, so no writer undoes another. `change` answering `undefined` writes nothing. Answers what
+     * was written. `lifetime` is seconds, or worked out from the value written.
+     */
+    change: <T>(key: string, change: (current: unknown) => T | undefined | Promise<T | undefined>, lifetime?: KvChangeLifetime<T>) => Promise<T | undefined>;
+};
+
+/**
+ * A step refusing to go on, with a reason written for whoever called — a password too easy to guess, a board that is
+ * read-only, a quota reached.
+ *
+ * What any other step throws stays in the run's record and never reaches the caller: an error can carry a query, a
+ * URL, a credential's name, and a page is shown to anybody. This one says, by its type, that its message was written
+ * to be read. A run that ends on it answers `status: 'failed'` with the message as `error`, which a page's flow reads
+ * as `{{ step.error }}` — the same place a refusal before the run began puts its own.
+ */
+export declare class ActionRefusal extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Declares a space's functions. An identity at run time: it is here for the types, and so the same file is valid
+ * wherever it is loaded — natively in a self-hosted server, or built by the platform and run in its sandbox.
+ */
+export declare const defineFunctions: (definition: FunctionsDefinition) => FunctionsDefinition;
+
+declare type Environment = 'production' | 'staging' | 'development' | 'main';
+
+/**
+ * Everything a space's code can do besides computing — one object, the same wherever it runs. In a self-hosted server
+ * it is built from the run's own context; in the sandbox each method is a call back to the platform, which scopes it
+ * to the space and the run before doing it.
+ */
+export declare type FunctionContext = {
+    spaceId: number;
+    environment: Environment;
+    runId: string;
+    /** How the run was started: `call`, `render`, `schedule`, `webhook`… */
+    trigger: string;
+    /** `user:<id>` for a session, `ip:<address>` for everyone else — what a limit per person keys on. */
+    callerId: string;
+    user?: FunctionUser;
+    /**
+     * The space's own key/value store: `get`, `set`, `swap`, `increment`, lists — and `change`, to read, change and write
+     * a value back without undoing a writer that got there first.
+     */
+    kv: ActionKvStore;
+    /**
+     * Counts one more of `bucket` — per caller unless `per: 'everyone'` — and says whether it was within `most` in every
+     * `perSeconds`. The same count as a flow's `flow.rateLimit` step on that bucket. What to answer when it is not is the
+     * code's.
+     */
+    rateLimit: (bucket: string, limit: RateLimit) => Promise<RateCount>;
+    /**
+     * Signs `value` with a key of the space's own that the platform keeps and the code never sees: HMAC-SHA-256,
+     * base64url. What a link, an invitation or a key handed to a page is made of. Refused on a server with no signing
+     * secret.
+     */
+    sign: (value: string) => Promise<string>;
+    /** Whether `signature` is what `sign` answered for `value`, compared in constant time. */
+    verify: (value: string, signature: string) => Promise<boolean>;
+    /** To the hosts the space declared (`allow.hosts`) — and, with `credential`, with one of its secrets written in. */
+    fetch: FunctionFetch;
+    /** Says something on one of the space's realtime channels, as the server. */
+    publish: (topic: string, type: string, data: unknown) => Promise<void>;
+    /** Lets the visitor into one topic of a private (`grant: true`) channel. */
+    grant: (topic: string, ttlSeconds?: number) => Promise<string>;
+    /** Takes a grant back — or every grant for the topic, naming none. */
+    revoke: (topic: string, grant?: string) => Promise<void>;
+    /** A line for whoever reads the run: the builder's Try, and the deployment's logs. */
+    log: (...values: unknown[]) => void;
+    /** Progress for a caller that asked for a stream — a no-op when nobody did. */
+    emit: (chunk: unknown) => void;
+    /** Aborted when the run is: cancelled, or out of time. Hand it to what can stop early. */
+    signal: AbortSignal;
+};
+
+/** What a function's `fetch` answers: a web `Response`, whichever runner it is in. */
+export declare type FunctionFetch = (url: string | URL, init?: FunctionFetchInit) => Promise<Response>;
+
+/**
+ * A request a function makes: `fetch`'s own init, and `credential` — the id of one of the space's credentials, whose
+ * values the platform writes into the request where it says `{{credential.<key>}}` (in the URL, a header or the
+ * body). The code never holds the value; it names it.
+ */
+export declare type FunctionFetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    credential?: string;
+};
+
+/**
+ * An HTTP endpoint of the space, under `/api/`: a web-standard handler, the shape every edge runtime runs. The request
+ * carries no credentials — `ctx.user` says who is asking — and the response sets no cookies: the host's are the
+ * platform's.
+ */
+export declare type FunctionRoute = (request: Request, ctx: FunctionRouteContext) => Response | Promise<Response>;
+
+/** What a route's handler gets besides the request: the context, and the `:params` its key named, by name. */
+export declare type FunctionRouteContext = FunctionContext & {
+    params: Record<string, string>;
+};
+
+/** What a space's `functions/index.ts` exports: its tasks, its routes, and where its code may reach. */
+export declare type FunctionsDefinition = {
+    /** The hosts `ctx.fetch` may reach. Anything else is refused before it leaves. */
+    allow?: {
+        hosts?: string[];
+    };
+    tasks?: FunctionTask<never>[];
+    /** `'GET /board-assets/:board/:asset'` → a handler, served at `/api/board-assets/…`. */
+    routes?: Record<string, FunctionRoute>;
+};
+
+/**
+ * One step a server action can take, written by the space. The shape of the platform's own tasks — addressed as
+ * `<namespace>.<action>`, drawn in the builder from `params` — run with a {@link FunctionContext} rather than the
+ * platform's full one.
+ */
+export declare type FunctionTask<T extends Record<string, unknown> = Record<string, unknown>> = {
+    namespace: string;
+    action: string;
+    title: string;
+    description?: string;
+    params: Record<keyof T, InteractionCallbackParam<T>>;
+    run: (params: T, ctx: FunctionContext) => unknown;
+};
+
+/**
+ * Who started the run, as a space's own code may know them: everything a function decides by — who, their roles and
+ * permissions — and never their session. A token inside the sandbox is a token a function could send anywhere.
+ */
+export declare type FunctionUser = {
+    id: number;
+    username: string;
+    email: string;
+    verified: boolean;
+    permissions: string[];
+    roles: string[];
+};
+
+declare type InteractionCallbackParam<T extends Record<string, unknown> = Record<string, unknown>> = {
+    canBind?: boolean;
+    label?: string;
+    when?: boolean | ((params: InteractionCallbackParamValues<T>) => boolean);
+    /**
+     * This param names one of the space's credentials, of this provider. Serializable on purpose: an editor offers the
+     * space's credentials of that kind to pick from, rather than a text box somebody has to type an identifier into.
+     */
+    credentialProvider?: SpaceCredentialProvider;
+} & ({
+    type: 'text';
+    defaultValue?: string | number;
+} | {
+    type: 'textarea';
+    defaultValue?: string | number;
+} | {
+    type: 'codemirror-text';
+    defaultValue?: string;
+} | {
+    type: 'codemirror-json';
+    defaultValue?: string;
+} | {
+    type: 'boolean';
+    defaultValue?: boolean;
+} | {
+    /**
+     * Several elements of the space, stored as their ids. The editor offers the elements of `elementType` to pick
+     * from — it is the one that knows the page — so a step never asks for ids typed by hand.
+     */
+    type: 'elements';
+    defaultValue?: string[];
+    elementType?: string;
+} | {
+    type: 'select';
+    defaultValue?: string;
+    options: {
+        label: string;
+        value: string;
+    }[] | ((params: InteractionCallbackParamValues<T>) => {
+        label: string;
+        value: string;
+    }[]);
+} | {
+    type: (params: InteractionCallbackParamValues<T>) => InteractionParamType;
+    defaultValue?: string | number | boolean | string[];
+    options?: {
+        label: string;
+        value: string;
+    }[] | ((params: InteractionCallbackParamValues<T>) => {
+        label: string;
+        value: string;
+    }[]);
+});
+
+declare type InteractionCallbackParamValues<T extends Record<string, unknown> = Record<string, unknown>> = T;
+
+declare type InteractionParamType = 'boolean' | 'select' | 'text' | 'textarea' | 'codemirror-text' | 'codemirror-json' | 'elements';
+
+/**
+ * The lifetime a change writes with: a number of seconds, one worked out from the value written, or none.
+ */
+declare type KvChangeLifetime<T> = number | ((next: T) => number | undefined);
+
+/** One entry of a list: what it is called, where it sorts, and what it carries. */
+declare type KvListEntry = {
+    id: string;
+    score: number;
+    value: unknown;
+};
+
+/** What a put did: whether the entry went in, and what `keep` dropped to make room. */
+declare type KvListPut = {
+    stored: boolean;
+    dropped: KvListEntry[];
+};
+
+declare type KvListPutOptions = {
+    /** How many to keep, the highest scores; what falls past it is dropped. {@link MAX_LIST_ENTRIES} at most. */
+    keep?: number;
+    /**
+     * Replace an entry already there only with a score at least as high — a player's best, or the latest of two writes
+     * that arrived out of order. Otherwise the one there stays and nothing is written.
+     */
+    higherOnly?: boolean;
+};
+
+declare type KvListRange = {
+    /** How many entries to skip first. 0 when absent. */
+    offset?: number;
+    /** How many to answer. All of them when absent. */
+    limit?: number;
+    /** `desc` — the highest score first — when absent. */
+    order?: 'asc' | 'desc';
+};
+
+/** Where a limit stands after counting one more: whether that one was within it, and how many are left. */
+declare type RateCount = {
+    allowed: boolean;
+    count: number;
+    remaining: number;
+};
+
+/** How much of something is allowed: `most` in every `perSeconds`, for each caller or for everyone together. */
+declare type RateLimit = {
+    most: number;
+    perSeconds: number;
+    per?: 'caller' | 'everyone';
+};
+
+declare type SpaceCredentialProvider = 's3' | 'r2' | 'ssr' | 'custom' | 'smtp';
+
+export { }

package/dist/functions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Functions: a server's own code, and the contract a space's code is written against — the same file whether a
+ * self-hosted server loads it natively or the platform runs it in its sandbox. Its own entry so a space's code imports
+ * the contract alone, and nothing that runs it.
+ */
+export { ActionRefusal, defineFunctions } from './modules/functions/contract';
+export type { FunctionContext, FunctionFetch, FunctionFetchInit, FunctionRoute, FunctionRouteContext, FunctionsDefinition, FunctionTask, FunctionUser } from './modules/functions/contract';
+export type { FunctionsConfig, FunctionUsageRecord } from './modules/functions/config';
+export { DEFAULT_FUNCTION_LIMITS } from './modules/functions/config';
+/**
+ * What the platform keeps of a space's functions, and what it hands a runner: the built bundle and what it declared
+ * when it was saved (`prepareFunctions` on the actions module is the one way to make one).
+ */
+export type { FunctionsSource } from './modules/functions/build';
+export type { FunctionsManifest, FunctionTaskManifest, FunctionsProblem } from '@plitzi/sdk-shared';
+export type { FunctionInvocation, FunctionInvokeRequest, FunctionLimits, FunctionRunner, FunctionsBundle, FunctionStopReason, FunctionUsage, SpaceFunctions } from './modules/functions/protocol';
+export type { PreparedFunctions } from './modules/functions/space';
+export type { ManifestReading } from './modules/functions/manifest';
+export { functionTryEntry, TRY_STEP } from './modules/functions/tryEntry';

package/dist/functions.js

@@ -0,0 +1,5 @@
+import { ActionRefusal } from "./modules/actions/runtime/errors.js";
+import { DEFAULT_FUNCTION_LIMITS } from "./modules/functions/config.js";
+import { defineFunctions } from "./modules/functions/contract.js";
+import { TRY_STEP, functionTryEntry } from "./modules/functions/tryEntry.js";
+export { ActionRefusal, DEFAULT_FUNCTION_LIMITS, TRY_STEP, defineFunctions, functionTryEntry };

package/dist/functionsRunner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Running the spaces' functions: the runner service (its own process, holding nothing), the platform's client to it,
+ * and the isolates both are made of. Its own entry, apart from the contract, so a space's code and a self-hosted
+ * server's native functions never load a line of it — nor need `isolated-vm` or `core-js`, which only the process
+ * that runs isolates installs.
+ */
+export { startFunctionsRunnerService } from './modules/functions/runner/service';
+export type { FunctionsRunnerService, FunctionsRunnerServiceOptions } from './modules/functions/runner/service';
+export { createRemoteRunner } from './modules/functions/runner/remote';
+export type { RemoteRunnerOptions } from './modules/functions/runner/remote';
+export { createIsolateRunner } from './modules/functions/sandbox/isolate';
+export type { IsolateRunnerOptions } from './modules/functions/sandbox/isolate';
+export { FUNCTIONS_PROTOCOL, FunctionFailure } from './modules/functions/protocol';
+export { createLocalFunctions } from './modules/functions/local';
+export type { LocalFunctions, LocalFunctionsOptions } from './modules/functions/local';

package/dist/functionsRunner.js

@@ -0,0 +1,6 @@
+import { FUNCTIONS_PROTOCOL, FunctionFailure } from "./modules/functions/protocol.js";
+import { createIsolateRunner } from "./modules/functions/sandbox/isolate.js";
+import { startFunctionsRunnerService } from "./modules/functions/runner/service.js";
+import { createRemoteRunner } from "./modules/functions/runner/remote.js";
+import { createLocalFunctions } from "./modules/functions/local.js";
+export { FUNCTIONS_PROTOCOL, FunctionFailure, createIsolateRunner, createLocalFunctions, createRemoteRunner, startFunctionsRunnerService };

package/dist/handlers.d.ts

@@ -55,10 +55,10 @@ export { createAuthRouteHandlers, mountAuthRoutes } from './core/handlers/authRo
 export { createSocialAuthRouteHandlers, mountSocialAuthRoutes } from './core/handlers/socialRouteHandlers';
 export { createOAuthRouteHandlers, mountOAuthRoutes, OAUTH_ROUTE_PATHS } from './core/handlers/oauthRouteHandlers';
 export { createAuthMiddleware } from './core/handlers/authMiddleware';
-export { createCsrfMiddleware } from './core/handlers/csrfMiddleware';
+export { createCsrfMiddleware, createOriginGuardMiddleware } from './core/handlers/csrfMiddleware';
 export type { AuthRouteHandlersOptions } from './core/handlers/authRouteHandlers';
 export type { SocialRouteHandlersOptions } from './core/handlers/socialRouteHandlers';
 export type { OAuthResponse, OAuthRouteHandler, OAuthRouteHandlersOptions } from './core/handlers/oauthRouteHandlers';
 export type { AuthMiddlewareOptions } from './core/handlers/authMiddleware';
-export type { CsrfMiddlewareOptions } from './core/handlers/csrfMiddleware';
+export type { CsrfMiddlewareOptions, OriginGuardOptions } from './core/handlers/csrfMiddleware';
 export type { AuthedRequest, HttpRoute, JsonResponse, RedirectResponse, RouteHandler, RouterLike, SocialRouteHandler } from './core/handlers/types';

package/dist/handlers.js

@@ -2,5 +2,5 @@ import { createAuthRouteHandlers, mountAuthRoutes } from "./core/handlers/authRo
 import { createSocialAuthRouteHandlers, mountSocialAuthRoutes } from "./core/handlers/socialRouteHandlers.js";
 import { OAUTH_ROUTE_PATHS, createOAuthRouteHandlers, mountOAuthRoutes } from "./core/handlers/oauthRouteHandlers.js";
 import { createAuthMiddleware } from "./core/handlers/authMiddleware.js";
-import { createCsrfMiddleware } from "./core/handlers/csrfMiddleware.js";
-export { OAUTH_ROUTE_PATHS, createAuthMiddleware, createAuthRouteHandlers, createCsrfMiddleware, createOAuthRouteHandlers, createSocialAuthRouteHandlers, mountAuthRoutes, mountOAuthRoutes, mountSocialAuthRoutes };
+import { createCsrfMiddleware, createOriginGuardMiddleware } from "./core/handlers/csrfMiddleware.js";
+export { OAUTH_ROUTE_PATHS, createAuthMiddleware, createAuthRouteHandlers, createCsrfMiddleware, createOAuthRouteHandlers, createOriginGuardMiddleware, createSocialAuthRouteHandlers, mountAuthRoutes, mountOAuthRoutes, mountSocialAuthRoutes };

package/dist/helpers/atomicFile.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Writes a file whole or not at all: to a temporary name beside it, then renamed over it.
+ *
+ * Several workers can build or download the same plugin into the same folder at once, and a reader can open a file
+ * while another process is writing it. A rename replaces the file in one step, so whoever reads it sees the old
+ * version or the new one — never half of either. Same-folder temporary, so the rename never crosses a filesystem.
+ */
+export declare const writeFileAtomic: (file: string, data: string | Uint8Array) => Promise<void>;
+/** `copyFile`, with the same whole-or-nothing guarantee. */
+export declare const copyFileAtomic: (source: string, file: string) => Promise<void>;

package/dist/helpers/atomicFile.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+//#region src/helpers/atomicFile.ts
+/**
+* Writes a file whole or not at all: to a temporary name beside it, then renamed over it.
+*
+* Several workers can build or download the same plugin into the same folder at once, and a reader can open a file
+* while another process is writing it. A rename replaces the file in one step, so whoever reads it sees the old
+* version or the new one — never half of either. Same-folder temporary, so the rename never crosses a filesystem.
+*/
+var writeFileAtomic = async (file, data) => {
+	const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await fs.writeFile(temporary, data);
+		await fs.rename(temporary, file);
+	} catch (error) {
+		await fs.rm(temporary, { force: true });
+		throw error;
+	}
+};
+/** `copyFile`, with the same whole-or-nothing guarantee. */
+var copyFileAtomic = async (source, file) => {
+	const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await fs.copyFile(source, temporary);
+		await fs.rename(temporary, file);
+	} catch (error) {
+		await fs.rm(temporary, { force: true });
+		throw error;
+	}
+};
+//#endregion
+export { copyFileAtomic, writeFileAtomic };

package/dist/helpers/atomicFile.test.d.ts

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

package/dist/helpers/buildResponseHelpers.js

@@ -1,5 +1,18 @@
 import { DEFAULT_COMPRESSION, compressBody, selectEncoding } from "./compress.js";
 //#region src/helpers/buildResponseHelpers.ts
+/**
+* `compressBody`, remembered in `store` when the caller keeps one: the same body in the same encoding is compressed
+* once. What comes back uncompressed (identity, or a body under the threshold) is never stored — there is nothing to
+* reuse, and a stored copy would only be the body again.
+*/
+var compressOnce = (body, encoding, compression, store) => {
+	if (!store || encoding === "identity") return compressBody(body, encoding, compression);
+	const kept = store[encoding];
+	if (kept) return kept;
+	const compressed = compressBody(body, encoding, compression, true);
+	if (typeof compressed !== "string") store[encoding] = compressed;
+	return compressed;
+};
 var buildResponseHelpers = (raw, acceptEncoding, compression = DEFAULT_COMPRESSION) => {
 	let statusCode = 200;
 	const encoding = selectEncoding(acceptEncoding, compression);
@@ -12,7 +25,24 @@ var buildResponseHelpers = (raw, acceptEncoding, compression = DEFAULT_COMPRESSI
 	* already said so in a header.
 	*/
 	const transformable = () => !String(raw.getHeaders()["cache-control"]).includes("no-transform");
-	const writeSend = (body) => {
+	/** A stored form this request can take as it is, without the body it was made from. */
+	const storedFor = (store) => encoding === "identity" || !transformable() ? void 0 : store?.[encoding];
+	const writeBody = (payload, encoded) => {
+		if (encoded) {
+			raw.setHeader("Content-Encoding", encoding);
+			raw.setHeader("Vary", "Accept-Encoding");
+		}
+		raw.setHeader("Content-Length", Buffer.byteLength(payload).toString());
+		if (!raw.headersSent) raw.writeHead(statusCode);
+		raw.end(payload);
+	};
+	const writeSend = (content, store) => {
+		const stored = typeof content === "function" ? storedFor(store) : void 0;
+		if (stored) {
+			writeBody(stored, true);
+			return;
+		}
+		const body = typeof content === "function" ? content() : content;
 		/**
 		* A Buffer goes out untouched.
 		*
@@ -21,14 +51,8 @@ var buildResponseHelpers = (raw, acceptEncoding, compression = DEFAULT_COMPRESSI
 		* corrupts any font, image or archive served through it. What a Buffer holds is also compressed already
 		* (woff2, png), so re-encoding it would cost CPU to make it bigger.
 		*/
-		const compressed = typeof body === "string" && transformable() ? compressBody(body, encoding, compression) : body;
-		if (compressed !== body) {
-			raw.setHeader("Content-Encoding", encoding);
-			raw.setHeader("Vary", "Accept-Encoding");
-		}
-		raw.setHeader("Content-Length", Buffer.byteLength(compressed).toString());
-		if (!raw.headersSent) raw.writeHead(statusCode);
-		raw.end(compressed);
+		const compressed = typeof body === "string" && transformable() ? compressOnce(body, encoding, compression, store) : body;
+		writeBody(compressed, compressed !== body);
 	};
 	return {
 		get status() {
@@ -43,8 +67,8 @@ var buildResponseHelpers = (raw, acceptEncoding, compression = DEFAULT_COMPRESSI
 		setStatus(code) {
 			statusCode = code;
 		},
-		send(body) {
-			writeSend(body);
+		send(body, options) {
+			writeSend(body, options?.compressed);
 		},
 		write(chunk) {
 			if (!raw.headersSent) raw.writeHead(statusCode);

package/dist/helpers/buildServerInfo.js

@@ -1,3 +1,4 @@
+import { requestOrigin } from "../core/requestParser.js";
 //#region src/helpers/buildServerInfo.ts
 var getEnvironment = (env = "production", server) => {
 	switch (env) {
@@ -36,7 +37,8 @@ var getEnvironment = (env = "production", server) => {
 */
 var buildServerInfo = (req, config, ssr) => {
 	const accessToken = req.query["access-token"];
-	const origin = `${req.protocol}://${req.hostname}`;
+	const origin = requestOrigin(req) || `${req.protocol}://${req.hostname}`;
+	const host = origin.slice(`${req.protocol}://`.length);
 	const user = req.ctx.user;
 	return getEnvironment(config.environment, {
 		basePath: "/",
@@ -52,7 +54,7 @@ var buildServerInfo = (req, config, ssr) => {
 		location: {
 			origin,
 			protocol: `${req.protocol}:`,
-			host: req.hostname,
+			host,
 			hostname: req.hostname,
 			pathname: req.path || "/",
 			search: req.search

package/dist/helpers/buildServerInfo.test.d.ts

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

package/dist/helpers/cache/CompressedFileCache.d.ts

@@ -0,0 +1,18 @@
+import { CompressedBodies } from '@plitzi/sdk-shared';
+/**
+ * The compressed forms of static files, one entry per file, within a byte budget.
+ *
+ * A file is compressed once per version and encoding instead of on every request — the SDK bundle alone is megabytes
+ * of JavaScript. Keyed by path with the version beside it, so a file that changed replaces its old forms rather than
+ * sitting next to them. Past the budget the least recently served files go first.
+ */
+export declare class CompressedFileCache {
+    private readonly maxBytes;
+    private readonly entries;
+    constructor(maxBytes: number);
+    /** Where the compressed forms of this version of the file are kept; `send` fills it as encodings are asked for. */
+    storeFor(filePath: string, version: string): CompressedBodies;
+    /** Drops the least recently served files until the rest fit the budget. Called after a send may have grown one. */
+    trim(): void;
+    get bytes(): number;
+}

package/dist/helpers/cache/CompressedFileCache.js

@@ -0,0 +1,44 @@
+//#region src/helpers/cache/CompressedFileCache.ts
+var sizeOf = (bodies) => (bodies.br?.length ?? 0) + (bodies.gzip?.length ?? 0);
+/**
+* The compressed forms of static files, one entry per file, within a byte budget.
+*
+* A file is compressed once per version and encoding instead of on every request — the SDK bundle alone is megabytes
+* of JavaScript. Keyed by path with the version beside it, so a file that changed replaces its old forms rather than
+* sitting next to them. Past the budget the least recently served files go first.
+*/
+var CompressedFileCache = class {
+	maxBytes;
+	entries = /* @__PURE__ */ new Map();
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	/** Where the compressed forms of this version of the file are kept; `send` fills it as encodings are asked for. */
+	storeFor(filePath, version) {
+		const existing = this.entries.get(filePath);
+		this.entries.delete(filePath);
+		const entry = existing?.version === version ? existing : {
+			version,
+			bodies: {}
+		};
+		this.entries.set(filePath, entry);
+		return entry.bodies;
+	}
+	/** Drops the least recently served files until the rest fit the budget. Called after a send may have grown one. */
+	trim() {
+		let total = 0;
+		for (const entry of this.entries.values()) total += sizeOf(entry.bodies);
+		for (const [filePath, entry] of this.entries) {
+			if (total <= this.maxBytes) return;
+			total -= sizeOf(entry.bodies);
+			this.entries.delete(filePath);
+		}
+	}
+	get bytes() {
+		let total = 0;
+		for (const entry of this.entries.values()) total += sizeOf(entry.bodies);
+		return total;
+	}
+};
+//#endregion
+export { CompressedFileCache };

package/dist/helpers/cache/CompressedFileCache.test.d.ts

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

package/dist/helpers/cache/cacheManager.d.ts

@@ -1,3 +1,3 @@
 import { TtlCache } from './TtlCache';
 import { CacheManager } from '@plitzi/sdk-shared';
-export declare const buildCacheManager: (store: TtlCache<string>) => CacheManager;
+export declare const buildCacheManager: <T>(store: TtlCache<T>) => CacheManager;

package/dist/helpers/cache/cacheManager.js

@@ -1,3 +1,4 @@
+import { readHtmlCacheKey } from "./keys.js";
 //#region src/helpers/cache/cacheManager.ts
 var buildCacheManager = (store) => ({
 	invalidate(filter) {
@@ -7,7 +8,7 @@ var buildCacheManager = (store) => ({
 			return count;
 		}
 		return store.invalidateWhere((key) => {
-			const [keySpaceId, keyEnvironment, , keyHostname] = key.split("\0");
+			const { spaceId: keySpaceId, environment: keyEnvironment, hostname: keyHostname } = readHtmlCacheKey(key);
 			if (filter.spaceId !== void 0 && keySpaceId !== String(filter.spaceId)) return false;
 			if (filter.environment !== void 0 && keyEnvironment !== filter.environment) return false;
 			if (filter.hostname !== void 0 && keyHostname !== filter.hostname) return false;

package/dist/helpers/cache/cacheManager.test.d.ts

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

package/dist/helpers/cache/index.d.ts

@@ -2,5 +2,5 @@ export { DEFAULT_TTL_MS } from './defaults';
 export { TtlCache } from './TtlCache';
 export { buildHtmlCacheKey, buildOfflineDataCacheKey, buildRscCacheKey } from './keys';
 export { buildCacheManager } from './cacheManager';
-export type { ServerCaches } from './serverCaches';
+export type { CachedPage, ServerCaches } from './serverCaches';
 export { createServerCaches, destroyServerCaches } from './serverCaches';

package/dist/helpers/cache/keys.d.ts

@@ -10,7 +10,11 @@
  * one keyed — a space that switched dev tools on for its published site would otherwise hand the first visitor's
  * choice to the rest.
  *
- * Read from the request here rather than handed in, so a call site cannot key the page without it. Only those two
+ * So is the kept state the first paint depends on (`settings.paintedState`): `prepareRender` renders with that cookie's
+ * values, so a page drawn with one visitor's toolbar must not be served to the next. Keyed by its raw value — this
+ * key does not know which keys a space declares, and a space that declares none has no such cookie to split on.
+ *
+ * Read from the request here rather than handed in, so a call site cannot key the page without it. Only those
  * cookies are read: keying the whole header would split the cache on every analytics cookie a visitor carries.
  */
 export declare const buildHtmlCacheKey: (accessToken: string | undefined, spaceId: number | string | null, environment: string, revision: number, req: {
@@ -22,6 +26,16 @@ export declare const buildHtmlCacheKey: (accessToken: string | undefined, spaceI
         host?: string;
     };
 }) => string;
+/**
+ * What an HTML key says about the page it holds, read by the one list that also writes it. `server.cache.invalidate`
+ * filters on these; it used to split the key by positions of its own, and when the key grew a field in front the
+ * filter went on reading the wrong ones — every invalidation by space matched nothing.
+ */
+export declare const readHtmlCacheKey: (key: string) => {
+    spaceId: string;
+    environment: string;
+    hostname: string;
+};
 export declare const buildOfflineDataCacheKey: (spaceId: number, environment: string, revision: number) => string;
 export declare const buildRscCacheKey: (spaceId: number, environment: string, revision: number, userId: string | number | undefined, idsParam: string | undefined, req: {
     hostname: string;