@ar.io/sdk 3.11.0-alpha.9 → 3.11.0-beta.1

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

@@ -17,50 +17,47 @@ import EventEmitter from 'node:events';
 import { PassThrough, Readable } from 'node:stream';
 import { ARIO } from '../io.js';
 import { Logger } from '../logger.js';
-import { NetworkGatewaysProvider, SimpleCacheGatewaysProvider, StaticGatewaysProvider, } from './gateways.js';
-import { TrustedGatewaysHashProvider } from './gateways/trusted-gateways.js';
-import { RandomGatewayRouter } from './routers/random.js';
-import { HashVerifier } from './verification/hash-verifier.js';
+import { NetworkGatewaysProvider } from './gateways/network.js';
+import { SimpleCacheGatewaysProvider } from './gateways/simple-cache.js';
+import { StaticGatewaysProvider } from './gateways/static.js';
+import { FastestPingRoutingStrategy } from './routing/strategies/ping.js';
+import { HashVerificationStrategy } from './verification/strategies/hash-verifier.js';
+import { TrustedGatewaysHashProvider } from './verification/trusted.js';
 // known regexes for wayfinder urls
 export const arnsRegex = /^[a-z0-9_-]{1,51}$/;
 export const txIdRegex = /^[A-Za-z0-9_-]{43}$/;
 /**
- * Core function to resolve a wayfinder url against a target gateway
+ * Core function that converts a wayfinder url to the proper ar-io gateway URL
  * @param originalUrl - the wayfinder url to resolve
- * @param targetGateway - the target gateway to resolve the url against
+ * @param selectedGateway - the target gateway to resolve the url against
  * @returns the resolved url that can be used to make a request
  */
