bosia 1.2.5 → 1.2.7

package/README.md

@@ -144,16 +144,15 @@ const authHandle: Handle = async ({ event, resolve }) => {
 	return resolve(event);
 };
 
-const loggingHandle: Handle = async ({ event, resolve }) => {
-	const res = await resolve(event);
-	console.log(`${event.request.method} ${event.url.pathname} ${res.status}`);
-	return res;
+const langHandle: Handle = async ({ event, resolve }) => {
+	event.locals.lang = event.request.headers.get("accept-language")?.split(",")[0] ?? "en";
+	return resolve(event);
 };
 
-export const handle = sequence(authHandle, loggingHandle);
+export const handle = sequence(authHandle, langHandle);
 ```
 
-`locals` set here are available in every loader and API handler.
+`locals` set here are available in every loader and API handler. For an access log, use your reverse proxy's or add `accessLog()` from `bosia/plugins/access-log` to `bosia.config.ts` — not a `console.log` per request.
 
 ## Public API
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "1.2.5",
+	"version": "1.2.7",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.4"
@@ -37,6 +37,7 @@
 		"./client": "./src/lib/client.ts",
 		"./server": "./src/lib/server.ts",
 		"./plugins/server-timing": "./src/core/plugins/server-timing.ts",
+		"./plugins/access-log": "./src/core/plugins/access-log.ts",
 		"./plugins/inspector": "./src/core/plugins/inspector/index.ts"
 	},
 	"bin": {

package/src/core/backend.ts

@@ -1,8 +1,19 @@
 // ─── Bosia Backend App ────────────────────────────────────
 // A tiny Elysia-shaped HTTP app: chainable routes + onRequest / onAfterHandle /
-// onError hooks, one `fetch(request)` entry for Bun.serve and Workers alike.
+// onError / onResponse hooks, one `fetch(request)` entry for Bun.serve and
+// Workers alike.
 // Only the subset the framework and plugins use — not a general router.
 
+import type { Server } from "bun";
+
+import {
+	isUpgradeRequest,
+	isUpgraded,
+	runUpgrade,
+	websocketHandlers,
+	type WebSocketOptions,
+} from "./websocket.ts";
+
 /** Outbound response bag — merged into whatever the handler returns. */
 export interface ResponseSet {
 	status?: number;
@@ -34,10 +45,28 @@ export type AfterHandleHook = (ctx: {
 
 export type ErrorHook = (ctx: { request: Request; error: unknown; set: ResponseSet }) => unknown;
 
+/**
+ * Sees the final Response — after onRequest short-circuits, after-handle
+ * replacements, error hooks and the HEAD body drop — exactly once per request.
+ * `start`: `performance.now()` when the request entered `fetch`. Observe only:
+ * the return value is ignored and a throw or rejection is swallowed. `response`
+ * is the one the client gets — don't read its body or change its headers.
+ * `status` is the status the client got: 101 for a WebSocket upgrade, whose
+ * `response` is only a placeholder (a 101 Response can't be built).
+ */
+export type ResponseHook = (ctx: {
+	request: Request;
+	response: Response;
+	status: number;
+	upgraded: boolean;
+	start: number;
+}) => void | Promise<unknown>;
+
 export interface ServeOptions {
 	maxRequestBodySize?: number;
 	idleTimeout?: number;
 	reusePort?: boolean;
+	websocket?: WebSocketOptions;
 }
 
 type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "*";
@@ -55,6 +84,7 @@ export class BosiaApp {
 	private requestHooks: RequestHook[] = [];
 	private afterHooks: AfterHandleHook[] = [];
 	private errorHooks: ErrorHook[] = [];
+	private responseHooks: ResponseHook[] = [];
 	private server: ReturnType<typeof Bun.serve> | null = null;
 
 	constructor(private config: { serve?: ServeOptions } = {}) {}
@@ -100,6 +130,12 @@ export class BosiaApp {
 		return this;
 	}
 
+	/** Observes the final response of every request (see ResponseHook). */
+	onResponse(hook: ResponseHook): this {
+		this.responseHooks.push(hook);
+		return this;
+	}
+
 	// Paths match exactly, or "*" matches everything. Enough for plugin endpoints
 	// like /__bosia/locate; add `:param` matching here when a plugin needs it.
 	private route(method: Method, path: string, handler: Handler): this {
@@ -129,7 +165,52 @@ export class BosiaApp {
 		return [...methods];
 	}
 
-	fetch = async (request: Request): Promise<Response> => {
+	/** `undefined` after a WebSocket upgrade — Bun has already answered with 101.
+	 *  Only Bun passes `server`, so Workers never upgrades. */
+	fetch = (request: Request, server?: Server<any>): Promise<Response | undefined> =>
+		server && isUpgradeRequest(request)
+			? runUpgrade(request, server, () => this.handle(request))
+			: this.handle(request);
+
+	private handle = async (request: Request): Promise<Response | undefined> => {
+		if (this.responseHooks.length === 0) {
+			const response = await this.respond(request);
+			return isUpgraded() ? undefined : response;
+		}
+		const start = performance.now();
+		let response: Response;
+		try {
+			response = await this.respond(request);
+		} catch (error) {
+			// An error hook threw: the runtime answers 500, so observers see that.
+			this.observe(request, new Response(null, { status: 500 }), start);
+			throw error;
+		}
+		this.observe(request, response, start);
+		return isUpgraded() ? undefined : response;
+	};
+
+	private observe(request: Request, response: Response, start: number): void {
+		const upgraded = isUpgraded();
+		const status = upgraded ? 101 : response.status;
+		for (const hook of this.responseHooks) {
+			try {
+				const out = hook({ request, response, status, upgraded, start });
+				// An async observer's rejection would be unhandled — fatal in prod.
+				if (out instanceof Promise) out.catch(() => {});
+			} catch {
+				// Observers must not change what the client gets.
+			}
+		}
+	}
+
+	/** Answers without running onResponse observers — for the Workers warm-up
+	 *  render, which no client made and no access log should count. */
+	fetchUnobserved(request: Request): Promise<Response> {
+		return this.respond(request);
+	}
+
+	private async respond(request: Request): Promise<Response> {
 		const set: ResponseSet = { headers: {} };
 		const isHead = request.method === "HEAD";
 		const method = isHead ? "GET" : request.method.toUpperCase();
@@ -143,7 +224,7 @@ export class BosiaApp {
 			}
 			return new Response("Internal Server Error", { status: 500 });
 		}
-	};
+	}
 
 	private async dispatch(request: Request, method: string, set: ResponseSet): Promise<Response> {
 		for (const hook of this.requestHooks) {
@@ -173,6 +254,8 @@ export class BosiaApp {
 			response = "Method Not Allowed";
 		}
 
+		// Bun already sent the 101: nothing after this can change the answer.
+		if (isUpgraded()) return response as Response;
 		for (const hook of this.afterHooks) {
 			const out = await hook({ request, response, set });
 			if (out !== undefined) response = out;
@@ -189,6 +272,7 @@ export class BosiaApp {
 			maxRequestBodySize: serve.maxRequestBodySize,
 			idleTimeout: serve.idleTimeout,
 			reusePort: serve.reusePort ?? false,
+			websocket: { ...websocketHandlers, ...serve.websocket, sendPings: true },
 		});
 		callback?.();
 		return this;

package/src/core/basePath.ts

@@ -30,6 +30,36 @@ export function withBase(base: string, path: string): string {
 	return base + path;
 }
 
+/** Never a navigation target. Test a parsed `URL.protocol`, not the raw string: the
+ *  parser drops tabs, newlines and leading control chars, so `java\tscript:` is one too. */
+export const DANGEROUS_PROTOCOL = /^(javascript|data|vbscript):$/;
+
+/**
+ * What the client router matches: the path the server would see. Every URL goes
+ * through the URL parser against `pageHref`, like a link: `?page=2`, `b`, `../x`
+ * resolve, `/a b` and `/café` get encoded (params match the server's), `/\host`
+ * is another origin. Another origin comes back as its full URL so the router leaves the app.
+ */
+export function toRouterPath(url: string, pageHref: string): string {
+	const u = new URL(url, pageHref);
+	if (DANGEROUS_PROTOCOL.test(u.protocol)) {
+		throw new Error(`navigation: dangerous scheme in URL "${url}". Use a path or an http(s) URL.`);
+	}
+	// Scheme + host, not `origin`: a `blob:` URL shares the page's origin, and the URL
+	// parser gives app shells (`capacitor://localhost`) origin "null" for every host.
+	// A path starting `//` (from `/.//evil.com`) would read as another host once used as
+	// a URL, so it stays a full URL: the router leaves for this origin's `//evil.com` page.
+	const page = new URL(pageHref);
+	// No host (`file:`) is never ours: every file on disk would count as one app.
+	const ours =
+		u.host !== "" &&
+		u.protocol === page.protocol &&
+		u.host === page.host &&
+		!u.pathname.startsWith("//");
+	// `capacitor://localhost` has an empty path: that's the root.
+	return ours ? (u.pathname || "/") + u.search + u.hash : u.href;
+}
+
 /**
  * The in-app pathname for an incoming request, or `null` when the request is
  * not ours to answer. `/sso` and `/sso/` both resolve to `/` so the root route