@plitzi/sdk-server 0.37.9 → 0.38.1

package/dist/core/server/fleet/relay.js

@@ -1,5 +1,6 @@
 import { serverLog } from "../../../helpers/serverLog.js";
 import { broadcast, onBroadcast } from "./link.js";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/core/server/fleet/relay.ts
 /**
 * `server.cache` and `server.plugins` in a fleet, whose workers each keep their own: what one process is told, every
@@ -10,7 +11,6 @@ import { broadcast, onBroadcast } from "./link.js";
 * Code that runs in every process (a pub/sub subscription made where the server is created) is told N times; what
 * is relayed is safe to apply again, and cheap: it only drops entries from memory.
 */
-var isRecord = (value) => typeof value === "object" && value !== null;
 var PLUGIN_ACTIONS = [
 	"copy",
 	"compile",

package/dist/core/services/action.js

@@ -1,3 +1,4 @@
+import { connectorLookupsOf } from "../configSeam.js";
 import { handleActionCall } from "../../modules/actions/transport/callHandler.js";
 import { handleActionCatalog } from "../../modules/actions/transport/catalogHandler.js";
 import { handleActionWebhook } from "../../modules/actions/transport/webhookHandler.js";
@@ -38,8 +39,8 @@ var lineageOf = (req) => {
 var actionStage = async (ctx) => {
 	const { config, req, actions } = ctx;
 	const actionPath = config.action?.path ?? "/_action";
-	const hasConnectors = !!config.connectors;
-	if (!hasConnectors && !actions) return false;
+	const { connectors } = config;
+	if (!connectors && !actions) return false;
 	if (actions && req.method === "GET" && req.path === `${actionPath}/catalog`) {
 		ctx.operation = "action:catalog";
 		if (!req.ctx.user) {
@@ -104,7 +105,7 @@ var actionStage = async (ctx) => {
 		});
 		return true;
 	}
-	if (addressesAction || !hasConnectors) {
+	if (addressesAction || !connectors) {
 		ctx.operation = "action";
 		ctx.res.setStatus(404);
 		ctx.res.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -115,7 +116,7 @@ var actionStage = async (ctx) => {
 		return true;
 	}
 	ctx.operation = "action";
-	await handleAction(req, ctx.res, config, config.connectors);
+	await handleAction(req, ctx.res, config, connectorLookupsOf(connectors));
 	return true;
 };
 //#endregion

package/dist/core/services/registry.js

@@ -2,6 +2,7 @@ import { actionStage } from "./action.js";
 import { functionRoutesStage } from "./functionRoutes.js";
 import { realtimeStage } from "./realtime.js";
 import { rscStage } from "./rsc.js";
+import { imagesStage } from "../http/stages/images.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
 import { authRoutesStages } from "../http/stages/authRoutes.js";
 import { fontAssetsStage } from "../http/stages/fontAssets.js";
@@ -17,6 +18,7 @@ var buildPagePipeline = (services, extensions = {}) => {
 		wellKnownStage,
 		pluginAssetsStage,
 		fontAssetsStage,
+		imagesStage,
 		...authRoutesStages,
 		configStaticStage,
 		sdkAssetsStage

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

@@ -1,3 +1,14 @@
+/** What a cache key reads off a request: where it is, and — from the resolved deployment — what the flags are at. */
+type CacheKeyRequest = {
+    hostname: string;
+    path: string;
+    search: string;
+    ctx?: {
+        spaceDeployment?: {
+            flagsVersion?: string;
+        };
+    };
+};
 /**
  * The key a rendered document is cached under.
  *
@@ -14,13 +25,17 @@
  * 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.
  *
+ * So are the feature flags a tester forced from the dev tools, on a page that authorizes debugging: drawn with them,
+ * the page is not everybody's, and a tester holding the cookie must never be handed a page drawn without it. Keyed
+ * by its raw value, like the kept state.
+ *
+ * So is what the space's flags are at (`flagsVersion` on the resolved deployment), for a deployment that changes them
+ * apart from its revisions: a flag turned in production must reach the next visitor, while the revision is the same.
+ *
  * 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: {
-    hostname: string;
-    path: string;
-    search: string;
+export declare const buildHtmlCacheKey: (accessToken: string | undefined, spaceId: number | string | null, environment: string, revision: number, req: CacheKeyRequest & {
     headers: {
         cookie?: string;
         host?: string;
@@ -36,9 +51,7 @@ export declare const readHtmlCacheKey: (key: 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;
-    path: string;
-    search: string;
-}) => string;
+/** The space as read for a render: its revision, and what its flags are at when they change apart from it. */
+export declare const buildOfflineDataCacheKey: (spaceId: number, environment: string, revision: number, flagsVersion: string | undefined) => string;
+export declare const buildRscCacheKey: (spaceId: number, environment: string, revision: number, userId: string | number | undefined, idsParam: string | undefined, req: CacheKeyRequest) => string;
+export {};

package/dist/helpers/cache/keys.js

@@ -1,17 +1,21 @@
 import { ssrPaintedCookieName } from "../paintedCookie.js";
 import { readCookie } from "../readCookie.js";
+import { flagsCookieName } from "@plitzi/sdk-shared/flags";
 import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 //#region src/helpers/cache/keys.ts
+var flagsVersionOf = (req) => req.ctx?.spaceDeployment?.flagsVersion ?? "";
 /** The fields of an HTML key, in the order they are joined. */
 var HTML_KEY_FIELDS = [
 	"accessToken",
 	"spaceId",
 	"environment",
 	"revision",
+	"flags",
 	"theme",
 	"painted",
 	"debugHidden",
+	"forcedFlags",
 	"hostname",
 	"path",
 	"search"
@@ -32,6 +36,13 @@ var HTML_KEY_FIELDS = [
 * 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.
 *
+* So are the feature flags a tester forced from the dev tools, on a page that authorizes debugging: drawn with them,
+* the page is not everybody's, and a tester holding the cookie must never be handed a page drawn without it. Keyed
+* by its raw value, like the kept state.
+*
+* So is what the space's flags are at (`flagsVersion` on the resolved deployment), for a deployment that changes them
+* apart from its revisions: a flag turned in production must reach the next visitor, while the revision is the same.
+*
 * 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.
 */
@@ -41,9 +52,11 @@ var buildHtmlCacheKey = (accessToken = "anonymous", spaceId, environment, revisi
 		spaceId: String(spaceId ?? 1),
 		environment,
 		revision: String(revision),
+		flags: flagsVersionOf(req),
 		theme: themeFromCookies(req.headers.cookie) ?? "",
 		painted: readCookie(req.headers.cookie, ssrPaintedCookieName(req.headers.host)) ?? "",
 		debugHidden: readCookie(req.headers.cookie, debugCookieName(req.headers.host)) === "false" ? "debug-off" : "",
+		forcedFlags: readCookie(req.headers.cookie, flagsCookieName(req.headers.host)) ?? "",
 		hostname: req.hostname,
 		path: req.path,
 		search: req.search
@@ -64,7 +77,8 @@ var readHtmlCacheKey = (key) => {
 		hostname: at("hostname")
 	};
 };
-var buildOfflineDataCacheKey = (spaceId, environment, revision) => `${spaceId}|${environment}|${revision}`;
-var buildRscCacheKey = (spaceId, environment, revision, userId, idsParam, req) => `${spaceId}\0${environment}\0${revision}\0${userId ?? "anon"}\0${idsParam ?? ""}\0${req.hostname}\0${req.path}\0${req.search}`;
+/** The space as read for a render: its revision, and what its flags are at when they change apart from it. */
+var buildOfflineDataCacheKey = (spaceId, environment, revision, flagsVersion) => `${spaceId}|${environment}|${revision}|${flagsVersion ?? ""}`;
+var buildRscCacheKey = (spaceId, environment, revision, userId, idsParam, req) => `${spaceId}\0${environment}\0${revision}\0${flagsVersionOf(req)}\0${userId ?? "anon"}\0${idsParam ?? ""}\0${req.hostname}\0${req.path}\0${req.search}`;
 //#endregion
 export { buildHtmlCacheKey, buildOfflineDataCacheKey, buildRscCacheKey, readHtmlCacheKey };

package/dist/helpers/flagOverrides.d.ts

@@ -0,0 +1,27 @@
+import { Environment, FlagOverrides, SSRServerConfig } from '@plitzi/sdk-shared';
+/** The deployment's own layer for one space: `config.flags`, asked per space when it is a function. */
+export declare const serverFlagsFor: (config: Pick<SSRServerConfig, "flags">, space: {
+    spaceId: number;
+    environment: Environment;
+}) => Record<string, boolean> | undefined;
+/**
+ * The flags a tester forced from the dev tools, for a request allowed to debug — undefined for everybody else, and for
+ * a tester who forced nothing. Authorization is asked only when there is a cookie to honour, because answering it can
+ * mean reading the space.
+ */
+export declare const forcedFlagsFor: (req: {
+    headers: {
+        cookie?: string;
+        host?: string;
+    };
+}, authorized: boolean | (() => Promise<boolean>)) => Promise<Record<string, boolean> | undefined>;
+/** Both layers this server answers for, for one request. */
+export declare const requestFlagOverrides: (config: Pick<SSRServerConfig, "flags">, req: {
+    headers: {
+        cookie?: string;
+        host?: string;
+    };
+}, space: {
+    spaceId: number;
+    environment: Environment;
+}, authorized: boolean | (() => Promise<boolean>)) => Promise<FlagOverrides>;

package/dist/helpers/flagOverrides.js

@@ -0,0 +1,25 @@
+import { forcedFlagsFromCookies } from "@plitzi/sdk-shared/flags";
+//#region src/helpers/flagOverrides.ts
+/** The deployment's own layer for one space: `config.flags`, asked per space when it is a function. */
+var serverFlagsFor = (config, space) => typeof config.flags === "function" ? config.flags(space) : config.flags;
+/**
+* The flags a tester forced from the dev tools, for a request allowed to debug — undefined for everybody else, and for
+* a tester who forced nothing. Authorization is asked only when there is a cookie to honour, because answering it can
+* mean reading the space.
+*/
+var forcedFlagsFor = async (req, authorized) => {
+	const forced = forcedFlagsFromCookies(req.headers.cookie, req.headers.host);
+	if (Object.keys(forced).length === 0) return;
+	return (typeof authorized === "boolean" ? authorized : await authorized()) ? forced : void 0;
+};
+/** Both layers this server answers for, for one request. */
+var requestFlagOverrides = async (config, req, space, authorized) => {
+	const server = serverFlagsFor(config, space);
+	const qa = await forcedFlagsFor(req, authorized);
+	return {
+		...server ? { server } : {},
+		...qa ? { qa } : {}
+	};
+};
+//#endregion
+export { forcedFlagsFor, requestFlagOverrides, serverFlagsFor };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { createServer, resolveServices } from './core/createServer';
 export { closeOnSignals } from './core/server/closeOnSignals';
 export { loadFunctions, readFunctionsDir } from './modules/functions/load';
+export { freePort } from './core/freePort';
 export { registerHealthCheck, buildHealthPayload } from './core/health';
 export { consoleLogger, isLogged, logLevelOf, renderLogEvent, serverLog } from './helpers/serverLog';
 export type { HealthCheckApp, HealthIdentity } from './core/health';

package/dist/index.js

@@ -10,6 +10,7 @@ import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { createServer } from "./core/createServer.js";
 import { closeOnSignals } from "./core/server/closeOnSignals.js";
 import { loadFunctions, readFunctionsDir } from "./modules/functions/load.js";
+import { freePort } from "./core/freePort.js";
 import { createCloudAdapters } from "./adapters/cloudAdapters.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
 import { createAuthAdapters } from "./adapters/authAdapters.js";
@@ -18,4 +19,4 @@ import { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildc
 import { createSpaceAdapters } from "./adapters/space/index.js";
 import { createLocalFontStore, hostedPathsOf } from "./core/fontStore.js";
 import { createRedisPubSub } from "./modules/realtime/redisPubSub.js";
-export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, hostedPathsOf, isLogged, loadFunctions, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };
+export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, freePort, hostedPathsOf, isLogged, loadFunctions, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };

package/dist/modules/actions/moduleFor.js

@@ -1,3 +1,4 @@
+import { actionLookupsOf, dbDriversOf, functionsConfigOf } from "../../core/configSeam.js";
 import { createActionsModule } from "./index.js";
 import { realtimeModuleFor } from "../realtime/index.js";
 //#region src/modules/actions/moduleFor.ts
@@ -19,8 +20,9 @@ var actionsModuleFor = (config) => {
 	const existing = modules.get(config);
 	if (existing) return existing;
 	const module = createActionsModule({
-		lookups,
-		functions: config.functions,
+		lookups: actionLookupsOf(lookups),
+		flags: config.flags,
+		functions: functionsConfigOf(config.functions),
 		limits: config.action?.limits,
 		concurrency: config.action?.concurrency,
 		kv: config.action?.kv,
@@ -28,7 +30,7 @@ var actionsModuleFor = (config) => {
 		rateLimit: config.action?.rateLimit,
 		idempotency: config.action?.idempotency,
 		signingSecret: config.action?.signingSecret,
-		dbDrivers: config.action?.dbDrivers,
+		dbDrivers: dbDriversOf(config.action?.dbDrivers),
 		email: config.action?.email,
 		onRun: config.action?.onRun,
 		realtime: realtimeModuleFor(config)

package/dist/modules/actions/runtime/flags.d.ts

@@ -0,0 +1,16 @@
+import { ActionRunRequest, ActionsConfig } from '../types';
+/**
+ * Whether a flow names `flags` anywhere — a template, a `when` rule's field. Only those are worth a lookup: most flows
+ * read no flag, and asking for the space's flags on every run of every one of them would be a read per click.
+ *
+ * Over the serialized document, so a template in any step's params counts without knowing every step's shape. A word
+ * `flags` that is not the source costs one lookup that was not needed, never a flow without its flags. Kept per
+ * document, which the lookups hand out once per version.
+ */
+export declare const readsFlags: (document: object) => boolean;
+/**
+ * The space's flags as this run sees them: what the space declares at the run's revision, matched against the run's
+ * environment and visitor, then the server's own layer and a tester's forced one — the same order a page resolves
+ * them in. A run has no URL, so a rule on the host or the route does not match here.
+ */
+export declare const flagsForRun: (config: Pick<ActionsConfig, "lookups" | "flags">, request: Pick<ActionRunRequest, "entry" | "spaceId" | "environment" | "at" | "user" | "forcedFlags">) => Promise<Record<string, boolean>>;

package/dist/modules/actions/runtime/flags.js

@@ -0,0 +1,49 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { serverFlagsFor } from "../../../helpers/flagOverrides.js";
+import { flagUserFromSSR, flagValues, resolveFlags, undeclaredFlagOverrides } from "@plitzi/sdk-shared/flags";
+//#region src/modules/actions/runtime/flags.ts
+var reading = /* @__PURE__ */ new WeakMap();
+/**
+* Whether a flow names `flags` anywhere — a template, a `when` rule's field. Only those are worth a lookup: most flows
+* read no flag, and asking for the space's flags on every run of every one of them would be a read per click.
+*
+* Over the serialized document, so a template in any step's params counts without knowing every step's shape. A word
+* `flags` that is not the source costs one lookup that was not needed, never a flow without its flags. Kept per
+* document, which the lookups hand out once per version.
+*/
+var readsFlags = (document) => {
+	const known = reading.get(document);
+	if (known !== void 0) return known;
+	const reads = /\bflags\b/.test(JSON.stringify(document));
+	reading.set(document, reads);
+	return reads;
+};
+/**
+* The space's flags as this run sees them: what the space declares at the run's revision, matched against the run's
+* environment and visitor, then the server's own layer and a tester's forced one — the same order a page resolves
+* them in. A run has no URL, so a rule on the host or the route does not match here.
+*/
+var flagsForRun = async (config, request) => {
+	if (!readsFlags(request.entry.document)) return {};
+	const { getFlags } = config.lookups;
+	if (!getFlags) {
+		serverLog.warn("Actions", `Action "${request.entry.id}" reads flags, but this deployment's action lookups have no getFlags: it sees none.`);
+		return {};
+	}
+	const declared = await getFlags(request.spaceId, request.at);
+	const { spaceId, environment, user } = request;
+	const overrides = {
+		server: serverFlagsFor(config, {
+			spaceId,
+			environment
+		}),
+		qa: request.forcedFlags
+	};
+	undeclaredFlagOverrides(declared, { server: overrides.server }).forEach(({ name }) => serverLog.warn("Actions", `The server sets the flag "${name}", which space ${spaceId} does not declare.`));
+	return flagValues(resolveFlags(declared, {
+		environment,
+		user: flagUserFromSSR(user)
+	}, overrides));
+};
+//#endregion
+export { flagsForRun, readsFlags };

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

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

package/dist/modules/actions/runtime/kvList.js

@@ -1,3 +1,4 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/modules/actions/runtime/kvList.ts
 /**
 * The most a list holds. A list is one value of the store, read and written whole, so it is for what a page shows at
@@ -11,7 +12,6 @@ var MAX_LIST_ENTRIES = 500;
 var MAX_LIST_BYTES = 128e3;
 var ID = /^[A-Za-z0-9:_.@-]{1,128}$/;
 var listIdProblem = (id) => typeof id === "string" && ID.test(id) ? void 0 : "A list entry’s id is 1-128 of A-Z a-z 0-9 : _ . @ -";
-var isRecord = (value) => typeof value === "object" && value !== null;
 var isEntry = (value) => isRecord(value) && typeof value.id === "string" && typeof value.score === "number";
 /** The entries a stored list holds — none for a key that holds nothing, or something that is not a list. */
 var parseList = (raw) => {

package/dist/modules/actions/runtime/runAction.js

@@ -5,6 +5,7 @@ import { createKvStore } from "./kvStore.js";
 import { resolveLimits } from "./limits.js";
 import { createMemoryKv } from "./memoryKv.js";
 import { createEmailSender } from "./email.js";
+import { flagsForRun } from "./flags.js";
 import { createRedactor, projectUser } from "./scope.js";
 import { precheckRun } from "./precheck.js";
 import { createSigning } from "./signing.js";
@@ -240,6 +241,7 @@ var createActionRunner = (config, registryFor, baseFetch = fetch) => {
 		const scope = {
 			input: values,
 			user: projectUser(request.user),
+			flags: await flagsForRun(config, request),
 			spaceId: request.spaceId,
 			environment: request.environment,
 			trigger: request.trigger,

package/dist/modules/actions/transport/callHandler.js

@@ -1,6 +1,7 @@
 import { serverLog } from "../../../helpers/serverLog.js";
 import { triggerParams } from "../runtime/triggers.js";
 import { ActionRunError } from "../runtime/errors.js";
+import { forcedFlagsFor } from "../../../helpers/flagOverrides.js";
 import { precheckRun } from "../runtime/precheck.js";
 import onAbort from "../../../helpers/onAbort.js";
 import { openStream, wantsStream } from "./stream.js";
@@ -176,6 +177,12 @@ var handleActionCall = async (deps) => {
 	const readsRun = mayReadTrace(entryPoint, req.ctx.user);
 	const fullTrace = readsRun && (authoring === true || config.devMode === true);
 	const showsOutline = async () => readsRun && (fullTrace || await resolveDebugAuthorization(config, async () => (await config.adapters.getOfflineData(spaceId, environment, revision))?.schema.settings));
+	/**
+	* The flags a tester forced on the page this call came from, so the flow sees the feature the page was drawn with.
+	* Only for a page allowed to debug — the cookie is the visitor's own, and anywhere else it would let any of them
+	* switch a feature on for the server too. The authorization is asked only when there is a cookie to honour.
+	*/
+	const forcedFlags = await forcedFlagsFor(req, () => resolveDebugAuthorization(config, async () => (await config.adapters.getOfflineData(spaceId, environment, revision))?.schema.settings));
 	let outcome;
 	try {
 		const result = await module.runAction({
@@ -192,6 +199,7 @@ var handleActionCall = async (deps) => {
 				environment,
 				revision
 			},
+			...forcedFlags ? { forcedFlags } : {},
 			signal: run.controller.signal,
 			...stream ? {
 				emit: (chunk) => stream.send({

package/dist/modules/actions/types.d.ts

@@ -4,7 +4,7 @@ import { SpaceFunctions } from '../functions/protocol';
 import { KvChangeLifetime } from './runtime/kvChange';
 import { KvListEntry, KvListPut, KvListPutOptions, KvListRange } from './runtime/kvList';
 import { SpaceSigning } from './runtime/signing';
-import { ActionEmailConfig, ActionJobQueue, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionRunStep, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
+import { ActionEmailConfig, ActionJobQueue, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionRunStep, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, Schema, SpaceRevision, SSRServerConfig, SSRUser } from '@plitzi/sdk-shared';
 /** Resolved secret material, as the connector engine already models it. */
 export type ActionCredential = Record<string, string>;
 /**
@@ -120,6 +120,11 @@ export type ActionLookups = {
      * asked when a run names a task the deployment does not have, or a request a path under `/api/`.
      */
     getFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<SpaceFunctions | undefined>;
+    /**
+     * The feature flags the space declares as of that revision, for a flow that reads `{{ flags.<name> }}`. Only asked
+     * for a run whose document names `flags` at all. Absent, such a flow sees no flags — and the server says so.
+     */
+    getFlags?: (spaceId: number, at?: SpaceRevision) => Promise<Schema['flags']>;
 };
 /**
  * The only door a task has to the outside world.
@@ -235,6 +240,8 @@ export type ActionTaskRegistry = {
 /** What a deployment hands to `createServer` under `actions`. Absent → the module is never constructed. */
 export type ActionsConfig = {
     lookups: ActionLookups;
+    /** The flags this deployment decides — the server's own `flags`, which a flow sees the way a page does. */
+    flags?: SSRServerConfig['flags'];
     /** Code of the server's own, and the sandbox for the spaces' — see `FunctionsConfig`. */
     functions?: FunctionsConfig;
     /** Ceilings a per-action document may tighten but never exceed. */
@@ -386,6 +393,12 @@ export type ActionRunRequest = {
      * miniature.
      */
     at?: SpaceRevision;
+    /**
+     * The flags a tester forced, for a run started from a page allowed to debug — the same `qa` layer the page was
+     * drawn with, so a forced feature is not on in the page and off in the flow behind it. Never what the SDK's own
+     * `flags` say: those are the browser's claim, and a flow does not take a claim as a fact.
+     */
+    forcedFlags?: Record<string, boolean>;
     emit?: (chunk: unknown) => void;
     /** Reports each step as it settles, for a caller watching the run happen. Absent for a plain request/response. */
     onNode?: (id: string, status: InteractionNodeStatus) => void;

package/dist/modules/connectors/engine.js

@@ -1,7 +1,7 @@
 import { fetchOutbound } from "../../helpers/outboundGuard.js";
 import { getByPath } from "./getByPath.js";
-import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
+import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/connectors/engine.ts
 var DEFAULT_LIMIT = 10;
 /** Only scalars can become a URL fragment, a header or a record key. Anything else is treated as absent. */

package/dist/modules/functions/capabilities.js

@@ -1,3 +1,4 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/modules/functions/capabilities.ts
 var TEXTUAL = /^(text\/|application\/([\w.+-]*\+)?(json|xml|javascript|x-www-form-urlencoded))/i;
 /** A body as the wire carries it: as text when its type says it is text, base64 otherwise. */
@@ -42,7 +43,6 @@ var numberArg = (value, what) => {
 	return value;
 };
 var optionalNumber = (value, what) => value === void 0 || value === null ? void 0 : numberArg(value, what);
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var headerPairsOf = (value) => Array.isArray(value) ? value.flatMap((pair) => Array.isArray(pair) && typeof pair[0] === "string" && typeof pair[1] === "string" ? [[pair[0], pair[1]]] : []) : [];
 var wireBodyFrom = (value) => {
 	const body = isRecord(value) ? value : void 0;

package/dist/modules/functions/load.js

@@ -1,7 +1,8 @@
 import { buildFunctions } from "./build.js";
 import { readFunctionsSource } from "@plitzi/sdk-shared/actions";
-import { fileURLToPath } from "node:url";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 import { readFile, readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 //#region src/modules/functions/load.ts
 var nodeReader = {
 	list: async (dir) => (await readdir(dir, { withFileTypes: true })).map((entry) => ({
@@ -10,7 +11,6 @@ var nodeReader = {
 	})),
 	read: (file) => readFile(file, "utf8")
 };
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a module's default export has a definition's shape: what a server can register without surprises. */
 var isFunctionsDefinition = (value) => {
 	if (!isRecord(value)) return false;

package/dist/modules/functions/manifest.js

@@ -1,4 +1,5 @@
 import { taskName, taskNameProblem } from "../actions/tasks/registry.js";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/modules/functions/manifest.ts
 var ROUTE_METHODS = [
 	"GET",
@@ -24,7 +25,6 @@ var parseRouteKey = (key) => {
 	};
 };
 var HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var stringOf = (value) => typeof value === "string" ? value : void 0;
 var optionsOf = (value) => Array.isArray(value) ? value.flatMap((option) => {
 	const label = isRecord(option) ? stringOf(option.label) : void 0;

package/dist/modules/functions/runner/messages.js

@@ -1,3 +1,4 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 //#region src/modules/functions/runner/messages.ts
 var ENVIRONMENTS = {
 	production: true,
@@ -6,7 +7,6 @@ var ENVIRONMENTS = {
 	main: true
 };
 var isEnvironment = (value) => typeof value === "string" && Object.hasOwn(ENVIRONMENTS, value);
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var parse = (data) => {
 	try {
 		const value = JSON.parse(data);

package/dist/modules/images/allowlist.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a host is one a picture may come from: named exactly (`images.example.com`), or under a wildcard
+ * (`*.example.com` — its subdomains, not `example.com` itself, which is named on its own when it is meant).
+ */
+export declare const isAllowedImageHost: (domains: readonly string[], hostname: string) => boolean;

package/dist/modules/images/allowlist.js

@@ -0,0 +1,18 @@
+//#region src/modules/images/allowlist.ts
+/**
+* Whether a host is one a picture may come from: named exactly (`images.example.com`), or under a wildcard
+* (`*.example.com` — its subdomains, not `example.com` itself, which is named on its own when it is meant).
+*/
+var isAllowedImageHost = (domains, hostname) => {
+	const host = hostname.toLowerCase().replace(/\.$/, "");
+	return domains.some((entry) => {
+		const domain = entry.toLowerCase().trim();
+		if (domain.startsWith("*.")) {
+			const parent = domain.slice(2);
+			return host.endsWith(`.${parent}`);
+		}
+		return host === domain;
+	});
+};
+//#endregion
+export { isAllowedImageHost };

package/dist/modules/images/imageProxy.d.ts

@@ -0,0 +1,36 @@
+import { ImageTransform } from './transform';
+import { HostLookup } from '../../helpers/outboundGuard';
+/** What a request for a picture asked: the picture, the width, and what the browser takes (its `Accept`). */
+export type ImageRequest = {
+    url?: string;
+    width?: string;
+    accept?: string;
+};
+export type ImageAnswer = {
+    status: number;
+    headers: Record<string, string>;
+    body: Buffer | string;
+};
+export type ImageProxyOptions = {
+    domains: readonly string[];
+    cacheDir: string;
+    /** The transport every hop goes through. */
+    fetch: typeof fetch;
+    /** `sharp`'s, when it is installed; without one a picture is passed through, cached. */
+    transform?: ImageTransform;
+    lookup?: HostLookup;
+    now?: () => number;
+};
+/**
+ * Another site's picture, at a width this server makes, in the best format the browser takes.
+ *
+ * Each original is fetched once and kept, and each size of it is made once from the kept original and kept too: a page
+ * asking for eight widths in two formats costs one download and sixteen resizes, ever — not one of each per request,
+ * nor again a week later. Past a week the kept files still answer at once while the other site is asked, with the
+ * original's `ETag` / `Last-Modified`, whether it changed; only a changed original makes its sizes again.
+ *
+ * Only from the hosts the deployment allows, with every hop (redirects included) held to the allowlist and to the
+ * rule every outbound request is: a picture endpoint that fetched anything would be a way to make this server read
+ * its own network.
+ */
+export declare const createImageProxy: (options: ImageProxyOptions) => ((request: ImageRequest) => Promise<ImageAnswer>);