bosia 1.2.6 → 1.2.8

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";
@@ -72,8 +73,18 @@ import {
 	renderSSRStream,
 	renderErrorPage,
 	renderPageWithFormData,
+	routeCacheFlag,
 } 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
@@ -213,7 +224,7 @@ function parseDataRequest(url: URL): DataRequest | "invalid" | null {
 	let fresh = false;
 	for (const [key, val] of url.searchParams.entries()) {
 		if (key === "_invalidated") {
-			invalidatedBits = val;
+			invalidatedBits = val; // last wins: the client appends its mask after the page's query
 			continue;
 		}
 		// Set by the client router when the fetch follows an invalidate():
@@ -224,6 +235,11 @@ function parseDataRequest(url: URL): DataRequest | "invalid" | null {
 		}
 		routeUrl.searchParams.append(key, val);
 	}
+	// Only a 0/1 mask counts: it goes into the cache key, where a stray `?` or
+	// `|o=` would file the entry under the wrong path for invalidate(). Anything
+	// else runs and sends every loader, as having no mask does. A page's own 0/1
+	// `?_invalidated=` with no client mask after it is still read as the mask.
+	if (invalidatedBits !== null && !/^[01]*$/.test(invalidatedBits)) invalidatedBits = null;
 	return { routeUrl, invalidatedBits, fresh };
 }
 
@@ -281,17 +297,9 @@ function routesFor(
 
 const jsonEncoder = new TextEncoder();
 
-/** A page route's `export const cache` flag: the build-time read when it has
- *  one, otherwise the compiled page module's own export (see renderer.ts). */
-async function pageRouteCacheable(route: (typeof serverRoutes)[number]): Promise<boolean> {
-	const flag = (route as { cache?: boolean | null }).cache;
-	if (flag === true || flag === false) return flag;
-	return (await route.pageModule()).cache !== false;
-}
-
 /**
  * Decode an `_invalidated` bitmask string. Char 0 = page, char i+1 = layout
- * depth i. Only '0' has a meaning; any other char counts as '1'.
+ * depth i. Only 0/1 reach here: parseDataRequest drops any other mask.
  *   - Page '0': skip the page loader.
  *   - Layout '0': omit its data from the response. The loader still runs,
  *     since it may be a guard.
@@ -375,6 +383,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;
@@ -473,7 +486,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				!warmingUp &&
 				method === "GET" &&
 				pageMatch !== null &&
-				(await pageRouteCacheable(pageMatch.route));
+				(await routeCacheFlag(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.
@@ -650,12 +663,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 +752,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 +824,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 +1108,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 +1191,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 +1204,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 +1257,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 +1320,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 +1348,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 +1365,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 +1432,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 +1445,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 +1461,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 +1528,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;
@@ -1480,7 +1558,6 @@ function loadBuiltManifest(): RouteManifest {
 			layoutServers: [],
 			errorPages: [],
 			trailingSlash: r.trailingSlash,
-			cache: r.cache ?? null,
 			prerender: false,
 		})),
 		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, id: r.id, server: "" })),
@@ -1516,6 +1593,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>;
 	},
 };

package/src/core/types.ts

@@ -28,14 +28,6 @@ export interface PageRoute {
 	errorPages: { path: string; depth: number }[];
 	/** Effective trailing-slash mode (page wins over layout chain). Defaults to "never". */
 	trailingSlash: TrailingSlash;
-	/**
-	 * Build-time read of `export const cache` in +page.svelte, so the renderer can
-	 * decide cacheability on a cache hit without importing the page module:
-	 *   `true`  — no `cache` export → cacheable
-	 *   `false` — statically `cache = false` → opted out
-	 *   `null`  — a `cache` export exists but isn't a literal `false` (dynamic) → import at runtime
-	 */
-	cache: boolean | null;
 	/** `export const prerender = true` in +page.server.ts — its data is a static file at runtime. */
 	prerender: boolean;
 }

