threadforge 0.1.1 → 0.2.1

package/dist/decorators/ServiceProxy.js

@@ -0,0 +1,969 @@
+/**
+ * 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 { createHmac } from "node:crypto";
+import http from "node:http";
+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 { createStrategy } from "../core/RoutingStrategy.js";
+import { resolveRpcOptionsForTarget } from "../core/RpcConfig.js";
+import { createSignatureCacheFromEnv } from "../core/SignatureCache.js";
+import { getContract } from "./index.js";
+const DEFAULT_MAX_SOCKETS = 256;
+const DEFAULT_MAX_SOCKETS_PER_HOST = 64;
+const DEFAULT_KEEPALIVE_MS = 30_000;
+let _rpcAgent = null;
+/**
+ * Get or create the shared HTTP agent for remote RPC connections.
+ * Uses connection pooling with keepalive to avoid per-request TCP setup.
+ */
+export function _getRpcAgent(config) {
+    if (_rpcAgent)
+        return _rpcAgent;
+    const maxSockets = config?.maxSockets
+        ?? (parseInt(process.env.FORGE_RPC_MAX_SOCKETS || "", 10)
+            || DEFAULT_MAX_SOCKETS);
+    const maxSocketsPerHost = config?.maxSocketsPerHost
+        ?? (parseInt(process.env.FORGE_RPC_MAX_SOCKETS_PER_HOST || "", 10)
+            || DEFAULT_MAX_SOCKETS_PER_HOST);
+    const keepAliveMs = config?.keepAliveMs
+        ?? (parseInt(process.env.FORGE_RPC_KEEPALIVE_MS || "", 10)
+            || DEFAULT_KEEPALIVE_MS);
+    _rpcAgent = new http.Agent({
+        keepAlive: true,
+        keepAliveMsecs: keepAliveMs,
+        maxSockets: maxSocketsPerHost,
+        maxTotalSockets: maxSockets,
+    });
+    return _rpcAgent;
+}
+/**
+ * Destroy the shared RPC agent (for test teardown / graceful shutdown).
+ */
+export function _destroyRpcAgent() {
+    if (_rpcAgent) {
+        _rpcAgent.destroy();
+        _rpcAgent = null;
+    }
+}
+// ─── Module state ───────────────────────────────────────────
+const _WIRED_SERVICES = new WeakSet();
+// P-PERF-29: Global signature cache for internal RPC optimization
+let _signatureCache = null;
+/**
+ * Initialize the signature cache from environment variables.
+ * Called once on module load.
+ */
+function _initSignatureCache() {
+    if (_signatureCache)
+        return;
+    _signatureCache = createSignatureCacheFromEnv();
+    if (_signatureCache?.isEnabled()) {
+        console.log("[ThreadForge] Signature caching enabled for internal RPC (FORGE_CACHE_SIGNATURES=true)");
+    }
+}
+// Initialize signature cache on module load
+_initSignatureCache();
+/**
+ * Get or compute a signature for internal RPC.
+ * Uses the cache if enabled, otherwise computes per-request.
+ */
+function _getInternalSignature() {
+    const internalSecret = process.env.FORGE_INTERNAL_SECRET;
+    if (!internalSecret) {
+        throw new Error("FORGE_INTERNAL_SECRET not set");
+    }
+    if (_signatureCache && _signatureCache.isEnabled()) {
+        return _signatureCache.getSignature("POST", "/__forge/invoke");
+    }
+    // Fallback: compute per-request (original behavior)
+    const ts = String(Date.now());
+    const sig = createHmac("sha256", internalSecret).update(`POST:/__forge/invoke:${ts}`).digest("hex");
+    return { signature: sig, timestamp: ts };
+}
+/**
+ * Stop the signature cache (for cleanup/testing).
+ */
+export function _stopSignatureCache() {
+    if (_signatureCache) {
+        _signatureCache.stop();
+        _signatureCache = null;
+    }
+}
+// ─── 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;
+let _rateLimitCleanupTimer = null;
+function _rateLimitCleanupFn() {
+    const now = Date.now();
+    for (const [key, bucket] of _rateLimitBuckets) {
+        if (now - bucket.windowStart > 120_000) {
+            _rateLimitBuckets.delete(key);
+        }
+    }
+}
+/** Start (or restart) the periodic rate-limit bucket cleanup timer. */
+export function _startRateLimitCleanup() {
+    if (_rateLimitCleanupTimer)
+        return;
+    _rateLimitCleanupTimer = setInterval(_rateLimitCleanupFn, 60_000);
+    if (_rateLimitCleanupTimer && typeof _rateLimitCleanupTimer === "object" && "unref" in _rateLimitCleanupTimer) {
+        _rateLimitCleanupTimer.unref();
+    }
+}
+/** Stop the periodic rate-limit bucket cleanup timer (for test teardown). */
+export function _stopRateLimitCleanup() {
+    if (_rateLimitCleanupTimer) {
+        clearInterval(_rateLimitCleanupTimer);
+        _rateLimitCleanupTimer = null;
+    }
+}
+// Auto-start the cleanup timer on module load
+_startRateLimitCleanup();
+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.
+ */
+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.
+ */
+export function buildServiceProxies(ctx, serviceClasses, localServices = new Map(), options = {}) {
+    const proxies = {};
+    const { rpcConfig, ...baseOptions } = options;
+    // Ensure the shared RPC connection pool is initialized
+    _getRpcAgent(options.pool);
+    for (const [serviceName, ServiceClass] of serviceClasses) {
+        if (serviceName === ctx.serviceName)
+            continue;
+        const contract = getContract(ServiceClass);
+        // Resolve per-target RPC options and merge into proxy options
+        const targetRpcOptions = resolveRpcOptionsForTarget(rpcConfig, serviceName);
+        const mergedOptions = {
+            ...baseOptions,
+            ...targetRpcOptions,
+        };
+        proxies[serviceName] = createServiceProxy(ctx, serviceName, contract, localServices.get(serviceName) ?? null, mergedOptions);
+    }
+    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, createStrategy(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;
+    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.
+     */
+    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;
+                if (firstKey !== undefined) {
+                    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;
+            err.localAdmission = true;
+            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) {
+            const methodMeta = contract?.methods.get(methodName) ?? { name: methodName, options: {} };
+            fn = createProxiedMethod(ctx, targetName, methodName, methodMeta, 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 metaOptions = meta.options;
+    const methodRetry = metaOptions?.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 = metaOptions?.idempotent;
+    return async (...args) => {
+        // Enforce localOnly: reject remote calls for methods marked localOnly
+        if (metaOptions?.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();
+        const callCtx = {
+            from: ctx.serviceName,
+            target: targetName,
+            method: methodName,
+            args,
+            deadline: rctx?.deadline ?? null,
+            timeout: metaOptions?.timeout ?? 5000,
+            metadata: Object.create(null),
+            attempt: 0,
+            // Flag for interceptor chain: colocated calls skip circuit breaker + bulkhead
+            isColocated: !!localInstance,
+            // Propagated context
+            correlationId: rctx?.correlationId ?? null,
+            traceId: rctx?.traceId ?? null,
+            auth: rctx?.auth ?? null,
+        };
+        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) {
+                const resolved = ctx._endpointResolver?.resolve(targetName) ?? null;
+                // RT-C2: Handle broadcast strategy returning all endpoints
+                if (Array.isArray(resolved) && resolved.length > 0) {
+                    resolvedEndpoint = resolved[0];
+                    // Fan out to all endpoints, return first successful response
+                    const broadcastPromises = resolved.map(async (ep) => {
+                        const headers = { "Content-Type": "application/json" };
+                        const rctx = RequestContext.current();
+                        if (rctx)
+                            Object.assign(headers, rctx.toHeaders());
+                        const internalSecret = process.env.FORGE_INTERNAL_SECRET;
+                        if (internalSecret) {
+                            const { signature: sig, timestamp: ts } = _getInternalSignature();
+                            headers["x-forge-internal-sig"] = sig;
+                            headers["x-forge-internal-ts"] = ts;
+                        }
+                        const resp = await fetch(`http://${ep.host}:${ep.port}/__forge/invoke`, {
+                            method: "POST",
+                            headers,
+                            body: JSON.stringify({ method: methodName, args }),
+                            signal: AbortSignal.timeout(callCtx.timeout ?? 5000),
+                            keepalive: true,
+                        });
+                        const data = (await resp.json());
+                        if (data.error)
+                            throw new Error(data.error);
+                        return data.result;
+                    });
+                    return Promise.any(broadcastPromises);
+                }
+                resolvedEndpoint = Array.isArray(resolved) ? null : resolved;
+                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();
+            let targetHost = "127.0.0.1";
+            let targetPort;
+            try {
+                const result = await runInterceptorChain(attemptChain, callCtx, async (finalCtx) => {
+                    const extCtx = 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 (extCtx.deadline)
+                                        childCtx.deadline = extCtx.deadline;
+                                    return RequestContext.run(childCtx, () => method.apply(localInstance.service, args));
+                                }
+                                return method.apply(localInstance.service, args);
+                            };
+                            if (extCtx.deadline) {
+                                const timeLeft = extCtx.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 = extCtx.timeout ?? 5000;
+                    if (extCtx.deadline) {
+                        const remaining = extCtx.deadline - Date.now();
+                        if (remaining <= 0)
+                            throw new Error(`Deadline exceeded for ${targetName}.${methodName}`);
+                        effectiveTimeout = Math.min(effectiveTimeout, remaining);
+                    }
+                    targetHost = "127.0.0.1";
+                    targetPort = undefined;
+                    // Use the endpoint resolved once at the top of this attempt
+                    // (stored in callCtx) to avoid double round-robin advancement.
+                    const endpoint = extCtx.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 (extCtx.deadline) {
+                                payload.__forge_deadline = extCtx.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 (extCtx.deadline) {
+                            const remaining = extCtx.deadline - Date.now();
+                            if (remaining <= 0) {
+                                throw new Error(`Deadline exceeded for ${targetName}.${methodName}`);
+                            }
+                            headers["x-forge-deadline"] = String(remaining);
+                        }
+                    }
+                    // P-PERF-29: Sign request with HMAC (uses cache if enabled)
+                    const internalSecret = process.env.FORGE_INTERNAL_SECRET;
+                    if (internalSecret) {
+                        const { signature: sig, timestamp: ts } = _getInternalSignature();
+                        headers["x-forge-internal-sig"] = sig;
+                        headers["x-forge-internal-ts"] = ts;
+                    }
+                    const resp = await fetch(`http://${targetHost}:${targetPort}/__forge/invoke`, {
+                        method: "POST",
+                        headers,
+                        body: JSON.stringify({
+                            method: methodName,
+                            args,
+                        }),
+                        signal: AbortSignal.timeout(effectiveTimeout),
+                        keepalive: true,
+                    });
+                    // M-11: Enforce response body size limit to prevent OOM from oversized responses
+                    const MAX_RESPONSE_SIZE = 10 * 1024 * 1024;
+                    const contentLength = resp.headers.get("content-length");
+                    if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_SIZE) {
+                        throw new Error(`Response from ${targetHost}:${targetPort} exceeds 10MB limit`);
+                    }
+                    // DEC-M4: Stream body with size limit to guard against chunked transfers without Content-Length
+                    const reader = resp.body?.getReader();
+                    if (!reader) {
+                        throw new Error(`No response body from ${targetHost}:${targetPort}`);
+                    }
+                    const chunks = [];
+                    let totalSize = 0;
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        totalSize += value.byteLength;
+                        if (totalSize > MAX_RESPONSE_SIZE) {
+                            reader.cancel();
+                            throw new Error(`Response from ${targetHost}:${targetPort} exceeds 10MB limit`);
+                        }
+                        chunks.push(value);
+                    }
+                    const bodyText = new TextDecoder().decode(chunks.length === 1 ? chunks[0] : Buffer.concat(chunks));
+                    const data = JSON.parse(bodyText);
+                    if (data.error) {
+                        const err = new Error(data.error);
+                        err.statusCode = resp.status;
+                        if (typeof data.code === "string") {
+                            err.code = data.code;
+                            if (data.code === "CONCURRENCY_LIMIT" || data.code === "BULKHEAD_FULL") {
+                                err.localAdmission = true;
+                            }
+                        }
+                        throw err;
+                    }
+                    // REG-M2: Record success to reset failure counter
+                    if (targetHost && targetPort && ctx._endpointResolver) {
+                        ctx._endpointResolver.recordSuccess(targetHost, targetPort);
+                    }
+                    return data.result;
+                });
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                // REG-M2: Record connection failures for passive health checking
+                if (targetHost && targetPort && ctx._endpointResolver) {
+                    const errCode = err.code;
+                    if (errCode === "ECONNREFUSED" || errCode === "ECONNRESET" || errCode === "ETIMEDOUT" || errCode === "UND_ERR_CONNECT_TIMEOUT") {
+                        ctx._endpointResolver.recordFailure(targetHost, targetPort);
+                    }
+                }
+                // 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}`);
+                }
+                // INT-M2: Full jitter per AWS best practice: random(0, min(maxDelay, base * 2^attempt))
+                let delay = Math.random() * Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+                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
+ *   });
+ * }
+ */
+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;
+                    }
+                    // DEC-H1: Support role-based auth — auth string format "required:role1,role2"
+                    if (typeof route.auth === "string" && route.auth.includes(":")) {
+                        const roles = route.auth
+                            .split(":")[1]
+                            ?.split(",")
+                            .map((r) => r.trim())
+                            .filter(Boolean) ?? [];
+                        if (roles.length > 0 && !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 (typeof handler === "function") {
+                        try {
+                            await handler.call(service, payload.__forge_data);
+                        }
+                        catch (err) {
+                            _ctx?.logger?.error?.(`Subscription handler ${sub.handlerName} failed for event ${sub.event}: ${err.message}`);
+                        }
+                    }
+                }
+            }
+            return;
+        }
+        return originalOnMessage(from, payload);
+    };
+}
+//# sourceMappingURL=ServiceProxy.js.map