@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/retry-strategies.js

@@ -1 +1,534 @@
-import{err}from"./_deps/shared/index.js";export class ExponentialBackoffStrategy{name="ExponentialBackoff";maxAttempts;initialDelayMs;maxDelayMs;multiplier;jitter;jitterFactor;retryableErrors;constructor(t={}){this.maxAttempts=t.maxAttempts??3,this.initialDelayMs=t.initialDelayMs??1e3,this.maxDelayMs=t.maxDelayMs??3e4,this.multiplier=t.multiplier??2,this.jitter=t.jitter??!0,this.jitterFactor=t.jitterFactor??.2,this.retryableErrors=t.retryableErrors?new Set(t.retryableErrors):new Set(["SEND_FAILED","NETWORK_ERROR","RECIPIENT_UNREACHABLE","TIMEOUT"])}shouldRetry(t){if(t.attempt>=this.maxAttempts)return{shouldRetry:!1,reason:`Maximum attempts (${this.maxAttempts}) exceeded`};if(!this.retryableErrors.has(t.error))return{shouldRetry:!1,reason:`Error type '${t.error}' is not retryable`};const e=this.initialDelayMs*Math.pow(this.multiplier,t.attempt),s=Math.min(e,this.maxDelayMs),r=this.jitter?this.applyJitter(s):s;return{shouldRetry:!0,delayMs:Math.round(r),reason:`Attempt ${t.attempt+1}/${this.maxAttempts}`}}applyJitter(t){const e=new Uint32Array(1);crypto.getRandomValues(e);return t+(2*(e[0]/4294967295)-1)*(t*this.jitterFactor)}}export class LinearBackoffStrategy{name="LinearBackoff";maxAttempts;delayIncrementMs;initialDelayMs;maxDelayMs;jitter;jitterFactor;retryableErrors;constructor(t={}){this.maxAttempts=t.maxAttempts??3,this.delayIncrementMs=t.delayIncrementMs??1e3,this.initialDelayMs=t.initialDelayMs??1e3,this.maxDelayMs=t.maxDelayMs??3e4,this.jitter=t.jitter??!0,this.jitterFactor=t.jitterFactor??.1,this.retryableErrors=t.retryableErrors?new Set(t.retryableErrors):new Set(["SEND_FAILED","NETWORK_ERROR","RECIPIENT_UNREACHABLE","TIMEOUT"])}shouldRetry(t){if(t.attempt>=this.maxAttempts)return{shouldRetry:!1,reason:`Maximum attempts (${this.maxAttempts}) exceeded`};if(!this.retryableErrors.has(t.error))return{shouldRetry:!1,reason:`Error type '${t.error}' is not retryable`};const e=this.initialDelayMs+t.attempt*this.delayIncrementMs,s=Math.min(e,this.maxDelayMs),r=this.jitter?this.applyJitter(s):s;return{shouldRetry:!0,delayMs:Math.round(r),reason:`Attempt ${t.attempt+1}/${this.maxAttempts}`}}applyJitter(t){const e=new Uint32Array(1);crypto.getRandomValues(e);return t+(2*(e[0]/4294967295)-1)*(t*this.jitterFactor)}}export class FixedDelayStrategy{name="FixedDelay";maxAttempts;delayMs;jitter;jitterFactor;retryableErrors;constructor(t={}){this.maxAttempts=t.maxAttempts??3,this.delayMs=t.delayMs??1e3,this.jitter=t.jitter??!1,this.jitterFactor=t.jitterFactor??.1,this.retryableErrors=t.retryableErrors?new Set(t.retryableErrors):new Set(["SEND_FAILED","NETWORK_ERROR","RECIPIENT_UNREACHABLE","TIMEOUT"])}shouldRetry(t){if(t.attempt>=this.maxAttempts)return{shouldRetry:!1,reason:`Maximum attempts (${this.maxAttempts}) exceeded`};if(!this.retryableErrors.has(t.error))return{shouldRetry:!1,reason:`Error type '${t.error}' is not retryable`};const e=this.jitter?this.applyJitter(this.delayMs):this.delayMs;return{shouldRetry:!0,delayMs:Math.round(e),reason:`Attempt ${t.attempt+1}/${this.maxAttempts}`}}applyJitter(t){const e=new Uint32Array(1);crypto.getRandomValues(e);return t+(2*(e[0]/4294967295)-1)*(t*this.jitterFactor)}}export class NoRetryStrategy{name="NoRetry";shouldRetry(t){return{shouldRetry:!1,reason:"No retry policy - fail immediately"}}}export class CircuitBreaker{state="CLOSED";consecutiveFailures=0;consecutiveSuccesses=0;openedAt;totalRequests=0;totalFailures=0;totalSuccesses=0;failureTimestamps=[];failureThreshold;resetTimeoutMs;successThreshold;windowMs;constructor(t={}){this.failureThreshold=t.failureThreshold??5,this.resetTimeoutMs=t.resetTimeoutMs??6e4,this.successThreshold=t.successThreshold??2,this.windowMs=t.windowMs??6e4}allowRequest(){const t=Date.now();return this.failureTimestamps=this.failureTimestamps.filter(e=>t-e<this.windowMs),"CLOSED"===this.state||("OPEN"!==this.state||!!(this.openedAt&&t-this.openedAt>=this.resetTimeoutMs)&&(this.state="HALF_OPEN",this.consecutiveSuccesses=0,!0))}recordSuccess(){this.totalRequests++,this.totalSuccesses++,this.consecutiveFailures=0,"HALF_OPEN"===this.state&&(this.consecutiveSuccesses++,this.consecutiveSuccesses>=this.successThreshold&&(this.state="CLOSED",this.consecutiveSuccesses=0,this.openedAt=void 0))}recordFailure(){this.totalRequests++,this.totalFailures++,this.consecutiveFailures++,this.consecutiveSuccesses=0;const t=Date.now();if(this.failureTimestamps.push(t),"CLOSED"===this.state||"HALF_OPEN"===this.state){this.failureTimestamps.filter(e=>t-e<this.windowMs).length>=this.failureThreshold&&(this.state="OPEN",this.openedAt=t)}}getStats(){return{state:this.state,consecutiveFailures:this.consecutiveFailures,consecutiveSuccesses:this.consecutiveSuccesses,openedAt:this.openedAt,totalRequests:this.totalRequests,totalFailures:this.totalFailures,totalSuccesses:this.totalSuccesses}}reset(){this.state="CLOSED",this.consecutiveFailures=0,this.consecutiveSuccesses=0,this.openedAt=void 0,this.totalRequests=0,this.totalFailures=0,this.totalSuccesses=0,this.failureTimestamps=[]}forceOpen(){this.state="OPEN",this.openedAt=Date.now()}forceClose(){this.state="CLOSED",this.consecutiveFailures=0,this.consecutiveSuccesses=0,this.openedAt=void 0}}export class RetryStrategy{static exponentialBackoff(t){return new ExponentialBackoffStrategy(t)}static linearBackoff(t){return new LinearBackoffStrategy(t)}static fixedDelay(t){return new FixedDelayStrategy(t)}static noRetry(){return new NoRetryStrategy}static aggressive(){return new ExponentialBackoffStrategy({maxAttempts:5,initialDelayMs:500,maxDelayMs:1e4,multiplier:2,jitter:!0})}static conservative(){return new LinearBackoffStrategy({maxAttempts:2,initialDelayMs:2e3,delayIncrementMs:1e3,maxDelayMs:5e3,jitter:!0})}static default(){return new ExponentialBackoffStrategy({maxAttempts:3,initialDelayMs:1e3,maxDelayMs:3e4,multiplier:2,jitter:!0})}}export async function executeWithRetry(t,e,s){const r=Date.now();let i=0,a="NETWORK_ERROR";for(;;){if(s&&!s.allowRequest())return err("SEND_FAILED");const o=await t();if(o.ok)return s?.recordSuccess(),o;a=o.error,s?.recordFailure();const l={attempt:i,error:a,startTime:r,elapsedMs:Date.now()-r},n=e.shouldRetry(l);if(!n.shouldRetry)return err(a);n.delayMs&&n.delayMs>0&&await sleep(n.delayMs),i++}}function sleep(t){return new Promise(e=>setTimeout(e,t))}
+/**
+ * @module retry-strategies
+ * Configurable retry strategies for enhanced reliability.
+ *
+ * Provides flexible retry policies with exponential backoff, jitter, circuit breakers,
+ * and error-specific retry logic. Designed for production-grade fault tolerance.
+ *
+ * @example
+ * ```typescript
+ * import { RetryStrategy, CircuitBreaker } from '@private.me/xbind/retry-strategies';
+ *
+ * // Exponential backoff with circuit breaker
+ * const strategy = RetryStrategy.exponentialBackoff({
+ *   maxAttempts: 5,
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   multiplier: 2,
+ *   jitter: true
+ * });
+ *
+ * const circuitBreaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 60000
+ * });
+ * ```
+ */
+import { err } from"./_deps/shared/index.js";
+/* ── Retry Strategy Implementations ── */
+/**
+ * Exponential backoff retry strategy.
+ *
+ * Delay formula: min(initialDelay * multiplier^attempt, maxDelay) ± jitter
+ *
+ * Best for: Network requests, API calls, database operations.
+ * Avoids overwhelming failing services with exponentially increasing delays.
+ */
+export class ExponentialBackoffStrategy {
+    name = 'ExponentialBackoff';
+    maxAttempts;
+    initialDelayMs;
+    maxDelayMs;
+    multiplier;
+    jitter;
+    jitterFactor;
+    retryableErrors;
+    constructor(config = {}) {
+        this.maxAttempts = config.maxAttempts ?? 3;
+        this.initialDelayMs = config.initialDelayMs ?? 1000;
+        this.maxDelayMs = config.maxDelayMs ?? 30000;
+        this.multiplier = config.multiplier ?? 2;
+        this.jitter = config.jitter ?? true;
+        this.jitterFactor = config.jitterFactor ?? 0.2;
+        this.retryableErrors = config.retryableErrors
+            ? new Set(config.retryableErrors)
+            : new Set(['SEND_FAILED', 'NETWORK_ERROR', 'RECIPIENT_UNREACHABLE', 'TIMEOUT']);
+    }
+    shouldRetry(context) {
+        // Check if we've exceeded max attempts
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                reason: `Maximum attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        // Check if error is retryable
+        if (!this.retryableErrors.has(context.error)) {
+            return {
+                shouldRetry: false,
+                reason: `Error type '${context.error}' is not retryable`,
+            };
+        }
+        // Calculate exponential backoff delay
+        const baseDelay = this.initialDelayMs * Math.pow(this.multiplier, context.attempt);
+        const cappedDelay = Math.min(baseDelay, this.maxDelayMs);
+        // Apply jitter if enabled
+        const finalDelay = this.jitter ? this.applyJitter(cappedDelay) : cappedDelay;
+        return {
+            shouldRetry: true,
+            delayMs: Math.round(finalDelay),
+            reason: `Attempt ${context.attempt + 1}/${this.maxAttempts}`,
+        };
+    }
+    applyJitter(delayMs) {
+        // Use crypto.getRandomValues for secure random jitter (OWASP-compliant)
+        const randomArray = new Uint32Array(1);
+        crypto.getRandomValues(randomArray);
+        const random = randomArray[0] / 0xffffffff; // Normalize to [0, 1]
+        // Apply jitter: delay ± (delay * jitterFactor)
+        const jitterRange = delayMs * this.jitterFactor;
+        const jitter = (random * 2 - 1) * jitterRange; // Range: [-jitterRange, +jitterRange]
+        return delayMs + jitter;
+    }
+}
+/**
+ * Linear backoff retry strategy.
+ *
+ * Delay formula: min(initialDelay + attempt * increment, maxDelay) ± jitter
+ *
+ * Best for: Rate-limited APIs, gradual load recovery.
+ * More predictable than exponential, suitable when service recovery is linear.
+ */
+export class LinearBackoffStrategy {
+    name = 'LinearBackoff';
+    maxAttempts;
+    delayIncrementMs;
+    initialDelayMs;
+    maxDelayMs;
+    jitter;
+    jitterFactor;
+    retryableErrors;
+    constructor(config = {}) {
+        this.maxAttempts = config.maxAttempts ?? 3;
+        this.delayIncrementMs = config.delayIncrementMs ?? 1000;
+        this.initialDelayMs = config.initialDelayMs ?? 1000;
+        this.maxDelayMs = config.maxDelayMs ?? 30000;
+        this.jitter = config.jitter ?? true;
+        this.jitterFactor = config.jitterFactor ?? 0.1;
+        this.retryableErrors = config.retryableErrors
+            ? new Set(config.retryableErrors)
+            : new Set(['SEND_FAILED', 'NETWORK_ERROR', 'RECIPIENT_UNREACHABLE', 'TIMEOUT']);
+    }
+    shouldRetry(context) {
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                reason: `Maximum attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        if (!this.retryableErrors.has(context.error)) {
+            return {
+                shouldRetry: false,
+                reason: `Error type '${context.error}' is not retryable`,
+            };
+        }
+        // Calculate linear backoff delay
+        const baseDelay = this.initialDelayMs + context.attempt * this.delayIncrementMs;
+        const cappedDelay = Math.min(baseDelay, this.maxDelayMs);
+        // Apply jitter if enabled
+        const finalDelay = this.jitter ? this.applyJitter(cappedDelay) : cappedDelay;
+        return {
+            shouldRetry: true,
+            delayMs: Math.round(finalDelay),
+            reason: `Attempt ${context.attempt + 1}/${this.maxAttempts}`,
+        };
+    }
+    applyJitter(delayMs) {
+        const randomArray = new Uint32Array(1);
+        crypto.getRandomValues(randomArray);
+        const random = randomArray[0] / 0xffffffff;
+        const jitterRange = delayMs * this.jitterFactor;
+        const jitter = (random * 2 - 1) * jitterRange;
+        return delayMs + jitter;
+    }
+}
+/**
+ * Fixed delay retry strategy.
+ *
+ * Delay formula: delayMs ± jitter (constant for all attempts)
+ *
+ * Best for: Simple retry scenarios, testing.
+ * Predictable timing, no backoff complexity.
+ */
+export class FixedDelayStrategy {
+    name = 'FixedDelay';
+    maxAttempts;
+    delayMs;
+    jitter;
+    jitterFactor;
+    retryableErrors;
+    constructor(config = {}) {
+        this.maxAttempts = config.maxAttempts ?? 3;
+        this.delayMs = config.delayMs ?? 1000;
+        this.jitter = config.jitter ?? false;
+        this.jitterFactor = config.jitterFactor ?? 0.1;
+        this.retryableErrors = config.retryableErrors
+            ? new Set(config.retryableErrors)
+            : new Set(['SEND_FAILED', 'NETWORK_ERROR', 'RECIPIENT_UNREACHABLE', 'TIMEOUT']);
+    }
+    shouldRetry(context) {
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                reason: `Maximum attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        if (!this.retryableErrors.has(context.error)) {
+            return {
+                shouldRetry: false,
+                reason: `Error type '${context.error}' is not retryable`,
+            };
+        }
+        const finalDelay = this.jitter ? this.applyJitter(this.delayMs) : this.delayMs;
+        return {
+            shouldRetry: true,
+            delayMs: Math.round(finalDelay),
+            reason: `Attempt ${context.attempt + 1}/${this.maxAttempts}`,
+        };
+    }
+    applyJitter(delayMs) {
+        const randomArray = new Uint32Array(1);
+        crypto.getRandomValues(randomArray);
+        const random = randomArray[0] / 0xffffffff;
+        const jitterRange = delayMs * this.jitterFactor;
+        const jitter = (random * 2 - 1) * jitterRange;
+        return delayMs + jitter;
+    }
+}
+/**
+ * No retry strategy (fail immediately).
+ *
+ * Best for: Operations that must succeed on first try, testing.
+ */
+export class NoRetryStrategy {
+    name = 'NoRetry';
+    shouldRetry(_context) {
+        return {
+            shouldRetry: false,
+            reason: 'No retry policy - fail immediately',
+        };
+    }
+}
+/* ── Circuit Breaker ── */
+/**
+ * Circuit breaker for preventing cascading failures.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests fail immediately
+ * - HALF_OPEN: Testing recovery, limited requests allowed
+ *
+ * Best practices:
+ * - Use with retry strategies for comprehensive fault tolerance
+ * - Monitor circuit state changes for alerting
+ * - Tune thresholds based on service characteristics
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 60000,
+ *   successThreshold: 2
+ * });
+ *
+ * // Check before operation
+ * if (breaker.allowRequest()) {
+ *   const result = await operation();
+ *   if (result.ok) {
+ *     breaker.recordSuccess();
+ *   } else {
+ *     breaker.recordFailure();
+ *   }
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+    state = 'CLOSED';
+    consecutiveFailures = 0;
+    consecutiveSuccesses = 0;
+    openedAt;
+    totalRequests = 0;
+    totalFailures = 0;
+    totalSuccesses = 0;
+    failureTimestamps = [];
+    failureThreshold;
+    resetTimeoutMs;
+    successThreshold;
+    windowMs;
+    constructor(config = {}) {
+        this.failureThreshold = config.failureThreshold ?? 5;
+        this.resetTimeoutMs = config.resetTimeoutMs ?? 60000;
+        this.successThreshold = config.successThreshold ?? 2;
+        this.windowMs = config.windowMs ?? 60000;
+    }
+    /**
+     * Check if request should be allowed through circuit.
+     *
+     * @returns True if request should proceed, false if circuit is open
+     */
+    allowRequest() {
+        const now = Date.now();
+        // Clean up old failure timestamps outside the window
+        this.failureTimestamps = this.failureTimestamps.filter(timestamp => now - timestamp < this.windowMs);
+        // CLOSED: Allow all requests
+        if (this.state === 'CLOSED') {
+            return true;
+        }
+        // OPEN: Check if reset timeout has elapsed
+        if (this.state === 'OPEN') {
+            if (this.openedAt && now - this.openedAt >= this.resetTimeoutMs) {
+                // Transition to HALF_OPEN
+                this.state = 'HALF_OPEN';
+                this.consecutiveSuccesses = 0;
+                return true;
+            }
+            return false; // Circuit still open
+        }
+        // HALF_OPEN: Allow limited requests to test recovery
+        return true;
+    }
+    /**
+     * Record a successful operation.
+     */
+    recordSuccess() {
+        this.totalRequests++;
+        this.totalSuccesses++;
+        this.consecutiveFailures = 0;
+        if (this.state === 'HALF_OPEN') {
+            this.consecutiveSuccesses++;
+            // Enough successes to close circuit
+            if (this.consecutiveSuccesses >= this.successThreshold) {
+                this.state = 'CLOSED';
+                this.consecutiveSuccesses = 0;
+                this.openedAt = undefined;
+            }
+        }
+    }
+    /**
+     * Record a failed operation.
+     */
+    recordFailure() {
+        this.totalRequests++;
+        this.totalFailures++;
+        this.consecutiveFailures++;
+        this.consecutiveSuccesses = 0;
+        const now = Date.now();
+        this.failureTimestamps.push(now);
+        // Trip circuit if threshold exceeded
+        if (this.state === 'CLOSED' || this.state === 'HALF_OPEN') {
+            // Count failures within the time window
+            const recentFailures = this.failureTimestamps.filter(timestamp => now - timestamp < this.windowMs).length;
+            if (recentFailures >= this.failureThreshold) {
+                this.state = 'OPEN';
+                this.openedAt = now;
+            }
+        }
+    }
+    /**
+     * Get current circuit breaker statistics.
+     */
+    getStats() {
+        return {
+            state: this.state,
+            consecutiveFailures: this.consecutiveFailures,
+            consecutiveSuccesses: this.consecutiveSuccesses,
+            openedAt: this.openedAt,
+            totalRequests: this.totalRequests,
+            totalFailures: this.totalFailures,
+            totalSuccesses: this.totalSuccesses,
+        };
+    }
+    /**
+     * Reset circuit breaker to initial state.
+     */
+    reset() {
+        this.state = 'CLOSED';
+        this.consecutiveFailures = 0;
+        this.consecutiveSuccesses = 0;
+        this.openedAt = undefined;
+        this.totalRequests = 0;
+        this.totalFailures = 0;
+        this.totalSuccesses = 0;
+        this.failureTimestamps = [];
+    }
+    /**
+     * Force circuit to open (for testing or manual intervention).
+     */
+    forceOpen() {
+        this.state = 'OPEN';
+        this.openedAt = Date.now();
+    }
+    /**
+     * Force circuit to close (for testing or manual recovery).
+     */
+    forceClose() {
+        this.state = 'CLOSED';
+        this.consecutiveFailures = 0;
+        this.consecutiveSuccesses = 0;
+        this.openedAt = undefined;
+    }
+}
+/* ── Factory Functions ── */
+/**
+ * Factory for creating retry strategies with common configurations.
+ */
+export class RetryStrategy {
+    /**
+     * Create exponential backoff strategy.
+     *
+     * @param config - Configuration options
+     * @returns Exponential backoff strategy
+     */
+    static exponentialBackoff(config) {
+        return new ExponentialBackoffStrategy(config);
+    }
+    /**
+     * Create linear backoff strategy.
+     *
+     * @param config - Configuration options
+     * @returns Linear backoff strategy
+     */
+    static linearBackoff(config) {
+        return new LinearBackoffStrategy(config);
+    }
+    /**
+     * Create fixed delay strategy.
+     *
+     * @param config - Configuration options
+     * @returns Fixed delay strategy
+     */
+    static fixedDelay(config) {
+        return new FixedDelayStrategy(config);
+    }
+    /**
+     * Create no retry strategy (fail immediately).
+     *
+     * @returns No retry strategy
+     */
+    static noRetry() {
+        return new NoRetryStrategy();
+    }
+    /**
+     * Create aggressive retry strategy for critical operations.
+     *
+     * Config: 5 attempts, 500ms initial, max 10s, exponential backoff.
+     *
+     * @returns Aggressive retry strategy
+     */
+    static aggressive() {
+        return new ExponentialBackoffStrategy({
+            maxAttempts: 5,
+            initialDelayMs: 500,
+            maxDelayMs: 10000,
+            multiplier: 2,
+            jitter: true,
+        });
+    }
+    /**
+     * Create conservative retry strategy for non-critical operations.
+     *
+     * Config: 2 attempts, 2s initial, max 5s, linear backoff.
+     *
+     * @returns Conservative retry strategy
+     */
+    static conservative() {
+        return new LinearBackoffStrategy({
+            maxAttempts: 2,
+            initialDelayMs: 2000,
+            delayIncrementMs: 1000,
+            maxDelayMs: 5000,
+            jitter: true,
+        });
+    }
+    /**
+     * Create default retry strategy (balanced).
+     *
+     * Config: 3 attempts, 1s initial, max 30s, exponential backoff.
+     *
+     * @returns Default retry strategy
+     */
+    static default() {
+        return new ExponentialBackoffStrategy({
+            maxAttempts: 3,
+            initialDelayMs: 1000,
+            maxDelayMs: 30000,
+            multiplier: 2,
+            jitter: true,
+        });
+    }
+}
+/* ── Retry Executor ── */
+/**
+ * Execute an operation with retry strategy and optional circuit breaker.
+ *
+ * @param operation - Async operation to execute
+ * @param strategy - Retry strategy to use
+ * @param circuitBreaker - Optional circuit breaker
+ * @returns Result of the operation
+ *
+ * @example
+ * ```typescript
+ * const result = await executeWithRetry(
+ *   async () => transport.send(envelope, did),
+ *   RetryStrategy.exponentialBackoff(),
+ *   circuitBreaker
+ * );
+ * ```
+ */
+export async function executeWithRetry(operation, strategy, circuitBreaker) {
+    const startTime = Date.now();
+    let attempt = 0;
+    let lastError = 'NETWORK_ERROR'; // Default error
+    while (true) {
+        // Check circuit breaker
+        if (circuitBreaker && !circuitBreaker.allowRequest()) {
+            return err('SEND_FAILED');
+        }
+        // Execute operation
+        const result = await operation();
+        if (result.ok) {
+            // Success - record and return
+            circuitBreaker?.recordSuccess();
+            return result;
+        }
+        // Failure - record error
+        lastError = result.error;
+        circuitBreaker?.recordFailure();
+        // Check retry decision
+        const elapsedMs = Date.now() - startTime;
+        const context = {
+            attempt,
+            error: lastError,
+            startTime,
+            elapsedMs,
+        };
+        const decision = strategy.shouldRetry(context);
+        if (!decision.shouldRetry) {
+            // No more retries - return last error
+            return err(lastError);
+        }
+        // Wait before retry
+        if (decision.delayMs && decision.delayMs > 0) {
+            await sleep(decision.delayMs);
+        }
+        attempt++;
+    }
+}
+/**
+ * Sleep for specified milliseconds.
+ *
+ * @param ms - Duration in milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist-standalone/retry-transport.js

@@ -1 +1,98 @@
-export class RetryTransportAdapter{inner;maxRetries;baseDelayMs;maxJitterMs;constructor(e,t={}){this.inner=e,this.maxRetries=t.maxRetries??3,this.baseDelayMs=t.baseDelayMs??1e3,this.maxJitterMs=t.maxJitterMs??200}async send(e,t){let s;for(let r=0;r<=this.maxRetries;r++){const i=await this.inner.send(e,t);if(i.ok)return i;if(s=i.error,r<this.maxRetries){const e=Math.pow(2,r)*this.baseDelayMs,t=new Uint32Array(1);crypto.getRandomValues(t);const s=t[0]/4294967295*this.maxJitterMs*2-this.maxJitterMs;await this.sleep(e+s)}}throw new Error(`Failed after ${this.maxRetries} retries: ${s??"unknown error"}`)}onReceive(e){this.inner.onReceive(e)}dispose(){this.inner.dispose()}sleep(e){return new Promise(t=>setTimeout(t,e))}}
+/* ── Implementation ── */
+/**
+ * Decorator that adds exponential backoff retry logic to any transport adapter.
+ *
+ * Retry delays follow exponential backoff with jitter:
+ * - Formula: 2^attempt * baseDelay + jitter
+ * - Jitter: Math.random() * maxJitter * 2 - maxJitter
+ * - Default delays: 1s, 2s, 4s (with ±200ms jitter)
+ *
+ * Use case: Push notification delivery failures requiring automatic retry.
+ *
+ * @example
+ * ```typescript
+ * const transport = new RetryTransportAdapter(baseTransport, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxJitterMs: 200
+ * });
+ * ```
+ */
+export class RetryTransportAdapter {
+    inner;
+    maxRetries;
+    baseDelayMs;
+    maxJitterMs;
+    /**
+     * Create a new RetryTransportAdapter wrapping an existing transport.
+     *
+     * @param inner - The transport adapter to wrap with retry logic
+     * @param options - Retry configuration options
+     */
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.baseDelayMs = options.baseDelayMs ?? 1000;
+        this.maxJitterMs = options.maxJitterMs ?? 200;
+    }
+    /**
+     * Send an envelope with exponential backoff retry logic.
+     *
+     * Retries on all error types (SEND_FAILED, NETWORK_ERROR, RECIPIENT_UNREACHABLE, TIMEOUT).
+     * Throws error after all retries are exhausted.
+     *
+     * @param envelope - The envelope to send
+     * @param recipientDid - The recipient's DID
+     * @returns Result with void on success, or TransportError on failure
+     * @throws Error if all retry attempts are exhausted
+     */
+    async send(envelope, recipientDid) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const result = await this.inner.send(envelope, recipientDid);
+            // Success - return immediately
+            if (result.ok) {
+                return result;
+            }
+            // Store error for final throw
+            lastError = result.error;
+            // Don't delay after final attempt
+            if (attempt < this.maxRetries) {
+                // Exponential backoff: 2^attempt * baseDelay + jitter
+                const delay = Math.pow(2, attempt) * this.baseDelayMs;
+                // SAFETY: Using crypto.getRandomValues for OWASP-compliant secure random jitter
+                const jitterArray = new Uint32Array(1);
+                crypto.getRandomValues(jitterArray);
+                const jitter = (jitterArray[0] / 0xffffffff) * this.maxJitterMs * 2 -
+                    this.maxJitterMs;
+                await this.sleep(delay + jitter);
+            }
+        }
+        // All retries exhausted - throw error with clear message
+        throw new Error(`Failed after ${this.maxRetries} retries: ${lastError ?? 'unknown error'}`);
+    }
+    /**
+     * Register a handler for incoming envelopes.
+     * Delegates directly to the inner transport.
+     *
+     * @param handler - The envelope handler function
+     */
+    onReceive(handler) {
+        this.inner.onReceive(handler);
+    }
+    /**
+     * Shut down the transport.
+     * Delegates directly to the inner transport.
+     */
+    dispose() {
+        this.inner.dispose();
+    }
+    /**
+     * Sleep for a specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}