ninja-reverse-proxy 1.0.4 → 1.0.5

package/README.md

@@ -1,186 +1,234 @@
-# Ninja Reverse Proxy
+# 🛡️ Ninja Reverse Proxy
 
-A production-grade, backend-agnostic **Layer 7 Reverse Proxy** built from scratch in TypeScript and Node.js.
+A production-grade, backend-agnostic **Layer 7 Reverse Proxy & Load Balancer** built from scratch in TypeScript and Node.js.
 
-Designed in the same philosophy as Nginx, Traefik, and HAProxy — configure it once, point it at any backend, and it handles everything else.
+Designed in the same engineering philosophy as **NGINX, Envoy, and HAProxy** — configure it once, point it at any backend, and it handles enterprise-grade traffic distribution, load balancing, rate limiting, multi-tier caching, resilience patterns, and health monitoring automatically.
 
 ---
 
-## Works with any HTTP backend
+## 🏛️ Master-Worker Architecture Overview
 
-node· Kubernetes Services · Docker Compose services · **Any service that speaks HTTP**
+Ninja Reverse Proxy utilizes a highly performant **Master-Worker Cluster Architecture** that runs on all available CPU cores using Node.js Inter-Process Communication (IPC).
 
-The proxy never cares what technology runs behind the URLs. You configure upstreams in `config.yaml` and the proxy routes, balances, caches, rate-limits, and health-checks them automatically.
+```
+                     +----------------------------+
+                     |        Client (WS/HTTPS)   |
+                     +--------------+-------------+
+                                    |
+                                    ▼
+                     +----------------------------+
+                     |  Master Node (IPC Watchdog)|
+                     +-------+------------+-------+
+                             |            |
+                    (IPC Chans)          (IPC Chans)
+                             |            |
+            +----------------v---+    +---v----------------+
+            | Worker 1           |    | Worker 2           |
+            | - HTTP/WS Pipeline |    | - HTTP/WS Pipeline |
+            | - L1 In-Memory LRU |    | - L1 In-Memory LRU |
+            +-------+------------+    +---+----------------+
+                    |                     |
+             (TCP/WSS Proxy)       (TCP/WSS Proxy)
+                    |                     |
+      +-------------v---------------------v-------------+
+      |  Shared Distributed Tier:                       |
+      |  - L2 Response Cache (Redis)                    |
+      |  - Distributed Rate Limiter State (Redis Lua)   |
+      |  - Telemetry & Dynamic Service Registry         |
+      |  - Debezium CDC Invalidation Stream             |
+      +------+------------------------------------+-----+
+             |                                    |
+             ▼                                    ▼
+      +--------------+                     +--------------+
+      | Upstream A   |                     | Upstream B   |
+      +--------------+                     +--------------+
+```
 
 ---
 
-## Features
-
-| Feature | Details |
-|---|---|
-| Cluster Architecture | Master/Worker pattern via Node.js cluster — uses all CPU cores |
-| Round-Robin Load Balancing | Equal request distribution across healthy upstreams |
-| Circuit Breaker | Marks upstreams DOWN after configurable failure threshold |
-| Redis Response Cache | GET response caching with configurable TTL |
-| Per-Route Rate Limiting | Sliding window rate limiter per client IP per route |
-| Service Registry | Backends self-register, deregister, and send heartbeats |
-| Continuous Health Checks | Every 10 seconds — auto-removes and auto-recovers upstreams |
-| HTTPS / TLS Termination | Full SSL at the proxy; all HTTP auto-redirected (301) |
-| Sticky Sessions | Cookie-based session affinity per upstream |
-| Retry Logic | Up to 2 retries on upstream failure, each on a different upstream |
-| Graceful Shutdown | Drains all connections on SIGTERM / SIGINT |
-| Hot Reload | Watches `config.yaml` and `config.d/` — zero-downtime config updates |
-| Admin API | Live stats for load balancer, cache, registry, auto scaler |
-| YAML Configuration | One file, fully validated with Zod — no source code changes needed |
+## 📐 Enterprise Design Patterns Implemented
 
