threadforge 0.1.1 → 0.2.2

package/dist/core/ForgeContext.js

@@ -0,0 +1,1169 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import net from "node:net";
+import tls from "node:tls";
+import { StaticMountRegistry } from "../frontend/StaticMountRegistry.js";
+import { ForgeEndpoints, verifyJwt } from "./ForgeEndpoints.js";
+import { ForgeWebSocket } from "./ForgeWebSocket.js";
+import { IngressProtection } from "./Ingress.js";
+import { Logger } from "./Logger.js";
+// A10: Network utilities extracted to network-utils.js
+import { isPrivateNetwork, isTrustedProxy } from "./network-utils.js";
+import { PrometheusMetrics } from "./Prometheus.js";
+import { RequestContext } from "./RequestContext.js";
+import { Router } from "./Router.js";
+import { StaticFileServer } from "./StaticFileServer.js";
+import { WorkerChannelManager } from "./WorkerChannelManager.js";
+import { RegistryMode, ServiceType, } from "./config-enums.js";
+// Re-export for backward compatibility (A10)
+export { isPrivateNetwork, isTrustedProxy };
+const MAX_BODY_SIZE = 1_048_576; // 1MB
+const VALID_METHODS = new Set(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
+// S11: Body timeout reduced from 30s to 10s
+const BODY_TIMEOUT_MS = 10_000;
+export const NOT_HANDLED = Symbol("NOT_HANDLED");
+// Error messages for fatal bind errors
+const BIND_ERROR_MESSAGES = {
+    EPERM: (port) => `Permission denied binding to port ${port}. Run with elevated privileges or use a port >= 1024.`,
+    EACCES: (port) => `Access denied binding to port ${port}. Run with elevated privileges or use a port >= 1024.`,
+    EADDRNOTAVAIL: (port) => `Cannot bind to port ${port}. Address not available (restricted environment or invalid configuration).`,
+    EADDRINUSE: (port) => `Port ${port} is already in use. Stop the conflicting process or choose a different port.`,
+};
+/**
+ * ForgeContext
+ *
+ * Injected into every Service instance. Provides:
+ *  - HTTP router
+ *  - IPC messaging helpers (direct worker-to-worker when available)
+ *  - Metrics collection
+ *  - Structured logger
+ *  - Runtime metadata (service name, thread count, worker id, etc.)
+ */
+export class ForgeContext {
+    serviceName;
+    port;
+    workerId;
+    threadCount;
+    mode;
+    serviceType;
+    router;
+    logger;
+    metrics;
+    channels;
+    ingress;
+    _sendIPC;
+    _localSend;
+    _localRequest;
+    _ingressConfig;
+    _ingressApplied;
+    _forgeProxy;
+    _serviceInstance;
+    _servicePorts;
+    _endpointResolver;
+    _staticMounts;
+    _staticRegistry;
+    _staticFileServer;
+    _forgeEndpoints;
+    _wsConnections;
+    _wsPerIpCounts;
+    _wsMaxPerIp;
+    _wsPerIpCleanupTimer;
+    _wsHandlers;
+    _wsPluginHooks;
+    _server;
+    _needsHttpServer;
+    _activeRequests;
+    _messageHandlers;
+    _onMessage;
+    _onRequest;
+    _projectId;
+    _projectSchema;
+    _projectKeyPrefix;
+    _emitEvent;
+    constructor(options) {
+        this.serviceName = options.serviceName;
+        this.port = options.port;
+        this.workerId = options.workerId;
+        this.threadCount = options.threadCount;
+        this.mode = options.mode;
+        this.serviceType = options.serviceType ?? ServiceType.INTERNAL;
+        this._sendIPC = options.sendIPC;
+        this._localSend = options.localSend ?? null;
+        this._localRequest = options.localRequest ?? null;
+        this._ingressConfig = options.ingress ?? {};
+        this._ingressApplied = false;
+        this._forgeProxy = options.forgeProxy ?? process.env.FORGE_PROXY_URL ?? null;
+        this._serviceInstance = null; // set by worker-bootstrap after service.onStart
+        // Port map for HTTP-based service calls: { serviceName: port }
+        try {
+            this._servicePorts = JSON.parse(process.env.FORGE_SERVICE_PORTS || "{}");
+        }
+        catch {
+            this._servicePorts = {};
+        }
+        this._endpointResolver = null;
+        this.router = new Router();
+        this.logger = new Logger(this.serviceName, this.workerId);
+        this.metrics = new PrometheusMetrics(this.serviceName, this.workerId);
+        this._staticMounts = options.staticMounts ?? [];
+        this._staticRegistry = new StaticMountRegistry(this._staticMounts);
+        this._staticFileServer = new StaticFileServer({
+            staticRegistry: this._staticRegistry,
+            logger: this.logger,
+            metrics: this.metrics,
+        });
+        this._forgeEndpoints = new ForgeEndpoints({
+            serviceName: this.serviceName,
+            logger: this.logger,
+            getServiceInstance: () => this._serviceInstance,
+        });
+        this._wsConnections = new Set();
+        this._wsPerIpCounts = new Map();
+        this._wsMaxPerIp = parseInt(process.env.FORGE_WS_MAX_PER_IP || "100", 10) || 100;
+        this._wsPerIpCleanupTimer = setInterval(() => {
+            if (this._wsPerIpCounts.size > 50_000) {
+                // Nuclear option: map exceeded 50K entries — clear entirely
+                this._wsPerIpCounts.clear();
+                return;
+            }
+            for (const [ip, count] of this._wsPerIpCounts) {
+                if (count <= 0)
+                    this._wsPerIpCounts.delete(ip);
+            }
+        }, 60_000);
+        this._wsPerIpCleanupTimer.unref();
+        this._wsHandlers = new Map();
+        this._wsPluginHooks = [];
+        /**
+         * Direct channel manager — handles MessagePort connections
+         * to other services, bypassing the supervisor for all
+         * inter-service communication.
+         */
+        this.channels = new WorkerChannelManager(this.serviceName, this.workerId);
+        this.channels.init(this._sendIPC);
+        this._server = null;
+        // Compute once whether this service needs an HTTP server
+        const isEdge = this.serviceType === ServiceType.EDGE && this.port > 0;
+        const isMultiMachine = process.env.FORGE_REGISTRY_MODE && process.env.FORGE_REGISTRY_MODE !== RegistryMode.EMBEDDED;
+        let hasRemoteEndpoints = false;
+        try {
+            const eps = JSON.parse(process.env.FORGE_SERVICE_ENDPOINTS || "{}");
+            hasRemoteEndpoints = Object.values(eps).some((ep) => Array.isArray(ep) ? ep.some((e) => e.remote) : ep?.remote);
+        }
+        catch { }
+        this._needsHttpServer = isEdge || ((isMultiMachine || hasRemoteEndpoints) && this.port > 0);
+        this._activeRequests = 0;
+        this._messageHandlers = new Map();
+    }
+    setStaticMounts(mounts = []) {
+        this._staticMounts = mounts;
+        this._staticRegistry.setMounts(mounts);
+    }
+    /**
+     * Send a message to another service.
+     *
+     * Resolution order:
+     *   1. Local dispatch (colocated service in same process) — zero overhead
+     *   2. Direct UDS connection — bypasses supervisor
+     *   3. Supervisor IPC fallback — only during startup
+     */
+    async send(target, payload) {
+        // Try colocated first (direct function call, no serialization)
+        if (this._localSend?.(target, payload)) {
+            return;
+        }
+        // Fall through to UDS / supervisor IPC
+        this.channels.send(target, payload);
+    }
+    /**
+     * Broadcast to all workers of a target service.
+     * Note: channels.broadcast delivers to all workers including local via UDS.
+     * We only use _localSend for colocated services that share this process
+     * (no UDS needed), then broadcast to remote workers via channels.
+     */
+    async broadcast(target, payload) {
+        // Local colocated dispatch (same process, direct call)
+        this._localSend?.(target, payload);
+        // UDS broadcast to all OTHER workers (channels excludes self)
+        this.channels.broadcast(target, payload);
+    }
+    /**
+     * Send a request to another service and await a response.
+     *
+     * If the target is colocated, this is a direct async function call
+     * with zero serialization overhead.
+     */
+    async request(target, payload, timeoutMs = 5000) {
+        // Try colocated first
+        if (this._localRequest) {
+            const result = await this._localRequest(target, payload);
+            if (result !== NOT_HANDLED)
+                return result;
+        }
+        // Fall through to UDS / supervisor IPC
+        return this.channels.request(target, payload, timeoutMs);
+    }
+    /**
+     * Start the HTTP server for this service.
+     */
+    async startServer() {
+        // Auto-apply ingress protection for edge services (when no ForgeProxy)
+        if (this.serviceType === ServiceType.EDGE && !this._ingressApplied && !this._forgeProxy) {
+            this.ingress = new IngressProtection(this._ingressConfig ?? {});
+            this.router.use(this.ingress.middleware());
+            this._ingressApplied = true;
+        }
+        // ── S7: Prometheus metrics endpoint with optional auth ──
+        this.router.get("/metrics", (_req, res) => {
+            const metricsToken = process.env.FORGE_METRICS_TOKEN;
+            if (metricsToken) {
+                const auth = _req.headers.authorization;
+                const expected = `Bearer ${metricsToken}`;
+                if (!auth || auth.length !== expected.length || !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
+                    res.json({ error: "Unauthorized" }, 401);
+                    return;
+                }
+            }
+            res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+            res.end(this.metrics.expose());
+        });
+        // ── Internal forge endpoints (/__forge/*) ──
+        this._forgeEndpoints.registerRoutes(this.router);
+        return new Promise((resolve, reject) => {
+            this._server = createServer((req, res) => {
+                const start = performance.now();
+                const forgeReq = req;
+                const forgeRes = res;
+                // H8: Validate HTTP method early
+                if (!VALID_METHODS.has(req.method)) {
+                    res.writeHead(405, {
+                        "Content-Type": "application/json",
+                        Allow: "GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS",
+                    });
+                    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+                    return;
+                }
+                // H11: Strip internal forge headers from external requests BEFORE body parsing
+                // L-SEC-1: Also strip internal signature/timestamp headers for defense-in-depth
+                const remoteAddrEarly = req.socket?.remoteAddress ?? "";
+                if (!isPrivateNetwork(remoteAddrEarly)) {
+                    delete req.headers["x-forge-auth"];
+                    delete req.headers["x-forge-tenant"];
+                    delete req.headers["x-forge-user"];
+                    delete req.headers["x-forge-deadline"];
+                    delete req.headers["x-forge-internal-sig"];
+                    delete req.headers["x-forge-internal-ts"];
+                }
+                if (["POST", "PUT", "PATCH"].includes(req.method)) {
+                    const ct = (req.headers["content-type"] ?? "").toLowerCase();
+                    if (ct &&
+                        !ct.includes("application/json") &&
+                        !ct.includes("text/") &&
+                        !ct.includes("multipart/form-data") &&
+                        !ct.includes("application/x-www-form-urlencoded")) {
+                        res.writeHead(415, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Unsupported media type" }));
+                        return;
+                    }
+                    // Early Content-Length check — reject oversized requests without reading body
+                    const declaredLength = req.headers["content-length"];
+                    if (declaredLength != null) {
+                        const cl = parseInt(declaredLength, 10);
+                        if (!Number.isNaN(cl) && cl > MAX_BODY_SIZE) {
+                            res.writeHead(413, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({ error: "Request body too large" }));
+                            req.destroy();
+                            return;
+                        }
+                    }
+                    // P7: Collect chunks in array, single Buffer.concat at end
+                    const chunks = [];
+                    let bodySize = 0;
+                    let rejected = false;
+                    // S11: Reduced body timeout from 30s to 10s
+                    const bodyTimeout = setTimeout(() => {
+                        if (rejected)
+                            return;
+                        rejected = true;
+                        if (!res.headersSent) {
+                            res.writeHead(408, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({ error: "Request Timeout" }));
+                        }
+                        req.destroy();
+                    }, BODY_TIMEOUT_MS);
+                    req.on("data", (chunk) => {
+                        if (rejected)
+                            return;
+                        bodySize += chunk.length;
+                        if (bodySize > MAX_BODY_SIZE) {
+                            rejected = true;
+                            clearTimeout(bodyTimeout);
+                            if (!res.headersSent) {
+                                res.writeHead(413, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({ error: "Request body too large" }));
+                            }
+                            req.destroy();
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    req.on("end", () => {
+                        clearTimeout(bodyTimeout);
+                        if (rejected)
+                            return;
+                        const body = Buffer.concat(chunks).toString("utf-8");
+                        // Only JSON.parse when content-type is application/json or absent (backward compat)
+                        if (!ct || ct.includes("application/json")) {
+                            try {
+                                forgeReq.body = body
+                                    ? JSON.parse(body, (key, value) => {
+                                        if (key === "__proto__" || key === "constructor" || key === "prototype")
+                                            return undefined;
+                                        return value;
+                                    })
+                                    : {};
+                            }
+                            catch {
+                                // For internal forge endpoints, return 400 on malformed JSON
+                                const urlPath = new URL(req.url, "http://localhost").pathname;
+                                if (urlPath.startsWith("/__forge/")) {
+                                    if (!res.headersSent) {
+                                        res.writeHead(400, { "Content-Type": "application/json" });
+                                        res.end(JSON.stringify({ error: "Invalid JSON body" }));
+                                    }
+                                    return;
+                                }
+                                // Fall back to raw string for user routes
+                                forgeReq.body = body;
+                            }
+                        }
+                        else {
+                            forgeReq.body = body;
+                        }
+                        this._handleRequest(forgeReq, forgeRes, start);
+                    });
+                }
+                else {
+                    forgeReq.body = {};
+                    this._handleRequest(forgeReq, forgeRes, start);
+                }
+            });
+            // ── Client error handling ──
+            this._server.on("clientError", (err, socket) => {
+                this.logger.error("Client error", { error: err.message, code: err.code });
+                if (socket && !socket.destroyed) {
+                    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+                    socket.destroy();
+                }
+            });
+            // ── WebSocket upgrade handling ──
+            this._server.on("upgrade", (req, socket, head) => {
+                this._handleWsUpgrade(req, socket, head).catch((err) => {
+                    this.logger.error("WebSocket upgrade failed", { error: err.message, path: req.url });
+                    if (!socket.destroyed) {
+                        try {
+                            socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+                        }
+                        catch { }
+                        socket.destroy();
+                    }
+                });
+            });
+            // Set request timeouts to prevent slowloris attacks
+            this._server.timeout = 30000;
+            this._server.requestTimeout = 30000;
+            this._server.headersTimeout = 10000;
+            this._server.listen(this.port, () => {
+                // Reduce startup noise in multi-worker mode.
+                if (this.workerId === 0) {
+                    this.logger.info(`Listening on port ${this.port}`);
+                }
+                // Auto-register with ForgeProxy if configured
+                if (this._forgeProxy) {
+                    this._registerWithForgeProxy().catch((err) => {
+                        this.logger.warn(`ForgeProxy registration failed: ${err.message}`);
+                    });
+                }
+                resolve();
+            });
+            this._server.on("error", (err) => {
+                // Detect fatal bind errors that should not trigger restart loops
+                const isFatalBindError = err.code === "EPERM" || err.code === "EACCES" || err.code === "EADDRNOTAVAIL" || err.code === "EADDRINUSE";
+                if (isFatalBindError) {
+                    // Notify supervisor this is a fatal error — don't restart
+                    if (this._sendIPC) {
+                        this._sendIPC({
+                            type: "forge:fatal-error",
+                            error: err.code,
+                            message: err.message,
+                            port: this.port,
+                        });
+                    }
+                    // Augment error with clear message using constant map
+                    const messageGenerator = BIND_ERROR_MESSAGES[err.code];
+                    err.fatalBindError = true;
+                    err.userMessage = messageGenerator
+                        ? messageGenerator(this.port)
+                        : `Failed to bind to port ${this.port}: ${err.message}`;
+                }
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Route an incoming HTTP request.
+     * Creates a RequestContext that flows through the entire call chain.
+     */
+    _handleRequest(req, res, start) {
+        this._activeRequests++;
+        res._forgeTracked = true;
+        res.once("close", () => {
+            if (res._forgeTracked) {
+                this._activeRequests--;
+                res._forgeTracked = false;
+            }
+        });
+        // Convenience methods on response
+        res.json = (data, statusCode = 200) => {
+            if (res.headersSent)
+                return;
+            let body;
+            try {
+                body = JSON.stringify(data ?? null);
+            }
+            catch {
+                body = JSON.stringify({ error: "Response serialization failed" });
+                statusCode = 500;
+            }
+            const len = Buffer.byteLength(body);
+            res.writeHead(statusCode, { "Content-Type": "application/json", "Content-Length": len });
+            res.end(body);
+        };
+        res.status = (code) => {
+            res.statusCode = code;
+            return res;
+        };
+        // HTTP-M5: Streaming response support — sets Transfer-Encoding: chunked
+        // Handlers can call res.stream() then use res.write() / res.end() for large payloads.
+        res.stream = (statusCode = 200, headers = {}) => {
+            if (!res.headersSent) {
+                res.writeHead(statusCode, {
+                    "Transfer-Encoding": "chunked",
+                    ...headers,
+                });
+            }
+            return res;
+        };
+        // ── Build RequestContext from incoming headers ──
+        // Note: internal forge headers already stripped in createServer callback (H11)
+        const remoteAddr = req.socket?.remoteAddress ?? "";
+        const rctx = RequestContext.fromPropagation(req.headers);
+        rctx.service = this.serviceName;
+        // Security headers
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+        // HSTS should only be sent over HTTPS (RFC 6797 § 7.2)
+        // Only trust x-forwarded-proto from trusted proxies (FORGE_TRUSTED_PROXIES), not just any private network
+        if (req.socket?.encrypted ||
+            (isTrustedProxy(remoteAddr) && req.headers["x-forwarded-proto"] === "https")) {
+            res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+        }
+        // Always set the correlation ID response header
+        res.setHeader("x-correlation-id", rctx.correlationId);
+        res.setHeader("x-trace-id", rctx.traceId);
+        // In host mode, propagate project ID to the request context
+        rctx._projectId ??= this._projectId;
+        // Attach context to request for handlers to use
+        req.ctx = rctx;
+        req.auth = rctx.auth;
+        req.tenantId = rctx.tenantId;
+        req.projectId = rctx.projectId;
+        req.userId = rctx.userId;
+        req.correlationId = rctx.correlationId;
+        this.metrics.httpRequestStart();
+        const matched = this.router.match(req.method, req.url);
+        if (!matched) {
+            this._staticFileServer
+                .tryServeStatic(req, res, start)
+                .then((served) => {
+                if (served)
+                    return;
+                this.metrics.httpRequestEnd((performance.now() - start) / 1000, {
+                    method: req.method,
+                    route: "unmatched",
+                    status: 404,
+                });
+                res.json({ error: "Not Found" }, 404);
+            })
+                .catch((err) => {
+                this.logger.error("Static serve failure", {
+                    error: err.message,
+                    url: req.url,
+                });
+                if (!res.headersSent) {
+                    res.json({ error: "Internal server error" }, 500);
+                }
+            });
+            return;
+        }
+        req.params = matched.params;
+        req.query = matched.query;
+        // HEAD responses MUST NOT include a message body (RFC 7231 § 4.3.2)
+        if (req.method === "HEAD") {
+            let headContentLength = 0;
+            const origEnd = res.end.bind(res);
+            res.end = (_chunk, encoding, callback) => {
+                // Account for any final chunk passed to end()
+                if (_chunk != null) {
+                    headContentLength += Buffer.byteLength(_chunk, typeof encoding === "string" ? encoding : undefined);
+                }
+                if (!res.headersSent && headContentLength > 0 && !res.getHeader("content-length")) {
+                    res.setHeader("Content-Length", headContentLength);
+                }
+                return origEnd(null, encoding, callback);
+            };
+            res.write = (chunk, encodingOrCb, cb) => {
+                if (chunk != null) {
+                    headContentLength += Buffer.byteLength(chunk, typeof encodingOrCb === "string" ? encodingOrCb : undefined);
+                }
+                if (typeof encodingOrCb === "function")
+                    encodingOrCb(null);
+                else if (typeof cb === "function")
+                    cb(null);
+                return true;
+            };
+        }
+        // Execute middleware chain + handler INSIDE RequestContext
+        const handlers = [...this.router.middleware, matched.handler];
+        let i = 0;
+        const next = (err) => {
+            if (err) {
+                this.logger.error("Request error", {
+                    error: err.message,
+                    url: req.url,
+                    ...rctx.toLogFields(),
+                });
+                if (!res.headersSent) {
+                    const status = err.statusCode || 500;
+                    const message = status >= 500 ? "Internal server error" : err.message || "Internal error";
+                    res.json({ error: message }, status);
+                }
+                return;
+            }
+            const handler = handlers[i++];
+            if (!handler)
+                return;
+            let stepCalled = false;
+            const stepNext = (stepErr) => {
+                if (stepCalled) {
+                    if (process.env.NODE_ENV !== "production") {
+                        process.stderr.write(`${JSON.stringify({
+                            timestamp: new Date().toISOString(),
+                            level: "warn",
+                            message: `Middleware called next() more than once (handler index ${i - 1}). This is likely a bug.`,
+                        })}\n`);
+                    }
+                    return;
+                }
+                stepCalled = true;
+                next(stepErr);
+            };
+            try {
+                const result = handler(req, res, stepNext);
+                if (result && typeof result.catch === "function") {
+                    result.catch(stepNext);
+                }
+            }
+            catch (e) {
+                stepNext(e);
+            }
+        };
+        // Run entire handler chain within the RequestContext.
+        // AsyncLocalStorage.run() properly propagates through the entire async chain,
+        // including middleware that does `await next()` followed by post-next work.
+        RequestContext.run(rctx, () => next());
+        // Track metrics on response finish
+        const onFinish = () => {
+            const duration = (performance.now() - start) / 1000;
+            const labels = {
+                method: req.method,
+                route_pattern: matched.pattern,
+                status: res.statusCode,
+            };
+            this.metrics.httpRequestEnd(duration, labels);
+            res.removeListener("finish", onFinish);
+        };
+        res.on("finish", onFinish);
+    }
+    /**
+     * Wire message/request handlers to both the direct channel manager
+     * AND the supervisor fallback IPC path.
+     */
+    _wireMessageHandlers() {
+        // Direct channel path (primary — used once ports are established)
+        this.channels.onMessage = (from, payload) => {
+            if (this._onMessage)
+                this._onMessage(from, payload);
+        };
+        this.channels.onRequest = (from, payload) => {
+            if (this._onRequest)
+                return this._onRequest(from, payload);
+            return null;
+        };
+    }
+    /**
+     * Handle an incoming IPC message from the supervisor.
+     * This is the FALLBACK path — only used during startup before
+     * direct MessagePorts are established, and for supervisor-level
+     * commands (health checks, shutdown, etc.)
+     */
+    _handleIPCMessage(msg) {
+        if (!msg || !msg.type)
+            return;
+        // Supervisor-level messages
+        if (msg.type === "forge:health-check") {
+            this._sendIPC({
+                type: "forge:health-response",
+                timestamp: msg.timestamp,
+                uptime: process.uptime(),
+                memory: process.memoryUsage(),
+                pid: process.pid,
+            });
+            return;
+        }
+        // Fallback message routing (before direct ports are ready)
+        if (msg.type === "forge:message" && this._onMessage) {
+            this._onMessage(msg.from, msg.payload);
+        }
+        if (msg.type === "forge:request" && this._onRequest) {
+            Promise.resolve(this._onRequest(msg.from, msg.payload))
+                .then((result) => {
+                this._sendIPC({
+                    type: "forge:response",
+                    requestId: msg.requestId,
+                    payload: result,
+                    error: null,
+                });
+            })
+                .catch((err) => {
+                this._sendIPC({
+                    type: "forge:response",
+                    requestId: msg.requestId,
+                    payload: null,
+                    error: err.message,
+                });
+            });
+        }
+        if (msg.type === "forge:response") {
+            const handler = this._messageHandlers.get(msg.requestId);
+            if (handler)
+                handler(msg);
+        }
+    }
+    _isMethodAllowed(method) {
+        return this._forgeEndpoints.isMethodAllowed(method);
+    }
+    async _executeForgeEndpoint(res, rctx, handler, method, { args, logPrefix }) {
+        return this._forgeEndpoints.execute(res, rctx, handler, method, { args, logPrefix });
+    }
+    /**
+     * Gracefully shut down.
+     */
+    async stop() {
+        // M-13: Stop IngressProtection timers if active
+        if (this.ingress) {
+            this.ingress.stop();
+        }
+        // Close direct channels
+        this.channels.destroy();
+        // Close all active WebSocket connections and clean up timers
+        for (const ws of this._wsConnections) {
+            if (ws._closeTimer) {
+                clearTimeout(ws._closeTimer);
+                ws._closeTimer = null;
+            }
+            if (ws._pingTimer) {
+                clearInterval(ws._pingTimer);
+                ws._pingTimer = null;
+            }
+            if (!ws._closed) {
+                ws._closed = true;
+            }
+            if (!ws.socket.destroyed) {
+                ws.socket.destroy();
+            }
+        }
+        this._wsConnections.clear();
+        if (this._server) {
+            // Deregister from ForgeProxy on shutdown
+            if (this._forgeProxy) {
+                try {
+                    const data = JSON.stringify({
+                        service: this.serviceName,
+                        host: this._getHost(),
+                        port: this.port,
+                    });
+                    const url = new URL(`${this._forgeProxy}/deregister`);
+                    await fetch(url, { method: "POST", body: data, headers: { "Content-Type": "application/json" } }).catch(() => { });
+                }
+                catch { }
+            }
+            return new Promise((resolve) => {
+                let drainInterval = null;
+                // Stop accepting new connections and terminate idle keep-alive sockets
+                this._server.close(() => {
+                    if (drainInterval)
+                        clearInterval(drainInterval);
+                    resolve();
+                });
+                // Force-close idle keep-alive connections (Node 18.2+)
+                if (typeof this._server.closeAllConnections === "function") {
+                    // Wait briefly for in-flight requests, then force-close
+                    const drainStart = Date.now();
+                    drainInterval = setInterval(() => {
+                        if (this._activeRequests <= 0 || Date.now() - drainStart >= 5000) {
+                            clearInterval(drainInterval);
+                            drainInterval = null;
+                            this._server.closeAllConnections();
+                        }
+                    }, 50);
+                    drainInterval.unref();
+                }
+            });
+        }
+    }
+    // ── WebSocket Support ──
+    /**
+     * Register a WebSocket handler for a path.
+     *
+     *   ctx.ws('/ws', (socket, req) => {
+     *     socket.on('message', (data) => {
+     *       const msg = JSON.parse(data);
+     *       // req.ctx has the RequestContext with auth, correlationId
+     *       socket.send(JSON.stringify({ echo: msg }));
+     *     });
+     *   });
+     */
+    ws(path, handlerOrOptions, maybeHandler) {
+        let handler;
+        let options;
+        if (typeof handlerOrOptions === "function") {
+            handler = handlerOrOptions;
+            options = {};
+        }
+        else {
+            options = handlerOrOptions ?? {};
+            handler = maybeHandler;
+        }
+        // S8: WebSocket endpoints require auth by default
+        if (options.auth === undefined) {
+            options.auth = "required";
+        }
+        this._wsHandlers.set(path, { handler, options });
+    }
+    /**
+     * Write a short HTTP response over a raw upgrade socket and close it.
+     */
+    _writeWsUpgradeError(socket, statusCode, reason, headers = {}) {
+        const statusText = String(reason || "Upgrade Rejected").replace(/[\r\n]/g, " ");
+        let response = `HTTP/1.1 ${statusCode} ${statusText}\r\n`;
+        for (const [key, value] of Object.entries(headers)) {
+            const safeKey = String(key).replace(/[\r\n:]/g, "");
+            const safeVal = String(value).replace(/[\r\n]/g, " ");
+            response += `${safeKey}: ${safeVal}\r\n`;
+        }
+        response += "\r\n";
+        socket.write(response);
+        socket.destroy();
+    }
+    /**
+     * Run websocket plugin hooks for a lifecycle stage.
+     */
+    async _runWsPluginHooks(stage, payload) {
+        const methodByStage = {
+            upgrade: "onWsUpgrade",
+            connect: "onWsConnect",
+            message: "onWsMessage",
+            close: "onWsClose",
+        };
+        const method = methodByStage[stage];
+        if (!method)
+            return [];
+        const results = [];
+        for (const hook of this._wsPluginHooks) {
+            const fn = hook?.[method];
+            if (typeof fn !== "function")
+                continue;
+            try {
+                const result = await fn(payload);
+                results.push({ plugin: hook.name, ok: true, result });
+            }
+            catch (err) {
+                this.logger.warn(`WebSocket plugin hook failed`, {
+                    plugin: hook.name,
+                    stage,
+                    error: err.message,
+                });
+                results.push({ plugin: hook.name, ok: false, error: err });
+            }
+        }
+        return results;
+    }
+    /**
+     * Handle HTTP→WebSocket upgrade.
+     * Implements RFC 6455 handshake without external dependencies.
+     */
+    async _handleWsUpgrade(req, socket, head) {
+        // H-SEC-2: Per-IP WebSocket connection limit to prevent file descriptor exhaustion
+        // HTTP-M4: Use X-Forwarded-For from trusted proxies for accurate per-IP tracking
+        let wsRemoteAddr = req.socket?.remoteAddress ?? "unknown";
+        const rawAddr = req.socket?.remoteAddress;
+        if (rawAddr && (process.env.FORGE_TRUSTED_PROXIES ? isTrustedProxy(rawAddr) : isPrivateNetwork(rawAddr))) {
+            const xff = req.headers["x-forwarded-for"];
+            if (xff) {
+                const clientIp = (Array.isArray(xff) ? xff[0] : xff).split(",")[0]?.trim();
+                if (clientIp)
+                    wsRemoteAddr = clientIp;
+            }
+        }
+        const currentCount = this._wsPerIpCounts.get(wsRemoteAddr) ?? 0;
+        if (currentCount >= this._wsMaxPerIp) {
+            socket.write("HTTP/1.1 429 Too Many Requests\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
+        const entry = this._wsHandlers.get(url.pathname);
+        if (!entry) {
+            const proxied = await this._proxyWsUpgradeToDevServer(req, socket, head, url);
+            if (proxied)
+                return;
+            socket.destroy();
+            return;
+        }
+        const handler = typeof entry === "function" ? entry : entry.handler;
+        const wsOptions = typeof entry === "function" ? {} : (entry.options ?? {});
+        // S3: WebSocket Origin Validation — default deny
+        const allowedOrigins = wsOptions.allowedOrigins;
+        if (allowedOrigins && allowedOrigins.length > 0) {
+            // Explicit allowlist: check if '*' is included (opt-out of security)
+            if (!allowedOrigins.includes("*")) {
+                const origin = req.headers.origin;
+                if (!origin || !allowedOrigins.includes(origin)) {
+                    socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+                    socket.destroy();
+                    return;
+                }
+            }
+        }
+        else {
+            // No allowedOrigins configured — default deny (reject cross-origin)
+            const origin = req.headers.origin;
+            if (origin) {
+                // Compare origin host to request host
+                try {
+                    const originHost = new URL(origin).host;
+                    const reqHost = req.headers.host?.split(":")[0];
+                    if (originHost !== reqHost && originHost !== req.headers.host) {
+                        socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+                        socket.destroy();
+                        return;
+                    }
+                }
+                catch {
+                    socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+                    socket.destroy();
+                    return;
+                }
+            }
+        }
+        // Strip internal forge headers from external WebSocket upgrades
+        let headers = req.headers;
+        const remoteAddr = req.socket?.remoteAddress ?? "";
+        if (!isPrivateNetwork(remoteAddr)) {
+            headers = { ...req.headers };
+            delete headers["x-forge-auth"];
+            delete headers["x-forge-tenant"];
+            delete headers["x-forge-user"];
+            delete headers["x-forge-deadline"];
+        }
+        const rctx = RequestContext.fromPropagation(headers);
+        rctx.service = this.serviceName;
+        rctx.method = `ws:${url.pathname}`;
+        req.ctx = rctx;
+        req.auth = rctx.auth;
+        req.tenantId = rctx.tenantId;
+        // S8: Enforce auth by default (auth defaults to 'required' from ws() method)
+        if (wsOptions.auth === "required") {
+            if (!rctx.auth) {
+                socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            // M-3 Security: When JWT_SECRET is set, verify the JWT signature — not just auth presence
+            if (process.env.JWT_SECRET) {
+                const rawToken = headers["x-forge-auth"] ??
+                    headers.authorization ??
+                    url.searchParams.get("token");
+                const verified = rawToken ? verifyJwt(rawToken) : null;
+                if (!verified) {
+                    socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                    socket.destroy();
+                    return;
+                }
+            }
+        }
+        const wsMeta = {
+            service: this.serviceName,
+            workerId: this.workerId,
+            path: url.pathname,
+            options: wsOptions,
+            requestContext: rctx,
+        };
+        const upgradeResults = await this._runWsPluginHooks("upgrade", {
+            req,
+            socket,
+            meta: wsMeta,
+        });
+        for (const res of upgradeResults) {
+            if (!res.ok) {
+                this._writeWsUpgradeError(socket, 503, "Service Unavailable");
+                return;
+            }
+            const decision = res.result;
+            if (decision === false || (decision && decision.allow === false)) {
+                this._writeWsUpgradeError(socket, decision && typeof decision === "object" ? (decision.statusCode ?? 403) : 403, decision && typeof decision === "object" ? (decision.reason ?? "Forbidden") : "Forbidden", decision && typeof decision === "object" ? (decision.headers ?? {}) : {});
+                return;
+            }
+        }
+        // M6: Validate Sec-WebSocket-Version (must be 13 per RFC 6455)
+        if (req.headers["sec-websocket-version"] !== "13") {
+            socket.write("HTTP/1.1 426 Upgrade Required\r\nSec-WebSocket-Version: 13\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        // RFC 6455 handshake
+        const key = req.headers["sec-websocket-key"];
+        if (!key) {
+            socket.destroy();
+            return;
+        }
+        const accept = createHash("sha1").update(`${key}258EAFA5-E914-47DA-95CA-5AB4085B9976`).digest("base64");
+        const safeCorrelationId = (rctx.correlationId || "").replace(/[\r\n]/g, "");
+        socket.write("HTTP/1.1 101 Switching Protocols\r\n" +
+            "Upgrade: websocket\r\n" +
+            "Connection: Upgrade\r\n" +
+            `Sec-WebSocket-Accept: ${accept}\r\n` +
+            `X-Correlation-ID: ${safeCorrelationId}\r\n` +
+            "\r\n");
+        // Create a minimal WebSocket wrapper
+        const ws = new ForgeWebSocket(socket, rctx, wsOptions);
+        // H1: If _head buffer has data, prepend it so the first frame isn't lost
+        if (head && head.length > 0) {
+            ws._onData(head);
+        }
+        this._wsConnections.add(ws);
+        this.metrics.wsConnectionOpen();
+        // H-SEC-2: Track per-IP count
+        this._wsPerIpCounts.set(wsRemoteAddr, (this._wsPerIpCounts.get(wsRemoteAddr) ?? 0) + 1);
+        ws.on("close", () => {
+            this._wsConnections.delete(ws);
+            this.metrics.wsConnectionClose();
+            // H-SEC-2: Decrement per-IP count
+            const count = (this._wsPerIpCounts.get(wsRemoteAddr) ?? 1) - 1;
+            if (count <= 0) {
+                this._wsPerIpCounts.delete(wsRemoteAddr);
+            }
+            else {
+                this._wsPerIpCounts.set(wsRemoteAddr, count);
+            }
+        });
+        ws.on("message", () => {
+            this.metrics.wsMessage("inbound");
+        });
+        ws.on("message", (message) => {
+            void this._runWsPluginHooks("message", {
+                ws,
+                req,
+                data: message,
+                meta: wsMeta,
+            });
+        });
+        ws.on("close", (code, reason) => {
+            void this._runWsPluginHooks("close", {
+                ws,
+                req,
+                code,
+                reason,
+                meta: wsMeta,
+            });
+        });
+        const connectResults = await this._runWsPluginHooks("connect", {
+            ws,
+            req,
+            meta: wsMeta,
+        });
+        for (const res of connectResults) {
+            if (!res.ok) {
+                try {
+                    ws.close?.(1011, "Internal plugin error");
+                }
+                catch { }
+                return;
+            }
+            const decision = res.result;
+            if (decision === false || (decision && decision.allow === false)) {
+                try {
+                    ws.close?.(decision && typeof decision === "object" ? (decision.closeCode ?? 1008) : 1008, decision && typeof decision === "object"
+                        ? (decision.closeReason ?? "Policy violation")
+                        : "Policy violation");
+                }
+                catch { }
+                return;
+            }
+        }
+        // Run handler within RequestContext
+        RequestContext.run(rctx, () => handler(ws, req));
+    }
+    async _proxyWsUpgradeToDevServer(req, socket, head, url) {
+        const mount = this._staticFileServer.resolveMountForRequest(req, url.pathname);
+        if (!mount?.devProxyTarget)
+            return false;
+        let target;
+        try {
+            target = new URL(mount.devProxyTarget);
+        }
+        catch (err) {
+            this.logger.warn("Invalid frontend dev proxy target for websocket upgrade", {
+                siteId: mount.siteId,
+                proxyTarget: mount.devProxyTarget,
+                error: err.message,
+            });
+            return false;
+        }
+        const isTls = target.protocol === "https:" || target.protocol === "wss:";
+        const isTcp = target.protocol === "http:" || target.protocol === "ws:";
+        if (!isTls && !isTcp) {
+            this.logger.warn("Unsupported websocket dev proxy protocol", {
+                siteId: mount.siteId,
+                proxyTarget: mount.devProxyTarget,
+                protocol: target.protocol,
+            });
+            return false;
+        }
+        const targetPort = target.port ? Number.parseInt(target.port, 10) : isTls ? 443 : 80;
+        const upstream = isTls
+            ? tls.connect({ host: target.hostname, port: targetPort })
+            : net.connect({ host: target.hostname, port: targetPort });
+        const forwardedHeaders = [];
+        const rawHeaders = Array.isArray(req.rawHeaders) ? req.rawHeaders : [];
+        for (let i = 0; i < rawHeaders.length; i += 2) {
+            const key = rawHeaders[i];
+            const value = rawHeaders[i + 1];
+            const keyLower = String(key ?? "").toLowerCase();
+            if (!keyLower)
+                continue;
+            if (keyLower === "host")
+                continue;
+            if (keyLower.startsWith("x-forge-"))
+                continue;
+            forwardedHeaders.push([String(key), String(value ?? "")]);
+        }
+        forwardedHeaders.push(["Host", target.host]);
+        if (req.headers.host) {
+            forwardedHeaders.push(["X-Forwarded-Host", String(req.headers.host)]);
+        }
+        forwardedHeaders.push(["X-Forwarded-Proto", "http"]);
+        const requestLine = `${req.method} ${url.pathname}${url.search} HTTP/${req.httpVersion}\r\n`;
+        const headerLines = forwardedHeaders.map(([k, v]) => `${k}: ${v}`).join("\r\n");
+        const upgradePayload = `${requestLine}${headerLines}\r\n\r\n`;
+        const connectEvent = isTls ? "secureConnect" : "connect";
+        return await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            const fail = (statusCode, statusText, err = null) => {
+                if (err) {
+                    this.logger.warn("Frontend websocket dev proxy failed", {
+                        siteId: mount.siteId,
+                        proxyTarget: mount.devProxyTarget,
+                        error: err.message,
+                    });
+                }
+                if (!socket.destroyed) {
+                    try {
+                        socket.write(`HTTP/1.1 ${statusCode} ${statusText}\r\n\r\n`);
+                    }
+                    catch { }
+                    socket.destroy();
+                }
+                if (!upstream.destroyed)
+                    upstream.destroy();
+                finish(true);
+            };
+            socket.once("error", (err) => fail(502, "Bad Gateway", err));
+            socket.once("close", () => {
+                if (!upstream.destroyed)
+                    upstream.destroy();
+            });
+            upstream.once("error", (err) => fail(502, "Bad Gateway", err));
+            upstream.once("close", () => {
+                if (!socket.destroyed)
+                    socket.destroy();
+            });
+            upstream.once(connectEvent, () => {
+                try {
+                    upstream.write(upgradePayload);
+                    if (head && head.length > 0) {
+                        upstream.write(head);
+                    }
+                    socket.pipe(upstream);
+                    upstream.pipe(socket);
+                    finish(true);
+                }
+                catch (err) {
+                    fail(502, "Bad Gateway", err);
+                }
+            });
+        });
+    }
+    /**
+     * Register this service with ForgeProxy.
+     * ForgeProxy then routes external traffic to us.
+     */
+    async _registerWithForgeProxy() {
+        const contract = this._serviceInstance?.constructor?.contract;
+        const methods = contract?.expose ?? [];
+        const registration = {
+            service: this.serviceName,
+            host: this._getHost(),
+            port: this.port,
+            workers: this.threadCount,
+            methods,
+            health_endpoint: "/health",
+        };
+        const resp = await fetch(`${this._forgeProxy}/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(registration),
+        });
+        if (resp.ok) {
+            this.logger.info(`Registered with ForgeProxy at ${this._forgeProxy}`, {
+                methods: methods.length,
+            });
+        }
+        else {
+            throw new Error(`ForgeProxy registration failed: ${resp.status}`);
+        }
+    }
+    _getHost() {
+        return process.env.FORGE_HOST ?? process.env.HOSTNAME ?? "127.0.0.1";
+    }
+}
+export { ForgeWebSocket };
+//# sourceMappingURL=ForgeContext.js.map