@plitzi/sdk-server 0.37.9 → 0.38.1

package/dist/modules/images/imageProxy.js

@@ -0,0 +1,273 @@
+import { fetchOutbound } from "../../helpers/outboundGuard.js";
+import { writeFileAtomic } from "../../helpers/atomicFile.js";
+import { isAllowedImageHost } from "./allowlist.js";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { IMAGE_WIDTHS, isImageWidth } from "@plitzi/sdk-shared/helpers/images";
+//#region src/modules/images/imageProxy.ts
+/** The formats a picture may arrive in, as the file extension it is kept under. SVG is not one: served from this
+*  origin, an SVG is a document that can run script. */
+var SOURCE_TYPES = {
+	"image/jpeg": "jpg",
+	"image/png": "png",
+	"image/gif": "gif",
+	"image/webp": "webp",
+	"image/avif": "avif"
+};
+var TYPE_OF_EXTENSION = Object.fromEntries(Object.entries(SOURCE_TYPES).map(([type, extension]) => [extension, type]));
+/** The largest picture fetched, and how long fetching it may take. */
+var MAX_SOURCE_BYTES = 15728640;
+var FETCH_TIMEOUT_MS = 1e4;
+/**
+* How long a kept original answers without asking the other site again. Past it the kept files still answer — at once —
+* while the original is asked for with its `ETag` / `Last-Modified`: unchanged, nothing is fetched or resized again.
+*/
+var FRESH_MS = 6048e5;
+/** How long a picture that could not be fetched is not asked for again: a broken address is not a reason to keep asking. */
+var FAILED_MS = 3e5;
+var CACHE_CONTROL = "public, max-age=86400, stale-while-revalidate=604800";
+var HostNotAllowed = class extends Error {};
+var answer = (status, message) => ({
+	status,
+	headers: {
+		"Content-Type": "text/plain; charset=utf-8",
+		"Cache-Control": "no-store"
+	},
+	body: message
+});
+/** What a request is answered with when it gets no picture, carried up from wherever it was decided. */
+var Refusal = class extends Error {
+	answer;
+	constructor(answer) {
+		super(String(answer.body));
+		this.answer = answer;
+	}
+};
+var refuse = (status, message) => new Refusal(answer(status, message));
+/** One of each at a time: a second request for what is being made waits for the first. */
+var oneAtATime = () => {
+	const running = /* @__PURE__ */ new Map();
+	return (key, make) => {
+		const known = running.get(key);
+		if (known) return known;
+		const made = make().finally(() => running.delete(key));
+		running.set(key, made);
+		return made;
+	};
+};
+/** What the browser takes, best first; `original` when it takes neither modern format. */
+var negotiate = (accept) => {
+	if (accept.includes("image/avif")) return "avif";
+	return accept.includes("image/webp") ? "webp" : "original";
+};
+var FORMATS = [
+	"avif",
+	"webp",
+	"original"
+];
+var isOriginalMeta = (value) => typeof value === "object" && value !== null && "type" in value && typeof value.type === "string" && "checkedAt" in value && typeof value.checkedAt === "number" && "version" in value && typeof value.version === "string";
+var sha = (text) => createHash("sha256").update(text).digest("hex");
+/**
+* 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.
+*/
+var createImageProxy = (options) => {
+	const { domains, cacheDir, transform, lookup, now = Date.now } = options;
+	const failedUntil = /* @__PURE__ */ new Map();
+	const revalidating = oneAtATime();
+	const fetchingOriginal = oneAtATime();
+	const resizing = oneAtATime();
+	const allowedFetch = (input, init) => {
+		const target = new URL(input instanceof Request ? input.url : String(input));
+		if (!isAllowedImageHost(domains, target.hostname)) return Promise.reject(new HostNotAllowed(target.hostname));
+		return options.fetch(input, init);
+	};
+	const originalFile = (urlKey, extension) => path.join(cacheDir, "originals", urlKey.slice(0, 2), `${urlKey}.${extension}`);
+	const variantKey = (urlKey, version, width, format) => sha(`${urlKey}\n${version}\n${String(width)}\n${format}`);
+	const variantFile = (key, extension) => path.join(cacheDir, key.slice(0, 2), `${key}.${extension}`);
+	const write = async (file, data) => {
+		await fs.mkdir(path.dirname(file), { recursive: true });
+		await writeFileAtomic(file, data);
+	};
+	const readMeta = async (urlKey) => {
+		try {
+			const parsed = JSON.parse(await fs.readFile(originalFile(urlKey, "json"), "utf-8"));
+			return isOriginalMeta(parsed) ? parsed : void 0;
+		} catch {
+			return;
+		}
+	};
+	const readFile = async (file) => {
+		try {
+			return await fs.readFile(file);
+		} catch {
+			return;
+		}
+	};
+	/** A size already made, in whichever type it came out as. */
+	const keptVariant = async (key) => {
+		for (const [extension, type] of Object.entries(TYPE_OF_EXTENSION)) {
+			const body = await readFile(variantFile(key, extension));
+			if (body) return {
+				body,
+				type
+			};
+		}
+	};
+	/** The original from the other site — asked conditionally when one is kept. Throws an answer to give back. */
+	const fetchOriginal = async (source, kept) => {
+		const headers = { accept: "image/avif,image/webp,image/*" };
+		if (kept?.etag) headers["if-none-match"] = kept.etag;
+		if (kept?.lastModified) headers["if-modified-since"] = kept.lastModified;
+		let response;
+		try {
+			response = await fetchOutbound(allowedFetch, source, {
+				headers,
+				signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+			}, lookup);
+		} catch (error) {
+			throw error instanceof HostNotAllowed ? refuse(403, `The picture moved to ${error.message}, which is not an allowed host.`) : refuse(502, "The picture could not be fetched.");
+		}
+		if (kept && response.status === 304) {
+			await response.body?.cancel();
+			return { changed: false };
+		}
+		const type = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+		if (!response.ok || !Object.hasOwn(SOURCE_TYPES, type)) {
+			await response.body?.cancel();
+			throw refuse(502, response.ok ? `Not a picture this endpoint serves (${type || "no type"}).` : "The picture could not be fetched.");
+		}
+		if (Number(response.headers.get("content-length") ?? 0) > MAX_SOURCE_BYTES) {
+			await response.body?.cancel();
+			throw refuse(413, "The picture is too large.");
+		}
+		const body = Buffer.from(await response.arrayBuffer());
+		if (body.length > MAX_SOURCE_BYTES) throw refuse(413, "The picture is too large.");
+		const etag = response.headers.get("etag");
+		const lastModified = response.headers.get("last-modified");
+		return {
+			changed: true,
+			body,
+			meta: {
+				type,
+				...etag ? { etag } : {},
+				...lastModified ? { lastModified } : {},
+				checkedAt: now(),
+				version: sha(body).slice(0, 16)
+			}
+		};
+	};
+	/** Keeps a new original and its meta, and drops the sizes made from the one it replaces. */
+	const keepOriginal = async (urlKey, fetched, previous) => {
+		await write(originalFile(urlKey, SOURCE_TYPES[fetched.meta.type]), fetched.body);
+		await write(originalFile(urlKey, "json"), JSON.stringify(fetched.meta));
+		if (!previous || previous.version === fetched.meta.version) return;
+		if (previous.type !== fetched.meta.type) await fs.rm(originalFile(urlKey, SOURCE_TYPES[previous.type]), { force: true });
+		const stale = IMAGE_WIDTHS.flatMap((width) => FORMATS.flatMap((format) => {
+			const key = variantKey(urlKey, previous.version, width, format);
+			return Object.keys(TYPE_OF_EXTENSION).map((extension) => variantFile(key, extension));
+		}));
+		await Promise.all(stale.map((file) => fs.rm(file, { force: true })));
+	};
+	/** Asks the other site whether a kept original changed: unchanged costs a header, changed makes new sizes later. */
+	const revalidate = (urlKey, source, meta) => revalidating(urlKey, async () => {
+		try {
+			const fetched = await fetchOriginal(source, meta);
+			if (fetched.changed) await keepOriginal(urlKey, fetched, meta);
+			else await write(originalFile(urlKey, "json"), JSON.stringify({
+				...meta,
+				checkedAt: now()
+			}));
+		} catch {}
+	});
+	/** The original, kept or fetched: its bytes and its meta. Throws an answer to give back. */
+	const original = async (urlKey, source) => {
+		const meta = await readMeta(urlKey);
+		const body = meta && await readFile(originalFile(urlKey, SOURCE_TYPES[meta.type]));
+		if (meta && body) return {
+			body,
+			meta
+		};
+		if ((failedUntil.get(urlKey) ?? 0) > now()) throw refuse(502, "The picture could not be fetched a moment ago; it is asked for again in a few minutes.");
+		return fetchingOriginal(urlKey, async () => {
+			try {
+				const fetched = await fetchOriginal(source);
+				if (!fetched.changed) throw refuse(502, "The picture could not be fetched.");
+				await keepOriginal(urlKey, fetched, meta);
+				return fetched;
+			} catch (error) {
+				failedUntil.set(urlKey, now() + FAILED_MS);
+				throw error;
+			}
+		});
+	};
+	/** One size of the original, made once and kept. A GIF is passed through: resizing one keeps its first frame. */
+	const makeVariant = (key, source, width, format) => resizing(key, async () => {
+		let body = source.body;
+		let type = source.meta.type;
+		if (transform && type !== "image/gif") try {
+			body = await transform(source.body, width, format);
+			type = format === "original" ? type : `image/${format}`;
+		} catch {
+			body = source.body;
+			type = source.meta.type;
+		}
+		await write(variantFile(key, SOURCE_TYPES[type]), body);
+		return {
+			body,
+			type
+		};
+	});
+	return async ({ url, width, accept = "" }) => {
+		let source;
+		try {
+			source = new URL(url ?? "");
+		} catch {
+			return answer(400, "`url` is the picture’s address.");
+		}
+		if (source.protocol !== "https:" && source.protocol !== "http:") return answer(400, "`url` is the picture’s web address.");
+		const requested = Number(width);
+		if (!isImageWidth(requested)) return answer(400, `\`w\` is one of ${IMAGE_WIDTHS.join(", ")}.`);
+		if (!isAllowedImageHost(domains, source.hostname)) return answer(403, `${source.hostname} is not one of the hosts this server takes pictures from.`);
+		const format = transform ? negotiate(accept) : "original";
+		const urlKey = sha(source.href);
+		try {
+			const kept = await readMeta(urlKey);
+			if (kept && now() - kept.checkedAt >= FRESH_MS) revalidate(urlKey, source, kept);
+			const made = kept && await keptVariant(variantKey(urlKey, kept.version, requested, format));
+			if (made) return {
+				status: 200,
+				headers: headersOf(made.type),
+				body: made.body
+			};
+			const from = await original(urlKey, source);
+			const variant = await makeVariant(variantKey(urlKey, from.meta.version, requested, format), from, requested, format);
+			return {
+				status: 200,
+				headers: headersOf(variant.type),
+				body: variant.body
+			};
+		} catch (error) {
+			if (error instanceof Refusal) return error.answer;
+			throw error;
+		}
+	};
+};
+var headersOf = (type) => ({
+	"Content-Type": type,
+	"Cache-Control": CACHE_CONTROL,
+	Vary: "Accept",
+	"X-Content-Type-Options": "nosniff",
+	"Content-Security-Policy": "default-src 'none'; sandbox"
+});
+//#endregion
+export { createImageProxy };

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Resizing and re-encoding, by `sharp` when the deployment installed it. An optional peer, as `isolated-vm` is: a
+ * native module this package does not impose on a server that resizes nothing.
+ */
+/** The output a picture is encoded in: what the browser said it takes, or the picture's own format. */
+export type ImageFormat = 'avif' | 'webp' | 'original';
+/** Resizes `input` to `width` (never larger than it is) in `format`. */
+export type ImageTransform = (input: Buffer, width: number, format: ImageFormat) => Promise<Buffer>;
+/** The transform `sharp` makes, or `undefined` when it is not installed. */
+export declare const loadSharpTransform: () => Promise<ImageTransform | undefined>;

