threadforge 0.1.1 → 0.2.1

package/dist/core/RoutingStrategy.js

@@ -0,0 +1,306 @@
+/**
+ * Routing Strategies
+ *
+ * When a service has multiple workers, the proxy needs to decide
+ * which worker handles each request. Different strategies suit
+ * different service patterns.
+ *
+ * Strategies:
+ *
+ *   round-robin     Default. Cycles through workers sequentially.
+ *                   Best for: stateless services, uniform workloads.
+ *
+ *   hash            Routes by a key (e.g., userId). Same key always
+ *                   goes to the same worker. Uses consistent hashing
+ *                   so adding/removing workers only remaps ~1/N keys.
+ *                   Best for: stateful services, in-memory caches,
+ *                   services that benefit from data locality.
+ *
+ *   least-pending   Routes to the worker with fewest in-flight requests.
+ *                   Best for: variable-latency services (DB queries,
+ *                   external API calls).
+ *
+ *   broadcast       Sends to ALL workers. Returns the first response.
+ *                   Best for: search/aggregation across sharded data.
+ *
+ *   primary         Always routes to worker 0. Others are standbys.
+ *                   Best for: singleton services (cron scheduler,
+ *                   leader election).
+ */
+import { createHmac, randomBytes } from "node:crypto";
+import { ROUTING_STRATEGY_NAMES, } from "./config-enums.js";
+// RT-L1: Allow configurable salt via FORGE_HASH_SALT for cross-restart consistency
+const HASH_SALT = process.env.FORGE_HASH_SALT || randomBytes(16).toString("hex");
+// P-1: Fast non-cryptographic FNV-1a hash for runtime routing.
+// HMAC-SHA256 is ~100x slower and unnecessary for load distribution.
+function fnv1a(str) {
+    let hash = 0x811c9dc5 | 0; // FNV offset basis
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = (hash * 0x01000193) | 0; // FNV prime
+    }
+    return hash >>> 0; // Convert to unsigned 32-bit
+}
+// ─── Round-Robin ────────────────────────────────────────────
+export class RoundRobinStrategy {
+    index;
+    constructor() {
+        this.index = 0;
+    }
+    pick(workers, _callContext) {
+        if (workers.length === 0)
+            return null;
+        const worker = workers[this.index % workers.length];
+        this.index = (this.index + 1) % 1_000_000_000;
+        return worker;
+    }
+    get name() {
+        return "round-robin";
+    }
+}
+// ─── Hash-Based (Consistent Hashing) ────────────────────────
+export class HashStrategy {
+    keyField;
+    vnodes;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: used as ring-built sentinel at runtime
+    _ring;
+    _workerCacheKey;
+    _ringHashes;
+    _ringKeys;
+    _fallbackCounter;
+    _salt;
+    constructor(options = {}) {
+        this.keyField = options.key ?? null;
+        this.vnodes = options.vnodes ?? 150;
+        this._ring = null;
+        this._workerCacheKey = "";
+        this._fallbackCounter = 0;
+        // RT-L1: Allow per-instance salt override for cross-restart consistency
+        this._salt = options.salt ?? HASH_SALT;
+    }
+    pick(workers, callContext) {
+        if (workers.length === 0)
+            return null;
+        if (workers.length === 1)
+            return workers[0];
+        // Extract the hash key from the call context
+        const hashKey = this._extractKey(callContext ?? null);
+        if (!hashKey) {
+            // No key available — fall back to counter-based round-robin
+            const idx = this._fallbackCounter % workers.length;
+            this._fallbackCounter = (this._fallbackCounter + 1) % 1_000_000_000;
+            return workers[idx];
+        }
+        // Rebuild ring when worker identities change (not just count).
+        // This ensures the ring is correct when workers restart with new keys.
+        const currentCacheKey = workers
+            .map((w) => w.key)
+            .sort()
+            .join(",");
+        if (this._workerCacheKey !== currentCacheKey) {
+            this._buildRing(workers);
+        }
+        // Find the worker on the ring
+        const hash = this._simpleHash(hashKey);
+        return this._findOnRing(hash, workers);
+    }
+    _extractKey(callContext) {
+        if (!callContext)
+            return null;
+        // If a key field is specified, look for it in the call args
+        if (this.keyField) {
+            const args = callContext.__forge_args ?? [];
+            // Check first arg (usually the main parameter)
+            if (args.length > 0) {
+                if (typeof args[0] === "string" || typeof args[0] === "number") {
+                    return String(args[0]);
+                }
+                if (typeof args[0] === "object" && args[0] !== null && args[0][this.keyField]) {
+                    return String(args[0][this.keyField]);
+                }
+            }
+        }
+        // Try to use __forge_hash if explicitly set by the caller
+        if (callContext.__forge_hash) {
+            return String(callContext.__forge_hash);
+        }
+        return null;
+    }
+    _buildRing(workers) {
+        // P5: Pre-compute all virtual node hashes and store sorted for binary search
+        const totalNodes = workers.length * this.vnodes;
+        const hashes = new Uint32Array(totalNodes);
+        // RT-H3: Store worker keys instead of positional indices to avoid
+        // incorrect mapping when the workers array arrives in a different order.
+        const keys = new Array(totalNodes);
+        let pos = 0;
+        for (let i = 0; i < workers.length; i++) {
+            for (let v = 0; v < this.vnodes; v++) {
+                hashes[pos] = this._computeHash(`${workers[i].key}:${v}`);
+                keys[pos] = workers[i].key;
+                pos++;
+            }
+        }
+        // Sort by hash value, keeping keys aligned
+        const sortOrder = Array.from({ length: totalNodes }, (_, i) => i);
+        sortOrder.sort((a, b) => hashes[a] - hashes[b]);
+        this._ringHashes = new Uint32Array(totalNodes);
+        this._ringKeys = new Array(totalNodes);
+        for (let i = 0; i < totalNodes; i++) {
+            this._ringHashes[i] = hashes[sortOrder[i]];
+            this._ringKeys[i] = keys[sortOrder[i]];
+        }
+        this._ring = true; // sentinel
+        this._workerCacheKey = workers
+            .map((w) => w.key)
+            .sort()
+            .join(",");
+    }
+    _findOnRing(hash, workers) {
+        const hashes = this._ringHashes;
+        // Binary search for the first ring entry >= hash
+        let lo = 0, hi = hashes.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (hashes[mid] < hash)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        // Wrap around
+        const idx = lo < hashes.length ? lo : 0;
+        // RT-H3: Look up worker by key instead of positional index
+        const targetKey = this._ringKeys[idx];
+        return workers.find((w) => w.key === targetKey) ?? workers[0];
+    }
+    /**
+     * Pre-compute a keyed SHA-256 hash for ring building (called at build time).
+     */
+    _computeHash(str) {
+        return createHmac("sha256", this._salt).update(str).digest().readUInt32BE(0);
+    }
+    /**
+     * P-1: Fast FNV-1a hash for runtime routing decisions.
+     * Salted to prevent predictable distribution from external input.
+     */
+    _simpleHash(str) {
+        return fnv1a(this._salt + str);
+    }
+    get name() {
+        return `hash(${this.keyField ?? "auto"})`;
+    }
+}
+// ─── Least-Pending ──────────────────────────────────────────
+export class LeastPendingStrategy {
+    _pending;
+    // RT-M1: Track worker identity set (not just count) for accurate pruning
+    _lastWorkerKeys;
+    constructor() {
+        this._pending = new Map();
+        this._lastWorkerKeys = "";
+    }
+    /**
+     * Pick the worker with the fewest in-flight requests.
+     */
+    pick(workers, _callContext) {
+        if (workers.length === 0)
+            return null;
+        if (workers.length === 1)
+            return workers[0];
+        // RT-M1: Prune when worker identity set changes (handles replacements at same count)
+        const currentKeys = workers.map((w) => w.key).sort().join(",");
+        if (this._pending.size > 0 && currentKeys !== this._lastWorkerKeys) {
+            const activeKeys = new Set(workers.map((w) => w.key));
+            for (const key of this._pending.keys()) {
+                if (!activeKeys.has(key)) {
+                    this._pending.delete(key);
+                }
+            }
+        }
+        this._lastWorkerKeys = currentKeys;
+        let best = workers[0];
+        let bestPending = this._pending.get(best.key) ?? 0;
+        for (let i = 1; i < workers.length; i++) {
+            const p = this._pending.get(workers[i].key) ?? 0;
+            if (p < bestPending) {
+                best = workers[i];
+                bestPending = p;
+            }
+        }
+        return best;
+    }
+    /** Call when dispatching a request to a worker */
+    acquire(workerKey) {
+        this._pending.set(workerKey, (this._pending.get(workerKey) ?? 0) + 1);
+    }
+    /** Call when a request to a worker completes */
+    release(workerKey) {
+        const count = this._pending.get(workerKey) ?? 0;
+        if (count <= 0) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn("[LeastPendingStrategy] Spurious release()");
+            }
+            this._pending.delete(workerKey);
+            return;
+        }
+        if (count <= 1) {
+            this._pending.delete(workerKey);
+        }
+        else {
+            this._pending.set(workerKey, count - 1);
+        }
+    }
+    get name() {
+        return "least-pending";
+    }
+}
+// ─── Broadcast ──────────────────────────────────────────────
+export class BroadcastStrategy {
+    /**
+     * Returns ALL workers. The caller is responsible for sending
+     * to all of them and handling multiple responses.
+     */
+    pick(workers, _callContext) {
+        return workers; // Return the full array — caller detects this
+    }
+    get name() {
+        return "broadcast";
+    }
+    get isBroadcast() {
+        return true;
+    }
+}
+// ─── Primary ────────────────────────────────────────────────
+export class PrimaryStrategy {
+    /**
+     * Always routes to worker index 0. If worker 0 is down,
+     * routes to the next available.
+     */
+    pick(workers, _callContext) {
+        if (workers.length === 0)
+            return null;
+        return workers[0]; // Primary is always first
+    }
+    get name() {
+        return "primary";
+    }
+}
+// ─── Strategy Factory ───────────────────────────────────────
+const STRATEGIES = {
+    "round-robin": (_opts) => new RoundRobinStrategy(),
+    hash: (opts) => new HashStrategy(opts),
+    "least-pending": (_opts) => new LeastPendingStrategy(),
+    broadcast: (_opts) => new BroadcastStrategy(),
+    primary: (_opts) => new PrimaryStrategy(),
+};
+/**
+ * Create a routing strategy by name.
+ */
+export function createStrategy(name, options = {}) {
+    const factory = STRATEGIES[name];
+    if (!factory) {
+        throw new Error(`Unknown routing strategy: "${name}". Available: ${ROUTING_STRATEGY_NAMES.join(", ")}`);
+    }
+    return factory(options);
+}
+//# sourceMappingURL=RoutingStrategy.js.map

