threadforge 0.1.0

package/src/decorators/ServiceProxy.js

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