package/dist/modules/images/transform.js

@@ -0,0 +1,28 @@
+//#region src/modules/images/transform.ts
+var isSharpFactory = (value) => typeof value === "function";
+/** The transform `sharp` makes, or `undefined` when it is not installed. */
+var loadSharpTransform = async () => {
+	const name = "sharp";
+	let loaded;
+	try {
+		loaded = await import(
+			/* @vite-ignore */
+			name
+);
+	} catch {
+		return;
+	}
+	const factory = typeof loaded === "object" && loaded !== null && "default" in loaded ? loaded.default : loaded;
+	if (!isSharpFactory(factory)) return;
+	return async (input, width, format) => {
+		const pipeline = factory(input).rotate().resize({
+			width,
+			withoutEnlargement: true
+		});
+		if (format === "avif") return pipeline.avif({ quality: 55 }).toBuffer();
+		if (format === "webp") return pipeline.webp({ quality: 75 }).toBuffer();
+		return pipeline.toBuffer();
+	};
+};
+//#endregion
+export { loadSharpTransform };

package/dist/modules/images/transform.test.d.ts

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

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

@@ -3,7 +3,7 @@ import { ActionLookups } from '../actions/types';
 import { ConnectorLookups } from '../connectors/resolver';
 import { SSRAdapters } from '@plitzi/sdk-shared';
 /**
- * `getRscData`, built from the producers the server was already given — connectors, actions, or both.
+ * `getRscData`, built from the producers the server was already given — connectors, actions, its own static files.
  *
  * Every deployment that served server-driven elements wrote this same adapter: await the render payload, check the
  * schema opted into RSC, then hand `resolveRscData` a resolver over the lookups — all of which are this package's
@@ -17,9 +17,14 @@ import { SSRAdapters } from '@plitzi/sdk-shared';
  *
  * A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
  */
