bosia 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "1.1.2",
+	"version": "1.1.4",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.4"

package/src/core/assetCache.ts

@@ -0,0 +1,124 @@
+// ─── In-memory Asset Cache ───────────────────────────────
+// Keeps small static files and prerendered pages (and their .br/.gz variants)
+// in memory after their first request, so later hits skip the per-request
+// open/stat/read of `Bun.file`. Filled lazily — boot does no extra I/O, so a
+// cold start costs the same as before. Byte-budget LRU, keyed by absolute path.
+//
+// Bun only: on Workers, static files are served by Workers Static Assets
+// before the worker runs, so this module never sees them.
+
+type Bytes = Uint8Array<ArrayBuffer>;
+export type AssetHit = { bytes: Bytes; type: string };
+
+function parseBytes(raw: string | undefined, fallback: number): number {
+	if (!raw) return fallback;
+	const n = parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 0) return fallback;
+	return n;
+}
+
+export const DEFAULT_ASSET_CACHE_MAX_BYTES = 52_428_800; // 50MB; 0 = disabled
+export const DEFAULT_ASSET_CACHE_MAX_FILE_BYTES = 1_048_576; // 1MB
+
+export function parseAssetCacheEnv(env: Record<string, string | undefined>): {
+	maxBytes: number;
+	maxFileBytes: number;
+} {
+	return {
+		maxBytes: parseBytes(env.ASSET_CACHE_MAX_BYTES, DEFAULT_ASSET_CACHE_MAX_BYTES),
+		maxFileBytes: parseBytes(env.ASSET_CACHE_MAX_FILE_BYTES, DEFAULT_ASSET_CACHE_MAX_FILE_BYTES),
+	};
+}
+
+export class AssetCache {
+	private map = new Map<string, AssetHit>();
+	private inFlight = new Map<string, Promise<void>>();
+	private used = 0;
+
+	constructor(
+		readonly maxBytes: number,
+		readonly maxFileBytes: number,
+	) {}
+
+	get enabled(): boolean {
+		return this.maxBytes > 0 && this.maxFileBytes > 0;
+	}
+
+	get usedBytes(): number {
+		return this.used;
+	}
+
+	get size(): number {
+		return this.map.size;
+	}
+
+	/** Hit promotes the entry (Map insertion order = LRU order). */
+	get(path: string): AssetHit | undefined {
+		const hit = this.map.get(path);
+		if (hit === undefined) return undefined;
+		this.map.delete(path);
+		this.map.set(path, hit);
+		return hit;
+	}
+
+	/**
+	 * Read `path` into memory in the background. `type` is the Content-Type of
+	 * the original file — a `.br` variant must not report its own. Errors are
+	 * swallowed: the caller already answered from disk, and will again.
+	 */
+	fill(path: string, type: string): void {
+		if (!this.enabled || this.map.has(path) || this.inFlight.has(path)) return;
+		const job = (async () => {
+			const file = Bun.file(path);
+			if (file.size > this.maxFileBytes || file.size > this.maxBytes) return;
+			const bytes = (await file.bytes()) as Bytes;
+			if (bytes.byteLength > this.maxFileBytes || bytes.byteLength > this.maxBytes) return;
+			this.store(path, { bytes, type });
+		})()
+			.catch(() => {})
+			.finally(() => this.inFlight.delete(path));
+		this.inFlight.set(path, job);
+	}
+
+	/** Resolves once every fill started so far has settled. For tests. */
+	async idle(): Promise<void> {
+		while (this.inFlight.size > 0) await Promise.all(this.inFlight.values());
+	}
+
+	clear(): void {
+		this.map.clear();
+		this.used = 0;
+	}
+
+	private store(path: string, hit: AssetHit): void {
+		const prev = this.map.get(path);
+		if (prev) {
+			this.used -= prev.bytes.byteLength;
+			this.map.delete(path);
+		}
+		const size = hit.bytes.byteLength;
+		for (const [oldPath, old] of this.map) {
+			if (this.used + size <= this.maxBytes) break;
+			this.map.delete(oldPath);
+			this.used -= old.bytes.byteLength;
+		}
+		this.map.set(path, hit);
+		this.used += size;
+	}
+}
+
+const env: Record<string, string | undefined> =
+	typeof process !== "undefined" && process.env ? process.env : {};
+const limits = parseAssetCacheEnv(env);
+
+export const assetCache = new AssetCache(limits.maxBytes, limits.maxFileBytes);
+
+const mb = (n: number) => `${Math.round((n / 1_048_576) * 10) / 10}MB`;
+
+export function logAssetCache(): void {
+	console.log(
+		assetCache.enabled
+			? `🗂️  Asset cache: max ${mb(assetCache.maxBytes)}, max file ${mb(assetCache.maxFileBytes)}`
+			: "🗂️  Asset cache: disabled",
+	);
+}

package/src/core/build.ts

