bosia 1.2.5 → 1.2.7

package/src/core/routeTypes.ts

@@ -55,6 +55,12 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		}
 	}
 
+	// +server.ts dirs get Params and WebSocketHandler too.
+	for (const api of manifest.apis) {
+		const apiDir = routeDirOf(api.server);
+		if (!dirs.has(apiDir)) dirs.set(apiDir, {});
+	}
+
 	if (manifest.errorPage) {
 		if (!dirs.has(".")) dirs.set(".", {});
 		dirs.get(".")!.hasErrorPage = true;
@@ -78,7 +84,9 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 				: `{ ${params.map((p) => `${PARAM_NAME.test(p) ? p : JSON.stringify(p)}: string`).join("; ")} }`;
 
 		const lines: string[] = ["// AUTO-GENERATED by bosia — do not edit\n"];
-		lines.push(`import type { LoadEvent, MetadataEvent, RequestEvent, Metadata } from 'bosia';`);
+		lines.push(
+			`import type { LoadEvent, MetadataEvent, RequestEvent, Metadata, WebSocketHandler as _WebSocketHandler } from 'bosia';`,
+		);
 		lines.push(``);
 		lines.push(`export type Params = ${paramsType};`);
 		lines.push(``);
@@ -97,6 +105,13 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		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 };`);
+		lines.push(``);
+		lines.push(
+			`/** \`export const websocket: WebSocketHandler<Data>\` in +server.ts (Bun only). */`,
+		);
+		lines.push(
+			`export type WebSocketHandler<T extends object = {}> = _WebSocketHandler<T, _RequestEvent>;`,
+		);
 
 		if (info.pageServer) {
 			lines.push(``);

package/src/core/server.bun.ts

@@ -107,8 +107,13 @@ async function shutdown() {
 		console.log("✅ All requests drained");
 	}
 
-	app.stop(true).then(() => process.exit(0));
 	setTimeout(() => process.exit(1), 2_000);
+	// inFlight reaches 0 just before Bun writes the last responses, so stop
+	// gracefully first, briefly: an open stream (SSE) never finishes by itself,
+	// and a socket that never acks its 1001 shouldn't hold the exit either.
+	if (left === 0) await Promise.race([app.stop(), Bun.sleep(500)]);
+	await app.stop(true);
+	process.exit(0);
 }
 
 process.on("SIGTERM", shutdown);

package/src/core/server.ts

@@ -16,7 +16,8 @@ import { HttpError, Redirect, ActionFailure, isHttpError, isRedirect } from "./e
 import { CookieJar } from "./cookies.ts";
 import { safePath } from "./safePath.ts";
 import { HEALTH_PATH, isFrameworkPath, isStaticPath } from "./staticPath.ts";
-import { checkCsrf } from "./csrf.ts";
+import { checkCsrf, checkUpgradeOrigin } from "./csrf.ts";
+import { applyForwarded } from "./proxy.ts";
 import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
 import type { CorsConfig } from "./cors.ts";
@@ -46,26 +47,43 @@ import {
 import { dedup } from "./dedup.ts";
 import {
 	CACHE_ENABLED,
-	CACHE_MAX_BODY_BYTES,
+	CACHE_WAIT_TIMEOUT,
+	bodyFitsCache,
 	buildCompressedVariants,
 	cacheGet,
 	cacheSet,
-	coalesceMiss,
+	claimMiss,
 	collectTags,
+	depsReadIgnoredParams,
+	stripIgnoredParams,
 	computeCacheKey,
 	deferCacheWrite,
+	isNoStoreCacheControl,
+	readBodyForCache,
 	serveCached,
+	varyBlocksCache,
 	warnUncoveredCookies,
 } from "./cache.ts";
 import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import {
 	loadRouteData,
+	emptyDeps,
 	loadMetadata,
+	metadataFailed,
 	renderSSRStream,
 	renderErrorPage,
 	renderPageWithFormData,
 } from "./renderer.ts";
 import { getServerTime } from "../lib/utils.ts";
+import {
+	closeAllSockets,
+	isUpgradeRequest,
+	isUpgraded,
+	closeUpgraded,
+	upgradeRequest,
+	type WebSocketHandler,
+	type WebSocketOptions,
+} from "./websocket.ts";
 
 // ─── User Hooks ──────────────────────────────────────────
 // Set by createApp(). Each runtime entry finds `src/hooks.server.ts` its own
@@ -78,13 +96,14 @@ let userHandle: Handle | null = null;
 // 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.
+// A handler's own Vary is kept: serveCached adds Accept-Encoding to it, so a
+// hit varies on the same headers as the miss did.
 const NON_CACHEABLE_HEADERS = new Set([
 	"content-length",
 	"content-encoding",
 	"transfer-encoding",
 	"content-type",
 	"set-cookie",
-	"vary",
 	"x-bosia-cache",
 ]);
 
@@ -366,6 +385,11 @@ async function serveStaticFile(path: string, request: Request): Promise<Response
 	return null;
 }
 
+// Not Response.redirect(): it rejects relative URLs on Workers.
+function redirectResponse(r: Redirect): Response {
+	return new Response(null, { status: r.status, headers: { Location: r.location } });
+}
+
 async function resolve(event: RequestEvent): Promise<Response> {
 	const { request, url, locals, cookies } = event;
 	const path = url.pathname;
@@ -406,6 +430,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			const runLoad = async () => {
 				// metadata() runs alongside the loaders; the page load() gets its
 				// `data`, as on SSR. A failure stays non-fatal here.
+				const metaDeps = emptyDeps();
 				const metaP = pageMatch
 					? loadMetadata(
 							pageMatch.route,
@@ -414,6 +439,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 							locals,
 							cookies,
 							request,
+							metaDeps,
 						).catch(() => null)
 					: Promise.resolve(null);
 				const data = await loadRouteData(
@@ -438,7 +464,12 @@ async function resolve(event: RequestEvent): Promise<Response> {
 						}
 					: null;
 
-				return { data, metadata, cookiesAccessed: (cookies as CookieJar).accessed };
+				return {
+					data,
+					metadata,
+					metaDeps,
+					cookiesAccessed: (cookies as CookieJar).accessed,
+				};
 			};
 
 			// ── Response cache for client-navigation data ──
@@ -446,9 +477,11 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			// (different masks return different slots), tag/path invalidation, and
 			// no CSP. Only GETs use it (the client router only sends GETs); a
 			// `_fresh` fetch after invalidate() skips the read only.
-			const cacheKey =
-				computeCacheKey(routeUrl, request, cookies as CookieJar) +
-				`|data${invalidatedBits ? `|m=${invalidatedBits}` : ""}`;
+			// Set when this request replaced a stuck leader: its dedup() call,
+			// started right after that gate, is replaced rather than joined.
+			let replaceDedupBefore = -Infinity;
+			const keySuffix = `|data${invalidatedBits ? `|m=${invalidatedBits}` : ""}`;
+			const cacheKey = computeCacheKey(routeUrl, request, cookies as CookieJar) + keySuffix;
 			const dataCacheable =
 				CACHE_ENABLED &&
 				!CSP_ENABLED &&
@@ -457,15 +490,27 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				pageMatch !== null &&
 				(await pageRouteCacheable(pageMatch.route));
 			if (dataCacheable && !fresh) {
+				// Tracking params (CACHE_IGNORE_PARAMS): the plain URL's entry
+				// first, then this URL's own, as before — see cache.ts.
+				const plainUrl = stripIgnoredParams(routeUrl);
+				if (plainUrl !== routeUrl) {
+					const plain = cacheGet(
+						computeCacheKey(plainUrl, request, cookies as CookieJar) + keySuffix,
+					);
+					if (plain && !plain.queryAware) return serveCached(plain, request);
+				}
 				const hit = cacheGet(cacheKey);
 				if (hit) return serveCached(hit, request);
-				const gate = coalesceMiss(cacheKey);
-				if (gate.wait) {
-					await gate.wait;
-					const rehit = cacheGet(cacheKey);
-					if (rehit) return serveCached(rehit, request);
-				} else {
-					releaseDataMiss = gate.release;
+				const claim = await claimMiss(cacheKey, request.signal);
+				if (claim.hit) return serveCached(claim.hit, request);
+				if (claim.aborted) return new Response(null, { status: 499 });
+				if (claim.lead) {
+					releaseDataMiss = claim.lead.release;
+					// It replaced a stuck leader: start a new loader run, which
+					// later requests join, instead of joining the stuck one (a
+					// call that began within 1s of the stuck gate, not a later
+					// healthy one).
+					if (claim.lead.stale) replaceDedupBefore = claim.lead.staleStart + 1000;
 				}
 			}
 
@@ -477,7 +522,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			const dedupK =
 				computeCacheKey(routeUrl, request, cookies as CookieJar) +
 				(invalidatedBits ? `|m=${invalidatedBits}` : "");
-			const result = await dedup(dedupK, runLoad);
+			const result = await dedup(dedupK, runLoad, CACHE_WAIT_TIMEOUT, replaceDedupBefore);
 			// Identity only covers CACHE_KEYS — warn if a loader read a session
 			// cookie outside that list (dedup could then mix users' results).
 			warnUncoveredCookies(cookies);
@@ -503,16 +548,23 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			const body = jsonEncoder.encode(JSON.stringify({ ...payload, metadata: result.metadata }));
 
 			// A loader that said not to store its response is taken at its word.
-			const loaderCc = (loaderHeaders["cache-control"] ?? "").toLowerCase();
-			const loaderOptOut = /no-store|no-cache|private/.test(loaderCc);
+			const loaderOptOut =
+				isNoStoreCacheControl(loaderHeaders["cache-control"]) ||
+				varyBlocksCache(loaderHeaders["vary"]) ||
+				// Failed or timed out: don't keep a copy without its title/meta.
+				metadataFailed(result.metaDeps);
 			let sent: Encoded | null | undefined;
 			if (
 				dataCacheable &&
 				!loaderOptOut &&
 				(cookies as CookieJar).outgoing.length === 0 &&
-				(CACHE_MAX_BODY_BYTES === 0 || body.length <= CACHE_MAX_BODY_BYTES)
+				bodyFitsCache(body.length)
 			) {
 				const tags = collectTags(result.data.layoutDeps ?? null, result.data.pageDeps ?? null);
+				const queryAware = depsReadIgnoredParams(
+					[...(result.data.layoutDeps ?? []), result.metaDeps],
+					result.data.pageDeps ?? null,
+				);
 				const rel = releaseDataMiss;
 				releaseDataMiss = null;
 				// Encoded once at cache quality and shared by response and entry.
@@ -538,6 +590,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 								status: 200,
 								extraHeaders: extra,
 								tags,
+								queryAware,
 							},
 							cookies,
 						);
@@ -612,12 +665,42 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		let releaseApiMiss: (() => void) | null = null;
 		try {
 			const mod = await apiMatch.route.module();
+
+			// WebSocket upgrade — before the response cache, which must never see it.
+			const ws = (mod as { websocket?: WebSocketHandler<any, any> }).websocket;
+			if (ws && isUpgradeRequest(request)) {
+				event.params = apiMatch.params;
+				const result = ws.upgrade ? await ws.upgrade(event) : undefined;
+				if (result instanceof Response) return result;
+				if (isRedirect(result)) {
+					return redirectResponse(result);
+				}
+				if (result !== undefined && (result === null || typeof result !== "object")) {
+					throw new Error(
+						`websocket.upgrade() in ${apiMatch.route.id} must return an object, a Response or nothing`,
+					);
+				}
+				// Cookies a hook set before resolve() ride on the 101; later ones are lost.
+				const headers = new Headers();
+				for (const cookie of (cookies as CookieJar).outgoing) headers.append("Set-Cookie", cookie);
+				return upgradeRequest(ws, result ?? {}, headers);
+			}
+
 			// HEAD falls back to GET (an explicit HEAD export still wins). BosiaApp
 			// strips the body on the way out, for every route kind.
 			const handler = mod[method] ?? (method === "HEAD" ? mod.GET : undefined);
 
 			if (!handler) {
+				// A websocket-only route asked over plain HTTP.
+				if (ws && (method === "GET" || method === "HEAD")) {
+					return new Response("Upgrade Required", {
+						status: 426,
+						headers: { Upgrade: "websocket", Connection: "Upgrade" },
+					});
+				}
 				const allowed = Object.keys(mod).filter((k) => /^[A-Z]+$/.test(k));
+				// A websocket route takes GET (the upgrade's method); HEAD answers 426.
+				if (ws && !allowed.includes("GET")) allowed.push("GET");
 				if (allowed.includes("GET") && !allowed.includes("HEAD")) allowed.push("HEAD");
 				return Response.json(
 					{ error: `Method ${method} not allowed` },
@@ -649,14 +732,10 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				if (apiCacheable && !url.searchParams.has("_invalidated")) {
 					// Miss coalescing: first miss runs the handler; concurrent misses
 					// wait, re-check the cache, and on a still-miss run independently.
-					const gate = coalesceMiss(apiCacheKey);
-					if (gate.wait) {
-						await gate.wait;
-						const rehit = cacheGet(apiCacheKey);
-						if (rehit) return serveCached(rehit, request);
-					} else {
-						releaseApiMiss = gate.release;
-					}
+					const claim = await claimMiss(apiCacheKey, request.signal);
+					if (claim.hit) return serveCached(claim.hit, request);
+					if (claim.aborted) return new Response(null, { status: 499 });
+					if (claim.lead) releaseApiMiss = claim.lead.release;
 				}
 			}
 
@@ -675,10 +754,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 
 			// Redirect returned (not thrown) — convert to a 303 Response.
 			if (isRedirect(handlerResult)) {
-				return new Response(null, {
-					status: handlerResult.status,
-					headers: { Location: handlerResult.location },
-				});
+				return redirectResponse(handlerResult);
 			}
 
 			const response = handlerResult as Response;
@@ -690,11 +766,12 @@ async function resolve(event: RequestEvent): Promise<Response> {
 
 			// Respect handler opt-out via Cache-Control. Standard HTTP semantics:
 			// no-store / private / no-cache all signal "don't reuse this response".
-			const cacheControl = (response.headers.get("cache-control") ?? "").toLowerCase();
+			// A Vary the key can't honor, or a body the handler already encoded
+			// (the entry would replay it without its Content-Encoding), isn't reused.
 			const noStore =
-				cacheControl.includes("no-store") ||
-				cacheControl.includes("private") ||
-				cacheControl.includes("no-cache");
+				isNoStoreCacheControl(response.headers.get("cache-control")) ||
+				varyBlocksCache(response.headers.get("vary")) ||
+				response.headers.has("content-encoding");
 
 			if (
 				apiCacheable &&
@@ -702,7 +779,9 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				response.status === 200 &&
 				!isEventStream &&
 				!noStore &&
-				(cookies as CookieJar).outgoing.length === 0
+				(cookies as CookieJar).outgoing.length === 0 &&
+				// A declared size that can't fit: skip the copy and the read entirely.
+				bodyFitsCache(parseInt(response.headers.get("content-length") ?? "", 10) || 0)
 			) {
 				const cloned = response.clone();
 				const extraHeaders = captureCacheableHeaders(response.headers);
@@ -714,10 +793,10 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				releaseApiMiss = null;
 				deferCacheWrite(async () => {
 					try {
-						const buf = new Uint8Array(await cloned.arrayBuffer());
-						// Oversized bodies skip early so they never pay compression;
-						// cacheSet re-checks as the authoritative guard.
-						if (CACHE_MAX_BODY_BYTES > 0 && buf.length > CACHE_MAX_BODY_BYTES) return;
+						// Stops reading once the body can't fit, so an oversized body
+						// never sits in memory or pays compression; cacheSet re-checks.
+						const buf = await readBodyForCache(cloned);
+						if (buf === null) return;
 						const { gzip, brotli } = buildCompressedVariants(buf);
 						// API endpoints have no LoaderDeps in v0.6 — invalidation is
 						// URL/prefix only. See ROADMAP for deferred tag support.
@@ -747,10 +826,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			// `throw redirect(303, "/")` from a +server.ts handler — turn it into
 			// a real 303 instead of a 500. Mirrors the page-action handler below.
 			if (isRedirect(err)) {
-				return new Response(null, {
-					status: err.status,
-					headers: { Location: err.location },
-				});
+				return redirectResponse(err);
 			}
 			if (isHttpError(err)) {
 				return Response.json({ error: err.message }, { status: err.status });
@@ -1034,9 +1110,10 @@ async function resolve(event: RequestEvent): Promise<Response> {
 // (preview/proxy hubs, design tools, etc.). Other security headers stay on.
 const _xfoDisabled = process.env.DISABLE_X_FRAME_OPTIONS === "true";
 
-// Trust `x-forwarded-proto` header behind a TLS-terminating proxy when computing
-// per-request HTTPS-ness (drives `Secure` cookie flag). Off by default — the
-// header is spoofable from any client that talks directly to the app.
+// Behind a reverse proxy, rebuild the request url from X-Forwarded-Host/-Proto
+// (applyForwarded): event.url, redirects, the CSRF/WebSocket origin checks and
+// the `Secure` cookie flag all follow it. Off by default — the headers are
+// spoofable from any client that talks directly to the app.
 const TRUST_PROXY = process.env.TRUST_PROXY === "true";
 
 const SECURITY_HEADERS: Record<string, string> = {
@@ -1095,7 +1172,10 @@ function finalizeResponse(
 		applyCorsVary(headers);
 		const corsHeaders = getCorsHeaders(request, CORS_CONFIG);
 		if (corsHeaders) {
-			for (const [k, v] of Object.entries(corsHeaders)) headers.set(k, v);
+			// Vary: Origin is already merged in above; set() would drop Accept-Encoding.
+			for (const [k, v] of Object.entries(corsHeaders)) {
+				if (k.toLowerCase() !== "vary") headers.set(k, v);
+			}
 		}
 	}
 	// Apply any Set-Cookie headers accumulated during the request
@@ -1113,19 +1193,7 @@ function finalizeResponse(
 }
 
 async function handleRequest(request: Request, url: URL): Promise<Response> {
-	// Behind a trusted proxy the inbound `Host`/scheme is the proxy's inner hop
-	// (e.g. `localhost:PORT` over plain HTTP), so `url` built from `request.url`
-	// misreports the public origin. Rebuild it from `X-Forwarded-Host`/`-Proto`
-	// so `event.url` — and every absolute redirect, canonical URL, and
-	// `url.origin` the app derives — points at the public-facing origin instead
-	// of localhost. Gated on TRUST_PROXY since these headers are client-spoofable
-	// when no proxy strips them.
-	if (TRUST_PROXY) {
-		const fwdHost = request.headers.get("x-forwarded-host");
-		if (fwdHost) url.host = fwdHost;
-		const fwdProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
-		if (fwdProto) url.protocol = `${fwdProto}:`;
-	}
+	applyForwarded(request, url, TRUST_PROXY);
 
 	// Mounted under BASE_PATH? Everything downstream — hooks, the router, the
 	// /_health and /__bosia tests below — works in app space, so the prefix comes
@@ -1138,6 +1206,16 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		url.pathname = appPath;
 	}
 
+	// No page lives at a `//x` path: anything that echoes it as a URL (the trailing-slash
+	// 308, `page.url`, the client router) would read it as host x. Collapse the slashes.
+	if (url.pathname.startsWith("//")) {
+		return new Response(null, {
+			status: 308,
+			// `base +`, not withBase: withBase skips a path already under base, so `/sso//sso/x` would lose it.
+			headers: { Location: base + url.pathname.replace(/^\/+/, "/") + url.search },
+		});
+	}
+
 	// Bun.serve enforces maxRequestBodySize itself; Workers has no such knob, so
 	// check the declared length here. A chunked upload without Content-Length
 	// falls back to the host's own request cap (Cloudflare: 100MB on free).
