maxserver 1.0.1 → 2.0.0

package/src/docs.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+
+const SECURITY = [{ bearerAuth: [] }, { cookieAuth: [] }];
+const NOT_SCHEMA = ["$id", "auth", "order", "tags", "summary"];
+
+
+/**
+ * Rewrites model refs: "User" -> "#/components/schemas/User",
+ * "User#/properties/name" -> "#/components/schemas/User/properties/name"
+ */
+function fixRefs(value) {
+	if (Array.isArray(value)) return value.map(fixRefs);
+	if (!value || typeof value !== "object") return value;
+
+	const out = {};
+	for (const [k, v] of Object.entries(value)) {
+		if (k === "$ref" && typeof v === "string" && !v.startsWith("#")) {
+			const [name, pointer = ""] = v.split("#");
+			out[k] = `#/components/schemas/${name}${pointer}`;
+		} else out[k] = fixRefs(v);
+	}
+	return out;
+}
+
+
+function clean(schema) {
+	const out = { ...schema };
+	for (const k of NOT_SCHEMA) delete out[k];
+	return fixRefs(out);
+}
+
+
+/**
+ * Params, querystring and headers become OpenAPI parameters.
+ * Every path param is listed, typed from schema.params if given.
+ */
+function parameters(route, schema) {
+	const list = [];
+	const add = (where, s = {}, names) => {
+		const props = s.properties || (s.type ? {} : s);
+		for (const name of names || Object.keys(props))
+			list.push({
+				name, in: where,
+				required: where === "path" || (s.required || []).includes(name),
+				schema: fixRefs(props[name] || { type: "string" }),
+				...(props[name]?.description && { description: props[name].description }),
+			});
+	};
+
+	add("path", schema.params, [...route.path.matchAll(/:(\w+)/g)].map(m => m[1]));
+	if (schema.querystring || schema.query) add("query", schema.querystring || schema.query);
+	if (schema.headers) add("header", schema.headers);
+	return list;
+}
+
+
+function operation(route) {
+	const s = route.schema;
+	const op = {};
+
+	if (s.tags) op.tags = s.tags;
+	if (s.summary) op.summary = s.summary;
+	if (s.description) op.description = s.description;
+
+	const params = parameters(route, s);
+	if (params.length) op.parameters = params;
+
+	if (s.body) op.requestBody = { required: true, content: { "application/json": { schema: fixRefs(s.body) } } };
+
+	op.responses = {};
+	for (const [status, r] of Object.entries(s.response || { 200: null }))
+		op.responses[status] = r
+			? { description: r.description || "Default Response", content: { "application/json": { schema: fixRefs(r) } } }
+			: { description: "Default Response" };
+
+	if (s.auth) op.security = SECURITY;
+	return op;
+}
+
+
+/**
+ * Routes sorted like v1: folder order kept, inside a folder by schema.order.
+ */
+function sortRoutes(routes) {
+	const dirs = [];
+	for (const r of routes) {
+		const dir = path.dirname(r.file || "");
+		if (!dirs.includes(dir)) dirs.push(dir);
+	}
+
+	const key = r => dirs.indexOf(path.dirname(r.file || ""));
+	return [...routes].sort((a, b) => key(a) - key(b) || (a.schema.order ?? 999) - (b.schema.order ?? 999));
+}
+
+
+/**
+ * OpenAPI 3.1 document from routes with a schema and all models.
+ */
+export function buildOpenApi(routes, models, info) {
+	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" },
+			},
+			schemas: {},
+		},
+		paths: {},
+	};
+
+	for (const m of models) doc.components.schemas[m.$id] = clean(m);
+
+	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);
+	}
+
+	return doc;
+}
+
+
+// Dev GUI files (built in the maxserver-docs repo). Read from disk, never
+// imported, so production bundles stay free of them.
+const UI_DIR = path.resolve(import.meta.dir, "../devdocs");
+const UI_FILES = { "maxserver-docs.js": "text/javascript; charset=utf-8", "maxserver-docs.css": "text/css; charset=utf-8" };
+
+
+function escapeHtml(text) {
+	return String(text).replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
+}
+
+
+/**
+ * Bun routes: /docs/openapi.json always; in development also the /docs
+ * dev GUI with its two files, when they exist.
+ */
+export async function docsRoutes(openapi, dev) {
+	const json = JSON.stringify(openapi);
+	const routes = {
+		"/docs/openapi.json": () => new Response(json, { headers: { "Content-Type": "application/json" } }),
+	};
+
+	// 1. Production, or bundled app without the files: spec only
+	if (!dev || !(await Bun.file(path.join(UI_DIR, "maxserver-docs.js")).exists())) return routes;
+
+	// 2. Development: page + UI files
+	const html = `<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>${escapeHtml(openapi.info?.title || "API")}</title>
+	<link rel="stylesheet" href="/docs/maxserver-docs.css">
+</head>
+<body>
+	<div id="app" data-spec="/docs/openapi.json"></div>
+	<script type="module" src="/docs/maxserver-docs.js"></script>
+</body>
+</html>`;
+
+	routes["/docs"] = () => new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+	for (const [name, type] of Object.entries(UI_FILES))
+		routes[`/docs/${name}`] = () => new Response(Bun.file(path.join(UI_DIR, name)), { headers: { "Content-Type": type } });
+
+	return routes;
+}

