threadforge 0.1.1 → 0.2.1

package/src/core/MessageBus.js

@@ -1,321 +0,0 @@
-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);
-    }
-
-    // F-6: Reject pending requests dispatched to the dead worker immediately
-    // instead of making callers wait for the full timeout.
-    for (const [reqId, entry] of this.pendingRequests) {
-      if (entry.targetPid === pidOrThreadId) {
-        clearTimeout(entry.timer);
-        this.pendingRequests.delete(reqId);
-        entry.reject(new Error(`Worker ${pidOrThreadId} for "${serviceName}" exited while handling request`));
-      }
-    }
-
-    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);
-
-      const idx = this.rrIndex.get(target);
-      const worker = channel[idx % channel.length];
-
-      // F-6: Track target PID so pending requests can be rejected on worker death
-      this.pendingRequests.set(requestId, { resolve, reject, timer, targetPid: worker.pid });
-      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

@@ -1,305 +0,0 @@
-/**
- * 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;
-      }
-    }
-  }
-}