-export declare const connectorRscData: (lookups?: ConnectorLookups, actions?: {
-    lookups: ActionLookups;
-    module: ActionsModule;
-}, 
-/** The deployment's per-element ceiling, when it set one. `resolveRscData` decides the default. */
-elementTimeoutMs?: number) => NonNullable<SSRAdapters["getRscData"]>;
+export declare const connectorRscData: ({ connectors, actions, publicDir, elementTimeoutMs }: {
+    connectors?: ConnectorLookups;
+    actions?: {
+        lookups: ActionLookups;
+        module: ActionsModule;
+    };
+    /** Where the server's static files are: a provider whose `query` is one of them is read from disk. */
+    publicDir?: string;
+    /** The deployment's per-element ceiling, when it set one. `resolveRscData` decides the default. */
+    elementTimeoutMs?: number;
+}) => NonNullable<SSRAdapters["getRscData"]>;

package/dist/modules/rsc/connectorRscData.js

@@ -1,9 +1,10 @@
 import { createActionResolver } from "../actions/runtime/renderResolver.js";
 import { createConnectorResolver } from "../connectors/resolver.js";
+import { publicFileResolver } from "./publicFileResolver.js";
 import { resolveRscData } from "./resolveRscData.js";
 //#region src/modules/rsc/connectorRscData.ts
 /**
-* `getRscData`, built from the producers the server was already given — connectors, actions, or both.
+* `getRscData`, built from the producers the server was already given — connectors, actions, its own static files.
 *
 * Every deployment that served server-driven elements wrote this same adapter: await the render payload, check the
 * schema opted into RSC, then hand `resolveRscData` a resolver over the lookups — all of which are this package's
@@ -17,22 +18,24 @@ import { resolveRscData } from "./resolveRscData.js";
 *
 * A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
 */
