ton-provider-system 0.2.1 → 0.2.4

package/dist/index.cjs

@@ -753,17 +753,43 @@ var OnFinalityProvider = class extends BaseProvider {
     if (normalized.includes("onfinality.io")) {
       try {
         const url = new URL(normalized);
-        const baseUrl = normalized.split("?")[0];
+        const hasQueryParams = normalized.includes("?");
+        const queryString = hasQueryParams ? normalized.split("?")[1] : "";
+        const hasApiKeyInQuery = queryString.includes("apikey=");
         if (!url.pathname || url.pathname === "/") {
           if (this.provider.apiKey) {
-            return baseUrl.replace(/\/?$/, "/rpc");
+            const baseUrl2 = normalized.split("?")[0];
+            if (hasApiKeyInQuery) {
+              return normalized.replace(/\/?$/, "/rpc");
+            }
+            if (hasQueryParams) {
+              return `${baseUrl2.replace(/\/?$/, "/rpc")}?${queryString}&apikey=${encodeURIComponent(this.provider.apiKey)}`;
+            }
+            return `${baseUrl2.replace(/\/?$/, "/rpc")}?apikey=${encodeURIComponent(this.provider.apiKey)}`;
           }
+          const baseUrl = normalized.split("?")[0];
           return baseUrl.replace(/\/?$/, "/public");
         }
         if (url.pathname === "/rpc" || url.pathname === "/public") {
-          return baseUrl;
+          if (url.pathname === "/rpc") {
+            if (hasApiKeyInQuery) {
+              return normalized;
+            }
+            if (this.provider.apiKey) {
+              const baseUrl = normalized.split("?")[0];
+              if (hasQueryParams) {
+                return `${baseUrl}?${queryString}&apikey=${encodeURIComponent(this.provider.apiKey)}`;
+              }
+              return `${baseUrl}?apikey=${encodeURIComponent(this.provider.apiKey)}`;
+            }
+            return normalized;
+          }
+          if (url.pathname === "/public") {
+            return normalized.split("?")[0];
+          }
+          return normalized;
         }
-        return baseUrl;
+        return normalized;
       } catch {
         if (normalized.includes("{key}")) {
           return normalized.split("?")[0].replace(/\/?$/, "/public");
@@ -771,7 +797,7 @@ var OnFinalityProvider = class extends BaseProvider {
         if (!normalized.includes("/rpc") && !normalized.includes("/public")) {
           return normalized.split("?")[0] + "/public";
         }
-        return normalized.split("?")[0];
+        return normalized;
       }
     }
     return normalized;
@@ -780,9 +806,6 @@ var OnFinalityProvider = class extends BaseProvider {
     const headers = {
       "Content-Type": "application/json"
     };
-    if (this.provider.apiKey) {
-      headers["apikey"] = this.provider.apiKey;
-    }
     return headers;
   }
   parseResponse(data) {
@@ -1086,7 +1109,8 @@ var HealthChecker = class {
       } catch (error) {
         if (provider.type === "onfinality" && normalizedEndpoint.includes("/rpc") && provider.apiKey && error.message?.includes("backend error")) {
           this.logger.debug(`OnFinality /rpc failed, retrying with /public endpoint`);
-          const publicEndpoint = normalizedEndpoint.replace("/rpc", "/public");
+          const baseUrl = normalizedEndpoint.split("?")[0];
+          const publicEndpoint = baseUrl.replace("/rpc", "/public");
           const publicProvider = { ...provider, apiKey: void 0 };
           const publicProviderImpl = createProvider(publicProvider);
           info = await this.callGetMasterchainInfo(publicEndpoint, publicProvider, publicProviderImpl);
@@ -1133,17 +1157,26 @@ var HealthChecker = class {
       const endTime = performance.now();
       const latencyMs = Math.round(endTime - startTime);
       const errorMsg = error.message || String(error) || "Unknown error";
+      const errorMsgLower = errorMsg.toLowerCase();
       const isCorsError = this.isCorsError(error, errorMsg);
-      const is429 = errorMsg.includes("429") || errorMsg.toLowerCase().includes("rate limit");
-      const is404 = errorMsg.includes("404") || errorMsg.toLowerCase().includes("not found");
-      const is503 = errorMsg.includes("503") || errorMsg.toLowerCase().includes("service unavailable");
-      const is502 = errorMsg.includes("502") || errorMsg.toLowerCase().includes("bad gateway");
-      const isTimeout = error.name === "AbortError" || errorMsg.includes("timeout");
-      const isOnFinalityBackendError = provider.type === "onfinality" && (errorMsg.includes("Backend error") || errorMsg.includes("backend error"));
+      const responseStatus = error?.response?.status || error?.status || error?.statusCode || null;
+      const statusMatch = errorMsg.match(/\b(\d{3})\b/);
+      const statusFromMsg = statusMatch ? parseInt(statusMatch[1], 10) : null;
+      const httpStatus = responseStatus || statusFromMsg;
+      const is429 = httpStatus === 429 || errorMsgLower.includes("429") || errorMsgLower.includes("rate limit") || errorMsgLower.includes("too many requests");
+      const is404 = httpStatus === 404 || errorMsgLower.includes("404") || errorMsgLower.includes("not found");
+      const is401 = httpStatus === 401 || errorMsgLower.includes("401") || errorMsgLower.includes("unauthorized") || errorMsgLower.includes("invalid api key") || errorMsgLower.includes("authentication failed");
+      const is403 = httpStatus === 403 || errorMsgLower.includes("403") || errorMsgLower.includes("forbidden");
+      const is503 = httpStatus === 503 || errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
+      const is502 = httpStatus === 502 || errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
+      const isTimeout = error.name === "AbortError" || errorMsgLower.includes("timeout") || errorMsgLower.includes("timed out") || errorMsgLower.includes("aborted");
+      const isOnFinalityBackendError = provider.type === "onfinality" && (errorMsgLower.includes("backend error") || errorMsgLower.includes("backend error"));
       let status = "offline";
       if (is429) {
         status = "degraded";
-      } else if (is404 || is503 || is502 || isOnFinalityBackendError) {
+      } else if (is404 || is401 || is403) {
+        status = "offline";
+      } else if (is503 || is502 || isOnFinalityBackendError) {
         status = "offline";
       } else if (isTimeout) {
         status = "offline";
@@ -1171,8 +1204,9 @@ var HealthChecker = class {
    * 
    * @param batchSize - Number of providers to test in parallel (default: 2)
    * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+   *                       If not provided, calculates delay based on lowest RPS in batch
    */
-  async testProviders(providers, batchSize = 2, batchDelayMs = 500) {
+  async testProviders(providers, batchSize = 2, batchDelayMs) {
     const results = [];
     for (let i = 0; i < providers.length; i += batchSize) {
       const batch = providers.slice(i, i + batchSize);
@@ -1180,8 +1214,15 @@ var HealthChecker = class {
         batch.map((p) => this.testProvider(p))
       );
       results.push(...batchResults);
-      if (i + batchSize < providers.length && batchDelayMs > 0) {
-        await this.sleep(batchDelayMs);
+      if (i + batchSize < providers.length) {
+        let delay = batchDelayMs;
+        if (delay === void 0) {
+          const minRps = Math.min(...batch.map((p) => p.rps || 1));
+          delay = Math.max(500, Math.ceil(1e3 / minRps * 1.5));
+        }
+        if (delay > 0) {
+          await this.sleep(delay);
+        }
       }
     }
     return results;
@@ -1570,24 +1611,36 @@ var TokenBucketRateLimiter = class {
     const startTime = Date.now();
     if (this.processing) {
       const acquired = await new Promise((resolve) => {
+        let timeoutInterval = null;
+        let resolved = false;
+        const cleanup = () => {
+          if (timeoutInterval !== null) {
+            clearInterval(timeoutInterval);
+            timeoutInterval = null;
+          }
+        };
         const checkTimeout = () => {
           if (Date.now() - startTime > timeoutMs) {
             const idx = this.requestQueue.indexOf(resolveCallback);
             if (idx >= 0) {
               this.requestQueue.splice(idx, 1);
             }
-            resolve(false);
+            if (!resolved) {
+              resolved = true;
+              cleanup();
+              resolve(false);
+            }
           }
         };
-        const resolveCallback = () => resolve(true);
-        this.requestQueue.push(resolveCallback);
-        const timeoutInterval = setInterval(checkTimeout, 1e3);
-        const cleanup = () => clearInterval(timeoutInterval);
-        Promise.resolve().then(() => {
-          if (this.requestQueue.includes(resolveCallback)) ; else {
+        const resolveCallback = () => {
+          if (!resolved) {
+            resolved = true;
             cleanup();
+            resolve(true);
           }
-        });
+        };
+        this.requestQueue.push(resolveCallback);
+        timeoutInterval = setInterval(checkTimeout, 1e3);
       });
       if (!acquired) {
         return false;
@@ -1595,24 +1648,25 @@ var TokenBucketRateLimiter = class {
     }
     this.processing = true;
     try {
-      this.refill();
       if (this.currentBackoff > 0) {
         this.logger.debug(`Applying backoff: ${this.currentBackoff}ms`);
         await sleep(this.currentBackoff);
         this.lastRefill = Date.now();
-        this.currentBackoff = 0;
       }
+      this.refill();
       while (this.tokens <= 0) {
         if (Date.now() - startTime > timeoutMs) {
           return false;
         }
-        await sleep(Math.min(100, this.config.minDelayMs));
+        const waitTime = Math.min(100, this.config.minDelayMs);
+        await sleep(waitTime);
         this.refill();
       }
       this.tokens--;
       const timeSinceLastRefill = Date.now() - this.lastRefill;
       if (timeSinceLastRefill < this.config.minDelayMs) {
-        await sleep(this.config.minDelayMs - timeSinceLastRefill);
+        const remainingDelay = this.config.minDelayMs - timeSinceLastRefill;
+        await sleep(remainingDelay);
       }
       this.lastRefill = Date.now();
       return true;
@@ -1630,10 +1684,21 @@ var TokenBucketRateLimiter = class {
   release() {
   }
   /**
-   * Report a successful request (resets backoff)
+   * Report a successful request (gradually reduces backoff)
+   * 
+   * Instead of immediately clearing backoff, we gradually reduce it to prevent
+   * immediately hitting the rate limit again after a single success.
    */
   reportSuccess() {
-    this.currentBackoff = 0;
+    if (this.currentBackoff > 0) {
+      this.currentBackoff = Math.max(
+        this.config.minDelayMs,
+        Math.floor(this.currentBackoff / 2)
+      );
+      if (this.currentBackoff <= this.config.minDelayMs) {
+        this.currentBackoff = 0;
+      }
+    }
     this.consecutiveErrors = 0;
   }
   /**
@@ -1824,7 +1889,9 @@ var DEFAULT_CONFIG2 = {
   latencyWeight: 0.4,
   priorityWeight: 0.3,
   freshnessWeight: 0.3,
-  minStatus: ["available", "degraded"]
+  minStatus: ["available", "degraded"],
+  retryCooldownMs: 3e4
+  // 30 seconds
 };
 var ProviderSelector = class {
   constructor(registry, healthChecker, config, logger, adapter = "node") {
@@ -1918,14 +1985,19 @@ var ProviderSelector = class {
           return defaultProvider;
         }
         if (health.success === false && health.lastTested) {
-          const timeSinceFailure = Date.now() - health.lastTested.getTime();
-          const cooldownMs = 3e4;
-          if (timeSinceFailure > cooldownMs) {
-            this.logger.warn(
-              `No healthy providers for ${network}, retrying failed default after cooldown: ${defaultProvider.id}`
+          if (this.isRetryableError(health.error)) {
+            const timeSinceFailure = Date.now() - health.lastTested.getTime();
+            if (timeSinceFailure > this.config.retryCooldownMs) {
+              this.logger.warn(
+                `No healthy providers for ${network}, retrying failed default after cooldown: ${defaultProvider.id}`
+              );
+              this.activeProviderByNetwork.set(network, defaultProvider.id);
+              return defaultProvider;
+            }
+          } else {
+            this.logger.debug(
+              `Skipping provider ${defaultProvider.id} with permanent error: ${health.error}`
             );
-            this.activeProviderByNetwork.set(network, defaultProvider.id);
-            return defaultProvider;
           }
         }
       }
@@ -1939,14 +2011,19 @@ var ProviderSelector = class {
           return provider;
         }
         if (health.success === false && health.lastTested) {
-          const timeSinceFailure = Date.now() - health.lastTested.getTime();
-          const cooldownMs = 3e4;
-          if (timeSinceFailure > cooldownMs) {
-            this.logger.warn(
-              `No healthy providers for ${network}, retrying failed provider after cooldown: ${provider.id}`
+          if (this.isRetryableError(health.error)) {
+            const timeSinceFailure = Date.now() - health.lastTested.getTime();
+            if (timeSinceFailure > this.config.retryCooldownMs) {
+              this.logger.warn(
+                `No healthy providers for ${network}, retrying failed provider after cooldown: ${provider.id}`
+              );
+              this.activeProviderByNetwork.set(network, provider.id);
+              return provider;
+            }
+          } else {
+            this.logger.debug(
+              `Skipping provider ${provider.id} with permanent error: ${health.error}`
             );
-            this.activeProviderByNetwork.set(network, provider.id);
-            return provider;
           }
         }
       }
@@ -1961,6 +2038,12 @@ var ProviderSelector = class {
       this.logger.debug(
         `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)})`
       );
+    } else if (bestHealth && bestHealth.success === false) {
+      this.bestProviderByNetwork.delete(network);
+      this.activeProviderByNetwork.set(network, best.id);
+      this.logger.debug(
+        `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)}, failed - not cached)`
+      );
     } else {
       this.activeProviderByNetwork.set(network, best.id);
       this.logger.debug(
@@ -2011,11 +2094,12 @@ var ProviderSelector = class {
       return 0.01 * (1 / (provider.priority + 1));
     }
     if (health.success === false) {
-      if (health.lastTested) {
-        const timeSinceFailure = Date.now() - health.lastTested.getTime();
-        const cooldownMs = 3e4;
-        if (timeSinceFailure > cooldownMs) {
-          return 1e-3 * (1 / (provider.priority + 1));
+      if (this.isRetryableError(health.error)) {
+        if (health.lastTested) {
+          const timeSinceFailure = Date.now() - health.lastTested.getTime();
+          if (timeSinceFailure > this.config.retryCooldownMs) {
+            return 1e-3 * (1 / (provider.priority + 1));
+          }
         }
       }
       return 0;
@@ -2210,6 +2294,34 @@ var ProviderSelector = class {
       return true;
     });
   }
+  /**
+   * Check if an error is retryable (temporary) or permanent
+   * 
+   * Permanent errors (never retry):
+   * - 404 (Not Found) - endpoint doesn't exist
+   * - 401 (Unauthorized) - invalid API key
+   * - Invalid API key errors
+   * 
+   * Retryable errors (can retry after cooldown):
+   * - 503 (Service Unavailable) - temporary server issue
+   * - 502 (Bad Gateway) - temporary gateway issue
+   * - Timeout errors - network issues
+   * - Network errors - connection issues
+   * - 429 (Rate Limit) - temporary rate limit (handled separately)
+   */
+  isRetryableError(error) {
+    if (!error) {
+      return true;
+    }
+    const errorLower = error.toLowerCase();
+    if (errorLower.includes("404") || errorLower.includes("not found") || errorLower.includes("401") || errorLower.includes("unauthorized") || errorLower.includes("invalid api key") || errorLower.includes("api key is invalid") || errorLower.includes("authentication failed") || errorLower.includes("forbidden")) {
+      return false;
+    }
+    if (errorLower.includes("503") || errorLower.includes("service unavailable") || errorLower.includes("502") || errorLower.includes("bad gateway") || errorLower.includes("timeout") || errorLower.includes("network error") || errorLower.includes("connection") || errorLower.includes("econnrefused") || errorLower.includes("enotfound")) {
+      return true;
+    }
+    return true;
+  }
 };
 function createSelector(registry, healthChecker, config, logger, adapter = "node") {
   return new ProviderSelector(registry, healthChecker, config, logger, adapter);
@@ -2633,10 +2745,17 @@ var _ProviderManager = class _ProviderManager {
     }
     const acquired = await this.rateLimiter.acquire(provider.id, timeoutMs);
     if (!acquired) {
-      this.options.logger.warn(`Rate limit timeout for ${provider.id}`);
+      const timeoutError = new Error(`Rate limit token acquisition timeout for ${provider.id} after ${timeoutMs || 6e4}ms`);
+      this.options.logger.warn(timeoutError.message);
+      this.reportError(timeoutError);
       const next = this.selector.getNextProvider(this.network, [provider.id]);
       if (next) {
-        return normalizeV2Endpoint(next.endpointV2, next);
+        const nextTimeout = timeoutMs ? Math.min(timeoutMs, 1e4) : 1e4;
+        const nextAcquired = await this.rateLimiter.acquire(next.id, nextTimeout);
+        if (nextAcquired) {
+          return normalizeV2Endpoint(next.endpointV2, next);
+        }
+        this.options.logger.warn(`Rate limit timeout for next provider ${next.id}, using fallback`);
       }
       return this.getFallbackEndpoint();
     }
@@ -2686,26 +2805,48 @@ var _ProviderManager = class _ProviderManager {
     if (!provider) {
       provider = this.selector.getBestProvider(this.network);
     }
-    if (!provider) return;
+    if (!provider) {
+      this.options.logger.warn(`Cannot report error: no provider available for ${this.network}`);
+      return;
+    }
     const errorMsg = error instanceof Error ? error.message : String(error);
     const errorMsgLower = errorMsg.toLowerCase();
-    const is429 = errorMsgLower.includes("429") || errorMsgLower.includes("rate limit");
-    const is503 = errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
-    const is502 = errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
-    const is404 = errorMsgLower.includes("404") || errorMsgLower.includes("not found");
-    const isTimeout = errorMsgLower.includes("timeout") || errorMsgLower.includes("abort");
+    const enhancedErrorMsg = `Provider ${provider.id} (${provider.name}): ${errorMsg}`;
+    const responseStatus = error instanceof Error && error?.response?.status || error instanceof Error && error?.status || error instanceof Error && error?.statusCode || null;
+    const statusMatch = errorMsg.match(/\b(\d{3})\b/);
+    const statusFromMsg = statusMatch ? parseInt(statusMatch[1], 10) : null;
+    const httpStatus = responseStatus || statusFromMsg;
+    const is429 = httpStatus === 429 || errorMsgLower.includes("429") || errorMsgLower.includes("rate limit") || errorMsgLower.includes("too many requests");
+    const is503 = httpStatus === 503 || errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
+    const is502 = httpStatus === 502 || errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
+    const is404 = httpStatus === 404 || errorMsgLower.includes("404") || errorMsgLower.includes("not found");
+    const is401 = httpStatus === 401 || errorMsgLower.includes("401") || errorMsgLower.includes("unauthorized") || errorMsgLower.includes("invalid api key") || errorMsgLower.includes("authentication failed");
+    const isTimeout = error instanceof Error && error.name === "AbortError" || errorMsgLower.includes("timeout") || errorMsgLower.includes("timed out") || errorMsgLower.includes("abort");
     if (isRateLimitError(error) || is429) {
       this.rateLimiter.reportRateLimitError(provider.id);
-      this.healthChecker.markDegraded(provider.id, this.network, errorMsg);
-    } else if (is503 || is502 || is404 || isTimeout) {
+      this.healthChecker.markDegraded(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.warn(`${enhancedErrorMsg} - Rate limit detected, switching to next provider`);
+    } else if (is404 || is401) {
+      this.rateLimiter.reportError(provider.id);
+      this.healthChecker.markOffline(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.error(`${enhancedErrorMsg} - Permanent error (${is404 ? "404" : "401"}), provider marked offline`);
+    } else if (is503 || is502 || isTimeout) {
       this.rateLimiter.reportError(provider.id);
-      this.healthChecker.markOffline(provider.id, this.network, errorMsg);
+      this.healthChecker.markOffline(provider.id, this.network, enhancedErrorMsg);
+      const errorType = is503 ? "503" : is502 ? "502" : "timeout";
+      this.options.logger.warn(`${enhancedErrorMsg} - Server error (${errorType}), switching to next provider`);
     } else {
       this.rateLimiter.reportError(provider.id);
-      this.healthChecker.markDegraded(provider.id, this.network, errorMsg);
+      this.healthChecker.markDegraded(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.warn(`${enhancedErrorMsg} - Unknown error, switching to next provider`);
+    }
+    const nextProvider = this.selector.handleProviderFailure(provider.id, this.network);
+    if (nextProvider) {
+      this.options.logger.info(`Failover: switched from ${provider.id} to ${nextProvider.id}`);
+    } else {
+      this.options.logger.warn(`Failover: no alternative provider available for ${this.network}`);
     }
     this.selector.clearCache(this.network);
-    this.selector.handleProviderFailure(provider.id, this.network);
     this.notifyListeners();
   }
   // ========================================================================
@@ -3256,9 +3397,11 @@ var BrowserAdapter = class {
   // ========================================================================
   /**
    * Make a JSON-RPC call to the TON API
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async jsonRpc(method, params = {}, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -3297,9 +3440,11 @@ var BrowserAdapter = class {
   // ========================================================================
   /**
    * Get address state
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressState(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressState?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3329,9 +3474,11 @@ var BrowserAdapter = class {
   }
   /**
    * Get address balance
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressBalance(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressBalance?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3361,9 +3508,11 @@ var BrowserAdapter = class {
   }
   /**
    * Get address information
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressInfo(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressInformation?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3391,9 +3540,11 @@ var BrowserAdapter = class {
   }
   /**
    * Run get method
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async runGetMethod(address, method, stack = [], timeoutMs = 15e3) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/runGetMethod`;
     const controller = new AbortController();