package/src/errors.js

@@ -0,0 +1,70 @@
+import { STATUS_CODES } from "node:http";
+
+
+/**
+ * Creates an Error with an HTTP status code.
+ * Throw it from handlers to stop with a clean HTTP error.
+ */
+export function createError(code, message) {
+	const err = new Error(message);
+	err.statusCode = code;
+	Error.captureStackTrace?.(err, createError);
+	return err;
+}
+
+
+/**
+ * Only valid HTTP error codes, everything else is 500.
+ */
+function statusOf(err) {
+	const code = Number(err?.statusCode || err?.status);
+	return code >= 400 && code <= 599 ? code : 500;
+}
+
+
+/**
+ * Turns any thrown error into a JSON response.
+ * Shape as in v1 (Fastify): { statusCode, error, message }
+ */
+export function errorResponse(err, production) {
+	const code = statusOf(err);
+
+	let message = err?.message || STATUS_CODES[code];
+	if (code >= 500 && production) message = STATUS_CODES[code];
+
+	return Response.json(
+		{ statusCode: code, error: STATUS_CODES[code] || "Error", message },
+		{ status: code }
+	);
+}
+
+
+/**
+ * First stack frame in the app (inside cwd, not node_modules), as "src/file.js:4".
+ */
+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+/);
+		if (match && match[1].startsWith(cwd) && !match[1].includes("/node_modules/"))
+			return `${match[1].slice(cwd.length)}:${match[2]}`;
+	}
+	return null;
+}
+
+
+/**
+ * One log entry per error: status, request, message, app file:line, stack for 5xx.
+ * Development logs all errors, production only 5xx.
+ */
+export function logError(err, req, dev) {
+	const code = statusOf(err);
+	if (!dev && code < 500) return;
+
+	const { pathname } = new URL(req.url);
+	const where = appLocation(err);
+	console.error(`❌ ${code} ${req.method} ${pathname}  ${err?.message}${where ? `  (${where})` : ""}`);
+
+	const stack = String(err?.stack || "").split("\n").slice(1).join("\n");
+	if (code >= 500 && stack) console.error(stack);
+}

package/src/headers.js

@@ -0,0 +1,32 @@
+/**
+ * Security headers, same as v1 helmet config:
+ * helmet defaults without CSP and frameguard, CORP cross-origin.
+ */
+export const SECURITY_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",
+	"X-XSS-Protection": "0",
+};
+
+
+/**
+ * Sets headers on a response. Responses with immutable headers
+ * (e.g. from fetch) are copied first.
+ */
+export function setHeaders(response, headers) {
+	try {
+		for (const [k, v] of Object.entries(headers)) response.headers.set(k, v);
+		return response;
+	} catch {
+		const copy = new Response(response.body, response);
+		for (const [k, v] of Object.entries(headers)) copy.headers.set(k, v);
+		return copy;
+	}
+}

package/src/index.js

@@ -1,93 +1,115 @@
-import Fastify from "fastify";
+import { createError } from "./errors.js";
+import { configureJwt } from "./jwt.js";
+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 {
-	setupCors,
-	setupHelmet,
-	setupJwt,
-	setupMongo,
-	setupStatic,
-	setupCookie,
-	setupErrorLogger,
-} from "./setup.js";
+export { createError } from "./errors.js";
+export { signJwt, verifyJwt } from "./jwt.js";
 
