@olane/o-node 0.7.12-alpha.4 → 0.7.12-alpha.41

package/dist/src/utils/circuit-breaker.test.js

@@ -0,0 +1,262 @@
+import { expect } from 'chai';
+import { CircuitBreaker, CircuitState } from './circuit-breaker.js';
+describe('CircuitBreaker', () => {
+    let breaker;
+    beforeEach(() => {
+        breaker = new CircuitBreaker('test-service', {
+            enabled: true,
+            failureThreshold: 3,
+            openTimeoutMs: 1000,
+            halfOpenMaxAttempts: 1,
+        });
+    });
+    describe('State Transitions', () => {
+        it('should start in CLOSED state', () => {
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+        });
+        it('should transition to OPEN after threshold failures', () => {
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+            // Record failures up to threshold
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+            // Third failure should open circuit
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+            expect(breaker.shouldAllowRequest()).to.equal(false);
+        });
+        it('should transition to HALF_OPEN after timeout', async () => {
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+            // Wait for timeout
+            await new Promise((resolve) => setTimeout(resolve, 1100));
+            // Next request should transition to HALF_OPEN
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+            expect(breaker.getState()).to.equal(CircuitState.HALF_OPEN);
+        });
+        it('should transition from HALF_OPEN to CLOSED on success', async () => {
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Wait and transition to HALF_OPEN
+            await new Promise((resolve) => setTimeout(resolve, 1100));
+            breaker.shouldAllowRequest();
+            // Success should close circuit
+            breaker.recordSuccess();
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+        });
+        it('should transition from HALF_OPEN to OPEN on failure', async () => {
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Wait and transition to HALF_OPEN
+            await new Promise((resolve) => setTimeout(resolve, 1100));
+            breaker.shouldAllowRequest();
+            expect(breaker.getState()).to.equal(CircuitState.HALF_OPEN);
+            // Failure should reopen circuit
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+        });
+    });
+    describe('Request Gating', () => {
+        it('should allow all requests in CLOSED state', () => {
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+        });
+        it('should block all requests in OPEN state', () => {
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.shouldAllowRequest()).to.equal(false);
+        });
+        it('should limit requests in HALF_OPEN state', async () => {
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Wait and transition to HALF_OPEN
+            await new Promise((resolve) => setTimeout(resolve, 1100));
+            // First request allowed
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+            expect(breaker.getState()).to.equal(CircuitState.HALF_OPEN);
+            // Subsequent requests blocked until result recorded
+            expect(breaker.shouldAllowRequest()).to.equal(false);
+        });
+    });
+    describe('Failure Tracking', () => {
+        it('should track consecutive failures', () => {
+            breaker.recordFailure();
+            expect(breaker.getStats().consecutiveFailures).to.equal(1);
+            breaker.recordFailure();
+            expect(breaker.getStats().consecutiveFailures).to.equal(2);
+            breaker.recordFailure();
+            expect(breaker.getStats().consecutiveFailures).to.equal(3);
+        });
+        it('should reset consecutive failures on success', () => {
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getStats().consecutiveFailures).to.equal(2);
+            breaker.recordSuccess();
+            expect(breaker.getStats().consecutiveFailures).to.equal(0);
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+        });
+        it('should track total failures and successes', () => {
+            breaker.recordFailure();
+            breaker.recordSuccess();
+            breaker.recordFailure();
+            breaker.recordSuccess();
+            const stats = breaker.getStats();
+            expect(stats.totalFailures).to.equal(2);
+            expect(stats.totalSuccesses).to.equal(2);
+        });
+        it('should track timestamps', () => {
+            const beforeFailure = Date.now();
+            breaker.recordFailure();
+            const afterFailure = Date.now();
+            const stats = breaker.getStats();
+            expect(stats.lastFailureTime).greaterThanOrEqual(beforeFailure);
+            expect(stats.lastFailureTime).lessThanOrEqual(afterFailure);
+            const beforeSuccess = Date.now();
+            breaker.recordSuccess();
+            const afterSuccess = Date.now();
+            const stats2 = breaker.getStats();
+            expect(stats2.lastSuccessTime).greaterThanOrEqual(beforeSuccess);
+            expect(stats2.lastSuccessTime).lessThanOrEqual(afterSuccess);
+        });
+    });
+    describe('Configuration', () => {
+        it('should respect custom failure threshold', () => {
+            const customBreaker = new CircuitBreaker('test', {
+                enabled: true,
+                failureThreshold: 5,
+                openTimeoutMs: 1000,
+                halfOpenMaxAttempts: 1,
+            });
+            // Should not open before threshold
+            customBreaker.recordFailure();
+            customBreaker.recordFailure();
+            customBreaker.recordFailure();
+            customBreaker.recordFailure();
+            expect(customBreaker.getState()).to.equal(CircuitState.CLOSED);
+            // Should open at threshold
+            customBreaker.recordFailure();
+            expect(customBreaker.getState()).to.equal(CircuitState.OPEN);
+        });
+        it('should respect custom half-open attempts', async () => {
+            const customBreaker = new CircuitBreaker('test', {
+                enabled: true,
+                failureThreshold: 2,
+                openTimeoutMs: 100,
+                halfOpenMaxAttempts: 3,
+            });
+            // Open circuit
+            customBreaker.recordFailure();
+            customBreaker.recordFailure();
+            // Wait for timeout
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            // Should allow 3 attempts in HALF_OPEN
+            expect(customBreaker.shouldAllowRequest()).to.equal(true);
+            expect(customBreaker.shouldAllowRequest()).to.equal(true);
+            expect(customBreaker.shouldAllowRequest()).to.equal(true);
+            expect(customBreaker.shouldAllowRequest()).to.equal(false);
+        });
+        it('should bypass all logic when disabled', () => {
+            const disabledBreaker = new CircuitBreaker('test', {
+                enabled: false,
+                failureThreshold: 1,
+                openTimeoutMs: 1000,
+                halfOpenMaxAttempts: 1,
+            });
+            // Record many failures
+            disabledBreaker.recordFailure();
+            disabledBreaker.recordFailure();
+            disabledBreaker.recordFailure();
+            // Should still allow requests
+            expect(disabledBreaker.shouldAllowRequest()).to.equal(true);
+            expect(disabledBreaker.getState()).to.equal(CircuitState.CLOSED);
+        });
+    });
+    describe('Manual Control', () => {
+        it('should reset to CLOSED state', () => {
+            // Open circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+            // Reset
+            breaker.reset();
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+            expect(breaker.getStats().consecutiveFailures).to.equal(0);
+            expect(breaker.shouldAllowRequest()).to.equal(true);
+        });
+    });
+    describe('Statistics', () => {
+        it('should provide comprehensive stats', () => {
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordSuccess();
+            const stats = breaker.getStats();
+            expect(stats).to.have.property('state');
+            expect(stats).to.have.property('consecutiveFailures');
+            expect(stats).to.have.property('totalFailures');
+            expect(stats).to.have.property('totalSuccesses');
+            expect(stats).to.have.property('lastFailureTime');
+            expect(stats).to.have.property('lastSuccessTime');
+            expect(stats).to.have.property('openedAt');
+            expect(stats.state).to.equal(CircuitState.CLOSED);
+            expect(stats.consecutiveFailures).to.equal(0);
+            expect(stats.totalFailures).to.equal(2);
+            expect(stats.totalSuccesses).to.equal(1);
+        });
+        it('should track openedAt timestamp', () => {
+            const before = Date.now();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            const after = Date.now();
+            const stats = breaker.getStats();
+            expect(stats.openedAt).greaterThanOrEqual(before);
+            expect(stats.openedAt).lessThanOrEqual(after);
+        });
+    });
+    describe('Edge Cases', () => {
+        it('should handle rapid state transitions', async () => {
+            // Open
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+            // Wait for HALF_OPEN
+            await new Promise((resolve) => setTimeout(resolve, 1100));
+            breaker.shouldAllowRequest();
+            expect(breaker.getState()).to.equal(CircuitState.HALF_OPEN);
+            // Close
+            breaker.recordSuccess();
+            expect(breaker.getState()).to.equal(CircuitState.CLOSED);
+            // Open again
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+        });
+        it('should not open before timeout expires in OPEN state', async () => {
+            // Open circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+            // Wait less than timeout
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            // Should still be closed
+            expect(breaker.shouldAllowRequest()).to.equal(false);
+            expect(breaker.getState()).to.equal(CircuitState.OPEN);
+        });
+    });
+});