@@ -19,6 +19,7 @@ import { makeBosiaSvelteCompiler, svelteMapCache } from "./svelteCompiler.ts";
 import { finalizeComponentCss } from "./componentCss.ts";
 import { buildPreloadMap } from "./preloadMap.ts";
 import { prerenderStaticRoutes, generateStaticSite } from "./prerender.ts";
+import { precompressDir } from "./precompress.ts";
 import { loadEnv, classifyEnvVars } from "./env.ts";
 import { generateEnvModules } from "./envCodegen.ts";
 import { BOSIA_NODE_PATH, OUT_DIR, resolveBosiaBin, toPosix } from "./paths.ts";
@@ -398,6 +399,25 @@ await prerenderStaticRoutes(manifest);
 // 10. Generate static site output (HTML + client assets + public → dist/static/)
 generateStaticSite();
 
+// 10b. Precompress client assets + prerendered HTML (.br/.gz siblings) for the
+// Bun server. Runs after the static mirror so dist/static — the Workers upload
+// and static-host output — stays free of them; Workers' edge compresses itself.
+// public/ is left raw: mostly already-compressed images, and it is the app's
+// source dir. Precompress into dist/static and serve from there if that bites.
+if (isProduction && target !== "workers") {
+	const t0 = performance.now();
+	const results = await Promise.all([
+		precompressDir(join(OUT_DIR, "client")),
+		precompressDir(join(OUT_DIR, "prerendered")),
+	]);
+	const files = results.reduce((n, r) => n + r.files, 0);
+	const raw = results.reduce((n, r) => n + r.rawBytes, 0);
+	const br = results.reduce((n, r) => n + r.brBytes, 0);
+	console.log(
+		`✅ Precompressed ${files} files: ${Math.round(raw / 1024)}KB → ${Math.round(br / 1024)}KB br (${Math.round(performance.now() - t0)}ms)`,
+	);
+}
+
 // 11. Workers target: a second server bundle for Cloudflare. The Bun one above
 // still exists — prerender just booted it to crawl static routes.
 if (target === "workers") await buildWorker();

package/src/core/cache.ts

@@ -8,11 +8,10 @@
 // node:crypto / node:zlib rather than Bun.* — the same code runs on Bun and on
 // Cloudflare Workers (nodejs_compat), and both stay sync there.
 import { createHash } from "node:crypto";
-import { brotliCompressSync, gzipSync, constants as zlibConstants } from "node:zlib";
 import type { Cookies, LoaderDeps } from "./hooks.ts";
 import type { CookieJar } from "./cookies.ts";
 import { dedupKey } from "./dedup.ts";
-import { compressionOn, PRECOMPRESSED } from "./html.ts";
+import { compressionOn, encodeBytes, PRECOMPRESSED } from "./html.ts";
 
 // ─── Config ──────────────────────────────────────────────
 
