threadforge 0.1.0

package/src/core/MessageBus.js

@@ -0,0 +1,310 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * MessageBus
+ *
+ * @deprecated Use DirectMessageBus instead. MessageBus uses older cluster IPC
+ * with round-robin dispatch. DirectMessageBus provides Unix Domain Socket mesh
+ * for direct worker-to-worker communication with better performance.
+ *
+ * Provides inter-service communication within a ThreadForge runtime.
+ * Uses IPC channels for cluster workers and MessagePort for worker_threads.
+ *
+ * Features:
+ *  - Named channels per service
+ *  - Round-robin dispatch across workers of the same service
+ *  - Request/response pattern support
+ *  - Broadcast to all workers of a service
+ */
+export class MessageBus extends EventEmitter {
+  constructor() {
+    super();
+    console.warn('[ThreadForge] MessageBus is deprecated. Use DirectMessageBus instead.');
+
+    /** @type {Map<string, Array<{pid: number, send: Function}>>} */
+    this.channels = new Map();
+
+    /** @type {Map<string, number>} round-robin index per service */
+    this.rrIndex = new Map();
+
+    /** @type {Map<string, {resolve: Function, reject: Function, timer: NodeJS.Timeout}>} */
+    this.pendingRequests = new Map();
+
+    this.requestCounter = 0;
+  }
+
+  /**
+   * Register a worker for a service.
+   *
+   * @param {string} serviceName
+   * @param {Object} worker - cluster.Worker or worker_threads.Worker
+   * @param {'cluster' | 'worker'} mode
+   */
+  registerWorker(serviceName, worker, mode = "cluster") {
+    if (!this.channels.has(serviceName)) {
+      this.channels.set(serviceName, []);
+      this.rrIndex.set(serviceName, 0);
+    }
+
+    const channel = this.channels.get(serviceName);
+
+    if (mode === "cluster") {
+      channel.push({
+        pid: worker.id,
+        send: (msg) => worker.send(msg),
+        worker,
+      });
+
+      // Listen for messages from this worker and route them
+      worker.on("message", (msg) => this._handleMessage(serviceName, msg, worker));
+    } else {
+      // worker_threads mode
+      channel.push({
+        pid: worker.threadId,
+        send: (msg) => worker.postMessage(msg),
+        worker,
+      });
+
+      worker.on("message", (msg) => this._handleMessage(serviceName, msg, worker));
+    }
+  }
+
+  /**
+   * Remove all workers for a service.
+   */
+  unregisterService(serviceName) {
+    this.channels.delete(serviceName);
+    this.rrIndex.delete(serviceName);
+  }
+
+  /**
+   * Remove a specific worker.
+   */
+  unregisterWorker(serviceName, pidOrThreadId) {
+    const channel = this.channels.get(serviceName);
+    if (!channel) return;
+
+    const idx = channel.findIndex((c) => c.pid === pidOrThreadId);
+    if (idx !== -1) {
+      channel.splice(idx, 1);
+    }
+
+    if (channel.length === 0) {
+      this.channels.delete(serviceName);
+      this.rrIndex.delete(serviceName);
+    } else {
+      // CR-IPC-12: Use modulo to preserve distribution during scale-down
+      const currentIdx = this.rrIndex.get(serviceName) ?? 0;
+      if (currentIdx >= channel.length) {
+        this.rrIndex.set(serviceName, currentIdx % channel.length);
+      }
+    }
+  }
+
+  /**
+   * Send a fire-and-forget message to a service (round-robin across its workers).
+   *
+   * @param {string} from      - Sending service name
+   * @param {string} target    - Target service name
+   * @param {*}      payload   - Message payload (must be structured-cloneable)
+   */
+  send(from, target, payload) {
+    const channel = this.channels.get(target);
+    if (!channel || channel.length === 0) {
+      throw new Error(`[MessageBus] No workers registered for service "${target}"`);
+    }
+
+    const idx = this.rrIndex.get(target);
+    const worker = channel[idx % channel.length];
+    this.rrIndex.set(target, (idx + 1) % 1_000_000_000);
+
+    // CR-IPC-6: Let send errors propagate to callers
+    worker.send({
+      type: "forge:message",
+      from,
+      payload,
+    });
+  }
+
+  /**
+   * Broadcast a message to ALL workers of a service.
+   */
+  broadcast(from, target, payload) {
+    const channel = this.channels.get(target);
+    if (!channel || channel.length === 0) {
+      throw new Error(`[MessageBus] No workers registered for service "${target}"`);
+    }
+
+    let successCount = 0;
+    for (const worker of channel) {
+      try {
+        worker.send({
+          type: "forge:message",
+          from,
+          payload,
+        });
+        successCount++;
+      } catch (err) {
+        this.logger?.warn?.(`Broadcast failed for worker ${worker.pid}: ${err.message}`);
+      }
+    }
+    return successCount;
+  }
+
+  /**
+   * Broadcast a message to ALL services (all workers).
+   */
+  broadcastAll(from, payload) {
+    for (const [serviceName] of this.channels) {
+      if (serviceName !== from) {
+        this.broadcast(from, serviceName, payload);
+      }
+    }
+  }
+
+  /**
+   * Send a request and wait for a response.
+   * Implements a request/reply pattern over IPC.
+   *
+   * @param {string} from
+   * @param {string} target
+   * @param {*}      payload
+   * @param {number} [timeoutMs=5000]
+   * @returns {Promise<*>}
+   */
+  request(from, target, payload, timeoutMs = 5000) {
+    const channel = this.channels.get(target);
+    if (!channel || channel.length === 0) {
+      return Promise.reject(new Error(`[MessageBus] No workers registered for service "${target}"`));
+    }
+
+    if (this.pendingRequests.size >= 10000) {
+      return Promise.reject(new Error(
+        `Too many pending requests (${this.pendingRequests.size}). Target service "${target}" may be unresponsive.`
+      ));
+    }
+
+    this.requestCounter = (this.requestCounter + 1) % 1_000_000_000;
+    const requestId = `req_sup_${this.requestCounter}_${Date.now()}_${Math.random().toString(36).slice(2, 18)}`;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error(`[MessageBus] Request to "${target}" timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pendingRequests.set(requestId, { resolve, reject, timer });
+
+      const idx = this.rrIndex.get(target);
+      const worker = channel[idx % channel.length];
+      this.rrIndex.set(target, (idx + 1) % 1_000_000_000);
+
+      try {
+        worker.send({
+          type: "forge:request",
+          requestId,
+          from,
+          payload,
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        this.pendingRequests.delete(requestId);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Handle an incoming message from a worker.
+   */
+  _handleMessage(sourceName, msg, callerWorker) {
+    if (!msg || !msg.type) return;
+
+    switch (msg.type) {
+      case "forge:send": {
+        // Worker wants to send to another service
+        this.send(sourceName, msg.target, msg.payload);
+        break;
+      }
+
+      case "forge:broadcast": {
+        this.broadcast(sourceName, msg.target, msg.payload);
+        break;
+      }
+
+      case "forge:request": {
+        // Worker wants to make a request to another service
+        this.request(sourceName, msg.target, msg.payload, msg.timeout)
+          .then((result) => {
+            // Send response only to the requesting worker (not all workers)
+            try {
+              callerWorker.send({
+                type: "forge:response",
+                requestId: msg.requestId,
+                payload: result,
+                error: null,
+              });
+            } catch (sendErr) {
+              console.error('[MessageBus] Failed to send response:', sendErr.message);
+            }
+          })
+          .catch((err) => {
+            try {
+              callerWorker.send({
+                type: "forge:response",
+                requestId: msg.requestId,
+                payload: null,
+                error: { message: err.message, code: err.code, statusCode: err.statusCode },
+              });
+            } catch (sendErr) {
+              console.error('[MessageBus] Failed to send error response:', sendErr.message);
+            }
+          });
+        break;
+      }
+
+      case "forge:response": {
+        // Response to a pending request
+        const pending = this.pendingRequests.get(msg.requestId);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this.pendingRequests.delete(msg.requestId);
+          if (msg.error) {
+            const errObj = typeof msg.error === 'object' ? msg.error : { message: msg.error };
+            const err = new Error(errObj.message);
+            if (errObj.code) err.code = errObj.code;
+            if (errObj.statusCode) err.statusCode = errObj.statusCode;
+            pending.reject(err);
+          } else {
+            pending.resolve(msg.payload);
+          }
+        }
+        break;
+      }
+
+      case "forge:metric": {
+        this.emit("metric", { service: sourceName, ...msg });
+        break;
+      }
+
+      case "forge:log": {
+        this.emit("log", { service: sourceName, ...msg });
+        break;
+      }
+    }
+  }
+
+  /**
+   * Get stats about registered channels.
+   */
+  stats() {
+    const result = {};
+    for (const [name, workers] of this.channels) {
+      result[name] = {
+        workerCount: workers.length,
+        pids: workers.map((w) => w.pid),
+      };
+    }
+    return result;
+  }
+}

package/src/core/Prometheus.js

@@ -0,0 +1,305 @@
+/**
+ * Prometheus Metrics
+ *
+ * Proper Prometheus exposition format. Auto-tracks:
+ *
+ *   forge_http_request_duration_seconds  — histogram, per route + status + tenant
+ *   forge_http_requests_total            — counter, per route + status + tenant
+ *   forge_http_active_requests           — gauge, current in-flight
+ *   forge_rpc_duration_seconds           — histogram, per target + method
+ *   forge_rpc_total                      — counter, per target + method + success/error
+ *   forge_circuit_breaker_state          — gauge, 0=closed 1=open 2=half-open
+ *   forge_concurrency_limit              — gauge, per-service adaptive limit
+ *   forge_concurrency_in_flight          — gauge, per-service in-flight
+ *   forge_ws_connections_active          — gauge, current WebSocket connections
+ *   forge_ws_messages_total              — counter, WebSocket messages
+ *
+ * GET /metrics → text/plain Prometheus format
+ *
+ * Usage:
+ *   const metrics = new PrometheusMetrics('users', 0);
+ *   metrics.httpRequestDuration(0.045, { method: 'GET', path: '/users/:id', status: 200, tenant_id: 't_acme' });
+ *   metrics.expose() → "# HELP forge_http_request_duration_seconds ..."
+ */
+
+const ALLOWED_HTTP_LABELS = new Set(["method", "status", "route_pattern", "service", "status_code"]);
+const ALLOWED_RPC_LABELS = new Set(["target", "method", "result", "service"]);
+
+/** P2: Normalize error codes to a finite set to prevent cardinality bombs */
+export function normalizeErrorCode(err) {
+  if (err.code === 'ETIMEDOUT' || err.code === 'TIMEOUT') return 'timeout';
+  if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET') return 'connection';
+  if (err.statusCode >= 500) return 'server_error';
+  if (err.statusCode >= 400) return 'client_error';
+  if (err.code === 'CIRCUIT_OPEN') return 'circuit_open';
+  return 'unknown';
+}
+
+/** P9: Cache label key string construction */
+const _labelKeyCache = new Map();
+const MAX_LABEL_KEY_CACHE = 10000;
+
+function filterLabels(labels, allowed) {
+  const filtered = {};
+  for (const key of Object.keys(labels)) {
+    if (allowed.has(key)) filtered[key] = labels[key];
+  }
+  return filtered;
+}
+
+export class PrometheusMetrics {
+  constructor(serviceName, workerId) {
+    this.serviceName = serviceName;
+    this.workerId = workerId;
+    this.startTime = Date.now();
+
+    // Histogram buckets (seconds)
+    this.httpBuckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+    this.rpcBuckets = [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.5, 1, 5];
+
+    /** @type {Map<string, number>} */
+    this._counters = new Map();
+    /** @type {Map<string, number>} */
+    this._gauges = new Map();
+    /** @type {Map<string, {count: number, sum: number, buckets: number[], bucketBounds: number[]}>} */
+    this._histograms = new Map();
+  }
+
+  // ── Auto-tracked methods ──
+
+  httpRequestStart() {
+    this._gaugeInc("forge_http_active_requests", { service: this.serviceName });
+  }
+
+  httpRequestEnd(durationSecs, labels = {}) {
+    const filtered = filterLabels({ service: this.serviceName, ...labels }, ALLOWED_HTTP_LABELS);
+    this._gaugeDec("forge_http_active_requests", { service: this.serviceName });
+    this._histogramObserve(
+      "forge_http_request_duration_seconds",
+      durationSecs,
+      filtered,
+      this.httpBuckets,
+    );
+    this._counterInc("forge_http_requests_total", filtered);
+  }
+
+  rpcCall(durationSecs, labels = {}) {
+    const filtered = filterLabels({ service: this.serviceName, ...labels }, ALLOWED_RPC_LABELS);
+    this._histogramObserve(
+      "forge_rpc_duration_seconds",
+      durationSecs,
+      {
+        source: this.serviceName,
+        ...filtered,
+      },
+      this.rpcBuckets,
+    );
+    this._counterInc("forge_rpc_total", {
+      source: this.serviceName,
+      ...filtered,
+    });
+  }
+
+  wsConnectionOpen() {
+    this._gaugeInc("forge_ws_connections_active", { service: this.serviceName });
+  }
+
+  wsConnectionClose() {
+    this._gaugeDec("forge_ws_connections_active", { service: this.serviceName });
+  }
+
+  wsMessage(direction = "inbound") {
+    this._counterInc("forge_ws_messages_total", {
+      service: this.serviceName,
+      direction,
+    });
+  }
+
+  concurrencyUpdate(target, limit, inFlight) {
+    this._gaugeSet("forge_concurrency_limit", limit, {
+      source: this.serviceName,
+      target,
+    });
+    this._gaugeSet("forge_concurrency_in_flight", inFlight, {
+      source: this.serviceName,
+      target,
+    });
+  }
+
+  circuitBreakerState(target, state) {
+    // 0=closed, 1=open, 2=half-open
+    const val = state === "open" ? 1 : state === "half-open" ? 2 : 0;
+    this._gaugeSet("forge_circuit_breaker_state", val, {
+      source: this.serviceName,
+      target,
+    });
+  }
+
+  // ── Generic methods (for custom metrics) ──
+
+  counter(name, value = 1, labels = {}) {
+    this._counterInc(name, { service: this.serviceName, ...labels }, value);
+  }
+
+  gauge(name, value, labels = {}) {
+    this._gaugeSet(name, value, { service: this.serviceName, ...labels });
+  }
+
+  histogram(name, value, labels = {}, buckets) {
+    this._histogramObserve(name, value, { service: this.serviceName, ...labels }, buckets || this.httpBuckets);
+  }
+
+  // ── Exposition ──
+
+  /**
+   * Render all metrics in Prometheus text exposition format.
+   */
+  expose() {
+    const lines = [];
+    const now = Date.now();
+
+    // Uptime
+    lines.push(`# HELP forge_uptime_seconds Service uptime`);
+    lines.push(`# TYPE forge_uptime_seconds gauge`);
+    lines.push(
+      `forge_uptime_seconds{service="${this.serviceName}",worker="${this.workerId}"} ${((now - this.startTime) / 1000).toFixed(1)}`,
+    );
+    lines.push("");
+
+    // Counters
+    const counterNames = new Set([...this._counters.keys()].map((k) => k.split("{")[0]));
+    for (const name of counterNames) {
+      lines.push(`# HELP ${name} ${name}`);
+      lines.push(`# TYPE ${name} counter`);
+      for (const [key, val] of this._counters) {
+        if (key === name || key.startsWith(name + "{")) {
+          lines.push(`${key} ${val}`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Gauges
+    const gaugeNames = new Set([...this._gauges.keys()].map((k) => k.split("{")[0]));
+    for (const name of gaugeNames) {
+      lines.push(`# HELP ${name} ${name}`);
+      lines.push(`# TYPE ${name} gauge`);
+      for (const [key, val] of this._gauges) {
+        if (key === name || key.startsWith(name + "{")) {
+          lines.push(`${key} ${val}`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Histograms
+    const histNames = new Set([...this._histograms.keys()].map((k) => k.split("{")[0]));
+    for (const name of histNames) {
+      lines.push(`# HELP ${name} ${name}`);
+      lines.push(`# TYPE ${name} histogram`);
+      for (const [key, hist] of this._histograms) {
+        if (key !== name && !key.startsWith(name + "{")) continue;
+        const labelPart = key.includes("{") ? key.slice(key.indexOf("{")) : "";
+        const prefix = name;
+
+        // Bucket lines
+        const buckets = hist.bucketBounds;
+        for (let i = 0; i < buckets.length; i++) {
+          const le = buckets[i];
+          const bucketLabel = labelPart ? labelPart.replace("}", `,le="${le}"}`) : `{le="${le}"}`;
+          lines.push(`${prefix}_bucket${bucketLabel} ${hist.buckets[i]}`);
+        }
+        const infLabel = labelPart ? labelPart.replace("}", `,le="+Inf"}`) : `{le="+Inf"}`;
+        lines.push(`${prefix}_bucket${infLabel} ${hist.count}`);
+        lines.push(`${prefix}_sum${labelPart} ${hist.sum.toFixed(6)}`);
+        lines.push(`${prefix}_count${labelPart} ${hist.count}`);
+      }
+      lines.push("");
+    }
+
+    // Process metrics
+    const mem = process.memoryUsage();
+    lines.push(`# HELP process_resident_memory_bytes Resident memory size in bytes`);
+    lines.push(`# TYPE process_resident_memory_bytes gauge`);
+    lines.push(`process_resident_memory_bytes{service="${this.serviceName}"} ${mem.rss}`);
+    lines.push(`# HELP process_heap_used_bytes Node.js heap used in bytes`);
+    lines.push(`# TYPE process_heap_used_bytes gauge`);
+    lines.push(`process_heap_used_bytes{service="${this.serviceName}"} ${mem.heapUsed}`);
+    lines.push("");
+
+    return `${lines.join("\n")}\n`;
+  }
+
+  // ── Internal ──
+
+  _labelStr(labels) {
+    const key = JSON.stringify(labels);
+    if (_labelKeyCache.has(key)) return _labelKeyCache.get(key);
+
+    const validKeyRe = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+    const parts = [];
+    for (const k of Object.keys(labels)) {
+      const v = labels[k];
+      if (v === undefined || v === null) continue;
+      // H7: Sanitize label keys
+      const safeKey = validKeyRe.test(k) ? k : k.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[^a-zA-Z_]/, '_');
+      // Truncate label values to 256 chars and escape special characters
+      const safeVal = String(v).slice(0, 256).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+      parts.push(`${safeKey}="${safeVal}"`);
+    }
+    const result = parts.length > 0 ? `{${parts.join(",")}}` : "";
+
+    // P9-fix: Evict oldest 20% when cache is full (was: stop caching entirely)
+    if (_labelKeyCache.size >= MAX_LABEL_KEY_CACHE) {
+      const evictCount = Math.ceil(MAX_LABEL_KEY_CACHE * 0.2);
+      const iter = _labelKeyCache.keys();
+      for (let i = 0; i < evictCount; i++) {
+        const k = iter.next().value;
+        if (k !== undefined) _labelKeyCache.delete(k);
+      }
+    }
+    _labelKeyCache.set(key, result);
+    return result;
+  }
+
+  _counterInc(name, labels = {}, value = 1) {
+    const key = `${name}${this._labelStr(labels)}`;
+    this._counters.set(key, (this._counters.get(key) ?? 0) + value);
+  }
+
+  _gaugeSet(name, value, labels = {}) {
+    const key = `${name}${this._labelStr(labels)}`;
+    this._gauges.set(key, value);
+  }
+
+  _gaugeInc(name, labels = {}) {
+    const key = `${name}${this._labelStr(labels)}`;
+    this._gauges.set(key, (this._gauges.get(key) ?? 0) + 1);
+  }
+
+  _gaugeDec(name, labels = {}) {
+    const key = `${name}${this._labelStr(labels)}`;
+    this._gauges.set(key, Math.max(0, (this._gauges.get(key) ?? 0) - 1));
+  }
+
+  _histogramObserve(name, value, labels = {}, buckets) {
+    const key = `${name}${this._labelStr(labels)}`;
+    let hist = this._histograms.get(key);
+    if (!hist) {
+      hist = { count: 0, sum: 0, buckets: new Array(buckets.length).fill(0), bucketBounds: buckets };
+      this._histograms.set(key, hist);
+    }
+    hist.count++;
+    hist.sum += value;
+    // P18: Early break — once value <= buckets[i], all subsequent buckets also match
+    // since buckets are sorted ascending. Increment from this point to end.
+    for (let i = 0; i < buckets.length; i++) {
+      if (value <= buckets[i]) {
+        for (let j = i; j < buckets.length; j++) {
+          hist.buckets[j]++;
+        }
+        break;
+      }
+    }
+  }
+}