@nexa-stack/framework 1.0.0

package/packages/server/src/router.ts

@@ -0,0 +1,813 @@
+import { parseListQuery } from "./query.js";
+import { t, getUi } from "../../core/src/lang.js";
+import type { ResourceDefinition } from "../../core/src/resource.js";
+import type { Database } from "../../database/src/database.js";
+import { validate } from "../../validation/src/validate.js";
+import {
+  hasRole,
+  login,
+  register,
+  userFromRequest,
+  type AuthUser,
+} from "../../auth/src/auth.js";
+import { checkPolicy, type PolicyAction } from "../../core/src/policy.js";
+import { saveUpload, storagePath, isImageExt } from "../../storage/src/upload.js";
+import { emit } from "../../events/src/index.js";
+import {
+  unreadNotifications,
+  markNotificationRead,
+  markAllRead,
+  notify,
+} from "../../notifications/src/index.js";
+import { exportResponse } from "../../export/src/index.js";
+import { runMiddleware, checkAuthRateLimit } from "./middleware.js";
+import { hook } from "../../plugins/src/index.js";
+import { cache } from "../../cache/src/index.js";
+import { config, isAuthRegisterEnabled } from "../../core/src/config.js";
+import { defaultLocale } from "../../core/src/lang.js";
+import { getResources } from "../../core/src/registry.js";
+import {
+  isDevMode,
+  getDevStatus,
+  groupRouteKey,
+  recordDevRequest,
+} from "../../core/src/dev.js";
+import { extname, join } from "path";
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { createServer as createHttpServer, type Server as HttpServer } from "node:http";
+
+type Handler = (req: Request, user: AuthUser | null) => Promise<Response> | Response;
+
+function json(data: unknown, status = 200): Response {
+  return Response.json(data, { status });
+}
+
+function error(message: string, status = 400, errors?: unknown): Response {
+  return json({ error: message, errors }, status);
+}
+
+function listCacheTtl(): number {
+  return Number(config("LIST_CACHE_TTL") || 0);
+}
+
+async function invalidateListCache(resourceName: string): Promise<void> {
+  if (listCacheTtl() <= 0) return;
+  await cache.forgetPrefix(`list:${resourceName}:`);
+}
+
+export class Router {
+  private routes: Map<string, Handler> = new Map();
+  private resources: ResourceDefinition[] = [];
+  private resourceRouteKeys = new Set<string>();
+  private customRouteKeys = new Set<string>();
+
+  constructor(
+    private db: Database,
+    private staticDir?: string,
+    private fallbackStaticDir?: string
+  ) {}
+
+  private authorize(
+    resource: ResourceDefinition,
+    action: PolicyAction,
+    user: AuthUser | null,
+    item?: Record<string, unknown>
+  ): Response | null {
+    if (resource.authRole && !hasRole(user, resource.authRole)) {
+      return error("Unauthorized", 401);
+    }
+    if (!checkPolicy(resource.policy, action, user, item)) {
+      return error("Forbidden", 403);
+    }
+    return null;
+  }
+
+  private setResourceRoute(key: string, handler: Handler): void {
+    this.resourceRouteKeys.add(key);
+    this.routes.set(key, handler);
+  }
+
+  /** Drop resource API routes and re-register from the current registry. */
+  reloadResources(): void {
+    for (const key of this.resourceRouteKeys) this.routes.delete(key);
+    this.resourceRouteKeys.clear();
+    this.resources = [];
+    for (const def of getResources()) this.registerResource(def);
+  }
+
+  registerResource(resource: ResourceDefinition): void {
+    if (!resource.hasCrud || !resource.hasApi) return;
+    this.resources.push(resource);
+
+    const base = `/api/${resource.name.toLowerCase()}`;
+
+    this.setResourceRoute(`GET ${base}`, async (req, user) => {
+      const denied = this.authorize(resource, "view", user);
+      if (denied) return denied;
+
+      const url = new URL(req.url);
+      const ttl = listCacheTtl();
+      const cacheKey = `list:${resource.name}:${url.search}`;
+      if (ttl > 0) {
+        const hit = await cache.get(cacheKey);
+        if (hit) return json(hit);
+      }
+
+      const opts = parseListQuery(url, resource);
+      const result = await this.db.paginate(
+        resource.table,
+        resource,
+        opts,
+        `${url.origin}${base}`
+      );
+      result.data = await this.enrichMany(resource, result.data);
+      if (ttl > 0) await cache.set(cacheKey, result, ttl);
+      return json(result);
+    });
+
+    this.setResourceRoute(`GET ${base}/export`, async (req, user) => {
+      const denied = this.authorize(resource, "view", user);
+      if (denied) return denied;
+      const url = new URL(req.url);
+      const format = url.searchParams.get("format") === "json" ? "json" : "csv";
+      const opts = parseListQuery(url, resource);
+      opts.limit = 10000;
+      opts.offset = 0;
+      const rows = await this.db.findAll(resource.table, opts);
+      return exportResponse(rows, format, resource.name);
+    });
+
+    this.setResourceRoute(`GET ${base}/:id`, async (req, user) => {
+      const denied = this.authorize(resource, "view", user);
+      if (denied) return denied;
+
+      const id = extractId(req.url);
+      if (id === null) return error("Invalid id", 400);
+
+      const item = await this.db.findById(resource.table, id);
+      if (!item) return error("Not found", 404);
+      if (resource.softDelete && item.deleted_at) return error("Not found", 404);
+
+      return json({ data: await this.enrich(resource, item) });
+    });
+
+    this.setResourceRoute(`POST ${base}`, async (req, user) => {
+      const denied = this.authorize(resource, "create", user);
+      if (denied) return denied;
+
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+
+      const result = validate(resource.fields, body);
+      if (!result.valid) return error("Validation failed", 422, result.errors);
+
+      const item = await this.db.insert(resource.table, result.data);
+      await invalidateListCache(resource.name);
+      await emit(`${resource.name}.created`, { id: item.id, data: item });
+      await hook("resource.created", { resource: resource.name, data: item });
+      return json({ data: await this.enrich(resource, item) }, 201);
+    });
+
+    this.setResourceRoute(`PUT ${base}/:id`, async (req, user) => {
+      const id = extractId(req.url);
+      if (id === null) return error("Invalid id", 400);
+
+      const existing = await this.db.findById(resource.table, id);
+      if (!existing) return error("Not found", 404);
+
+      const denied = this.authorize(resource, "update", user, existing);
+      if (denied) return denied;
+
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+
+      const result = validate(resource.fields, body, true);
+      if (!result.valid) return error("Validation failed", 422, result.errors);
+
+      const item = await this.db.update(resource.table, id, result.data);
+      await invalidateListCache(resource.name);
+      await emit(`${resource.name}.updated`, { id, data: item });
+      return json({ data: await this.enrich(resource, item) });
+    });
+
+    this.setResourceRoute(`DELETE ${base}/:id`, async (req, user) => {
+      const id = extractId(req.url);
+      if (id === null) return error("Invalid id", 400);
+
+      const existing = await this.db.findById(resource.table, id);
+      if (!existing) return error("Not found", 404);
+
+      const denied = this.authorize(resource, "delete", user, existing);
+      if (denied) return denied;
+
+      const force = new URL(req.url).searchParams.get("force") === "1";
+      let deleted: boolean;
+      if (resource.softDelete && !force) {
+        deleted = await this.db.softDelete(resource.table, id);
+      } else {
+        deleted = await this.db.delete(resource.table, id);
+      }
+      if (!deleted) return error("Not found", 404);
+
+      await invalidateListCache(resource.name);
+      await emit(`${resource.name}.deleted`, { id, data: existing, soft: resource.softDelete && !force });
+      return json({ data: { id, deleted: true, soft: resource.softDelete && !force } });
+    });
+
+    if (resource.softDelete) {
+      this.setResourceRoute(`POST ${base}/:id/restore`, async (req, user) => {
+        const denied = this.authorize(resource, "update", user);
+        if (denied) return denied;
+        const parts = new URL(req.url).pathname.split("/");
+        const id = Number(parts[parts.length - 2]);
+        if (!Number.isInteger(id) || id <= 0) return error("Invalid id", 400);
+        const ok = await this.db.restore(resource.table, id);
+        if (!ok) return error("Not found", 404);
+        await invalidateListCache(resource.name);
+        const item = await this.db.findById(resource.table, id);
+        return json({ data: await this.enrich(resource, item!) });
+      });
+    }
+  }
+
+  registerAuthRoutes(): void {
+    this.routes.set("POST /api/auth/register", async (req) => {
+      const limited = checkAuthRateLimit(req);
+      if (limited) return limited;
+      if (!isAuthRegisterEnabled()) {
+        return error("Registration is disabled", 403);
+      }
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+
+      const email = String(body.email ?? "");
+      const password = String(body.password ?? "");
+      if (!email || !password) return error("email and password required", 422);
+
+      try {
+        const user = await register(email, password);
+        return json({ data: user }, 201);
+      } catch {
+        return error("Email already exists", 409);
+      }
+    });
+
+    this.routes.set("POST /api/auth/login", async (req) => {
+      const limited = checkAuthRateLimit(req);
+      if (limited) return limited;
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+
+      const result = await login(String(body.email ?? ""), String(body.password ?? ""));
+      if (!result) return error("Invalid credentials", 401);
+
+      return json({ data: result });
+    });
+
+    this.routes.set("POST /api/auth/forgot-password", async (req) => {
+      const limited = checkAuthRateLimit(req);
+      if (limited) return limited;
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+      const email = String(body.email ?? "");
+      if (!email) return error("email required", 422);
+      const { forgotPassword } = await import("../../auth/src/auth.js");
+      await forgotPassword(email);
+      return json({ data: { sent: true } });
+    });
+
+    this.routes.set("POST /api/auth/reset-password", async (req) => {
+      const limited = checkAuthRateLimit(req);
+      if (limited) return limited;
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+      const email = String(body.email ?? "");
+      const token = String(body.token ?? "");
+      const password = String(body.password ?? "");
+      if (!email || !token || !password) {
+        return error("email, token and password required", 422);
+      }
+      const { resetPassword } = await import("../../auth/src/auth.js");
+      const ok = await resetPassword(email, token, password);
+      if (!ok) return error("Invalid or expired token", 422);
+      return json({ data: { reset: true } });
+    });
+
+    this.routes.set("POST /api/auth/verify-email", async (req) => {
+      let body: Record<string, unknown> = {};
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        /* allow empty — also accept query */
+      }
+      const url = new URL(req.url);
+      const email = String(body.email ?? url.searchParams.get("email") ?? "");
+      const token = String(body.token ?? url.searchParams.get("token") ?? "");
+      if (!email || !token) return error("email and token required", 422);
+      const { verifyEmail } = await import("../../auth/src/auth.js");
+      const ok = await verifyEmail(email, token);
+      if (!ok) return error("Invalid or expired token", 422);
+      return json({ data: { verified: true } });
+    });
+
+    this.routes.set("GET /api/auth/verify-email", async (req) => {
+      const url = new URL(req.url);
+      const email = String(url.searchParams.get("email") ?? "");
+      const token = String(url.searchParams.get("token") ?? "");
+      if (!email || !token) return error("email and token required", 422);
+      const { verifyEmail } = await import("../../auth/src/auth.js");
+      const ok = await verifyEmail(email, token);
+      if (!ok) return error("Invalid or expired token", 422);
+      return json({ data: { verified: true } });
+    });
+
+    this.routes.set("POST /api/auth/resend-verification", async (req) => {
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+      const email = String(body.email ?? "");
+      if (!email) return error("email required", 422);
+      const { resendVerification } = await import("../../auth/src/auth.js");
+      await resendVerification(email);
+      return json({ data: { sent: true } });
+    });
+
+    this.routes.set("POST /api/upload", async (req, user) => {
+      if (!user) return error("Unauthorized", 401);
+
+      let form: FormData;
+      try {
+        form = await req.formData();
+      } catch {
+        return error("Invalid form data", 400);
+      }
+
+      const file = form.get("file");
+      if (!(file instanceof File)) return error("file is required", 422);
+
+      const type = String(form.get("type") ?? "file");
+      const ext = extname(file.name);
+      if (type === "image" && !isImageExt(ext)) {
+        return error("Only image files allowed", 422);
+      }
+
+      try {
+        const url = await saveUpload(file);
+        return json({ data: { url, name: file.name, size: file.size } }, 201);
+      } catch (e) {
+        return error(e instanceof Error ? e.message : "Upload failed", 422);
+      }
+    });
+  }
+
+  registerNotificationRoutes(): void {
+    this.routes.set("GET /api/notifications", async (_req, user) => {
+      if (!user) return error("Unauthorized", 401);
+      const data = await unreadNotifications(user.id);
+      return json({ data });
+    });
+
+    this.routes.set("POST /api/notifications", async (req, user) => {
+      if (!user) return error("Unauthorized", 401);
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return error("Invalid JSON body", 400);
+      }
+
+      const title = String(body.title ?? "").trim();
+      if (!title) return error("title required", 422);
+
+      let targetId = user.id;
+      if (body.user_id != null && body.user_id !== "") {
+        if (user.role !== "admin") return error("Forbidden", 403);
+        targetId = Number(body.user_id);
+        if (!Number.isInteger(targetId) || targetId <= 0) return error("Invalid user_id", 422);
+      }
+
+      const viaRaw = body.via;
+      const via =
+        Array.isArray(viaRaw) && viaRaw.every((v) => v === "database" || v === "mail")
+          ? (viaRaw as ("database" | "mail")[])
+          : (["database"] as ("database" | "mail")[]);
+
+      await notify(
+        { id: targetId, email: body.email ? String(body.email) : user.email },
+        {
+          title,
+          body: body.body != null ? String(body.body) : "",
+          type: body.type != null ? String(body.type) : "app",
+          data:
+            body.data && typeof body.data === "object" && !Array.isArray(body.data)
+              ? (body.data as Record<string, unknown>)
+              : undefined,
+          via,
+        }
+      );
+
+      return json({ data: { sent: true, user_id: targetId } }, 201);
+    });
+
+    this.routes.set("POST /api/notifications/read-all", async (_req, user) => {
+      if (!user) return error("Unauthorized", 401);
+      await markAllRead(user.id);
+      return json({ data: { ok: true } });
+    });
+
+    this.routes.set("POST /api/notifications/:id/read", async (req, user) => {
+      if (!user) return error("Unauthorized", 401);
+      const parts = new URL(req.url).pathname.split("/");
+      const id = Number(parts[parts.length - 2]);
+      if (!Number.isInteger(id) || id <= 0) return error("Invalid id", 400);
+      const ok = await markNotificationRead(id, user.id);
+      if (!ok) return error("Not found", 404);
+      return json({ data: { id, read: true } });
+    });
+  }
+
+  /** Mount routes registered via `route()` from app code. */
+  registerCustomRoutes(handlers: { method: string; path: string; handler: Handler }[]): void {
+    for (const key of this.customRouteKeys) this.routes.delete(key);
+    this.customRouteKeys.clear();
+    for (const r of handlers) {
+      const key = `${r.method} ${r.path}`;
+      this.customRouteKeys.add(key);
+      this.routes.set(key, r.handler);
+    }
+  }
+
+  getRouteManifest(): ReturnType<typeof groupRouteKey>[] {
+    return [...this.routes.keys()]
+      .map((key) => groupRouteKey(key, this.resourceRouteKeys, this.customRouteKeys))
+      .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+  }
+
+  private staticDirs(): string[] {
+    return [this.staticDir, this.fallbackStaticDir].filter(Boolean) as string[];
+  }
+
+  private async servePublicFile(path: string, contentType: string): Promise<Response | null> {
+    for (const dir of this.staticDirs()) {
+      const full = join(dir, path);
+      if (!existsSync(full)) continue;
+      const buf = await readFile(full);
+      return new Response(buf, { headers: { "Content-Type": contentType } });
+    }
+    return null;
+  }
+
+  private async serveHtmlPage(fullPath: string): Promise<Response> {
+    let html = await readFile(fullPath, "utf8");
+    if (isDevMode() && !html.includes("dev-bar.js")) {
+      html = html.replace(
+        "</body>",
+        '<script src="/dev-bar.js" defer></script>\n</body>'
+      );
+    }
+    return new Response(html, {
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  }
+
+  private serializeRow(
+    resource: ResourceDefinition,
+    item: Record<string, unknown>
+  ): Record<string, unknown> {
+    const row = { ...item };
+    for (const [name, field] of Object.entries(resource.fields)) {
+      if (field.type !== "boolean" || !(name in row)) continue;
+      const v = row[name];
+      if (v === null || v === undefined) {
+        row[name] = null;
+        continue;
+      }
+      row[name] = v === 1 || v === true || v === "1" || v === "true";
+    }
+    return row;
+  }
+
+  private async enrich(resource: ResourceDefinition, item: Record<string, unknown>) {
+    const [row] = await this.enrichMany(resource, [item]);
+    return row ?? item;
+  }
+
+  private async enrichMany(
+    resource: ResourceDefinition,
+    items: Record<string, unknown>[]
+  ): Promise<Record<string, unknown>[]> {
+    if (items.length === 0) return items;
+    const rels = Object.entries(resource.fields)
+      .filter(([, f]) => !!f.relation)
+      .map(([name]) => name);
+    if (rels.length === 0) return items.map((i) => this.serializeRow(resource, i));
+
+    const ids = items.map((i) => Number(i.id)).filter((id) => id > 0);
+    if (ids.length === 0) return items.map((i) => this.serializeRow(resource, i));
+
+    const loaded = await this.db.from(resource.table).whereIn("id", ids).with(...rels).get();
+    const map = new Map(loaded.map((r) => [Number(r.id), r]));
+    return items.map((i) => this.serializeRow(resource, map.get(Number(i.id)) ?? i));
+  }
+
+  async handle(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    const user = userFromRequest(req);
+    const t0 = performance.now();
+
+    const res = await runMiddleware(req, user, async () => {
+      if (req.method === "OPTIONS") {
+        return new Response(null, { status: 204 });
+      }
+
+      if (isDevMode()) {
+        if (req.method === "GET" && path === "/dev-bar.js") {
+          const file = await this.servePublicFile("dev-bar.js", "application/javascript; charset=utf-8");
+          if (file) return file;
+        }
+
+        if (req.method === "GET" && path === "/api/dev/status") {
+          const status = getDevStatus(this.routes.size);
+          status.dialect = this.db.dialect;
+          return json({ data: status });
+        }
+
+        if (req.method === "GET" && path === "/api/dev/routes") {
+          return json({
+            data: {
+              resources: this.resources.map((r) => ({
+                name: r.name,
+                table: r.table,
+                has_api: r.hasApi,
+                has_admin: r.hasAdmin,
+                soft_delete: r.softDelete,
+              })),
+              routes: this.getRouteManifest(),
+            },
+          });
+        }
+      }
+
+      // Load balancer / k8s probes — no auth
+      if (req.method === "GET" && (path === "/health" || path === "/api/health")) {
+        return json({ ok: true, status: "healthy" });
+      }
+      if (req.method === "GET" && (path === "/ready" || path === "/api/ready")) {
+        try {
+          await this.db.getOne("SELECT 1 as ok");
+          return json({ ok: true, status: "ready", dialect: this.db.dialect });
+        } catch {
+          return error("Database not ready", 503);
+        }
+      }
+
+      if (req.method === "GET" && path.startsWith("/storage/uploads/")) {
+        const filePath = storagePath(path);
+        if (!filePath || !existsSync(filePath)) return error("Not found", 404);
+        const buf = await readFile(filePath);
+        return new Response(buf);
+      }
+
+      if (req.method === "GET" && !path.startsWith("/api")) {
+        const page = path === "/" ? "index" : path.slice(1);
+        if (!page.includes("..") && /^[a-zA-Z0-9/_-]*$/.test(page)) {
+          for (const dir of this.staticDirs()) {
+            const full = join(dir, `${page}.html`);
+            if (existsSync(full)) {
+              return this.serveHtmlPage(full);
+            }
+          }
+        }
+      }
+
+      if (req.method === "GET" && path === "/api/docs") {
+        const { readdirSync } = await import("fs");
+        const { join } = await import("path");
+        const dir = join(process.cwd(), "docs");
+        let files: string[] = [];
+        try {
+          files = readdirSync(dir)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => f.replace(/\.md$/, ""));
+        } catch {
+          files = [];
+        }
+        return json({ data: files });
+      }
+
+      if (req.method === "GET" && path.startsWith("/api/docs/")) {
+        const { readFileSync, existsSync } = await import("fs");
+        const { join } = await import("path");
+        const slug = path.slice("/api/docs/".length).replace(/[^a-zA-Z0-9_-]/g, "");
+        if (!slug) return error("Invalid doc", 400);
+        const file = join(process.cwd(), "docs", `${slug}.md`);
+        if (!existsSync(file)) return error("Not found", 404);
+        const content = readFileSync(file, "utf-8");
+        const title = content.match(/^#\s+(.+)$/m)?.[1] ?? slug;
+        return json({ data: { slug, title, content }, slug, title, content });
+      }
+
+      if (req.method === "GET" && path === "/api/schema") {
+        const locale = url.searchParams.get("lang") ?? defaultLocale();
+        const ui = getUi(locale);
+        // Login page may fetch UI strings without a token
+        if (!user) {
+          return json({ data: [], ui });
+        }
+        const schemas = this.resources
+          .filter((r) => r.hasAdmin)
+          .map((r) => ({
+            name: r.name,
+            label: r.labelKey ? t(r.labelKey, locale) : r.label,
+            auth: r.authRole,
+            softDelete: r.softDelete,
+            fields: Object.entries(r.fields).map(([name, f]) => ({
+              name,
+              label: f.label ?? name,
+              type: f.type,
+              required: f.required,
+              relation: f.relation ?? null,
+              options: f.options ?? null,
+            })),
+          }));
+        return json({ data: schemas, ui });
+      }
+
+      if (req.method === "GET" && path === "/api/dashboard") {
+        if (!user) return error("Unauthorized", 401);
+        const locale = url.searchParams.get("lang") ?? defaultLocale();
+        const stats = await Promise.all(
+          this.resources
+            .filter((r) => r.hasAdmin)
+            .map(async (r) => ({
+              name: r.name,
+              label: r.labelKey ? t(r.labelKey, locale) : r.label,
+              count: (
+                await this.db.findAll(r.table, {
+                  limit: 10000,
+                  softDelete: r.softDelete ? "exclude" : undefined,
+                })
+              ).length,
+            }))
+        );
+
+        return json({ data: { stats } });
+      }
+
+      if (req.method === "GET" && path === "/api") {
+        const endpoints = [...this.routes.keys()]
+          .filter((key) => key.startsWith("GET ") || key.startsWith("POST "))
+          .map((key) => key.replace(/^(GET|POST|PUT|DELETE) /, "$1 "));
+
+        return json({ message: "Nexa", endpoints, resources: this.resources.map((r) => r.name) });
+      }
+
+      const exactKey = `${req.method} ${path}`;
+      if (this.routes.has(exactKey)) {
+        return this.routes.get(exactKey)!(req, user);
+      }
+
+      for (const [key, handler] of this.routes) {
+        const [method, pattern] = key.split(" ");
+        if (method !== req.method) continue;
+
+        const regex = pattern.replace(/:\w+/g, "(\\d+)");
+        if (new RegExp(`^${regex}$`).test(path)) {
+          return handler(req, user);
+        }
+      }
+
+      return error("Not found", 404);
+    });
+
+    recordDevRequest(req.method, path, res.status, performance.now() - t0);
+    return res;
+  }
+}
+
+function extractId(url: string): number | null {
+  const parts = new URL(url).pathname.split("/");
+  const id = Number(parts[parts.length - 1]);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+export interface NexaServer {
+  port: number;
+  close: () => void;
+  stop: () => void;
+}
+
+export function createServer(router: Router, port = 3333): Promise<NexaServer> {
+  return new Promise(async (resolve, reject) => {
+    let tryPort = port;
+    let lastErr: unknown;
+
+    for (let attempt = 0; attempt < 10; attempt++) {
+      try {
+        const server = await listenOnce(router, tryPort);
+        if (tryPort !== port) {
+          console.warn(`[nexa] Port ${port} in use — listening on ${tryPort}`);
+        }
+        resolve(server);
+        return;
+      } catch (err: unknown) {
+        lastErr = err;
+        const code = (err as { code?: string })?.code;
+        if (code === "EADDRINUSE" && attempt < 9) {
+          tryPort++;
+          continue;
+        }
+        reject(err);
+        return;
+      }
+    }
+    reject(lastErr ?? new Error(`Could not bind a port near ${port}`));
+  });
+}
+
+function listenOnce(router: Router, port: number): Promise<NexaServer> {
+  return new Promise((resolve, reject) => {
+    const server: HttpServer = createHttpServer(async (req, res) => {
+      try {
+        const host = req.headers.host || `localhost:${port}`;
+        const url = `http://${host}${req.url || "/"}`;
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        const bodyBuf = Buffer.concat(chunks);
+        const headers = new Headers();
+        for (const [key, value] of Object.entries(req.headers)) {
+          if (value === undefined) continue;
+          if (Array.isArray(value)) {
+            for (const v of value) headers.append(key, v);
+          } else {
+            headers.set(key, value);
+          }
+        }
+        const method = req.method || "GET";
+        const request = new Request(url, {
+          method,
+          headers,
+          body: method === "GET" || method === "HEAD" ? undefined : bodyBuf,
+          duplex: "half",
+        } as RequestInit);
+
+        const response = await router.handle(request);
+        res.statusCode = response.status;
+        response.headers.forEach((value, key) => {
+          if (key.toLowerCase() === "transfer-encoding") return;
+          res.setHeader(key, value);
+        });
+        const ab = await response.arrayBuffer();
+        res.end(Buffer.from(ab));
+      } catch (e) {
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+      }
+    });
+
+    const onError = (err: Error) => {
+      server.close();
+      reject(err);
+    };
+    server.once("error", onError);
+    server.listen(port, () => {
+      server.off("error", onError);
+      const close = () => {
+        server.close();
+      };
+      resolve({ port, close, stop: close });
+    });
+  });
+}