bosia 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "1.1.3",
+	"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/cache.ts

@@ -279,26 +279,35 @@ function cacheDeleteIndexOnly(key: string, entry: CacheEntry): void {
 
 // ─── Compression helpers ─────────────────────────────────
 
-/** Build gzip + brotli copies of body. Sync — call it from `deferCacheWrite`. */
-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 = encodeBytes(body, "gzip");
-	} 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 (set in encodeBytes): ~20x faster than the default 11, still
-		// beats gzip on size. 11 would block the event loop ~17ms/500KB.
-		brotli = encodeBytes(body, "br");
-	} catch {
-		brotli = null;
+	if (!brotli) {
+		try {
+			brotli = encodeBytes(body, "br", "cache");
+		} catch {
+			brotli = null;
+		}
 	}
 	return { gzip, brotli };
 }
@@ -309,9 +318,6 @@ export function buildCompressedVariants(body: Bytes): {
  * 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.
- *
- * On a miss the variant sent to the client is compressed twice (response +
- * cache). Off the critical path; pass the built variant in if it ever shows up.
  */
 export function deferCacheWrite(fn: () => void | Promise<void>): void {
 	if (compressionOn) setImmediate(fn);

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

@@ -475,16 +475,42 @@ export function pickEncoding(accept: string | null): Encoding | null {
 	return null;
 }
 
-// Quality 5: close to gzip's speed with a better ratio — runs per request.
-const BROTLI_RUNTIME = { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 } };
-
-/** Compress bytes on the request path. The one place runtime quality is set —
- *  cache.ts builds its stored variants through here too. */
-export function encodeBytes(bytes: Uint8Array, enc: Encoding): Uint8Array<ArrayBuffer> {
-	const out = enc === "br" ? brotliCompressSync(bytes, BROTLI_RUNTIME) : gzipSync(bytes);
+// 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,
@@ -495,12 +521,15 @@ export function compress(
 	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.
@@ -509,14 +538,11 @@ export function compressBytes(
 		vary: "Accept-Encoding",
 		...extraHeaders,
 	};
-	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 new Response(encodeBytes(bytes, enc), {
+	if (encoded) {
+		return new Response(encoded.encoded, {
 			...PRECOMPRESSED,
 			status,
-			headers: { ...headers, "content-encoding": enc },
+			headers: { ...headers, "content-encoding": encoded.enc },
 		});
 	}
 	return new Response(bytes, { status, headers });

package/src/core/renderer.ts

@@ -33,7 +33,9 @@ import {
 	buildHtmlTail,
 	compress,
 	compressBytes,
+	encodeForRequest,
 	isDev,
+	type Encoded,
 } from "./html.ts";
 import type { Metadata } from "./hooks.ts";
 import { loadPlugins } from "./config.ts";
@@ -850,6 +852,9 @@ export async function renderSSRStream(
 		];
 
 		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
@@ -865,9 +870,18 @@ export async function renderSSRStream(
 				// after cacheSet ran, so their re-check hits.
 				const rel = releaseMiss;
 				releaseMiss = null;
+				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,
 							{
@@ -888,7 +902,7 @@ export async function renderSSRStream(
 			}
 		}
 
-		return compressBytes(fullBody, "text/html; charset=utf-8", req, 200, 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/staticManifest.ts

@@ -1,6 +1,7 @@
 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";
 
 /** `br`/`gz`: absolute paths of build-time precompressed siblings (precompress.ts). */
 export type StaticEntry = { absPath: string; cacheControl?: string; br?: string; gz?: string };
@@ -136,24 +137,91 @@ function withSiblings(
  * 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;
-	if (!entry.br && !entry.gz) return new Response(Bun.file(entry.absPath), { headers: out });
 
-	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) return new Response(Bun.file(entry.absPath), { headers: out });
+	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 });
+}
 
-	out["Content-Type"] ??= Bun.file(entry.absPath).type;
-	out["Content-Encoding"] = variant === entry.br ? "br" : "gzip";
-	return new Response(Bun.file(variant), { ...PRECOMPRESSED, 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 {

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