bosia 1.2.5 → 1.2.7

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 {

package/templates/default/.env.example

@@ -48,6 +48,20 @@ 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
+# Memory for all cached responses together, in bytes (0 = entry count only).
+# CACHE_MAX_BYTES=104857600
+# Query params left out of the page cache key: a link with ?utm_source=… or
+# ?fbclid=… gets the cached page of the same URL without them, instead of a new
+# render per ad click. Comma-separated; `name*` matches a prefix; `none` turns
+# it off. Without that cached page, or when load()/metadata() reads one of
+# these params, the full URL is cached on its own, as before.
+# Defaults to the list below. Setting it replaces the list.
+# CACHE_IGNORE_PARAMS=utm_*,fbclid,gclid,gbraid,wbraid,dclid,msclkid,twclid,ttclid,li_fat_id,igshid,yclid,mc_cid,mc_eid,_ga,_gl
+# How long a request waits for another one building the same cached response
+# before building it itself, in ms, so one that hangs can't block its URL.
+# 0 or Infinity = wait for it. Defaults to 60000 (60s), or METADATA_TIMEOUT +
+# LOAD_TIMEOUT + 10s when that is longer.
+# CACHE_WAIT_TIMEOUT=60000
 
 # Static files and prerendered pages are kept in memory after their first
 # request (Bun only; ignored on Cloudflare Workers). Total budget in bytes,
@@ -56,13 +70,14 @@ PUBLIC_STATIC_APP_NAME=My Bosia App
 # 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
+# Timeout for load() functions (layout + page) in milliseconds. Defaults to 30000 (30s).
+# A page's time includes its `await parent()`. Bun drops a silent connection after
+# IDLE_TIMEOUT (10s): raise it too for slower loaders. Set to 0 or Infinity to disable.
+# LOAD_TIMEOUT=30000
 
-# Timeout for metadata() functions in milliseconds. Defaults to 3000 (3s).
+# Timeout for metadata() functions in milliseconds. Defaults to 10000 (10s).
 # Set to 0 or Infinity to disable.
-# METADATA_TIMEOUT=3000
+# METADATA_TIMEOUT=10000
 
 # Timeout for prerender fetches during build in milliseconds. Defaults to 5000 (5s).
 # Set to 0 or Infinity to disable.

package/templates/default/tsconfig.json

@@ -9,7 +9,7 @@
 		"allowImportingTsExtensions": true,
 		"noEmit": true,
 		"verbatimModuleSyntax": true,
-		"types": ["bun-types"],
+		"types": ["bun"],
 		"lib": ["dom", "dom.iterable", "esnext"],
 		"rootDirs": [".", ".bosia/types"],
 		"paths": {

package/templates/demo/.env.example

@@ -15,6 +15,20 @@ BODY_SIZE_LIMIT=512K
 # Per-user pages stay isolated. Disable per-route with `export const cache = false`.
 # CACHE_KEYS=session,sid,auth,token,jwt,Authorization
 # CACHE_MAX_ENTRIES=500
+# Memory for all cached responses together, in bytes (0 = entry count only).
+# CACHE_MAX_BYTES=104857600
+# Query params left out of the page cache key: a link with ?utm_source=… or
+# ?fbclid=… gets the cached page of the same URL without them, instead of a new
+# render per ad click. Comma-separated; `name*` matches a prefix; `none` turns
+# it off. Without that cached page, or when load()/metadata() reads one of
+# these params, the full URL is cached on its own, as before.
+# Defaults to the list below. Setting it replaces the list.
+# CACHE_IGNORE_PARAMS=utm_*,fbclid,gclid,gbraid,wbraid,dclid,msclkid,twclid,ttclid,li_fat_id,igshid,yclid,mc_cid,mc_eid,_ga,_gl
+# How long a request waits for another one building the same cached response
+# before building it itself, in ms, so one that hangs can't block its URL.
+# 0 or Infinity = wait for it. Defaults to 60000 (60s), or METADATA_TIMEOUT +
+# LOAD_TIMEOUT + 10s when that is longer.
+# CACHE_WAIT_TIMEOUT=60000
 
 # Static files and prerendered pages are kept in memory after their first
 # request (Bun only; ignored on Cloudflare Workers). Total budget in bytes,
@@ -59,13 +73,14 @@ CORS_ALLOWED_ORIGINS=
 # Default: 86400 (24 hours)
 # CORS_MAX_AGE=86400
 
-# Timeout for load() functions (layout + page) in milliseconds. Defaults to 5000 (5s).
-# Set to 0 or Infinity to disable.
-# LOAD_TIMEOUT=5000
+# Timeout for load() functions (layout + page) in milliseconds. Defaults to 30000 (30s).
+# A page's time includes its `await parent()`. Bun drops a silent connection after
+# IDLE_TIMEOUT (10s): raise it too for slower loaders. Set to 0 or Infinity to disable.
+# LOAD_TIMEOUT=30000
 
-# Timeout for metadata() functions in milliseconds. Defaults to 3000 (3s).
+# Timeout for metadata() functions in milliseconds. Defaults to 10000 (10s).
 # Set to 0 or Infinity to disable.
-# METADATA_TIMEOUT=3000
+# METADATA_TIMEOUT=10000
 
 # Timeout for prerender fetches during build in milliseconds. Defaults to 5000 (5s).
 # Set to 0 or Infinity to disable.

package/templates/demo/src/hooks.server.ts

@@ -1,4 +1,3 @@
-import { sequence } from "bosia";
 import type { Handle } from "bosia";
 
 // Sets locals that every loader and API handler can read
@@ -8,14 +7,6 @@ const authHandle: Handle = async ({ event, resolve }) => {
 	return resolve(event);
 };
 
-// Logs each request with method, path, status, and duration
-const loggingHandle: Handle = async ({ event, resolve }) => {
-	const start = Date.now();
-	const res = await resolve(event);
-	const ms = Date.now() - start;
-	console.log(`[${event.request.method}] ${event.url.pathname} ${res.status} (${ms}ms)`);
-	res.headers.set("X-Response-Time", `${ms}ms`);
-	return res;
-};
-
-export const handle = sequence(authHandle, loggingHandle);
+// Need an access log? Let nginx/Caddy keep it, or add `accessLog()` from
+// "bosia/plugins/access-log" to bosia.config.ts.
+export const handle = authHandle;

package/templates/demo/tsconfig.json

@@ -9,7 +9,7 @@
 		"allowImportingTsExtensions": true,
 		"noEmit": true,
 		"verbatimModuleSyntax": true,
-		"types": ["bun-types"],
+		"types": ["bun"],
 		"lib": ["dom", "dom.iterable", "esnext"],
 		"rootDirs": [".", ".bosia/types"],
 		"paths": {

package/templates/shop/src/app.d.ts

@@ -9,6 +9,5 @@ declare module "*.svelte" {
 declare namespace App {
 	interface Locals {
 		db: import("./features/drizzle").Database;
-		requestTime: number;
 	}
 }

package/templates/shop/src/hooks.server.ts

@@ -18,14 +18,6 @@ const guardHandle: Handle = async ({ event, resolve }) => {
 	return resolve(event);
 };
 
-const loggingHandle: Handle = async ({ event, resolve }) => {
-	const start = Date.now();
-	event.locals.requestTime = start;
-	const res = await resolve(event);
-	const ms = Date.now() - start;
-	console.log(`[${event.request.method}] ${event.url.pathname} ${res.status} (${ms}ms)`);
-	res.headers.set("X-Response-Time", `${ms}ms`);
-	return res;
-};
-
-export const handle = sequence(dbHandle, authHandle, guardHandle, loggingHandle);
+// Need an access log? Let nginx/Caddy keep it, or add `accessLog()` from
+// "bosia/plugins/access-log" to bosia.config.ts.
+export const handle = sequence(dbHandle, authHandle, guardHandle);

package/templates/shop/src/routes/+layout.server.ts

@@ -3,7 +3,6 @@ import type { LoadEvent } from "bosia";
 export async function load({ locals }: LoadEvent) {
 	return {
 		appName: "Bosia Shop",
-		requestTime: (locals.requestTime as number | null) ?? null,
 		user: locals.user ?? null,
 	};
 }

package/templates/shop/tsconfig.json

@@ -9,7 +9,7 @@
 		"allowImportingTsExtensions": true,
 		"noEmit": true,
 		"verbatimModuleSyntax": true,
-		"types": ["bun-types"],
+		"types": ["bun"],
 		"lib": ["dom", "dom.iterable", "esnext"],
 		"rootDirs": [".", ".bosia/types"],
 		"paths": {

package/templates/store/src/app.d.ts

@@ -9,6 +9,5 @@ declare module "*.svelte" {
 declare namespace App {
 	interface Locals {
 		db: import("./features/drizzle").Database;
-		requestTime: number;
 	}
 }

package/templates/store/src/hooks.server.ts

@@ -18,14 +18,6 @@ const guardHandle: Handle = async ({ event, resolve }) => {
 	return resolve(event);
 };
 
-const loggingHandle: Handle = async ({ event, resolve }) => {
-	const start = Date.now();
-	event.locals.requestTime = start;
-	const res = await resolve(event);
-	const ms = Date.now() - start;
-	console.log(`[${event.request.method}] ${event.url.pathname} ${res.status} (${ms}ms)`);
-	res.headers.set("X-Response-Time", `${ms}ms`);
-	return res;
-};
-
-export const handle = sequence(dbHandle, authHandle, guardHandle, loggingHandle);
+// Need an access log? Let nginx/Caddy keep it, or add `accessLog()` from
+// "bosia/plugins/access-log" to bosia.config.ts.
+export const handle = sequence(dbHandle, authHandle, guardHandle);

package/templates/store/src/routes/+layout.server.ts

@@ -3,7 +3,6 @@ import type { LoadEvent } from "bosia";
 export async function load({ locals }: LoadEvent) {
 	return {
 		appName: "Bosia Shop",
-		requestTime: (locals.requestTime as number | null) ?? null,
 		user: locals.user ?? null,
 	};
 }

package/templates/store/tsconfig.json

@@ -9,7 +9,7 @@
 		"allowImportingTsExtensions": true,
 		"noEmit": true,
 		"verbatimModuleSyntax": true,
-		"types": ["bun-types"],
+		"types": ["bun"],
 		"lib": ["dom", "dom.iterable", "esnext"],
 		"rootDirs": [".", ".bosia/types"],
 		"paths": {