bosia 1.2.6 → 1.2.7

package/src/core/devWsProxy.ts

@@ -0,0 +1,144 @@
+// ─── Dev Proxy: WebSockets ────────────────────────────────
+// The dev proxy forwards HTTP with fetch(), which can't carry an upgrade. This
+// opens the app's socket first and upgrades the client only once the app has
+// accepted, so a refusal reaches the client as a failed handshake — what a
+// browser sees in prod too (it never learns the status). Then frames are piped
+// both ways, type kept.
+//
+// Simple version: no backpressure across the proxy hop, frames sent during a
+// restart are dropped, and cookies the app sets on its 101 don't reach the
+// client (Bun's client WebSocket doesn't expose handshake headers). If that
+// ever matters, buffer with a cap (close with 1013 past it) and do the
+// upstream handshake over a raw socket to read its headers.
+
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+
+import { closeEach } from "./websocket.ts";
+
+interface ProxyData {
+	upstream: WebSocket;
+	client: ServerWebSocket<ProxyData> | null;
+	/** Frames the app sent before the client socket opened. */
+	pending: (string | ArrayBuffer)[];
+	/** The app closed before the client socket opened. */
+	early: { code: number; reason: string } | null;
+}
+
+// Handshake headers belong to each hop; everything else (cookie,
+// authorization, origin, x-forwarded-*) goes through to the app.
+const HOP_HEADERS = new Set([
+	"host",
+	"connection",
+	"upgrade",
+	"content-length",
+	"sec-websocket-key",
+	"sec-websocket-version",
+	"sec-websocket-extensions",
+	"sec-websocket-protocol",
+]);
+
+const UPSTREAM_TIMEOUT_MS = 10_000;
+
+const proxied = new Set<ServerWebSocket<ProxyData>>();
+
+/**
+ * A close code `close()` accepts. 1005/1006/1015 only describe a close:
+ * 1005 (no code) becomes 1000, 1006/1015 (connection lost) become `lost`.
+ * Reserved or out-of-range codes become 1000; Bun's client close() throws on them.
+ */
+export function toSendableCode(code: number, lost: number): number {
+	if (code === 1006 || code === 1015) return lost;
+	const valid =
+		(code >= 1000 && code <= 1003) ||
+		(code >= 1007 && code <= 1014) ||
+		(code >= 3000 && code <= 4999);
+	return valid ? code : 1000;
+}
+
+/**
+ * Upgrade `req` through to `target` (an http:// URL on the app server).
+ * Returns undefined once upgraded, or the Response to send instead.
+ */
+export async function proxyUpgrade(
+	req: Request,
+	server: Server<ProxyData>,
+	target: URL,
+	inHeaders: Headers,
+): Promise<Response | undefined> {
+	const headers: Record<string, string> = {};
+	for (const [k, v] of inHeaders) if (!HOP_HEADERS.has(k.toLowerCase())) headers[k] = v;
+	const protocols =
+		req.headers
+			.get("sec-websocket-protocol")
+			?.split(",")
+			.map((p) => p.trim())
+			.filter(Boolean) ?? [];
+
+	const url = new URL(target);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	const upstream = new WebSocket(url.href, { headers, protocols } as any);
+	upstream.binaryType = "arraybuffer";
+	const data: ProxyData = { upstream, client: null, pending: [], early: null };
+
+	upstream.addEventListener("message", (e) => {
+		if (data.client) data.client.send(e.data);
+		else data.pending.push(e.data);
+	});
+	upstream.addEventListener("close", (e) => {
+		if (!data.client) data.early = { code: e.code, reason: e.reason };
+		else if (proxied.has(data.client)) data.client.close(toSendableCode(e.code, 1011), e.reason);
+	});
+
+	const opened = await new Promise<boolean>((resolve) => {
+		const timer = setTimeout(() => resolve(false), UPSTREAM_TIMEOUT_MS);
+		const done = (ok: boolean) => {
+			clearTimeout(timer);
+			resolve(ok);
+		};
+		upstream.addEventListener("open", () => done(true), { once: true });
+		upstream.addEventListener("error", () => done(false), { once: true });
+		upstream.addEventListener("close", () => done(false), { once: true });
+	});
+	if (!opened) {
+		upstream.close();
+		return new Response("WebSocket upgrade refused by app", { status: 502 });
+	}
+
+	const ok = server.upgrade(req, {
+		data,
+		headers: new Headers(upstream.protocol ? { "Sec-WebSocket-Protocol": upstream.protocol } : {}),
+	});
+	if (ok) return undefined;
+	upstream.close();
+	return new Response("Bad WebSocket handshake", { status: 400 });
+}
+
+export const proxyHandlers: WebSocketHandler<ProxyData> = {
+	// The app enforces WS_MAX_PAYLOAD (and closes with 1009, passed through);
+	// the proxy must not cut frames off at Bun's 16 MB default first.
+	maxPayloadLength: 2 ** 30,
+	open(ws) {
+		const data = ws.data;
+		data.client = ws;
+		proxied.add(ws);
+		for (const frame of data.pending) ws.send(frame);
+		data.pending = [];
+		if (data.early) ws.close(toSendableCode(data.early.code, 1011), data.early.reason);
+	},
+	message(ws, message) {
+		const { upstream } = ws.data;
+		if (upstream.readyState === WebSocket.OPEN) upstream.send(message);
+	},
+	close(ws, code, reason) {
+		proxied.delete(ws);
+		const { upstream } = ws.data;
+		if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) {
+			upstream.close(toSendableCode(code, 1001), reason);
+		}
+	},
+};
+
+/** Close every proxied client — 1012 on a rebuild, so clients reconnect to the new app. */
+export function closeProxiedSockets(code: number, reason: string): void {
+	closeEach(proxied, code, reason);
+}