-import { getAddress } from "./getAddress.js";
-import { setupDocs } from "./setupDocs.js";
-import { setupRoutes } from "./setupRoutes.js";
-import { setupDevSounds } from "./devSounds.js";
 
-import fastifyWebsocket from "@fastify/websocket";
+// Framework globals
+globalThis.createError = createError;
+globalThis.ENV = {
+	...process.env,
+	development: process.env.NODE_ENV !== "production",
+	production: process.env.NODE_ENV === "production",
+};
+
+
+// Filled by generated setup.js before server.js runs
+const registry = { routes: null, models: [] };
+
+
+/**
+ * Called by setup.js with all routes and models.
+ */
+export function register({ routes = [], models = [] } = {}) {
+	registry.routes = routes;
+	registry.models = models;
+}
+
 
 export default async function maxserver(config = {}) {
+
+	// 1. Config: maxserver() > .env > default
 	const {
 		port = Number(process.env.PORT || 3000),
 		secret = process.env.SECRET,
-		mongodb = process.env.MONGODB,
 		docs = process.env.DOCS !== "false",
 		cors = process.env.CORS || "*",
 		env = process.env.NODE_ENV || "development",
-		routesDir = process.env.ROUTESDIR || "src",
-		scalar = {},
-		openapiInfo,
-		sounds = true,
-		static: isStatic = process.env.STATIC,
+		static: staticDir = process.env.STATIC,
 		public: isPublic = process.env.PUBLIC === "true",
-
-		...fastifyOpts
+		openapiInfo,
+		routesDir,
+		...bunOptions
 	} = config;
 
-	globalThis.ENV = {
-		...process.env,
-		development: process.env.NODE_ENV !== "production",
-		production: process.env.NODE_ENV === "production"
-	};
+	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 (!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)");
+
+	// 2. Models need an $id to be referenced
+	for (const m of registry.models)
+		if (!m.schema?.$id) throw new Error(`maxserver: model schema needs an $id (${m.file})`);
+	const models = registry.models.map(m => m.schema);
 
-	const maxserverConfig = {
-		port, secret, mongodb, docs, cors, env, openapiInfo, routesDir, scalar, sounds,
-		static: isStatic,
-		public: isPublic
+	// 3. Shared context for all requests
+	const dev = env !== "production";
+	configureJwt(secret);
+
+	const ctx = {
+		dev,
+		secret,
+		cors: setupCors(cors, !dev),
+		static: setupStatic(staticDir),
+		ajvs: createValidators(models),
 	};
 
-	if (!secret) throw new Error("secret is must have");
-
-	let app;
-	try {
-		app = Fastify({
-			trustProxy: true,
-			ajv: { customOptions: { strictSchema: false } },
-			...fastifyOpts
-		});
-	} catch (err) {
-		console.error("❌ Fastify initialization failed:", err);
-		throw err;
+	// 4. Routes: user routes + docs
+	const routes = buildRoutes(registry.routes, ctx);
+	if (docs) {
+		const openapi = buildOpenApi(registry.routes, models, openapiInfo);
+		for (const [path, handler] of Object.entries(await docsRoutes(openapi, dev)))
+			routes[path] = { GET: req => finish(req, handler(), ctx) };
 	}
 
-	app.decorate("maxserver", maxserverConfig);
-
-	app.decorate("start", async function () {
-		const port = this.maxserver.port ?? 3000;
-		const host = this.maxserver.public ? "0.0.0.0" : "127.0.0.1";
-		await this.listen({ port, host });
-		console.log("🟢 ", getAddress(this));
-	});
-
-	app.register(fastifyWebsocket);
-
-	await setupDevSounds(app);
-	await setupErrorLogger(app);
-	await setupCookie(app);
-	await setupHelmet(app);
-	await setupCors(app);
-	await setupJwt(app);
-	await setupMongo(app);
-	await setupStatic(app);
-	await setupDocs(app);
-	await setupRoutes(app);
-
-	global.createError = function (code, message) {
-		const err = new Error(message);
-		err.statusCode = code;
-		return err;
+	// 5. Server object
+	const server = {
+		config: { port, docs, cors, env, static: staticDir, public: isPublic, ...bunOptions },
+		bun: null,
+		url: null,
+
+		async start() {
+			// Defaults first (1 MiB body limit like v1), then any Bun.serve option,
+			// then what maxserver must control
+			server.bun = Bun.serve({
+				maxRequestBodySize: 1048576,
+				development: dev,
+				...bunOptions,
+				port,
+				hostname: isPublic ? "0.0.0.0" : "127.0.0.1",
+				routes,
+				fetch: fallback(ctx),
+			});
+
+			server.url = server.bun.url.href.replace(/\/$/, "");
+			console.log("🟢 ", server.url);
+			if (routes["/docs"]) console.log("📚 ", `${server.url}/docs`);
+			return server;
+		},
+
+		async stop() {
+			await server.bun?.stop(true);
+		},
 	};
 
-	return app;
-}
+	return server;
+}

package/src/jwt.js

@@ -0,0 +1,107 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createError } from "./errors.js";
+
+const HEADER = b64(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+const UNITS = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+
+let configuredSecret;
+
+
+export function configureJwt(secret) {
+	configuredSecret = secret;
+}
+
+
+function getSecret() {
+	const secret = configuredSecret || process.env.SECRET;
+	if (!secret) throw new Error("signJwt: no secret, set secret in maxserver() or SECRET in .env");
+	return secret;
+}
+
+
+function b64(str) {
+	return Buffer.from(str).toString("base64url");
+}
+
+
+function sign(data, secret) {
+	return createHmac("sha256", secret).update(data).digest("base64url");
+}
+
+
+/**
+ * Parses expiresIn: seconds as number or "60s", "30m", "12h", "7d", "2w".
+ */
+function toSeconds(value) {
+	if (typeof value === "number") return value;
+	const m = String(value).match(/^(\d+)\s*([smhdw])$/);
+	if (!m) throw new Error(`signJwt: invalid expiresIn "${value}"`);
+	return Number(m[1]) * UNITS[m[2]];
+}
+
+
+/**
+ * Creates a HS256 JWT signed with the server secret.
+ */
+export function signJwt(payload, { expiresIn } = {}) {
+	const now = Math.floor(Date.now() / 1000);
+	const claims = { iat: now, ...payload };
+	if (expiresIn !== undefined) claims.exp = now + toSeconds(expiresIn);
+
+	const data = `${HEADER}.${b64(JSON.stringify(claims))}`;
+	return `${data}.${sign(data, getSecret())}`;
+}
+
+
+/**
+ * Verifies a HS256 JWT and returns its payload.
+ * Only HS256 is accepted, signature compared in constant time.
+ */
+export function verifyJwt(token, secret = getSecret()) {
+	const invalid = createError(401, "Authorization token is invalid");
+
+	// 1. Structure
+	const parts = String(token).split(".");
+	if (parts.length !== 3) throw invalid;
+	const [head, body, signature] = parts;
+
+	// 2. Algorithm
+	let header, payload;
+	try {
+		header = JSON.parse(Buffer.from(head, "base64url"));
+		payload = JSON.parse(Buffer.from(body, "base64url"));
+	} catch {
+		throw invalid;
+	}
+	if (header?.alg !== "HS256") throw invalid;
+	if (!payload || typeof payload !== "object") throw invalid;
+
+	// 3. Signature
+	const expected = Buffer.from(sign(`${head}.${body}`, secret));
+	const given = Buffer.from(signature);
+	if (given.length !== expected.length || !timingSafeEqual(given, expected)) throw invalid;
+
+	// 4. Time claims
+	const now = Math.floor(Date.now() / 1000);
+	if (typeof payload.exp === "number" && now >= payload.exp)
+		throw createError(401, "Authorization token expired");
+	if (typeof payload.nbf === "number" && now < payload.nbf) throw invalid;
+
+	return payload;
+}
+
+
+/**
+ * Auth for routes with auth: true.
+ * Token from "Authorization: Bearer <token>" header or "token" cookie.
+ */
+export function authenticate(req, secret) {
+	const auth = req.headers.get("authorization") || "";
+	const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : req.cookies?.get("token");
+
+	if (!token) throw createError(401, "No Authorization was found in request");
+
+	const user = verifyJwt(token, secret);
+	req.user = user;
+	req.userId = user.sub || user.userId || user.userid || user.id || null;
+}