----
+1. **Strategy Pattern (`ILoadBalancerStrategy`, `IRateLimiterAlgorithm`)**: Decouples algorithm selection from proxy execution. All 12 load balancing and 5 rate limiting algorithms implement common interfaces and are swapped at runtime.
+2. **Factory Pattern (`BalancerFactory`)**: Centralized instantiator that parses Zod schemas and generates configured load balancer strategies.
+3. **Dependency Inversion Principle (SOLID)**: Core proxy components depend strictly on abstractions (`ICache`, `IInvalidator`, `IServiceRegistry`), enabling seamless swapping between Memory, Redis, and Hybrid stores.
+4. **Koa/Express Onion Middleware Model**: Declarative pipeline (`RequestContext`, `MiddlewarePipeline`) executing CORS, Authentication, Tracing, Rate Limiting, Cache, and Circuit Breakers in non-blocking order.
+5. **Zero-Copy TCP Socket Tunneling**: Direct bidirectional piping (`clientSocket.pipe(targetSocket)`) for WebSocket and HTTPS connections.
 
-## Quick Start
+---
 
-### 1. Install globally
+## ⚡ Core Systems & Features
 
-```bash
-npm install -g ninja-reverse-proxy
-```
+### 1. Advanced Load Balancing Engine (12 Strategies)
+All load balancing strategies are dynamically validated using Zod schemas and instantiated via `BalancerFactory`:
 
-### 2. Generate TLS certificates
+* **Weighted Round-Robin (WRR)**: Smooth interleaved scheduling (NGINX style) using `currentWeight` adjustments.
+* **Adaptive Weighted Round-Robin**: Automatically modifies weights in real time based on latency EWMA and request error rates.
+* **Power of Two Choices (P2C)**: Pick two random healthy upstreams and route to the one with the lowest active connections ($O(1)$ efficiency).
+* **Least Connections**: Route to the healthy upstream with the fewest active connections.
+* **Weighted Least Connections**: Select using the `activeConnections / weight` ratio.
+* **Least Response Time**: Route using latency EWMA (Exponentially Weighted Moving Average).
+* **Consistent Hashing**: Distributed virtual node (150 replicas) ring mapping client IP to upstreams with minimum cache eviction.
+* **IP Hash**: FNV-1a hash-modulo routing using client IP.
+* **Sticky Sessions**: Cookie-based (`NINJA_ROUTE`) session affinity.
+* **Resource-Based**: Telemetry-aware load routing using live CPU and memory metrics reported by sidecars.
+* **Random Selection**: Fallback randomized distribution.
 
-```bash
-openssl req -x509 -newkey rsa:4096 \
-  -keyout key.pem -out cert.pem \
-  -days 365 -nodes \
-  -subj "/CN=localhost"
-```
+---
 
-### 3. Create your config file
+### 2. High-Performance Multi-Tier Caching & Invalidation
+* **L1/L2 Hybrid Caching**: In-memory LRU cache (L1 RAM) backed by Redis (L2 Distributed Store) with automatic L1 warming & background synchronization.
+* **Debezium CDC (Change Data Capture) Invalidation**: Subscribes to Redis Pub/Sub events from Debezium Server. Parses transaction log updates from SQL databases and MongoDB (supporting ObjectId `$oid` conversions) to invalidate cached paths instantly:
+  * *SQL Event Map*: `{"op":"u", "source":{"table":"orders"}, "after":{"id":999}}` $\rightarrow$ Invalidates `/api/orders/999`.
+  * *Mongo Event Map*: `{"op":"u", "source":{"collection":"orders"}, "after":{"_id":{"$oid":"60d5ec4b..."}}}` $\rightarrow$ Invalidates matching mapped paths.
+* **Pattern & Tag-Based Invalidation**: Glob pattern matching (`PatternInvalidator`) and metadata grouping (`TagInvalidator`).
+* **Cache Control Directives (`CacheControlParser`)**: Parses standards-compliant HTTP headers (`no-store`, `no-cache`, `max-age`, `s-maxage`, `private`).
+* **Cache Normalization (`KeyBuilder`)**: Strips marketing query parameters (`utm_source`, `fbclid`) and handles `Vary` headers (`Accept-Encoding: gzip`).
+* **Advanced Cache Policies**:
+  * `stale-while-revalidate`: Serves stale cache while triggering concurrent lock-free background revalidation (preventing Thundering Herd / Cache Stampedes).
+  * `stale-if-error`: Serves expired stale cache during upstream 5xx or network outages.
 