package/src/core/env.ts

@@ -24,6 +24,10 @@ const FRAMEWORK_VARS = new Set([
 	"PRERENDER_CONCURRENCY",
 	"IDLE_TIMEOUT",
 	"MAX_INFLIGHT",
+	"WS_MAX_PAYLOAD",
+	"WS_IDLE_TIMEOUT",
+	"WS_BACKPRESSURE_LIMIT",
+	"WS_COMPRESS",
 	"TRUST_PROXY",
 	"CSP_DIRECTIVES",
 	"DISABLE_X_FRAME_OPTIONS",

package/src/core/errors.ts

@@ -1,7 +1,7 @@
 // ─── Error / Redirect Helpers ────────────────────────────
 // Throw these from load() functions; the server catches and handles them.
 
-import { withBase } from "./basePath.ts";
+import { DANGEROUS_PROTOCOL, withBase } from "./basePath.ts";
 import { currentBase } from "./appBase.ts";
 
 // Identity across bundle boundaries. `dist/hooks.server.js` keeps "bosia"
@@ -59,17 +59,26 @@ export class Redirect {
 (HttpError.prototype as any)[HTTP_ERROR_BRAND] = true;
 (Redirect.prototype as any)[REDIRECT_BRAND] = true;
 
-const DANGEROUS_SCHEMES = /^(javascript|data|vbscript):/i;
+// Any parseable origin works as the base: only "did it stay on it?" is asked.
+const SELF = "http://bosia.invalid";
 
 function validateRedirectLocation(location: string, options?: RedirectOptions): void {
 	const trimmed = location.trim();
+	// Parsed like the browser will parse the Location: `java\tscript:` is javascript:,
+	// `htt\tps://evil.com` and `/\\evil.com` are another origin.
+	let url: URL;
+	try {
+		url = new URL(trimmed, SELF);
+	} catch {
+		throw new Error(`redirect(): invalid URL "${location}".`);
+	}
 
 	// Dangerous schemes are rejected even when `allowExternal: true` —
 	// `javascript:` / `data:` / `vbscript:` are never legitimate redirect targets.
-	if (DANGEROUS_SCHEMES.test(trimmed)) {
+	if (DANGEROUS_PROTOCOL.test(url.protocol)) {
 		throw new Error(
 			`redirect(): dangerous scheme in URL "${location}". ` +
-				`Only relative paths and same-origin URLs are allowed.`,
+				`Use a relative path or an http(s) URL with { allowExternal: true }.`,
 		);
 	}
 
@@ -83,8 +92,16 @@ function validateRedirectLocation(location: string, options?: RedirectOptions):
 		);
 	}
 
-	// Allow relative paths (no scheme)
-	if (!/^[a-zA-Z][a-zA-Z0-9+\-.]*:/.test(trimmed)) return;
+	// Relative only when it isn't a URL on its own: `http:evil.com` resolves against
+	// SELF as a path, but on an https page the browser reads it as http://evil.com.
+	// try/new URL, not URL.canParse: this file ships to browsers without it (Safari < 17).
+	let absolute = true;
+	try {
+		new URL(trimmed);
+	} catch {
+		absolute = false;
+	}
+	if (!absolute && url.origin === SELF) return;
 
 	// It's an absolute URL — reject external origins
 	throw new Error(

package/src/core/plugins/access-log.ts

@@ -111,11 +111,11 @@ export function accessLog(options: AccessLogOptions = {}): BosiaPlugin {
 			before(app) {
 				// onResponse swallows a throw here (a broken filter/format/sink),
 				// so logging can never change or fail a response.
-				return app.onResponse(({ request, response, start }) => {
+				return app.onResponse(({ request, status, start }) => {
 					log({
 						method: request.method,
 						path: pathOf(request.url),
-						status: response.status,
+						status,
 						ms: performance.now() - start,
 						request,
 					});

package/src/core/proxy.ts

@@ -0,0 +1,48 @@
+// Behind a reverse proxy the inbound `Host`/scheme is the proxy's inner hop
+// (e.g. `localhost:PORT` over plain HTTP). X-Forwarded-Host/-Proto carry the
+// public origin, but any client can send them, so they count only when the
+// operator sets TRUST_PROXY=true.
+
+/**
+ * First value of an `X-Forwarded-*` header: each proxy in a chain appends its
+ * own ("https, http"), and the first is the client-facing one.
+ */
+function firstForwarded(request: Request, name: string): string | undefined {
+	return request.headers.get(name)?.split(",")[0]?.trim() || undefined;
+}
+
+const SCHEMES: Record<string, string> = {
+	http: "http:",
+	https: "https:",
+	// Traefik sends ws/wss on upgrades; the origin a browser sends is http(s).
+	ws: "http:",
+	wss: "https:",
+};
+
+/**
+ * Point `url` at the public origin from X-Forwarded-Host/-Proto, in place, so
+ * `event.url`, redirects and the CSRF/WebSocket origin checks all see it.
+ * Does nothing unless `trustProxy`. A malformed host leaves `url` as it was,
+ * scheme included; an unknown scheme is ignored.
+ */
+export function applyForwarded(request: Request, url: URL, trustProxy: boolean): void {
+	if (!trustProxy) return;
+	const proto = SCHEMES[firstForwarded(request, "x-forwarded-proto")?.toLowerCase() ?? ""];
+	const host = firstForwarded(request, "x-forwarded-host");
+	let parsed: URL | undefined;
+	if (host) {
+		// The parser would quietly keep part of `evil.com@app.com` or `app.com/x`.
+		if (/[\s/?#@\\]/.test(host)) return;
+		try {
+			parsed = new URL(`${proto ?? url.protocol}//${host}`);
+		} catch {
+			return;
+		}
+	}
+	if (proto) url.protocol = proto;
+	if (parsed) {
+		// hostname + port, not `host`: setting `host` without a port keeps the inner one.
+		url.hostname = parsed.hostname;
+		url.port = parsed.port;
+	}
+}

package/src/core/renderer.ts

@@ -76,7 +76,7 @@ const enc = new TextEncoder();
 //
 // `url` is app-space (server.ts strips BASE_PATH exactly once, at the top of
 // handleRequest), but every value the client half writes to these fields is
-// browser-space: hydrate.ts assigns raw window.location.pathname, and
+// browser-space: hydrate.ts assigns locationPath() (the address bar), and
 // clientRoutes are generated with the prefix already in them. So the base goes
 // back on before seeding, or a mounted app server-renders `/admin/audit` and
 // hydration flips it to `/sso/admin/audit`.

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";
@@ -74,6 +75,15 @@ import {
 	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
@@ -375,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;
@@ -650,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` },
@@ -709,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;
@@ -784,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 });
@@ -1071,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> = {
@@ -1153,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
@@ -1178,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).
@@ -1221,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
@@ -1277,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) {
@@ -1301,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
@@ -1311,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(
 							{
@@ -1379,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);
@@ -1392,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");
@@ -1406,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,
@@ -1452,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;
@@ -1516,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

@@ -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>;
 	},
 };