@ar.io/wayfinder-core 2.0.0 → 2.0.1

package/README.md

@@ -715,6 +715,14 @@ const wayfinder = createWayfinderClient({
 });
 ```
 
+## Resiliency
+
+Wayfinder includes built-in resiliency features:
+
+- **Gateway retry**: If a gateway returns a 5xx error or a network failure occurs, Wayfinder automatically re-selects a different gateway and retries (up to 3 attempts). Client errors (4xx) are returned immediately without retry.
+- **Fetch timeouts**: All outbound requests include configurable timeouts — 10s for metadata (HEAD, peer list), 30s for data retrieval — to prevent indefinite hangs on slow or dead gateways.
+- **Smart pagination**: `NetworkGatewaysProvider` stops fetching from the on-chain registry once enough gateways pass the filter, avoiding unnecessary RPC calls.
+
 ## Request Flow
 
 ```mermaid

package/dist/fetch/wayfinder-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wayfinder-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/wayfinder-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,mHAYlC,qBAAqB,KAAG,CAAC,CAC1B,KAAK,EAAE,GAAG,GAAG,WAAW,EACxB,IAAI,CAAC,EAAE,oBAAoB,KACxB,OAAO,CAAC,QAAQ,CAAC,CA4MrB,CAAC"}
+{"version":3,"file":"wayfinder-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/wayfinder-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,mHAYlC,qBAAqB,KAAG,CAAC,CAC1B,KAAK,EAAE,GAAG,GAAG,WAAW,EACxB,IAAI,CAAC,EAAE,oBAAoB,KACxB,OAAO,CAAC,QAAQ,CAAC,CA0PrB,CAAC"}

package/dist/fetch/wayfinder-fetch.js

@@ -94,43 +94,78 @@ export const createWayfinderFetch = ({ logger = defaultLogger, strict = false, f
                 subdomain,
                 path,
             });
-            // Select gateway using routing strategy
-            const selectedGateway = await routingStrategy.selectGateway({
-                path,
-                subdomain,
-            });
-            // it's just a non data specific request, construct the gateway URL and fetch directly
-            const redirectUrl = constructGatewayUrl({
-                selectedGateway,
-                subdomain,
-                path,
-            });
-            // Emit routing succeeded event
-            requestEmitter.emit('routing-succeeded', {
-                originalUrl: requestUri,
-                selectedGateway: selectedGateway.toString(),
-                redirectUrl: redirectUrl.toString(),
-            });
-            // if its a txId or arnsName use the dataRetrievalStrategy to fetch the data; otherwise just call internal fetch
-            if (!txId && !arnsName) {
-                logger.debug('No transaction ID or ARNS name found, performing direct fetch', {
-                    uri: requestUri,
-                });
-                return fetch(redirectUrl.toString(), init);
+            // Attempt data retrieval with gateway retry. If the selected gateway
+            // fails (network error, 5xx, timeout), re-select and try again up to
+            // maxAttempts times. 4xx responses are NOT retried (client error).
+            const maxAttempts = 3;
+            let dataResponse;
+            let selectedGateway;
+            let redirectUrl;
+            let lastError;
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                try {
+                    selectedGateway = await routingStrategy.selectGateway({
+                        path,
+                        subdomain,
+                    });
+                    redirectUrl = constructGatewayUrl({
+                        selectedGateway,
+                        subdomain,
+                        path,
+                    });
+                    // Emit routing succeeded event
+                    requestEmitter.emit('routing-succeeded', {
+                        originalUrl: requestUri,
+                        selectedGateway: selectedGateway.toString(),
+                        redirectUrl: redirectUrl.toString(),
+                    });
+                    // Non-data requests (e.g. /ar-io/info) don't need retry
+                    if (!txId && !arnsName) {
+                        logger.debug('No transaction ID or ARNS name found, performing direct fetch', { uri: requestUri });
+                        return fetch(redirectUrl.toString(), init);
+                    }
+                    const requestHeaders = {
+                        ...Object.fromEntries(new Headers(init?.headers || {})),
+                        ...createWayfinderRequestHeaders({
+                            traceId: requestSpan?.spanContext().traceId,
+                        }),
+                    };
+                    dataResponse = await dataRetrievalStrategy.getData({
+                        gateway: selectedGateway,
+                        requestUrl: redirectUrl,
+                        headers: requestHeaders,
+                    });
+                    // 4xx = client error, don't retry; 2xx/3xx = success
+                    if (dataResponse.ok ||
+                        (dataResponse.status >= 400 && dataResponse.status < 500)) {
+                        break;
+                    }
+                    // 5xx = server error, retry with different gateway
+                    logger.warn('Gateway returned server error, retrying with different gateway', {
+                        uri: requestUri,
+                        gateway: selectedGateway.toString(),
+                        status: dataResponse.status,
+                        attempt: attempt + 1,
+                        maxAttempts,
+                    });
+                }
+                catch (error) {
+                    lastError = error;
+                    if (attempt < maxAttempts - 1) {
+                        logger.warn('Gateway request failed, retrying with different gateway', {
+                            uri: requestUri,
+                            gateway: selectedGateway?.toString(),
+                            error: error.message,
+                            attempt: attempt + 1,
+                            maxAttempts,
+                        });
+                    }
+                }
+            }
+            // All attempts exhausted
+            if (!dataResponse) {
+                throw lastError ?? new Error('All gateway attempts failed');
             }