package/dist/core/RoutingStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingStrategy.js","sourceRoot":"","sources":["../../src/core/RoutingStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,sBAAsB,GAEvB,MAAM,mBAAmB,CAAC;AAE3B,mFAAmF;AACnF,MAAM,SAAS,GAAW,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAyBzF,+DAA+D;AAC/D,qEAAqE;AACrE,SAAS,KAAK,CAAC,GAAW;IACxB,IAAI,IAAI,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,mBAAmB;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,GAAG,CAAC,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;IAC9C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,6BAA6B;AAClD,CAAC;AAED,+DAA+D;AAE/D,MAAM,OAAO,kBAAkB;IAC7B,KAAK,CAAS;IAEd;QACE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,OAAsB,EAAE,YAAiC;QAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC;QAC9C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,aAAa,CAAC;IACvB,CAAC;CACF;AAED,+DAA+D;AAE/D,MAAM,OAAO,YAAY;IACvB,QAAQ,CAAgB;IACxB,MAAM,CAAS;IACf,oGAAoG;IAC5F,KAAK,CAAiB;IACtB,eAAe,CAAS;IACxB,WAAW,CAAe;IAC1B,SAAS,CAAY;IACrB,gBAAgB,CAAS;IACzB,KAAK,CAAS;IAEtB,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC1B,wEAAwE;QACxE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC;IACzC,CAAC;IAED,IAAI,CAAC,OAAsB,EAAE,WAAgC;QAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;QAE5C,6CAA6C;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,4DAA4D;YAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;YACnD,IAAI,CAAC,gBAAgB,GAAG,CAAC,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC;YACpE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QAED,+DAA+D;QAC/D,uEAAuE;QACvE,MAAM,eAAe,GAAG,OAAO;aAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;aACjB,IAAI,EAAE;aACN,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,IAAI,IAAI,CAAC,eAAe,KAAK,eAAe,EAAE,CAAC;YAC7C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAED,8BAA8B;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAEO,WAAW,CAAC,WAA+B;QACjD,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAE9B,4DAA4D;QAC5D,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,IAAI,EAAE,CAAC;YAC5C,+CAA+C;YAC/C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;oBAC/D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzB,CAAC;gBACD,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAK,IAAI,CAAC,CAAC,CAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC3G,OAAO,MAAM,CAAE,IAAI,CAAC,CAAC,CAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACrE,CAAC;YACH,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,IAAI,WAAW,CAAC,YAAY,EAAE,CAAC;YAC7B,OAAO,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,UAAU,CAAC,OAAsB;QACvC,6EAA6E;QAC7E,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAChD,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,UAAU,CAAC,CAAC;QAC3C,kEAAkE;QAClE,yEAAyE;QACzE,MAAM,IAAI,GAAa,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC3B,GAAG,EAAE,CAAC;YACR,CAAC;QACH,CAAC;QACD,2CAA2C;QAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAClE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,CAAC,SAAS,GAAG,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW;QAC9B,IAAI,CAAC,eAAe,GAAG,OAAO;aAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;aACjB,IAAI,EAAE;aACN,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAEO,WAAW,CAAC,IAAY,EAAE,OAAsB;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAChC,iDAAiD;QACjD,IAAI,EAAE,GAAG,CAAC,EACR,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI;gBAAE,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;;gBAChC,EAAE,GAAG,GAAG,CAAC;QAChB,CAAC;QACD,cAAc;QACd,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,2DAA2D;QAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,GAAW;QAC9B,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACK,WAAW,CAAC,GAAW;QAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,QAAQ,IAAI,CAAC,QAAQ,IAAI,MAAM,GAAG,CAAC;IAC5C,CAAC;CACF;AAED,+DAA+D;AAE/D,MAAM,OAAO,oBAAoB;IACvB,QAAQ,CAAsB;IACtC,yEAAyE;IACjE,eAAe,CAAS;IAEhC;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAsB,EAAE,YAAiC;QAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;QAE5C,qFAAqF;QACrF,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/D,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,WAAW,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YACnE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;gBACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,WAAW,CAAC;QAEnC,IAAI,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjD,IAAI,CAAC,GAAG,WAAW,EAAE,CAAC;gBACpB,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;gBAClB,WAAW,GAAG,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kDAAkD;IAClD,OAAO,CAAC,SAAiB;QACvB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,gDAAgD;IAChD,OAAO,CAAC,SAAiB;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAChC,OAAO;QACT,CAAC;QACD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,eAAe,CAAC;IACzB,CAAC;CACF;AAED,+DAA+D;AAE/D,MAAM,OAAO,iBAAiB;IAC5B;;;OAGG;IACH,IAAI,CAAC,OAAsB,EAAE,YAAiC;QAC5D,OAAO,OAAO,CAAC,CAAC,8CAA8C;IAChE,CAAC;IAED,IAAI,IAAI;QACN,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,+DAA+D;AAE/D,MAAM,OAAO,eAAe;IAC1B;;;OAGG;IACH,IAAI,CAAC,OAAsB,EAAE,YAAiC;QAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,0BAA0B;IAC/C,CAAC;IAED,IAAI,IAAI;QACN,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED,+DAA+D;AAE/D,MAAM,UAAU,GAAsF;IACpG,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,kBAAkB,EAAE;IAClD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC;IACtC,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,oBAAoB,EAAE;IACtD,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,iBAAiB,EAAE;IAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,eAAe,EAAE;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAA+B,EAAE;IAC5E,MAAM,OAAO,GAAG,UAAU,CAAC,IAAiC,CAAC,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,iBAAiB,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC"}