@@ -1181,11 +1259,18 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 			console.warn(`[CSRF] Blocked request: ${csrfError}`);
 			return Response.json({ error: "Forbidden", message: csrfError }, { status: 403 });
 		}
+		// A WebSocket upgrade is a GET, so checkCsrf skips it. Checked here, before
+		// the hooks, so a cross-site attempt never reaches a session lookup.
+		const upgradeError = isUpgradeRequest(request)
+			? checkUpgradeOrigin(request, url, CSRF_CONFIG)
+			: null;
+		if (upgradeError) {
+			console.warn(`[CSRF] Blocked WebSocket upgrade: ${upgradeError}`);
+			return Response.json({ error: "Forbidden", message: upgradeError }, { status: 403 });
+		}
 
-		const isHttps =
-			(TRUST_PROXY && request.headers.get("x-forwarded-proto") === "https") ||
-			url.protocol === "https:";
-		cookieJar = new CookieJar(request.headers.get("cookie") ?? "", isHttps);
+		// url already carries the forwarded scheme when TRUST_PROXY is on.
+		cookieJar = new CookieJar(request.headers.get("cookie") ?? "", url.protocol === "https:");
 		nonce = CSP_ENABLED ? generateNonce() : "";
 
 		// Decode the data endpoint before the hooks, not inside resolve(): a guard