@@ -280,34 +279,51 @@ function cacheDeleteIndexOnly(key: string, entry: CacheEntry): void {
 
 // ─── Compression helpers ─────────────────────────────────
 
-/** Build gzip + brotli copies of body. Sync, runs in microtask. */
-export function buildCompressedVariants(body: Bytes): {
+/**
+ * Build gzip + brotli copies of body. Sync — call it from `deferCacheWrite`.
+ * `prebuilt`: a variant already encoded for the response (at cache quality),
+ * reused as-is so a miss compresses each encoding once.
+ */
+export function buildCompressedVariants(
+	body: Bytes,
+	prebuilt: { gzip?: Bytes; brotli?: Bytes } = {},
+): {
 	gzip: Bytes | null;
 	brotli: Bytes | null;
 } {
 	const COMPRESS_MIN_BYTES = 2048;
 	if (!compressionOn || body.length < COMPRESS_MIN_BYTES) return { gzip: null, brotli: null };
-	let gzip: Bytes | null = null;
-	let brotli: Bytes | null = null;
-	try {
-		gzip = new Uint8Array(gzipSync(body)) as Bytes;
-	} catch {
-		gzip = null;
+	let gzip: Bytes | null = prebuilt.gzip ?? null;
+	let brotli: Bytes | null = prebuilt.brotli ?? null;
+	if (!gzip) {
+		try {
+			gzip = encodeBytes(body, "gzip", "cache");
+		} catch {
+			gzip = null;
+		}
 	}
-	try {
-		// Quality 5: ~20x faster than the default 11, still beats gzip on size.
-		// This runs sync in a microtask — 11 would block the event loop ~17ms/500KB.
-		brotli = new Uint8Array(
-			brotliCompressSync(body, {
-				params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 },
-			}),
-		) as Bytes;
-	} catch {
-		brotli = null;
+	if (!brotli) {
+		try {
+			brotli = encodeBytes(body, "br", "cache");
+		} catch {
+			brotli = null;
+		}
 	}
 	return { gzip, brotli };
 }
 
+/**
+ * Run a cache write after the current response has gone out. A microtask
+ * would not: it fires before the awaiting caller resumes, so gzip + brotli of
+ * the body ran ahead of the first byte. `setImmediate` yields to I/O first.
+ * Workers keeps the microtask — it compresses nothing (the edge does), and a
+ * timer after the response returns is not guaranteed to run there.
+ */
+export function deferCacheWrite(fn: () => void | Promise<void>): void {
+	if (compressionOn) setImmediate(fn);
+	else queueMicrotask(fn);
+}
+
 /** Concatenate multiple Uint8Array chunks into one buffer. */
 export function concatChunks(chunks: Uint8Array[]): Bytes {
 	let total = 0;

package/src/core/env.ts

@@ -3,6 +3,7 @@ import { join } from "path";
 
 // ─── Framework-reserved vars ─────────────────────────────
 // These are controlled by Bosia itself — users access them via process.env directly.
+// `test/env.test.ts` scans `src/` and fails when Bosia reads a name missing here.
 const FRAMEWORK_VARS = new Set([
 	"PORT",
 	"NODE_ENV",
@@ -20,8 +21,24 @@ const FRAMEWORK_VARS = new Set([
 	"LOAD_TIMEOUT",
 	"METADATA_TIMEOUT",
 	"PRERENDER_TIMEOUT",
+	"PRERENDER_CONCURRENCY",
+	"IDLE_TIMEOUT",
+	"MAX_INFLIGHT",
+	"TRUST_PROXY",
+	"CSP_DIRECTIVES",
+	"DISABLE_X_FRAME_OPTIONS",
+	"CACHE_KEYS",
+	"CACHE_MAX_ENTRIES",
+	"CACHE_MAX_BODY_BYTES",
+	"ASSET_CACHE_MAX_BYTES",
+	"ASSET_CACHE_MAX_FILE_BYTES",
 ]);
 
+/** Framework-owned: a listed name, or anything under the reserved `BOSIA_` prefix. */
+export function isFrameworkVar(name: string): boolean {
+	return FRAMEWORK_VARS.has(name) || name.startsWith("BOSIA_");
+}
+
 // ─── .env File Parser ────────────────────────────────────
 
 /** Valid JS/TS identifier: starts with letter/underscore, then alphanumeric/underscore. */
@@ -173,7 +190,7 @@ export function loadEnv(mode: string, dir?: string): Record<string, string> {
 	// Return only non-framework vars
 	const result: Record<string, string> = {};
 	for (const key of declaredNames) {
-		if (!FRAMEWORK_VARS.has(key)) {
+		if (!isFrameworkVar(key)) {
 			result[key] = process.env[key] ?? merged[key] ?? "";
 		}
 	}

package/src/core/html.ts

@@ -1,4 +1,4 @@
-import { gzipSync } from "node:zlib";
+import { brotliCompressSync, gzipSync, constants as zlibConstants } from "node:zlib";
 
 import { readArtifact } from "./artifacts.ts";
 import { nonceAttr } from "./csp.ts";
@@ -464,12 +464,72 @@ export function disableCompression(): void {
 // Shared, stateless — one instance instead of a fresh allocation per response.
 const textEncoder = new TextEncoder();
 
+export type Encoding = "br" | "gzip";
+
+/** Best encoding the client accepts — brotli over gzip, null for identity.
+ *  A substring check, not q-value parsing: no browser sends `br;q=0`. */
+export function pickEncoding(accept: string | null): Encoding | null {
+	if (!accept) return null;
+	if (accept.includes("br")) return "br";
+	if (accept.includes("gzip")) return "gzip";
+	return null;
+}
+
+// Per-request brotli runs once per response, so it favors speed: q3 is ~2x
+// faster than q5 for ~5–25% bigger output. Cached variants are built once and
+// served many times, so they take q5. 11 (the default) would block the event
+// loop ~17ms per 500KB.
+export type Quality = "request" | "cache";
+const BROTLI = {
+	request: { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 3 } },
+	cache: { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 } },
+};
+
+/** The one place runtime compression quality is set — cache.ts builds its
+ *  stored variants through here too. gzip keeps zlib's default level. */
+export function encodeBytes(
+	bytes: Uint8Array,
+	enc: Encoding,
+	quality: Quality = "request",
+): Uint8Array<ArrayBuffer> {
+	const out = enc === "br" ? brotliCompressSync(bytes, BROTLI[quality]) : gzipSync(bytes);
+	return new Uint8Array(out) as Uint8Array<ArrayBuffer>;
+}
+
+export type Encoded = { enc: Encoding; encoded: Uint8Array<ArrayBuffer> };
+
+/** The body this client gets, or null when it goes out uncompressed. */
+export function encodeForRequest(
+	bytes: Uint8Array<ArrayBuffer>,
+	req: Request,
+	quality: Quality = "request",
+): Encoded | null {
+	const enc = pickEncoding(req.headers.get("accept-encoding"));
+	// Skip compression in dev — the dev proxy's fetch() auto-decompresses gzip
+	// responses but keeps the Content-Encoding header, causing ERR_CONTENT_DECODING_FAILED.
+	if (!compressionOn || isDev || !enc || bytes.length <= GZIP_MIN_BYTES) return null;
+	return { enc, encoded: encodeBytes(bytes, enc, quality) };
+}
+
 export function compress(
 	body: string,
 	contentType: string,
 	req: Request,
 	status = 200,
 	extraHeaders?: Record<string, string>,
+): Response {
+	return compressBytes(textEncoder.encode(body), contentType, req, status, extraHeaders);
+}
+
+/** `encoded`: the result of `encodeForRequest` when the caller already has it
+ *  (a cache write reuses the same bytes); omitted, it is built here. */
+export function compressBytes(
+	bytes: Uint8Array<ArrayBuffer>,
+	contentType: string,
+	req: Request,
+	status = 200,
+	extraHeaders?: Record<string, string>,
+	encoded: Encoded | null = encodeForRequest(bytes, req),
 ): Response {
 	// Base keys lowercased so lowercased extraHeaders (e.g. loader setHeaders)
 	// override them instead of getting comma-joined by Headers.
@@ -478,15 +538,11 @@ export function compress(
 		vary: "Accept-Encoding",
 		...extraHeaders,
 	};
-	const accept = req.headers.get("accept-encoding") ?? "";
-	const bytes = textEncoder.encode(body);
-	// Skip compression in dev — the dev proxy's fetch() auto-decompresses gzip
-	// responses but keeps the Content-Encoding header, causing ERR_CONTENT_DECODING_FAILED.
-	if (compressionOn && !isDev && bytes.length > GZIP_MIN_BYTES && accept.includes("gzip")) {
-		return new Response(gzipSync(bytes), {
+	if (encoded) {
+		return new Response(encoded.encoded, {
 			...PRECOMPRESSED,
 			status,
-			headers: { ...headers, "content-encoding": "gzip" },
+			headers: { ...headers, "content-encoding": encoded.enc },
 		});
 	}
 	return new Response(bytes, { status, headers });

package/src/core/plugins/server-timing.ts

@@ -10,9 +10,9 @@ export interface ServerTimingOptions {
 /**
  * Adds a `Server-Timing` response header that reports how long each request
  * spent inside the framework's handler. Measured from `onRequest` to
- * `onAfterHandle` — so for streaming SSR routes this is "time to start
- * streaming," not full end-to-end. Headers must flush before the body, so a
- * true end-to-end value cannot be reported in a response header.
+ * `onAfterHandle` — the time to build the response, not to deliver it. A
+ * streaming `+server.ts` route reports "time to start streaming". Headers must
+ * flush before the body, so a true end-to-end value cannot be reported here.
  */
 export function serverTiming(options: ServerTimingOptions = {}): BosiaPlugin {
 	const headerName = options.header ?? "Server-Timing";

package/src/core/precompress.ts

@@ -0,0 +1,82 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { extname, join } from "path";
+import { promisify } from "util";
+import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
+
+// ─── Build-time Precompression ───────────────────────────
+// Writes `file.br` + `file.gz` next to each compressible build output so the
+// server hands out ready-made bytes (staticManifest.ts `serveStatic`) instead of
+// raw ones. Build time is paid once, so both run at max quality.
+
+const brotliAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+
+const COMPRESSIBLE = new Set([
+	".js",
+	".css",
+	".html",
+	".json",
+	".svg",
+	".txt",
+	".xml",
+	".webmanifest",
+	".map",
+]);
+
+// Same floor as the runtime compress(): below it the overhead beats the saving.
+const MIN_BYTES = 2048;
+
+function* files(dir: string): Generator<string> {
+	let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" }) as unknown as Array<{
+			name: string;
+			isDirectory(): boolean;
+			isFile(): boolean;
+		}>;
+	} catch {
+		return;
+	}
+	for (const ent of entries) {
+		const abs = join(dir, ent.name);
+		if (ent.isDirectory()) yield* files(abs);
+		else if (ent.isFile()) yield abs;
+	}
+}
+
+export type PrecompressStats = { files: number; rawBytes: number; brBytes: number };
+
+/**
+ * Precompress every compressible file under `dir`. A variant is only written
+ * when it is smaller than the original, so the server can trust any sibling it
+ * finds. Missing `dir` is a no-op.
+ */
+export async function precompressDir(dir: string): Promise<PrecompressStats> {
+	const stats: PrecompressStats = { files: 0, rawBytes: 0, brBytes: 0 };
+	const jobs: Promise<void>[] = [];
+	for (const abs of files(dir)) {
+		if (!COMPRESSIBLE.has(extname(abs))) continue;
+		if (statSync(abs).size < MIN_BYTES) continue;
+		jobs.push(
+			(async () => {
+				const raw = readFileSync(abs);
+				const [br, gz] = await Promise.all([
+					brotliAsync(raw, {
+						params: {
+							[zlibConstants.BROTLI_PARAM_QUALITY]: zlibConstants.BROTLI_MAX_QUALITY,
+							[zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.length,
+						},
+					}),
+					gzipAsync(raw, { level: 9 }),
+				]);
+				if (br.length < raw.length) writeFileSync(`${abs}.br`, br);
+				if (gz.length < raw.length) writeFileSync(`${abs}.gz`, gz);
+				stats.files++;
+				stats.rawBytes += raw.length;
+				stats.brBytes += Math.min(br.length, raw.length);
+			})(),
+		);
+	}
+	await Promise.all(jobs);
+	return stats;
+}

package/src/core/renderer.ts

@@ -16,6 +16,7 @@ import {
 	collectTags,
 	computeCacheKey,
 	concatChunks,
+	deferCacheWrite,
 	serveCached,
 } from "./cache.ts";
 import type { CookieJar } from "./cookies.ts";
@@ -31,7 +32,10 @@ import {
 	buildMetadataChunk,
 	buildHtmlTail,
 	compress,
+	compressBytes,
+	encodeForRequest,
 	isDev,
+	type Encoded,
 } from "./html.ts";
 import type { Metadata } from "./hooks.ts";
 import { loadPlugins } from "./config.ts";
@@ -640,7 +644,7 @@ export async function renderSSRStream(
 	// INVARIANT: releaseMiss must fire exactly once — a missed release() hangs
 	// coalesced waiters for the process lifetime. Every early return and throw
 	// below must stay inside this try; the cache-write path hands the release
-	// off to its cacheSet microtask by nulling releaseMiss first.
+	// off to its deferred cacheSet by nulling releaseMiss first.
 	try {
 		// ── Pre-stream phase: resolve metadata before committing to a 200 ──
 		// Errors here return a proper error response with correct status code.
@@ -777,9 +781,7 @@ export async function renderSSRStream(
 					data.layoutDeps,
 					appHtmlSegments,
 				);
-			return new Response(html, {
-				headers: { "content-type": "text/html; charset=utf-8", ...data.loaderHeaders },
-			});
+			return compress(html, "text/html; charset=utf-8", req, 200, data.loaderHeaders);
 		}
 
 		// Render-first: run render() before committing to a 200. Failure → proper error page
@@ -817,7 +819,10 @@ export async function renderSSRStream(
 			);
 		}
 
-		// Pre-compute all chunks; pull-based stream gives Bun native backpressure.
+		// Every chunk is built before the first byte, so the body goes out whole and
+		// compressed — a stream here never streamed, it only skipped compression.
+		// Truly progressive SSR (ROADMAP) would pipe a stream through
+		// CompressionStream instead.
 		const chunks: Uint8Array[] = [
 			enc.encode(
 				buildHtmlShellOpen(
@@ -846,24 +851,37 @@ export async function renderSSRStream(
 			),
 		];
 
-		// ── Response cache: write after chunks built, before stream creation ──
+		const fullBody = concatChunks(chunks);
+		// Set only on a cache write: the client's variant, encoded once at cache
+		// quality and shared by the response and the cache entry.
+		let sent: Encoded | null | undefined;
+
+		// ── Response cache: write after the response has gone out ──
 		// 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.
+		// per-request Set-Cookie headers. deferCacheWrite runs the variant
+		// compression after this response is flushed, not ahead of it.
 		if (cacheable && cacheKey && (cookies as any).outgoing?.length === 0) {
-			const fullBody = concatChunks(chunks);
 			// Oversized bodies skip early so they never pay compression; cacheSet
 			// re-checks as the authoritative guard.
 			if (CACHE_MAX_BODY_BYTES === 0 || fullBody.length <= CACHE_MAX_BODY_BYTES) {
 				const tags = collectTags(data.layoutDeps ?? null, data.pageDeps ?? null);
 				const keyForWrite = cacheKey;
-				// Hand the gate release to the write microtask: waiters resume only
+				// Hand the gate release to the deferred write: waiters resume only
 				// after cacheSet ran, so their re-check hits.
 				const rel = releaseMiss;
 				releaseMiss = null;
-				queueMicrotask(() => {
+				const encoded = encodeForRequest(fullBody, req, "cache");
+				sent = encoded;
+				deferCacheWrite(() => {
 					try {
-						const { gzip, brotli } = buildCompressedVariants(fullBody);
+						const { gzip, brotli } = buildCompressedVariants(
+							fullBody,
+							encoded?.enc === "br"
+								? { brotli: encoded.encoded }
+								: encoded
+									? { gzip: encoded.encoded }
+									: {},
+						);
 						cacheSet(
 							keyForWrite,
 							{
@@ -884,35 +902,7 @@ export async function renderSSRStream(
 			}
 		}
 
-		let i = 0;
-		let cancelled = false;
-		const onAbort = () => {
-			cancelled = true;
-		};
-		req.signal.addEventListener("abort", onAbort, { once: true });
-
-		const stream = new ReadableStream<Uint8Array>({
-			pull(controller) {
-				if (cancelled || i >= chunks.length) {
-					controller.close();
-					req.signal.removeEventListener("abort", onAbort);
-					return;
-				}
-				controller.enqueue(chunks[i++]);
-				if (i >= chunks.length) {
-					controller.close();
-					req.signal.removeEventListener("abort", onAbort);
-				}
-			},
-			cancel() {
-				cancelled = true;
-				req.signal.removeEventListener("abort", onAbort);
-			},
-		});
-
-		return new Response(stream, {
-			headers: { "content-type": "text/html; charset=utf-8", ...data.loaderHeaders },
-		});
+		return compressBytes(fullBody, "text/html; charset=utf-8", req, 200, data.loaderHeaders, sent);
 	} finally {
 		releaseMiss?.();
 	}

package/src/core/server.bun.ts

@@ -11,6 +11,7 @@ import { isDev } from "./html.ts";
 import { OUT_DIR } from "./paths.ts";
 import { pidsOnPort } from "./port.ts";
 import { CACHE_ENABLED, CACHE_KEYS } from "./cache.ts";
+import { logAssetCache } from "./assetCache.ts";
 
 // ─── User Hooks ──────────────────────────────────────────
 // Production prefers the pre-bundled `${OUT_DIR}/hooks.server.js` emitted by the
@@ -44,6 +45,9 @@ if (hooksPath) {
 
 const app = await createApp({ handle });
 
+// Dev serves files straight from disk (no manifest), so the cache never runs there.
+if (!isDev) logAssetCache();
+
 // ─── Listen ──────────────────────────────────────────────
 
 const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : isDev ? 9001 : 9000;

package/src/core/server.ts

@@ -25,7 +25,12 @@ import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
 import { stripBase, withBase } from "./basePath.ts";
 import { currentBase } from "./appBase.ts";
-import { buildPrerenderManifest, buildStaticManifest, lookupStatic } from "./staticManifest.ts";
+import {
+	buildPrerenderManifest,
+	buildStaticManifest,
+	lookupStatic,
+	serveStatic,
+} from "./staticManifest.ts";
 import { dedup } from "./dedup.ts";
 import {
 	CACHE_ENABLED,
@@ -35,6 +40,7 @@ import {
 	cacheSet,
 	coalesceMiss,
 	computeCacheKey,
+	deferCacheWrite,
 	serveCached,
 	warnUncoveredCookies,
 } from "./cache.ts";
@@ -410,12 +416,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// api-before-static ordering intact for every user-facing path.
 	if (staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
 		const hit = lookupStatic(staticManifest, path);
-		if (hit) {
-			return new Response(
-				Bun.file(hit.absPath),
-				hit.cacheControl ? { headers: { "Cache-Control": hit.cacheControl } } : undefined,
-			);
-		}
+		if (hit) return serveStatic(hit, request);
 	}
 
 	// API routes (+server.ts) — resolve with `.json` alias preference.
@@ -428,7 +429,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		if (warmingUp) return new Response(null, { status: 404 });
 		// INVARIANT: once set, releaseApiMiss must fire exactly once — a missed
 		// release() hangs coalesced waiters for the process lifetime. The cache
-		// write path hands it off to its microtask by nulling it first.
+		// write path hands it off to its deferred write by nulling it first.
 		let releaseApiMiss: (() => void) | null = null;
 		try {
 			const mod = await apiMatch.route.module();
@@ -518,11 +519,11 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				const extraHeaders = captureCacheableHeaders(response.headers);
 				const contentType = responseContentType || "application/octet-stream";
 				const keyForWrite = apiCacheKey;
-				// Hand the gate release to the write microtask: waiters resume only
+				// Hand the gate release to the deferred write: waiters resume only
 				// after the cacheSet attempt, so their re-check hits.
 				const rel = releaseApiMiss;
 				releaseApiMiss = null;
-				queueMicrotask(async () => {
+				deferCacheWrite(async () => {
 					try {
 						const buf = new Uint8Array(await cloned.arrayBuffer());
 						// Oversized bodies skip early so they never pay compression;
@@ -588,12 +589,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		// Prod fast path: single Map lookup, no per-request stat calls.
 		if (staticManifest) {
 			const hit = lookupStatic(staticManifest, path);
-			if (hit) {
-				return new Response(
-					Bun.file(hit.absPath),
-					hit.cacheControl ? { headers: { "Cache-Control": hit.cacheControl } } : undefined,
-				);
-			}
+			if (hit) return serveStatic(hit, request);
 			return new Response("Not Found", { status: 404 });
 		}
 		// Dev: keep the per-request fallthrough so files dropped into `public/`
@@ -646,13 +642,11 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		// Keys come from a boot-time walk of `dist/prerendered/`, not from the
 		// URL, so no safePath needed — a non-matching path is just a miss.
 		const key = path === "/" ? "/" : path.replace(/\/$/, "");
-		const abs = prerenderManifest.get(key);
-		if (abs) {
-			return new Response(Bun.file(abs), {
-				headers: {
-					"Content-Type": "text/html; charset=utf-8",
-					"Cache-Control": "public, max-age=3600",
-				},
+		const hit = prerenderManifest.get(key);
+		if (hit) {
+			return serveStatic(hit, request, {
+				"Content-Type": "text/html; charset=utf-8",
+				"Cache-Control": "public, max-age=3600",
 			});
 		}
 	}

package/src/core/staticManifest.ts

@@ -1,7 +1,10 @@
 import { existsSync, readdirSync, statSync } from "fs";
 import { basename, join, resolve as resolvePath } from "path";
+import { PRECOMPRESSED, pickEncoding } from "./html.ts";
+import { AssetCache, assetCache } from "./assetCache.ts";
 
-export type StaticEntry = { absPath: string; cacheControl?: string };
+/** `br`/`gz`: absolute paths of build-time precompressed siblings (precompress.ts). */
+export type StaticEntry = { absPath: string; cacheControl?: string; br?: string; gz?: string };
 export type StaticManifest = Map<string, StaticEntry>;
 
 const HASHED_BASENAME = /\-[a-z0-9]{8,}\.[a-z]+$/;
@@ -49,9 +52,16 @@ export function buildStaticManifest(outDir: string): StaticManifest {
 
 	const clientRoot = join(outAbs, "client");
 	if (existsSync(clientRoot)) {
-		for (const { abs, rel } of walk(clientRoot)) {
-			const cacheControl = HASHED_BASENAME.test(basename(rel)) ? IMMUTABLE_CACHE : DEFAULT_CACHE;
-			addOnce(manifest, `/dist/client/${rel}`, { absPath: abs, cacheControl });
+		for (const entry of withSiblings(walk(clientRoot))) {
+			const cacheControl = HASHED_BASENAME.test(basename(entry.rel))
+				? IMMUTABLE_CACHE
+				: DEFAULT_CACHE;
+			addOnce(manifest, `/dist/client/${entry.rel}`, {
+				absPath: entry.abs,
+				cacheControl,
+				br: entry.br,
+				gz: entry.gz,
+			});
 		}
 	}
 
@@ -99,6 +109,121 @@ export function buildStaticManifest(outDir: string): StaticManifest {
 	return manifest;
 }
 
+/**
+ * Fold `x.br` / `x.gz` into the entry for `x`. The variants are not URLs of
+ * their own — a request for `/chunk.js.br` is a miss, like any file the build
+ * never meant to publish. A `.br` with no original is kept as a plain file.
+ */
+function withSiblings(
+	all: Iterable<{ abs: string; rel: string }>,
+): Array<{ abs: string; rel: string; br?: string; gz?: string }> {
+	const list = [...all];
+	const byRel = new Map(list.map((f) => [f.rel, f]));
+	const out: Array<{ abs: string; rel: string; br?: string; gz?: string }> = [];
+	for (const f of list) {
+		const ext = f.rel.endsWith(".br") ? ".br" : f.rel.endsWith(".gz") ? ".gz" : null;
+		if (ext && byRel.has(f.rel.slice(0, -ext.length))) continue;
+		out.push({
+			...f,
+			br: byRel.get(`${f.rel}.br`)?.abs,
+			gz: byRel.get(`${f.rel}.gz`)?.abs,
+		});
+	}
+	return out;
+}
+
+/**
+ * Response for a manifest hit, precompressed when the build left a variant the
+ * client accepts. Content-Type comes from the original — `Bun.file("x.js.br")`
+ * would infer the wrong one. `Vary` only when variants exist: a raw-only file
+ * answers every client the same way.
+ *
+ * Small files are answered from `assetCache` once a first request has read
+ * them; the miss itself is served from disk as before and fills the cache in
+ * the background. Range requests always go to disk — Bun answers those with a
+ * 206 for `Bun.file` bodies, not for bytes.
+ *
+ * Every answer carries an `ETag` (Bun's `Bun.file` responses have none), so a
+ * `no-cache` file or an expired prerendered page revalidates with a 304
+ * instead of downloading again.
+ */
+export function serveStatic(
+	entry: StaticEntry,
+	req: Request,
+	headers: Record<string, string> = {},
+	cache: AssetCache = assetCache,
+): Response {
+	const out: Record<string, string> = { ...headers };
+	if (entry.cacheControl) out["Cache-Control"] = entry.cacheControl;
+
+	let path = entry.absPath;
+	let init: ResponseInit = {};
+	if (entry.br || entry.gz) {
+		out["Vary"] = "Accept-Encoding";
+		const enc = pickEncoding(req.headers.get("accept-encoding"));
+		const variant = enc === "br" ? (entry.br ?? entry.gz) : enc === "gzip" ? entry.gz : undefined;
+		if (variant) {
+			path = variant;
+			init = PRECOMPRESSED;
+			out["Content-Encoding"] = variant === entry.br ? "br" : "gzip";
+		}
+	}
+
+	const etag = etagFor(path, out["Content-Encoding"]);
+	if (etag) {
+		out["ETag"] = etag;
+		if (matchesEtag(req.headers.get("if-none-match"), etag)) {
+			delete out["Content-Encoding"];
+			delete out["Content-Type"];
+			return new Response(null, { status: 304, headers: out });
+		}
+	}
+
+	if (cache.enabled && !req.headers.has("range")) {
+		const hit = cache.get(path);
+		if (hit) {
+			out["Content-Type"] ??= hit.type;
+			return new Response(hit.bytes, { ...init, headers: out });
+		}
+		const type = out["Content-Type"] ?? Bun.file(entry.absPath).type;
+		cache.fill(path, type);
+		if (path !== entry.absPath) out["Content-Type"] = type;
+	} else if (path !== entry.absPath) {
+		out["Content-Type"] ??= Bun.file(entry.absPath).type;
+	}
+	return new Response(Bun.file(path), { ...init, headers: out });
+}
+
+// One stat per served path per process. Files under dist/ and public/ are not
+// expected to change while the server runs; a redeploy restarts the process.
+// If that ever stops holding, key the map on mtime too (one stat per request).
+const etags = new Map<string, string | null>();
+
+/** Strong ETag from size + mtime. The encoding suffix keeps br/gzip/raw apart. */
+function etagFor(path: string, encoding: string | undefined): string | null {
+	let tag = etags.get(path);
+	if (tag === undefined) {
+		try {
+			const st = statSync(path);
+			const suffix = encoding === "br" ? "-br" : encoding === "gzip" ? "-gz" : "";
+			tag = `"${st.size.toString(36)}-${Math.floor(st.mtimeMs).toString(36)}${suffix}"`;
+		} catch {
+			tag = null;
+		}
+		etags.set(path, tag);
+	}
+	return tag;
+}
+
+function matchesEtag(header: string | null, etag: string): boolean {
+	if (!header) return false;
+	for (const raw of header.split(",")) {
+		const t = raw.trim();
+		if (t === "*" || t === etag || (t.startsWith("W/") && t.slice(2) === etag)) return true;
+	}
+	return false;
+}
+
 export function lookupStatic(manifest: StaticManifest, urlPath: string): StaticEntry | null {
 	const raw = urlPath.split("?")[0];
 	// Manifest keys are raw filenames; URLs arrive percent-encoded.
@@ -117,10 +242,10 @@ export function lookupStatic(manifest: StaticManifest, urlPath: string): StaticE
  * On collision the `…/index.html` variant wins (mirrors the old runtime
  * candidate order). Replaces per-request `Bun.file().exists()` probes.
  */
-export function buildPrerenderManifest(outDir: string): Map<string, string> {
-	const manifest = new Map<string, string>();
+export function buildPrerenderManifest(outDir: string): Map<string, StaticEntry> {
+	const manifest = new Map<string, StaticEntry>();
 	const root = join(resolvePath(outDir), "prerendered");
-	for (const { abs, rel } of walk(root)) {
+	for (const { abs, rel, br, gz } of withSiblings(walk(root))) {
 		if (!rel.endsWith(".html")) continue;
 		let key: string;
 		let isIndex = false;
@@ -133,7 +258,7 @@ export function buildPrerenderManifest(outDir: string): Map<string, string> {
 		} else {
 			key = `/${rel.slice(0, -".html".length)}`;
 		}
-		if (isIndex || !manifest.has(key)) manifest.set(key, abs);
+		if (isIndex || !manifest.has(key)) manifest.set(key, { absPath: abs, br, gz });
 	}
 	return manifest;
 }

package/templates/default/.env.example

@@ -49,6 +49,13 @@ PUBLIC_STATIC_APP_NAME=My Bosia App
 # Max cache entries (LRU). Set to 0 to disable the cache entirely. Defaults to 500.
 # CACHE_MAX_ENTRIES=500
 
+# Static files and prerendered pages are kept in memory after their first
+# request (Bun only; ignored on Cloudflare Workers). Total budget in bytes,
+# 0 = always read from disk. Defaults to 52428800 (50MB).
+# ASSET_CACHE_MAX_BYTES=52428800
+# Largest file kept in memory, in bytes. Defaults to 1048576 (1MB).
+# ASSET_CACHE_MAX_FILE_BYTES=1048576
+
 # 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

@@ -16,6 +16,13 @@ BODY_SIZE_LIMIT=512K
 # CACHE_KEYS=session,sid,auth,token,jwt,Authorization
 # CACHE_MAX_ENTRIES=500
 
+# Static files and prerendered pages are kept in memory after their first
+# request (Bun only; ignored on Cloudflare Workers). Total budget in bytes,
+# 0 = always read from disk. Defaults to 52428800 (50MB).
+# ASSET_CACHE_MAX_BYTES=52428800
+# Largest file kept in memory, in bytes. Defaults to 1048576 (1MB).
+# ASSET_CACHE_MAX_FILE_BYTES=1048576
+
 # 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