maxserver 1.0.1 → 2.1.0

package/src/routes.js

@@ -0,0 +1,226 @@
+import { authenticate as authenticateJwt } from "./jwt.js";
+import { corsHeaders, fixedCorsHeaders, originHeaders, preflight } from "./cors.js";
+import { errorResponse, logError } from "./errors.js";
+import { API_HEADERS, SECURITY_HEADERS, setHeaders } from "./headers.js";
+import { compileRoute, validatePart, checkResponse } from "./validate.js";
+import { serveStatic } from "./static.js";
+
+
+/**
+ * Common end of every response: 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 });
+}
+
+
+/**
+ * Query string as object, repeated keys become arrays (like Fastify).
+ */
+function parseQuery(url) {
+	const query = {};
+	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];
+	}
+	return query;
+}
+
+
+/**
+ * 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 });
+}
+
+
+/**
+ * Blocks prototype poisoning like Fastify: __proto__ and constructor.prototype keys -> 400.
+ */
+function safeParse(text) {
+	const risky = text.includes("__proto__") || text.includes("constructor");
+	return JSON.parse(text, risky ? (key, value) => {
+		if (key === "__proto__" || (key === "constructor" && value && typeof value === "object" && "prototype" in value))
+			throw badRequest("Object contains forbidden prototype property");
+		return value;
+	} : undefined);
+}
+
+
+/**
+ * Parses the body: JSON and text, else left unread.
+ */
+async function parseBody(req) {
+	const type = (req.headers.get("content-type") || "").toLowerCase();
+	if (type.includes("application/json")) {
+		const text = await req.text();
+		if (!text) throw badRequest("Body cannot be empty when content-type is set to 'application/json'");
+		try {
+			return safeParse(text);
+		} catch (err) {
+			throw err.statusCode ? err : badRequest("Body is not valid JSON");
+		}
+	}
+	if (type.startsWith("text/")) return await req.text();
+	return undefined;
+}
+
+
+function setProp(obj, key, value) {
+	Object.defineProperty(obj, key, { value, writable: true, configurable: true, enumerable: true });
+}
+
+
+/**
+ * Handler response object: collects status and headers.
+ * Headers are a copy of the defaults, made only when a handler sets one.
+ */
+function createRes(ctx) {
+	const res = {
+		statusCode: 200,
+		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;
+		},
+	};
+	return res;
+}
+
+
+/**
+ * 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 });
+	}
+
+	return Response.json(data, { status: res.statusCode, headers });
+}
+
+
+/**
+ * Wraps a route handler: auth, parsing, validation, handler, response.
+ */
+function wrap(route, ctx) {
+	const schema = route.schema || {};
+	const v = compileRoute(schema, ctx.ajvs, ctx.dev);
+	const name = `${route.method} ${route.path}`;
+
+	return async function (req) {
+		try {
+
+			// 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 (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", 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, "body", body);
+
+			// 4. Handler
+			const res = createRes(ctx);
+			const data = await route.handler(req, 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);
+			return finish(req, errorResponse(err, !ctx.dev), ctx, API_HEADERS);
+		}
+	};
+}
+
+
+/**
+ * Registered routes -> Bun.serve routes object.
+ */
+export function buildRoutes(routes, ctx) {
+	const out = {};
+	for (const r of routes) {
+		out[r.path] ||= {};
+		try {
+			out[r.path][r.method] = wrap(r, ctx);
+		} catch (err) {
+			throw new Error(`Invalid schema for ${r.method} ${r.path} (${r.file}): ${err.message}`);
+		}
+	}
+	return out;
+}
+
+
+/**
+ * Everything not matched by a route: preflight, static files, 404.
+ */
+export function fallback(ctx) {
+	return async function (req) {
+		if (req.method === "OPTIONS") return finish(req, preflight(req, ctx.cors), ctx);
+
+		const file = await serveStatic(req, ctx.static);
+		if (file) return finish(req, file, 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, API_HEADERS);
+	};
+}