package/dist/core/RpcConfig.d.ts

@@ -0,0 +1,72 @@
+/**
+ * RPC Configuration Utilities
+ *
+ * Centralizes validation, merge logic, and resolution for per-service
+ * and per-target RPC options (circuit breaker, retry, timeout, bulkhead,
+ * concurrency).
+ *
+ * Merge precedence (lowest → highest):
+ *   1. Framework defaults (in Interceptors.ts constructors)
+ *   2. Service-level `rpc` field
+ *   3. Target-level `rpcTargets[targetName]`
+ *   4. Contract-level options (static contract = { circuitBreaker: ... })
+ *   5. Per-method decorator options (@Expose({ retry: false }))
+ *
+ * Steps 1-3 are resolved here. Steps 4-5 are resolved in ServiceProxy.
+ */
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    /** Percentage-based failure rate threshold (0-100). When set, the breaker
+     *  opens if the failure rate within the sliding window exceeds this value
+     *  AND the minimum sample count is met. Takes precedence over failureThreshold. */
+    failureRateThreshold?: number;
+    /** Minimum number of calls in the window before failure rate is evaluated. */
+    minimumCallCount?: number;
+    resetTimeoutMs?: number;
+    successThreshold?: number;
+    windowMs?: number;
+    /** Number of concurrent probe requests allowed in half-open state. */
+    halfOpenMaxProbes?: number;
+}
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface BulkheadOptions {
+    maxConcurrent?: number;
+}
+export interface ConcurrencyOptions {
+    initialLimit?: number;
+    minLimit?: number;
+    maxLimit?: number;
+    smoothing?: number;
+    tolerance?: number;
+}
+export interface RpcOptions {
+    circuitBreaker?: CircuitBreakerOptions;
+    retry?: RetryOptions | false;
+    defaultTimeout?: number;
+    bulkhead?: BulkheadOptions;
+    concurrency?: ConcurrencyOptions;
+}
+export interface RpcConfig {
+    rpc?: RpcOptions;
+    rpcTargets?: Record<string, RpcOptions>;
+}
+/**
+ * Validate an RPC options object shape.
+ */
+export declare function validateRpcOptions(serviceName: string, label: string, options: unknown): void;
+/**
+ * Deep-merge two RPC options objects. Override values take precedence.
+ * For nested objects (circuitBreaker, retry, bulkhead, concurrency),
+ * individual fields merge so you only need to specify what changes.
+ */
+export declare function mergeRpcOptions(base?: RpcOptions, override?: RpcOptions): RpcOptions;
+/**
+ * Resolve the final RPC options for a specific target service.
+ * Merges service-level `rpc` defaults with target-specific `rpcTargets` overrides.
+ */
+export declare function resolveRpcOptionsForTarget(config: RpcConfig | undefined, targetName: string): RpcOptions;
+//# sourceMappingURL=RpcConfig.d.ts.map