-```yaml
-# config.yaml
-server:
-  listen: 8080
-  httpsPort: 8443
-  workers: 2
+---
 
-  loadBalancing:
-    strategy: round-robin
-    failureThreshold: 3
-    recoveryTimeMs: 15000
-    retry:
-      maxAttempts: 2
-      statusCodes: [502, 503, 504]
-
-  upstreams:
-    - id: my-api
-      url: http://localhost:5000
-    - id: my-api-2
-      url: http://localhost:5001
-
-  paths:
-    - path: /
-      upstream: [my-api, my-api-2]
-
-  headers:
-    - key: X-Forwarded-For
-      value: client_ip
-
-  cache:
-    enabled: false
-    host: redis
-    port: 6379
-    ttlSeconds: 60
-```
+### 3. Distributed Rate Limiting & Throttling
+* **5 Algorithms**: `token-bucket`, `leaking-bucket`, `fixed-window`, `sliding-window-log`, and `sliding-window-counter`.
+* **Atomic Redis Lua Scripts**: Server-side Lua script execution preventing race conditions across distributed proxy nodes.
+* **Soft Limit Warning & Burst Policy**: Dynamically increases burst limit ($1.5\times$ base limit) when current system load is below soft threshold.
+* **Multi-Dimension Rules**: Independent rate limiting rules evaluated per IP, Route, API-Key, and Header combination (`rl:ip:/api/v1:10.0.0.1`).
 
-### 4. Start the proxy
+---
 
-```bash
-ninja-proxy --config config.yaml
-```
+### 4. Advanced Fault Tolerance & Resilience
+* **Classic Circuit Breaker**: Standard state machine (`CLOSED` $\rightarrow$ `OPEN` $\rightarrow$ `HALF_OPEN`) based on consecutive failure thresholds.
+* **Google SRE EWMA Adaptive Circuit Breaker**: Rate-based shedding model using Google SRE probability math:
+  $$P = \frac{\text{requests} - K \times \text{accepts}}{\text{requests} + 1}$$
+* **Bulkhead Pattern**: Concurrency isolation slots preventing slow upstreams from exhausting worker thread pools.
+* **4 Jitter Backoff Algorithms**:
+  * `ExponentialBackoff`: Deterministic doubling.
+  * `FullJitterBackoff`: $Random(0, min(cap, base \times 2^{attempt}))$.
+  * `EqualJitterBackoff`: $\frac{temp}{2} + Random(0, \frac{temp}{2})$.
+  * `DecorrelatedJitterBackoff`: $Random(base, previousSleep \times 3)$.
+* **Retry Budgets**: Capped retry allowance (e.g. max 15% retry budget) to prevent upstream retry storms.
 
-### 5. Test it
+---
 
-```bash
-curl -k https://localhost:8443/
-curl -k https://localhost:8443/__lb-stats
-```
+### 5. Dynamic Service Registry & Health Probes
+* **Dynamic Self-Registration REST API**: Upstreams can self-register, heartbeat, and deregister (`/__registry/register`, `heartbeat`, `deregister`).
+* **Disk Snapshot Persistence**: Automatic rehydration of services from `registry.json` snapshot backups on proxy restart.
+* **Dual Health Probes**: Active HTTP ping probes (`checkUpstream`) + Passive background failure monitors.
 
 ---
 
-## Dynamic Service Registry
-
-Backends can self-register at runtime without touching `config.yaml`:
+### 6. Observability, Telemetry & Multi-Tenant Logging
+* **Prometheus Exposition Endpoint (`/metrics`)**: Exposes latency percentiles (P50, P95, P99), RPS, active connections, and circuit breaker status.
+* **5 Auto-Provisioned Grafana Dashboards**: Visual monitoring dashboards for Proxy Overview, Load Balancers, Cache, Circuit Breakers, and Rate Limiters.
+* **Tenant Log Streamer**: Webhook log streaming engine dispatching structured JSON access logs to tenant HTTP webhooks.
 
