threadforge 0.1.1 → 0.2.1

package/src/core/Ingress.js

@@ -1,768 +0,0 @@
-/**
- * Ingress Protection
- *
- * Multiple layers of defense between the internet and your services.
- * Each layer catches different failure modes:
- *
- * ┌─────────────────────────────────────────────────────────────┐
- * │ INTERNET                                                   │
- * └───────────────────────────┬─────────────────────────────────┘
- *                             ▼
- * ┌─────────────────────────────────────────────────────────────┐
- * │ Layer 1: CONNECTION LIMITER                                │
- * │ Total open connections capped at N (e.g. 10,000).          │
- * │ New connections get TCP RST when full.                     │
- * │ Prevents file descriptor exhaustion.                       │
- * └───────────────────────────┬─────────────────────────────────┘
- *                             ▼
- * ┌─────────────────────────────────────────────────────────────┐
- * │ Layer 2: RATE LIMITER (per client)                         │
- * │ Token bucket per IP / API key. Burst-friendly.             │
- * │ Returns 429 Too Many Requests when exceeded.               │
- * │ Prevents single client from consuming all capacity.        │
- * └───────────────────────────┬─────────────────────────────────┘
- *                             ▼
- * ┌─────────────────────────────────────────────────────────────┐
- * │ Layer 3: GLOBAL LOAD SHEDDER                               │
- * │ Monitors gateway CPU + event loop lag.                     │
- * │ When overloaded, sheds low-priority requests (503).        │
- * │ High-priority requests (health checks, auth) pass through. │
- * │ Prevents cascade failure in the gateway itself.            │
- * └───────────────────────────┬─────────────────────────────────┘
- *                             ▼
- * ┌─────────────────────────────────────────────────────────────┐
- * │ Layer 4: ADAPTIVE CONCURRENCY (per service)                │
- * │ Limits in-flight requests to each downstream service.      │
- * │ Dynamically adjusts limit based on observed latency.       │
- * │ When a service slows down, we send FEWER requests to it.   │
- * │ Returns 503 when the service's concurrency window is full. │
- * │ Prevents a slow service from consuming all gateway threads.│
- * └───────────────────────────┬─────────────────────────────────┘
- *                             ▼
- * ┌─────────────────────────────────────────────────────────────┐
- * │ SERVICE (users, billing, etc.)                             │
- * └─────────────────────────────────────────────────────────────┘
- *
- * Usage in a gateway service:
- *
- *   import { IngressProtection } from 'threadforge/ingress';
- *
- *   export default class GatewayService extends Service {
- *     async onStart(ctx) {
- *       this.ingress = new IngressProtection({
- *         maxConnections: 10000,
- *         rateLimit: { windowMs: 60000, maxRequests: 100 },
- *         loadShedding: { eventLoopThresholdMs: 100 },
- *         services: {
- *           users:         { maxConcurrent: 200 },
- *           billing:       { maxConcurrent: 50 },
- *           notifications: { maxConcurrent: 100 },
- *         },
- *       });
- *
- *       // Apply as middleware
- *       ctx.router.use(this.ingress.middleware());
- *     }
- *   }
- */
-
-import { EventEmitter } from "node:events";
-import { isPrivateNetwork } from "./ForgeContext.js";
-
-// ─── Rate Limiter (Token Bucket) ────────────────────────────
-
-/**
- * Per-client rate limiter using the token bucket algorithm.
- *
- * Token bucket is burst-friendly: a client that hasn't made
- * requests in a while accumulates tokens and can burst.
- * A client that's been hammering the API runs out of tokens
- * and gets 429'd.
- *
- * Why token bucket instead of sliding window:
- *   - Allows natural burst patterns (page load = 10 requests at once)
- *   - Smoother than fixed windows (no "thundering herd" at window reset)
- *   - O(1) per request (no sorted sets or sliding counters)
- */
-export class RateLimiter {
-  /**
-   * @param {Object} options
-   * @param {number} [options.maxTokens=100]     - Max tokens per client (burst size)
-   * @param {number} [options.refillRate=10]     - Tokens added per second
-   * @param {number} [options.windowMs=60000]    - Cleanup interval for stale buckets
-   * @param {Function} [options.keyExtractor]    - (req) => string, extracts client identity
-   */
-  constructor(options = {}) {
-    this.maxTokens = options.maxTokens ?? 100;
-    this.refillRate = options.refillRate ?? (options.maxRequests ?? 100) / 60;
-    this.windowMs = options.windowMs ?? 60000;
-    this.keyExtractor = options.keyExtractor ?? defaultKeyExtractor;
-
-    /** @type {Map<string, {tokens: number, lastRefill: number}>} */
-    this.buckets = new Map();
-
-    // Periodically clean stale buckets
-    this._cleanupTimer = setInterval(() => this._cleanup(), this.windowMs);
-    this._cleanupTimer.unref();
-  }
-
-  /**
-   * Check if a request is allowed.
-   * @returns {{ allowed: boolean, remaining: number, retryAfter?: number }}
-   */
-  check(req) {
-    const key = this.keyExtractor(req);
-    const now = Date.now();
-
-    let bucket = this.buckets.get(key);
-    if (!bucket) {
-      bucket = { tokens: this.maxTokens, lastRefill: now };
-      this.buckets.set(key, bucket);
-    }
-
-    // Refill tokens based on elapsed time
-    const elapsed = (now - bucket.lastRefill) / 1000;
-    bucket.tokens = Math.min(this.maxTokens, bucket.tokens + elapsed * this.refillRate);
-    bucket.lastRefill = now;
-
-    if (bucket.tokens >= 1) {
-      bucket.tokens -= 1;
-      return {
-        allowed: true,
-        remaining: Math.floor(bucket.tokens),
-      };
-    }
-
-    // Rate limited — calculate retry-after
-    const tokensNeeded = 1 - bucket.tokens;
-    const retryAfterMs = Math.ceil((tokensNeeded / this.refillRate) * 1000);
-
-    return {
-      allowed: false,
-      remaining: 0,
-      retryAfter: retryAfterMs,
-    };
-  }
-
-  _cleanup() {
-    const staleThreshold = Date.now() - this.windowMs * 2;
-    for (const [key, bucket] of this.buckets) {
-      if (bucket.lastRefill < staleThreshold) {
-        this.buckets.delete(key);
-      }
-    }
-  }
-
-  get stats() {
-    return {
-      activeClients: this.buckets.size,
-      maxTokens: this.maxTokens,
-      refillRate: this.refillRate,
-    };
-  }
-
-  stop() {
-    if (this._cleanupTimer) clearInterval(this._cleanupTimer);
-  }
-}
-
-function isValidIP(str) {
-  if (!str) return false;
-  // IPv4
-  if (/^(\d{1,3}\.){3}\d{1,3}$/.test(str)) {
-    return str.split(".").every((p) => {
-      const n = parseInt(p, 10);
-      return n >= 0 && n <= 255;
-    });
-  }
-  // IPv6 (basic check)
-  if (/^[0-9a-fA-F:]+$/.test(str) && str.includes(":")) return true;
-  return false;
-}
-
-function isTrustedProxyAddr(address) {
-  const trusted = process.env.FORGE_TRUSTED_PROXIES;
-  if (!trusted) return false;
-  if (!address) return false;
-  const noZone = address.split("%")[0];
-  const addr = noZone.toLowerCase().replace(/^(0{0,4}:){0,5}(0{0,4}:)?ffff:/, "").replace(/^::ffff:/, "");
-  for (const entry of trusted.split(",")) {
-    const trimmed = entry.trim();
-    if (addr === trimmed) return true;
-  }
-  return false;
-}
-
-function defaultKeyExtractor(req) {
-  const rawAddr = req.socket?.remoteAddress;
-  const remoteAddr = rawAddr ?? `unknown_${Math.random().toString(36).slice(2, 10)}`;
-
-  // H1: Only trust X-Forwarded-For from trusted proxies
-  // If FORGE_TRUSTED_PROXIES is set, only those addresses are trusted.
-  // Otherwise, fall back to trusting private networks for backwards compatibility.
-  const trusted = process.env.FORGE_TRUSTED_PROXIES;
-  const isProxyTrusted = trusted ? isTrustedProxyAddr(remoteAddr) : (rawAddr && isPrivateNetwork(remoteAddr));
-  if (isProxyTrusted) {
-    const xff = req.headers?.["x-forwarded-for"];
-    if (xff) {
-      const ips = xff.split(",").slice(0, 10).map((ip) => ip.trim());
-      // Walk right-to-left to find first untrusted IP (the real client)
-      for (let i = ips.length - 1; i >= 0; i--) {
-        if (!isValidIP(ips[i])) continue;
-        const ipTrusted = trusted ? isTrustedProxyAddr(ips[i]) : isPrivateNetwork(ips[i]);
-        if (ips[i] && !ipTrusted) {
-          return ips[i];
-        }
-      }
-    }
-
-    // Fallback to X-Real-IP (commonly set by nginx)
-    const realIp = req.headers?.["x-real-ip"];
-    if (realIp && isValidIP(realIp)) {
-      return realIp;
-    }
-
-    return remoteAddr;
-  }
-
-  // Direct connection or no trusted proxies configured — use direct remote address
-  return remoteAddr;
-}
-
-// ─── Load Shedder ───────────────────────────────────────────
-
-/**
- * Global load shedder. Monitors the gateway process health and
- * drops requests when overloaded.
- *
- * Monitors two signals:
- *   1. Event loop lag — if the event loop is delayed by > threshold,
- *      the process is CPU-starved. Start shedding.
- *   2. Active requests — if we have too many in-flight, shed.
- *
- * Shedding is priority-based:
- *   - CRITICAL: health checks, auth — never shed
- *   - HIGH: payment webhooks — shed only at extreme load
- *   - NORMAL: regular API calls — shed when overloaded
- *   - LOW: analytics, logging — shed first
- */
-export class LoadShedder {
-  /**
-   * @param {Object} options
-   * @param {number} [options.eventLoopThresholdMs=100]   - Lag threshold to start shedding
-   * @param {number} [options.maxActiveRequests=5000]     - Max in-flight before shedding
-   * @param {number} [options.checkIntervalMs=500]        - How often to check event loop
-   * @param {Object} [options.priorities]                 - Path → priority overrides
-   */
-  constructor(options = {}) {
-    this.eventLoopThresholdMs = options.eventLoopThresholdMs ?? 100;
-    this.maxActiveRequests = options.maxActiveRequests ?? 5000;
-    this.checkIntervalMs = options.checkIntervalMs ?? 500;
-
-    // Default priority rules
-    this.priorityRules = [
-      { pattern: /^\/(health|ready|live)/, priority: "critical" },
-      { pattern: /^\/auth(\/|$)|^\/login(\/|$)|^\/oauth(\/|$)/, priority: "critical" },
-      { pattern: /^\/webhook(\/|$)|^\/stripe(\/|$)/, priority: "high" },
-      { pattern: /^\/api\//, priority: "normal" },
-      { pattern: /^\/analytics|^\/telemetry/, priority: "low" },
-      ...(options.priorityRules ?? []),
-    ];
-
-    this.activeRequests = 0;
-    this.eventLoopLag = 0;
-    this._lastCheck = Date.now();
-
-    // Shedding thresholds by priority
-    this.shedThresholds = {
-      low: { lagMs: 50, loadRatio: 0.6 },
-      normal: { lagMs: 100, loadRatio: 0.8 },
-      high: { lagMs: 200, loadRatio: 0.95 },
-      critical: { lagMs: Infinity, loadRatio: Infinity }, // never shed
-    };
-
-    // Start event loop lag measurement using recursive setTimeout to prevent drift
-    this._lagTimerActive = true;
-    const measureLag = () => {
-      if (!this._lagTimerActive) return;
-      const now = Date.now();
-      const expected = this.checkIntervalMs;
-      const actual = now - this._lastCheck;
-      this.eventLoopLag = Math.max(0, actual - expected);
-      this._lastCheck = now;
-      this._lagTimer = setTimeout(measureLag, this.checkIntervalMs);
-      this._lagTimer.unref();
-    };
-    this._lagTimer = setTimeout(measureLag, this.checkIntervalMs);
-    this._lagTimer.unref();
-  }
-
-  /**
-   * Should this request be accepted or shed?
-   * @param {Object} req - HTTP request
-   * @returns {{ accept: boolean, reason?: string, priority: string }}
-   */
-  shouldAccept(req) {
-    const priority = this._getPriority(req);
-    const threshold = this.shedThresholds[priority];
-    const loadRatio = this.activeRequests / this.maxActiveRequests;
-
-    // Check event loop lag
-    if (this.eventLoopLag > threshold.lagMs) {
-      return {
-        accept: false,
-        reason: `Event loop lag ${this.eventLoopLag}ms exceeds ${threshold.lagMs}ms threshold for ${priority} priority`,
-        priority,
-      };
-    }
-
-    // Check active request count
-    if (loadRatio > threshold.loadRatio) {
-      return {
-        accept: false,
-        reason: `Load at ${(loadRatio * 100).toFixed(0)}% exceeds ${(threshold.loadRatio * 100).toFixed(0)}% threshold for ${priority} priority`,
-        priority,
-      };
-    }
-
-    return { accept: true, priority };
-  }
-
-  _getPriority(req) {
-    const url = req.url ?? "/";
-    for (const rule of this.priorityRules) {
-      if (rule.pattern.test(url)) {
-        return rule.priority;
-      }
-    }
-    return "normal";
-  }
-
-  trackRequest() {
-    this.activeRequests++;
-    return () => {
-      this.activeRequests--;
-    };
-  }
-
-  get stats() {
-    return {
-      activeRequests: this.activeRequests,
-      maxActiveRequests: this.maxActiveRequests,
-      eventLoopLagMs: this.eventLoopLag,
-      loadPercent: ((this.activeRequests / this.maxActiveRequests) * 100).toFixed(1),
-      shedding:
-        this.eventLoopLag > this.shedThresholds.normal.lagMs || this.activeRequests > this.maxActiveRequests * 0.8,
-    };
-  }
-
-  stop() {
-    this._lagTimerActive = false;
-    if (this._lagTimer) clearTimeout(this._lagTimer);
-  }
-}
-
-// ─── Adaptive Concurrency Limiter ───────────────────────────
-
-/**
- * Adaptive Concurrency Limiter (per downstream service)
- *
- * The core problem: how many concurrent requests should we send
- * to the users service? Too few = wasted capacity. Too many =
- * overwhelm the service, latency spikes, cascade failure.
- *
- * Fixed limits are fragile — they're either too conservative
- * (wasting capacity during normal load) or too aggressive
- * (causing failures during peak).
- *
- * Instead, we use the Vegas algorithm (from TCP congestion control):
- *
- *   1. Start with a small concurrency window (e.g., 10)
- *   2. Measure round-trip latency for each request
- *   3. Track the minimum observed latency (the "no-load" baseline)
- *   4. If current latency ≈ baseline → increase the window
- *      (service has capacity, give it more)
- *   5. If current latency >> baseline → decrease the window
- *      (service is queuing, back off)
- *
- * This automatically adapts to:
- *   - Fast services (high window, more concurrent requests)
- *   - Slow services (low window, fewer concurrent requests)
- *   - Services that degrade under load (window shrinks as latency rises)
- *   - Services that recover (window grows as latency drops)
- *
- * Inspired by Netflix's concurrency-limits library.
- */
-export class AdaptiveConcurrencyLimiter {
-  /**
-   * @param {string} serviceName
-   * @param {Object} options
-   * @param {number} [options.initialLimit=20]     - Starting concurrency limit
-   * @param {number} [options.minLimit=5]          - Floor
-   * @param {number} [options.maxLimit=500]        - Ceiling
-   * @param {number} [options.smoothing=0.2]       - EMA smoothing for latency
-   * @param {number} [options.tolerance=2.0]       - Ratio of current/min latency
-   *                                                  before we reduce the limit
-   */
-  constructor(serviceName, options = {}) {
-    this.serviceName = serviceName;
-    this.limit = options.initialLimit ?? 20;
-    this.minLimit = options.minLimit ?? 5;
-    this.maxLimit = options.maxLimit ?? 500;
-    this.smoothing = options.smoothing ?? 0.2;
-    this.tolerance = options.tolerance ?? 2.0;
-
-    this.inFlight = 0;
-    this.minLatency = Infinity;
-    this.smoothedLatency = 0;
-
-    // Metrics
-    this.totalRequests = 0;
-    this.totalRejected = 0;
-    this.totalSuccesses = 0;
-    this.totalFailures = 0;
-
-    // Latency percentiles (ring buffer)
-    this._latencies = new Float64Array(1000);
-    this._latencyIdx = 0;
-    this._latencyCount = 0;
-
-    // Windowed minimum latency reset
-    this._minLatencyWindow = new Float64Array(1000);
-    this._minLatencyWindowIdx = 0;
-    this._minLatencyWindowCount = 0;
-    this._minLatencyObservations = 0;
-  }
-
-  /**
-   * Try to acquire a concurrency slot.
-   * @returns {{ acquired: boolean, release?: Function }}
-   */
-  tryAcquire() {
-    this.totalRequests++;
-
-    if (this.inFlight >= this.limit) {
-      this.totalRejected++;
-      return { acquired: false };
-    }
-
-    this.inFlight++;
-    const startTime = performance.now();
-
-    const release = (success = true) => {
-      this.inFlight--;
-      const latency = performance.now() - startTime;
-      this._recordLatency(latency, success);
-    };
-
-    return { acquired: true, release };
-  }
-
-  _recordLatency(latencyMs, success) {
-    if (success) {
-      this.totalSuccesses++;
-
-      // Track minimum latency with windowed reset
-      this._minLatencyWindow[this._minLatencyWindowIdx % this._minLatencyWindow.length] = latencyMs;
-      this._minLatencyWindowIdx++;
-      this._minLatencyWindowCount = Math.min(this._minLatencyWindowCount + 1, this._minLatencyWindow.length);
-      this._minLatencyObservations++;
-
-      if (latencyMs < this.minLatency) {
-        this.minLatency = latencyMs;
-      }
-
-      // Every 1000 observations, recalculate minLatency from the window
-      if (this._minLatencyObservations >= 1000) {
-        this._minLatencyObservations = 0;
-        let windowMin = Infinity;
-        for (let i = 0; i < this._minLatencyWindowCount; i++) {
-          if (this._minLatencyWindow[i] < windowMin) {
-            windowMin = this._minLatencyWindow[i];
-          }
-        }
-        this.minLatency = windowMin;
-      }
-
-      // Exponential moving average
-      if (this.smoothedLatency === 0) {
-        this.smoothedLatency = latencyMs;
-      } else {
-        this.smoothedLatency = this.smoothing * latencyMs + (1 - this.smoothing) * this.smoothedLatency;
-      }
-
-      // Store in ring buffer for percentile calculation
-      this._latencies[this._latencyIdx % this._latencies.length] = latencyMs;
-      this._latencyIdx++;
-      this._latencyCount = Math.min(this._latencyCount + 1, this._latencies.length);
-
-      // Adjust limit using Vegas algorithm
-      this._adjustLimit();
-    } else {
-      this.totalFailures++;
-      // On failure, aggressively reduce limit
-      this.limit = Math.max(this.minLimit, Math.floor(this.limit * 0.75));
-    }
-  }
-
-  _adjustLimit() {
-    if (this.minLatency === Infinity || this.smoothedLatency === 0) return;
-
-    const ratio = this.smoothedLatency / this.minLatency;
-
-    if (ratio < this.tolerance) {
-      // Latency is close to baseline — we have room, increase slowly
-      // The gradient determines how aggressively we grow
-      const gradient = Math.max(0, (this.tolerance - ratio) / this.tolerance);
-      const increase = Math.ceil(gradient * 2);
-      this.limit = Math.min(this.maxLimit, this.limit + increase);
-    } else {
-      // Latency is elevated — service is queuing, reduce
-      // Reduce proportionally to how far over the tolerance we are
-      const overshoot = ratio / this.tolerance;
-      const decrease = Math.ceil(overshoot);
-      this.limit = Math.max(this.minLimit, this.limit - decrease);
-    }
-  }
-
-  get stats() {
-    return {
-      service: this.serviceName,
-      currentLimit: this.limit,
-      inFlight: this.inFlight,
-      utilization: `${((this.inFlight / this.limit) * 100).toFixed(0)}%`,
-      minLatencyMs: this.minLatency === Infinity ? null : this.minLatency.toFixed(2),
-      smoothedLatencyMs: this.smoothedLatency.toFixed(2),
-      p99LatencyMs: this._getPercentile(0.99)?.toFixed(2) ?? null,
-      totalRequests: this.totalRequests,
-      totalRejected: this.totalRejected,
-      rejectionRate: `${((this.totalRejected / Math.max(1, this.totalRequests)) * 100).toFixed(1)}%`,
-    };
-  }
-
-  _getPercentile(p) {
-    if (this._latencyCount === 0) return null;
-    const sorted = Array.from(this._latencies.slice(0, this._latencyCount)).sort((a, b) => a - b);
-    const idx = Math.floor(sorted.length * p);
-    return sorted[idx];
-  }
-}
-
-// ─── IngressProtection (combines all layers) ────────────────
-
-/**
- * Combined ingress protection middleware.
- *
- * Applies all layers in order: connection limit → rate limit →
- * load shedding → route → adaptive concurrency → service.
- */
-export class IngressProtection extends EventEmitter {
-  /**
-   * @param {Object} options
-   * @param {number} [options.maxConnections=10000]
-   * @param {Object} [options.rateLimit]
-   * @param {Object} [options.loadShedding]
-   * @param {Object} [options.services]  - Per-service concurrency config
-   */
-  constructor(options = {}) {
-    super();
-
-    this.maxConnections = options.maxConnections ?? 10000;
-    this.activeConnections = 0;
-
-    this.rateLimiter = new RateLimiter(options.rateLimit ?? {});
-    this.loadShedder = new LoadShedder(options.loadShedding ?? {});
-
-    // Per-service adaptive concurrency limiters
-    /** @type {Map<string, AdaptiveConcurrencyLimiter>} */
-    this.serviceLimiters = new Map();
-
-    if (options.services) {
-      for (const [name, config] of Object.entries(options.services)) {
-        this.serviceLimiters.set(name, new AdaptiveConcurrencyLimiter(name, config));
-      }
-    }
-
-    this._metricsInterval = setInterval(() => {
-      this.emit("metrics", this.stats);
-    }, 10000);
-    this._metricsInterval.unref();
-  }
-
-  /**
-   * Get or create a concurrency limiter for a service.
-   */
-  getServiceLimiter(serviceName) {
-    if (!this.serviceLimiters.has(serviceName)) {
-      this.serviceLimiters.set(serviceName, new AdaptiveConcurrencyLimiter(serviceName));
-    }
-    return this.serviceLimiters.get(serviceName);
-  }
-
-  /**
-   * Returns a middleware function for the ForgeContext router.
-   *
-   * Usage:
-   *   ctx.router.use(this.ingress.middleware());
-   */
-  middleware() {
-    return async (req, res, next) => {
-      // Layer 1: Connection limit
-      if (this.activeConnections >= this.maxConnections) {
-        res.writeHead(503, { "Retry-After": "5" });
-        res.end(JSON.stringify({ error: "Server at connection capacity" }));
-        return;
-      }
-      this.activeConnections++;
-      let connectionCounted = true;
-      req.on("close", () => {
-        if (connectionCounted) {
-          this.activeConnections--;
-          connectionCounted = false;
-        }
-      });
-
-      // Layer 2: Rate limiting
-      const rateCheck = this.rateLimiter.check(req);
-      if (!rateCheck.allowed) {
-        const retryAfterSec = Math.ceil(rateCheck.retryAfter / 1000);
-        res.writeHead(429, {
-          "Retry-After": String(retryAfterSec),
-          "X-RateLimit-Remaining": "0",
-          "X-RateLimit-Reset": String(retryAfterSec),
-        });
-        res.end(
-          JSON.stringify({
-            error: "Rate limit exceeded",
-            retryAfter: retryAfterSec,
-          }),
-        );
-        if (connectionCounted) {
-          connectionCounted = false;
-          this.activeConnections--;
-        }
-        return;
-      }
-
-      // Layer 3: Load shedding
-      const shedCheck = this.loadShedder.shouldAccept(req);
-      if (!shedCheck.accept) {
-        res.writeHead(503, { "Retry-After": "1" });
-        // Don't expose internal load/lag details to clients
-        res.end(
-          JSON.stringify({
-            error: "Service temporarily overloaded",
-          }),
-        );
-        if (connectionCounted) {
-          connectionCounted = false;
-          this.activeConnections--;
-        }
-        return;
-      }
-
-      // Track active request
-      const releaseRequest = this.loadShedder.trackRequest();
-
-      // Add headers
-      res.setHeader("X-RateLimit-Remaining", String(rateCheck.remaining));
-
-      // Track completion by wrapping res.end — also hook close for premature disconnects
-      let requestReleased = false;
-      const doRelease = () => {
-        if (!requestReleased) {
-          requestReleased = true;
-          releaseRequest();
-          // Clean up close listener to avoid accumulation
-          if (typeof res.removeListener === "function") {
-            res.removeListener("close", doRelease);
-          }
-        }
-      };
-
-      const origEnd = res.end.bind(res);
-      res.end = (...args) => {
-        doRelease();
-        return origEnd(...args);
-      };
-
-      // If client disconnects before res.end(), still release
-      if (typeof res.on === "function") res.on("close", doRelease);
-
-      // Pass through to router
-      if (next) next();
-    };
-  }
-
-  /**
-   * Wrap a proxy call with adaptive concurrency limiting.
-   *
-   * Usage in the gateway:
-   *   const user = await this.ingress.withConcurrencyLimit('users', () =>
-   *     this.users.getUser(id)
-   *   );
-   *
-   * Or in the proxy interceptor layer:
-   *   The ServiceProxy automatically calls this if ingress is configured.
-   */
-  async withConcurrencyLimit(serviceName, fn) {
-    const limiter = this.getServiceLimiter(serviceName);
-    const slot = limiter.tryAcquire();
-
-    if (!slot.acquired) {
-      const err = new Error(
-        `Service "${serviceName}" at concurrency limit (${limiter.limit}). ` +
-          `${limiter.inFlight} requests in flight.`,
-      );
-      err.code = "CONCURRENCY_LIMIT";
-      err.statusCode = 503;
-      throw err;
-    }
-
-    try {
-      const result = await fn();
-      slot.release(true);
-      return result;
-    } catch (err) {
-      slot.release(false);
-      throw err;
-    }
-  }
-
-  get stats() {
-    const serviceStats = {};
-    for (const [name, limiter] of this.serviceLimiters) {
-      serviceStats[name] = limiter.stats;
-    }
-
-    return {
-      connections: {
-        active: this.activeConnections,
-        max: this.maxConnections,
-      },
-      rateLimiter: this.rateLimiter.stats,
-      loadShedder: this.loadShedder.stats,
-      services: serviceStats,
-    };
-  }
-
-  /**
-   * HTTP handler for ingress stats endpoint.
-   * Mount on the metrics server:
-   *   GET /ingress → full stats
-   */
-  httpHandler(req, res) {
-    if (req.url === "/ingress") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify(this.stats, null, 2));
-      return true;
-    }
-    return false;
-  }
-
-  stop() {
-    this.rateLimiter.stop();
-    this.loadShedder.stop();
-    if (this._metricsInterval) clearInterval(this._metricsInterval);
-  }
-}