@@ -1237,12 +1322,16 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		response ??=
 			userHandle && !warmingUp ? await userHandle({ event, resolve }) : await resolve(event);
 
+		// Bun already answered with 101; there is no response left to finish.
+		if (isUpgraded()) return response;
+
 		// A hook that short-circuits a data request with a redirect is answering
 		// the client router, which speaks JSON — an unconverted 3xx is followed by
 		// `fetch` and the router receives the redirect target's HTML instead.
 		// `Location` is copied verbatim: `redirect()` already rebased it through
 		// `withBase()`, and a raw `Response.redirect` under a BASE_PATH carries the
 		// base by hand, so rebasing here would double the prefix on both.
+
 		if (dataReq && response.status >= 300 && response.status < 400) {
 			const location = response.headers.get("location");
 			if (location) {
@@ -1261,6 +1350,13 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 
 		return finalizeResponse(response, request, nonce, cookieJar);
 	} catch (err) {
+		// Bun already sent the 101, so there is no 500 to send: close the socket
+		// with 1011, the way a handler error does.
+		if (isUpgraded()) {
+			console.error("Hook error after the WebSocket upgrade (socket closed with 1011):", err);
+			closeUpgraded();
+			return new Response(null);
+		}
 		// `throw redirect()` / `throw error()` from a hook lands here — the same
 		// escape hatch loaders have always had. Without these branches both fall
 		// through to the 500 below, which is why the docs could only ever suggest
@@ -1271,8 +1367,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 					? // Shape-identical to the loader conversion below, so the
 						// router has one payload contract regardless of who redirected.
 						Response.json({ redirect: err.location, status: err.status })
-					: // Not Response.redirect(): it rejects relative URLs on Workers.
-						new Response(null, { status: err.status, headers: { Location: err.location } })
+					: redirectResponse(err)
 				: dataReq
 					? Response.json(
 							{
@@ -1339,11 +1434,11 @@ function parseCorsMaxAge(value?: string): number | undefined {
 // Format: "512K", "1M", "1G", plain bytes, or "Infinity".
 // Default: 512K (matches SvelteKit).
 
-function parseBodySizeLimit(value?: string): number {
-	if (!value) return 512 * 1024;
-	if (value === "Infinity") return 0; // Bun: 0 = no limit
+// "Infinity" → 0, Bun's "no limit". `key` names the variable in the error.
+function parseSize(key: string, value: string): number {
+	if (value === "Infinity") return 0;
 	const match = value.match(/^(\d+(?:\.\d+)?)\s*([KMG]?)$/i);
-	if (!match) throw new Error(`Invalid BODY_SIZE_LIMIT: "${value}"`);
+	if (!match) throw new Error(`Invalid ${key}: "${value}"`);
 	const num = parseFloat(match[1]);
 	const unit = match[2].toUpperCase();
 	if (unit === "K") return Math.floor(num * 1024);
@@ -1352,7 +1447,9 @@ function parseBodySizeLimit(value?: string): number {
 	return Math.floor(num);
 }
 
-const BODY_SIZE_LIMIT = parseBodySizeLimit(process.env.BODY_SIZE_LIMIT);
+const BODY_SIZE_LIMIT = process.env.BODY_SIZE_LIMIT
+	? parseSize("BODY_SIZE_LIMIT", process.env.BODY_SIZE_LIMIT)
+	: 512 * 1024;
 
 if (BODY_SIZE_LIMIT === 0) {
 	console.log("📦 Body size limit: none");
@@ -1366,18 +1463,39 @@ if (BODY_SIZE_LIMIT === 0) {
 // Raise when API routes hold streaming responses with long gaps
 // between chunks (e.g. AI tool calls that shell out and wait).
 
-function parseIdleTimeout(value?: string): number {
-	if (!value) return 10;
+// Whole seconds, 0..max. parseInt-lenient ("10s" reads as 10), as it always was.
+function parseSeconds(key: string, value: string | undefined, fallback: number, max: number) {
+	if (!value) return fallback;
 	const n = parseInt(value, 10);
-	if (!Number.isFinite(n) || n < 0) throw new Error(`Invalid IDLE_TIMEOUT: "${value}"`);
-	if (n > 255) throw new Error(`Invalid IDLE_TIMEOUT: "${value}" (max 255)`);
+	if (!Number.isFinite(n) || n < 0) throw new Error(`Invalid ${key}: "${value}"`);
+	if (n > max) throw new Error(`Invalid ${key}: "${value}" (max ${max})`);
 	return n;
 }
 
-const IDLE_TIMEOUT = parseIdleTimeout(process.env.IDLE_TIMEOUT);
+const IDLE_TIMEOUT = parseSeconds("IDLE_TIMEOUT", process.env.IDLE_TIMEOUT, 10, 255);
 
 console.log(`⏱  Idle timeout: ${IDLE_TIMEOUT}s`);
 
+// ─── WebSocket Limits ─────────────────────────────────────
+// Parsed once at startup. Sizes take the BODY_SIZE_LIMIT format ("16M").
+// WS_IDLE_TIMEOUT is seconds without a frame before Bun closes the socket; Bun
+// pings idle sockets on its own, so a live peer never hits it.
+
+// Bun has no "no limit" for these, so 0 and "Infinity" are refused.
+function parseWsSize(key: string, value?: string): number {
+	if (!value) return 16 * 1024 * 1024;
+	const n = parseSize(key, value);
+	if (n === 0) throw new Error(`Invalid ${key}: "${value}" (must be above 0)`);
+	return n;
+}
+
+const WEBSOCKET_OPTIONS: WebSocketOptions = {
+	maxPayloadLength: parseWsSize("WS_MAX_PAYLOAD", process.env.WS_MAX_PAYLOAD),
+	idleTimeout: parseSeconds("WS_IDLE_TIMEOUT", process.env.WS_IDLE_TIMEOUT, 120, 960),
+	backpressureLimit: parseWsSize("WS_BACKPRESSURE_LIMIT", process.env.WS_BACKPRESSURE_LIMIT),
+	perMessageDeflate: process.env.WS_COMPRESS === "true",
+};
+
 // ─── 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,
@@ -1412,6 +1530,8 @@ let drainResolve: (() => void) | null = null;
 /** Stop taking new requests; resolves once in-flight ones have finished. */
 export function beginShutdown(): Promise<void> {
 	shuttingDown = true;
+	// 1001 "going away": clients reconnect, to this server's replacement.
+	closeAllSockets();
 	if (inFlight === 0) return Promise.resolve();
 	return new Promise<void>((r) => {
 		drainResolve = r;
@@ -1476,6 +1596,7 @@ export async function createApp(options: CreateAppOptions = {}): Promise<BosiaAp
 			// splits traffic between two different builds. Opt in only for deliberate
 			// N-worker clustering.
 			reusePort: process.env.BOSIA_REUSE_PORT === "1",
+			websocket: WEBSOCKET_OPTIONS,
 		},
 	});
 

package/src/core/server.workers.ts

@@ -29,7 +29,7 @@ const quiet = { log: console.log, warn: console.warn, error: console.error };
 console.log = console.warn = console.error = () => {};
 setWarmingUp(true);
 try {
-	await app.fetch(new Request("http://localhost/"));
+	await app.fetchUnobserved(new Request("http://localhost/"));
 } catch {
 	// best effort
 } finally {
@@ -41,6 +41,7 @@ export default {
 	fetch(request: Request, env: PlatformEnv): Response | Promise<Response> {
 		// Bindings are one object per isolate — capture on the first request.
 		if (!getPlatform()) setPlatform({ env });
-		return app.fetch(request);
+		// No `server` passed, so nothing is ever upgraded and a Response always comes back.
+		return app.fetch(request) as Promise<Response>;
 	},
 };

package/src/core/types/plugin.ts

@@ -35,7 +35,8 @@ export interface BosiaPlugin {
 
 	/**
 	 * Mount points around the framework's HTTP backend — Bosia's own small,
-	 * Elysia-shaped app (`get/post/…`, `onRequest`, `onAfterHandle`, `onError`).
+	 * Elysia-shaped app (`get/post/…`, `onRequest`, `onAfterHandle`, `onError`,
+	 * and observe-only `onResponse` for logging/metrics on the final response).
 	 */
 	backend?: {
 		/** Runs before framework middleware/routes — can register routes that bypass Bosia. */