-export const resolveWayfinderUrl = async ({ originalUrl, targetGateway, logger, }) => {
+export const resolveWayfinderUrl = ({ originalUrl, selectedGateway, logger, }) => {
     if (originalUrl.toString().startsWith('ar://')) {
         logger?.debug(`Applying wayfinder routing protocol to ${originalUrl}`, {
             originalUrl,
         });
-        const targetGatewayUrl = new URL(await targetGateway());
-        logger?.debug(`Selected target gateway: ${targetGatewayUrl}`, {
-            originalUrl,
-            targetGateway: targetGatewayUrl,
-        });
         const [, path] = originalUrl.toString().split('ar://');
         // e.g. ar:///info should route to the info endpoint of the target gateway
         if (path.startsWith('/')) {
-            logger?.debug(`Routing to ${path.slice(1)} on ${targetGatewayUrl}`, {
+            logger?.debug(`Routing to ${path.slice(1)} on ${selectedGateway}`, {
                 originalUrl,
-                targetGateway: targetGatewayUrl,
+                selectedGateway,
             });
-            return new URL(path.slice(1), targetGatewayUrl);
+            return new URL(path.slice(1), selectedGateway);
         }
         // TODO: this breaks 43 character named arns names - we should check a a local name cache list before resolving raw transaction ids
         if (txIdRegex.test(path)) {
             const [txId, ...rest] = path.split('/');
-            return new URL(`${txId}${rest.join('/')}`, targetGatewayUrl);
+            return new URL(`${txId}${rest.join('/')}`, selectedGateway);
         }
         if (arnsRegex.test(path)) {
             // TODO: tests to ensure arns names support query params and paths
             const [name, ...rest] = path.split('/');
-            const arnsUrl = `${targetGatewayUrl.protocol}//${name}.${targetGatewayUrl.hostname}${targetGatewayUrl.port ? `:${targetGatewayUrl.port}` : ''}`;
+            const arnsUrl = `${selectedGateway.protocol}//${name}.${selectedGateway.hostname}${selectedGateway.port ? `:${selectedGateway.port}` : ''}`;
             logger?.debug(`Routing to ${path} on ${arnsUrl}`, {
                 originalUrl,
-                targetGateway: targetGatewayUrl,
+                selectedGateway,
             });
             return new URL(rest.join('/'), arnsUrl);
         }
@@ -79,7 +76,7 @@ export class WayfinderEmitter extends EventEmitter {
      } = {}) {
         super();
         if (onVerificationPassed) {
-            this.on('verification-passed', onVerificationPassed);
+            this.on('verification-succeeded', onVerificationPassed);
         }
         if (onVerificationFailed) {
             this.on('verification-failed', onVerificationFailed);
@@ -95,7 +92,7 @@ export class WayfinderEmitter extends EventEmitter {
         return super.on(event, listener);
     }
 }
-export function tapAndVerifyStream({ originalStream, contentLength, verifyData, txId, emitter, }) {
+export function tapAndVerifyStream({ originalStream, contentLength, verifyData, txId, emitter, strict = false, }) {
     // taps node streams
     if (originalStream instanceof Readable &&
         typeof originalStream.pipe === 'function') {
@@ -123,26 +120,39 @@ export function tapAndVerifyStream({ originalStream, contentLength, verifyData,
         });
         originalStream.on('end', async () => {
             streamToVerify.end(); // triggers verifier completion and completes the verification promise
-            try {
-                await verificationPromise;
-                emitter?.emit('verification-passed', {
-                    txId,
-                });
-                tappedClientStream.end();
+            if (strict) {
+                // in strict mode, we wait for verification to complete before ending the client stream
+                try {
+                    await verificationPromise;
+                    emitter?.emit('verification-succeeded', { txId });
+                    tappedClientStream.end();
+                }
+                catch (error) {
+                    emitter?.emit('verification-failed', { error, txId });
+                    // In strict mode, destroy the client stream with the error
+                    tappedClientStream.destroy(new Error('Verification failed', { cause: error }));
+                }
             }
-            catch (error) {
-                emitter?.emit('verification-failed', {
-                    error,
-                    txId,
+            else {
+                // in non-strict mode, we end the client stream immediately and handle verification asynchronously
+                tappedClientStream.end();
+                // trigger the verification promise and emit events for the result
+                verificationPromise
+                    .then(() => {
+                    emitter?.emit('verification-succeeded', { txId });
+                })
+                    .catch((error) => {
+                    emitter?.emit('verification-failed', { error, txId });
                 });
-                tappedClientStream.destroy(error);
             }
         });
         originalStream.on('error', (err) => {
+            // emit the verification failed event
             emitter?.emit('verification-failed', {
                 error: err,
                 txId,
             });
+            // destroy both streams and propagate the original stream error
             streamToVerify.destroy(err);
             tappedClientStream.destroy(err);
         });
@@ -164,20 +174,37 @@ export function tapAndVerifyStream({ originalStream, contentLength, verifyData,
             async pull(controller) {
                 const { done, value } = await reader.read();
                 if (done) {
-                    try {
-                        // due to backpressure, if the client does not consume the stream, the verification will not complete (particularly important for fetch, where the response body needs to be awaited for verification to complete)
-                        await verificationPromise;
-                        emitter?.emit('verification-passed', {
-                            txId,
-                        });
-                        controller.close();
+                    if (strict) {
+                        // in strict mode, we wait for verification to complete before closing the controller
+                        try {
+                            await verificationPromise;
+                            emitter?.emit('verification-succeeded', { txId });
+                            controller.close();
+                        }
+                        catch (err) {
+                            emitter?.emit('verification-failed', {
+                                txId,
+                                error: err,
+                            });
+                            // In strict mode, we report the error to the client stream
+                            controller.error(new Error('Verification failed', { cause: err }));
+                        }
                     }
-                    catch (err) {
-                        emitter?.emit('verification-failed', {
-                            txId,
-                            error: err,
+                    else {
+                        // in non-strict mode, we close the controller immediately and handle verification asynchronously
+                        controller.close();
+                        // trigger the verification promise and emit events for the result
+                        verificationPromise
+                            .then(() => {
+                            emitter?.emit('verification-succeeded', { txId });
+                        })
+                            .catch((err) => {
+                            emitter?.emit('verification-failed', {
+                                txId,
+                                error: err,
+                            });
+                            // we don't call controller.error() to avoid breaking the client stream
                         });
-                        controller.error(err);
                     }
                 }
                 else {
@@ -191,7 +218,9 @@ export function tapAndVerifyStream({ originalStream, contentLength, verifyData,
                 }
             },
             cancel(reason) {
+                // cancel the reader regardless of verification status
                 reader.cancel(reason);
+                // emit the verification cancellation event
                 emitter?.emit('verification-failed', {
                     txId,
                     error: new Error('Verification cancelled', {
@@ -200,6 +229,8 @@ export function tapAndVerifyStream({ originalStream, contentLength, verifyData,
                         },
                     }),
                 });
+                // note: we don't block or throw errors here even in strict mode
+                // since the stream is already being cancelled by the client
             },
         });
         return clientStreamWithVerification;
@@ -234,7 +265,7 @@ export function wrapVerifiedResponse(original, newBody, txId) {
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped http client that supports ar:// protocol
  */
-export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, emitter = new WayfinderEmitter(), logger, }) => {
+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;
@@ -242,157 +273,226 @@ export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, emit
             logger?.debug('Original URL is not a string, skipping routing', {
                 originalUrl,
             });
+            emitter?.emit('routing-skipped', {
+                originalUrl: JSON.stringify(originalUrl),
+            });
             return fn(...rawArgs);
         }
         emitter?.emit('routing-started', {
             originalUrl: originalUrl.toString(),
         });
-        // route the request to the target gateway
-        const redirectUrl = await resolveUrl({
-            originalUrl,
-            logger,
-        });
-        emitter?.emit('routing-succeeded', {
-            originalUrl,
-            targetGateway: redirectUrl.toString(),
-        });
-        logger?.debug(`Redirecting request to ${redirectUrl}`, {
-            originalUrl,
-            redirectUrl,
-        });
-        // 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?
-        logger?.debug(`Successfully routed request to ${redirectUrl}`, {
-            redirectUrl,
-            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();
-                let headersObject = response.headers ?? {};
-                if (typeof headersObject.get !== 'function') {
-                    headersObject = Object.fromEntries(headersObject);
-                    for (const [key, value] of Object.entries(headersObject)) {
-                        headers.set(key, value);
-                    }
-                }
-                else {
-                    for (const [key, value] of headersObject.entries()) {
-                        headers.set(key, value);
-                    }
-                }
-                // 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,
-                        originalUrl,
-                    });
-                    emitter?.emit('verification-skipped', {
-                        originalUrl,
-                    });
-                    return response;
-                }
-                emitter?.emit('identified-transaction-id', {
+        // TODO: by default we will retry 3 times but this should be configurable and moved to a routing strategy
+        const maxRetries = 3;
+        const retryDelay = 1000;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                // select the target gateway
+                const selectedGateway = await selectGateway();
+                logger?.debug('Selected gateway', {
                     originalUrl,
-                    targetGateway: redirectUrl.toString(),
-                    txId,
+                    selectedGateway: selectedGateway.toString(),
                 });
-                // 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(),
+                // route the request to the target gateway
+                const redirectUrl = resolveUrl({
+                    originalUrl,
+                    selectedGateway,
+                    logger,
+                });
+                emitter?.emit('routing-succeeded', {
+                    originalUrl,
+                    selectedGateway: selectedGateway.toString(),
+                    redirectUrl: redirectUrl.toString(),
+                });
+                logger?.debug(`Redirecting request`, {
+                    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?
+                logger?.debug(`Successfully routed request to gateway`, {
+                    redirectUrl: redirectUrl.toString(),
+                    originalUrl: originalUrl.toString(),
+                });
+                // 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,
-                        },
-                    });
-                }
-                else {
-                    logger?.debug('Verifying data hash for txId', {
-                        redirectUrl: redirectUrl.toString(),
-                        originalUrl: originalUrl.toString(),
-                        txId,
-                    });
-                    const newClientStream = tapAndVerifyStream({
-                        originalStream: responseBody,
-                        contentLength,
-                        verifyData,
-                        txId,
-                        emitter,
-                    });
-                    if (responseBody instanceof ReadableStream) {
-                        // specific to fetch
-                        return wrapVerifiedResponse(response, newClientStream, txId);
-                    }
-                    else if (responseBody instanceof Readable) {
-                        // 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
-                        try {
-                            // if strict set to true
-                            await verifyData({
-                                data: responseBody,
-                                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(),
+                                },
                             });
-                            emitter?.emit('verification-passed', {
-                                txId,
+                        }
+                        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,
+                                },
                             });
                         }
-                        catch (error) {
-                            logger?.debug('Failed to verify data hash', {
-                                error,
-                                txId,
+                        else if (responseBody === undefined) {
+                            throw new Error('No data body provided, skipping verification', {
+                                cause: {
+                                    redirectUrl: redirectUrl.toString(),
+                                    originalUrl: originalUrl.toString(),
+                                    txId,
+                                },
                             });
-                            emitter?.emit('verification-failed', {
+                        }
+                        else {
+                            logger?.debug('Verifying data hash for txId', {
+                                redirectUrl: redirectUrl.toString(),
+                                originalUrl: originalUrl.toString(),
                                 txId,
-                                error,
                             });
+                            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 response;
                     }
                 }
+                // TODO: if strict - wait for verification to finish and succeed before returning the response
+                return response;
+            }
+            catch (error) {
+                logger?.debug('Failed to route request', {
+                    error: error.message,
+                    stack: error.stack,
+                    originalUrl,
+                    attempt: i + 1,
+                    maxRetries,
+                });
+                if (i < maxRetries - 1) {
+                    await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                }
             }
         }
-        // TODO: if strict - wait for verification to finish and succeed before returning the response
-        return response;
+        throw new Error('Failed to route request after max retries', {
+            cause: {
+                originalUrl,
+                maxRetries,
+            },
+        });
     };
     return new Proxy(httpClient, {
         // support direct calls: fetch('ar://…', options)
@@ -416,87 +516,116 @@ export const createWayfinderClient = ({ httpClient, resolveUrl, verifyData, emit
  */
 export class Wayfinder {
     /**
-     * The router to use for requests
+     * The native http client used by wayfinder. By default, the native fetch api is used.
      *
      * @example
      * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
-     *     }),
-     *   }),
+     *   httpClient: axios,
      * });
      *
-     * // Returns a target gateway based on the routing strategy
-     * const targetGateway = await wayfinder.router.getTargetGateway();
      */
-    router;
+    httpClient;
     /**
-     * The native http client used by wayfinder
+     * The gateways provider is responsible for providing the list of gateways to use for routing requests.
      *
      * @example
      * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
-     *     }),
+     *   gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *     gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *     ttlSeconds: 60 * 60 * 24, // 1 day
      *   }),
-     *   httpClient: axios,
      * });
-     *
      */
-    httpClient;
+    gatewaysProvider;
     /**
-     * The function that resolves the redirect url for ar:// requests to a target gateway
+     * The routing strategy to use when routing requests.
      *
      * @example
      * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
-     *     }),
+     *   strategy: new FastestPingStrategy({
+     *     timeoutMs: 1000,
      *   }),
-     *   httpClient: axios,
      * });
+     */
+    routingStrategy;
+    /**
+     * A helper function that resolves the redirect url for ar:// requests to a target gateway.
+     *
+     * Note: no verification is done when resolving an ar://<path> url to a wayfinder route.
+     * In order to verify the data, you must use the `request` function or request the data and
+     * verify it yourself via the `verifyData` function.
+     *
+     * @example
+     * const { resolveUrl } = new Wayfinder();
      *
      * // returns the redirected URL based on the routing strategy and the original url
-     * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
+     * const redirectUrl = await resolveUrl({ originalUrl: 'ar://example' });
+     *
+     * window.open(redirectUrl.toString(), '_blank');
      */
     resolveUrl;
     /**
-     * A wrapped http client that supports ar:// protocol
+     *
+     * A wrapped http client 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
-     * const { request: wayfind } = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     * const wayfinder = new Wayfinder({
+     *   verificationStrategy: new HashVerificationStrategy({
+     *     trustedHashProvider: new TrustedGatewaysHashProvider({
+     *       gatewaysProvider: new StaticGatewaysProvider({
+     *         gateways: ['https://permagate.io'],
+     *       }),
      *     }),
      *   }),
-     *   httpClient: axios,
-     * });;
-     *
-     * const response = await wayfind('ar://example', {
-     *   method: 'POST',
-     *   data: {
-     *     name: 'John Doe',
-     *   },
      * })
+     *
+     * // request an arns name
+     * const response = await wayfinder.request('ar://ardrive')
+     *
+     * // 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,
+     * });
+     *
+     * // This will throw an error if verification fails
+     * try {
+     *   const response = await wayfinder.request('ar://1234567890');
+     * } catch (error) {
+     *   console.error('Verification failed', error);
+     * }
      */
     request;
-    // TODO: stats provider
-    // TODO: metricsProvider for otel/prom support
+    /**
+     * The function that verifies the data hash for a given transaction id.
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   verifyData: (data, txId) => {
+     *     // some custom verification logic
+     *     return true;
+     *   },
+     * });
+     */
     verifyData;
+    /**
+     * Whether verification should be strict (blocking) or not.
+     * If true, verification failures will cause requests to fail.
+     * If false, verification will be performed asynchronously and failures will only emit events.
+     */
+    strict;
     /**
      * The event emitter for wayfinder that emits verification events.
      *
      * const wayfinder = new Wayfinder()
      *
-     * wayfinder.emitter.on('verification-passed', (event) => {
+     * wayfinder.emitter.on('verification-succeeded', (event) => {
      *   console.log('Verification passed!', event);
      * })
      *
@@ -522,63 +651,74 @@ export class Wayfinder {
      *
      * const response = await wayfind('ar://example');
      */
-    // TODO: consider changing this to events or event emitter
     emitter;
-    constructor({ httpClient, 
-    // TODO: consider changing router to routingStrategy or strategy
-    router = new RandomGatewayRouter({
-        gatewaysProvider: new SimpleCacheGatewaysProvider({
-            gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-            ttlSeconds: 60 * 60 * 24, // 1 day
+    /**
+     * 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({
+        gatewaysProvider: new NetworkGatewaysProvider({
+            ario: ARIO.mainnet(),
         }),
-    }), logger = Logger.default, 
-    // TODO: support disabling verification or create some PassThroughVerifier like thing
-    verifier = new HashVerifier({
+        ttlSeconds: 60 * 60, // 1 hour
+    }), routingStrategy = new FastestPingRoutingStrategy({
+        timeoutMs: 1000,
+    }), verificationStrategy = new HashVerificationStrategy({
         trustedHashProvider: new TrustedGatewaysHashProvider({
             gatewaysProvider: new StaticGatewaysProvider({
                 gateways: ['https://permagate.io'],
             }),
         }),
-    }), events,
+    }), events = {
+        onVerificationPassed: (event) => {
+            logger.debug('Verification passed!', event);
+        },
+        onVerificationFailed: (event) => {
+            logger.error('Verification failed!', event);
+        },
+        onVerificationProgress: (event) => {
+            logger.debug('Verification progress!', event);
+        },
+    }, strict = false,
     // TODO: stats provider
      }) {
-        this.router = router;
+        this.routingStrategy = routingStrategy;
+        this.gatewaysProvider = gatewaysProvider;
         this.httpClient = httpClient;
         this.emitter = new WayfinderEmitter(events);
-        this.verifyData = verifier.verifyData.bind(verifier);
+        this.verifyData =
+            verificationStrategy.verifyData.bind(verificationStrategy);
+        this.strict = strict;
+        // top level function to easily resolve wayfinder urls using the routing strategy and gateways provider
         this.resolveUrl = async ({ originalUrl, logger }) => {
+            const selectedGateway = await this.routingStrategy.selectGateway({
+                gateways: await this.gatewaysProvider.getGateways(),
+            });
             return resolveWayfinderUrl({
                 originalUrl,
-                targetGateway: async () => await this.router.getTargetGateway(),
+                selectedGateway,
                 logger,
             });
         };
+        // create a wayfinder client with the routing strategy and gateways provider
         this.request = createWayfinderClient({
             httpClient,
-            resolveUrl: this.resolveUrl,
+            selectGateway: async () => {
+                return this.routingStrategy.selectGateway({
+                    gateways: await this.gatewaysProvider.getGateways(),
+                });
+            },
+            resolveUrl: resolveWayfinderUrl,
             verifyData: this.verifyData,
             emitter: this.emitter,
             logger,
+            strict,
         });
-        logger?.debug(`Wayfinder initialized with ${router.name} routing strategy`);
+        logger?.debug(`Wayfinder initialized with ${routingStrategy.constructor.name} routing strategy`);
     }
 }
-// TODO: add a chart for verification strategies and what they do
-// include complexity, performance, and security
-// explain use cases that each strategy is best for
-// e.g.
-/**
- *
- *  type    | complexity | performance | security
- * ---------|------------|-------------|---------
- *  hash    | low        | high        | low
- * ---------|------------|-------------|---------
- *  data root    | medium       | medium      | low | only L1
- * ---------|------------|-------------|---------
- * signature    | medium       | medium      | medium
- * ---------|------------|-------------|---------
- *  composite | high       | low         | high
- * ---------|------------|-------------|---------
- *
- *
- */