maxserver 0.0.2

package/README.md

@@ -0,0 +1,233 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/max-matinpalo/maxserver/refs/heads/main/assets/logo.png" alt="Project logo" width="160">
+</p>
+<br>
+
+# @max-matinpalo/maxserver
+
+-> Node server setup based on **Fastify** with a great new route loader. 
+
+- **Route loader**: auto-register routes and schemas
+- **JWT auth** (cookie or `Authorization: Bearer ...`)
+- **Autogenerates docs** (`/openapi.json`) + optional UI (`/docs`)
+- **MongoDB** auto-connect + global `db` + `oid()` helper
+- **Dev server** (auto reload on changes)
+- **HTTPS** support (when configured)
+
+
+---
+
+## Quick Start
+
+```bash
+npx @max-matinpalo/maxserver my-app
+cd my-app
+npm run dev
+```
+
+---
+
+## Setup
+maxserver(options) forwards options to fastify(options).
+It returns the fully configured Fastify server instance.
+
+```js
+import maxserver from "@max-matinpalo/maxserver";
+const server = await maxserver();
+const address = await server.listen({
+	port: Number(process.env.PORT || 3000),
+});
+
+console.log("Server running at", address);
+export default server;
+```
+
+---
+
+## ⚙️ Configuration (Environment)
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `PORT` | `3000` | Server port |
+| `JWT_SECRET` | *(optional)* | Enables JWT auth (private-by-default routes) |
+| `MONGODB_URI` | *(optional)* | Enables MongoDB auto-connect + global `db` |
+| `DOCS` | `true` | Set `false` to disable docs UI at `/docs` |
+| `STATIC_DIR` | *(optional)* | Serve static files (example: `./public`) |
+| `CORS_ORIGIN` | `*` | Allowed CORS origins |
+
+---
+
+## 🗂️ Project Structure
+
+**Convention: 1 route = 1 handler file + 1 schema file (siblings).**
+
+Example:
+
+```
+src/
+	users/
+	teams/
+	forms/
+		get.js
+		get.schema.js
+	...
+```
+
+---
+
+## 🛣️ Writing Route Handlers
+
+### 1) Define method + path
+Every route file starts with:
+
+```js
+// GET /teams/:id
+```
+
+That comment is what the route loader uses to auto-register the route.
+
+### 2) Default export handler
+
+Keep handlers small, and split logic into numbered steps.
+
+If something fails, throw:
+
+```js
+throw createError(code, "Specific failure reason");
+```
+
+### Example
+
+```js
+// GET /teams/:id
+
+export default async function (req, res) {
+
+	// 1. Read input
+	const id = req.params.id;
+
+	// 2. Load data
+	const team = { id, name: "Team A" };
+
+	// 3. Respond
+	return team;
+}
+```
+
+---
+
+## 🧾 Defining Schemas
+Create a sibling file ending in **`.schema.js`**. 
+This file will be auto registered.
+
+Schemas:
+- validate inputs
+- generate OpenAPI docs
+- control auth (public/private)
+
+
+**`src/teams/get.schema.js`**
+```js
+export default {
+	tags: ["Teams"],
+	summary: "Get team",
+	description: "Returns a single team by identifier.",
+
+	params: {
+		type: "object",
+		required: ["id"],
+		properties: {
+			id: {
+				type: "string",
+				minLength: 24,
+				example: "",
+			},
+		},
+	},
+
+	response: {
+		200: {
+			type: "object",
+			properties: {
+				id: {
+					type: "string",
+					example: "507f1f77bcf86cd799439011",
+				},
+				name: { type: "string", example: "Team A" },
+			},
+			required: ["id", "name"],
+		},
+	},
+};
+```
+
+---
+
+## 🔐 Authentication (JWT)
+
+Enable auth by setting:
+
+- `JWT_SECRET`
+
+Behavior:
+- **Private by default**: routes require JWT (cookie or Bearer header)
+- Authenticated user identifier is available as **`req.userId`**
+- Make a route **public** by setting `config.public: true` in its schema
+
+```js
+export default {
+	config: { public: true },
+	// ...
+};
+```
+
+---
+
+## 🍃 MongoDB
+Define in the env **`MONGODB_URI`** 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` | Avoid importing `ObjectId` everywhere |
+
+
+---
+
+## 🧰 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 02:00 in logs.
+
+---
+
+## 📚 API Docs
+
+- OpenAPI JSON: **`/openapi.json`**
+- Optional UI: **`/docs`** (controlled via `DOCS=true`)
+
+---
+
+## 🛠️ Tips & Tools
+
+### 🔌 Scalar API Client (Live Testing)
+- Add Item → Import from OpenAPI
+- Paste: `http://localhost:3000/openapi.json`
+- Enable watch mode for live updates
+
+### ⚡ VS Code Auto-Start
+In `.vscode/tasks.json`, enable the task with:
+```json
+"runOptions": { "runOn": "folderOpen" }
+```
+
+### 🤖 AI Assistants (Code Style)
+Copy **`RULES.md`** into your AI tool as system context, then ask it to generate routes + schemas.