-```bash
-# Register a new upstream dynamically
-curl -X POST -H "Content-Type: application/json" \
-  -d '{"id":"my-service","url":"http://localhost:3000"}' \
-  http://localhost:8080/__registry/register
+---
 
-# Send a heartbeat
-curl -X PUT http://localhost:8080/__registry/heartbeat/my-service
+## 📄 Complete Production `config.yaml` Reference
 
-# Deregister
-curl -X DELETE http://localhost:8080/__registry/deregister/my-service
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+  httpsPort: 8443
+  workers: 4
+
+upstreams:
+  - id: "app-node-1"
+    url: "http://127.0.0.1:3000"
+    weight: 3
+    maxConnections: 500
+    healthPath: "/health"
+  - id: "app-node-2"
+    url: "http://127.0.0.1:3001"
+    weight: 1
+    maxConnections: 500
+    healthPath: "/health"
+
+loadBalancing:
+  strategy: "weighted-round-robin"  # Options: round-robin, least-connections, power-of-two, consistent-hashing, adaptive-wrr, resource-based
+  stickyCookieName: "NINJA_ROUTE"
+
+rateLimit:
+  enabled: true
+  storage: "memory"                 # Options: memory, redis, hybrid
+  algorithm: "token-bucket"         # Options: fixed-window, sliding-window-log, sliding-window-counter, token-bucket, leaking-bucket
+  windowMs: 60000
+  maxRequests: 1000
+  softLimit: true
+  dimensions:
+    - dimension: "ip"
+      maxRequests: 100
+      windowMs: 60000
+    - dimension: "api-key"
+      maxRequests: 500
+      windowMs: 60000
+
+cache:
+  enabled: true
+  ttlSeconds: 60
+  l1MaxSize: 1000
+  staleWhileRevalidate: true
+  staleIfError: true
+  debezium:
+    enabled: true
+    channel: "debezium-cdc-events"
+    mappings:
+      - table: "orders"
+        pathPattern: "/api/orders/{id}"
+
+resilience:
+  circuitBreaker:
+    mode: "adaptive"                # Options: classic, adaptive
+    failureThreshold: 3
+    recoveryTimeMs: 10000
+  bulkhead:
+    maxConcurrent: 100
+  retry:
+    maxAttempts: 3
+    backoff: "full-jitter"          # Options: exponential, full-jitter, equal-jitter, decorrelated-jitter
+
+observability:
+  metrics:
+    enabled: true
+    path: "/metrics"
 ```
 
 ---
 
-## Multi-Tenant Config (Nginx-style)
-
-Drop extra config files into a `config.d/` folder — the proxy merges them automatically with zero downtime:
+## 🧪 Testing & Verification Suites
 
+### 1. Run Complete 63-Unit & Integration Test Suite
 ```bash
-mkdir config.d
-
-# Each tenant/app gets their own isolated file
-echo "
-server:
-  upstreams:
-    - id: tenant-a
-      url: http://localhost:4000
-  paths:
-    - path: /tenant-a
-      upstream: [tenant-a]
-" > config.d/tenant-a.yaml
+node node_modules/typescript/bin/tsc -p tsconfig.test.json && node --test dist-test/tests/unit/**/*.js dist-test/tests/integration/*.js
 ```
 
-The proxy hot-reloads `config.d/` automatically whenever a file is added or changed.
-
----
-
-## Admin API
+### 2. Run 30-Feature Audit & Report Generator
+```bash
+node node_modules/typescript/bin/tsc -p tsconfig.test.json && node dist-test/scripts/verify-all-features.js
+```
+*(Generates markdown proof report in `results/interview_proof_report.md`)*
 
-| Endpoint | Method | Description |
-|---|---|---|
-| `/__lb-stats` | GET | Load balancer stats + healthy upstreams |
-| `/__cache-stats` | GET | Redis cache hit/miss stats |
-| `/__registry` | GET | All registered services |
-| `/__registry/register` | POST | Register a new upstream |
-| `/__registry/deregister/:id` | DELETE | Deregister an upstream |
-| `/__registry/heartbeat/:id` | PUT | Upstream heartbeat ping |
+### 3. Run Production High-RPS Benchmark
+```bash
+npx tsx scripts/benchmark.ts https://localhost:8443/ 1000 20
+```
 
 ---
 
-## Configuration Reference
+## 📦 Build & NPM Publish
 
