@monygroupcorp/micro-web3 1.3.5 → 1.3.8

package/micro-web3-ipfs-gateway-rotation-spec.md

@@ -0,0 +1,231 @@
+# micro-web3 IpfsService: Intelligent Gateway Rotation
+
+## Current State
+
+IpfsService currently only provides:
+- `setCustomGateway(url)` - Set a custom gateway URL
+
+**Missing methods (apps need these now):**
+- `getGateway()` - Get the current gateway URL
+- `resolveUrl(ipfsUri)` - Convert `ipfs://` URI to gateway URL
+- `fetchJson(cid)` - Fetch and parse JSON from IPFS
+
+## Problem
+
+Currently, IpfsService uses a single hardcoded gateway which fails when that gateway is down or slow. Users must manually switch gateways when issues occur.
+
+## Proposed Solution
+
+Implement dynamic gateway rotation with automatic failover and performance-based selection.
+
+## Feature Requirements
+
+### 1. Gateway Pool
+
+Maintain a pool of known reliable IPFS gateways:
+
+```javascript
+const GATEWAY_POOL = [
+  'https://nftstorage.link/ipfs/',
+  'https://dweb.link/ipfs/',
+  'https://cloudflare-ipfs.com/ipfs/',
+  'https://w3s.link/ipfs/',
+  'https://ipfs.io/ipfs/'
+];
+```
+
+### 2. Environment-Aware Gateway Prioritization
+
+Detect development vs production and prioritize CORS-friendly gateways in dev:
+
+```javascript
+function getEnvironment() {
+  const hostname = window.location.hostname;
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname.includes('.local')
+    ? 'development'
+    : 'production';
+}
+
+// Gateways known to have proper CORS headers for localhost
+const CORS_FRIENDLY_GATEWAYS = [
+  'https://cloudflare-ipfs.com/ipfs/',
+  'https://dweb.link/ipfs/',
+  'https://w3s.link/ipfs/'
+];
+
+function getPrioritizedGateways() {
+  if (getEnvironment() === 'development') {
+    // In dev, put CORS-friendly gateways first
+    return [
+      ...CORS_FRIENDLY_GATEWAYS,
+      ...GATEWAY_POOL.filter(g => !CORS_FRIENDLY_GATEWAYS.includes(g))
+    ];
+  }
+  return GATEWAY_POOL;
+}
+```
+
+This ensures developers don't hit CORS issues during local development while still allowing the full gateway pool in production.
+
+### 2. Initial Gateway Selection (Race Strategy)
+
+When fetching the first batch of assets, race all gateways in parallel:
+
+```javascript
+async function selectBestGateway(testCid) {
+  const results = await Promise.allSettled(
+    GATEWAY_POOL.map(async (gateway) => {
+      const start = Date.now();
+      const response = await fetch(`${gateway}${testCid}`, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(5000)
+      });
+      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);
+
+  return successful[0]?.gateway || GATEWAY_POOL[0];
+}
+```
+
+### 3. Parallel First-Batch Loading
+
+For the initial N assets (e.g., first 3), use different gateways simultaneously to determine the fastest:
+
+```javascript
+async function loadWithGatewayDiscovery(cids) {
+  // Assign each of first N cids to different gateways
+  const gatewayStats = {};
+
+  const results = await Promise.allSettled(
+    cids.slice(0, GATEWAY_POOL.length).map((cid, i) => {
+      const gateway = GATEWAY_POOL[i % GATEWAY_POOL.length];
+      const start = Date.now();
+      return fetch(`${gateway}${cid}`)
+        .then(res => res.json())
+        .then(data => {
+          gatewayStats[gateway] = Date.now() - start;
+          return { cid, data, gateway };
+        });
+    })
+  );
+
+  // Select best gateway based on results
+  const bestGateway = Object.entries(gatewayStats)
+    .sort(([,a], [,b]) => a - b)[0]?.[0];
+
+  // Use best gateway for remaining assets
+  return { results, bestGateway };
+}
+```
+
+### 4. Automatic Failover
+
+If the selected gateway fails mid-session, automatically rotate to next best:
+
+```javascript
+class IpfsService {
+  constructor() {
+    this.currentGateway = null;
+    this.gatewayLatencies = new Map();
+    this.failedGateways = new Set();
+  }
+
+  async fetch(cid) {
+    const gateway = this.currentGateway || await this.selectBestGateway(cid);
+
+    try {
+      return await this._fetchWithTimeout(`${gateway}${cid}`);
+    } catch (err) {
+      this.failedGateways.add(gateway);
+      this.currentGateway = this._getNextBestGateway();
+      return this.fetch(cid); // Retry with new gateway
+    }
+  }
+
+  _getNextBestGateway() {
+    return GATEWAY_POOL
+      .filter(g => !this.failedGateways.has(g))
+      .sort((a, b) =>
+        (this.gatewayLatencies.get(a) || Infinity) -
+        (this.gatewayLatencies.get(b) || Infinity)
+      )[0];
+  }
+}
+```
+
+### 5. Gateway Health Monitoring
+
+Periodically test gateway health and update rankings:
+
+```javascript
+async function monitorGatewayHealth() {
+  // Run every 60 seconds in background
+  for (const gateway of GATEWAY_POOL) {
+    try {
+      const start = Date.now();
+      await fetch(`${gateway}bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi`, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(3000)
+      });
+      this.gatewayLatencies.set(gateway, Date.now() - start);
+      this.failedGateways.delete(gateway);
+    } catch {
+      this.gatewayLatencies.set(gateway, Infinity);
+    }
+  }
+}
+```
+
+## API Design
+
+```javascript
+import { IpfsService } from '@monygroupcorp/micro-web3';
+
+// Auto-selects best gateway
+const ipfs = new IpfsService();
+
+// Fetch with automatic gateway rotation
+const metadata = await ipfs.fetchJson(cid);
+const imageUrl = ipfs.resolveUrl(metadata.image);
+
+// Manual gateway override (optional)
+ipfs.setPreferredGateway('https://dweb.link/ipfs/');
+
+// Get current gateway stats
+const stats = ipfs.getGatewayStats();
+// { current: 'https://nftstorage.link/ipfs/', latencies: {...}, failed: [...] }
+```
+
+## Configuration Options
+
+```javascript
+const ipfs = new IpfsService({
+  gateways: [...customGateways],     // Override default pool
+  timeout: 5000,                      // Request timeout (ms)
+  maxRetries: 3,                      // Retries before marking gateway failed
+  healthCheckInterval: 60000,         // Health monitoring interval (ms)
+  parallelDiscovery: true,            // Use parallel first-batch strategy
+  cacheResults: true                  // Cache successful responses
+});
+```
+
+## Benefits
+
+1. **Reliability**: Automatic failover means no manual intervention when gateways fail
+2. **Performance**: Always uses the fastest available gateway
+3. **Resilience**: Survives individual gateway outages transparently
+4. **Developer Experience**: Simple API, complex logic handled internally
+
+## Migration Path
+
+1. Add new gateway rotation logic to IpfsService
+2. Keep `setCustomGateway()` for backwards compatibility
+3. Default to new auto-selection behavior
+4. Apps using IpfsService get improvements automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monygroupcorp/micro-web3",
-  "version": "1.3.5",
+  "version": "1.3.8",
   "description": "A lean, reusable Web3 toolkit with components for wallet connection, IPFS, and common Web3 UI patterns.",
   "main": "dist/micro-web3.cjs",
   "module": "dist/micro-web3.esm.js",

package/src/components/Wallet/WalletModal.js

@@ -65,6 +65,23 @@ export class WalletModal extends Component {
             )
         );
     }
+
+    static get styles() {
+        return `
+        .wallet-option .wallet-icon {
+            width: 36px;
+            height: 36px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+
+        .wallet-option .wallet-icon svg {
+            width: 28px;
+            height: 28px;
+        }
+        `;
+    }
 }
 
 export default WalletModal;