package/dist/src/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './stream.utils.js';
+export * from './network.utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/src/utils/index.js

@@ -0,0 +1,2 @@
+export * from './stream.utils.js';
+export * from './network.utils.js';

package/dist/src/utils/leader-request-wrapper.d.ts

@@ -0,0 +1,66 @@
+import { oObject, oAddress } from '@olane/o-core';
+import { CircuitBreakerConfig } from './circuit-breaker.js';
+export interface LeaderRetryConfig {
+    enabled: boolean;
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    timeoutMs: number;
+    circuitBreaker?: CircuitBreakerConfig;
+}
+/**
+ * Leader Request Wrapper
+ *
+ * Wraps requests to leader/registry with retry logic and circuit breaker.
+ * Used when leader may be temporarily unavailable (healing, maintenance).
+ *
+ * Strategy:
+ * 1. Detect if request is to leader or registry
+ * 2. Check circuit breaker state (fast-fail if open)
+ * 3. Apply retry logic with exponential backoff
+ * 4. Timeout individual attempts
+ * 5. Record success/failure in circuit breaker
+ * 6. Log retries for observability
+ */
+export declare class LeaderRequestWrapper extends oObject {
+    private config;
+    private leaderCircuitBreaker;
+    private registryCircuitBreaker;
+    constructor(config: LeaderRetryConfig);
+    /**
+     * Check if address is a leader-related address that needs retry
+     */
+    private isLeaderAddress;
+    /**
+     * Get the appropriate circuit breaker for the address
+     */
+    private getCircuitBreaker;
+    /**
+     * Execute request with retry logic and circuit breaker
+     */
+    execute<T>(requestFn: () => Promise<T>, address: oAddress, context?: string): Promise<T>;
+    /**
+     * Calculate exponential backoff delay
+     */
+    private calculateBackoffDelay;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+    /**
+     * Get current configuration
+     */
+    getConfig(): LeaderRetryConfig;
+    /**
+     * Get circuit breaker statistics for observability
+     */
+    getCircuitBreakerStats(): {
+        leader: import("./circuit-breaker.js").CircuitStats;
+        registry: import("./circuit-breaker.js").CircuitStats;
+    };
+    /**
+     * Reset circuit breakers (for testing or manual recovery)
+     */
+    resetCircuitBreakers(): void;
+}
+//# sourceMappingURL=leader-request-wrapper.d.ts.map