-| Field | Default | Description |
-|---|---|---|
-| `server.listen` | `8080` | HTTP port — redirects all traffic to HTTPS |
-| `server.httpsPort` | `8443` | HTTPS port — main entry point |
-| `server.workers` | `2` | Set to your CPU core count |
-| `loadBalancing.strategy` | `round-robin` | `round-robin` \| `least-connections` \| `ip-hash` \| `random` |
-| `loadBalancing.failure0Threshold` | `3` | Mark upstream DOWN after N consecutive failures |
-| `loadBalancing.recoveryTimeMs` | `15000` | Retry a DOWN upstream after N ms |
-| `cache.enabled` | `false` | Enable Redis GET response caching |
-| `cache.ttlSeconds` | `60` | Cache TTL in seconds |
-
----
-
-## Repository
+```bash
+# Build TypeScript bundle to dist/
+pnpm run build
 
-[github.com/praveenkumar-co/reverse-proxy](https://github.com/praveenkumar-co/reverse-proxy)
+# Publish to npmjs.com
+npm publish
+```
 
 ---
 
-## License
+## 📜 License
 
-MIT
+MIT License © 2026 Praveen Kumar

package/dist/balancer/contracts/balancer.interface.d.ts

@@ -0,0 +1,8 @@
+export interface IBalancer {
+    pickFiltered(healthyIds: Set<string>, clientIp?: string, attemptedIds?: Set<string>, cookies?: string): string | null;
+    recordSuccess(id: string, latencyMs?: number): void;
+    recordFailure(id: string): void;
+    setHealthy(id: string, healthy: boolean): void;
+    getStats(): Record<string, any>;
+}
+//# sourceMappingURL=balancer.interface.d.ts.map

package/dist/balancer/contracts/balancer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balancer.interface.d.ts","sourceRoot":"","sources":["../../../src/balancer/contracts/balancer.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,YAAY,CACV,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAAC;IACjB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/C,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC"}

package/dist/balancer/contracts/balancer.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=balancer.interface.js.map

package/dist/balancer/contracts/balancer.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balancer.interface.js","sourceRoot":"","sources":["../../../src/balancer/contracts/balancer.interface.ts"],"names":[],"mappings":""}

package/dist/balancer/contracts/context.types.d.ts

@@ -0,0 +1,7 @@
+export interface PickContext {
+    clientIp?: string;
+    attemptedIds?: Set<string>;
+    cookies?: string;
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=context.types.d.ts.map

package/dist/balancer/contracts/context.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.types.d.ts","sourceRoot":"","sources":["../../../src/balancer/contracts/context.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}

package/dist/balancer/contracts/context.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.types.js.map

package/dist/balancer/contracts/context.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.types.js","sourceRoot":"","sources":["../../../src/balancer/contracts/context.types.ts"],"names":[],"mappings":""}

package/dist/balancer/contracts/strategy.interface.d.ts

@@ -0,0 +1,6 @@
+import type { UpstreamState } from "../../types/upstream.types.js";
+export interface IStrategy {
+    pick(candidates: UpstreamState[], clientIp?: string, cookies?: string): UpstreamState | null;
+    onUpstreamsChanged?(upstreams: UpstreamState[]): void;
+}
+//# sourceMappingURL=strategy.interface.d.ts.map

package/dist/balancer/contracts/strategy.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.interface.d.ts","sourceRoot":"","sources":["../../../src/balancer/contracts/strategy.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,MAAM,WAAW,SAAS;IACxB,IAAI,CACF,UAAU,EAAE,aAAa,EAAE,EAC3B,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,aAAa,GAAG,IAAI,CAAC;IACxB,kBAAkB,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;CACvD"}

package/dist/balancer/contracts/strategy.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=strategy.interface.js.map

package/dist/balancer/contracts/strategy.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.interface.js","sourceRoot":"","sources":["../../../src/balancer/contracts/strategy.interface.ts"],"names":[],"mappings":""}

package/dist/balancer/core/load-balancer.d.ts

@@ -0,0 +1,21 @@
+import type { LoadBalancerOptions } from "../../types/balancer.types.js";
+import type { IStrategy } from "../contracts/strategy.interface.js";
+export declare class LoadBalancer {
+    private strategy;
+    private ewmaAlpha;
+    private slowStartSeconds;
+    private circuitBreakerConfig;
+    private states;
+    constructor(options: LoadBalancerOptions, strategy: IStrategy);
+    addUpstream(id: string, url: string, weight?: number, maxConnections?: number): void;
+    removeUpstream(id: string): void;
+    setHealthy(id: string, healthy: boolean): void;
+    incrementConnection(id: string): void;
+    releaseConnection(id: string): void;
+    recordSuccess(id: string, latencyMs?: number): void;
+    recordFailure(id: string): void;
+    pickFiltered(healthyIds: Set<string>, clientIp?: string, attemptedIds?: Set<string>, cookies?: string): string | null;
+    getStats(): any[];
+    private notifyStrategy;
+}
+//# sourceMappingURL=load-balancer.d.ts.map

