@olane/o-node 0.7.12-alpha.3 → 0.7.12-alpha.31

package/dist/o-node/src/streaming/node-stream-handler.js

@@ -0,0 +1,101 @@
+import { StreamHandlerBase, ProtocolBuilder, } from '../../../o-core/src/streaming/index.js';
+/**
+ * o-node specific implementation of StreamHandlerBase.
+ * Integrates with libp2p streams and tracks metrics for o-node tools.
+ */
+export class NodeStreamHandler extends StreamHandlerBase {
+    constructor(transport, options = {}) {
+        super(options);
+        this.successCount = 0;
+        this.errorCount = 0;
+        this.transport = transport;
+        this.nodeOptions = {
+            trackSuccessCount: true,
+            trackErrorCount: true,
+            ...options,
+        };
+    }
+    /**
+     * Get the success count (number of chunks successfully sent)
+     */
+    getSuccessCount() {
+        return this.successCount;
+    }
+    /**
+     * Get the error count
+     */
+    getErrorCount() {
+        return this.errorCount;
+    }
+    /**
+     * Reset metrics
+     */
+    resetMetrics() {
+        this.successCount = 0;
+        this.errorCount = 0;
+    }
+    /**
+     * Implementation of sendChunk using libp2p transport and protocol builder
+     */
+    async sendChunk(chunk, sequence, isLast, request) {
+        // Build the JSON-RPC streaming chunk message
+        const message = ProtocolBuilder.buildStreamChunkFromRequest(chunk, sequence, isLast, request);
+        // Encode the message to bytes
+        const encoded = ProtocolBuilder.encodeMessage(message);
+        // Send through the transport (handles backpressure)
+        await this.transport.send(encoded);
+        // Track metrics if enabled
+        if (this.nodeOptions.trackSuccessCount) {
+            this.successCount++;
+        }
+        // Close the stream if this is the last chunk
+        if (isLast) {
+            await this.transport.close();
+        }
+    }
+    /**
+     * Hook: Called when streaming starts
+     */
+    onStreamStart(request) {
+        // Reset metrics for this stream
+        if (this.nodeOptions.enableMetrics) {
+            this.resetMetrics();
+        }
+    }
+    /**
+     * Hook: Called when streaming completes successfully
+     */
+    onStreamComplete(request, totalChunks) {
+        // Log completion if metrics enabled
+        if (this.nodeOptions.enableMetrics) {
+            console.log(`Stream completed for ${request.method}: ${totalChunks} chunks sent`);
+        }
+    }
+    /**
+     * Hook: Called when streaming encounters an error
+     */
+    onStreamError(request, error) {
+        // Track error count
+        if (this.nodeOptions.trackErrorCount) {
+            this.errorCount++;
+        }
+        // Log error
+        console.error(`Stream error for ${request.method}:`, error);
+    }
+    /**
+     * Reset the handler for reuse with a new transport
+     */
+    reset() {
+        // Call parent reset
+        this.state = 0; // Reset state (IDLE)
+        this.currentSequence = 0;
+        this.resetMetrics();
+    }
+    /**
+     * Create a new NodeStreamHandler with a different transport
+     * (useful for handling multiple streams)
+     */
+    static create(transport, options) {
+        return new NodeStreamHandler(transport, options);
+    }
+}

package/dist/o-node/src/utils/circuit-breaker.d.ts

