bosia 0.5.13 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.5.13",
+	"version": "0.6.1",
 	"type": "module",
 	"description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing inspired by SvelteKit. No Node.js, no Vite, no adapters.",
 	"keywords": [
@@ -33,6 +33,7 @@
 	"exports": {
 		".": "./src/lib/index.ts",
 		"./client": "./src/lib/client.ts",
+		"./server": "./src/lib/server.ts",
 		"./plugins/server-timing": "./src/core/plugins/server-timing.ts",
 		"./plugins/inspector": "./src/core/plugins/inspector/index.ts"
 	},

package/src/core/cache.ts

@@ -0,0 +1,367 @@
+// ─── Server-side Response Cache ──────────────────────────
+// Skips load() + render() + compression on cache hit. Keyed by URL + identity
+// (cookies/headers from CACHE_KEYS). Invalidated by tag (LoaderDeps.keys),
+// fetch URL (LoaderDeps.urls), or exact/prefix path.
+//
+// See docs/guides/response-cache.md.
+
+import type { Cookies, LoaderDeps } from "./hooks.ts";
+import { dedupKey } from "./dedup.ts";
+
+// ─── Config ──────────────────────────────────────────────
+
+function parseCacheKeys(raw: string | undefined): string[] {
+	const value = raw?.trim();
+	if (value === undefined || value === "") {
+		return ["session", "sid", "auth", "token", "jwt", "Authorization"];
+	}
+	return value
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+function parseMaxEntries(raw: string | undefined): number {
+	if (!raw) return 500;
+	const n = parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 0) return 500;
+	return n;
+}
+
+// `invalidate` / `invalidateAll` are re-exported from the public `bosia`
+// barrel, so this module also evaluates in the browser bundle. Guard every
+// `process.env` read — otherwise hydration throws `ReferenceError: Can't
+// find variable: process` (Safari) the moment the barrel is imported.
+const env: Record<string, string | undefined> =
+	typeof process !== "undefined" && process.env ? process.env : {};
+const isServer = typeof process !== "undefined";
+
+export const CACHE_KEYS: readonly string[] = parseCacheKeys(env.CACHE_KEYS);
+export const CACHE_MAX_ENTRIES = parseMaxEntries(env.CACHE_MAX_ENTRIES);
+export const CACHE_ENABLED = CACHE_MAX_ENTRIES > 0;
+
+if (isServer) {
+	if (CACHE_ENABLED) {
+		console.log(
+			`💾 Response cache: max ${CACHE_MAX_ENTRIES} entries, identity keys [${CACHE_KEYS.join(", ")}]`,
+		);
+	} else {
+		console.log("💾 Response cache: disabled (CACHE_MAX_ENTRIES=0)");
+	}
+}
+
+// ─── Entry shape ─────────────────────────────────────────
+
+type Bytes = Uint8Array<ArrayBuffer>;
+
+export type CacheEntry = {
+	raw: Bytes;
+	gzip: Bytes | null;
+	brotli: Bytes | null;
+	contentType: string;
+	status: number;
+	extraHeaders: Record<string, string>;
+	tags: string[];
+};
+
+// ─── Tiny LRU ────────────────────────────────────────────
+// Uses Map's insertion-order iteration. get() promotes by re-inserting.
+
+class LRU<K, V> {
+	private map = new Map<K, V>();
+	constructor(private cap: number) {}
+	get(key: K): V | undefined {
+		const v = this.map.get(key);
+		if (v === undefined) return undefined;
+		this.map.delete(key);
+		this.map.set(key, v);
+		return v;
+	}
+	set(key: K, value: V): K | undefined {
+		if (this.map.has(key)) this.map.delete(key);
+		this.map.set(key, value);
+		if (this.map.size > this.cap) {
+			const oldest = this.map.keys().next().value as K | undefined;
+			if (oldest !== undefined) {
+				this.map.delete(oldest);
+				return oldest;
+			}
+		}
+		return undefined;
+	}
+	delete(key: K): boolean {
+		return this.map.delete(key);
+	}
+	keys(): IterableIterator<K> {
+		return this.map.keys();
+	}
+	clear(): void {
+		this.map.clear();
+	}
+	get size(): number {
+		return this.map.size;
+	}
+}
+
+// ─── Storage ─────────────────────────────────────────────
+
+const htmlCache = new LRU<string, CacheEntry>(CACHE_MAX_ENTRIES || 1);
+const tagIndex = new Map<string, Set<string>>();
+const pathIndex = new Map<string, Set<string>>(); // pathname → cacheKeys
+
+// ─── Key building ────────────────────────────────────────
+
+/** FNV-1a 32-bit hash. Compact, no dep, collision-tolerant for an identity bucket. */
+function fnv1a(s: string): string {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0).toString(36);
+}
+
+export function computeIdentityHash(req: Request, cookies: Cookies): string {
+	const headers = req.headers;
+	const parts: string[] = [];
+	for (const name of CACHE_KEYS) {
+		const cv = cookies.get(name);
+		if (cv) parts.push(`c:${name}=${cv}`);
+		const hv = headers.get(name);
+		if (hv) parts.push(`h:${name}=${hv}`);
+	}
+	if (parts.length === 0) return "0";
+	parts.sort();
+	return fnv1a(parts.join("&"));
+}
+
+export function computeCacheKey(url: URL, req: Request, cookies: Cookies): string {
+	return `${dedupKey(url)}|i=${computeIdentityHash(req, cookies)}`;
+}
+
+/** Extract pathname portion of a cacheKey for path-based invalidation. */
+function pathOfKey(key: string): string {
+	const qIdx = key.indexOf("?");
+	const pIdx = key.indexOf("|");
+	const end = qIdx === -1 ? pIdx : Math.min(qIdx, pIdx);
+	return end === -1 ? key : key.slice(0, end);
+}
+
+// ─── Tag collection ──────────────────────────────────────
+
+export function collectTags(
+	layoutDeps: (LoaderDeps | null)[] | null,
+	pageDeps: LoaderDeps | null,
+): string[] {
+	const tags = new Set<string>();
+	if (layoutDeps) {
+		for (const deps of layoutDeps) {
+			if (!deps) continue;
+			for (const k of deps.keys) tags.add(`k:${k}`);
+			for (const u of deps.urls) tags.add(`u:${u}`);
+		}
+	}
+	if (pageDeps) {
+		for (const k of pageDeps.keys) tags.add(`k:${k}`);
+		for (const u of pageDeps.urls) tags.add(`u:${u}`);
+	}
+	return [...tags];
+}
+
+// ─── Public-ish: read / write ────────────────────────────
+
+export function cacheGet(key: string): CacheEntry | undefined {
+	if (!CACHE_ENABLED) return undefined;
+	return htmlCache.get(key);
+}
+
+export function cacheSet(key: string, entry: CacheEntry): void {
+	if (!CACHE_ENABLED) return;
+	// Drop any existing entry's index pointers first
+	cacheDeleteKey(key);
+	const evicted = htmlCache.set(key, entry);
+	if (evicted) cacheDeleteIndexOnly(evicted);
+	for (const tag of entry.tags) {
+		let set = tagIndex.get(tag);
+		if (!set) {
+			set = new Set();
+			tagIndex.set(tag, set);
+		}
+		set.add(key);
+	}
+	const path = pathOfKey(key);
+	let pset = pathIndex.get(path);
+	if (!pset) {
+		pset = new Set();
+		pathIndex.set(path, pset);
+	}
+	pset.add(key);
+}
+
+/** Remove a key from htmlCache AND its index pointers. */
+function cacheDeleteKey(key: string): void {
+	const entry = htmlCache.get(key);
+	if (entry) {
+		for (const tag of entry.tags) {
+			const set = tagIndex.get(tag);
+			if (set) {
+				set.delete(key);
+				if (set.size === 0) tagIndex.delete(tag);
+			}
+		}
+	}
+	const path = pathOfKey(key);
+	const pset = pathIndex.get(path);
+	if (pset) {
+		pset.delete(key);
+		if (pset.size === 0) pathIndex.delete(path);
+	}
+	htmlCache.delete(key);
+}
+
+/** Cleanup index pointers for a key after LRU evicted it. */
+function cacheDeleteIndexOnly(key: string): void {
+	for (const set of tagIndex.values()) set.delete(key);
+	for (const [tag, set] of tagIndex) if (set.size === 0) tagIndex.delete(tag);
+	const path = pathOfKey(key);
+	const pset = pathIndex.get(path);
+	if (pset) {
+		pset.delete(key);
+		if (pset.size === 0) pathIndex.delete(path);
+	}
+}
+
+// ─── Compression helpers ─────────────────────────────────
+
+/** Build gzip + brotli copies of body. Sync, runs in microtask. */
+export function buildCompressedVariants(body: Bytes): {
+	gzip: Bytes | null;
+	brotli: Bytes | null;
+} {
+	const COMPRESS_MIN_BYTES = 2048;
+	if (body.length < COMPRESS_MIN_BYTES) return { gzip: null, brotli: null };
+	let gzip: Bytes | null = null;
+	let brotli: Bytes | null = null;
+	try {
+		gzip = Bun.gzipSync(body) as Bytes;
+	} catch {
+		gzip = null;
+	}
+	// brotliCompressSync exists in Bun >= 1.1.5 but is missing from older
+	// @types/bun shipments — cast through any so the call stays loose.
+	const brotliFn = (Bun as unknown as { brotliCompressSync?: (b: Bytes) => Uint8Array })
+		.brotliCompressSync;
+	if (brotliFn) {
+		try {
+			brotli = brotliFn(body) as Bytes;
+		} catch {
+			brotli = null;
+		}
+	}
+	return { gzip, brotli };
+}
+
+/** Concatenate multiple Uint8Array chunks into one buffer. */
+export function concatChunks(chunks: Uint8Array[]): Bytes {
+	let total = 0;
+	for (const c of chunks) total += c.length;
+	const out = new Uint8Array(new ArrayBuffer(total));
+	let off = 0;
+	for (const c of chunks) {
+		out.set(c, off);
+		off += c.length;
+	}
+	return out;
+}
+
+// ─── Serve a cache hit ───────────────────────────────────
+
+export function serveCached(entry: CacheEntry, req: Request): Response {
+	const accept = req.headers.get("accept-encoding") ?? "";
+	const headers: Record<string, string> = {
+		"Content-Type": entry.contentType,
+		Vary: "Accept-Encoding",
+		"X-Bosia-Cache": "HIT",
+		...entry.extraHeaders,
+	};
+	if (entry.brotli && accept.includes("br")) {
+		headers["Content-Encoding"] = "br";
+		return new Response(entry.brotli, { status: entry.status, headers });
+	}
+	if (entry.gzip && accept.includes("gzip")) {
+		headers["Content-Encoding"] = "gzip";
+		return new Response(entry.gzip, { status: entry.status, headers });
+	}
+	return new Response(entry.raw, { status: entry.status, headers });
+}
+
+// ─── Invalidation API ────────────────────────────────────
+
+/**
+ * Evict all cache entries matching `key`.
+ *
+ * - `invalidate("app:user")` → evict entries tagged with depends("app:user")
+ *   (matches the loader's tag list).
+ * - `invalidate("/api/posts")` → evict entries tagged with a fetch URL whose
+ *   path equals `/api/posts`, AND entries whose own path equals `/api/posts`.
+ */
+export function invalidate(key: string): number {
+	if (!CACHE_ENABLED) return 0;
+	let count = 0;
+	const tagKey = key.startsWith("/") ? `u:${key}` : `k:${key}`;
+	const fromTag = tagIndex.get(tagKey);
+	if (fromTag) {
+		// Also collect URL tag matches where the loader fetched an absolute URL
+		// whose pathname == key. Conservative: also match the bare `k:` tag in
+		// case the user uses a key that starts with `/` but isn't a URL.
+		for (const k of [...fromTag]) {
+			cacheDeleteKey(k);
+			count++;
+		}
+	}
+	if (key.startsWith("/")) {
+		// Match absolute URL tags too: any `u:<origin><key>` recorded by trackedFetch.
+		for (const [tag, set] of tagIndex) {
+			if (tag.startsWith("u:") && tag.endsWith(key)) {
+				for (const k of [...set]) {
+					cacheDeleteKey(k);
+					count++;
+				}
+			}
+		}
+		// Match cache entries whose own path equals key
+		const pset = pathIndex.get(key);
+		if (pset) {
+			for (const k of [...pset]) {
+				cacheDeleteKey(k);
+				count++;
+			}
+		}
+	}
+	return count;
+}
+
+/**
+ * Evict every entry whose path starts with `prefix`.
+ * Use for bulk eviction (e.g. `invalidateAll("/products/")`).
+ */
+export function invalidateAll(prefix: string): number {
+	if (!CACHE_ENABLED) return 0;
+	let count = 0;
+	for (const [path, set] of [...pathIndex]) {
+		if (path.startsWith(prefix)) {
+			for (const k of [...set]) {
+				cacheDeleteKey(k);
+				count++;
+			}
+		}
+	}
+	return count;
+}
+
+/** Test-only: clear everything. */
+export function cacheClear(): void {
+	htmlCache.clear();
+	tagIndex.clear();
+	pathIndex.clear();
+}

