@monygroupcorp/micro-web3 1.3.5 → 1.3.8

package/src/services/IpfsService.js

@@ -1,9 +1,9 @@
 /**
  * IPFS Service
- * 
+ *
  * Light client for IPFS resolution with gateway rotation and fallback.
  * Handles both direct IPFS URIs and metadata fetching.
- * 
+ *
  * No secrets, no backend - pure client-side IPFS gateway resolution.
  */
 
@@ -19,6 +19,265 @@ const IPFS_GATEWAYS = [
     'https://dweb.link/ipfs/'
 ];
 
+/**
+ * CORS-friendly gateways that work well in development environments
+ */
+const CORS_FRIENDLY_GATEWAYS = [
+    'https://cloudflare-ipfs.com/ipfs/',
+    'https://dweb.link/ipfs/',
+    'https://w3s.link/ipfs/'
+];
+
+/**
+ * Well-known CID for health checks (empty directory)
+ */
+const HEALTH_CHECK_CID = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi';
+
+/**
+ * Internal GatewayManager class for intelligent gateway selection and rotation
+ */
+class GatewayManager {
+    constructor() {
+        this.currentGateway = null;
+        this.gatewayLatencies = new Map();
+        this.failedGateways = new Set();
+        this.failureCounts = new Map();
+        this.lastHealthCheck = null;
+        this.healthCheckInterval = null;
+        this.initialized = false;
+        this.config = {
+            timeout: 5000,
+            maxRetries: 3,
+            healthCheckInterval: 60000,
+            parallelDiscovery: true,
+            corsGatewaysFirst: true
+        };
+    }
+
+    /**
+     * Detect current environment (development vs production)
+     * @returns {'development'|'production'}
+     */
+    getEnvironment() {
+        if (typeof window === 'undefined') return 'production';
+        const hostname = window.location.hostname;
+        return hostname === 'localhost' || hostname === '127.0.0.1' || hostname.includes('.local')
+            ? 'development'
+            : 'production';
+    }
+
+    /**
+     * Get gateways prioritized based on environment and performance
+     * @returns {string[]} Prioritized gateway list
+     */
+    getPrioritizedGateways() {
+        const custom = getCustomGateway();
+        const baseGateways = custom ? [custom, ...IPFS_GATEWAYS] : IPFS_GATEWAYS;
+
+        if (!this.config.corsGatewaysFirst || this.getEnvironment() !== 'development') {
+            return baseGateways;
+        }
+
+        // In dev, put CORS-friendly gateways first
+        const corsFirst = baseGateways.filter(g => CORS_FRIENDLY_GATEWAYS.some(c => g.includes(c)));
+        const others = baseGateways.filter(g => !CORS_FRIENDLY_GATEWAYS.some(c => g.includes(c)));
+        return [...corsFirst, ...others];
+    }
+
+    /**
+     * Record a successful request to a gateway
+     * @param {string} gateway - Gateway URL
+     * @param {number} latency - Request latency in ms
+     */
+    recordSuccess(gateway, latency) {
+        this.gatewayLatencies.set(gateway, latency);
+        this.failedGateways.delete(gateway);
+        this.failureCounts.delete(gateway);
+        if (!this.currentGateway || latency < (this.gatewayLatencies.get(this.currentGateway) || Infinity)) {
+            this.currentGateway = gateway;
+        }
+    }
+
+    /**
+     * Record a failed request to a gateway
+     * @param {string} gateway - Gateway URL
+     */
+    recordFailure(gateway) {
+        const count = (this.failureCounts.get(gateway) || 0) + 1;
+        this.failureCounts.set(gateway, count);
+        if (count >= this.config.maxRetries) {
+            this.failedGateways.add(gateway);
+            this.gatewayLatencies.set(gateway, Infinity);
+            if (this.currentGateway === gateway) {
+                this.currentGateway = this.getNextBestGateway();
+            }
+        }
+    }
+
+    /**
+     * Get the next best gateway based on latency
+     * @returns {string|undefined} Next best gateway URL
+     */
+    getNextBestGateway() {
+        return this.getPrioritizedGateways()
+            .filter(g => !this.failedGateways.has(g))
+            .sort((a, b) =>
+                (this.gatewayLatencies.get(a) || Infinity) -
+                (this.gatewayLatencies.get(b) || Infinity)
+            )[0];
+    }
+
+    /**
+     * Select the best gateway by racing all gateways
+     * @param {string} testCid - CID to use for testing
+     * @returns {Promise<string>} Best gateway URL
+     */
+    async selectBestGateway(testCid = HEALTH_CHECK_CID) {
+        const gateways = this.getPrioritizedGateways();
+
+        const results = await Promise.allSettled(
+            gateways.map(async (gateway) => {
+                const start = Date.now();
+                const response = await fetch(`${gateway}${testCid}`, {
+                    method: 'HEAD',
+                    signal: AbortSignal.timeout(this.config.timeout)
+                });
+                if (!response.ok) throw new Error('Failed');
+                return { gateway, latency: Date.now() - start };
+            })
+        );
+
+        const successful = results
+            .filter(r => r.status === 'fulfilled')
+            .map(r => r.value)
+            .sort((a, b) => a.latency - b.latency);
+
+        // Record all successful results
+        successful.forEach(({ gateway, latency }) => this.recordSuccess(gateway, latency));
+
+        // Record failures
+        results.forEach((result, i) => {
+            if (result.status === 'rejected') {
+                this.recordFailure(gateways[i]);
+            }
+        });
+
+        this.currentGateway = successful[0]?.gateway || gateways[0];
+        this.initialized = true;
+        return this.currentGateway;
+    }
+
+    /**
+     * Fetch with intelligent gateway rotation
+     * @param {string} path - IPFS path to fetch
+     * @param {object} options - Fetch options
+     * @returns {Promise<object>} Parsed JSON response
+     */
+    async fetchWithRotation(path, options = {}) {
+        const { timeout = this.config.timeout, ...fetchOptions } = options;
+        const gateways = this.getPrioritizedGateways();
+        const errors = [];
+
+        // Start with current best or first gateway
+        let startIndex = this.currentGateway
+            ? gateways.indexOf(this.currentGateway)
+            : 0;
+        if (startIndex === -1) startIndex = 0;
+
+        for (let attempt = 0; attempt < gateways.length; attempt++) {
+            const index = (startIndex + attempt) % gateways.length;
+            const gateway = gateways[index];
+
+            if (this.failedGateways.has(gateway)) continue;
+
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const start = Date.now();
+
+            try {
+                const response = await fetch(`${gateway}${path}`, {
+                    ...fetchOptions,
+                    signal: controller.signal
+                });
+                clearTimeout(timeoutId);
+
+                if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+                const json = await response.json();
+                this.recordSuccess(gateway, Date.now() - start);
+                return json;
+            } catch (error) {
+                clearTimeout(timeoutId);
+                this.recordFailure(gateway);
+                errors.push(`${gateway}: ${error.message}`);
+            }
+        }
+
+        throw new Error(`All gateways failed:\n${errors.join('\n')}`);
+    }
+
+    /**
+     * Start background health monitoring
+     */
+    startHealthMonitoring() {
+        if (this.healthCheckInterval) return;
+        if (this.config.healthCheckInterval <= 0) return;
+
+        this.healthCheckInterval = setInterval(
+            () => this.runHealthCheck(),
+            this.config.healthCheckInterval
+        );
+    }
+
+    /**
+     * Stop background health monitoring
+     */
+    stopHealthMonitoring() {
+        if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+            this.healthCheckInterval = null;
+        }
+    }
+
+    /**
+     * Run a health check on all gateways
+     */
+    async runHealthCheck() {
+        const gateways = this.getPrioritizedGateways();
+        this.lastHealthCheck = Date.now();
+
+        for (const gateway of gateways) {
+            try {
+                const start = Date.now();
+                const response = await fetch(`${gateway}${HEALTH_CHECK_CID}`, {
+                    method: 'HEAD',
+                    signal: AbortSignal.timeout(3000)
+                });
+                if (response.ok) {
+                    this.recordSuccess(gateway, Date.now() - start);
+                }
+            } catch {
+                // Don't mark as failed from health check, just update latency
+                this.gatewayLatencies.set(gateway, Infinity);
+            }
+        }
+    }
+
+    /**
+     * Reset gateway manager state
+     */
+    reset() {
+        this.currentGateway = null;
+        this.gatewayLatencies.clear();
+        this.failedGateways.clear();
+        this.failureCounts.clear();
+        this.initialized = false;
+    }
+}
+
+// Singleton instance
+const gatewayManager = new GatewayManager();
+
 /**
  * Get custom IPFS gateway from localStorage (user preference)
  * @returns {string|null} Custom gateway base URL or null
@@ -48,8 +307,7 @@ function getCustomGateway() {
  * @returns {string[]} Array of gateway base URLs
  */
 function getAllGateways() {
-    const custom = getCustomGateway();
-    return custom ? [custom, ...IPFS_GATEWAYS] : IPFS_GATEWAYS;
+    return gatewayManager.getPrioritizedGateways();
 }
 
 /**
@@ -85,22 +343,28 @@ export function normalizeIpfsPath(ipfsUri) {
 /**
  * Resolve IPFS URI to HTTP URL using a specific gateway
  * @param {string} ipfsUri - IPFS URI (e.g., ipfs://Qm...)
- * @param {number} gatewayIndex - Index of gateway to use (0-based)
+ * @param {number} [gatewayIndex] - Index of gateway to use (0-based). If omitted, uses intelligent selection.
  * @returns {string|null} HTTP URL or null if invalid
  */