package/dist/src/utils/leader-request-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-request-wrapper.d.ts","sourceRoot":"","sources":["../../../src/utils/leader-request-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAuB,MAAM,eAAe,CAAC;AACvE,OAAO,EAEL,oBAAoB,EAErB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAInC,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,oBAAoB,CAAiB;IAC7C,OAAO,CAAC,sBAAsB,CAAiB;gBAE3B,MAAM,EAAE,iBAAiB;IAuB7C;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;IACG,OAAO,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC;IA2Gb;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,SAAS,IAAI,iBAAiB;IAI9B;;OAEG;IACH,sBAAsB;;;;IAOtB;;OAEG;IACH,oBAAoB,IAAI,IAAI;CAI7B"}

package/dist/src/utils/leader-request-wrapper.js

@@ -0,0 +1,160 @@
+import { oObject } from '@olane/o-core';
+import { CircuitBreaker, CircuitState, } from './circuit-breaker.js';
+/**
+ * Leader Request Wrapper
+ *
+ * Wraps requests to leader/registry with retry logic and circuit breaker.
+ * Used when leader may be temporarily unavailable (healing, maintenance).
+ *
+ * Strategy:
+ * 1. Detect if request is to leader or registry
+ * 2. Check circuit breaker state (fast-fail if open)
+ * 3. Apply retry logic with exponential backoff
+ * 4. Timeout individual attempts
+ * 5. Record success/failure in circuit breaker
+ * 6. Log retries for observability
+ */
+export class LeaderRequestWrapper extends oObject {
+    constructor(config) {
+        super();
+        this.config = config;
+        // Initialize circuit breakers with defaults if not provided
+        const defaultCircuitBreakerConfig = {
+            failureThreshold: 3,
+            openTimeoutMs: 30000, // 30 seconds
+            halfOpenMaxAttempts: 1,
+            enabled: true,
+        };
+        const circuitConfig = {
+            ...defaultCircuitBreakerConfig,
+            ...(config.circuitBreaker || {}),
+        };
+        this.leaderCircuitBreaker = new CircuitBreaker('leader', circuitConfig);
+        this.registryCircuitBreaker = new CircuitBreaker('registry', circuitConfig);
+    }
+    /**
+     * Check if address is a leader-related address that needs retry
+     */
+    isLeaderAddress(address) {
+        const addressStr = address.toString();
+        return addressStr === 'o://leader' || addressStr === 'o://registry';
+    }
+    /**
+     * Get the appropriate circuit breaker for the address
+     */
+    getCircuitBreaker(address) {
+        const addressStr = address.toString();
+        if (addressStr === 'o://leader') {
+            return this.leaderCircuitBreaker;
+        }
+        if (addressStr === 'o://registry') {
+            return this.registryCircuitBreaker;
+        }
+        return null;
+    }
+    /**
+     * Execute request with retry logic and circuit breaker
+     */
+    async execute(requestFn, address, context) {
+        // If retry disabled or not a leader address, execute directly
+        if (!this.config.enabled || !this.isLeaderAddress(address)) {
+            return await requestFn();
+        }
+        const circuitBreaker = this.getCircuitBreaker(address);
+        // Check circuit breaker state before attempting
+        if (circuitBreaker && !circuitBreaker.shouldAllowRequest()) {
+            const stats = circuitBreaker.getStats();
+            const error = new Error(`Circuit breaker is ${stats.state} for ${address.toString()}. ` +
+                `Consecutive failures: ${stats.consecutiveFailures}. ` +
+                `Fast-failing to prevent cascading failures.`);
+            this.logger.warn(`Circuit breaker blocked request to ${address.toString()}` +
+                (context ? ` (${context})` : ''));
+            throw error;
+        }
+        let attempt = 0;
+        let lastError;
+        while (attempt < this.config.maxAttempts) {
+            attempt++;
+            try {
+                if (attempt > 5) {
+                    this.logger.debug(`Retrying... Leader request attempt ${attempt}/${this.config.maxAttempts}` +
+                        (context ? ` (${context})` : ''));
+                }
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error(`Leader request timeout after ${this.config.timeoutMs}ms`)), this.config.timeoutMs);
+                });
+                // Race between request and timeout
+                const result = await Promise.race([requestFn(), timeoutPromise]);
+                // Success! Record in circuit breaker
+                if (circuitBreaker) {
+                    circuitBreaker.recordSuccess();
+                }
+                if (attempt > 1) {
+                    this.logger.info(`Leader request succeeded after ${attempt} attempts` +
+                        (context ? ` (${context})` : ''));
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Record failure in circuit breaker
+                if (circuitBreaker) {
+                    circuitBreaker.recordFailure();
+                }
+                this.logger.warn(`Leader request attempt ${attempt} failed: ${lastError.message}` +
+                    (context ? ` (${context})` : ''));
+                // Check if circuit breaker has opened during retries
+                if (circuitBreaker && circuitBreaker.getState() === CircuitState.OPEN) {
+                    this.logger.error(`Circuit breaker opened during retries for ${address.toString()}, stopping retry attempts` +
+                        (context ? ` (${context})` : ''));
+                    throw new Error(`Circuit breaker opened after ${attempt} attempts: ${lastError.message}`);
+                }
+                if (attempt < this.config.maxAttempts) {
+                    const delay = this.calculateBackoffDelay(attempt);
+                    this.logger.debug(`Waiting ${delay}ms before next attempt...`);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All attempts failed
+        this.logger.error(`Leader request failed after ${this.config.maxAttempts} attempts` +
+            (context ? ` (${context})` : ''));
+        throw lastError || new Error('Leader request failed');
+    }
+    /**
+     * Calculate exponential backoff delay
+     */
+    calculateBackoffDelay(attempt) {
+        const delay = this.config.baseDelayMs * Math.pow(2, attempt - 1);
+        return Math.min(delay, this.config.maxDelayMs);
+    }
+    /**
+     * Sleep utility
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get circuit breaker statistics for observability
+     */
+    getCircuitBreakerStats() {
+        return {
+            leader: this.leaderCircuitBreaker.getStats(),
+            registry: this.registryCircuitBreaker.getStats(),
+        };
+    }
+    /**
+     * Reset circuit breakers (for testing or manual recovery)
+     */
+    resetCircuitBreakers() {
+        this.leaderCircuitBreaker.reset();
+        this.registryCircuitBreaker.reset();
+    }
+}

package/dist/src/utils/leader-request-wrapper.test.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=leader-request-wrapper.test.d.ts.map

package/dist/src/utils/leader-request-wrapper.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-request-wrapper.test.d.ts","sourceRoot":"","sources":["../../../src/utils/leader-request-wrapper.test.ts"],"names":[],"mappings":""}