package/src/core/websocket.ts

@@ -0,0 +1,232 @@
+// ─── WebSockets (Bun only) ────────────────────────────────
+// A `+server.ts` exports `websocket = { upgrade?, open, message, close, … }`.
+// resolve() runs `upgrade()` after the hooks, then hands the request to Bun's
+// `server.upgrade()`. Bun.serve takes one websocket handler for the whole
+// server, so the upgrade carries the route's handlers in an envelope; open()
+// keeps them per socket and sets `ws.data` to what upgrade() returned.
+//
+// Subprotocols are not selectable yet: `upgrade()` returns only data. To add
+// it, let the export declare `protocols: string[]` and send the first one the
+// client offers as `Sec-WebSocket-Protocol` in server.upgrade's headers. The
+// dev proxy already passes it through.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { Server, ServerWebSocket, WebSocketHandler as BunWebSocketHandler } from "bun";
+
+import type { RequestEvent } from "./hooks.ts";
+
+/** What a `+server.ts` exports as `websocket`. `ws` is Bun's ServerWebSocket. */
+export interface WebSocketHandler<T extends object = {}, E = RequestEvent> {
+	/**
+	 * Runs after `hooks.server.ts`, so `event.locals` is set. Return the
+	 * connection's `ws.data` (a fresh object per connection), or a Response to
+	 * refuse. A thrown `error()` / `redirect()` answers like an API handler.
+	 */
+	upgrade?(event: E): T | Response | void | Promise<T | Response | void>;
+	open?(ws: ServerWebSocket<T>): unknown;
+	/** `string` for text frames, `Buffer` for binary frames. */
+	message?(ws: ServerWebSocket<T>, message: string | Buffer): unknown;
+	/** The socket can take more data again after `send()` returned -1. */
+	drain?(ws: ServerWebSocket<T>): unknown;
+	close?(ws: ServerWebSocket<T>, code: number, reason: string): unknown;
+	ping?(ws: ServerWebSocket<T>, data: Buffer): unknown;
+	pong?(ws: ServerWebSocket<T>, data: Buffer): unknown;
+}
+
+export interface WebSocketOptions {
+	maxPayloadLength: number;
+	idleTimeout: number;
+	backpressureLimit: number;
+	perMessageDeflate: boolean;
+}
+
+type Socket = ServerWebSocket<any>;
+
+/** What server.upgrade() carries until open() unwraps it. */
+class Envelope {
+	constructor(
+		readonly handler: WebSocketHandler<any, any>,
+		readonly data: object,
+	) {}
+}
+
+// Per socket, not on ws.data: one object returned by two routes (a cached
+// session user, say) must not carry either route's handlers.
+const routeOf = new WeakMap<Socket, WebSocketHandler<any, any>>();
+
+// Sec-WebSocket-Key too: a stray Upgrade header on a plain GET (a proxy, a
+// scanner) must reach the GET handler, not run upgrade() and then 400.
+export function isUpgradeRequest(request: Request): boolean {
+	return (
+		request.method === "GET" &&
+		request.headers.get("upgrade")?.toLowerCase() === "websocket" &&
+		request.headers.has("sec-websocket-key")
+	);
+}
+
+// One per upgrade request, set by BosiaApp.fetch. It holds the Request Bun gave
+// (server.upgrade() needs that one, and a hook may pass resolve() a new one)
+// and whether the upgrade happened — a per-request flag, so a hook that
+// rebuilds or mutates the returned Response can't hide or leak it.
+interface UpgradeContext {
+	request?: Request;
+	server?: Server<any>;
+	upgraded: boolean;
+	/** Set by open(), which Bun runs inside server.upgrade(). */
+	socket?: Socket;
+}
+
+const upgrades = new AsyncLocalStorage<UpgradeContext>();
+
+export async function runUpgrade<T>(
+	request: Request,
+	server: Server<any>,
+	fn: () => Promise<T>,
+): Promise<T> {
+	const ctx: UpgradeContext = { request, server, upgraded: false };
+	try {
+		return await upgrades.run(ctx, fn);
+	} finally {
+		// A timer or pool started during this request keeps the context: it must
+		// not hold the Request, nor see isUpgraded() in its own later fetches.
+		ctx.request = ctx.server = ctx.socket = undefined;
+		ctx.upgraded = false;
+	}
+}
+
+/** True once this request has been upgraded: Bun already sent the 101. */
+export function isUpgraded(): boolean {
+	return upgrades.getStore()?.upgraded === true;
+}
+
+/** A hook threw after the 101: close the socket, as a handler error would. */
+export function closeUpgraded(): void {
+	const ws = upgrades.getStore()?.socket;
+	if (ws) closeEach([ws], 1011, "Internal error");
+}
+
+let closing = false;
+
+// Bun answers without a protocol, so a browser that asked for one fails the
+// handshake with no error on the server. Warn once per route, not per connect.
+const warnedProtocol = new WeakSet<WebSocketHandler<any, any>>();
+
+function warnProtocol(handler: WebSocketHandler<any, any>, request: Request): void {
+	const asked = request.headers.get("sec-websocket-protocol");
+	if (!asked || warnedProtocol.has(handler)) return;
+	warnedProtocol.add(handler);
+	console.warn(
+		`[WebSocket] ${new URL(request.url).pathname}: the client asked for Sec-WebSocket-Protocol ` +
+			`"${asked}", but Bosia can't pick one yet. Browsers fail this handshake; drop the ` +
+			`protocols argument from new WebSocket().`,
+	);
+}
+
+/**
+ * Upgrade the current request with `data` as `ws.data`. Returns a placeholder
+ * Response (Bun ignores it; isUpgraded() is the signal), or the Response to
+ * send instead (bad handshake, a runtime without WebSockets).
+ */
+export function upgradeRequest(
+	handler: WebSocketHandler<any, any>,
+	data: object,
+	headers: Headers,
+): Response {
+	const ctx = upgrades.getStore();
+	if (!ctx?.request || !ctx.server) {
+		return new Response("WebSockets are not supported here", { status: 501 });
+	}
+	warnProtocol(handler, ctx.request);
+	if (!ctx.server.upgrade(ctx.request, { data: new Envelope(handler, data) as any, headers })) {
+		return new Response("Bad WebSocket handshake", { status: 400 });
+	}
+	ctx.upgraded = true;
+	return new Response(null, { status: 200 });
+}
+
+// ─── Shared Bun handlers ─────────────────────────────────
+
+const sockets = new Set<Socket>();
+
+function fail(ws: Socket, err: unknown): void {
+	console.error("WebSocket handler error:", err);
+	closeEach([ws], 1011, "Internal error");
+}
+
+// A user handler's throw or rejection closes that socket with 1011; it must
+// never reach the prod `uncaughtException` handler, which exits the process.
+//
+// Bun runs open() inside server.upgrade(), so in the upgrade request's async
+// context; exit() it, so a timer or callback started in open() doesn't hold
+// that request or see isUpgraded() in its own in-process fetches. (Other
+// events run outside it; exit() is then a no-op.)
+function run(ws: Socket, name: Exclude<keyof WebSocketHandler, "upgrade">, args: unknown[]): void {
+	upgrades.exit(() => call(ws, name, args));
+}
+
+function call(ws: Socket, name: Exclude<keyof WebSocketHandler, "upgrade">, args: unknown[]): void {
+	const handler = routeOf.get(ws);
+	const fn = handler?.[name] as ((...a: unknown[]) => unknown) | undefined;
+	if (!fn) return;
+	try {
+		const out = fn.call(handler, ws, ...args);
+		if (out instanceof Promise) out.catch((err) => fail(ws, err));
+	} catch (err) {
+		fail(ws, err);
+	}
+}
+
+export const websocketHandlers: BunWebSocketHandler<any> = {
+	open(ws) {
+		// The very object upgrade() returned becomes ws.data (an app may keep it
+		// in a registry).
+		const envelope = ws.data as Envelope;
+		routeOf.set(ws, envelope.handler);
+		ws.data = envelope.data;
+		sockets.add(ws);
+		const ctx = upgrades.getStore();
+		if (ctx) ctx.socket = ws;
+		run(ws, "open", []);
+		// An upgrade still in its async upgrade() during the shutdown sweep opens
+		// after it: the app has seen open() and gets close(), so it can clean up.
+		if (closing) ws.close(1001, "Server shutting down");
+	},
+	message(ws, message) {
+		run(ws, "message", [message]);
+	},
+	drain(ws) {
+		run(ws, "drain", []);
+	},
+	close(ws, code, reason) {
+		sockets.delete(ws);
+		run(ws, "close", [code, reason]);
+	},
+	ping(ws, data) {
+		run(ws, "ping", [data]);
+	},
+	pong(ws, data) {
+		run(ws, "pong", [data]);
+	},
+};
+
+/** Shutdown: close every open socket with 1001 (clients reconnect elsewhere),
+ *  and any that opens from here on. */
+export function closeAllSockets(): void {
+	closing = true;
+	closeEach(sockets, 1001, "Server shutting down");
+}
+
+export function closeEach(
+	list: Iterable<ServerWebSocket<any>>,
+	code: number,
+	reason: string,
+): void {
+	for (const ws of [...list]) {
+		try {
+			ws.close(code, reason);
+		} catch {
+			/* already closed */
+		}
+	}
+}

