@shadow-corp/nearconnect 1.0.0

package/build/connection/retry.js

@@ -0,0 +1,427 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.DEFAULT_TIMEOUT_CONFIG = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.calculateBackoffDelay = calculateBackoffDelay;
+exports.isRetryableError = isRetryableError;
+exports.withRetry = withRetry;
+exports.withTimeout = withTimeout;
+exports.withRetryAndTimeout = withRetryAndTimeout;
+exports.createRetryWrapper = createRetryWrapper;
+exports.createTimeoutWrapper = createTimeoutWrapper;
+exports.makeCancellable = makeCancellable;
+const errors_1 = require("../errors");
+/**
+ * Default retry configuration
+ */
+exports.DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    backoffMultiplier: 2,
+    jitter: true,
+    retryableErrors: [
+        errors_1.ErrorCode.CONNECTION_TIMEOUT,
+        errors_1.ErrorCode.RPC_ERROR,
+        errors_1.ErrorCode.NETWORK_MISMATCH,
+    ],
+};
+/**
+ * Default timeout configuration
+ */
+exports.DEFAULT_TIMEOUT_CONFIG = {
+    connection: 30000,
+    signTransaction: 120000,
+    signMessage: 60000,
+    broadcast: 60000,
+    warningThreshold: 0.8,
+};
+/**
+ * Default circuit breaker configuration
+ */
+exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = {
+    failureThreshold: 5,
+    cooldownPeriod: 60000,
+    healthCheckInterval: 10000,
+};
+/**
+ * Calculate delay for a given attempt with exponential backoff
+ */
+function calculateBackoffDelay(attempt, config) {
+    // Exponential backoff: baseDelay * (multiplier ^ attempt)
+    let delay = config.baseDelay * Math.pow(config.backoffMultiplier, attempt);
+    // Cap at maxDelay
+    delay = Math.min(delay, config.maxDelay);
+    // Add jitter (±25% randomization)
+    if (config.jitter) {
+        const jitterFactor = 0.75 + Math.random() * 0.5; // 0.75 to 1.25
+        delay = Math.floor(delay * jitterFactor);
+    }
+    return delay;
+}
+/**
+ * Check if an error is retryable based on config
+ */
+function isRetryableError(error, config) {
+    if (config.shouldRetry) {
+        return config.shouldRetry(error, 0);
+    }
+    if (error instanceof errors_1.WalletError) {
+        return config.retryableErrors.includes(error.code);
+    }
+    // Network errors are generally retryable
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Execute an operation with retry logic
+ */
+async function withRetry(operation, config = {}) {
+    const fullConfig = { ...exports.DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    for (let attempt = 0; attempt < fullConfig.maxAttempts; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry
+            const shouldRetry = fullConfig.shouldRetry
+                ? fullConfig.shouldRetry(error, attempt)
+                : isRetryableError(error, fullConfig);
+            if (!shouldRetry || attempt >= fullConfig.maxAttempts - 1) {
+                break;
+            }
+            // Calculate delay for next attempt
+            const delay = calculateBackoffDelay(attempt, fullConfig);
+            // Notify about retry
+            fullConfig.onRetry?.(attempt + 1, delay, error);
+            // Wait before retrying
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // All retries exhausted
+    fullConfig.onExhausted?.(lastError, fullConfig.maxAttempts);
+    throw lastError;
+}
+/**
+ * Execute an operation with timeout
+ */
+async function withTimeout(operation, timeoutMs, operationName = "operation", onWarning, warningThreshold = 0.8) {
+    return new Promise((resolve, reject) => {
+        let warningTimer = null;
+        let completed = false;
+        // Set up warning timer
+        if (onWarning && warningThreshold > 0 && warningThreshold < 1) {
+            const warningTime = timeoutMs * warningThreshold;
+            warningTimer = setTimeout(() => {
+                if (!completed) {
+                    onWarning(warningTime, timeoutMs);
+                }
+            }, warningTime);
+        }
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            if (!completed) {
+                completed = true;
+                if (warningTimer)
+                    clearTimeout(warningTimer);
+                reject(new errors_1.WalletError({
+                    code: errors_1.ErrorCode.CONNECTION_TIMEOUT,
+                    message: `${operationName} timed out after ${timeoutMs}ms`,
+                }));
+            }
+        }, timeoutMs);
+        // Execute operation
+        operation()
+            .then((result) => {
+            if (!completed) {
+                completed = true;
+                clearTimeout(timeoutId);
+                if (warningTimer)
+                    clearTimeout(warningTimer);
+                resolve(result);
+            }
+        })
+            .catch((error) => {
+            if (!completed) {
+                completed = true;
+                clearTimeout(timeoutId);
+                if (warningTimer)
+                    clearTimeout(warningTimer);
+                reject(error);
+            }
+        });
+    });
+}
+/**
+ * Combine retry and timeout
+ */
+async function withRetryAndTimeout(operation, timeoutMs, retryConfig = {}, operationName = "operation") {
+    return withRetry(() => withTimeout(operation, timeoutMs, operationName), retryConfig);
+}
+/**
+ * Circuit Breaker
+ *
+ * Prevents hammering a failing wallet by temporarily disabling connections
+ */
+class CircuitBreaker {
+    circuits = new Map();
+    config;
+    healthCheckTimers = new Map();
+    constructor(config = {}) {
+        this.config = { ...exports.DEFAULT_CIRCUIT_BREAKER_CONFIG, ...config };
+    }
+    /**
+     * Get or create circuit entry for a wallet
+     */
+    getCircuit(walletId) {
+        let circuit = this.circuits.get(walletId);
+        if (!circuit) {
+            circuit = {
+                state: "closed",
+                failures: 0,
+                lastFailure: 0,
+                lastSuccess: 0,
+                openedAt: null,
+            };
+            this.circuits.set(walletId, circuit);
+        }
+        return circuit;
+    }
+    /**
+     * Check if a wallet's circuit allows requests
+     */
+    isAllowed(walletId) {
+        const circuit = this.getCircuit(walletId);
+        switch (circuit.state) {
+            case "closed":
+                return true;
+            case "open":
+                // Check if cooldown has passed
+                if (circuit.openedAt && Date.now() - circuit.openedAt >= this.config.cooldownPeriod) {
+                    this.transitionTo(walletId, "half-open");
+                    return true; // Allow one test request
+                }
+                return false;
+            case "half-open":
+                // Only allow one request at a time in half-open state
+                return true;
+            default:
+                return true;
+        }
+    }
+    /**
+     * Record a successful operation
+     */
+    recordSuccess(walletId) {
+        const circuit = this.getCircuit(walletId);
+        circuit.lastSuccess = Date.now();
+        if (circuit.state === "half-open") {
+            // Success in half-open state closes the circuit
+            this.transitionTo(walletId, "closed");
+            circuit.failures = 0;
+        }
+    }
+    /**
+     * Record a failed operation
+     */
+    recordFailure(walletId) {
+        const circuit = this.getCircuit(walletId);
+        circuit.failures++;
+        circuit.lastFailure = Date.now();
+        if (circuit.state === "half-open") {
+            // Failure in half-open state re-opens the circuit
+            this.transitionTo(walletId, "open");
+        }
+        else if (circuit.state === "closed" &&
+            circuit.failures >= this.config.failureThreshold) {
+            // Too many failures, open the circuit
+            this.transitionTo(walletId, "open");
+        }
+    }
+    /**
+     * Transition circuit to a new state
+     */
+    transitionTo(walletId, state) {
+        const circuit = this.getCircuit(walletId);
+        const previousState = circuit.state;
+        circuit.state = state;
+        // Handle state-specific actions
+        switch (state) {
+            case "open":
+                circuit.openedAt = Date.now();
+                this.config.onOpen?.(walletId, circuit.failures);
+                this.scheduleHealthCheck(walletId);
+                break;
+            case "closed":
+                circuit.openedAt = null;
+                circuit.failures = 0;
+                this.config.onClose?.(walletId);
+                this.cancelHealthCheck(walletId);
+                break;
+            case "half-open":
+                this.config.onHalfOpen?.(walletId);
+                break;
+        }
+    }
+    /**
+     * Schedule health check for an open circuit
+     */
+    scheduleHealthCheck(walletId) {
+        // Cancel existing timer
+        this.cancelHealthCheck(walletId);
+        // Schedule check at cooldown period
+        const timer = setTimeout(() => {
+            const circuit = this.getCircuit(walletId);
+            if (circuit.state === "open") {
+                this.transitionTo(walletId, "half-open");
+            }
+        }, this.config.cooldownPeriod);
+        this.healthCheckTimers.set(walletId, timer);
+    }
+    /**
+     * Cancel health check timer
+     */
+    cancelHealthCheck(walletId) {
+        const timer = this.healthCheckTimers.get(walletId);
+        if (timer) {
+            clearTimeout(timer);
+            this.healthCheckTimers.delete(walletId);
+        }
+    }
+    /**
+     * Manually reset a circuit
+     */
+    reset(walletId) {
+        this.cancelHealthCheck(walletId);
+        const circuit = this.getCircuit(walletId);
+        circuit.state = "closed";
+        circuit.failures = 0;
+        circuit.openedAt = null;
+    }
+    /**
+     * Manually reset all circuits
+     */
+    resetAll() {
+        for (const walletId of this.circuits.keys()) {
+            this.reset(walletId);
+        }
+    }
+    /**
+     * Get circuit state for a wallet
+     */
+    getState(walletId) {
+        return this.getCircuit(walletId).state;
+    }
+    /**
+     * Get circuit info for a wallet
+     */
+    getInfo(walletId) {
+        const circuit = this.getCircuit(walletId);
+        let remainingCooldown = null;
+        if (circuit.state === "open" && circuit.openedAt) {
+            const elapsed = Date.now() - circuit.openedAt;
+            remainingCooldown = Math.max(0, this.config.cooldownPeriod - elapsed);
+        }
+        return {
+            state: circuit.state,
+            failures: circuit.failures,
+            lastFailure: circuit.lastFailure,
+            lastSuccess: circuit.lastSuccess,
+            remainingCooldown,
+        };
+    }
+    /**
+     * Get all circuit states
+     */
+    getAllStates() {
+        const states = {};
+        for (const [walletId, circuit] of this.circuits) {
+            states[walletId] = circuit.state;
+        }
+        return states;
+    }
+    /**
+     * Execute an operation through the circuit breaker
+     */
+    async execute(walletId, operation) {
+        if (!this.isAllowed(walletId)) {
+            const info = this.getInfo(walletId);
+            throw new errors_1.WalletError({
+                code: errors_1.ErrorCode.CONNECTION_TIMEOUT,
+                message: `Circuit breaker open for wallet ${walletId}. Try again in ${info.remainingCooldown}ms`,
+                walletId,
+            });
+        }
+        try {
+            const result = await operation();
+            this.recordSuccess(walletId);
+            return result;
+        }
+        catch (error) {
+            this.recordFailure(walletId);
+            throw error;
+        }
+    }
+    /**
+     * Cleanup all timers
+     */
+    destroy() {
+        for (const timer of this.healthCheckTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.healthCheckTimers.clear();
+        this.circuits.clear();
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+/**
+ * Create a retry wrapper with default configuration
+ */
+function createRetryWrapper(config = {}) {
+    const fullConfig = { ...exports.DEFAULT_RETRY_CONFIG, ...config };
+    return (operation) => withRetry(operation, fullConfig);
+}
+/**
+ * Create a timeout wrapper with default configuration
+ */
+function createTimeoutWrapper(timeoutMs, operationName, onWarning) {
+    return (operation) => withTimeout(operation, timeoutMs, operationName, onWarning);
+}
+/**
+ * Create a cancellable operation
+ */
+function makeCancellable(operation) {
+    let cancelled = false;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+        rejectFn = reject;
+        operation()
+            .then((result) => {
+            if (!cancelled) {
+                resolve(result);
+            }
+        })
+            .catch((error) => {
+            if (!cancelled) {
+                reject(error);
+            }
+        });
+    });
+    return {
+        promise,
+        cancel: () => {
+            if (!cancelled) {
+                cancelled = true;
+                rejectFn(new errors_1.WalletError({
+                    code: errors_1.ErrorCode.USER_REJECTED,
+                    message: "Operation cancelled by user",
+                }));
+            }
+        },
+        isCancelled: () => cancelled,
+    };
+}
+//# sourceMappingURL=retry.js.map

package/build/connection/retry.js.map

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

package/build/connection/state.d.ts

@@ -0,0 +1,222 @@
+import { WalletError } from "../errors";
+import { Account } from "../types";
+/**
+ * Connection state types
+ */
+export type ConnectionStatus = "idle" | "detecting" | "connecting" | "authenticating" | "connected" | "signing" | "reconnecting" | "disconnecting" | "error";
+/**
+ * Connection state with context
+ */
+export type ConnectionState = {
+    status: "idle";
+} | {
+    status: "detecting";
+    walletId: string;
+    startedAt: number;
+} | {
+    status: "connecting";
+    walletId: string;
+    startedAt: number;
+} | {
+    status: "authenticating";
+    walletId: string;
+    startedAt: number;
+} | {
+    status: "connected";
+    walletId: string;
+    accounts: Account[];
+    connectedAt: number;
+} | {
+    status: "signing";
+    walletId: string;
+    operation: string;
+    startedAt: number;
+} | {
+    status: "reconnecting";
+    walletId: string;
+    attempt: number;
+    startedAt: number;
+} | {
+    status: "disconnecting";
+    walletId: string;
+    startedAt: number;
+} | {
+    status: "error";
+    walletId?: string;
+    error: WalletError;
+    occurredAt: number;
+};
+/**
+ * State transition history entry
+ */
+export interface StateHistoryEntry {
+    from: ConnectionState;
+    to: ConnectionState;
+    timestamp: number;
+    reason?: string;
+}
+/**
+ * State machine configuration
+ */
+export interface StateMachineConfig {
+    /** Maximum history entries to keep (default: 50) */
+    maxHistorySize: number;
+    /** Persist state to storage (default: false) */
+    persistState: boolean;
+    /** Storage key for persistence */
+    storageKey: string;
+    /** State expiration in ms (default: 24 hours) */
+    stateExpiration: number;
+    /** Callback when state changes */
+    onStateChange?: (from: ConnectionState, to: ConnectionState) => void;
+    /** Callback when invalid transition attempted */
+    onInvalidTransition?: (current: ConnectionStatus, attempted: ConnectionStatus) => void;
+}
+/**
+ * Default state machine configuration
+ */
+export declare const DEFAULT_STATE_MACHINE_CONFIG: StateMachineConfig;
+/**
+ * Connection State Machine
+ *
+ * Manages connection lifecycle with proper state transitions
+ */
+export declare class ConnectionStateMachine {
+    private state;
+    private history;
+    private config;
+    private listeners;
+    constructor(config?: Partial<StateMachineConfig>);
+    /**
+     * Get current state
+     */
+    get current(): ConnectionState;
+    /**
+     * Get current status (convenience getter)
+     */
+    get status(): ConnectionStatus;
+    /**
+     * Check if currently in a specific status
+     */
+    is(status: ConnectionStatus): boolean;
+    /**
+     * Check if in any of the given statuses
+     */
+    isAnyOf(...statuses: ConnectionStatus[]): boolean;
+    /**
+     * Check if a transition is valid
+     */
+    canTransition(to: ConnectionStatus): boolean;
+    /**
+     * Transition to a new state
+     */
+    transition(to: ConnectionState, reason?: string): void;
+    /**
+     * Convenience methods for common transitions
+     */
+    toDetecting(walletId: string): void;
+    toConnecting(walletId: string): void;
+    toAuthenticating(walletId: string): void;
+    toConnected(walletId: string, accounts: Account[]): void;
+    toSigning(walletId: string, operation: string): void;
+    toReconnecting(walletId: string, attempt?: number): void;
+    toDisconnecting(walletId: string): void;
+    toError(error: WalletError, walletId?: string): void;
+    toIdle(): void;
+    /**
+     * Reset to idle state (bypasses transition validation)
+     */
+    reset(): void;
+    /**
+     * Record state transition in history
+     */
+    private recordHistory;
+    /**
+     * Get state history
+     */
+    getHistory(): StateHistoryEntry[];
+    /**
+     * Get last N history entries
+     */
+    getRecentHistory(count?: number): StateHistoryEntry[];
+    /**
+     * Clear history
+     */
+    clearHistory(): void;
+    /**
+     * Register callback for entering a state
+     */
+    onEnter(status: ConnectionStatus, callback: (state: ConnectionState) => void): () => void;
+    /**
+     * Register callback for exiting a state
+     */
+    onExit(status: ConnectionStatus, callback: (state: ConnectionState) => void): () => void;
+    /**
+     * Register callback for any transition
+     */
+    onTransition(callback: (from: ConnectionState, to: ConnectionState) => void): () => void;
+    /**
+     * Get connected wallet ID if in connected state
+     */
+    getConnectedWalletId(): string | null;
+    /**
+     * Get connected accounts if in connected state
+     */
+    getConnectedAccounts(): Account[];
+    /**
+     * Get error if in error state
+     */
+    getError(): WalletError | null;
+    /**
+     * Get time spent in current state
+     */
+    getTimeInCurrentState(): number;
+    /**
+     * Check if current state has timed out
+     */
+    hasTimedOut(timeoutMs: number): boolean;
+    /**
+     * Persist state to storage
+     */
+    private persistState;
+    /**
+     * Restore state from storage
+     */
+    private restoreState;
+    /**
+     * Clear persisted state
+     */
+    private clearPersistedState;
+    /**
+     * Create a snapshot of current state
+     */
+    snapshot(): {
+        state: ConnectionState;
+        history: StateHistoryEntry[];
+        timestamp: number;
+    };
+    /**
+     * Check if currently processing (not idle or connected)
+     */
+    isProcessing(): boolean;
+    /**
+     * Check if in a stable state (idle or connected)
+     */
+    isStable(): boolean;
+    /**
+     * Wait for state to become stable
+     */
+    waitForStable(timeoutMs?: number): Promise<ConnectionState>;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create a simple state machine instance
+ */
+export declare function createStateMachine(config?: Partial<StateMachineConfig>): ConnectionStateMachine;
+/**
+ * Get human-readable status description
+ */
+export declare function getStatusDescription(status: ConnectionStatus): string;