package/dist/core/RpcConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RpcConfig.d.ts","sourceRoot":"","sources":["../../src/core/RpcConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;uFAEmF;IACnF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,KAAK,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACzC;AAqBD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAuC7F;AA0BD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU,CAmCpF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAIxG"}

package/dist/core/RpcConfig.js

@@ -0,0 +1,127 @@
+/**
+ * RPC Configuration Utilities
+ *
+ * Centralizes validation, merge logic, and resolution for per-service
+ * and per-target RPC options (circuit breaker, retry, timeout, bulkhead,
+ * concurrency).
+ *
+ * Merge precedence (lowest → highest):
+ *   1. Framework defaults (in Interceptors.ts constructors)
+ *   2. Service-level `rpc` field
+ *   3. Target-level `rpcTargets[targetName]`
+ *   4. Contract-level options (static contract = { circuitBreaker: ... })
+ *   5. Per-method decorator options (@Expose({ retry: false }))
+ *
+ * Steps 1-3 are resolved here. Steps 4-5 are resolved in ServiceProxy.
+ */
+const VALID_RPC_KEYS = new Set([
+    "circuitBreaker", "retry", "defaultTimeout", "bulkhead", "concurrency",
+]);
+const VALID_CB_KEYS = new Set([
+    "failureThreshold", "failureRateThreshold", "minimumCallCount",
+    "resetTimeoutMs", "successThreshold", "windowMs", "halfOpenMaxProbes",
+]);
+const VALID_RETRY_KEYS = new Set([
+    "maxAttempts", "baseDelayMs", "maxDelayMs",
+]);
+const VALID_BULKHEAD_KEYS = new Set(["maxConcurrent"]);
+const VALID_CONCURRENCY_KEYS = new Set([
+    "initialLimit", "minLimit", "maxLimit", "smoothing", "tolerance",
+]);
+/**
+ * Validate an RPC options object shape.
+ */
+export function validateRpcOptions(serviceName, label, options) {
+    if (options === undefined || options === null)
+        return;
+    if (typeof options !== "object" || Array.isArray(options)) {
+        throw new Error(`Service "${serviceName}": ${label} must be an object`);
+    }
+    const opts = options;
+    for (const key of Object.keys(opts)) {
+        if (!VALID_RPC_KEYS.has(key)) {
+            throw new Error(`Service "${serviceName}": unknown ${label} key "${key}". ` +
+                `Valid keys: ${[...VALID_RPC_KEYS].join(", ")}`);
+        }
+    }
+    if (opts.circuitBreaker !== undefined) {
+        _validateSubObject(serviceName, `${label}.circuitBreaker`, opts.circuitBreaker, VALID_CB_KEYS, "number");
+    }
+    if (opts.retry !== undefined && opts.retry !== false) {
+        _validateSubObject(serviceName, `${label}.retry`, opts.retry, VALID_RETRY_KEYS, "number");
+    }
+    if (opts.defaultTimeout !== undefined) {
+        if (typeof opts.defaultTimeout !== "number" || opts.defaultTimeout <= 0) {
+            throw new Error(`Service "${serviceName}": ${label}.defaultTimeout must be a positive number`);
+        }
+    }
+    if (opts.bulkhead !== undefined) {
+        _validateSubObject(serviceName, `${label}.bulkhead`, opts.bulkhead, VALID_BULKHEAD_KEYS, "number");
+    }
+    if (opts.concurrency !== undefined) {
+        _validateSubObject(serviceName, `${label}.concurrency`, opts.concurrency, VALID_CONCURRENCY_KEYS, "number");
+    }
+}
+function _validateSubObject(serviceName, path, obj, validKeys, valueType) {
+    if (typeof obj !== "object" || Array.isArray(obj) || obj === null) {
+        throw new Error(`Service "${serviceName}": ${path} must be an object`);
+    }
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        if (!validKeys.has(key)) {
+            throw new Error(`Service "${serviceName}": unknown ${path} key "${key}". ` +
+                `Valid keys: ${[...validKeys].join(", ")}`);
+        }
+        if (typeof record[key] !== valueType) {
+            throw new Error(`Service "${serviceName}": ${path}.${key} must be a ${valueType}`);
+        }
+    }
+}
+/**
+ * Deep-merge two RPC options objects. Override values take precedence.
+ * For nested objects (circuitBreaker, retry, bulkhead, concurrency),
+ * individual fields merge so you only need to specify what changes.
+ */
+export function mergeRpcOptions(base, override) {
+    if (!override)
+        return base ?? {};
+    if (!base)
+        return override;
+    const merged = {};
+    // circuitBreaker: deep merge
+    if (base.circuitBreaker || override.circuitBreaker) {
+        merged.circuitBreaker = { ...base.circuitBreaker, ...override.circuitBreaker };
+    }
+    // retry: false disables retries; object values deep-merge; undefined inherits from base
+    if (override.retry === false) {
+        merged.retry = false;
+    }
+    else if (override.retry !== undefined) {
+        const baseRetry = base.retry === false ? {} : (base.retry ?? {});
+        merged.retry = { ...baseRetry, ...override.retry };
+    }
+    else if (base.retry !== undefined) {
+        merged.retry = base.retry;
+    }
+    // defaultTimeout: scalar override
+    merged.defaultTimeout = override.defaultTimeout ?? base.defaultTimeout;
+    // bulkhead: deep merge
+    if (base.bulkhead || override.bulkhead) {
+        merged.bulkhead = { ...base.bulkhead, ...override.bulkhead };
+    }
+    // concurrency: deep merge
+    if (base.concurrency || override.concurrency) {
+        merged.concurrency = { ...base.concurrency, ...override.concurrency };
+    }
+    return merged;
+}
+/**
+ * Resolve the final RPC options for a specific target service.
+ * Merges service-level `rpc` defaults with target-specific `rpcTargets` overrides.
+ */
+export function resolveRpcOptionsForTarget(config, targetName) {
+    const base = config?.rpc ?? {};
+    const targetOverride = config?.rpcTargets?.[targetName];
+    return mergeRpcOptions(base, targetOverride);
+}
+//# sourceMappingURL=RpcConfig.js.map