-export function resolveIpfsToHttp(ipfsUri, gatewayIndex = 0) {
+export function resolveIpfsToHttp(ipfsUri, gatewayIndex) {
     if (!isIpfsUri(ipfsUri)) {
         return ipfsUri; // Return as-is if not IPFS
     }
-    
+
+    const normalizedPath = normalizeIpfsPath(ipfsUri);
+
+    // If no index provided, use intelligent gateway selection
+    if (gatewayIndex === undefined) {
+        const gateway = gatewayManager.currentGateway || gatewayManager.getPrioritizedGateways()[0];
+        return gateway + normalizedPath;
+    }
+
     const gateways = getAllGateways();
     if (gatewayIndex < 0 || gatewayIndex >= gateways.length) {
         return null;
     }
-    
-    const normalizedPath = normalizeIpfsPath(ipfsUri);
+
     const gateway = gateways[gatewayIndex];
-    
     return gateway + normalizedPath;
 }
 
@@ -113,22 +377,22 @@ export function resolveIpfsToHttp(ipfsUri, gatewayIndex = 0) {
  */
 export async function fetchJsonWithIpfsSupport(urlOrIpfs, options = {}) {
     const { timeout = 10000, ...fetchOptions } = options;
-    
+
     // If it's not an IPFS URI, use regular fetch
     if (!isIpfsUri(urlOrIpfs)) {
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeout);
-        
+
         try {
             const response = await fetch(urlOrIpfs, {
                 ...fetchOptions,
                 signal: controller.signal
             });
-            
+
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
-            
+
             const json = await response.json();
             clearTimeout(timeoutId);
             return json;
@@ -140,58 +404,10 @@ export async function fetchJsonWithIpfsSupport(urlOrIpfs, options = {}) {
             throw error;
         }
     }
-    
-    // IPFS URI - try gateways in order
-    const gateways = getAllGateways();
+
+    // IPFS URI - use intelligent gateway rotation
     const normalizedPath = normalizeIpfsPath(urlOrIpfs);
-    const errors = [];
-    
-    for (let i = 0; i < gateways.length; i++) {
-        const gateway = gateways[i];
-        const httpUrl = gateway + normalizedPath;
-        
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeout);
-        
-        try {
-            const response = await fetch(httpUrl, {
-                ...fetchOptions,
-                signal: controller.signal
-            });
-            
-            clearTimeout(timeoutId);
-            
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-            }
-            
-            const json = await response.json();
-            
-            // Success - log which gateway worked (for debugging)
-            if (i > 0) {
-                console.log(`[IpfsService] Resolved IPFS via gateway ${i + 1}/${gateways.length}: ${gateway}`);
-            }
-            
-            return json;
-        } catch (error) {
-            clearTimeout(timeoutId);
-            
-            const errorMsg = error.name === 'AbortError' 
-                ? `Timeout after ${timeout}ms`
-                : error.message || 'Unknown error';
-            
-            errors.push(`Gateway ${i + 1} (${gateway}): ${errorMsg}`);
-            
-            // Continue to next gateway
-            continue;
-        }
-    }
-    
-    // All gateways failed
-    throw new Error(
-        `Failed to fetch IPFS content after trying ${gateways.length} gateways:\n` +
-        errors.join('\n')
-    );
+    return gatewayManager.fetchWithRotation(normalizedPath, { timeout, ...fetchOptions });
 }
 
 /**
@@ -242,8 +458,86 @@ export function setCustomGateway(gatewayBaseUrl) {
         } else {
             localStorage.removeItem('customIpfsGatewayBaseUrl');
         }
+        // Reset gateway manager state when custom gateway changes
+        gatewayManager.reset();
     } catch (error) {
         console.warn('[IpfsService] Failed to save custom gateway to localStorage:', error);
     }
 }
 
+// ============================================================================
+// New exports for intelligent gateway management
+// ============================================================================
+
+/**
+ * Get the current best gateway
+ * @returns {string} Current best gateway URL
+ */
+export function getGateway() {
+    return gatewayManager.currentGateway || gatewayManager.getPrioritizedGateways()[0];
+}
+
+/**
+ * Resolve an IPFS URI to an HTTP URL using the best gateway
+ * Simpler alias for resolveIpfsToHttp without gateway index
+ * @param {string} ipfsUri - IPFS URI to resolve
+ * @returns {string} HTTP URL
+ */
+export function resolveUrl(ipfsUri) {
+    if (!isIpfsUri(ipfsUri)) return ipfsUri;
+    return getGateway() + normalizeIpfsPath(ipfsUri);
+}
+
+/**
+ * Fetch JSON from IPFS with intelligent gateway rotation
+ * Cleaner API that assumes IPFS CID input
+ * @param {string} cid - IPFS CID or path
+ * @param {object} options - Fetch options
+ * @returns {Promise<object>} Parsed JSON
+ */
+export function fetchJson(cid, options = {}) {
+    return gatewayManager.fetchWithRotation(cid, options);
+}
+
+/**
+ * Get gateway statistics
+ * @returns {object} Gateway stats including current, latencies, failed, lastHealthCheck, initialized
+ */
+export function getGatewayStats() {
+    return {
+        current: gatewayManager.currentGateway,
+        latencies: Object.fromEntries(gatewayManager.gatewayLatencies),
+        failed: Array.from(gatewayManager.failedGateways),
+        lastHealthCheck: gatewayManager.lastHealthCheck,
+        initialized: gatewayManager.initialized
+    };
+}
+
+/**
+ * Initialize gateway discovery by racing all gateways
+ * @param {string} [testCid] - Optional CID to use for testing
+ * @returns {Promise<string>} Best gateway URL
+ */
+export async function initializeGatewayDiscovery(testCid) {
+    return gatewayManager.selectBestGateway(testCid);
+}
+
+/**
+ * Configure the gateway manager
+ * @param {object} options - Configuration options
+ * @param {number} [options.timeout] - Request timeout in ms
+ * @param {number} [options.maxRetries] - Max retries before marking gateway as failed
+ * @param {number} [options.healthCheckInterval] - Health check interval in ms (0 to disable)
+ * @param {boolean} [options.parallelDiscovery] - Whether to race gateways in parallel
+ * @param {boolean} [options.corsGatewaysFirst] - Whether to prioritize CORS-friendly gateways in dev
+ */
+export function configureGatewayManager(options) {
+    Object.assign(gatewayManager.config, options);
+    if (options.healthCheckInterval !== undefined) {
+        gatewayManager.stopHealthMonitoring();
+        if (options.healthCheckInterval > 0) {
+            gatewayManager.startHealthMonitoring();
+        }
+    }
+}
+