@ar.io/sdk 3.12.0-beta.2 → 3.12.0-beta.4

package/lib/esm/common/wayfinder/wayfinder.js

@@ -236,56 +236,44 @@ export function tapAndVerifyStream({ originalStream, contentLength, verifyData,
     }
     throw new Error('Unsupported body type for cloning');
 }
-export function wrapVerifiedResponse(original, newBody, txId) {
-    // Clone headers (Header objects aren't serializable)
-    const headers = new Headers();
-    original.headers.forEach((value, key) => headers.set(key, value));
-    // Create a new Response with the new body and cloned headers
-    const wrapped = new Response(newBody, {
-        status: original.status,
-        statusText: original.statusText,
-        headers,
-    });
-    // Attach txId for downstream tracking
-    wrapped.txId = txId;
-    wrapped.redirectedFrom = original.url;
-    return wrapped;
-}
 /**
- * Creates a wrapped http client that supports ar:// protocol
+ * Creates a wrapped fetch function that supports ar:// protocol
  *
- * This function leverages a Proxy to intercept calls to the http client
- * and redirects them to the target gateway using the resolveUrl function url.
- * It also supports the http client methods like get(), post(), put(), delete(), etc.
+ * This function leverages a Proxy to intercept calls to fetch
+ * and redirects them to the target gateway using the resolveUrl function.
  *
- * Any URLs provided that are not wayfinder urls will be returned as is.
+ * Any URLs provided that are not wayfinder urls will be passed directly to fetch.
  *
- * @param httpClient - the http client to wrap (e.g. axios, fetch, got, etc.)
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
- * @returns a wrapped http client that supports ar:// protocol
+ * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, selectGateway, emitter = new WayfinderEmitter(), logger, strict = false, }) => {
-    const wayfinderRedirect = async (fn, rawArgs) => {
-        // TODO: handle if first arg is not a string (i.e. just return the result of the function call)
-        const [originalUrl, ...rest] = rawArgs;
-        if (typeof originalUrl !== 'string') {
-            logger?.debug('Original URL is not a string, skipping routing', {
+export const createWayfinderClient = ({ resolveUrl, verifyData, selectGateway, emitter = new WayfinderEmitter(), logger, strict = false, }) => {
+    // Create a function that will handle the redirection logic for ar:// URLs
+    const wayfinderRedirect = async (url, init) => {
+        // If the url is not a string or URL (e.g., it's a Request object), extract the URL from it
+        const originalUrl = url instanceof Request ? url.url : url.toString();
+        // If it's not an ar:// URL, pass it directly to fetch
+        if (!originalUrl.startsWith('ar://')) {
+            logger?.debug('Not a wayfinder URL, passing to fetch directly', {
                 originalUrl,
             });
             emitter?.emit('routing-skipped', {
-                originalUrl: JSON.stringify(originalUrl),
+                originalUrl,
             });
-            return fn(...rawArgs);
+            // we don't do anything special with non-ar:// urls, just pass them through
+            return fetch(url, init);
         }
+        // Start the routing process
         emitter?.emit('routing-started', {
-            originalUrl: originalUrl.toString(),
+            originalUrl,
         });
-        // TODO: by default we will retry 3 times but this should be configurable and moved to a routing strategy
+        // Retry logic for gateway selection
         const maxRetries = 3;
         const retryDelay = 1000;
         for (let i = 0; i < maxRetries; i++) {
             try {
                 // select the target gateway
+                // TODO: we may want to provide the `path` to select gateway so the HEAD checks in routers check the existence of the actual path/request
                 const selectedGateway = await selectGateway();
                 logger?.debug('Selected gateway', {
                     originalUrl,
@@ -306,172 +294,70 @@ export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, sele
                     originalUrl,
                     redirectUrl: redirectUrl.toString(),
                 });
-                // make the request to the target gateway using the redirect url and http client
-                const response = await fn(redirectUrl.toString(), ...rest);
-                // TODO: trigger a routing event with the raw response object?
+                // Make the request to the target gateway
+                const response = await fetch(redirectUrl.toString(), {
+                    ...init,
+                    // follow redirects as gateways use sandboxing on /txId requests
+                    redirect: 'follow',
+                });
+                // TODO: update any caching we use for the request and gateway response
                 logger?.debug(`Successfully routed request to gateway`, {
                     redirectUrl: redirectUrl.toString(),
-                    originalUrl: originalUrl.toString(),
+                    originalUrl,
                 });
-                // only verify data if the redirect url is different from the original url
-                if (response && redirectUrl.toString() !== originalUrl.toString()) {
-                    if (verifyData) {
-                        // if the headers do not have .get on them, we need to parse the headers manually
-                        const headers = new Headers();
-                        const headersObject = response.headers ?? {};
-                        if (headersObject instanceof Map) {
-                            for (const [key, value] of headersObject.entries()) {
-                                headers.set(key, value);
-                            }
-                        }
-                        else if (headersObject instanceof Headers) {
-                            for (const [key, value] of headersObject.entries()) {
-                                headers.set(key, value);
-                            }
-                        }
-                        else if (headersObject !== undefined &&
-                            typeof headersObject === 'object') {
-                            for (const [key, value] of Object.entries(headersObject)) {
-                                headers.set(key, value);
-                            }
-                        }
-                        else {
-                            throw new Error('Gateway did not return headers needed for verification', {
-                                cause: {
-                                    redirectUrl: redirectUrl.toString(),
-                                    originalUrl: originalUrl.toString(),
-                                },
-                            });
-                        }
-                        // transaction id is either in the response headers or the path of the request as the first parameter
-                        // TODO: we may want to move this parsing to be returned by the resolveUrl function depending on the redirect URL we've constructed
-                        const txId = headers.get('x-arns-resolved-id') ??
-                            redirectUrl.pathname.split('/')[1];
-                        // TODO: validate nodes return content length for all responses
-                        const contentLength = +(headers.get('content-length') ?? 0);
-                        if (!txIdRegex.test(txId)) {
-                            // no transaction id found, skip verification
-                            logger?.debug('No transaction id found, skipping verification', {
-                                redirectUrl: redirectUrl.toString(),
-                                originalUrl,
-                            });
-                            emitter?.emit('verification-skipped', {
-                                originalUrl,
-                            });
-                            return response;
-                        }
-                        emitter?.emit('identified-transaction-id', {
-                            originalUrl,
-                            selectedGateway: redirectUrl.toString(),
-                            txId,
-                        });
-                        // parse out the key that contains the response body, we'll use it later when updating the response object
-                        const responseDataKey = response.body
-                            ? 'body'
-                            : response.data
-                                ? 'data'
-                                : undefined;
-                        if (responseDataKey === undefined) {
-                            throw new Error('No data body or data provided, skipping verification', {
-                                cause: {
-                                    redirectUrl: redirectUrl.toString(),
-                                    originalUrl: originalUrl.toString(),
-                                },
-                            });
-                        }
-                        const responseBody = response[responseDataKey];
-                        // TODO: determine if it is data item or L1 transaction, and tell the verifier accordingly, just drop in hit to graphql now
-                        if (txId === undefined) {
-                            throw new Error('Failed to parse data hash from response headers', {
-                                cause: {
-                                    redirectUrl: redirectUrl.toString(),
-                                    originalUrl: originalUrl.toString(),
-                                    txId,
-                                },
-                            });
-                        }
-                        else if (responseBody === undefined) {
-                            throw new Error('No data body provided, skipping verification', {
-                                cause: {
-                                    redirectUrl: redirectUrl.toString(),
-                                    originalUrl: originalUrl.toString(),
-                                    txId,
-                                },
-                            });
-                        }
-                        else {
-                            logger?.debug('Verifying data hash for txId', {
-                                redirectUrl: redirectUrl.toString(),
-                                originalUrl: originalUrl.toString(),
-                                txId,
-                            });
-                            if (responseBody instanceof ReadableStream ||
-                                responseBody instanceof Readable) {
-                                const newClientStream = tapAndVerifyStream({
-                                    originalStream: responseBody,
-                                    contentLength,
-                                    verifyData,
-                                    txId,
-                                    emitter,
-                                    strict,
-                                });
-                                if (response instanceof Response) {
-                                    // specific to fetch
-                                    return wrapVerifiedResponse(response, newClientStream, txId);
-                                }
-                                else {
-                                    // overwrite the response body with the new client stream
-                                    response.txId = txId;
-                                    response.body = newClientStream;
-                                    return response;
-                                }
-                            }
-                            else {
-                                // TODO: content-application/json and it's smaller than 10mb
-                                // TODO: add tests and verify this works for all non-Readable/streamed responses
-                                if (strict) {
-                                    // In strict mode, wait for verification before returning response
-                                    try {
-                                        await verifyData({
-                                            data: responseBody,
-                                            txId,
-                                        });
-                                        emitter?.emit('verification-succeeded', { txId });
-                                        return response;
-                                    }
-                                    catch (error) {
-                                        logger?.debug('Failed to verify data hash', {
-                                            error,
-                                            txId,
-                                        });
-                                        emitter?.emit('verification-failed', { txId, error });
-                                        throw new Error('Verification failed', { cause: error });
-                                    }
-                                }
-                                else {
-                                    // In non-strict mode, perform verification in the background
-                                    verifyData({
-                                        data: responseBody,
-                                        txId,
-                                    })
-                                        .then(() => {
-                                        emitter?.emit('verification-succeeded', { txId });
-                                    })
-                                        .catch((error) => {
-                                        logger?.debug('Failed to verify data hash', {
-                                            error,
-                                            txId,
-                                        });
-                                        emitter?.emit('verification-failed', { txId, error });
-                                    });
-                                    return response;
-                                }
-                            }
-                        }
-                    }
+                // return the response right away if no redirect was made
+                if (redirectUrl.toString() === originalUrl) {
+                    return response;
+                }
+                // return the response right away if no verification is needed or if there is no body
+                if (!verifyData) {
+                    return response;
+                }
+                // the txId is either in the response headers or the path of the request as the first parameter
+                const txId = response.headers.get('x-arns-resolved-id') ??
+                    redirectUrl.pathname.split('/')[1];
+                const contentLength = +(response.headers.get('content-length') ?? 0);
+                if (!txIdRegex.test(txId)) {
+                    // No transaction ID found, skip verification
+                    logger?.debug('No transaction ID found, skipping verification', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl,
+                    });
+                    emitter?.emit('verification-skipped', {
+                        originalUrl,
+                    });
+                    return response;
+                }
+                emitter?.emit('identified-transaction-id', {
+                    originalUrl,
+                    selectedGateway: redirectUrl.toString(),
+                    txId,
+                });
+                if (!response.body) {
+                    logger?.debug('No body, skipping verification', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl,
+                    });
+                    emitter?.emit('verification-skipped', {
+                        originalUrl,
+                    });
+                    return response;
                 }
-                // TODO: if strict - wait for verification to finish and succeed before returning the response
-                return response;
+                const verifiedStream = tapAndVerifyStream({
+                    originalStream: response.body,
+                    contentLength,
+                    verifyData,
+                    txId,
+                    emitter,
+                    strict,
+                });
+                // wrap the response with the verified stream
+                return new Response(verifiedStream, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    // TODO: we could add identified transaction id to the headers here, but it would be changing information from the original response
+                    headers: response.headers,
+                });
             }
             catch (error) {
                 logger?.debug('Failed to route request', {
@@ -484,6 +370,12 @@ export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, sele
                 if (i < maxRetries - 1) {
                     await new Promise((resolve) => setTimeout(resolve, retryDelay));
                 }
+                else {
+                    emitter?.emit('routing-failed', {
+                        originalUrl,
+                        error,
+                    });
+                }
             }
         }
         throw new Error('Failed to route request after max retries', {
@@ -493,37 +385,12 @@ export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, sele
             },
         });
     };
-    return new Proxy(httpClient, {
-        // support direct calls: fetch('ar://…', options)
-        // axios() or got()
-        apply: (_target, _thisArg, argArray) => wayfinderRedirect(httpClient, argArray),
-        // support http clients that use functions like `got.get`, `got.post`, `axios.get`, etc. while still using the wayfinder redirect function
-        get: (target, prop, receiver) => {
-            const value = Reflect.get(target, prop, receiver);
-            if (typeof value === 'function') {
-                return (...inner) => wayfinderRedirect(value.bind(target), inner);
-            }
-            return value; // numbers, objects, symbols pass through untouched
-        },
-    });
+    return wayfinderRedirect;
 };
 /**
  * The main class for the wayfinder
- * @param router - the router to use for requests
- * @param httpClient - the http client to use for requests
- * @param blocklist - the blocklist of gateways to avoid
  */
 export class Wayfinder {
-    /**
-     * The native http client used by wayfinder. By default, the native fetch api is used.
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   httpClient: axios,
-     * });
-     *
-     */
-    httpClient;
     /**
      * The gateways provider is responsible for providing the list of gateways to use for routing requests.
      *
@@ -564,8 +431,7 @@ export class Wayfinder {
      */
     resolveUrl;
     /**
-     *
-     * A wrapped http client that supports ar:// protocol. If a verification strategy is provided,
+     * A wrapped fetch function that supports ar:// protocol. If a verification strategy is provided,
      * the request will be verified and events will be emitted as the request is processed.
      *
      * @example
@@ -585,9 +451,6 @@ export class Wayfinder {
      * // request a transaction id
      * const response = await wayfinder.request('ar://1234567890')
      *
-     * // request a transaction id with a custom http client
-     * const response = await wayfinder.request('ar://1234567890')
-     *
      * // Set strict mode to true to make verification blocking
      * const wayfinder = new Wayfinder({
      *   strict: true,
@@ -653,14 +516,13 @@ export class Wayfinder {
     emitter;
     /**
      * The constructor for the wayfinder
-     * @param httpClient - the http client to use for requests
      * @param routingStrategy - the routing strategy to use for requests
      * @param verificationStrategy - the verification strategy to use for requests
      * @param gatewaysProvider - the gateways provider to use for routing requests
      * @param logger - the logger to use for logging
      * @param strict - if true, verification will be blocking and will fail requests if verification fails; if false, verification will be non-blocking
      */
-    constructor({ httpClient = fetch, logger = Logger.default, gatewaysProvider = new SimpleCacheGatewaysProvider({
+    constructor({ logger = Logger.default, gatewaysProvider = new SimpleCacheGatewaysProvider({
         gatewaysProvider: new NetworkGatewaysProvider({
             ario: ARIO.mainnet(),
         }),
@@ -683,12 +545,9 @@ export class Wayfinder {
         onVerificationProgress: (event) => {
             logger.debug('Verification progress!', event);
         },
-    }, strict = false,
-    // TODO: stats provider
-     }) {
+    }, strict = false, }) {
         this.routingStrategy = routingStrategy;
         this.gatewaysProvider = gatewaysProvider;
-        this.httpClient = httpClient;
         this.emitter = new WayfinderEmitter(events);
         this.verifyData =
             verificationStrategy.verifyData.bind(verificationStrategy);
@@ -706,7 +565,6 @@ export class Wayfinder {
         };
         // create a wayfinder client with the routing strategy and gateways provider
         this.request = createWayfinderClient({
-            httpClient,
             selectGateway: async () => {
                 return this.routingStrategy.selectGateway({
                     gateways: await this.gatewaysProvider.getGateways(),

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '3.12.0-beta.2';
+export const version = '3.12.0-beta.4';

package/lib/types/common/wayfinder/index.d.ts

@@ -18,6 +18,7 @@ export * from './routing/strategies/random.js';
 export * from './routing/strategies/static.js';
 export * from './routing/strategies/ping.js';
 export * from './routing/strategies/round-robin.js';
+export * from './routing/strategies/preferred-with-fallback.js';
 export * from './gateways/network.js';
 export * from './gateways/simple-cache.js';
 export * from './gateways/static.js';

package/lib/types/common/wayfinder/routing/strategies/preferred-with-fallback.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { RoutingStrategy } from '../../../../types/wayfinder.js';
+import { Logger } from '../../../logger.js';
+export declare class PreferredWithFallbackRoutingStrategy implements RoutingStrategy {
+    readonly name = "preferred-with-fallback";
+    private preferredGateway;
+    private fallbackStrategy;
+    private logger;
+    constructor({ preferredGateway, fallbackStrategy, logger, }: {
+        preferredGateway: string;
+        fallbackStrategy?: RoutingStrategy;
+        logger?: Logger;
+    });
+    selectGateway({ gateways }: {
+        gateways: URL[];
+    }): Promise<URL>;
+}

package/lib/types/common/wayfinder/wayfinder.d.ts

@@ -17,9 +17,7 @@ import EventEmitter from 'node:events';
 import { PassThrough, Readable } from 'node:stream';
 import { DataVerificationStrategy, GatewaysProvider, RoutingStrategy } from '../../types/wayfinder.js';
 import { Logger } from '../logger.js';
-type HttpClientArgs = unknown[];
-type HttpClientFunction = (...args: HttpClientArgs) => unknown;
-type WayfinderHttpClient<T extends HttpClientFunction> = T;
+type WayfinderHttpClient = typeof fetch;
 export declare const arnsRegex: RegExp;
 export declare const txIdRegex: RegExp;
 /**
@@ -100,53 +98,33 @@ export declare function tapAndVerifyStream<T extends Readable | ReadableStream>(
     emitter?: WayfinderEmitter;
     strict?: boolean;
 }): T extends Readable ? PassThrough : T;
-export declare function wrapVerifiedResponse(original: Response, newBody: ReadableStream<Uint8Array>, txId: string): Response;
 /**
- * Creates a wrapped http client that supports ar:// protocol
+ * Creates a wrapped fetch function that supports ar:// protocol
  *
- * This function leverages a Proxy to intercept calls to the http client
- * and redirects them to the target gateway using the resolveUrl function url.
- * It also supports the http client methods like get(), post(), put(), delete(), etc.
+ * This function leverages a Proxy to intercept calls to fetch
+ * and redirects them to the target gateway using the resolveUrl function.
  *
- * Any URLs provided that are not wayfinder urls will be returned as is.
+ * Any URLs provided that are not wayfinder urls will be passed directly to fetch.
  *
- * @param httpClient - the http client to wrap (e.g. axios, fetch, got, etc.)
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
- * @returns a wrapped http client that supports ar:// protocol
+ * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export declare const createWayfinderClient: <T extends HttpClientFunction>({ httpClient, resolveUrl, verifyData, selectGateway, emitter, logger, strict, }: {
-    httpClient: T;
+export declare const createWayfinderClient: ({ resolveUrl, verifyData, selectGateway, emitter, logger, strict, }: {
     selectGateway: () => Promise<URL>;
     resolveUrl: (params: {
         originalUrl: string | URL;
         selectedGateway: URL;
         logger?: Logger;
     }) => URL;
-    verifyData?: <T_1 extends Readable | ReadableStream | Buffer>({ data, txId, }: {
-        data: T_1;
-        txId: string;
-    }) => Promise<void>;
+    verifyData?: DataVerificationStrategy["verifyData"];
     logger?: Logger;
     emitter?: WayfinderEmitter;
     strict?: boolean;
-}) => WayfinderHttpClient<T>;
+}) => WayfinderHttpClient;
 /**
  * The main class for the wayfinder
- * @param router - the router to use for requests
- * @param httpClient - the http client to use for requests
- * @param blocklist - the blocklist of gateways to avoid
  */
-export declare class Wayfinder<T extends HttpClientFunction> {
-    /**
-     * The native http client used by wayfinder. By default, the native fetch api is used.
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   httpClient: axios,
-     * });
-     *
-     */
-    readonly httpClient: T;
+export declare class Wayfinder {
     /**
      * The gateways provider is responsible for providing the list of gateways to use for routing requests.
      *
@@ -190,8 +168,7 @@ export declare class Wayfinder<T extends HttpClientFunction> {
         logger?: Logger;
     }) => Promise<URL>;
     /**
-     *
-     * A wrapped http client that supports ar:// protocol. If a verification strategy is provided,
+     * A wrapped fetch function that supports ar:// protocol. If a verification strategy is provided,
      * the request will be verified and events will be emitted as the request is processed.
      *
      * @example
@@ -211,9 +188,6 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * // request a transaction id
      * const response = await wayfinder.request('ar://1234567890')
      *
-     * // request a transaction id with a custom http client
-     * const response = await wayfinder.request('ar://1234567890')
-     *
      * // Set strict mode to true to make verification blocking
      * const wayfinder = new Wayfinder({
      *   strict: true,
@@ -226,7 +200,7 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      *   console.error('Verification failed', error);
      * }
      */
-    readonly request: WayfinderHttpClient<T>;
+    readonly request: WayfinderHttpClient;
     /**
      * The function that verifies the data hash for a given transaction id.
      *
@@ -279,15 +253,13 @@ export declare class Wayfinder<T extends HttpClientFunction> {
     readonly emitter: WayfinderEmitter;
     /**
      * The constructor for the wayfinder
-     * @param httpClient - the http client to use for requests
      * @param routingStrategy - the routing strategy to use for requests
      * @param verificationStrategy - the verification strategy to use for requests
      * @param gatewaysProvider - the gateways provider to use for routing requests
      * @param logger - the logger to use for logging
      * @param strict - if true, verification will be blocking and will fail requests if verification fails; if false, verification will be non-blocking
      */
-    constructor({ httpClient, logger, gatewaysProvider, routingStrategy, verificationStrategy, events, strict, }: {
-        httpClient?: T;
+    constructor({ logger, gatewaysProvider, routingStrategy, verificationStrategy, events, strict, }: {
         routingStrategy?: RoutingStrategy;
         gatewaysProvider?: GatewaysProvider;
         verificationStrategy?: DataVerificationStrategy;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "3.12.0-beta.1";
+export declare const version = "3.12.0-beta.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.12.0-beta.2",
+  "version": "3.12.0-beta.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"