package/bin/watcher.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+
+
+/**
+ * maxserver-watcher
+ *
+ * A zero-config minimal development server watcher.
+ * - Watches the current project root recursively.
+ * - Restarts the node process on .js/.json changes.
+ * - Automatically loads .env if present via --env-file.
+ * - Ignores node_modules and hidden files.
+ */
+
+
+// Get entry file from args or default to server.js
+const entry = process.argv[2] || "server.js";
+let child;
+
+function start() {
+	const args = [];
+	if (fs.existsSync(".env")) args.push("--env-file=.env");
+	args.push(entry);
+
+	// Spawn the node process and share the console
+	child = spawn("node", args, { stdio: "inherit" });
+}
+
+function restart() {
+	console.clear();
+	console.log(`devserver restart`);
+	if (child) child.kill();
+	start();
+}
+
+
+fs.watch(".", { recursive: true }, (event, file) => {
+	if (!file) return;
+	if (file.includes("node_modules")) return;
+	if (file.startsWith(".")) return;
+	if (!file.endsWith(".js") && !file.endsWith(".json")) return;
+
+	console.log("\nupdated: ", file);
+	restart();
+});
+
+restart();

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "maxserver",
+	"version": "0.0.2",
+	"description": "Node server setup based fastify",
+	"author": "Max Matinpalo",
+	"type": "module",
+	"main": "src/index.js",
+	"bin": {
+		"maxserver": "bin/init.js",
+		"maxserver-watcher": "bin/watcher.js"
+	},
+	"files": [
+		"src",
+		"README.mde"
+	],
+	"dependencies": {
+		"@fastify/cookie": "^11.0.2",
+		"@fastify/cors": "^11.2.0",
+		"@fastify/helmet": "^13.0.2",
+		"@fastify/jwt": "^10.0.0",
+		"@fastify/mongodb": "^9.0.2",
+		"@fastify/static": "^9.0.0",
+		"@fastify/swagger": "^9.6.1",
+		"@scalar/fastify-api-reference": "^1.40.9",
+		"fastify": "^5.7.1"
+	}
+}

package/src/getAddress.js

@@ -0,0 +1,29 @@
+import os from "os";
+
+
+export function setupGetAddress(app) {
+	app.decorate("getAddress", function () {
+		const addr = this.server.address();
+
+		if (!addr) return null;
+		if (typeof addr === "string") return addr;
+
+		const protocol = this.initialConfig.https ? "https" : "http";
+		const host = getExternalIp() || "localhost";
+
+		return `${protocol}://${host}:${addr.port}`;
+	});
+}
+
+
+function getExternalIp() {
+	const nets = os.networkInterfaces();
+
+	for (const name of Object.keys(nets)) {
+		for (const net of nets[name]) {
+			if (net.family === "IPv4" && !net.internal) return net.address;
+		}
+	}
+
+	return null;
+}

package/src/index.js