-            const requestHeaders = {
-                ...Object.fromEntries(new Headers(init?.headers || {})),
-                ...createWayfinderRequestHeaders({
-                    traceId: requestSpan?.spanContext().traceId,
-                }),
-            };
-            // Use data retrieval strategy to fetch the actual data
-            const dataResponse = await dataRetrievalStrategy.getData({
-                gateway: selectedGateway,
-                requestUrl: redirectUrl,
-                headers: requestHeaders,
-            });
-            // If the response is not successful (e.g., 404, 500), return it directly
             if (!dataResponse.ok) {
                 logger.debug('Gateway returned error response', {
                     uri: requestUri,

package/dist/gateways/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/gateways/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,IAAI,EACJ,MAAwB,EACxB,SAAkB,EAClB,KAAY,EACZ,MAAqC,EACrC,MAAsB,GACvB,EAAE;QACD,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IASK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CA2DpC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/gateways/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,IAAI,EACJ,MAAwB,EACxB,SAAkB,EAClB,KAAY,EACZ,MAAqC,EACrC,MAAsB,GACvB,EAAE;QACD,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IASK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CAwEpC"}

package/dist/gateways/network.js

@@ -23,24 +23,36 @@ export class NetworkGatewaysProvider {
             sortOrder: this.sortOrder,
             limit: this.limit,
         });
+        // Fetch enough gateways to satisfy the limit after filtering.
+        // Request up to limit per page (capped at 1000 by the SDK) and
+        // stop paginating once we have enough filtered results.
+        const pageSize = Math.min(this.limit, 1000);
         do {
             try {
                 this.logger.debug('Fetching gateways batch', { cursor, attempts });
                 const { items: newGateways = [], nextCursor } = await this.ario.getGateways({
-                    limit: 1000,
+                    limit: pageSize,
                     cursor,
                     sortBy: this.sortBy,
                     sortOrder: this.sortOrder,
-                    // TODO: support filters on gateways
                 });
                 gateways.push(...newGateways);
                 cursor = nextCursor;
-                attempts = 0; // reset attempts if we get a new cursor
+                attempts = 0;
                 this.logger.debug('Fetched gateways batch', {
                     batchSize: newGateways.length,
                     totalFetched: gateways.length,
                     nextCursor: cursor,
                 });
+                // Stop early if we already have enough gateways that pass the filter
+                const filteredSoFar = gateways.filter(this.filter);
+                if (filteredSoFar.length >= this.limit) {
+                    this.logger.debug('Reached gateway limit, stopping pagination', {
+                        filteredCount: filteredSoFar.length,
+                        limit: this.limit,
+                    });
+                    break;
+                }
             }
             catch (error) {
                 this.logger.error('Error fetching gateways', {
@@ -52,7 +64,6 @@ export class NetworkGatewaysProvider {
                 attempts++;
             }
         } while (cursor !== undefined && attempts < 3);
-        // filter out any gateways that are not joined
         const filteredGateways = gateways.filter(this.filter).slice(0, this.limit);
         this.logger.debug('Finished fetching gateways', {
             totalFetched: gateways.length,

package/dist/version.d.ts

@@ -14,5 +14,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const WAYFINDER_CORE_VERSION = "v2.0.0";
+export declare const WAYFINDER_CORE_VERSION = "v2.0.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -14,4 +14,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export const WAYFINDER_CORE_VERSION = 'v2.0.0';
+export const WAYFINDER_CORE_VERSION = 'v2.0.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",