package/src/static.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+
+
+/**
+ * Resolves the static directory, null if not set or missing (as in v1).
+ */
+export function setupStatic(dir) {
+	if (!dir) return null;
+
+	if (typeof dir !== "string") {
+		console.error("❌ maxserver.static must be a string path");
+		return null;
+	}
+
+	const root = path.resolve(dir);
+	if (!fs.existsSync(root)) {
+		console.error(`❌ maxserver.static not found: ${root}`);
+		return null;
+	}
+
+	return root;
+}
+
+
+/**
+ * Serves a file from root, null if not found.
+ * Blocks paths outside root and dotfiles (.env, .git).
+ */
+export async function serveStatic(req, root) {
+	if (!root || (req.method !== "GET" && req.method !== "HEAD")) return null;
+
+	// 1. Decode path
+	let pathname;
+	try {
+		pathname = decodeURIComponent(new URL(req.url).pathname);
+	} catch {
+		return null;
+	}
+	if (pathname.includes("\0")) return null;
+
+	// 2. Stay inside root, no dotfiles
+	let file = path.resolve(root, "." + pathname);
+	const rel = path.relative(root, file);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+	if (rel.split(path.sep).some(p => p.startsWith("."))) return null;
+
+	// 3. Directory -> index.html
+	let stat;
+	try {
+		stat = fs.statSync(file, { throwIfNoEntry: false });
+	} catch {
+		return null;
+	}
+	if (stat?.isDirectory()) file = path.join(file, "index.html");
+
+	const bunFile = Bun.file(file);
+	if (!(await bunFile.exists())) return null;
+	return new Response(bunFile);
+}

package/src/validate.js

@@ -0,0 +1,90 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { createError } from "./errors.js";
+
+const PARTS = ["params", "querystring", "headers", "body"];
+
+
+/**
+ * Two ajv instances:
+ * - request: same options as Fastify defaults, changes data (coerce, defaults, remove)
+ * - response: never changes data, only reports
+ */
+export function createValidators(models = []) {
+	const request = new Ajv({ coerceTypes: "array", useDefaults: true, removeAdditional: true, strict: false });
+	const response = new Ajv({ allErrors: true, strict: false });
+
+	for (const ajv of [request, response]) {
+		addFormats(ajv);
+		for (const model of models) ajv.addSchema(model);
+	}
+
+	return { request, response };
+}
+
+
+/**
+ * Fastify shorthand: params / querystring / headers may list properties directly.
+ */
+function normalize(part, schema) {
+	if (part !== "body" && !schema.type && !schema.properties && !schema.$ref)
+		schema = { type: "object", properties: schema };
+	return part === "headers" ? lowercaseHeaders(schema) : schema;
+}
+
+
+/**
+ * Request header names are lowercase, so schema names must be too (as in Fastify).
+ */
+function lowercaseHeaders(schema) {
+	const out = { ...schema };
+	if (schema.properties)
+		out.properties = Object.fromEntries(Object.entries(schema.properties).map(([k, v]) => [k.toLowerCase(), v]));
+	if (schema.required) out.required = schema.required.map(k => k.toLowerCase());
+	return out;
+}
+
+
+/**
+ * Compiles all validators of one route once at startup.
+ */
+export function compileRoute(schema, ajvs, dev) {
+	const out = { request: {}, response: {} };
+
+	// 1. Request parts
+	for (const part of PARTS) {
+		const s = part === "querystring" ? (schema.querystring || schema.query) : schema[part];
+		if (s) out.request[part] = ajvs.request.compile(normalize(part, s));
+	}
+
+	// 2. Response schemas, only needed in development
+	if (dev && schema.response)
+		for (const [status, s] of Object.entries(schema.response))
+			out.response[status] = ajvs.response.compile(s);
+
+	return out;
+}
+
+
+/**
+ * Validates one request part, throws 400 like Fastify: "body/name must be string".
+ */
+export function validatePart(validate, part, data) {
+	if (validate(data)) return;
+	const e = validate.errors[0];
+	throw createError(400, `${part}${e.instancePath} ${e.message}`);
+}
+
+
+/**
+ * Development: checks the response against its schema, returns error text or null.
+ */
+export function checkResponse(validators, status, data) {
+	const validate = validators[status] || validators[`${String(status)[0]}xx`] || validators.default;
+	if (!validate) return null;
+
+	const json = data === undefined ? undefined : JSON.parse(JSON.stringify(data));
+	if (validate(json)) return null;
+
+	return validate.errors.map(e => `response${e.instancePath} ${e.message}`).join(", ");
+}