@@ -0,0 +1,48 @@
+import Fastify from "fastify";
+
+import {
+	setupCors,
+	setupHelmet,
+	setupJwt,
+	setupMongo,
+	setupStatic,
+	setupRoutes,
+	setupDocs,
+	setupCookie,
+	getHttpsOptions,
+} from "./setup.js";
+
+import { setupGetAddress } from "./getAddress.js";
+
+
+
+export default async function maxserver(options = {}) {
+
+	const app = Fastify({
+		trustProxy: true,
+		https: getHttpsOptions() || undefined,
+
+		// To allow writing example field to schema for doucumentation 
+		ajv: { customOptions: { strictSchema: false } },
+		...options,
+	});
+
+	global.createError = function (code, message) {
+		const err = new Error(message);
+		err.statusCode = code;
+		return err;
+	};
+
+	setupGetAddress(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);
+
+
+	return app;
+}

package/src/routeLoader.js

@@ -0,0 +1,122 @@
+// Scans src/** for files whose first line looks like:
+// POST /teams/create
+// Imports handler + schema and registers them with Fastify.
+
+import fs from "fs";
+import path from "path";
+
+const ROUTE_OPTION_KEYS = new Set([
+	"config",
+	"preHandler",
+	"onRequest",
+	"preValidation",
+	"preSerialization",
+	"errorHandler",
+	"logLevel",
+	"bodyLimit",
+	"attachValidation",
+	"exposeHeadRoute",
+	"constraints",
+	"timeout",
+	"websocket",
+	"prefixTrailingSlash",
+]);
+
+function walk(dir, out = []) {
+	if (!fs.existsSync(dir)) return out;
+	const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (entry.name === "node_modules") continue;
+		if (entry.name.startsWith(".")) continue;
+		const full = path.join(dir, entry.name);
+
+		if (entry.isDirectory()) {
+			walk(full, out);
+		} else if (entry.name.endsWith(".js")) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+function getFirstLine(file) {
+	const text = fs.readFileSync(file, "utf8");
+	const lines = text.split("\n");
+	const firstContent = lines.find((line) => line.trim().length > 0);
+
+	return (firstContent || "").trim().replace(/^\uFEFF/, "");
+}
+
+const ROUTE_REGEX = /^\/\/\s*(GET|POST|PUT|PATCH|DELETE)\s+(.+)$/;
+
+function parseRouteComment(file) {
+	const line = getFirstLine(file);
+	const m = line.match(ROUTE_REGEX);
+	if (!m) return null;
+
+	return { method: m[1].toLowerCase(), url: m[2] };
+}
+
+function splitSchemaExport(raw) {
+	const routeOptions = {};
+	const schema = {};
+
+	for (const [key, value] of Object.entries(raw || {})) {
+		if (ROUTE_OPTION_KEYS.has(key)) {
+			routeOptions[key] = value;
+			continue;
+		}
+		schema[key] = value;
+	}
+
+	return { routeOptions, schema };
+}
+
+export async function loadRoutes(fastify) {
+	const ROOT = path.join(process.cwd(), "src");
+	const files = walk(ROOT);
+	const seen = new Map();
+
+	for (const file of files) {
+		if (file.endsWith(".schema.js")) continue;
+
+		const info = parseRouteComment(file);
+		if (!info) continue;
+
+		const key = info.method + " " + info.url;
+		if (seen.has(key)) {
+			throw new Error(
+				`Duplicate route "${key}" detected:\n` +
+				`1. ${seen.get(key)}\n` +
+				`2. ${file}`
+			);
+		}
+		seen.set(key, file);
+
+		const handlerMod = await import("file://" + file);
+		const handler = handlerMod.default;
+
+		const schemaFile = file.replace(/\.js$/, ".schema.js");
+		let raw = null;
+
+		if (fs.existsSync(schemaFile)) {
+			const schemaMod = await import("file://" + schemaFile);
+			raw = schemaMod.default || {};
+		} else {
+			fastify.log.warn(
+				`Route schema missing: ` +
+				`${info.method.toUpperCase()} ${info.url}`
+			);
+			raw = {};
+		}
+
+		const parts = splitSchemaExport(raw);
+
+		fastify[info.method](
+			info.url,
+			{ ...parts.routeOptions, schema: parts.schema },
+			handler
+		);
+	}
+}

package/src/setup.js

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import cors from "@fastify/cors";
+import jwt from "@fastify/jwt";
+import cookie from "@fastify/cookie";
+import mongodb from "@fastify/mongodb";
+import fastifyStatic from "@fastify/static";
+import helmet from "@fastify/helmet";
+import swagger from "@fastify/swagger";
+import apiReference from "@scalar/fastify-api-reference";
+
+import { loadRoutes } from "./routeLoader.js";
+
+
+export async function setupCookie(app) {
+	// Use COOKIE_SECRET or fall back to JWT_SECRET so you don't need a new env var immediately
+	const secret = process.env.COOKIE_SECRET || process.env.JWT_SECRET || "change-me-in-prod";
+
+	await app.register(cookie, {
+		secret,
+		hook: "onRequest", // Crucial: Ensures cookies are parsed before your route handlers run
+		parseOptions: {}
+	});
+}
+
+
+
+export async function setupHelmet(app) {
+	await app.register(helmet, {
+		contentSecurityPolicy: false,
+		crossOriginResourcePolicy: {
+			policy: "cross-origin"
+		}
+	});
+}
+
+export async function setupCors(app) {
+	const isProd = process.env.NODE_ENV === "production";
+	const origin = process.env.CORS_ORIGIN || true;
+
+	if (isProd && !process.env.CORS_ORIGIN) app.log.warn("CORS_ORIGIN not set, allowing all origins");
+
+	await app.register(cors, { origin });
+}
+
+
+
+export async function setupRoutes(app) {
+	await loadRoutes(app);
+}
+
+export function getHttpsOptions() {
+	const { TLS_KEY, TLS_CERT } = process.env;
+	if (!TLS_KEY || !TLS_CERT) return null;
+
+	try {
+		return {
+			key: fs.readFileSync(TLS_KEY),
+			cert: fs.readFileSync(TLS_CERT),
+		};
+	} catch (err) {
+		throw new Error(`TLS read failed: ${err.message || err}`);
+	}
+}
+
+
+
+
+
+function isAuthSkippableUrl(url) {
+	if (!url) return false;
+	if (url.startsWith("/openapi.json")) return true;
+	if (url.startsWith("/docs")) return true;
+	if (url.startsWith("/static/")) return true;
+	return false;
+}
+
+export async function setupJwt(app) {
+	const secret = process.env.JWT_SECRET;
+	if (!secret) return;
+
+	// because we added own cookie setup function above
+	//await app.register(cookie);
+
+	await app.register(jwt, { secret, cookie: { cookieName: "token" } });
+
+	app.addHook("onRequest", async function (req) {
+		if (req.method === "OPTIONS") return;
+
+		const url = req.raw?.url || req.url;
+		if (isAuthSkippableUrl(url)) return;
+		if (req.routeOptions?.config?.public) return;
+
+		await req.jwtVerify();
+
+		const u = req.user;
+		req.userId = u?.sub || u?.userId || u?.userid || u?.id || null;
+	});
+}
+
+export async function setupMongo(app) {
+
+	const url = process.env.MONGODB_URI;
+	if (!url) return;
+
+	await app.register(mongodb, { url });
+
+	// ObjectId is available on app.mongo after registration
+	const { ObjectId, db } = app.mongo;
+
+	global.oid = id => new ObjectId(id ? String(id) : undefined);
+	global.db = db;
+}
+
+export async function setupStatic(app) {
+	const dir = process.env.STATIC_DIR;
+	if (!dir) return;
+
+	await app.register(fastifyStatic, {
+		root: path.resolve(dir),
+		prefix: "/static/",
+	});
+}
+
+export async function setupDocs(app) {
+	const defaultSecurity = [{ bearerAuth: [] }, { cookieAuth: [] }];
+
+	await app.register(swagger, {
+		openapi: {
+			components: {
+				securitySchemes: {
+					bearerAuth: { type: "http", scheme: "bearer" },
+					cookieAuth: { type: "apiKey", in: "cookie", name: "token" },
+				},
+			},
+		},
+	});
+
+	app.get("/openapi.json", { config: { public: true } }, () => app.swagger());
+
+	await app.register(apiReference, { routePrefix: "/docs", openapi: true });
+
+	app.addHook("onRoute", (route) => {
+		if (route.config?.public) return;
+		route.schema ||= {};
+		route.schema.security = defaultSecurity;
+	});
+}