-var connectorRscData = (lookups, actions, elementTimeoutMs) => {
-	const resolveConnector = lookups ? createConnectorResolver(lookups) : void 0;
+var connectorRscData = ({ connectors, actions, publicDir, elementTimeoutMs }) => {
+	const resolveConnector = connectors ? createConnectorResolver(connectors) : void 0;
 	const resolveAction = actions ? createActionResolver(actions.lookups, actions.module) : void 0;
+	const resolvePublicFile = publicDir ? publicFileResolver(publicDir) : void 0;
 	/**
 	* An element names ONE producer, and which one decides how its data is fetched.
 	*
-	* A connector is the declarative read and stays the default; an action is the read a manifest cannot express.
-	* Checked in that order so an element carrying both — a connector element an author later pointed at an action —
-	* keeps resolving the way its page already renders, instead of silently changing under them.
+	* A connector is the declarative read and stays the default; an action is the read a manifest cannot express; a
+	* file of the server's own is the read with no backend at all. Checked in that order so an element carrying more
+	* than one keeps resolving the way its page already renders, instead of silently changing under them.
 	*/
 	const resolveElement = async (context) => {
 		const attributes = context.element.attributes;
 		if (attributes.connector) return resolveConnector ? resolveConnector(context) : void 0;
-		return attributes.action && resolveAction ? resolveAction(context) : void 0;
+		if (attributes.action) return resolveAction ? resolveAction(context) : void 0;
+		return resolvePublicFile ? resolvePublicFile(context) : void 0;
 	};
-	return async ({ req, spaceId, environment, user, ids, loadOfflineData }) => {
+	return async ({ req, spaceId, environment, user, ids, loadOfflineData, flagOverrides }) => {
 		const offlineData = await loadOfflineData();
 		if (!offlineData?.schema.rsc?.enabled) return {};
 		return resolveRscData({
@@ -43,6 +46,7 @@ var connectorRscData = (lookups, actions, elementTimeoutMs) => {
 			user,
 			ids,
 			resolveElement,
+			...flagOverrides ? { flagOverrides } : {},
 			...elementTimeoutMs === void 0 ? {} : { timeoutMs: elementTimeoutMs }
 		});
 	};

package/dist/modules/rsc/handler.js

@@ -1,9 +1,11 @@
 import { serverLog } from "../../helpers/serverLog.js";
+import { requestFlagOverrides } from "../../helpers/flagOverrides.js";
 import { resolveDebugAuthorization } from "../../helpers/debugAuthorization.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildRscCacheKey } from "../../helpers/cache/keys.js";
 import { readDraftToken } from "../../core/previewToken.js";
 import { createOfflineDataLoader } from "../../helpers/offlineDataLoader.js";
+import { forcedFlagsFromCookies } from "@plitzi/sdk-shared/flags";
 //#region src/modules/rsc/handler.ts
 /** Bounds the reflected location: it only ever selects one of this space's own pages, but it is still input. */
 var MAX_PAGE_LOCATION = 2048;
@@ -93,10 +95,16 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 	* refresh that arrives a second after it expired is still part of the same preview.
 	*/
 	const previewing = readDraftToken(req) !== void 0;
+	/**
+	* A tester forcing flags from the dev tools sees data for features nobody else has on — and must never be handed a
+	* slice resolved without them. Their refreshes go around the cache both ways, like a draft's.
+	*/
+	const forcingFlags = Object.keys(forcedFlagsFromCookies(req.headers.cookie, req.headers.host)).length > 0;
+	const uncached = previewing || forcingFlags;
 	const ttlMs = config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc;
 	const isAuthenticated = !!req.ctx.user;
-	const cacheControl = environment === "main" || previewing ? "no-store" : isAuthenticated ? `private, max-age=${Math.floor(ttlMs / 1e3)}` : `public, max-age=${Math.floor(ttlMs / 1e3)}`;
-	const cacheKey = environment !== "main" && !previewing ? buildRscCacheKey(spaceId, environment, revision, req.ctx.user?.id, idsParam, req) : void 0;
+	const cacheControl = environment === "main" || uncached ? "no-store" : isAuthenticated ? `private, max-age=${Math.floor(ttlMs / 1e3)}` : `public, max-age=${Math.floor(ttlMs / 1e3)}`;
+	const cacheKey = environment !== "main" && !uncached ? buildRscCacheKey(spaceId, environment, revision, req.ctx.user?.id, idsParam, req) : void 0;
 	const cached = cacheKey ? cache?.get(cacheKey) : void 0;
 	if (!previewing) await meterRsc(req, config, spaceId, environment, revision, !!cached);
 	if (cached) {
@@ -107,6 +115,11 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 		return;
 	}
 	const loadOfflineData = createOfflineDataLoader(() => config.adapters.getOfflineData(spaceId, environment, revision));
+	const settings = async () => (await loadOfflineData())?.schema.settings;
+	const flagOverrides = await requestFlagOverrides(config, req, {
+		spaceId,
+		environment
+	}, () => resolveDebugAuthorization(config, settings));
 	let rscData;
 	try {
 		rscData = await config.adapters.getRscData({
@@ -116,7 +129,8 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 			revision,
 			user: req.ctx.user,
 			ids,
-			loadOfflineData
+			loadOfflineData,
+			flagOverrides
 		});
 	} catch (err) {
 		serverLog.error("RSC", "getRscData error", err);
@@ -124,7 +138,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 		res.send(JSON.stringify({ error: "RSC data fetch failed" }));
 		return;
 	}
-	const actionRuns = Boolean(req.ctx.actionRuns?.length) && await resolveDebugAuthorization(config, async () => (await loadOfflineData())?.schema.settings) ? req.ctx.actionRuns : void 0;
+	const actionRuns = Boolean(req.ctx.actionRuns?.length) && await resolveDebugAuthorization(config, settings) ? req.ctx.actionRuns : void 0;
 	const payload = {
 		version: 1,
 		transport: "json",

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

@@ -0,0 +1,13 @@
+import { RscElementResolver } from './resolveRscData';
+/**
+ * A server provider whose `query` is a file this server serves from `publicDir` — `/data/home.json` — read from disk
+ * and handed to the render, so the page arrives with the section in it.
+ *
+ * A project with no backend keeps its data in `public/data/*.json`, and an `apiContainer` fetching it from the browser
+ * leaves the server-rendered page without those sections: a flash of nothing, no content for a crawler, and no
+ * anchor in place for `/#section` to land on. Read here, it is the same bytes the browser would have fetched.
+ *
+ * Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
+ * in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
+ */
+export declare const publicFileResolver: (publicDir: string) => RscElementResolver;

package/dist/modules/rsc/publicFileResolver.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/modules/rsc/publicFileResolver.ts
+/**
+* A server provider whose `query` is a file this server serves from `publicDir` — `/data/home.json` — read from disk
+* and handed to the render, so the page arrives with the section in it.
+*
+* A project with no backend keeps its data in `public/data/*.json`, and an `apiContainer` fetching it from the browser
+* leaves the server-rendered page without those sections: a flash of nothing, no content for a crawler, and no
+* anchor in place for `/#section` to land on. Read here, it is the same bytes the browser would have fetched.
+*
+* Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
+* in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
+*/
+var publicFileResolver = (publicDir) => {
+	const root = path.resolve(publicDir);
+	return async ({ element, signal }) => {
+		const query = element.attributes.query;
+		if (typeof query !== "string" || !query.startsWith("/") || query.startsWith("//") || query.includes("{{")) return;
+		let pathname;
+		try {
+			pathname = decodeURIComponent(query.split(/[?#]/)[0]);
+		} catch {
+			return;
+		}
+		const file = path.resolve(root, `.${pathname}`);
+		if (!file.startsWith(`${root}${path.sep}`)) return;
+		try {
+			return JSON.parse(await readFile(file, {
+				encoding: "utf8",
+				signal
+			}));
+		} catch {
+			return null;
+		}
+	};
+};
+//#endregion
+export { publicFileResolver };

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

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

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

@@ -1,4 +1,4 @@
-import { Element, Environment, Schema, SSRRequest, SSRRscData, SSRUser } from '@plitzi/sdk-shared';
+import { Element, Environment, FlagOverrides, Schema, SSRRequest, SSRRscData, SSRUser } from '@plitzi/sdk-shared';
 /** Everything an element resolver needs to turn one `runtime: 'server'` element into its data slice. */
 export type RscResolveContext = {
     element: Element;
@@ -30,6 +30,8 @@ export type ResolveRscDataOptions = {
     /** Restricts resolution to these element ids (partial refresh). Undefined resolves every server element. */
     ids?: string[];
     resolveElement: RscElementResolver;
+    /** The layers above the space that decide its flags for this request — see `SSRRscContext.flagOverrides`. */
+    flagOverrides?: FlagOverrides;
     /**
      * Per-element budget: one slow provider must not hold the whole payload, and must not go on working once it
      * has. It is the PAGE's ceiling and it wins over the producer's own — an action allowed ten seconds of its own
@@ -45,4 +47,4 @@ export type ResolveRscDataOptions = {
  * and the route params are what the browser will see. Each `runtime: 'server'` element resolves independently:
  * a provider that fails or hangs costs its own slice and nothing else.
  */
-export declare const resolveRscData: ({ schema, req, spaceId, environment, user, ids, resolveElement, timeoutMs }: ResolveRscDataOptions) => Promise<SSRRscData>;
+export declare const resolveRscData: ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs }: ResolveRscDataOptions) => Promise<SSRRscData>;

package/dist/modules/rsc/resolveRscData.js

@@ -1,5 +1,6 @@
 import { serverLog } from "../../helpers/serverLog.js";
 import { matchRscPage } from "./matchRscPage.js";
+import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
 import { collectServerElements } from "@plitzi/sdk-shared/schema/serverElements";
 //#region src/modules/rsc/resolveRscData.ts
 var DEFAULT_ELEMENT_TIMEOUT_MS = 5e3;
@@ -31,12 +32,19 @@ var withBudget = async (run, timeoutMs, label) => {
 * and the route params are what the browser will see. Each `runtime: 'server'` element resolves independently:
 * a provider that fails or hangs costs its own slice and nothing else.
 */
-var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, resolveElement, timeoutMs = DEFAULT_ELEMENT_TIMEOUT_MS }) => {
+var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, resolveElement, flagOverrides, timeoutMs = DEFAULT_ELEMENT_TIMEOUT_MS }) => {
 	if (schema.rsc?.enabled === false) return {};
 	const match = matchRscPage(schema, req.path, user);
 	if (!match) return { serverData: {} };
 	const { pageId, routeParams } = match;
-	const targets = collectServerElements(schema, pageId, ids);
+	const flags = flagValues(resolveFlags(schema.flags, {
+		environment,
+		hostname: req.hostname,
+		routeParams,
+		queryParams: req.query,
+		user: flagUserFromSSR(user)
+	}, flagOverrides));
+	const targets = collectServerElements(schema, pageId, ids, flags);
 	if (targets.length === 0) return { serverData: {} };
 	return { serverData: (await Promise.allSettled(targets.map(async (element) => ({
 		id: element.id,

package/dist/modules/runtime/bundle.js

@@ -1,8 +1,9 @@
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
 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 { pathToFileURL } from "node:url";
 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. */
@@ -50,7 +51,6 @@ var packRuntime = async (entry) => {
 	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;

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

@@ -15,6 +15,10 @@ export type ComponentProps = {
     theme?: Theme;
     /** The kept state the first paint depends on (`settings.paintedState`), from the visitor's cookie. */
     state?: Record<string, unknown>;
+    /** The flags this deployment decides (`config.flags`). */
+    serverFlags?: Record<string, boolean>;
+    /** The flags a tester forced, for a page allowed to debug. See `prepareRender`. */
+    forcedFlags?: Record<string, boolean>;
 };
-declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, debugMode, overQuota, theme, state }: ComponentProps) => import('react').JSX.Element;
+declare const Component: ({ server, renderMode, previewMode, offlineData, environment, plugins, ssrResult, sdkDevToolsStylePath, debugMode, overQuota, theme, state, serverFlags, forcedFlags }: 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, overQuota, theme, state }) => {
+var Component = ({ server, renderMode = "raw", previewMode = true, offlineData, environment = "main", plugins, ssrResult, sdkDevToolsStylePath, debugMode = false, overQuota, theme, state, serverFlags, forcedFlags }) => {
 	const serverWithResult = {
 		...server,
 		ssr: {
@@ -21,6 +21,8 @@ var Component = ({ server, renderMode = "raw", previewMode = true, offlineData,
 		...overQuota === void 0 ? {} : { overQuota },
 		...theme === void 0 ? {} : { theme },
 		...state === void 0 ? {} : { state },
+		...serverFlags === void 0 ? {} : { serverFlags },
+		...forcedFlags === void 0 ? {} : { forcedFlags },
 		children: plugins && Object.keys(plugins).map((key) => /* @__PURE__ */ jsx(PlitziSdk.Plugin, {
 			renderType: key,
 			component: plugins[key].component,