package/src/core/dev.ts

@@ -247,6 +247,12 @@ const devServer = Bun.serve({
 		const forwardedHeaders = new Headers(req.headers);
 		forwardedHeaders.set("x-forwarded-host", reqUrl.host);
 		forwardedHeaders.set("x-forwarded-proto", reqUrl.protocol.replace(":", ""));
+		// Force inner app to respond uncompressed. Bun's `fetch()` auto-decodes
+		// gzip/br bodies but leaves the original `Content-Encoding` header on
+		// the Response, so passing it through made Safari throw -1015 ("cannot
+		// decode raw data") on every HTML navigation. Identity on the dev wire
+		// is fine — it's localhost.
+		forwardedHeaders.set("accept-encoding", "identity");
 
 		// HMR-driven reloads can land on the proxy before the freshly-respawned
 		// inner has bound APP_PORT. Retry for a few seconds on idempotent HTML

package/src/core/plugins/inspector/index.ts

@@ -20,7 +20,7 @@ export interface InspectorOptions {
 interface ServerError {
 	id: string;
 	ts: number;
-	source: "elysia" | "uncaught" | "rejection";
+	source: "server" | "uncaught" | "rejection";
 	message: string;
 	stack?: string;
 	file?: string;
@@ -147,7 +147,7 @@ function installProcessListeners() {
 function installGlobalReporter() {
 	globalThis.__BOSIA_REPORT_ERROR__ = (e) => {
 		pushServerError({
-			source: e.source ?? "elysia",
+			source: e.source ?? "server",
 			message: e.message,
 			stack: e.stack,
 		});
@@ -282,7 +282,7 @@ export function inspector(options: InspectorOptions = {}): BosiaPlugin | false {
 					chained = chained.onError(({ error }) => {
 						const e = error as Error;
 						pushServerError({
-							source: "elysia",
+							source: "server",
 							message: e?.message ?? String(error),
 							stack: e?.stack,
 						});

package/src/core/renderer.ts

@@ -5,6 +5,16 @@ import { serverRoutes, errorPage } from "bosia:routes";
 import type { RouteMatch } from "./types.ts";
 import type { Cookies, LoaderDeps } from "./hooks.ts";
 import { CSP_ENABLED } from "./csp.ts";
+import {
+	CACHE_ENABLED,
+	buildCompressedVariants,
+	cacheGet,
+	cacheSet,
+	collectTags,
+	computeCacheKey,
+	concatChunks,
+	serveCached,
+} from "./cache.ts";
 import { HttpError, Redirect } from "./errors.ts";
 import { pickErrorPage, type ErrorOrigin } from "./errorMatch.ts";
 import App from "./client/App.svelte";
@@ -503,6 +513,28 @@ export async function renderSSRStream(
 	const { route, params } = match;
 	const nonce = CSP_ENABLED && typeof locals.nonce === "string" ? locals.nonce : undefined;
 
+	// ── Response cache: short-circuit on hit ──
+	// Look up cached HTML before doing anything expensive (metadata, load,
+	// render, compress). Key includes URL + identity hash (cookies/headers
+	// from CACHE_KEYS), so per-user pages stay isolated. Routes opt out via
+	// `export const cache = false`. See cache.ts and docs/guides/response-cache.md.
+	const pageMod: any = await route.pageModule();
+	const cacheBypass = url.searchParams.has("_invalidated");
+	// CSP is incompatible with response cache — the per-request nonce is baked
+	// into the cached HTML but the CSP header is re-derived each request, so a
+	// cached page would ship with a dead nonce and the browser would block its
+	// inline scripts. Operators who turn on CSP_DIRECTIVES forfeit the cache.
+	const cacheable =
+		CACHE_ENABLED && !CSP_ENABLED && pageMod.cache !== false && req.method === "GET";
+	let cacheKey: string | null = null;
+	if (cacheable) {
+		cacheKey = computeCacheKey(url, req, cookies);
+		if (!cacheBypass) {
+			const hit = cacheGet(cacheKey);
+			if (hit) return serveCached(hit, req);
+		}
+	}
+
 	// ── Pre-stream phase: resolve metadata before committing to a 200 ──
 	// Errors here return a proper error response with correct status code.
 	let metadata: Metadata | null = null;
@@ -535,13 +567,11 @@ export async function renderSSRStream(
 	// This ensures HttpError/Redirect from load() can return a proper response before any bytes are sent.
 	const metadataData = metadata?.data ?? null;
 	let data: Awaited<ReturnType<typeof loadRouteData>>;
-	let pageMod: any;
 	let layoutMods: any[];
 
 	try {
-		[data, pageMod, layoutMods] = await Promise.all([
+		[data, layoutMods] = await Promise.all([
 			loadRouteData(url, locals, req, cookies, metadataData, match),
-			route.pageModule(),
 			Promise.all(route.layoutModules.map((l: () => Promise<any>) => l())),
 		]);
 	} catch (err) {
@@ -692,6 +722,28 @@ export async function renderSSRStream(
 		),
 	];
 
+	// ── Response cache: write after chunks built, before stream creation ──
+	// Skip if the handler set cookies — cached response can't reproduce
+	// per-request Set-Cookie headers. Compression runs in a microtask so
+	// the response goes out first.
+	if (cacheable && cacheKey && (cookies as any).outgoing?.length === 0) {
+		const fullBody = concatChunks(chunks);
+		const tags = collectTags(data.layoutDeps ?? null, data.pageDeps ?? null);
+		const keyForWrite = cacheKey;
+		queueMicrotask(() => {
+			const { gzip, brotli } = buildCompressedVariants(fullBody);
+			cacheSet(keyForWrite, {
+				raw: fullBody,
+				gzip,
+				brotli,
+				contentType: "text/html; charset=utf-8",
+				status: 200,
+				extraHeaders: {},
+				tags,
+			});
+		});
+	}
+
 	let i = 0;
 	let cancelled = false;
 	const onAbort = () => {

package/src/core/routeTypes.ts

@@ -84,6 +84,10 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		lines.push(``);
 		lines.push(`export type Params = ${paramsType};`);
 		lines.push(``);
+		lines.push(`/** Set \`export const cache: CacheOption = false;\` in +page(.server).ts`);
+		lines.push(` *  or +server.ts to opt the route out of the server response cache. */`);
+		lines.push(`export type CacheOption = false;`);
+		lines.push(``);
 		lines.push(`type _LoadEvent = Omit<LoadEvent, 'params'> & { params: Params };`);
 		lines.push(`type _MetadataEvent = Omit<MetadataEvent, 'params'> & { params: Params };`);
 		lines.push(`type _RequestEvent = Omit<RequestEvent, 'params'> & { params: Params };`);

package/src/core/server.ts

@@ -25,6 +25,14 @@ import { isDev, compress, isStaticPath } from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
 import { dedup, dedupKey } from "./dedup.ts";
+import {
+	CACHE_ENABLED,
+	buildCompressedVariants,
+	cacheGet,
+	cacheSet,
+	computeCacheKey,
+	serveCached,
+} from "./cache.ts";
 import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import {
 	loadRouteData,
@@ -56,6 +64,27 @@ if (existsSync(hooksPath)) {
 
 // ─── Env Helpers ─────────────────────────────────────────
 
+// Headers that must not be baked into a cache entry. Content-Length is
+// recomputed by Bun, content-encoding/transfer-encoding depend on the chosen
+// variant, and security/CORS/Set-Cookie headers are applied by handleRequest.
+const NON_CACHEABLE_HEADERS = new Set([
+	"content-length",
+	"content-encoding",
+	"transfer-encoding",
+	"content-type",
+	"set-cookie",
+	"vary",
+	"x-bosia-cache",
+]);
+
+function captureCacheableHeaders(headers: Headers): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [k, v] of headers) {
+		if (!NON_CACHEABLE_HEADERS.has(k.toLowerCase())) out[k] = v;
+	}
+	return out;
+}
+
 function splitCsvEnv(key: string): string[] | undefined {
 	return (
 		process.env[key]
@@ -379,7 +408,63 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			}
 
 			event.params = apiMatch.params;
-			return await handler({ request, params: apiMatch.params, url, locals, cookies });
+
+			// ── Response cache for +server.ts GET handlers ──
+			// CSP is skipped because cached responses would ship with a stale
+			// nonce (see renderer.ts for the same gate). The cache key includes
+			// URL + identity so per-user responses stay isolated.
+			const apiCacheable =
+				CACHE_ENABLED && !CSP_ENABLED && (mod as any).cache !== false && method === "GET";
+			let apiCacheKey: string | null = null;
+			if (apiCacheable) {
+				apiCacheKey = computeCacheKey(url, request, cookies);
+				if (!url.searchParams.has("_invalidated")) {
+					const hit = cacheGet(apiCacheKey);
+					if (hit) return serveCached(hit, request);
+				}
+			}
+
+			const response = await handler({
+				request,
+				params: apiMatch.params,
+				url,
+				locals,
+				cookies,
+			});
+
+			if (
+				apiCacheable &&
+				apiCacheKey &&
+				response.status === 200 &&
+				(cookies as CookieJar).outgoing.length === 0
+			) {
+				const cloned = response.clone();
+				const extraHeaders = captureCacheableHeaders(response.headers);
+				const contentType =
+					response.headers.get("content-type") ?? "application/octet-stream";
+				const keyForWrite = apiCacheKey;
+				queueMicrotask(async () => {
+					try {
+						const buf = new Uint8Array(await cloned.arrayBuffer());
+						const { gzip, brotli } = buildCompressedVariants(buf);
+						// API endpoints have no LoaderDeps in v0.6 — invalidation is
+						// URL/prefix only. See ROADMAP for deferred tag support.
+						cacheSet(keyForWrite, {
+							raw: buf,
+							gzip,
+							brotli,
+							contentType,
+							status: 200,
+							extraHeaders,
+							tags: [],
+						});
+					} catch {
+						/* drop silently — cache population is best-effort */
+					}
+				});
+			}
+
+			return response;
 		} catch (err) {
 			if (isDev) console.error("API route error:", err);
 			else console.error("API route error:", (err as Error).message ?? err);
@@ -630,6 +715,16 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		});
 	}
 
+	// Shed load above MAX_INFLIGHT. Checked before any work so the 503 is
+	// cheap. /_health stays available so the orchestrator can still tell the
+	// process is alive (and decide whether to restart or scale out).
+	if (inFlight >= MAX_INFLIGHT && url.pathname !== "/_health") {
+		return new Response("Service Unavailable", {
+			status: 503,
+			headers: { "Retry-After": "1" },
+		});
+	}
+
 	inFlight++;
 	try {
 		// Handle CORS preflight before CSRF check (OPTIONS is CSRF-exempt)
@@ -762,6 +857,29 @@ const IDLE_TIMEOUT = parseIdleTimeout(process.env.IDLE_TIMEOUT);
 
 console.log(`⏱  Idle timeout: ${IDLE_TIMEOUT}s`);
 
+// ─── Concurrency Ceiling ──────────────────────────────────
+// Soft cap on in-flight requests, parsed from MAX_INFLIGHT env var.
+// Default is unlimited so existing apps see no behavior change. When set,
+// requests above the cap get a fast 503 + Retry-After before any work is
+// done — protects single-replica container deploys from OOM under spike
+// traffic. /_health is exempt so orchestrator liveness probes still work
+// while the app sheds load.
+
+function parseMaxInflight(value?: string): number {
+	if (!value) return Infinity;
+	const trimmed = value.trim();
+	if (trimmed === "" || trimmed.toLowerCase() === "infinity") return Infinity;
+	const n = parseInt(trimmed, 10);
+	if (!Number.isFinite(n) || n <= 0) throw new Error(`Invalid MAX_INFLIGHT: "${value}"`);
+	return n;
+}
+
+const MAX_INFLIGHT = parseMaxInflight(process.env.MAX_INFLIGHT);
+
+if (Number.isFinite(MAX_INFLIGHT)) {
+	console.log(`🚦 Max in-flight requests: ${MAX_INFLIGHT}`);
+}
+
 // ─── Graceful Shutdown State ──────────────────────────────
 
 let shuttingDown = false;
@@ -909,4 +1027,22 @@ async function shutdown() {
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);
 
+// Prod-only fatal handlers. The dev inspector plugin installs its own
+// uncaughtException/unhandledRejection listeners that route errors into the
+// overlay and let the dev runner's crash-backoff restart the process. In prod
+// there's no inspector — without these handlers an unhandled rejection from a
+// background timer or plugin hook orphans the process with no log context.
+// Log + exit(1) lets the orchestrator (Podman/k8s) restart cleanly.
+if (!isDev) {
+	process.on("uncaughtException", (err: Error) => {
+		console.error("[FATAL] uncaughtException:", err?.stack ?? err);
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason: unknown) => {
+		const e = reason as Error | undefined;
+		console.error("[FATAL] unhandledRejection:", e?.stack ?? reason);
+		process.exit(1);
+	});
+}
+
 export { app };

package/src/lib/index.ts

@@ -6,6 +6,9 @@
 export { cn, getServerTime } from "./utils.ts";
 export { sequence } from "../core/hooks.ts";
 export { error, redirect, fail } from "../core/errors.ts";
+// `invalidate` / `invalidateAll` (server response-cache eviction) live in
+// "bosia/server" — they touch server-process state and pulling them into
+// the shared barrel leaks `process.env` reads into client bundles.
 export type { HttpError, Redirect, RedirectOptions, ActionFailure } from "../core/errors.ts";
 export type {
 	RequestEvent,

package/src/lib/server.ts

@@ -0,0 +1,12 @@
+// ─── Bosia Server API ─────────────────────────────────────
+// Server-only helpers — import from "bosia/server".
+// Kept separate from "bosia" because these modules touch server-process
+// state (the response-cache Map, `process.env`) and have no meaning in
+// the browser. Importing them through the shared `bosia` barrel would
+// drag `process.env` reads into client bundles via the lib re-export
+// graph (see ROADMAP v0.6.0 entry on the Safari hydration ReferenceError).
+//
+// Usage in user apps (form actions, +server.ts, hooks):
+//   import { invalidate, invalidateAll } from "bosia/server";
+
+export { invalidate, invalidateAll } from "../core/cache.ts";

package/templates/default/.env.example

@@ -14,7 +14,7 @@
 # Import in your code:
 #   import { PUBLIC_STATIC_APP_NAME, DB_PASSWORD } from '$env';
 #
-# Framework vars (PORT, NODE_ENV, BODY_SIZE_LIMIT, CSRF_ALLOWED_ORIGINS,
+# Framework vars (PORT, NODE_ENV, BODY_SIZE_LIMIT, MAX_INFLIGHT, CSRF_ALLOWED_ORIGINS,
 # CORS_*, LOAD_TIMEOUT, METADATA_TIMEOUT, PRERENDER_TIMEOUT) are NOT exposed via $env —
 # access them via process.env directly.
 # ────────────────────────────────────────────────────────────────────────────────
@@ -30,6 +30,25 @@ PUBLIC_STATIC_APP_NAME=My Bosia App
 # Maximum request body size. Supports K/M/G suffixes or "Infinity". Defaults to 512K.
 # BODY_SIZE_LIMIT=512K
 
+# Soft cap on concurrent in-flight requests. Requests above the cap get a fast
+# 503 + Retry-After before any work is done — protects single-replica container
+# deploys from OOM under traffic spikes. Defaults to Infinity (no cap).
+# /_health is exempt so orchestrator liveness probes keep working under load.
+# MAX_INFLIGHT=500
+
+# Server response cache (skip-render). Caches HTML SSR pages and +server.ts GET
+# handlers in-memory, keyed by URL + identity (cookies/headers from CACHE_KEYS).
+# Per-user pages stay isolated. Disable per-route with `export const cache = false`.
+# See guides/response-cache for details.
+#
+# Identity keys: cookies AND headers with any of these names contribute to the
+# cache key, so logged-in users never see each other's pages. Default covers
+# common session cookie/header names. Leave blank to use the default.
+# CACHE_KEYS=session,sid,auth,token,jwt,Authorization
+#
+# Max cache entries (LRU). Set to 0 to disable the cache entirely. Defaults to 500.
+# CACHE_MAX_ENTRIES=500
+
 # Timeout for load() functions (layout + page) in milliseconds. Defaults to 5000 (5s).
 # Set to 0 or Infinity to disable.
 # LOAD_TIMEOUT=5000

package/templates/demo/.env.example

@@ -4,6 +4,18 @@ PORT=9000
 # Maximum request body size. Supports K/M/G suffixes or "Infinity". Defaults to 512K.
 BODY_SIZE_LIMIT=512K
 
+# Soft cap on concurrent in-flight requests. Requests above the cap get a fast
+# 503 + Retry-After before any work is done — protects single-replica container
+# deploys from OOM under traffic spikes. Defaults to Infinity (no cap).
+# /_health is exempt so orchestrator liveness probes keep working under load.
+# MAX_INFLIGHT=500
+
+# Server response cache (skip-render). Caches HTML SSR pages and +server.ts GET
+# handlers in-memory, keyed by URL + identity (cookies/headers from CACHE_KEYS).
+# Per-user pages stay isolated. Disable per-route with `export const cache = false`.
+# CACHE_KEYS=session,sid,auth,token,jwt,Authorization
+# CACHE_MAX_ENTRIES=500
+
 # Comma-separated list of allowed CORS origins for CSRF validation.
 # Leave unset to allow same-origin requests only.
 # Example: https://app.example.com, https://admin.example.com