package/src/core/workersGuard.ts

@@ -19,6 +19,7 @@ export interface WorkersGuardHit {
 }
 
 const SERVER_FILE = /(^|\/)(hooks\.server\.(ts|js)|\+server\.(ts|js)|\+[^/]*\.server\.(ts|js))$/;
+const API_FILE = /(^|\/)\+server\.(ts|js)$/;
 const LIB_SERVER = /^lib\/server\/.*\.(ts|js)$/;
 const FS_MODULES = new Set(["fs", "node:fs", "fs/promises", "node:fs/promises"]);
 
@@ -54,13 +55,27 @@ export function findWorkersIncompatible(srcDir = "./src"): WorkersGuardHit[] {
 		const lines = source.split("\n");
 
 		let imports: { path: string }[] = [];
+		let exports: string[] = [];
 		try {
-			imports = new Bun.Transpiler({ loader: rel.endsWith(".js") ? "js" : "ts" }).scan(
-				source,
-			).imports;
+			({ imports, exports } = new Bun.Transpiler({
+				loader: rel.endsWith(".js") ? "js" : "ts",
+			}).scan(source));
 		} catch {
 			continue; // syntax error — the real build reports it better
 		}
+		// Any export form (`const`, `let`, `export { websocket }`) shows up here.
+		if (API_FILE.test(rel) && exports.includes("websocket")) {
+			const i = Math.max(
+				0,
+				lines.findIndex((l) => /\bwebsocket\b/.test(l) && /\bexport\b/.test(l)),
+			);
+			hits.push({
+				file,
+				line: i + 1,
+				col: 1,
+				message: "exports `websocket` — WebSockets are Bun-only for now",
+			});
+		}
 		for (const { path } of imports) {
 			const message = badImport(path);
 			if (!message) continue;

package/src/lib/index.ts

@@ -34,6 +34,7 @@ export type {
 	PlatformEnv,
 } from "../core/hooks.ts";
 export type { CsrfConfig } from "../core/csrf.ts";
+export type { WebSocketHandler } from "../core/websocket.ts";
 export type { CorsConfig } from "../core/cors.ts";
 export { defineConfig } from "../core/types/plugin.ts";
 export type {