package/dist/core/RpcConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RpcConfig.js","sourceRoot":"","sources":["../../src/core/RpcConfig.ts"],"names":[],"mappings":"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"}

package/dist/core/SignatureCache.d.ts

@@ -0,0 +1,81 @@
+/**
+ * SignatureCache - Rotating HMAC signature cache for internal RPC optimization
+ *
+ * P-PERF-29: Reduce per-request HMAC computation cost by caching signatures with
+ * periodic rotation. Maintains replay protection guarantees while reducing CPU overhead.
+ *
+ * Security Model:
+ * - Signatures rotate every 5 seconds (configurable)
+ * - Multiple signatures active during overlap window for clock drift tolerance
+ * - Replay protection window: 30 seconds (INTERNAL_SIG_MAX_AGE_MS)
+ * - Rotation interval (5s) << replay window (30s) = safe
+ *
+ * Performance:
+ * - Reduces HMAC computations by ~5s/rotation_interval ratio
+ * - At 1000 RPS: 5000 HMAC ops/rotation vs 1 per rotation = ~5000x reduction
+ * - Memory overhead: ~200 bytes per cached signature entry
+ */
+/**
+ * Configuration for signature cache behavior
+ */
+export interface SignatureCacheConfig {
+    /** How often to rotate signatures (ms). Default: 5000 (5s) */
+    rotationIntervalMs?: number;
+    /** Whether caching is enabled. Default: false (opt-in for safety) */
+    enabled?: boolean;
+}
+/**
+ * SignatureCache maintains a rotating set of precomputed HMAC signatures
+ * for internal RPC authentication. Reduces per-request CPU cost while
+ * preserving replay protection guarantees.
+ */
+export declare class SignatureCache {
+    private readonly secret;
+    private readonly rotationIntervalMs;
+    private readonly enabled;
+    private currentSignatures;
+    private previousSignatures;
+    private currentTimestamp;
+    private previousTimestamp;
+    private rotationTimer;
+    constructor(secret: string, config?: SignatureCacheConfig);
+    /**
+     * Get a signature for the given method and path.
+     * If caching is disabled, computes a fresh signature each time.
+     * If caching is enabled, returns the current cached signature.
+     */
+    getSignature(method: string, path: string): {
+        signature: string;
+        timestamp: string;
+    };
+    /**
+     * Check if caching is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get cache statistics for monitoring
+     */
+    getStats(): {
+        enabled: boolean;
+        rotationIntervalMs: number;
+        currentTimestamp: number | null;
+        previousTimestamp: number | null;
+    };
+    /**
+     * Stop the rotation timer (for cleanup)
+     */
+    stop(): void;
+    /**
+     * Force an immediate rotation (useful for testing)
+     */
+    rotate(): void;
+    private _initializeCache;
+    private _startRotation;
+    private _rotateSignature;
+    private _computeFreshSignature;
+}
+/**
+ * Create a signature cache instance from environment configuration
+ */
+export declare function createSignatureCacheFromEnv(): SignatureCache | null;
+//# sourceMappingURL=SignatureCache.d.ts.map

package/dist/core/SignatureCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignatureCache.d.ts","sourceRoot":"","sources":["../../src/core/SignatureCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAGlC,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,kBAAkB,CAA0C;IAGpE,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAAuB;IAGhD,OAAO,CAAC,aAAa,CAA+B;gBAExC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,oBAAyB;IAmC7D;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IA8BpF;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,QAAQ,IAAI;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC;IASD;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACH,MAAM,IAAI,IAAI;IAMd,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,sBAAsB;CAK/B;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,GAAG,IAAI,CAenE"}