@@ -0,0 +1,107 @@
+import { oObject } from '@olane/o-core';
+export declare enum CircuitState {
+    CLOSED = "CLOSED",// Normal operation, requests pass through
+    OPEN = "OPEN",// Circuit broken, requests fast-fail
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerConfig {
+    failureThreshold: number;
+    openTimeoutMs: number;
+    halfOpenMaxAttempts: number;
+    enabled: boolean;
+}
+export interface CircuitStats {
+    state: CircuitState;
+    consecutiveFailures: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    openedAt?: number;
+}
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Prevents cascading failures by "breaking the circuit" when a service
+ * experiences persistent failures. This allows the system to fail fast
+ * rather than wasting resources on retries that are likely to fail.
+ *
+ * States:
+ * - CLOSED: Normal operation, all requests pass through
+ * - OPEN: Circuit broken due to failures, requests fail immediately
+ * - HALF_OPEN: Testing recovery, limited requests allowed
+ *
+ * Flow:
+ * 1. CLOSED -> OPEN: After N consecutive failures
+ * 2. OPEN -> HALF_OPEN: After timeout period
+ * 3. HALF_OPEN -> CLOSED: After successful request
+ * 4. HALF_OPEN -> OPEN: After failure in recovery
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker('registry', {
+ *   failureThreshold: 3,
+ *   openTimeoutMs: 30000,
+ *   halfOpenMaxAttempts: 1,
+ *   enabled: true,
+ * });
+ *
+ * // Before making request
+ * if (!breaker.shouldAllowRequest()) {
+ *   throw new Error('Circuit breaker is open');
+ * }
+ *
+ * try {
+ *   const result = await makeRequest();
+ *   breaker.recordSuccess();
+ *   return result;
+ * } catch (error) {
+ *   breaker.recordFailure();
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class CircuitBreaker extends oObject {
+    private readonly serviceName;
+    private readonly config;
+    private state;
+    private consecutiveFailures;
+    private totalFailures;
+    private totalSuccesses;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private openedAt?;
+    private halfOpenAttempts;
+    constructor(serviceName: string, config: CircuitBreakerConfig);
+    /**
+     * Check if a request should be allowed through the circuit breaker
+     * @returns true if request should proceed, false if should fast-fail
+     */
+    shouldAllowRequest(): boolean;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): CircuitStats;
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Force reset the circuit breaker to CLOSED state
+     * Use with caution - mainly for testing or manual recovery
+     */
+    reset(): void;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/o-node/src/utils/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../../src/utils/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,oBAAY,YAAY;IACtB,MAAM,WAAW,CAAE,0CAA0C;IAC7D,IAAI,SAAS,CAAE,qCAAqC;IACpD,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,cAAe,SAAQ,OAAO;IAWvC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXzB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAa;gBAGlB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,oBAAoB;IAW/C;;;OAGG;IACH,kBAAkB,IAAI,OAAO;IA2C7B;;OAEG;IACH,aAAa,IAAI,IAAI;IAkBrB;;OAEG;IACH,aAAa,IAAI,IAAI;IA+BrB;;OAEG;IACH,QAAQ,IAAI,YAAY;IAYxB;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,OAAO,CAAC,YAAY;CAOrB"}

package/dist/o-node/src/utils/circuit-breaker.js

@@ -0,0 +1,175 @@
+import { oObject } from '@olane/o-core';
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Prevents cascading failures by "breaking the circuit" when a service
+ * experiences persistent failures. This allows the system to fail fast
+ * rather than wasting resources on retries that are likely to fail.
+ *
+ * States:
+ * - CLOSED: Normal operation, all requests pass through
+ * - OPEN: Circuit broken due to failures, requests fail immediately
+ * - HALF_OPEN: Testing recovery, limited requests allowed
+ *
+ * Flow:
+ * 1. CLOSED -> OPEN: After N consecutive failures
+ * 2. OPEN -> HALF_OPEN: After timeout period
+ * 3. HALF_OPEN -> CLOSED: After successful request
+ * 4. HALF_OPEN -> OPEN: After failure in recovery
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker('registry', {
+ *   failureThreshold: 3,
+ *   openTimeoutMs: 30000,
+ *   halfOpenMaxAttempts: 1,
+ *   enabled: true,
+ * });
+ *
+ * // Before making request
+ * if (!breaker.shouldAllowRequest()) {
+ *   throw new Error('Circuit breaker is open');
+ * }
+ *
+ * try {
+ *   const result = await makeRequest();
+ *   breaker.recordSuccess();
+ *   return result;
+ * } catch (error) {
+ *   breaker.recordFailure();
+ *   throw error;
+ * }
+ * ```
+ */
+export class CircuitBreaker extends oObject {
+    constructor(serviceName, config) {
+        super();
+        this.serviceName = serviceName;
+        this.config = config;
+        this.state = CircuitState.CLOSED;
+        this.consecutiveFailures = 0;
+        this.totalFailures = 0;
+        this.totalSuccesses = 0;
+        this.halfOpenAttempts = 0;
+        this.logger.debug(`Circuit breaker initialized for ${serviceName}:`, `threshold=${config.failureThreshold},`, `timeout=${config.openTimeoutMs}ms,`, `enabled=${config.enabled}`);
+    }
+    /**
+     * Check if a request should be allowed through the circuit breaker
+     * @returns true if request should proceed, false if should fast-fail
+     */
+    shouldAllowRequest() {
+        if (!this.config.enabled) {
+            return true;
+        }
+        const now = Date.now();
+        switch (this.state) {
+            case CircuitState.CLOSED:
+                return true;
+            case CircuitState.OPEN:
+                // Check if timeout period has elapsed
+                if (this.openedAt &&
+                    now - this.openedAt >= this.config.openTimeoutMs) {
+                    this.logger.info(`Circuit breaker for ${this.serviceName} entering HALF_OPEN state`);
+                    this.transitionTo(CircuitState.HALF_OPEN);
+                    this.halfOpenAttempts = 0;
+                    return true;
+                }
+                // Circuit still open, fast-fail
+                this.logger.debug(`Circuit breaker for ${this.serviceName} is OPEN, rejecting request`);
+                return false;
+            case CircuitState.HALF_OPEN:
+                // Allow limited attempts in HALF_OPEN state
+                if (this.halfOpenAttempts < this.config.halfOpenMaxAttempts) {
+                    this.halfOpenAttempts++;
+                    return true;
+                }
+                this.logger.debug(`Circuit breaker for ${this.serviceName} HALF_OPEN max attempts reached`);
+                return false;
+        }
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess() {
+        if (!this.config.enabled) {
+            return;
+        }
+        this.totalSuccesses++;
+        this.lastSuccessTime = Date.now();
+        this.consecutiveFailures = 0;
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.logger.info(`Circuit breaker for ${this.serviceName} recovered, closing circuit`);
+            this.transitionTo(CircuitState.CLOSED);
+            this.halfOpenAttempts = 0;
+        }
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure() {
+        if (!this.config.enabled) {
+            return;
+        }
+        this.totalFailures++;
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.logger.warn(`Circuit breaker for ${this.serviceName} failed in HALF_OPEN, reopening circuit`);
+            this.transitionTo(CircuitState.OPEN);
+            this.openedAt = Date.now();
+            this.halfOpenAttempts = 0;
+            return;
+        }
+        if (this.state === CircuitState.CLOSED &&
+            this.consecutiveFailures >= this.config.failureThreshold) {
+            this.logger.error(`Circuit breaker for ${this.serviceName} opening after ${this.consecutiveFailures} consecutive failures`);
+            this.transitionTo(CircuitState.OPEN);
+            this.openedAt = Date.now();
+        }
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return {
+            state: this.state,
+            consecutiveFailures: this.consecutiveFailures,
+            totalFailures: this.totalFailures,
+            totalSuccesses: this.totalSuccesses,
+            lastFailureTime: this.lastFailureTime,
+            lastSuccessTime: this.lastSuccessTime,
+            openedAt: this.openedAt,
+        };
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Force reset the circuit breaker to CLOSED state
+     * Use with caution - mainly for testing or manual recovery
+     */
+    reset() {
+        this.logger.info(`Circuit breaker for ${this.serviceName} manually reset`);
+        this.transitionTo(CircuitState.CLOSED);
+        this.consecutiveFailures = 0;
+        this.halfOpenAttempts = 0;
+        this.openedAt = undefined;
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.logger.debug(`Circuit breaker for ${this.serviceName}: ${oldState} -> ${newState}`);
+    }
+}

package/dist/o-node/src/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from './stream.utils.js';
+export * from './network.utils.js';
+export * from './circuit-breaker.js';
+export * from './leader-request-wrapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/o-node/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;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC"}

package/dist/o-node/src/utils/index.js

@@ -0,0 +1,4 @@
+export * from './stream.utils.js';
+export * from './network.utils.js';
+export * from './circuit-breaker.js';
+export * from './leader-request-wrapper.js';

package/dist/o-node/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/o-node/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/o-node/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/o-node/src/utils/network.utils.d.ts

@@ -0,0 +1,20 @@
+import { Libp2p, Multiaddr } from '@olane/o-config';
+import { oObject } from '@olane/o-core';
+import { CID } from 'multiformats';
+import { oNodeAddress } from '../router/o-node.address.js';
+export declare class NetworkUtils extends oObject {
+    static findProviders(p2pNode: Libp2p, cid: CID): Promise<{
+        transports: Multiaddr[];
+        staticAddress: string;
+        absoluteAddress: string;
+    }>;
+    static findNode(p2pNode: Libp2p, address: oNodeAddress): Promise<{
+        transports: Multiaddr[];
+        staticAddress: string;
+        absoluteAddress: string;
+    }>;
+    static advertiseValueToNetwork(value: CID, p2pNode: Libp2p): Promise<void>;
+    static dhtProvide(value: CID, p2pNode: Libp2p): Promise<void>;
+    static advertiseToNetwork(address: oNodeAddress, staticAddress: oNodeAddress, p2pNode: Libp2p): Promise<void>;
+}
+//# sourceMappingURL=network.utils.d.ts.map

package/dist/o-node/src/utils/network.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.utils.d.ts","sourceRoot":"","sources":["../../../../src/utils/network.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,qBAAa,YAAa,SAAQ,OAAO;WACnB,aAAa,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,GAAG,GACP,OAAO,CAAC;QACT,UAAU,EAAE,SAAS,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;WA2BkB,QAAQ,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;QACT,UAAU,EAAE,SAAS,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;WAiBkB,uBAAuB,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM;WAgBnD,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM;WAYtC,kBAAkB,CACpC,OAAO,EAAE,YAAY,EACrB,aAAa,EAAE,YAAY,EAC3B,OAAO,EAAE,MAAM;CAoClB"}