package/{templates → template}/env

@@ -4,5 +4,4 @@ NODE_ENV = development
 # PORT
 # CORS
 # SECRET
-# MONGODB
 # STATIC 

package/template/gitignore

@@ -0,0 +1,3 @@
+node_modules
+setup.js
+dist

package/template/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "__NAME__",
+	"version": "0.1.0",
+	"description": "",
+	"main": "setup.js",
+	"scripts": {
+		"dev": "maxserver dev",
+		"build": "maxserver build",
+		"start": "bun dist/bundle.js"
+	},
+	"type": "module",
+	"private": true,
+	"dependencies": {}
+}

package/{templates → template}/src/Test/hello.js

@@ -1,6 +1,6 @@
 // POST /hello
 
-export default async function handler(req, rep) {
+export default async function handler(req, res) {
 
 	console.log("POST /hello");
 

package/{templates → template}/src/Test/welcome.js

@@ -1,10 +1,10 @@
 // GET /welcome
 
-export default async function handler(req, rep) {
+export default async function handler(req, res) {
 
 	console.log("GET /welcome");
 	return {
-		message: "Weclome to maxserver 😉 - Updated",
+		message: "Welcome to maxserver 😉",
 	};
 
 }

package/{templates → template}/src/Test/welcome.schema.js

@@ -8,7 +8,7 @@ export default {
 			properties: {
 				message: {
 					type: "string",
-					example: "Weclome to maxserver 😉 - Updated"
+					example: "Welcome to maxserver 😉"
 				}
 			},
 			required: ["message"]

package/.github/README.md

@@ -1,263 +0,0 @@
-# maxserver
-Node server setup based on **Fastify** to speed up backend development.  
-
-- **Auto Routes**: auto imports and registers routes and schemas
-- **Auto Docs**: auto generates docs based on schemas
-- **Preconfigures essentials**: jwt auth, cors, helmet
-- **Auto Connect MongoDB** (optional)
-
-<br><br>
-
-## Install
-```js
-npm install maxserver
-```
-<br>
-
-## Setup
-```js
-import maxserver from "maxserver";
-
-const server = await maxserver({
-	port: 3000,
-	secret: "your_secret"
-});
-
-await server.start();
-export default server;
-```
-<br>
-
-## ⚙️ Configure
-Configs can be passed to the init call to **maxserver()** or set in your .env file.  
-If you define options in env, use all upper case letters.  
-Any fastify options can be passed to maxserver() too.
-
-
-| Variable | Default | Description |
-| :--- | :--- | :--- |
-| `port` | `3000` | Server port |
-| `secret` | *-* | Secret used for jwt and cookies |
-| `cors` | `*` | Default all allowed |
-| `docs` | `true` | Set `false` to disable auto generated docs |
-| `mongodb` | *-* | MongoDB URI, if set auto-connects db |
-| `public` | `false` | Set `true` to expose the server publicly (binds to `0.0.0.0`) |
-| `static` | *-* | If set, serves this directory statically |
-| `routesDir` | *src* | Directory to auto collect routes |
----
-
-<br>
-
-
-## 🤖 Auto Routing
-Routes are auto registered based on one small comment per file:  
-
-```
-// METHOD /path 
-```
-<br>
-
-
-```js
-// GET /hello
-
-export default async function handler(req, rep) {
-
-	console.log("GET /hello");
-	return {
-		message: "Hello world",
-	};
-
-}
-```
-<br>
-
-Doesn't matter how nested your path is or how many params,  
-It always works this simple and you are free to position your files the way you like.  
-If you don't want to autoregister some files, then simply don't add that magic comment 😃
-<br>
-<br>
-```
-// GET /teams/:teamid  
-// PATCH /forms/:formId/questions/:questionId
-...   
-```
-<br/>
-
-### 3 RULES
-1. Add magic comment
-2. Default export handler
-3. One handler per file 
-
-<br>
-
-
-## 🧾 Schemas
-Files ending with **`.schema.js`** will be auto registered.  
-For example: **hello.js** and **hello.schema.js**  
-
-Schemas are optional.
-Besides the basic validation fields we can set fields like `tags`, `summary` and description,  
-which will appear in the docs. Only if a schema exists the route will be added to the documentation.
-
-
-```js
-export default {
-
-	tags: ["Test"],
-	summary: "Post hello",
-	description: "Accepts a name and returns a greeting.",
-
-	body: {
-		type: "object",
-		required: ["name"],
-		properties: {
-			name: {
-				type: "string",
-			},
-		},
-	},
-
-	...
-};
-```
-
-
-### MODELS
-You can also auto register **models** (schemas which are shared between multiple routes).  
-For example `User.schema.js`. It "magically" understand the difference betwen route specific
-schema or generic model, by looking if a sibling file exist or not 😉
-
-<br>
-
-**‼️ Important use export default**  
-Some examples in the template folder.
-
-
-
-## 📚 API Docs
-Open in your browser **`localhost:3000/docs`**  
-You should find all your routes well documented.  
-And you can also easily test any route.
-
-<br>
-
-
-
-## Global Named Exports
-
-Every named export across your JavaScript files is automatically assigned to the Node.js `global` object on startup. This makes your utility functions, constants, or services instantly accessible anywhere in the application without manual `import` statements. The system safely ignores `default` exports and lifecycle hooks, and it will immediately halt with a clear console error if it detects duplicate variable names across different files.
-
-
-
-
-
-
-
-
-
-
-
-
-
-## 🔐 Authentication
-JWT header and cookie based auth is preconfigured.  
-To enable auth for a route set in it's schema **auth = true**  
-The authenticated user is available as **`req.userId`**
-
-```js
-// Inside schema
-
-export default {
-	auth: true
-};
-```
-
-## 🛠️ Route Options
-Though we don't mostly register routes manually, we don't set route options on the register call.  
-If needed, you can wether register that route manually or just set them on the schema.
-
-```js
-// Inside schema
-
-export default {
-	routeOptions: {
-		config: {
-			preHandler: ...
-		},
-	},
-	...
-```
-
-<br>
-<br>
-
-## 🍃 MongoDB
-Set option **`MONGODB`** your mongodbURI and it will auto-connect at server start and you get:
-
-- global **`db`** (connected database handle)
-- global **`oid(string)`** (string → MongoDB `ObjectId`)
-
-| Global | What it is | Why it exists |
-| :--- | :--- | :--- |
-| `db` | MongoDB database handle | Use it directly in handlers |
-| `oid(id)` | string → `ObjectId` | Saves you from importing everywhere `ObjectId` |
-
-### Example
-
-```js
-// Inside route handlers
-
-export default async function (req, res) {
-
-	await db.feedback.insert(...)
-}
-```
-
-
-<br>
-
-## 🧰 Error Handling
-
-Use `createError(code, message)` to stop immediately with a clean HTTP error.
-
-```js
-if (!user) throw createError(404, "User not found");
-```
-
-Rule of thumb: make the message something you would want to see at 03:00 in logs.
-
-<br>
-
-
-## Autoregister Hooks
-
-Exported functions starting with `autoregister_` automatically execute on startup and receive the Fastify `app` instance. This allows files to self-inject custom hooks, plugins, or configurations locally.
-
-### Example
-```javascript
-// In any standard .js file
-export async function autoregister_custom_auth(app) {
-	app.addHook("onRequest", async (req, reply) => {
-		// Local hook logic here
-	});
-}
-```
-
-
-
-
-## About
-- Dependencies: original fastify packages + scalar/fastify-api-reference
-- The source is simple. Everyone can read, understand and modify if needed.
-
-
-## Todo
-- document how to add fastify hooks
-- document how to pass scalar options
-- more example and best practises
-- document project setup with npx
-- npx option, atm devserver macos only
-- unit tests
-
-