mates-fullstack 1.0.0-beta.1

package/dist/server.js

@@ -0,0 +1,1218 @@
+/**
+ * mates-fullstack — server.ts
+ *
+ * Pure Node.js (node:http) HTTP server.
+ * No express, no hono, no fastify, no Bun APIs.
+ *
+ * Request routing order:
+ *  1.  GET  /health, /healthz              → 200 JSON { status: "ok", timestamp }
+ *  2.  GET  /__mates_reload  (dev only)    → SSE live-reload stream
+ *  3.  POST /__mates_log     (dev only)    → console.log browser messages
+ *  4.  GET  /_mates/*                      → virtual files (rpc-client.js, errors.js, etc.)
+ *  5.  Upgrade: websocket                  → emit "upgrade" (caller handles WS)
+ *  6.  onRequest hooks                 → raw HTTP escape hatch
+ *  7.  GET  /api/docs                      → docs page (dev or API_DOCS=true)
+ *  8.  POST /api/**                        → RPC runner
+ *  9.       /api/**  (non-POST)            → 405
+ * 10.  Static assets: /assets/** or public/→ serveStatic()
+ * 11.  GET  /**                            → renderPage() (SSR)
+ * 12.  (other methods) /**                 → 405
+ * 13.  fallthrough                         → 404
+ */
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { createContext, applyResHeaders } from "./ctx.js";
+import { runRpcRequest } from "./rpc-runner.js";
+import { runRequestHooks, runResponseHooks } from "./middleware.js";
+import { lookupRpcFn } from "./rpc-registry.js";
+import { isPathInside } from "./project-resolver.js";
+import { serializeError } from "./errors.js";
+import { getPublicEnv } from "./env-loader.js";
+import { isRedirect } from "./redirect.js";
+import { devLog, devWarn, devError, fatalError, startupLog } from "./log.js";
+import { _getServerTimeoutMs } from "./server-timeout.js";
+import { matchAndRunRest } from "./rest.js";
+import { runWithContext, setSSRContext } from "./ssr-context.js";
+import { BROWSER_LOG_ENDPOINT, INTERNAL_ASSET_PREFIX, INTERNAL_MATES_PREFIX, INTERNAL_PKG_PREFIX, INTERNAL_SRC_PREFIX, RELOAD_ENDPOINT, RUNTIME_RELOAD_ENDPOINT, } from "./internal-prefixes.js";
+const _serverConfig = {
+    staticStreamTimeout: 60000,
+    maxSseClients: 500,
+};
+/**
+ * Configure server-level limits. Call before startServer().
+ */
+export function configureServer(options) {
+    if (options.staticStreamTimeout !== undefined)
+        _serverConfig.staticStreamTimeout = options.staticStreamTimeout;
+    if (options.maxSseClients !== undefined)
+        _serverConfig.maxSseClients = options.maxSseClients;
+}
+// ─── MIME types ───────────────────────────────────────────────────────────────
+const MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".txt": "text/plain; charset=utf-8",
+    ".map": "application/json",
+    ".wasm": "application/wasm",
+    ".xml": "application/xml",
+    ".pdf": "application/pdf",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".webm": "video/webm",
+    ".ogg": "audio/ogg",
+};
+// ─── Security headers ─────────────────────────────────────────────────────────
+const BASE_SECURITY_HEADERS = {
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+    "X-XSS-Protection": "0",
+    "Cross-Origin-Opener-Policy": "same-origin",
+    "Cross-Origin-Resource-Policy": "same-site",
+    Server: "mates",
+    "X-Powered-By": "",
+};
+const CSP_DEV = "default-src 'self'; " +
+    "script-src 'self' 'unsafe-inline'; " +
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+    "img-src 'self' data: https:; " +
+    "font-src 'self' https://fonts.gstatic.com; " +
+    "connect-src 'self'; " +
+    "frame-ancestors 'none'";
+const CSP_PROD = "default-src 'self'; " +
+    "script-src 'self'; " +
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+    "img-src 'self' data: https:; " +
+    "font-src 'self' https://fonts.gstatic.com; " +
+    "connect-src 'self'; " +
+    "frame-ancestors 'none'";
+const HSTS = "max-age=63072000; includeSubDomains; preload";
+// ─── Module-level state ───────────────────────────────────────────────────────
+/** Set of connected SSE reload clients */
+const _sseClients = new Set();
+/** Current SSE generation string */
+let _sseGeneration = "0";
+/**
+ * Last HMR message broadcast to clients, serialized as a single line of JSON.
+ * Sent verbatim to newly-connected clients so they can establish a baseline
+ * generation without triggering a reload.
+ */
+let _sseMessage = JSON.stringify({ t: _sseGeneration, kind: "init" });
+/** Active request counter */
+let _activeRequests = 0;
+/** Whether graceful shutdown is in progress */
+let _isShuttingDown = false;
+/** Callbacks to call when active requests reach zero during shutdown */
+const _drainCallbacks = [];
+// ─── Public helpers ───────────────────────────────────────────────────────────
+/**
+ * Trigger an HMR event for all connected dev clients.
+ * Called by the CLI (via the runtime-reload endpoint) when a file change
+ * triggers a rebuild.
+ *
+ * `update.kind === "css"` swaps the stylesheet in place (no page reload,
+ * preserving application state); anything else falls back to a full reload.
+ */
+export function notifyReload(generation, update = { kind: "reload" }) {
+    _sseGeneration = generation;
+    _sseMessage = JSON.stringify({ t: generation, ...update });
+    devLog(`dev ${update.kind} update (generation ${generation}) — ` +
+        `notifying ${_sseClients.size} browser(s)`);
+    for (const client of _sseClients) {
+        try {
+            client.write(`data: ${_sseMessage}\n\n`);
+        }
+        catch {
+            // Client disconnected — will be cleaned up on "close"
+        }
+    }
+}
+/**
+ * Returns the current number of in-flight requests.
+ */
+export function getActiveRequests() {
+    return _activeRequests;
+}
+/**
+ * Returns the client IP address from the request.
+ * When trustProxy=true, reads X-Forwarded-For / X-Real-IP first.
+ */
+export function getClientIp(req, trustProxy) {
+    if (trustProxy) {
+        const forwarded = req.headers["x-forwarded-for"];
+        if (forwarded) {
+            const first = Array.isArray(forwarded)
+                ? forwarded[0]
+                : forwarded.split(",")[0];
+            return first.trim();
+        }
+        const realIp = req.headers["x-real-ip"];
+        if (realIp) {
+            return Array.isArray(realIp) ? realIp[0] : realIp;
+        }
+    }
+    return req.socket?.remoteAddress ?? "unknown";
+}
+// ─── Security header application ─────────────────────────────────────────────
+function applySecurityHeaders(res, dev, isHtml = false) {
+    if (res.headersSent)
+        return;
+    for (const [key, value] of Object.entries(BASE_SECURITY_HEADERS)) {
+        // X-Powered-By: set to empty removes it from common middleware defaults
+        if (key === "X-Powered-By") {
+            res.removeHeader("X-Powered-By");
+            continue;
+        }
+        res.setHeader(key, value);
+    }
+    if (isHtml) {
+        res.setHeader("Content-Security-Policy", dev ? CSP_DEV : CSP_PROD);
+        if (!dev) {
+            res.setHeader("Strict-Transport-Security", HSTS);
+        }
+    }
+}
+// ─── JSON response helpers ────────────────────────────────────────────────────
+function sendJson(res, status, data, dev) {
+    if (res.headersSent)
+        return;
+    let body;
+    try {
+        body = JSON.stringify(data);
+    }
+    catch {
+        body = '{"error":"Serialization error"}';
+    }
+    const buf = Buffer.from(body, "utf8");
+    applySecurityHeaders(res, dev, false);
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.setHeader("Content-Length", buf.byteLength);
+    res.writeHead(status);
+    res.end(buf);
+}
+function sendError(res, status, message, dev) {
+    sendJson(res, status, { error: message, status }, dev);
+}
+function send404(res, dev) {
+    sendError(res, 404, "Not Found", dev);
+}
+function send405(res, dev) {
+    if (!res.headersSent) {
+        applySecurityHeaders(res, dev, false);
+        res.setHeader("Allow", "GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS");
+    }
+    sendError(res, 405, "Method Not Allowed", dev);
+}
+function send400(res, message, dev) {
+    sendError(res, 400, message, dev);
+}
+function send401(res, message, dev) {
+    if (!res.headersSent) {
+        res.setHeader("WWW-Authenticate", 'Bearer realm="mates-api-docs"');
+    }
+    sendError(res, 401, message, dev);
+}
+function send500(res, dev) {
+    sendError(res, 500, "Internal Server Error", dev);
+}
+function createFetchRequest(req, pathname, trustProxy) {
+    const host = req.headers.host ?? "localhost";
+    const forwardedProto = req.headers["x-forwarded-proto"];
+    const proto = trustProxy && forwardedProto
+        ? Array.isArray(forwardedProto)
+            ? forwardedProto[0]
+            : forwardedProto.split(",")[0].trim()
+        : "http";
+    const url = new URL(req.url ?? pathname, `${proto}://${host}`);
+    const method = (req.method ?? "GET").toUpperCase();
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else {
+            headers.set(key, value);
+        }
+    }
+    const init = { method, headers };
+    if (method !== "GET" && method !== "HEAD") {
+        init.body = req;
+        init.duplex = "half";
+    }
+    return new Request(url, init);
+}
+async function sendFetchResponse(response, ctx, req, res, dev) {
+    if (res.headersSent)
+        return;
+    const contentType = response.headers.get("content-type") ?? "";
+    applySecurityHeaders(res, dev, contentType.includes("text/html"));
+    response.headers.forEach((value, key) => {
+        if (key.toLowerCase() === "set-cookie")
+            return;
+        res.setHeader(key, value);
+    });
+    const setCookies = response.headers.getSetCookie?.();
+    if (setCookies?.length) {
+        res.setHeader("set-cookie", setCookies);
+    }
+    else {
+        const setCookie = response.headers.get("set-cookie");
+        if (setCookie)
+            res.setHeader("set-cookie", setCookie);
+    }
+    applyResHeaders(ctx.resHeaders, res);
+    const body = Buffer.from(await response.arrayBuffer());
+    res.statusCode = response.status;
+    res.statusMessage = response.statusText || res.statusMessage;
+    if (!res.hasHeader("Content-Length")) {
+        res.setHeader("Content-Length", body.byteLength);
+    }
+    if (req.method?.toUpperCase() === "HEAD") {
+        res.end();
+        return;
+    }
+    res.end(body);
+}
+// ─── Static file serving ─────────────────────────────────────────────────────
+function serveStatic(pathname, publicDir, req, res, dev) {
+    // Strip null bytes to prevent null-byte injection attacks
+    if (pathname.includes("\0")) {
+        send404(res, dev);
+        return;
+    }
+    // Safely resolve and check for path traversal
+    const filePath = path.resolve(publicDir, "." + pathname);
+    if (!isPathInside(publicDir, filePath)) {
+        send404(res, dev);
+        return;
+    }
+    // Resolve symlinks to prevent symlink escapes outside public dir
+    let realPath;
+    try {
+        realPath = fs.realpathSync(filePath);
+    }
+    catch {
+        send404(res, dev);
+        return;
+    }
+    if (!isPathInside(publicDir, realPath)) {
+        send404(res, dev);
+        return;
+    }
+    let stat;
+    try {
+        stat = fs.statSync(realPath);
+    }
+    catch {
+        send404(res, dev);
+        return;
+    }
+    if (!stat.isFile()) {
+        send404(res, dev);
+        return;
+    }
+    // ETag based on mtime + size
+    const etag = `"${stat.mtimeMs}-${stat.size}"`;
+    const ifNoneMatch = req.headers["if-none-match"];
+    if (!dev && ifNoneMatch === etag) {
+        applySecurityHeaders(res, dev, false);
+        res.writeHead(304);
+        res.end();
+        return;
+    }
+    // Cache-Control
+    let cacheControl;
+    if (dev) {
+        cacheControl = "no-store";
+    }
+    else if (pathname.startsWith("/assets/")) {
+        cacheControl = "public, max-age=31536000, immutable";
+    }
+    else {
+        cacheControl = "public, max-age=3600";
+    }
+    const ext = path.extname(realPath).toLowerCase();
+    const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+    if (res.headersSent)
+        return;
+    applySecurityHeaders(res, dev, false);
+    res.setHeader("Content-Type", contentType);
+    res.setHeader("Cache-Control", cacheControl);
+    res.setHeader("ETag", etag);
+    res.setHeader("Content-Length", stat.size);
+    res.writeHead(200);
+    // Set a timeout on slow client connections to prevent resource exhaustion
+    // A client reading a large file very slowly should not hold the connection indefinitely
+    req.setTimeout(_serverConfig.staticStreamTimeout, () => {
+        if (!res.headersSent && !res.writableEnded) {
+            res.end();
+        }
+        req.destroy();
+    });
+    const stream = fs.createReadStream(realPath);
+    stream.on("error", (err) => {
+        if (!res.headersSent && !res.writableEnded) {
+            res.end();
+        }
+        devError("static stream error:", err.message);
+    });
+    stream.pipe(res);
+}
+// ─── Dev package module serving ───────────────────────────────────────────────
+function _parsePkgRequest(pathname) {
+    const parts = pathname
+        .replace(new RegExp(`^${INTERNAL_PKG_PREFIX}/`), "")
+        .split("/")
+        .filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const scoped = parts[0].startsWith("@");
+    const pkg = scoped ? `${parts[0]}/${parts[1] ?? ""}` : parts[0];
+    const relParts = parts.slice(scoped ? 2 : 1);
+    return { pkg, rel: relParts.join("/") };
+}
+function _findPackageDir(projectRoot, pkg) {
+    const direct = path.join(projectRoot, "node_modules", pkg);
+    if (fs.existsSync(path.join(direct, "package.json")))
+        return direct;
+    try {
+        const req = createRequire(path.join(projectRoot, "package.json"));
+        const pkgJson = req.resolve(`${pkg}/package.json`);
+        return path.dirname(pkgJson);
+    }
+    catch {
+        return null;
+    }
+}
+function _resolvePackageExport(pkgDir, rel) {
+    const pkgJson = path.join(pkgDir, "package.json");
+    if (!fs.existsSync(pkgJson))
+        return null;
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+    if (rel) {
+        const explicit = path.join(pkgDir, rel);
+        if (fs.existsSync(explicit) && fs.statSync(explicit).isFile())
+            return explicit;
+        if (fs.existsSync(`${explicit}.js`))
+            return `${explicit}.js`;
+        if (fs.existsSync(`${explicit}.ts`))
+            return `${explicit}.ts`;
+    }
+    const exportKey = rel ? `./${rel}` : ".";
+    const exp = resolvePackageExportValue(pkg.exports, exportKey);
+    const target = typeof exp === "string"
+        ? exp
+        : (exp?.browser ??
+            exp?.import ??
+            exp?.module ??
+            exp?.default ??
+            (rel ? null : (pkg.module ?? pkg.main)));
+    if (!target || typeof target !== "string")
+        return null;
+    return path.resolve(pkgDir, target);
+}
+function resolvePackageExportValue(exportsField, exportKey) {
+    if (!exportsField)
+        return null;
+    if (typeof exportsField === "string")
+        return exportKey === "." ? exportsField : null;
+    if (exportKey === "." && (exportsField.import || exportsField.default)) {
+        return exportsField;
+    }
+    return exportsField[exportKey] ?? null;
+}
+function _packageImportUrl(projectRoot, spec, exportRel) {
+    const parts = spec.split("/");
+    const scoped = parts[0].startsWith("@");
+    const pkg = scoped ? `${parts[0]}/${parts[1]}` : parts[0];
+    const rel = exportRel ?? parts.slice(scoped ? 2 : 1).join("/");
+    const pkgDir = _findPackageDir(projectRoot, pkg);
+    if (!pkgDir)
+        return null;
+    const file = _resolvePackageExport(pkgDir, rel);
+    if (!file)
+        return null;
+    const relFile = path.relative(pkgDir, file).split(path.sep).join("/");
+    return `${INTERNAL_PKG_PREFIX}/${pkg}/${relFile}`;
+}
+export function buildDevImportMap(projectRoot) {
+    const imports = {};
+    const matesUrl = _packageImportUrl(projectRoot, "mates");
+    if (matesUrl) {
+        imports.mates = matesUrl;
+        imports["mates/"] = `${INTERNAL_PKG_PREFIX}/mates/`;
+    }
+    const litHtmlUrl = _packageImportUrl(projectRoot, "lit-html");
+    if (litHtmlUrl) {
+        imports["lit-html"] = litHtmlUrl;
+        imports["lit-html/"] = `${INTERNAL_PKG_PREFIX}/lit-html/`;
+    }
+    // Browser-side imports of the fullstack package must use the browser-safe
+    // entry. The public server barrel exports Node-only modules like server.js.
+    for (const pkg of ["mates-fullstack"]) {
+        const browserUrl = _packageImportUrl(projectRoot, pkg, "browser");
+        if (browserUrl)
+            imports[pkg] = browserUrl;
+        const clientUrl = _packageImportUrl(projectRoot, `${pkg}/client`);
+        if (clientUrl)
+            imports[`${pkg}/client`] = clientUrl;
+        if (browserUrl || clientUrl)
+            imports[`${pkg}/`] = `${INTERNAL_PKG_PREFIX}/${pkg}/`;
+    }
+    const devtoolsUrl = _packageImportUrl(projectRoot, "mates-devtools");
+    if (devtoolsUrl) {
+        imports["mates-devtools"] = devtoolsUrl;
+        imports["mates-devtools/"] = `${INTERNAL_PKG_PREFIX}/mates-devtools/`;
+    }
+    return imports;
+}
+// ─── SSE live-reload ──────────────────────────────────────────────────────────
+function handleSseReload(req, res) {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.writeHead(200);
+    // Send the current HMR message immediately so the client can establish a
+    // baseline generation (and detect a stale page after a server restart).
+    res.write(`data: ${_sseMessage}\n\n`);
+    // Limit SSE clients to prevent resource exhaustion from too many connections
+    if (_sseClients.size >= _serverConfig.maxSseClients) {
+        // Remove oldest client to make room
+        const oldest = _sseClients.values().next().value;
+        if (oldest) {
+            oldest.end();
+            _sseClients.delete(oldest);
+        }
+    }
+    _sseClients.add(res);
+    const cleanup = () => {
+        _sseClients.delete(res);
+    };
+    res.on("close", cleanup);
+    res.on("error", cleanup);
+    // Keep the connection alive
+    req.on("close", () => {
+        _sseClients.delete(res);
+        if (!res.writableEnded) {
+            res.end();
+        }
+    });
+}
+// ─── API docs ─────────────────────────────────────────────────────────────────
+function isApiDocsEnabled(dev) {
+    return dev || process.env.API_DOCS === "true";
+}
+function isApiDocsAuthorized(req, dev) {
+    // Dev mode: always authorized
+    if (dev)
+        return true;
+    // Production: check for explicit public access flag
+    if (process.env.API_DOCS_PUBLIC === "true")
+        return true;
+    // Production: require a token
+    const token = process.env.API_DOCS_TOKEN;
+    if (!token)
+        return false;
+    const auth = req.headers.authorization;
+    const bearer = Array.isArray(auth) ? auth[0] : auth;
+    if (bearer === `Bearer ${token}`)
+        return true;
+    const header = req.headers["x-api-docs-token"];
+    const tokenHeader = Array.isArray(header) ? header[0] : header;
+    return tokenHeader === token;
+}
+async function handleApiDocs(res, dev, apiDir, sharedTypesDir, projectRoot) {
+    try {
+        const { generateDocs } = (await import("./docs-generator.js"));
+        const { serveDocsPage } = (await import("./docs-page.js"));
+        const docs = apiDir
+            ? await generateDocs(apiDir, sharedTypesDir, projectRoot)
+            : [];
+        applySecurityHeaders(res, dev, true);
+        serveDocsPage(res, docs, dev);
+    }
+    catch (err) {
+        // Fallback: minimal plain-text response if docs modules fail
+        if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end("API docs unavailable.");
+        }
+    }
+}
+// ─── Dev no-bundle source/module serving ─────────────────────────────────────
+const DEV_MODULE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|json|css)$/i;
+async function serveDevSourceModule(pathname, res, options) {
+    if (!options.dev || !options.noBundle)
+        return false;
+    const sourceRoot = path.resolve(options.sourceRoot ?? options.projectRoot);
+    const rel = pathname
+        .replace(new RegExp(`^${INTERNAL_SRC_PREFIX}/?`), "")
+        .replace(/^\/+/, "");
+    // Client code may import server/api/** (converted to RPC stubs), but all
+    // other server/** files remain server-only in no-bundle mode too.
+    if (rel.startsWith("server/") && !rel.startsWith("server/api/"))
+        return false;
+    const filePath = path.resolve(sourceRoot, rel);
+    if (!isPathInside(sourceRoot, filePath) ||
+        !DEV_MODULE_EXT_RE.test(filePath)) {
+        return false;
+    }
+    const { transformDevModule } = await import("./build-esbuild.js");
+    const sourceUrl = `${INTERNAL_SRC_PREFIX}/${rel}`;
+    const result = await transformDevModule(filePath, {
+        projectRoot: sourceRoot,
+        moduleRoot: sourceRoot,
+        modulePrefix: INTERNAL_SRC_PREFIX,
+        apiDir: options.sourceApiDir ?? options.paths.apiDir,
+        publicEnv: getPublicEnv(),
+        sourceUrl,
+        importMap: buildDevImportMap(options.projectRoot),
+    });
+    if (!result)
+        return false;
+    sendJsModule(res, result.code, options.dev);
+    return true;
+}
+async function serveDevPackageModule(pathname, res, options) {
+    if (!options.dev || !options.noBundle)
+        return false;
+    const parsed = _parsePkgRequest(pathname);
+    if (!parsed)
+        return false;
+    const pkgDir = _findPackageDir(options.projectRoot, parsed.pkg);
+    if (!pkgDir)
+        return false;
+    const filePath = _resolvePackageExport(pkgDir, parsed.rel);
+    if (!filePath || !isPathInside(pkgDir, filePath))
+        return false;
+    if (!DEV_MODULE_EXT_RE.test(filePath)) {
+        const relFile = "/" + path.relative(pkgDir, filePath).split(path.sep).join("/");
+        serveStatic(relFile, pkgDir, { headers: {}, method: "GET" }, res, options.dev);
+        return true;
+    }
+    const { transformDevModule } = await import("./build-esbuild.js");
+    const modulePrefix = `${INTERNAL_PKG_PREFIX}/${parsed.pkg}`;
+    const sourceUrl = `${modulePrefix}/${path.relative(pkgDir, filePath).split(path.sep).join("/")}`;
+    const result = await transformDevModule(filePath, {
+        projectRoot: options.projectRoot,
+        moduleRoot: pkgDir,
+        modulePrefix,
+        apiDir: null,
+        publicEnv: getPublicEnv(),
+        sourceUrl,
+        importMap: buildDevImportMap(options.projectRoot),
+    });
+    if (!result)
+        return false;
+    sendJsModule(res, result.code, options.dev);
+    return true;
+}
+function serveDevAsset(pathname, req, res, options) {
+    if (!options.dev || !options.noBundle)
+        return false;
+    const sourceRoot = path.resolve(options.sourceRoot ?? options.projectRoot);
+    const rel = pathname
+        .replace(new RegExp(`^${INTERNAL_ASSET_PREFIX}/?`), "")
+        .replace(/^\/+/, "");
+    const filePath = path.resolve(sourceRoot, rel);
+    if (!isPathInside(sourceRoot, filePath))
+        return false;
+    try {
+        if (!fs.statSync(filePath).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    // Serve the raw file. The no-bundle transform replaces `import logo from "./logo.svg"`
+    // with `const logo = "/_asset/..."` — the URL is always used as a plain string, never
+    // as a live ESM import. So browsers fetching <img src> or CSS url() get the real content.
+    serveStatic("/" + rel, sourceRoot, req, res, options.dev);
+    return true;
+}
+function sendJsModule(res, code, dev) {
+    const buf = Buffer.from(code, "utf-8");
+    applySecurityHeaders(res, dev, false);
+    res.writeHead(200, {
+        "Content-Type": "application/javascript; charset=utf-8",
+        "Content-Length": buf.length,
+        "Cache-Control": "no-store",
+    });
+    res.end(buf);
+}
+function getCurrentCssFilename(options) {
+    const configured = options.cssFilename;
+    const assetsDir = path.join(options.paths.outDir, "assets");
+    if (configured && fs.existsSync(path.join(assetsDir, configured))) {
+        return configured;
+    }
+    if (!fs.existsSync(assetsDir))
+        return null;
+    return (fs
+        .readdirSync(assetsDir)
+        .filter((file) => /^styles.*\.css$/i.test(file))
+        .sort()
+        .at(-1) ?? null);
+}
+// ─── Request tracking ─────────────────────────────────────────────────────────
+async function refreshDevRuntime(options, generation, kind = "full", changedPath = null) {
+    const { paths } = options;
+    const gen = generation ?? Date.now().toString(36);
+    // CSS-only updates don't touch server modules — swap the single linked
+    // stylesheet in the browser without reloading application state.
+    if (kind === "css") {
+        const cssFilename = getCurrentCssFilename(options);
+        const css = cssFilename ? `/assets/${cssFilename}` : null;
+        notifyReload(gen, css ? { kind: "css", css } : { kind: "reload" });
+        return;
+    }
+    if (kind === "js" && changedPath) {
+        const { clearTransformCache } = await import("./build-esbuild.js");
+        clearTransformCache();
+        notifyReload(gen, { kind: "js", path: changedPath });
+        return;
+    }
+    if (paths.apiDir) {
+        const { scanRpcFunctions } = await import("./rpc-registry.js");
+        await scanRpcFunctions(paths.apiDir, true);
+    }
+    if (paths.socketDir) {
+        const { scanSocketHandlers } = await import("./socket-router.js");
+        await scanSocketHandlers(paths.socketDir, true);
+    }
+    if (paths.mainFile) {
+        const { reloadMainFile } = await import("./main-runner.js");
+        await reloadMainFile(paths.mainFile);
+    }
+    notifyReload(gen, { kind: "reload" });
+}
+function trackRequest(res) {
+    _activeRequests++;
+    // Both "finish" (response sent) and "close" (socket closed) can fire for
+    // the same response on keep-alive connections. Guard with a one-shot flag
+    // so the counter and drain callbacks are only triggered once per request.
+    let decremented = false;
+    const decrement = () => {
+        if (decremented)
+            return;
+        decremented = true;
+        _activeRequests = Math.max(0, _activeRequests - 1);
+        if (_isShuttingDown && _activeRequests === 0) {
+            for (const cb of _drainCallbacks)
+                cb();
+            _drainCallbacks.length = 0;
+        }
+    };
+    res.on("finish", decrement);
+    res.on("close", decrement);
+}
+// ─── Main request handler ─────────────────────────────────────────────────────
+async function handleRequest(req, res, options) {
+    const { dev, paths, trustProxy = false } = options;
+    const timeoutMs = options.timeoutMs ?? _getServerTimeoutMs();
+    // Track active requests for graceful shutdown
+    trackRequest(res);
+    // Wire up connection-level error handling
+    req.on("error", (err) => {
+        if (err.code === "ECONNRESET" || err.code === "EPIPE") {
+            devWarn("client connection error:", err.code);
+            return;
+        }
+        devError("request error:", err.message);
+        try {
+            req.socket?.destroy();
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    res.on("error", (err) => {
+        if (err.code === "ECONNRESET" || err.code === "EPIPE") {
+            devWarn("response error:", err.code);
+            return;
+        }
+        devError("response write error:", err.message);
+    });
+    // Parse URL
+    let url;
+    try {
+        url = new URL(req.url ?? "/", "http://localhost");
+    }
+    catch {
+        send400(res, "Malformed URL", dev);
+        return;
+    }
+    const pathname = url.pathname;
+    const method = (req.method ?? "GET").toUpperCase();
+    // ── 1. Health checks ──────────────────────────────────────────────────────
+    if (method === "GET" && (pathname === "/health" || pathname === "/healthz")) {
+        sendJson(res, 200, { status: "ok", timestamp: new Date().toISOString() }, dev);
+        return;
+    }
+    // ── 2. SSE live-reload (dev only) ─────────────────────────────────────────
+    if (dev && method === "GET" && pathname === RELOAD_ENDPOINT) {
+        handleSseReload(req, res);
+        return;
+    }
+    // ── 2b. Dev runtime refresh after rebuild ────────────────────────────────
+    // The dev parent process rebuilds dist/ files, then calls this endpoint.
+    // We rescan compiled RPC/socket/main modules with cache-busting imports,
+    // update the reload generation, and browsers reload via SSE. No server
+    // process restart needed for normal source changes.
+    if (dev && method === "POST" && pathname === RUNTIME_RELOAD_ENDPOINT) {
+        try {
+            const rawKind = url.searchParams.get("kind");
+            const kind = rawKind === "css" || rawKind === "js" ? rawKind : "full";
+            await refreshDevRuntime(options, url.searchParams.get("generation"), kind, url.searchParams.get("path"));
+            res.writeHead(204);
+            res.end();
+        }
+        catch (err) {
+            devError("runtime refresh error:", err?.message ?? err);
+            send500(res, dev);
+        }
+        return;
+    }
+    // ── 3. Browser log forwarding (dev only) ──────────────────────────────────
+    if (dev && method === "POST" && pathname === BROWSER_LOG_ENDPOINT) {
+        let body = "";
+        req.setEncoding("utf8");
+        req.on("data", (chunk) => {
+            body += chunk;
+        });
+        req.on("end", () => {
+            try {
+                const parsed = JSON.parse(body);
+                const level = parsed.level ?? "log";
+                const msg = parsed.message ?? body;
+                if (level === "error") {
+                    devError("[browser]", msg);
+                }
+                else if (level === "warn") {
+                    devWarn("[browser]", msg);
+                }
+                else {
+                    devLog("[browser]", msg);
+                }
+            }
+            catch {
+                devLog("[browser]", body);
+            }
+            if (!res.headersSent) {
+                res.writeHead(204);
+                res.end();
+            }
+        });
+        return;
+    }
+    // ── 4. Dev no-bundle source/package/asset modules ────────────────────────
+    if (dev && options.noBundle && method === "GET") {
+        if (pathname.startsWith(`${INTERNAL_SRC_PREFIX}/`)) {
+            if (await serveDevSourceModule(pathname, res, options))
+                return;
+            send404(res, dev);
+            return;
+        }
+        if (pathname.startsWith(`${INTERNAL_PKG_PREFIX}/`)) {
+            if (await serveDevPackageModule(pathname, res, options))
+                return;
+            send404(res, dev);
+            return;
+        }
+        if (pathname.startsWith(`${INTERNAL_ASSET_PREFIX}/`)) {
+            if (serveDevAsset(pathname, req, res, options))
+                return;
+            send404(res, dev);
+            return;
+        }
+    }
+    // ── 5. Virtual /_mates/ files (browser-side RPC helpers, error classes, etc.)
+    // These are generated at build time by the esbuild RPC stub plugin and marked
+    // as external ("/_mates/*") so they are NOT bundled. The server must serve
+    // them as plain JS modules.
+    if (method === "GET" && pathname.startsWith(`${INTERNAL_MATES_PREFIX}/`)) {
+        try {
+            const { serveVirtualFile } = await import("./build-esbuild.js");
+            const content = await serveVirtualFile(pathname);
+            if (content !== null) {
+                const buf = Buffer.from(content, "utf-8");
+                if (!res.headersSent) {
+                    applySecurityHeaders(res, dev, false);
+                    res.writeHead(200, {
+                        "Content-Type": "application/javascript; charset=utf-8",
+                        "Content-Length": buf.length,
+                        "Cache-Control": "no-cache",
+                    });
+                    res.end(buf);
+                }
+                return;
+            }
+        }
+        catch {
+            // Fall through to 404 if virtual file module not available
+        }
+        send404(res, dev);
+        return;
+    }
+    // ── 6. WebSocket upgrades — let the server emit "upgrade" (handled externally)
+    // We do NOT handle them here — they are handled via server.on("upgrade", ...)
+    // by the caller. If we reach here it was not an upgrade request.
+    const c = createContext(req, trustProxy);
+    // Wrap the entire request dispatch in AsyncLocalStorage so that
+    // getSSRContext(), getSSRRequest(), isSSRContext(), etc. work correctly
+    // in middleware, RPC functions, and SSR render.
+    await runWithContext(c.req.raw, false, async () => {
+        setSSRContext(c);
+        // ── 7. onRequest middleware ───────────────────────────────────────────────
+        try {
+            const result = await runRequestHooks(c);
+            if (result.response) {
+                c.resStatus = result.response.status;
+                await runResponseHooks(c);
+                await sendFetchResponse(result.response, c, req, res, dev);
+                return;
+            }
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                // For page requests (GET /), onRequest auth errors should NOT return JSON.
+                // Clear auth and fall through to SSR so the client router handles redirects.
+                if (method === "GET" && !pathname.startsWith("/api/")) {
+                    c.auth = null;
+                }
+                else {
+                    const serialized = serializeError(err, dev);
+                    sendJson(res, serialized.status, serialized, dev);
+                    return;
+                }
+            }
+        }
+        // ── 8. REST routes ────────────────────────────────────────────────────────
+        try {
+            const restResponse = await matchAndRunRest(c);
+            if (restResponse) {
+                c.resStatus = restResponse.status;
+                await runResponseHooks(c);
+                await sendFetchResponse(restResponse, c, req, res, dev);
+                return;
+            }
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                const serialized = serializeError(err, dev);
+                sendJson(res, serialized.status, serialized, dev);
+            }
+            return;
+        }
+        // ── 8. API docs ───────────────────────────────────────────────────────────
+        if (method === "GET" && pathname === "/api/docs") {
+            if (!isApiDocsEnabled(dev)) {
+                send404(res, dev);
+                return;
+            }
+            if (!isApiDocsAuthorized(req, dev)) {
+                send401(res, "API docs authentication required", dev);
+                return;
+            }
+            const docsApiDir = options.sourceApiDir ?? paths.apiDir;
+            const sourceRoot = path.resolve(options.sourceRoot ?? options.projectRoot);
+            const sourceSharedTypesDir = path.join(sourceRoot, "shared", "types");
+            const docsSharedTypesDir = fs.existsSync(sourceSharedTypesDir)
+                ? sourceSharedTypesDir
+                : paths.sharedTypesDir;
+            handleApiDocs(res, dev, docsApiDir, docsSharedTypesDir, options.projectRoot);
+            return;
+        }
+        // ── 7 & 8. RPC /api/** ────────────────────────────────────────────────────
+        if (pathname.startsWith("/api/")) {
+            if (method !== "POST") {
+                send405(res, dev);
+                return;
+            }
+            const entry = lookupRpcFn(pathname);
+            if (!entry) {
+                send404(res, dev);
+                return;
+            }
+            applySecurityHeaders(res, dev, false);
+            try {
+                await runRpcRequest(req, res, entry, dev, timeoutMs, c);
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    const serialized = serializeError(err, dev);
+                    sendJson(res, serialized.status, serialized, dev);
+                }
+            }
+            return;
+        }
+        // ── 10. Static files ──────────────────────────────────────────────────────
+        const publicDir = paths.publicDir;
+        // /assets/** — always served from clientBundlePath's directory or dist/assets
+        if (pathname.startsWith("/assets/")) {
+            const assetsDir = options.clientBundlePath
+                ? path.dirname(options.clientBundlePath)
+                : path.join(options.projectRoot, "dist", "assets");
+            const assetFile = path.resolve(assetsDir, "." + pathname.replace(/^\/assets/, ""));
+            if (isPathInside(assetsDir, assetFile)) {
+                try {
+                    const stat = fs.statSync(assetFile);
+                    if (stat.isFile()) {
+                        serveStatic("/" + path.relative(assetsDir, assetFile).replace(/\\/g, "/"), assetsDir, req, res, dev);
+                        return;
+                    }
+                }
+                catch {
+                    /* fall through */
+                }
+            }
+            // Also try public/assets
+            if (publicDir) {
+                serveStatic(pathname, publicDir, req, res, dev);
+                return;
+            }
+            send404(res, dev);
+            return;
+        }
+        // public/ static assets
+        if (publicDir) {
+            const filePath = path.resolve(publicDir, "." + pathname);
+            if (isPathInside(publicDir, filePath)) {
+                try {
+                    const stat = fs.statSync(filePath);
+                    if (stat.isFile()) {
+                        serveStatic(pathname, publicDir, req, res, dev);
+                        return;
+                    }
+                }
+                catch {
+                    /* not a static file, fall through to SSR */
+                }
+            }
+        }
+        // ── 11. SSR — GET only ──────────────────────────────────────────────────────────
+        if (method === "GET" || method === "HEAD") {
+            const { appFile } = paths;
+            // SPA mode or no App.ts — return 404
+            if (!appFile) {
+                send404(res, dev);
+                return;
+            }
+            applySecurityHeaders(res, dev, true);
+            // Mark this as an SSR page request before rendering so middleware
+            // can check c.isSSR to conditionally skip or adjust behavior.
+            c.isSSR = true;
+            try {
+                const { renderApp } = await import("./renderer.js");
+                const requestPath = url.pathname + url.search;
+                const result = await renderApp(appFile, requestPath, dev, timeoutMs);
+                const { buildShell } = await import("./head.js");
+                const sourceRoot = options.sourceRoot ?? options.projectRoot;
+                const clientEntry = dev && options.noBundle && options.sourceClientEntry
+                    ? `${INTERNAL_SRC_PREFIX}/${path.relative(sourceRoot, options.sourceClientEntry).split(path.sep).join("/")}`
+                    : `/assets/${path.basename(options.clientBundlePath ?? "client.js")}`;
+                const cssFilename = getCurrentCssFilename(options);
+                const cssUrl = cssFilename ? `/assets/${cssFilename}` : null;
+                const fullHtml = buildShell({
+                    projectRoot: options.projectRoot,
+                    bodyHtml: result.html,
+                    clientEntry,
+                    cssUrl,
+                    ssrStyles: result.styles,
+                    dev,
+                    importMap: dev && options.noBundle
+                        ? buildDevImportMap(options.projectRoot)
+                        : null,
+                });
+                const buf = Buffer.from(fullHtml, "utf-8");
+                if (!res.headersSent) {
+                    res.writeHead(200, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Content-Length": buf.length,
+                        "Cache-Control": dev ? "no-store" : "no-cache",
+                    });
+                    if (method !== "HEAD")
+                        res.end(buf);
+                    else
+                        res.end();
+                }
+            }
+            catch (err) {
+                if (isRedirect(err)) {
+                    if (!res.headersSent) {
+                        res.writeHead(err.status, { Location: err.url });
+                        res.end();
+                    }
+                    return;
+                }
+                devError("SSR render error:", err);
+                if (!res.headersSent)
+                    send500(res, dev);
+            }
+            return;
+        }
+        // ── 12. Method not allowed for non-GET/HEAD ────────────────────────────────
+        send405(res, dev);
+    }); // end runWithContext
+}
+// ─── startServer ─────────────────────────────────────────────────────────────
+/**
+ * Create and start the Node.js HTTP server.
+ * Returns a cleanup/shutdown function.
+ */
+export async function startServer(options) {
+    // Older tests/internal callers may omit projectRoot; paths.projectRoot is the
+    // canonical fallback.
+    options.projectRoot = options.projectRoot ?? options.paths.projectRoot;
+    const { paths, dev } = options;
+    const timeoutMs = options.timeoutMs ?? _getServerTimeoutMs();
+    const port = paths.port;
+    // Reset module-level state (supports hot-reload in tests)
+    _activeRequests = 0;
+    _isShuttingDown = false;
+    _drainCallbacks.length = 0;
+    _sseClients.clear();
+    _sseGeneration =
+        process.env.MATES_RELOAD_GENERATION ?? Date.now().toString(36);
+    let stopSocketServer = null;
+    const server = http.createServer(async (req, res) => {
+        // Abort quickly during shutdown — send 503
+        if (_isShuttingDown) {
+            applySecurityHeaders(res, dev, false);
+            res.setHeader("Retry-After", "5");
+            sendJson(res, 503, { error: "Server is shutting down", status: 503 }, dev);
+            return;
+        }
+        try {
+            await handleRequest(req, res, options);
+        }
+        catch (err) {
+            // Absolute last resort — handleRequest itself threw unexpectedly.
+            // This should never happen but if it does, the server must not crash.
+            devError("Unhandled server error — this is a framework bug, please report it.", err?.message ?? err);
+            if (!res.headersSent) {
+                try {
+                    const body = JSON.stringify({
+                        __type: "AppError",
+                        message: dev
+                            ? `Server encountered an unknown error: ${err?.message ?? err}`
+                            : "Server encountered an unknown error.",
+                        status: 500,
+                        code: "UNKNOWN_ERROR",
+                    });
+                    res.writeHead(500, {
+                        "Content-Type": "application/json; charset=utf-8",
+                        "Content-Length": Buffer.byteLength(body),
+                    });
+                    res.end(body);
+                }
+                catch {
+                    // Socket may be gone — nothing more we can do
+                }
+            }
+        }
+    });
+    // Limit concurrent connections to prevent resource exhaustion
+    server.maxConnections = options.maxConnections ?? 1000;
+    // Apply module-level server config from options
+    configureServer(options);
+    // Expose upgrade event — WebSocket caller attaches its own handler
+    // We simply do nothing here; Node.js will emit "upgrade" on the server.
+    // If nobody handles it, Node.js destroys the socket (correct behavior).
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            fatalError(`Port ${port} is already in use.\n` +
+                `  Stop the existing process or change the PORT environment variable.`);
+            process.exit(1);
+        }
+        devError("server error:", err.message);
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(port, () => resolve());
+        server.once("error", reject);
+    });
+    if (paths.socketDir) {
+        try {
+            const { attachSocketServer } = await import("./socket-router.js");
+            stopSocketServer = await attachSocketServer({ server, dev });
+        }
+        catch (err) {
+            devWarn(`WebSocket server failed to attach: ${err?.message ?? err}`);
+        }
+    }
+    if (dev) {
+        startupLog(`dev server running at http://localhost:${port}`);
+        startupLog(`dev reload generation: ${_sseGeneration}`);
+    }
+    // ── Graceful shutdown ────────────────────────────────────────────────────
+    const shutdownTimeoutMs = timeoutMs * 2;
+    function shutdown() {
+        if (_isShuttingDown)
+            return;
+        _isShuttingDown = true;
+        stopSocketServer?.();
+        // Close all SSE connections
+        for (const client of _sseClients) {
+            try {
+                if (!client.writableEnded)
+                    client.end();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        _sseClients.clear();
+        // Stop accepting new connections
+        server.close();
+        if (_activeRequests === 0) {
+            // Nothing in flight — done immediately
+            _callShutdownRenderer();
+            return;
+        }
+        // Wait for in-flight requests to drain
+        const drainTimeout = setTimeout(() => {
+            devWarn(`shutdown timeout — ${_activeRequests} request(s) still active`);
+            _callShutdownRenderer();
+        }, shutdownTimeoutMs);
+        _drainCallbacks.push(() => {
+            clearTimeout(drainTimeout);
+            _callShutdownRenderer();
+        });
+    }
+    return shutdown;
+}
+function _callShutdownRenderer() {
+    // If the renderer exposes a shutdown hook, call it
+    try {
+        // Dynamic require to avoid a hard dep at module level
+        const renderer = require("./renderer.js");
+        if (typeof renderer.shutdownRenderer === "function") {
+            renderer.shutdownRenderer();
+        }
+    }
+    catch {
+        // renderer not available — no-op
+    }
+}
+//# sourceMappingURL=server.js.map