playlist-data-engine 1.1.0

package/dist/utils/arweaveGatewayManager.d.ts

@@ -0,0 +1,485 @@
+/**
+ * Arweave Gateway Manager
+ *
+ * Manages gateway fallback for Arweave URLs. When a file fails to load on one gateway,
+ * automatically tries alternate gateways. Uses in-memory caching to remember working
+ * gateways for each transaction ID.
+ *
+ * Design decisions:
+ * - Parallel gateway checking (race all gateways + Wayfinder, first to respond wins)
+ * - localStorage persistence for active gateway across sessions
+ * - 5 second timeout per gateway check
+ * - 2 hour cache TTL
+ * - Active gateway is reused without HEAD checks; only real fetch failures trigger fallback
+ *
+ * @module utils/arweaveGatewayManager
+ */
+import type { GatewayConfig } from './arweaveUtils.js';
+/**
+ * Configuration for the gateway cache entry
+ */
+export interface GatewayCache {
+    /** The 43-character Arweave transaction ID */
+    txId: string;
+    /** The gateway that was found to work for this txId */
+    workingGateway: GatewayConfig;
+    /** Timestamp when this cache entry was created (ms since epoch) */
+    timestamp: number;
+    /** Time-to-live in milliseconds */
+    ttl: number;
+}
+/**
+ * Result of a gateway URL resolution
+ */
+export interface GatewayCheckResult {
+    /** The working URL that can be used to fetch the resource */
+    workingUrl: string;
+    /** The gateway that provided the working URL */
+    gateway: GatewayConfig;
+    /** Whether this result came from cache */
+    cached: boolean;
+}
+/**
+ * Configuration options for ArweaveGatewayManager
+ */
+export interface ArweaveGatewayManagerConfig {
+    /** List of gateways to try in priority order */
+    gateways?: GatewayConfig[];
+    /** Timeout for each gateway check in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Cache TTL in milliseconds (default: 7200000 = 2 hours) */
+    cacheTTL?: number;
+    /** Threshold in ms above which a fetch is considered "slow" (default: 8000) */
+    slowResponseThreshold?: number;
+    /** Number of consecutive slow responses before proactive gateway rotation (default: 3) */
+    maxSlowResponses?: number;
+}
+/**
+ * Options for prefetching URLs
+ */
+export interface PrefetchOptions {
+    /** Maximum number of concurrent gateway checks (default: 5) */
+    concurrency?: number;
+    /** Whether to continue on errors (default: true) */
+    continueOnError?: boolean;
+}
+/**
+ * Result of prefetching a single URL
+ */
+export interface PrefetchResultEntry {
+    /** The original URL that was prefetched */
+    url: string;
+    /** The transaction ID extracted from the URL */
+    txId: string;
+    /** Whether the prefetch succeeded */
+    success: boolean;
+    /** The working gateway (if successful) */
+    gateway?: GatewayConfig;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Result of prefetching multiple URLs
+ */
+export interface PrefetchResult {
+    /** Total number of URLs processed */
+    total: number;
+    /** Number of successful prefetches */
+    succeeded: number;
+    /** Number of failed prefetches */
+    failed: number;
+    /** Number of URLs skipped (not Arweave URLs) */
+    skipped: number;
+    /** Detailed results for each URL */
+    entries: PrefetchResultEntry[];
+}
+/**
+ * Statistics about the gateway cache
+ */
+export interface CacheStats {
+    /** Number of entries in the cache */
+    size: number;
+    /** List of cached transaction IDs */
+    txIds: string[];
+    /** Cache hit count (since last clear) */
+    hitCount: number;
+    /** Cache miss count (since last clear) */
+    missCount: number;
+    /** Cache TTL in milliseconds */
+    ttl: number;
+}
+/**
+ * Health statistics for a single gateway
+ */
+export interface GatewayHealthStats {
+    /** Gateway hostname */
+    host: string;
+    /** Current priority (lower = higher priority) */
+    priority: number;
+    /** Original priority from configuration */
+    originalPriority: number;
+    /** Number of successful checks */
+    successCount: number;
+    /** Number of failed checks */
+    failureCount: number;
+    /** Total number of checks */
+    totalChecks: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Average response time in milliseconds */
+    averageResponseTime: number;
+    /** Last successful check timestamp (ms since epoch) */
+    lastSuccess: number | null;
+    /** Last failure timestamp (ms since epoch) */
+    lastFailure: number | null;
+    /** Whether the gateway is currently considered healthy */
+    isHealthy: boolean;
+}
+/**
+ * Result of running a health check on all gateways
+ */
+export interface HealthCheckResult {
+    /** Timestamp when the health check was performed */
+    timestamp: number;
+    /** Health stats for each gateway */
+    gateways: GatewayHealthStats[];
+    /** List of healthy gateway hosts */
+    healthyGateways: string[];
+    /** List of unhealthy gateway hosts */
+    unhealthyGateways: string[];
+    /** Gateway with the best response time (if any) */
+    fastestGateway: string | null;
+    /** Total time taken for the health check in ms */
+    totalTime: number;
+}
+/**
+ * Options for running a health check
+ */
+export interface HealthCheckOptions {
+    /** Transaction ID to use for health check (default: a well-known stable txId) */
+    txId?: string;
+    /** Whether to adjust priorities based on results (default: false) */
+    adjustPriorities?: boolean;
+    /** Minimum number of checks before considering adjusting priorities (default: 3) */
+    minChecksForAdjustment?: number;
+    /** Threshold for considering a gateway healthy (success rate, default: 0.5) */
+    healthyThreshold?: number;
+    /** Maximum response time to consider a gateway "fast" in ms (default: 2000) */
+    fastThreshold?: number;
+}
+/**
+ * ArweaveGatewayManager class
+ *
+ * Manages gateway fallback for Arweave URLs with caching support.
+ *
+ * @example
+ * ```ts
+ * import { arweaveGatewayManager } from 'playlist-data-engine';
+ *
+ * // Resolve an Arweave URL to a working gateway
+ * const workingUrl = await arweaveGatewayManager.resolveUrl('https://arweave.net/abc123...');
+ * // Returns working URL from first responding gateway
+ * ```
+ */
+export declare class ArweaveGatewayManager {
+    private gateways;
+    private timeout;
+    private cacheTTL;
+    private cache;
+    private logger;
+    /** Cache hit counter for statistics */
+    private hitCount;
+    /** Cache miss counter for statistics */
+    private missCount;
+    /** Health tracking data for each gateway (keyed by host) */
+    private healthData;
+    /** Original gateway priorities (for potential reset) */
+    private originalPriorities;
+    /** Maximum number of response time records to keep per gateway */
+    private readonly MAX_HEALTH_RECORDS;
+    /** AR.IO Wayfinder client for dynamic routing */
+    private wayfinder;
+    /** The currently active dynamic gateway. Used globally to prevent constant switching. */
+    private activeGateway;
+    /** Time of the most recent successful resolve/fetch for the active gateway (ms) */
+    private lastFetchTiming;
+    /** Number of consecutive slow fetch responses from the active gateway */
+    private consecutiveSlowResponses;
+    /** Threshold in ms above which a fetch is considered "slow" (default: 8000) */
+    private readonly slowResponseThreshold;
+    /** Number of consecutive slow responses before proactive gateway rotation (default: 3) */
+    private readonly maxSlowResponses;
+    constructor(config?: ArweaveGatewayManagerConfig);
+    /**
+     * Resolve an Arweave URL to a working gateway URL
+     *
+     * If the URL is not an Arweave URL, returns it unchanged.
+     * If cached, returns the cached working URL.
+     * Otherwise, tries each gateway in priority order until one works.
+     * If all gateways fail, returns the original URL.
+     *
+     * @param url - The URL to resolve
+     * @returns A working URL (or original URL if all gateways fail)
+     */
+    resolveUrlOld(url: string): Promise<string>;
+    /**
+     * Wrap a promise with a timeout to prevent hanging indefinitely.
+     * Useful for third-party calls (e.g., Wayfinder) that have no built-in timeout.
+     */
+    private withTimeout;
+    /**
+     * Resolve an Arweave URL to a working gateway URL.
+     *
+     * Strategy: try static gateways first with real fetch checks (not HEAD),
+     * fall back to Wayfinder only if all static gateways fail.
+     *
+     * @param url - The URL to resolve
+     * @param signal - Optional AbortSignal to cancel in-flight gateway checks
+     * @returns A working URL (or original URL if all gateways fail or signal is aborted)
+     */
+    resolveUrl(url: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * Report that the active gateway failed a real fetch.
+     *
+     * Call this when the URL returned by resolveUrl() actually fails to load
+     * (e.g. fetch() returns a 4xx/5xx or throws). This clears the active gateway
+     * and finds a new one, persisting the result to localStorage.
+     *
+     * When reason is 'user-cancel-fast', the active gateway is preserved since
+     * the user intentionally cancelled and the gateway is likely fine.
+     *
+     * @param url - The URL that failed
+     * @param options - Optional signal for cancellation and reason to distinguish failure types
+     * @returns A new working URL (or original if all gateways fail or user cancelled quickly)
+     */
+    reportGatewayFailure(url: string, options?: {
+        signal?: AbortSignal;
+        reason?: 'load-error' | 'user-cancel-slow' | 'user-cancel-fast';
+        excludeHost?: string;
+    }): Promise<string>;
+    /**
+     * Report that a fetch succeeded with timing data.
+     *
+     * Callers invoke this after a successful fetch to feed timing data back to the manager.
+     * If the fetch was fast, the consecutive slow counter resets. If slow, it increments
+     * and may trigger proactive gateway rotation on the next resolveUrl() call.
+     *
+     * @param timingMs - The time the fetch took in milliseconds
+     */
+    reportFetchSuccess(timingMs: number): void;
+    /**
+     * Check a single gateway and set it as active if it works.
+     * Returns the working URL, or null if the check failed.
+     */
+    private checkAndSetGateway;
+    /**
+     * Try remaining fallback gateways (everything except arweave.net).
+     * Returns the URL of the first gateway that responds, or null if all fail.
+     */
+    private tryFallbackGateways;
+    /**
+     * Try Wayfinder as a last resort when all static gateways fail.
+     * Returns the URL of a working Wayfinder-selected gateway, or null if it fails.
+     */
+    private tryWayfinder;
+    /**
+     * Set the active gateway, cache it for the txId, and persist to localStorage.
+     */
+    private setActiveGateway;
+    /**
+     * Load the persisted active gateway from localStorage.
+     */
+    private loadPersistedGateway;
+    /**
+     * Persist the active gateway to localStorage.
+     */
+    private persistGateway;
+    /**
+     * Clear the persisted gateway from localStorage.
+     */
+    private clearPersistedGateway;
+    /**
+     * Check if a gateway can serve a transaction
+     *
+     * Uses a HEAD request with timeout to check if the gateway responds.
+     * Handles CORS errors gracefully (treats as failure, not exception).
+     *
+     * @param txId - The transaction ID to check
+     * @param gateway - The gateway to check
+     * @param pathSuffix - Optional path suffix to append after txId
+     * @param signal - Optional external AbortSignal to cancel the check
+     * @returns true if the gateway can serve the transaction
+     */
+    checkGateway(txId: string, gateway: GatewayConfig, pathSuffix?: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Get the cached working gateway for a transaction ID
+     *
+     * @param txId - The transaction ID to look up
+     * @returns The cached gateway config, or null if not cached or expired
+     */
+    getCachedGateway(txId: string): GatewayConfig | null;
+    /**
+     * Cache a working gateway for a transaction ID
+     *
+     * @param txId - The transaction ID
+     * @param gateway - The working gateway to cache
+     */
+    setCache(txId: string, gateway: GatewayConfig): void;
+    /**
+     * Clear all cached gateway entries
+     */
+    clearCache(): void;
+    /**
+     * Prefetch and cache gateways for multiple URLs in parallel
+     *
+     * This is useful for warming up the cache at app startup with known model URLs.
+     * URLs are resolved in parallel with configurable concurrency.
+     *
+     * @param urls - Array of URLs to prefetch (non-Arweave URLs are skipped)
+     * @param options - Prefetch options
+     * @returns Result summary with success/failure counts and details
+     *
+     * @example
+     * ```ts
+     * const result = await arweaveGatewayManager.prefetchUrls([
+     *     'https://arweave.net/abc123.../model.json',
+     *     'https://arweave.net/def456.../model.json',
+     * ]);
+     * console.log(`Prefetched ${result.succeeded}/${result.total} URLs`);
+     * ```
+     */
+    prefetchUrls(urls: string[], options?: PrefetchOptions): Promise<PrefetchResult>;
+    /**
+     * Get statistics about the gateway cache
+     *
+     * @returns Cache statistics including size, entries, and hit/miss counts
+     *
+     * @example
+     * ```ts
+     * const stats = arweaveGatewayManager.getCacheStats();
+     * console.log(`Cache has ${stats.size} entries, hit rate: ${stats.hitCount / (stats.hitCount + stats.missCount)}`);
+     * ```
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Get all cached gateway entries (for debugging)
+     *
+     * @returns Array of all cache entries (including expired ones)
+     */
+    getCacheEntries(): GatewayCache[];
+    /**
+     * Check if a cache entry is still valid
+     *
+     * @param cache - The cache entry to check
+     * @returns true if the entry is still within its TTL
+     */
+    private isCacheValid;
+    /**
+     * Get the average response time for a gateway from health data.
+     * Returns 0 if no records exist (indicates no history).
+     *
+     * @param host - Gateway hostname
+     * @returns Average response time in ms, or 0 if no data
+     */
+    /**
+     * Get the failure rate for a gateway based on health data.
+     *
+     * @param host - Gateway hostname
+     * @returns Object with failure rate (0-1) and total check count
+     */
+    private getFailureRate;
+    private getAverageResponseTime;
+    /**
+     * Record a gateway response for health tracking
+     *
+     * @param host - Gateway hostname
+     * @param responseTime - Response time in milliseconds
+     * @param success - Whether the check was successful
+     */
+    private recordGatewayResponse;
+    /**
+     * Report real fetch timing data for a gateway.
+     *
+     * Callers invoke this after an actual data-transfer fetch (not just a HEAD check)
+     * to feed real performance data into health tracking. This is separate from the
+     * HEAD-based timing recorded by checkGateway(), and gives a more accurate picture
+     * of actual download performance.
+     *
+     * @param host - Gateway hostname that served the fetch
+     * @param timingMs - Time the full fetch took in milliseconds
+     * @param success - Whether the fetch succeeded
+     */
+    reportFetchTiming(host: string, timingMs: number, success: boolean): void;
+    /**
+     * Get health statistics for a specific gateway
+     *
+     * @param host - Gateway hostname
+     * @returns Health statistics for the gateway, or undefined if not tracked
+     */
+    getGatewayHealth(host: string): GatewayHealthStats | undefined;
+    /**
+     * Get health statistics for all gateways
+     *
+     * @returns Array of health statistics for each gateway
+     */
+    getAllGatewayHealth(): GatewayHealthStats[];
+    /**
+     * Adjust gateway priorities based on health data
+     *
+     * This method reorders gateways based on:
+     * 1. Health status (healthy gateways first)
+     * 2. Average response time (faster gateways first among healthy)
+     * 3. Success rate (higher success rate first)
+     *
+     * @param options - Options for priority adjustment
+     * @returns The new gateway order after adjustment
+     */
+    adjustGatewayPriorities(options?: {
+        /** Minimum number of checks required before adjusting (default: 3) */
+        minChecks?: number;
+        /** Threshold for considering a gateway healthy (default: 0.5) */
+        healthyThreshold?: number;
+    }): GatewayConfig[];
+    /**
+     * Run a health check on all gateways
+     *
+     * Tests each gateway by making a HEAD request to a known transaction.
+     * Optionally adjusts priorities based on results.
+     *
+     * @param options - Health check options
+     * @returns Health check results
+     *
+     * @example
+     * ```ts
+     * const result = await arweaveGatewayManager.runHealthCheck({
+     *     adjustPriorities: true,
+     * });
+     * console.log(`Fastest gateway: ${result.fastestGateway}`);
+     * console.log(`Healthy gateways: ${result.healthyGateways.join(', ')}`);
+     * ```
+     */
+    runHealthCheck(options?: HealthCheckOptions): Promise<HealthCheckResult>;
+    /**
+     * Reset gateway priorities to their original values
+     */
+    resetGatewayPriorities(): void;
+    /**
+     * Clear all health tracking data
+     */
+    clearHealthData(): void;
+}
+/**
+ * Singleton instance of ArweaveGatewayManager
+ *
+ * Uses default configuration. For custom configuration, create a new instance.
+ *
+ * @example
+ * ```ts
+ * import { arweaveGatewayManager } from 'playlist-data-engine';
+ *
+ * // Use the singleton
+ * const url = await arweaveGatewayManager.resolveUrl('https://arweave.net/abc...');
+ * ```
+ */
+export declare const arweaveGatewayManager: ArweaveGatewayManager;
+//# sourceMappingURL=arweaveGatewayManager.d.ts.map

package/dist/utils/arweaveGatewayManager.d.ts.map

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

package/dist/utils/arweaveUtils.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Arweave URL Utilities
+ *
+ * Provides utilities for parsing and constructing Arweave gateway URLs.
+ * Supports multiple gateways for fallback functionality.
+ *
+ * @module utils/arweaveUtils
+ */
+/**
+ * Configuration for an Arweave gateway
+ */
+export interface GatewayConfig {
+    /** Gateway hostname (e.g., 'arweave.net') */
+    host: string;
+    /** Protocol to use (default: 'https') */
+    protocol: 'http' | 'https';
+    /** Priority order for gateway selection (lower = higher priority) */
+    priority: number;
+}
+/**
+ * Parsed information from an Arweave URL
+ */
+export interface ArweaveUrlInfo {
+    /** The 43-character Arweave transaction ID */
+    txId: string;
+    /** The original URL that was parsed */
+    originalUrl: string;
+    /** Additional path after the txId (e.g., '/model.json', '/image.png') */
+    pathSuffix: string;
+}
+/**
+ * Default gateway configurations in priority order
+ */
+export declare const DEFAULT_GATEWAYS: GatewayConfig[];
+/**
+ * Known Arweave gateway hosts for URL detection
+ */
+export declare const KNOWN_GATEWAY_HOSTS: readonly ["arweave.net", "ar.io", "ardrive.net", "turbo-gateway.com"];
+/**
+ * Check if a URL is an Arweave URL
+ *
+ * Detects:
+ * - `ar://` protocol URLs
+ * - URLs containing known Arweave gateway hosts
+ *
+ * @param url - The URL to check
+ * @returns True if the URL is an Arweave URL
+ *
+ * @example
+ * ```ts
+ * isArweaveUrl('ar://abc123...'); // true
+ * isArweaveUrl('https://arweave.net/abc123...'); // true
+ * isArweaveUrl('https://example.com/audio.mp3'); // false
+ * ```
+ */
+export declare function isArweaveUrl(url: string): boolean;
+/**
+ * Parse an Arweave URL to extract transaction ID and any path suffix
+ *
+ * Handles both formats:
+ * - `ar://{txId}` - Native Arweave protocol
+ * - `ar://{txId}/path/to/file` - Native protocol with path suffix
+ * - `https://arweave.net/{txId}` - HTTP gateway URL
+ * - `https://arweave.net/{txId}/path/to/file` - HTTP gateway with path suffix
+ *
+ * @param url - The Arweave URL to parse
+ * @returns Parsed URL info or null if not a valid Arweave URL
+ *
+ * @example
+ * ```ts
+ * parseArweaveUrl('ar://abc123...');
+ * // { txId: 'abc123...', originalUrl: 'ar://abc123...', pathSuffix: '' }
+ *
+ * parseArweaveUrl('https://arweave.net/abc123.../model.json');
+ * // { txId: 'abc123...', originalUrl: '...', pathSuffix: '/model.json' }
+ *
+ * parseArweaveUrl('https://example.com/audio.mp3');
+ * // null
+ * ```
+ */
+export declare function parseArweaveUrl(url: string): ArweaveUrlInfo | null;
+/**
+ * Construct a gateway URL from a transaction ID and gateway config
+ *
+ * @param txId - The 43-character Arweave transaction ID
+ * @param gateway - The gateway configuration to use
+ * @param pathSuffix - Optional path suffix to append after txId (e.g., '/file.jpg')
+ * @returns The constructed gateway URL
+ *
+ * @example
+ * ```ts
+ * constructGatewayUrl('abc123...', { host: 'arweave.net', protocol: 'https', priority: 1 });
+ * // 'https://arweave.net/abc123...'
+ *
+ * constructGatewayUrl('abc123...', { host: 'arweave.net', protocol: 'https', priority: 1 }, '/model.json');
+ * // 'https://arweave.net/abc123.../model.json'
+ * ```
+ */
+export declare function constructGatewayUrl(txId: string, gateway: GatewayConfig, pathSuffix?: string): string;
+/**
+ * Get all gateway URLs for a transaction ID in priority order
+ *
+ * @param txId - The 43-character Arweave transaction ID
+ * @param gateways - Array of gateway configs (defaults to DEFAULT_GATEWAYS)
+ * @param pathSuffix - Optional path suffix to append after txId (e.g., '/file.jpg')
+ * @returns Array of gateway URLs in priority order
+ *
+ * @example
+ * ```ts
+ * getAllGatewayUrls('abc123...');
+ * // ['https://arweave.net/abc123...', 'https://ar.io/abc123...', ...]
+ *
+ * getAllGatewayUrls('abc123...', DEFAULT_GATEWAYS, '/model.json');
+ * // ['https://arweave.net/abc123.../model.json', ...]
+ * ```
+ */
+export declare function getAllGatewayUrls(txId: string, gateways?: GatewayConfig[], pathSuffix?: string): string[];
+//# sourceMappingURL=arweaveUtils.d.ts.map

package/dist/utils/arweaveUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arweaveUtils.d.ts","sourceRoot":"","sources":["../../src/utils/arweaveUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAK3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,uEAKtB,CAAC;AAQX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAajD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CA8DlE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,GAAE,MAAW,GAAG,MAAM,CAGzG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,aAAa,EAAqB,EAC5C,UAAU,GAAE,MAAW,GACxB,MAAM,EAAE,CAIV"}