package/dist/balancer/core/load-balancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-balancer.d.ts","sourceRoot":"","sources":["../../../src/balancer/core/load-balancer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAMzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEpE,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,MAAM,CAAoC;gBAEtC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,SAAS;IAoCtD,WAAW,CAChB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,MAAM,SAAI,EACV,cAAc,CAAC,EAAE,MAAM;IA2BlB,cAAc,CAAC,EAAE,EAAE,MAAM;IAKzB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IAyBvC,mBAAmB,CAAC,EAAE,EAAE,MAAM;IAI9B,iBAAiB,CAAC,EAAE,EAAE,MAAM;IAI5B,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,SAAI;IAuCvC,aAAa,CAAC,EAAE,EAAE,MAAM;IAsBxB,YAAY,CACjB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,cAAoB,EAChC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,IAAI;IAqCT,QAAQ,IAAI,GAAG,EAAE;IAsBxB,OAAO,CAAC,cAAc;CAKvB"}

package/dist/balancer/core/load-balancer.js

@@ -0,0 +1,188 @@
+import { logger } from "../../observability/logger/logger.js";
+import { circuitBreakerManager } from "../../resilience/circuit-breaker/circuit-breaker.manager.js";
+import { ClassicCircuitBreaker } from "../../resilience/circuit-breaker/classic.circuit-breaker.js";
+import { AdaptiveCircuitBreaker } from "../../resilience/circuit-breaker/adaptive.circuit-breaker.js";
+export class LoadBalancer {
+    strategy;
+    ewmaAlpha;
+    slowStartSeconds;
+    circuitBreakerConfig;
+    states = new Map();
+    constructor(options, strategy) {
+        this.strategy = strategy;
+        this.ewmaAlpha = options.ewmaAlpha ?? 0.1;
+        this.slowStartSeconds = options.slowStartSeconds ?? 30;
+        this.circuitBreakerConfig = options.circuitBreaker ?? {
+            mode: "classic",
+            failureThreshold: options.failureThreshold ?? 3,
+            recoveryTimeMs: options.recoveryTimeMs ?? 15000,
+            K: 2,
+            windowMs: 10000,
+        };
+        for (const upstream of options.upstreams) {
+            this.states.set(upstream.id, {
+                id: upstream.id,
+                weight: upstream.weight ?? 1,
+                activeConnections: 0,
+                failures: 0,
+                state: "CLOSED",
+                lastFailureTime: 0,
+                responseTime: 10,
+                healthy: true,
+                requests: 0,
+                accepts: 0,
+                slowStartEndTime: 0,
+                maxConnections: upstream.maxConnections,
+                currentWeight: 0,
+            });
+            circuitBreakerManager.getOrCreate(upstream.id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+        }
+        this.notifyStrategy();
+    }
+    addUpstream(id, url, weight = 1, maxConnections) {
+        if (this.states.has(id))
+            return;
+        this.states.set(id, {
+            id,
+            url,
+            activeConnections: 0,
+            failures: 0,
+            lastFailureTime: 0,
+            state: "CLOSED",
+            healthy: true,
+            weight,
+            responseTime: 10,
+            totalBytes: 0,
+            requests: 0,
+            accepts: 0,
+            slowStartEndTime: 0,
+            maxConnections,
+            currentWeight: 0,
+        });
+        circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+        this.notifyStrategy();
+    }
+    removeUpstream(id) {
+        if (this.states.delete(id)) {
+            this.notifyStrategy();
+        }
+    }
+    setHealthy(id, healthy) {
+        const s = this.states.get(id);
+        if (!s)
+            return;
+        if (s.healthy !== healthy) {
+            logger.info("LoadBalancer", `Upstream health changed: ${id} -> ${healthy ? "HEALTHY" : "UNHEALTHY"}`);
+            s.healthy = healthy;
+            if (healthy) {
+                const cb = circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+                if (cb instanceof ClassicCircuitBreaker &&
+                    cb.getState() === "OPEN") {
+                    cb.recordSuccess(0);
+                }
+                s.slowStartEndTime = Date.now() + this.slowStartSeconds * 1000;
+            }
+        }
+    }
+    incrementConnection(id) {
+        const s = this.states.get(id);
+        if (s)
+            s.activeConnections++;
+    }
+    releaseConnection(id) {
+        const s = this.states.get(id);
+        if (s && s.activeConnections > 0)
+            s.activeConnections--;
+    }
+    recordSuccess(id, latencyMs = 0) {
+        const s = this.states.get(id);
+        if (!s)
+            return;
+        s.responseTime =
+            this.ewmaAlpha * latencyMs + (1 - this.ewmaAlpha) * s.responseTime;
+        const cb = circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+        const prevState = cb instanceof ClassicCircuitBreaker ? cb.getState() : "CLOSED";
+        cb.recordSuccess(latencyMs);
+        const postState = cb instanceof ClassicCircuitBreaker ? cb.getState() : "CLOSED";
+        if (cb instanceof ClassicCircuitBreaker &&
+            (prevState === "OPEN" || prevState === "HALF_OPEN") &&
+            postState === "CLOSED") {
+            logger.info("CircuitBreaker", `${id} restored to CLOSED state`);
+            s.slowStartEndTime = 0;
+            let totalWeight = 0;
+            for (const [, state] of this.states) {
+                const peerCb = circuitBreakerManager.getOrCreate(state.id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+                const peerOpen = peerCb instanceof ClassicCircuitBreaker &&
+                    peerCb.getState() === "OPEN";
+                if (state.healthy && !peerOpen) {
+                    totalWeight += state.weight;
+                }
+            }
+            s.currentWeight -= totalWeight;
+        }
+    }
+    recordFailure(id) {
+        const s = this.states.get(id);
+        if (!s)
+            return;
+        const cb = circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+        const prevState = cb instanceof ClassicCircuitBreaker ? cb.getState() : "CLOSED";
+        cb.recordFailure();
+        const postState = cb instanceof ClassicCircuitBreaker ? cb.getState() : "CLOSED";
+        if (cb instanceof ClassicCircuitBreaker &&
+            prevState !== "OPEN" &&
+            postState === "OPEN") {
+            logger.warn("CircuitBreaker", `${id} tripped to OPEN state`);
+        }
+    }
+    pickFiltered(healthyIds, clientIp, attemptedIds = new Set(), cookies) {
+        const candidates = [];
+        for (const [id, s] of this.states.entries()) {
+            if (!healthyIds.has(id) || !s.healthy)
+                continue;
+            if (attemptedIds.has(id))
+                continue;
+            const cb = circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+            if (!cb.isAllowed())
+                continue;
+            if (s.maxConnections !== undefined &&
+                s.activeConnections >= s.maxConnections) {
+                continue;
+            }
+            candidates.push(s);
+        }
+        if (candidates.length === 0)
+            return null;
+        const halfOpenCandidates = candidates.filter((s) => {
+            const cb = circuitBreakerManager.getOrCreate(s.id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+            return (cb instanceof ClassicCircuitBreaker && cb.getState() === "HALF_OPEN");
+        });
+        if (halfOpenCandidates.length > 0) {
+            return halfOpenCandidates[0].id;
+        }
+        const chosen = this.strategy.pick(candidates, clientIp, cookies);
+        return chosen ? chosen.id : null;
+    }
+    getStats() {
+        const list = [];
+        for (const [id, s] of this.states.entries()) {
+            const cb = circuitBreakerManager.getOrCreate(id, this.circuitBreakerConfig.mode, this.circuitBreakerConfig);
+            list.push({
+                id,
+                activeConnections: s.activeConnections,
+                failures: cb instanceof ClassicCircuitBreaker ? cb.getFailures() : 0,
+                state: cb instanceof ClassicCircuitBreaker ? cb.getState() : "CLOSED",
+                responseTime: s.responseTime,
+                healthy: s.healthy,
+                ...(cb instanceof AdaptiveCircuitBreaker ? { adaptiveStats: cb.getStats() } : {}),
+            });
+        }
+        return list;
+    }
+    notifyStrategy() {
+        if (this.strategy.onUpstreamsChanged) {
+            this.strategy.onUpstreamsChanged([...this.states.values()]);
+        }
+    }
+}
+//# sourceMappingURL=load-balancer.js.map