maxserver 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "maxserver",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"description": "Bun server setup",
 	"author": "Max Matinpalo",
 	"type": "module",
@@ -27,7 +27,8 @@
 		"devdocs"
 	],
 	"scripts": {
-		"test": "bun test ./test"
+		"test": "bun test ./test",
+		"bench": "bun test/bench/run.js"
 	},
 	"dependencies": {
 		"ajv": "^8",

package/src/cors.js

@@ -21,20 +21,31 @@ export function setupCors(cors = "*", production) {
  * CORS headers for a request, as in v1 (@fastify/cors with credentials).
  */
 export function corsHeaders(req, cors) {
-	const origin = req.headers.get("origin");
-	const headers = { "Access-Control-Allow-Credentials": "true" };
+	return { ...fixedCorsHeaders(cors), ...originHeaders(req, cors) };
+}
 
-	// 1. Allowed origin
-	if (cors.any && !cors.reflect) headers["Access-Control-Allow-Origin"] = "*";
-	else if (origin && (cors.any || cors.list.includes(origin))) {
-		headers["Access-Control-Allow-Origin"] = origin;
-		headers["Vary"] = "Origin";
-	}
 
+/**
+ * CORS headers that are the same for every request.
+ */
+export function fixedCorsHeaders(cors) {
+	const headers = { "Access-Control-Allow-Credentials": "true" };
+	if (cors.any && !cors.reflect) headers["Access-Control-Allow-Origin"] = "*";
 	return headers;
 }
 
 
+/**
+ * CORS headers for the request's origin (reflected or listed), null if none.
+ */
+export function originHeaders(req, cors) {
+	if (cors.any && !cors.reflect) return null;
+	const origin = req.headers.get("origin");
+	if (!origin || !(cors.any || cors.list.includes(origin))) return null;
+	return { "Access-Control-Allow-Origin": origin, "Vary": "Origin" };
+}
+
+
 /**
  * Answers OPTIONS preflight requests.
  */

package/src/docs.js

@@ -1,6 +1,5 @@
 import path from "node:path";
 
-const SECURITY = [{ bearerAuth: [] }, { cookieAuth: [] }];
 const NOT_SCHEMA = ["$id", "auth", "order", "tags", "summary"];
 
 
@@ -54,7 +53,7 @@ function parameters(route, schema) {
 }
 
 
-function operation(route) {
+function operation(route, security) {
 	const s = route.schema;
 	const op = {};
 
@@ -73,7 +72,7 @@ function operation(route) {
 			? { description: r.description || "Default Response", content: { "application/json": { schema: fixRefs(r) } } }
 			: { description: "Default Response" };
 
-	if (s.auth) op.security = SECURITY;
+	if (s.auth) op.security = security;
 	return op;
 }
 
@@ -95,16 +94,19 @@ function sortRoutes(routes) {
 
 /**
  * OpenAPI 3.1 document from routes with a schema and all models.
+ * The built-in JWT accepts a Bearer header or a cookie; an app's authenticate only Bearer.
  */
-export function buildOpenApi(routes, models, info) {
+export function buildOpenApi(routes, models, info, customAuth = false) {
+	const securitySchemes = customAuth
+		? { bearerAuth: { type: "http", scheme: "bearer" } }
+		: { bearerAuth: { type: "http", scheme: "bearer" }, cookieAuth: { type: "apiKey", in: "cookie", name: "token" } };
+	const security = Object.keys(securitySchemes).map(name => ({ [name]: [] }));
+
 	const doc = {
 		openapi: "3.1.0",
 		info: info || { title: "API", version: "1.0.0" },
 		components: {
-			securitySchemes: {
-				bearerAuth: { type: "http", scheme: "bearer" },
-				cookieAuth: { type: "apiKey", in: "cookie", name: "token" },
-			},
+			securitySchemes,
 			schemas: {},
 		},
 		paths: {},
@@ -115,7 +117,7 @@ export function buildOpenApi(routes, models, info) {
 	for (const r of sortRoutes(routes.filter(r => r.schema && Object.keys(r.schema).length))) {
 		const p = r.path.replace(/:(\w+)/g, "{$1}");
 		doc.paths[p] ||= {};
-		doc.paths[p][r.method.toLowerCase()] = operation(r);
+		doc.paths[p][r.method.toLowerCase()] = operation(r, security);
 	}
 
 	return doc;

package/src/errors.js

@@ -45,7 +45,7 @@ export function errorResponse(err, production) {
 function appLocation(err) {
 	const cwd = process.cwd() + "/";
 	for (const line of String(err?.stack || "").split("\n").slice(1)) {
-		const match = line.match(/(?:file:\/\/)?(\/[^\s()]+):(\d+):\d+/);
+		const match = line.match(/(?:file:\/\/)?(\/[^()]+):(\d+):\d+\)?$/);
 		if (match && match[1].startsWith(cwd) && !match[1].includes("/node_modules/"))
 			return `${match[1].slice(cwd.length)}:${match[2]}`;
 	}

package/src/headers.js

@@ -1,14 +1,23 @@
 /**
- * Security headers, same as v1 helmet config:
- * helmet defaults without CSP and frameguard, CORP cross-origin.
+ * Security headers for JSON (handler data, errors): the only helmet headers
+ * that matter for JSON. Each header costs Bun time on every response.
+ */
+export const API_HEADERS = {
+	"Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+	"X-Content-Type-Options": "nosniff",
+};
+
+
+/**
+ * Security headers for everything else (static files, /docs, returned Responses),
+ * same as v1 helmet config: helmet defaults without CSP and frameguard, CORP cross-origin.
  */
 export const SECURITY_HEADERS = {
+	...API_HEADERS,
 	"Cross-Origin-Opener-Policy": "same-origin",
 	"Cross-Origin-Resource-Policy": "cross-origin",
 	"Origin-Agent-Cluster": "?1",
 	"Referrer-Policy": "no-referrer",
-	"Strict-Transport-Security": "max-age=31536000; includeSubDomains",
-	"X-Content-Type-Options": "nosniff",
 	"X-DNS-Prefetch-Control": "off",
 	"X-Download-Options": "noopen",
 	"X-Permitted-Cross-Domain-Policies": "none",

package/src/index.js

@@ -4,7 +4,7 @@ import { setupCors } from "./cors.js";
 import { setupStatic } from "./static.js";
 import { createValidators } from "./validate.js";
 import { buildOpenApi, docsRoutes } from "./docs.js";
-import { buildRoutes, fallback, finish } from "./routes.js";
+import { buildRoutes, defaultHeaders, fallback, finish } from "./routes.js";
 
 export { createError } from "./errors.js";
 export { signJwt, verifyJwt } from "./jwt.js";
@@ -44,6 +44,7 @@ export default async function maxserver(config = {}) {
 		static: staticDir = process.env.STATIC,
 		public: isPublic = process.env.PUBLIC === "true",
 		openapiInfo,
+		authenticate,
 		routesDir,
 		...bunOptions
 	} = config;
@@ -51,8 +52,8 @@ export default async function maxserver(config = {}) {
 	if (routesDir !== undefined)
 		throw new Error("maxserver: routesDir is read by the generator, set ROUTESDIR in .env instead");
 
-	if (!secret)
-		throw new Error("maxserver: secret is required, set secret in maxserver() or SECRET in .env");
+	if (!secret && !authenticate)
+		throw new Error("maxserver: secret is required, set secret in maxserver() or SECRET in .env (or pass authenticate)");
 	if (!registry.routes)
 		throw new Error("maxserver: no routes registered. Start with `maxserver dev`, or `maxserver build` and `bun dist/bundle.js` (running server.js directly skips the generated setup.js)");
 
@@ -64,11 +65,14 @@ export default async function maxserver(config = {}) {
 	// 3. Shared context for all requests
 	const dev = env !== "production";
 	configureJwt(secret);
+	const corsConfig = setupCors(cors, !dev);
 
 	const ctx = {
 		dev,
 		secret,
-		cors: setupCors(cors, !dev),
+		authenticate,
+		cors: corsConfig,
+		headers: defaultHeaders(corsConfig),
 		static: setupStatic(staticDir),
 		ajvs: createValidators(models),
 	};
@@ -76,7 +80,7 @@ export default async function maxserver(config = {}) {
 	// 4. Routes: user routes + docs
 	const routes = buildRoutes(registry.routes, ctx);
 	if (docs) {
-		const openapi = buildOpenApi(registry.routes, models, openapiInfo);
+		const openapi = buildOpenApi(registry.routes, models, openapiInfo, !!authenticate);
 		for (const [path, handler] of Object.entries(await docsRoutes(openapi, dev)))
 			routes[path] = { GET: req => finish(req, handler(), ctx) };
 	}

package/src/routes.js

@@ -1,7 +1,7 @@
-import { authenticate } from "./jwt.js";
-import { corsHeaders, preflight } from "./cors.js";
+import { authenticate as authenticateJwt } from "./jwt.js";
+import { corsHeaders, fixedCorsHeaders, originHeaders, preflight } from "./cors.js";
 import { errorResponse, logError } from "./errors.js";
-import { SECURITY_HEADERS, setHeaders } from "./headers.js";
+import { API_HEADERS, SECURITY_HEADERS, setHeaders } from "./headers.js";
 import { compileRoute, validatePart, checkResponse } from "./validate.js";
 import { serveStatic } from "./static.js";
 
@@ -9,8 +9,17 @@ import { serveStatic } from "./static.js";
 /**
  * Common end of every response: CORS + security headers.
  */
-export function finish(req, response, ctx) {
-	return setHeaders(response, { ...corsHeaders(req, ctx.cors), ...SECURITY_HEADERS });
+export function finish(req, response, ctx, security = SECURITY_HEADERS) {
+	return setHeaders(response, { ...corsHeaders(req, ctx.cors), ...security });
+}
+
+
+/**
+ * Headers of every handler response, built once: Bun copies a Headers
+ * object much faster than it sets headers one by one.
+ */
+export function defaultHeaders(cors) {
+	return new Headers({ ...fixedCorsHeaders(cors), ...API_HEADERS });
 }
 
 
@@ -19,7 +28,9 @@ export function finish(req, response, ctx) {
  */
 function parseQuery(url) {
 	const query = {};
-	for (const [k, v] of new URL(url).searchParams) {
+	const i = url.indexOf("?");
+	if (i < 0) return query;
+	for (const [k, v] of new URLSearchParams(url.slice(i + 1))) {
 		if (!Object.hasOwn(query, k)) setProp(query, k, v);
 		else if (Array.isArray(query[k])) query[k].push(v);
 		else query[k] = [query[k], v];
@@ -28,6 +39,20 @@ function parseQuery(url) {
 }
 
 
+/**
+ * req.query parsed on first use, because reading req.url is slow in Bun.
+ */
+function lazyQuery(req) {
+	let query;
+	Object.defineProperty(req, "query", {
+		get: () => query ??= parseQuery(req.url),
+		set: value => { query = value; },
+		configurable: true,
+		enumerable: true,
+	});
+}
+
+
 function badRequest(message) {
 	return Object.assign(new Error(message), { statusCode: 400 });
 }
@@ -50,8 +75,6 @@ function safeParse(text) {
  * Parses the body: JSON and text, else left unread.
  */
 async function parseBody(req) {
-	if (req.method === "GET" || req.method === "HEAD") return undefined;
-
 	const type = (req.headers.get("content-type") || "").toLowerCase();
 	if (type.includes("application/json")) {
 		const text = await req.text();
@@ -74,13 +97,15 @@ function setProp(obj, key, value) {
 
 /**
  * Handler response object: collects status and headers.
+ * Headers are a copy of the defaults, made only when a handler sets one.
  */
-function createRes() {
+function createRes(ctx) {
 	const res = {
 		statusCode: 200,
-		headers: new Headers(),
+		headers: null,
 		status(code) { res.statusCode = code; return res; },
 		header(name, value) {
+			res.headers ||= new Headers(ctx.headers);
 			if (name.toLowerCase() === "set-cookie") res.headers.append(name, value);
 			else res.headers.set(name, value);
 			return res;
@@ -90,15 +115,27 @@ function createRes() {
 }
 
 
-function toResponse(data, res) {
-	if (data instanceof Response) return data;
+/**
+ * Handler result -> Response with default, handler and CORS origin headers.
+ */
+function toResponse(data, res, req, ctx) {
+	if (data instanceof Response) return finish(req, data, ctx);
+
+	// 1. Headers: the prebuilt defaults unless something is added
+	let headers = res.headers || ctx.headers;
+	const origin = originHeaders(req, ctx.cors);
+	if (origin) {
+		if (headers === ctx.headers) headers = new Headers(headers);
+		for (const [k, v] of Object.entries(origin)) headers.set(k, v);
+	}
 
+	// 2. Body
 	if (data === undefined) {
 		const status = res.statusCode === 200 ? 204 : res.statusCode;
-		return new Response(null, { status, headers: res.headers });
+		return new Response(null, { status, headers });
 	}
 
-	return Response.json(data, { status: res.statusCode, headers: res.headers });
+	return Response.json(data, { status: res.statusCode, headers });
 }
 
 
@@ -111,44 +148,46 @@ function wrap(route, ctx) {
 	const name = `${route.method} ${route.path}`;
 
 	return async function (req) {
-		let response;
 		try {
 
-			// 1. Auth
-			if (schema.auth) authenticate(req, ctx.secret);
+			// 1. Auth: the app's authenticate (its result is req.auth), else the built-in JWT
+			if (schema.auth && ctx.authenticate) {
+				const auth = await ctx.authenticate(req);
+				if (!auth) throw Object.assign(new Error("Unauthorized"), { statusCode: 401 });
+				setProp(req, "auth", auth);
+			} else if (schema.auth) authenticateJwt(req, ctx.secret);
 
-			// 2. Parse
-			const params = { ...req.params };
-			const query = parseQuery(req.url);
-			const body = await parseBody(req);
+			// 2. Parse (Bun's req.params is kept and validated in place)
+			const body = req.method === "GET" || req.method === "HEAD" ? undefined : await parseBody(req);
 
 			// 3. Validate (may coerce, add defaults, remove extras)
-			if (v.request.params) validatePart(v.request.params, "params", params);
-			if (v.request.querystring) validatePart(v.request.querystring, "querystring", query);
+			if (v.request.params) validatePart(v.request.params, "params", req.params);
+			if (v.request.querystring) {
+				const query = parseQuery(req.url);
+				validatePart(v.request.querystring, "querystring", query);
+				setProp(req, "query", query);
+			} else lazyQuery(req);
 			if (v.request.headers) validatePart(v.request.headers, "headers", Object.fromEntries(req.headers));
 			if (v.request.body) validatePart(v.request.body, "body", body);
 
-			setProp(req, "params", params);
-			setProp(req, "query", query);
 			setProp(req, "body", body);
 
 			// 4. Handler
-			const res = createRes();
+			const res = createRes(ctx);
 			const data = await route.handler(req, res);
-			response = toResponse(data, res);
+			const response = toResponse(data, res, req, ctx);
 
 			// 5. Development: check response against schema
 			if (ctx.dev && !(data instanceof Response)) {
 				const problem = checkResponse(v.response, response.status, data);
 				if (problem) console.warn(`⚠️  Response mismatch ${name} ${response.status} (${route.file}): ${problem}`);
 			}
+			return response;
 
 		} catch (err) {
 			logError(err, req, ctx.dev);
-			response = errorResponse(err, !ctx.dev);
+			return finish(req, errorResponse(err, !ctx.dev), ctx, API_HEADERS);
 		}
-
-		return finish(req, response, ctx);
 	};
 }
 
@@ -182,6 +221,6 @@ export function fallback(ctx) {
 
 		const { pathname } = new URL(req.url);
 		const err = Object.assign(new Error(`Route ${req.method}:${pathname} not found`), { statusCode: 404 });
-		return finish(req, errorResponse(err, !ctx.dev), ctx);
+		return finish(req, errorResponse(err, !ctx.dev), ctx, API_HEADERS);
 	};
 }