threadforge 0.1.1 → 0.2.1

package/src/decorators/ServiceProxy.js

@@ -1,904 +0,0 @@
-/**
- * ServiceProxy v2
- *
- * Auto-generates proxy clients with:
- *   - Pluggable routing strategies (round-robin, hash, least-pending)
- *   - Interceptor chains (deadline, logging, circuit breaker, retry)
- *   - Pending request tracking (for least-pending routing)
- *   - Contract-based method validation
- */
-
-import { isPrivateNetwork, isTrustedProxy } from "../core/ForgeContext.js";
-import { AdaptiveConcurrencyLimiter } from "../core/Ingress.js";
-import {
-  bulkheadInterceptor,
-  CircuitBreaker,
-  deadlineInterceptor,
-  isRetryable,
-  loggingInterceptor,
-  metricsInterceptor,
-  runInterceptorChain,
-} from "../core/Interceptors.js";
-import { RequestContext } from "../core/RequestContext.js";
-import { getContract } from "./index.js";
-
-const _WIRED_SERVICES = new WeakSet();
-
-// ─── LRU-style cache with oldest-20% eviction ────────────────────────
-const MAX_CACHE_SIZE = 1000;
-const EVICT_COUNT = Math.floor(MAX_CACHE_SIZE * 0.2); // 200
-
-/**
- * Evict the oldest 20% of entries from a Map whose values are
- * `{ fn, order }` objects. Entries are sorted by insertion order
- * and the lowest-order entries are removed.
- */
-function evictOldest(cache) {
-  if (cache.size <= MAX_CACHE_SIZE) return;
-  // Map iteration order is insertion order, so the first EVICT_COUNT entries are oldest
-  let removed = 0;
-  for (const key of cache.keys()) {
-    if (removed >= EVICT_COUNT) break;
-    cache.delete(key);
-    removed++;
-  }
-}
-
-// ─── Simple token-bucket rate limiter (per-route, per-IP) ────────────
-const _rateLimitBuckets = new Map();
-const MAX_RATE_LIMIT_BUCKETS = 100_000;
-
-const _rateLimitCleanupTimer = setInterval(() => {
-  const now = Date.now();
-  for (const [key, bucket] of _rateLimitBuckets) {
-    if (now - bucket.windowStart > 120_000) {
-      _rateLimitBuckets.delete(key);
-    }
-  }
-}, 60_000);
-_rateLimitCleanupTimer.unref?.();
-
-function parseRateLimit(spec) {
-  const m = /^(\d+)\/(sec|min|hour)$/i.exec(spec);
-  if (!m) return null;
-  const limit = parseInt(m[1], 10);
-  const windowMs = { sec: 1000, min: 60_000, hour: 3_600_000 }[m[2].toLowerCase()];
-  return { limit, windowMs };
-}
-
-let _lastEvictionCheck = 0;
-
-function checkRateLimit(routeKey, ip, config) {
-  const now = Date.now();
-  if (_rateLimitBuckets.size > MAX_RATE_LIMIT_BUCKETS && now - _lastEvictionCheck >= 10_000) {
-    _lastEvictionCheck = now;
-    setImmediate(() => {
-      const cutoff = Date.now();
-      for (const [k, b] of _rateLimitBuckets) {
-        if (cutoff - b.windowStart > 120_000) _rateLimitBuckets.delete(k);
-      }
-    });
-  }
-  const bucketKey = `${routeKey}:${ip}`;
-  let bucket = _rateLimitBuckets.get(bucketKey);
-  if (!bucket || now - bucket.windowStart >= config.windowMs) {
-    bucket = { count: 1, windowStart: now };
-    _rateLimitBuckets.set(bucketKey, bucket);
-    return true;
-  }
-  bucket.count++;
-  return bucket.count <= config.limit;
-}
-
-/** Sentinel returned by handleProxyRequest when the message isn't a proxy request. */
-export const NOT_HANDLED = Symbol("NOT_HANDLED");
-
-/**
- * Per-target concurrency limiters, shared across all proxies on this node.
- * @type {Map<string, AdaptiveConcurrencyLimiter>}
- */
-const _concurrencyLimiters = new Map();
-
-function getConcurrencyLimiter(targetName, config = {}) {
-  if (!_concurrencyLimiters.has(targetName)) {
-    _concurrencyLimiters.set(targetName, new AdaptiveConcurrencyLimiter(targetName, config));
-  }
-  return _concurrencyLimiters.get(targetName);
-}
-
-/** Expose for status endpoints */
-export function getAllConcurrencyStats() {
-  const stats = {};
-  for (const [name, limiter] of _concurrencyLimiters) {
-    stats[name] = limiter.stats;
-  }
-  return stats;
-}
-
-/**
- * Build proxy clients for all services this service connects to.
- *
- * @param {ForgeContext} ctx - The calling service's context
- * @param {Map<string, Function>} serviceClasses - service name → ServiceClass
- * @param {Map<string, {service, ctx}>} localServices - Colocated instances
- * @param {Object} [options]
- * @param {Object} [options.interceptors] - Default interceptors for all proxies
- * @returns {Object} Map of service name → proxy client
- */
-export function buildServiceProxies(ctx, serviceClasses, localServices = new Map(), options = {}) {
-  const proxies = {};
-
-  for (const [serviceName, ServiceClass] of serviceClasses) {
-    if (serviceName === ctx.serviceName) continue;
-
-    const contract = getContract(ServiceClass);
-    proxies[serviceName] = createServiceProxy(
-      ctx,
-      serviceName,
-      contract,
-      localServices.get(serviceName) ?? null,
-      options,
-    );
-  }
-
-  return proxies;
-}
-
-/**
- * Create a proxy client for a single target service.
- */
-export function createServiceProxy(ctx, targetName, contract, localInstance, options) {
-  // Wire routing strategy to EndpointResolver if configured
-  const routingStrategy = contract?.routingStrategy ?? options.routingStrategy;
-  if (routingStrategy && ctx._endpointResolver) {
-    ctx._endpointResolver.setStrategy(targetName, routingStrategy);
-  }
-
-  // Build interceptor chain (retry is handled as an outer loop, not in the chain)
-  const interceptors = buildInterceptors(ctx, targetName, contract, options);
-
-  // Retry config (service-level default; per-method overrides in createProxiedMethod)
-  const retryConfig = contract?.retry ?? options.retry;
-
-  // Circuit breakers are per-endpoint (host:port), so different endpoints
-  // can trip independently. Colocated calls share a single CB per service.
-  const cbOptions = contract?.circuitBreaker ?? options.circuitBreaker ?? {};
-  const MAX_ENDPOINT_CBS = 100;
-  /** @type {Map<string, CircuitBreaker>} endpoint string → CB instance */
-  const endpointCircuitBreakers = new Map();
-  // Shared CB for colocated (non-network) calls
-  const colocatedCircuitBreaker = new CircuitBreaker(cbOptions);
-
-  /**
-   * Get or create a circuit breaker for a specific endpoint.
-   * @param {string|null} endpointKey - e.g. "192.168.1.5:4001", or null for colocated
-   * @returns {CircuitBreaker}
-   */
-  function getCircuitBreaker(endpointKey) {
-    if (!endpointKey) return colocatedCircuitBreaker;
-    let cb = endpointCircuitBreakers.get(endpointKey);
-    if (!cb) {
-      // Cap to prevent unbounded growth
-      if (endpointCircuitBreakers.size >= MAX_ENDPOINT_CBS) {
-        // Evict the oldest entry
-        const firstKey = endpointCircuitBreakers.keys().next().value;
-        endpointCircuitBreakers.delete(firstKey);
-      }
-      cb = new CircuitBreaker(cbOptions);
-      endpointCircuitBreakers.set(endpointKey, cb);
-    }
-    return cb;
-  }
-
-  /** Remove a stale endpoint's CB */
-  function removeEndpointCB(endpointKey) {
-    endpointCircuitBreakers.delete(endpointKey);
-  }
-
-  if (contract) {
-    return buildContractProxy(
-      ctx,
-      targetName,
-      contract,
-      localInstance,
-      interceptors,
-      { getCircuitBreaker, removeEndpointCB, colocatedCircuitBreaker, endpointCircuitBreakers },
-      retryConfig,
-    );
-  }
-
-  return buildDynamicProxy(ctx, targetName, localInstance, interceptors, { getCircuitBreaker, removeEndpointCB, colocatedCircuitBreaker, endpointCircuitBreakers }, retryConfig);
-}
-
-/**
- * Build the interceptor chain for a proxy.
- *
- * Returns an array with a null placeholder at index 1 for the
- * per-attempt circuit breaker interceptor. This avoids allocating
- * a new array on every call — the caller just swaps slot [1].
- *
- * Layout: [deadline, CB_SLOT, concurrency, metrics?, logging]
- */
-function buildInterceptors(ctx, targetName, contract, options) {
-  const chain = [];
-
-  // Deadline propagation (always on)
-  const timeout = contract?.defaultTimeout ?? options.defaultTimeout ?? 5000;
-  chain.push(deadlineInterceptor(timeout));
-
-  // Slot [1] reserved for circuit breaker (swapped per-attempt)
-  chain.push(null);
-
-  // Bulkhead: limits concurrent outgoing calls per service
-  const bulkheadConfig = contract?.bulkhead ?? options.bulkhead ?? {};
-  chain.push(bulkheadInterceptor(bulkheadConfig));
-
-  // Adaptive concurrency limiting (always on for non-local services)
-  const concurrencyConfig = contract?.concurrency ?? options.concurrency ?? {};
-  const limiter = getConcurrencyLimiter(targetName, concurrencyConfig);
-  chain.push(concurrencyInterceptor(limiter));
-
-  // Metrics (always on if available)
-  if (ctx.metrics) {
-    chain.push(metricsInterceptor(ctx.metrics));
-  }
-
-  // Logging (debug level)
-  chain.push(loggingInterceptor(ctx.logger));
-
-  return chain;
-}
-
-/**
- * Adaptive concurrency interceptor.
- * Automatically wraps every proxy call with concurrency limiting.
- * No manual wrapping needed — it's invisible to the developer.
- */
-function concurrencyInterceptor(limiter) {
-  return async function adaptiveConcurrency(callCtx, next) {
-    const slot = limiter.tryAcquire();
-
-    if (!slot.acquired) {
-      const err = new Error(
-        `Service "${callCtx.target}" at concurrency limit (${limiter.limit}). ` +
-          `${limiter.inFlight} in flight. Rejecting ${callCtx.method}.`,
-      );
-      err.code = "CONCURRENCY_LIMIT";
-      err.statusCode = 503;
-      throw err;
-    }
-
-    try {
-      const result = await next();
-      slot.release(true);
-      return result;
-    } catch (err) {
-      slot.release(false);
-      throw err;
-    }
-  };
-}
-
-/**
- * Build a contract-based proxy with typed methods.
- */
-function buildContractProxy(
-  ctx,
-  targetName,
-  contract,
-  localInstance,
-  interceptors,
-  cbBag,
-  retryConfig,
-) {
-  const proxy = {};
-
-  for (const [methodName, meta] of contract.methods) {
-    proxy[methodName] = createProxiedMethod(
-      ctx,
-      targetName,
-      methodName,
-      meta,
-      localInstance,
-      contract,
-      interceptors,
-      cbBag,
-      retryConfig,
-    );
-  }
-
-  // Generic call method with private method guard, contract validation, and caching
-  const $callCache = new Map();
-  proxy.$call = (methodName, ...args) => {
-    if (typeof methodName !== 'string' || methodName.startsWith('_')) {
-      throw new Error(`Cannot call private method "${methodName}" via $call`);
-    }
-    if (contract && !contract.methods.has(methodName)) {
-      throw new Error(`Method "${methodName}" is not exposed on ${targetName}`);
-    }
-    evictOldest($callCache);
-    let fn = $callCache.get(methodName);
-    if (!fn) {
-      fn = createProxiedMethod(
-        ctx,
-        targetName,
-        methodName,
-        {},
-        localInstance,
-        contract,
-        interceptors,
-        cbBag,
-        retryConfig,
-      );
-      $callCache.set(methodName, fn);
-    }
-    return fn(...args);
-  };
-
-  // Invalidate method cache for hot-reload scenarios
-  proxy.$invalidate = () => {
-    $callCache.clear();
-    for (const key of Object.keys(proxy)) {
-      if (key.startsWith('$')) continue;
-      delete proxy[key];
-    }
-    // Re-create proxied methods from contract
-    for (const [methodName, meta] of contract.methods) {
-      proxy[methodName] = createProxiedMethod(
-        ctx, targetName, methodName, meta, localInstance, contract,
-        interceptors, cbBag, retryConfig,
-      );
-    }
-  };
-
-  // Metadata
-  proxy.$name = targetName;
-  proxy.$methods = [...contract.methods.keys()];
-  proxy.$isLocal = !!localInstance;
-  proxy.$circuitBreaker = cbBag.colocatedCircuitBreaker;
-  proxy.$endpointCircuitBreakers = cbBag.endpointCircuitBreakers;
-
-  return proxy;
-}
-
-/**
- * Build a dynamic proxy (no contract — any method name accepted).
- */
-function buildDynamicProxy(ctx, targetName, localInstance, interceptors, cbBag, retryConfig) {
-  const methodCache = new Map();
-  return new Proxy(
-    {},
-    {
-      get(_, methodName) {
-        if (methodName === "$name") return targetName;
-        if (methodName === "$isLocal") return !!localInstance;
-        if (methodName === "$circuitBreaker") return cbBag.colocatedCircuitBreaker;
-        if (methodName === "$endpointCircuitBreakers") return cbBag.endpointCircuitBreakers;
-        if (methodName === "$invalidate") return () => { methodCache.clear(); };
-        if (methodName === "then") return undefined;
-
-        evictOldest(methodCache);
-        if (methodCache.has(methodName)) return methodCache.get(methodName);
-        const fn = createProxiedMethod(
-          ctx,
-          targetName,
-          methodName,
-          {},
-          localInstance,
-          null,
-          interceptors,
-          cbBag,
-          retryConfig,
-        );
-        methodCache.set(methodName, fn);
-        return fn;
-      },
-    },
-  );
-}
-
-/**
- * Create a single proxied method with full interceptor + routing support.
- *
- * Retry is implemented as an outer loop around the interceptor chain so that
- * each attempt gets a fresh chain execution (deadline, circuit breaker,
- * metrics, logging all run on every attempt).
- */
-function createProxiedMethod(
-  ctx,
-  targetName,
-  methodName,
-  meta,
-  localInstance,
-  contract,
-  interceptors,
-  cbBag,
-  retryConfig,
-) {
-  // Resolve retry settings: per-method overrides service-level
-  const methodRetry = meta.options?.retry ?? retryConfig;
-  const retryDisabled = methodRetry === false;
-  const maxAttempts = retryDisabled ? 1 : (methodRetry?.maxAttempts ?? 3);
-  const baseDelayMs = retryDisabled ? 0 : (methodRetry?.baseDelayMs ?? 100);
-  const maxDelayMs = retryDisabled ? 0 : (methodRetry?.maxDelayMs ?? 2000);
-  const idempotent = meta.options?.idempotent;
-
-  return async (...args) => {
-    // Enforce localOnly: reject remote calls for methods marked localOnly
-    if (meta.options?.localOnly && !localInstance) {
-      throw new Error(`Method '${methodName}' on service '${targetName}' is marked localOnly and cannot be called remotely`);
-    }
-
-    // Capture the current RequestContext (from the calling service's request)
-    const rctx = RequestContext.current();
-
-    /** @type {CallContext} */
-    const callCtx = {
-      from: ctx.serviceName,
-      target: targetName,
-      method: methodName,
-      args,
-      deadline: rctx?.deadline ?? null,
-      timeout: meta.options?.timeout ?? 5000,
-      metadata: Object.create(null),
-      attempt: 0,
-      // Propagated context
-      correlationId: rctx?.correlationId ?? null,
-      traceId: rctx?.traceId ?? null,
-      auth: rctx?.auth ?? null,
-    };
-
-    const startTime = performance.now();
-    let lastError;
-
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      callCtx.attempt = attempt;
-
-      // Resolve endpoint ONCE per attempt — used for both circuit breaker
-      // selection and the actual HTTP call. This avoids round-robin advancing
-      // twice, which would cause circuit breaker state to accumulate against
-      // a different endpoint than the one actually called.
-      let endpointKey = null;
-      let resolvedEndpoint = null;
-      if (!localInstance) {
-        resolvedEndpoint = ctx._endpointResolver?.resolve(targetName) ?? null;
-        if (resolvedEndpoint) {
-          endpointKey = `${resolvedEndpoint.host}:${resolvedEndpoint.port}`;
-        } else {
-          const port = ctx._servicePorts?.[targetName];
-          if (port) endpointKey = `127.0.0.1:${port}`;
-        }
-        // COR-C1: Notify strategy of pending request (enables LeastPendingStrategy)
-        if (endpointKey && ctx._endpointResolver) {
-          ctx._endpointResolver.acquireEndpoint(targetName, endpointKey);
-        }
-      }
-      callCtx.resolvedEndpoint = resolvedEndpoint;
-      const circuitBreaker = cbBag.getCircuitBreaker(endpointKey);
-
-      // Abort early if circuit breaker is open and not yet ready for a probe
-      if (circuitBreaker.state === 'open' && Date.now() < circuitBreaker.nextAttemptTime) {
-        const err = new Error(
-          `Circuit breaker OPEN for ${targetName}.${methodName}` +
-            ` — service appears unavailable. Retry after ${new Date(circuitBreaker.nextAttemptTime).toISOString()}`,
-        );
-        err.code = 'CIRCUIT_OPEN';
-        throw err;
-      }
-
-      // Build per-attempt interceptor chain with the correct circuit breaker.
-      // Must copy because concurrent calls share the `interceptors` template —
-      // mutating slot [1] in-place would race with other in-flight chains.
-      const attemptChain = interceptors.slice();
-      attemptChain[1] = circuitBreaker.createInterceptor();
-
-      try {
-        const result = await runInterceptorChain(attemptChain, callCtx, async (finalCtx) => {
-          // === Colocated: direct function call with context propagation ===
-          if (localInstance) {
-            // Validate method is exposed in the contract (prevents calling private methods via colocated dispatch)
-            if (contract && !contract.methods.has(methodName)) {
-              throw new Error(`Method '${methodName}' is not exposed on service '${targetName}'`);
-            }
-
-            const method = localInstance.service[methodName];
-            if (typeof method === "function") {
-              const callFn = () => {
-                if (rctx) {
-                  const childCtx = rctx.child(targetName, methodName);
-                  if (finalCtx.deadline) childCtx.deadline = finalCtx.deadline;
-                  return RequestContext.run(childCtx, () => method.apply(localInstance.service, args));
-                }
-                return method.apply(localInstance.service, args);
-              };
-
-              if (finalCtx.deadline) {
-                const timeLeft = finalCtx.deadline - Date.now();
-                if (timeLeft <= 0) throw new Error(`Deadline exceeded for ${targetName}.${methodName}`);
-                let timer = null;
-                const timeoutPromise = new Promise((_, reject) => {
-                  timer = setTimeout(() => reject(new Error(`Deadline exceeded for colocated call ${targetName}.${methodName}`)), timeLeft);
-                });
-                return Promise.race([callFn(), timeoutPromise]).finally(() => { if (timer) clearTimeout(timer); });
-              }
-              return callFn();
-            }
-            throw new Error(`${targetName} has no method "${methodName}"`);
-          }
-
-          // === Remote: HTTP invoke when endpoint is known, otherwise IPC request fallback ===
-          // Calculate effective timeout respecting deadline.
-          let effectiveTimeout = finalCtx.timeout ?? 5000;
-          if (finalCtx.deadline) {
-            const remaining = finalCtx.deadline - Date.now();
-            if (remaining <= 0) throw new Error(`Deadline exceeded for ${targetName}.${methodName}`);
-            effectiveTimeout = Math.min(effectiveTimeout, remaining);
-          }
-
-          let targetHost = "127.0.0.1";
-          let targetPort;
-
-          // Use the endpoint resolved once at the top of this attempt
-          // (stored in callCtx) to avoid double round-robin advancement.
-          const endpoint = finalCtx.resolvedEndpoint;
-          if (endpoint) {
-            targetHost = endpoint.host;
-            targetPort = endpoint.port;
-          } else {
-            targetPort = ctx._servicePorts?.[targetName];
-          }
-
-          if (!targetPort) {
-            // Internal/background services may not expose HTTP ports. Use IPC request path.
-            if (typeof ctx.request === "function") {
-              const payload = {
-                __forge_method: methodName,
-                __forge_args: args,
-              };
-              if (finalCtx.deadline) {
-                payload.__forge_deadline = finalCtx.deadline;
-              }
-              return ctx.request(targetName, payload, effectiveTimeout);
-            }
-            throw new Error(
-              `No endpoint known for service "${targetName}". ` +
-                `Check that it's listed in forge.config and has a port.`,
-            );
-          }
-
-          const headers = { "Content-Type": "application/json" };
-
-          if (rctx) {
-            Object.assign(headers, rctx.toHeaders());
-            // Override deadline with remaining time from callCtx (shrinks on retry)
-            if (finalCtx.deadline) {
-              const remaining = finalCtx.deadline - Date.now();
-              if (remaining <= 0) {
-                throw new Error(`Deadline exceeded for ${targetName}.${methodName}`);
-              }
-              headers["x-forge-deadline"] = String(remaining);
-            }
-          }
-
-          const resp = await fetch(`http://${targetHost}:${targetPort}/__forge/invoke`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({
-              method: methodName,
-              args,
-            }),
-            signal: AbortSignal.timeout(effectiveTimeout),
-          });
-
-          // M-11: Enforce response body size limit to prevent OOM from oversized responses
-          const contentLength = resp.headers.get('content-length');
-          if (contentLength && parseInt(contentLength, 10) > 10 * 1024 * 1024) {
-            throw new Error(`Response from ${targetHost}:${targetPort} exceeds 10MB limit`);
-          }
-          const data = await resp.json();
-          if (data.error) {
-            const err = new Error(data.error);
-            err.statusCode = resp.status;
-            throw err;
-          }
-
-          return data.result;
-        });
-
-        return result;
-      } catch (err) {
-        lastError = err;
-
-        // Never retry circuit-open errors — the breaker is tripped
-        if (err.code === 'CIRCUIT_OPEN') {
-          throw err;
-        }
-
-        if (!isRetryable(err, idempotent) || attempt >= maxAttempts - 1) {
-          throw err;
-        }
-
-        // Check deadline before retrying
-        if (callCtx.deadline && Date.now() >= callCtx.deadline) {
-          throw new Error(`Deadline exceeded after ${attempt + 1} attempts to ${callCtx.target}.${callCtx.method}`);
-        }
-
-        // Exponential backoff with jitter, capped to remaining deadline
-        let delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt + Math.random() * 100);
-        if (callCtx.deadline) {
-          const timeLeft = callCtx.deadline - Date.now();
-          if (timeLeft <= 0) {
-            throw new Error(`Deadline exceeded after ${attempt + 1} attempts to ${callCtx.target}.${callCtx.method}`);
-          }
-          delay = Math.min(delay, timeLeft);
-        }
-
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      } finally {
-        // COR-C1: Release pending slot so LeastPendingStrategy sees accurate counts
-        if (!localInstance && endpointKey && ctx._endpointResolver) {
-          ctx._endpointResolver.releaseEndpoint(targetName, endpointKey);
-        }
-      }
-    }
-
-    throw lastError;
-  };
-}
-
-// ─── Request Handler (receiving side) ───────────────────────
-
-/**
- * Handle an incoming proxy-style RPC request on the receiving service.
- *
- * Detects the __forge_method convention, checks deadlines,
- * validates the method is exposed, and dispatches.
- */
-export function handleProxyRequest(service, from, payload) {
-  if (payload?.__forge_method) {
-    const methodName = payload.__forge_method;
-    const args = payload.__forge_args ?? [];
-
-    // Check deadline propagation (value is an absolute timestamp in ms)
-    let absoluteDeadline = null;
-    if (payload.__forge_deadline) {
-      absoluteDeadline = Number(payload.__forge_deadline);
-      const remaining = absoluteDeadline - Date.now();
-      if (remaining <= 0) {
-        throw new Error(`Deadline already exceeded for ${service.ctx?.serviceName}.${methodName}` + ` (caller: ${from})`);
-      }
-    }
-
-    // Contract/whitelist check first — reject unexposed methods before probing internals
-    const contract = getContract(service.constructor);
-    if (contract && !contract.methods.has(methodName)) {
-      throw new Error(`Method "${methodName}" is not exposed on this service`);
-    }
-
-    // Reject private methods when there is no contract to gate access
-    if (!contract && methodName.startsWith('_')) {
-      throw new Error(`Method "${methodName}" is private and cannot be invoked remotely`);
-    }
-
-    const method = service[methodName];
-    if (typeof method !== "function") {
-      throw new Error(
-        `Service "${service.ctx?.serviceName}" has no method "${methodName}". ` +
-          `Available: ${getExposedMethods(service).join(", ") || "none"}`,
-      );
-    }
-
-    // Enforce deadline during execution if set
-    if (absoluteDeadline) {
-      const remaining = absoluteDeadline - Date.now();
-      if (remaining <= 0) {
-        throw new Error(`Deadline already exceeded for ${service.ctx?.serviceName}.${methodName} (caller: ${from})`);
-      }
-      let timer = null;
-      const timeoutPromise = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error('Deadline exceeded during execution')), remaining);
-        if (timer) timer.unref();
-      });
-      // Re-check deadline immediately before race to close the window
-      const currentRemaining = absoluteDeadline - Date.now();
-      if (currentRemaining <= 0) {
-        clearTimeout(timer);
-        throw new Error('Deadline exceeded before execution start');
-      }
-      return Promise.race([method.apply(service, args), timeoutPromise]).finally(() => { if (timer) clearTimeout(timer); });
-    }
-
-    return method.apply(service, args);
-  }
-
-  return NOT_HANDLED;
-}
-
-function getExposedMethods(service) {
-  const contract = getContract(service.constructor);
-  if (contract) return [...contract.methods.keys()];
-
-  return Object.getOwnPropertyNames(Object.getPrototypeOf(service)).filter(
-    (m) => m !== "constructor" && !m.startsWith("_") && typeof service[m] === "function",
-  );
-}
-
-/**
- * Auto-register HTTP routes from @Route decorator / contract metadata.
- *
- * For every route declared via `@Route(method, path)` or the plain-JS
- * `static contract = { routes: [...] }`, this function registers the
- * corresponding handler on the service's HTTP router.
- *
- * **Contract route handler signature:**
- *
- *   async handler(body, params, query) -> result
- *
- * - `body`   — parsed request body (`req.body`)
- * - `params` — URL path parameters (`req.params`), e.g. `{ id: '42' }` for `/users/:id`
- * - `query`  — query-string parameters (`req.query`), e.g. `{ page: '2' }`
- * - Return value is automatically serialized as JSON via `res.json(result)`.
- *   POST routes respond with 201; all other methods respond with 200.
- *   Errors are caught and returned as `{ error: message }` with 404 (if the
- *   message contains "not found") or 500.
- *
- * **How this differs from manual `ctx.router` routes:**
- *
- * When you register routes manually in `onStart(ctx)`, the handler receives
- * the raw `(req, res)` pair and you are responsible for sending the response:
- *
- *   ctx.router.get('/health', (req, res) => {
- *     res.json({ ok: true });
- *   });
- *
- * Contract-based handlers are higher-level: the framework supplies the
- * individual pieces of the request as arguments and handles serialization
- * and status codes for you.
- *
- * @example
- * // ── Contract / decorator approach ──────────────────────
- * // Handler receives (body, params, query) and returns a value.
- *
- * class UserService extends Service {
- *   @Expose()
- *   @Route('GET', '/users/:id')
- *   async getUser(body, params, query) {
- *     return this.db.findUser(params.id);  // auto-serialized, 200 OK
- *   }
- *
- *   @Expose()
- *   @Route('POST', '/users')
- *   async createUser(body, params, query) {
- *     return this.db.insert(body);         // auto-serialized, 201 Created
- *   }
- * }
- *
- * // ── Manual approach (in onStart) ──────────────────────
- * // Handler receives (req, res) and must call res.json() itself.
- *
- * async onStart(ctx) {
- *   ctx.router.get('/users/:id', async (req, res) => {
- *     const user = await this.db.findUser(req.params.id);
- *     res.json(user);                      // you choose the status code
- *   });
- * }
- *
- * @param {Service} service - The service instance whose routes to register
- * @param {ForgeContext} ctx - The service's ForgeContext (must be type 'edge')
- */
-export function autoRegisterRoutes(service, ctx) {
-  const contract = getContract(service.constructor);
-  if (!contract || contract.routes.length === 0) return;
-
-  for (const route of contract.routes) {
-    const handler = service[route.handlerName];
-    if (typeof handler !== "function") {
-      throw new Error(`Route handler "${route.handlerName}" not found on service`);
-    }
-
-    if (ctx.serviceType === "edge") {
-      const method = route.httpMethod.toLowerCase();
-      const routeRateLimit = route.rateLimit ? parseRateLimit(route.rateLimit) : null;
-      const routeKey = `${method}:${route.path}`;
-
-      ctx.router[method](route.path, async (req, res) => {
-        const rctx = req.ctx ?? (req.headers ? RequestContext.fromPropagation(req.headers) : new RequestContext());
-
-        // @Auth enforcement -- defense-in-depth even without ForgeProxy
-        if (route.auth) {
-          if (!rctx.auth) {
-            res.json({ error: "Authentication required" }, 401);
-            return;
-          }
-          if (Array.isArray(route.auth.roles) && route.auth.roles.length > 0) {
-            if (!route.auth.roles.includes(rctx.auth.role)) {
-              res.json({ error: "Insufficient permissions" }, 403);
-              return;
-            }
-          }
-        }
-
-        // @RateLimit enforcement -- per-route, per-IP token bucket
-        if (routeRateLimit) {
-          const rawAddr = req.socket?.remoteAddress ?? "";
-          let ip;
-          // Trust X-Forwarded-For only from explicitly trusted proxies (FORGE_TRUSTED_PROXIES),
-          // or fall back to any private network if FORGE_TRUSTED_PROXIES is not configured.
-          const trustXff = process.env.FORGE_TRUSTED_PROXIES
-            ? isTrustedProxy(rawAddr)
-            : isPrivateNetwork(rawAddr);
-          if (trustXff) {
-            ip = req.headers?.["x-forwarded-for"]?.split(",")[0]?.trim() || rawAddr;
-          } else {
-            ip = rawAddr || "unknown";
-          }
-          if (!checkRateLimit(routeKey, ip, routeRateLimit)) {
-            res.json({ error: "Rate limit exceeded" }, 429);
-            return;
-          }
-        }
-
-        await RequestContext.run(rctx, async () => {
-          try {
-            const result = await handler.call(service, req.body, req.params, req.query);
-            const statusCode = route.httpMethod === "POST" ? 201 : 200;
-            res.json(result, statusCode);
-          } catch (err) {
-            let message;
-            let code;
-
-            if (err == null) {
-              message = "Unknown error";
-              code = 500;
-            } else if (typeof err === 'string') {
-              message = err;
-              code = 500;
-            } else {
-              message = err.message ?? "Unknown error";
-              if (err.statusCode) {
-                code = err.statusCode;
-              } else if (message.toLowerCase().includes("not found")) {
-                code = 404;
-              } else {
-                code = 500;
-              }
-            }
-
-            // Don't leak internals on 5xx errors
-            if (code >= 500) {
-              res.json({ error: "Internal server error" }, code);
-            } else {
-              res.json({ error: message }, code);
-            }
-          }
-        });
-      });
-    }
-  }
-}
-
-/**
- * Auto-wire event subscriptions from @On decorators.
- */
-export function autoWireSubscriptions(service, _ctx) {
-  if (_WIRED_SERVICES.has(service)) return; // Prevent double-wrapping on hot reload
-
-  const contract = getContract(service.constructor);
-  if (!contract || contract.subscriptions.length === 0) return;
-
-  _WIRED_SERVICES.add(service);
-  const originalOnMessage = service.onMessage.bind(service);
-
-  service.onMessage = async (from, payload) => {
-    if (payload?.__forge_event) {
-      for (const sub of contract.subscriptions) {
-        if (sub.service === from && sub.event === payload.__forge_event) {
-          const handler = service[sub.handlerName];
-          if (handler) await handler.call(service, payload.__forge_data);
-        }
-      }
-      return;
-    }
-    return originalOnMessage(from, payload);
-  };
-}