@ar.io/sdk 3.10.0-alpha.5 → 3.10.0-alpha.6

package/lib/cjs/common/wayfinder/wayfinder.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Wayfinder = exports.createWayfinderClient = exports.resolveWayfinderUrl = exports.randomInt = exports.txIdRegex = exports.arnsRegex = void 0;
+/**
+ * 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.
+ */
+const crypto_1 = require("crypto");
+const io_js_1 = require("../io.js");
+const gateways_js_1 = require("./gateways.js");
+const random_js_1 = require("./routers/random.js");
+// known regexes for wayfinder urls
+exports.arnsRegex = /^[a-z0-9_-]{1,51}$/;
+exports.txIdRegex = /^[a-z0-9]{43}$/;
+/**
+ * Cryptographically secure helper for randomness, does not support seeding
+ * @param min - the minimum value
+ * @param max - the maximum value
+ * @returns a random integer between min and max
+ */
+const randomInt = (min, max) => {
+    const [rand] = crypto_1.webcrypto.getRandomValues(new Uint32Array(1));
+    return min + (rand % (max - min));
+};
+exports.randomInt = randomInt;
+/**
+ * Core function to resolve a wayfinder url against a target gateway
+ * @param originalUrl - the wayfinder url to resolve
+ * @param targetGateway - the target gateway to resolve the url against
+ * @returns the resolved url that can be used to make a request
+ */
+const resolveWayfinderUrl = ({ originalUrl, targetGateway, }) => {
+    if (originalUrl.toString().startsWith('ar://')) {
+        const [, path] = originalUrl.toString().split('ar://');
+        // e.g. ar:///info should route to the info endpoint of the target gateway
+        if (path.startsWith('/')) {
+            return new URL(path.slice(1), targetGateway);
+        }
+        // TODO: this breaks 43 character named arns names - we should check a a local name cache list before resolving raw transaction ids
+        if (exports.txIdRegex.test(path)) {
+            const [txId, ...rest] = path.split('/');
+            return new URL(`${txId}${rest.join('/')}`, targetGateway);
+        }
+        if (exports.arnsRegex.test(path)) {
+            // TODO: tests to ensure arns names support query params and paths
+            const [name, ...rest] = path.split('/');
+            const targetGatewayUrl = new URL(targetGateway);
+            const arnsUrl = `${targetGatewayUrl.protocol}//${name}.${targetGatewayUrl.hostname}${targetGatewayUrl.port ? `:${targetGatewayUrl.port}` : ''}`;
+            return new URL(rest.join('/'), arnsUrl);
+        }
+        // TODO: support .eth addresses
+        // TODO: "gasless" routing via DNS TXT records (e.g. ar://gatewaypie.com -> TXT record lookup for TX ID and redirect to that gateway)
+    }
+    // return the original url if it's not a wayfinder url (allows you to use the wayfinder client with non-wayfinder urls)
+    return new URL(originalUrl);
+};
+exports.resolveWayfinderUrl = resolveWayfinderUrl;
+/**
+ * Creates a wrapped http client 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.
+ *
+ * Any URLs provided that are not wayfinder urls will be returned as is.
+ *
+ * @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
+ */
+const createWayfinderClient = ({ httpClient, resolveUrl, }) => {
+    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;
+        // route the request to the target gateway
+        const redirectUrl = await resolveUrl({
+            originalUrl,
+        });
+        // make the request to the target gateway using the redirect url and http client
+        const response = await fn(redirectUrl.toString(), ...rest);
+        // TODO: if verifyDataHash is provided, verify the data hash before returning
+        return response;
+    };
+    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 methods 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
+        },
+    });
+};
+exports.createWayfinderClient = createWayfinderClient;
+/**
+ * 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
+ */
+class Wayfinder {
+    /**
+     * The router to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     * });
+     */
+    router;
+    /**
+     * The http client to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     */
+    httpClient;
+    /**
+     * The function that resolves the redirect url for ar:// requests to a target gateway
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     *
+     * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
+     */
+    resolveUrl;
+    /**
+     * A wrapped http client that supports ar:// protocol
+     *
+     * @example
+     * const { request: wayfind } = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });;
+     *
+     * TODO: consider a top level function that supports wayfinder routing under the hood
+     * const response = await wayfind('ar://', {
+     *   method: 'POST',
+     *   data: {
+     *     name: 'John Doe',
+     *   },
+     * })
+     */
+    request;
+    // TODO: stats provider
+    // TODO: metricsProvider for otel/prom support
+    // TODO: private verificationSettings: {
+    //   trustedGateways: URL[];
+    //   method: 'local' | 'remote';
+    // };
+    constructor({ 
+    // TODO: consider changing router to routingStrategy or strategy
+    router = new random_js_1.RandomGatewayRouter({
+        // optionally use a cache gateways provider to reduce the number of requests to the contract
+        gatewaysProvider: new gateways_js_1.ARIOGatewaysProvider({ ario: io_js_1.ARIO.mainnet() }),
+    }), httpClient,
+    // TODO: add verifier interface that provides a verifyDataHash function
+    // TODO: stats provider
+     }) {
+        this.router = router;
+        this.httpClient = httpClient;
+        this.resolveUrl = async ({ originalUrl }) => (0, exports.resolveWayfinderUrl)({
+            originalUrl,
+            targetGateway: await this.router.getTargetGateway(),
+        });
+        this.request = (0, exports.createWayfinderClient)({
+            httpClient,
+            resolveUrl: this.resolveUrl,
+            // TODO: provide the verifyDataHash function from the verifier to the wayfinder client along with verificationSettings
+        });
+    }
+}
+exports.Wayfinder = Wayfinder;

package/lib/cjs/common/wayfinder/wayfinder.test.js

@@ -0,0 +1,254 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+const got_1 = __importDefault(require("got"));
+const node_assert_1 = __importDefault(require("node:assert"));
+const consumers_1 = require("node:stream/consumers");
+const node_test_1 = require("node:test");
+const random_js_1 = require("./routers/random.js");
+const wayfinder_js_1 = require("./wayfinder.js");
+const stubbedGateway = {
+    status: 'joined',
+    gatewayAddress: 'arweave',
+    operatorStake: 1000,
+    totalDelegatedStake: 1000,
+    startTimestamp: 1000,
+    settings: {
+        protocol: 'https',
+        fqdn: 'arweave.net',
+        port: 443,
+    },
+};
+const stubbedGatewaysProvider = {
+    getGateways: async () => [stubbedGateway],
+};
+(0, node_test_1.describe)('Wayfinder', () => {
+    (0, node_test_1.describe)('http wrapper', () => {
+        (0, node_test_1.describe)('fetch', () => {
+            let wayfinder;
+            (0, node_test_1.before)(() => {
+                wayfinder = new wayfinder_js_1.Wayfinder({
+                    httpClient: fetch,
+                    router: new random_js_1.RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+            });
+            (0, node_test_1.it)('should fetch the data using the selected gateway', async () => {
+                const nativeFetch = await fetch('https://ao.arweave.net');
+                const response = await wayfinder.request('ar://ao');
+                node_assert_1.default.strictEqual(response.status, 200);
+                node_assert_1.default.strictEqual(response.status, nativeFetch.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Array.from(response.headers.entries()).filter(([key]) => key.startsWith('x-arns-'));
+                const nativeFetchHeaders = Array.from(nativeFetch.headers.entries()).filter(([key]) => key.startsWith('x-arns-'));
+                node_assert_1.default.deepStrictEqual(arnsHeaders, nativeFetchHeaders);
+                node_assert_1.default.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+            (0, node_test_1.it)('should route a non-ar:// url as a normal fetch', async () => {
+                const [nativeFetch, response] = await Promise.all([
+                    fetch('https://arweave.net/', {
+                        method: 'HEAD',
+                    }),
+                    wayfinder.request('https://arweave.net/', {
+                        method: 'HEAD',
+                    }),
+                ]);
+                node_assert_1.default.strictEqual(response.status, 200);
+                node_assert_1.default.strictEqual(response.status, nativeFetch.status);
+                // TODO: ensure the headers are the same excluding unique headers
+                node_assert_1.default.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+            for (const api of ['/info', '/metrics', '/block/current']) {
+                (0, node_test_1.it)(`supports native arweave node apis ${api}`, async () => {
+                    const [nativeFetch, response] = await Promise.all([
+                        fetch(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    node_assert_1.default.strictEqual(response.status, 200);
+                    node_assert_1.default.strictEqual(response.status, nativeFetch.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    node_assert_1.default.deepStrictEqual(await response.text(), await nativeFetch.text());
+                });
+            }
+            for (const api of ['/ar-io/info', '/ar-io/__gateway_metrics']) {
+                (0, node_test_1.it)(`supports native ario node gateway apis ${api}`, async () => {
+                    const [nativeFetch, response] = await Promise.all([
+                        fetch(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    node_assert_1.default.strictEqual(response.status, 200);
+                    node_assert_1.default.strictEqual(response.status, nativeFetch.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    node_assert_1.default.deepStrictEqual(await response.text(), await nativeFetch.text());
+                });
+            }
+            (0, node_test_1.it)('supports a post request to graphql', async () => {
+                const response = await wayfinder.request('ar:///graphql', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        query: `
+                query {
+                  transactions(
+                    ids: ["xf958qhCNGfDme1FtoiD6DtMfDENDbtxZpjOM_1tsMM"]
+                  ) {
+                    edges {
+                      cursor
+                      node {
+                        id
+                        tags {
+                          name
+                          value
+                        }
+                        block {
+                          height
+                          timestamp
+                        }
+                      }
+                    }
+                    pageInfo {
+                      hasNextPage
+                    }
+                  }
+                }
+            `,
+                    }),
+                });
+                node_assert_1.default.strictEqual(response.status, 200);
+            });
+            (0, node_test_1.it)('returns the error from the target gateway if the route is not found', async () => {
+                const [nativeFetch, response] = await Promise.all([
+                    fetch('https://arweave.net/not-found'),
+                    wayfinder.request('https://arweave.net/not-found'),
+                ]);
+                node_assert_1.default.strictEqual(response.status, nativeFetch.status);
+                node_assert_1.default.strictEqual(response.statusText, nativeFetch.statusText);
+                node_assert_1.default.deepStrictEqual(await response.text(), await nativeFetch.text());
+            });
+        });
+        (0, node_test_1.describe)('axios', () => {
+            let wayfinder;
+            (0, node_test_1.before)(() => {
+                wayfinder = new wayfinder_js_1.Wayfinder({
+                    httpClient: axios_1.default,
+                    router: new random_js_1.RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+            });
+            (0, node_test_1.it)('should fetch the data using axios default function against the target gateway', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    (0, axios_1.default)('https://ao.arweave.net'),
+                    wayfinder.request('ar://ao'),
+                ]);
+                node_assert_1.default.strictEqual(response.status, 200);
+                node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Object.entries(response.headers)
+                    .sort()
+                    .filter(([key]) => key.startsWith('x-arns-'));
+                const nativeAxiosHeaders = Object.entries(nativeAxios.headers).filter(([key]) => key.startsWith('x-arns-'));
+                node_assert_1.default.deepStrictEqual(arnsHeaders.sort(), nativeAxiosHeaders.sort());
+                node_assert_1.default.deepStrictEqual(response.data, nativeAxios.data);
+            });
+            (0, node_test_1.it)('should fetch the data using the axios.get method against the target gateway', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    axios_1.default.get('https://ao.arweave.net'),
+                    wayfinder.request.get('ar://ao'),
+                ]);
+                node_assert_1.default.strictEqual(response.status, 200);
+                node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                // assert the arns headers are the same
+                const arnsHeaders = Object.entries(response.headers)
+                    .sort()
+                    .filter(([key]) => key.startsWith('x-arns-'));
+                const nativeAxiosHeaders = Object.entries(nativeAxios.headers).filter(([key]) => key.startsWith('x-arns-'));
+                node_assert_1.default.deepStrictEqual(arnsHeaders.sort(), nativeAxiosHeaders.sort());
+                node_assert_1.default.deepStrictEqual(response.data, nativeAxios.data);
+            });
+            (0, node_test_1.it)('should route a non-ar:// url as a normal axios request', async () => {
+                const [nativeAxios, response] = await Promise.all([
+                    (0, axios_1.default)('https://arweave.net/'),
+                    wayfinder.request('https://arweave.net/'),
+                ]);
+                node_assert_1.default.strictEqual(response.status, 200);
+                node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                node_assert_1.default.deepStrictEqual(response.data, nativeAxios.data);
+                // TODO: ensure the headers are the same excluding unique headers
+            });
+            for (const api of ['/info', '/metrics', '/block/current']) {
+                (0, node_test_1.it)(`supports native arweave node apis ${api}`, async () => {
+                    const [nativeAxios, response] = await Promise.all([
+                        (0, axios_1.default)(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    node_assert_1.default.strictEqual(response.status, 200);
+                    node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    node_assert_1.default.deepStrictEqual(response.data, nativeAxios.data);
+                });
+            }
+            for (const api of ['/ar-io/info', '/ar-io/__gateway_metrics']) {
+                (0, node_test_1.it)(`supports native ario node gateway apis ${api}`, async () => {
+                    const [nativeAxios, response] = await Promise.all([
+                        (0, axios_1.default)(`https://arweave.net${api}`),
+                        wayfinder.request(`ar:///${api}`),
+                    ]);
+                    node_assert_1.default.strictEqual(response.status, 200);
+                    node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                    // TODO: ensure the headers are the same excluding unique headers
+                    node_assert_1.default.deepStrictEqual(response.data, nativeAxios.data);
+                });
+            }
+            (0, node_test_1.it)('should return the error from the target gateway if the route is not found', async () => {
+                const axiosInstance = axios_1.default.create({
+                    validateStatus: () => true, // don't throw so we can compare axios result with wrapped axios result
+                });
+                const wayfinder = new wayfinder_js_1.Wayfinder({
+                    httpClient: axiosInstance,
+                    router: new random_js_1.RandomGatewayRouter({
+                        gatewaysProvider: stubbedGatewaysProvider,
+                    }),
+                });
+                const [nativeAxios, response] = await Promise.all([
+                    axiosInstance('https://arweave.net/not-found'),
+                    wayfinder.request('https://arweave.net/not-found'),
+                ]);
+                node_assert_1.default.strictEqual(response.status, nativeAxios.status);
+                node_assert_1.default.strictEqual(response.data, nativeAxios.data);
+            });
+        });
+    });
+    (0, node_test_1.describe)('got', () => {
+        let wayfinder;
+        (0, node_test_1.before)(() => {
+            wayfinder = new wayfinder_js_1.Wayfinder({
+                httpClient: got_1.default,
+                router: new random_js_1.RandomGatewayRouter({
+                    gatewaysProvider: stubbedGatewaysProvider,
+                }),
+            });
+        });
+        (0, node_test_1.it)('should fetch the data using the got default function against the target gateway', async () => {
+            const [nativeGot, response] = await Promise.all([
+                (0, got_1.default)('https://ao.arweave.net'),
+                wayfinder.request('ar://ao'),
+            ]);
+            node_assert_1.default.strictEqual(response.statusCode, 200);
+            node_assert_1.default.strictEqual(response.statusCode, nativeGot.statusCode);
+            node_assert_1.default.deepStrictEqual(response.body, nativeGot.body);
+        });
+        (0, node_test_1.it)('should stream the data using got.stream against the selected target gateway', async () => {
+            const nativeBuffer = await (0, consumers_1.buffer)(await got_1.default.stream('https://ao.arweave.net', { decompress: false }));
+            const wayfinderBuffer = await (0, consumers_1.buffer)(await wayfinder.request.stream('ar://ao', { decompress: false }));
+            node_assert_1.default.deepStrictEqual(wayfinderBuffer, nativeBuffer);
+        });
+    });
+    // TODO: streaming support using got.stream and got()
+});

package/lib/cjs/types/index.js

@@ -35,3 +35,4 @@ __exportStar(require("./common.js"), exports);
 __exportStar(require("./faucet.js"), exports);
 __exportStar(require("./io.js"), exports);
 __exportStar(require("./token.js"), exports);
+__exportStar(require("./wayfinder.js"), exports);

package/lib/cjs/types/wayfinder.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/version.js

@@ -17,4 +17,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-exports.version = '3.10.0-alpha.5';
+exports.version = '3.10.0-alpha.6';

package/lib/esm/common/index.js

@@ -22,3 +22,5 @@ export * from './faucet.js';
 // ao
 export * from './io.js';
 export * from './contracts/ao-process.js';
+// wayfinder
+export * from './wayfinder/index.js';

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

@@ -0,0 +1,69 @@
+export class ARIOGatewaysProvider {
+    ario;
+    constructor({ ario }) {
+        this.ario = ario;
+    }
+    async getGateways() {
+        let cursor;
+        let attempts = 0;
+        const gateways = [];
+        do {
+            try {
+                const { items: newGateways, nextCursor } = await this.ario.getGateways({
+                    limit: 1000,
+                    cursor,
+                });
+                gateways.push(...newGateways);
+                cursor = nextCursor;
+                attempts = 0; // reset attempts if we get a new cursor
+            }
+            catch (error) {
+                console.error('Error fetching gateways', {
+                    cursor,
+                    attempts,
+                    error,
+                });
+                attempts++;
+            }
+        } while (cursor !== undefined && attempts < 3);
+        // filter out any gateways that are not joined
+        return gateways.filter((g) => g.status === 'joined');
+    }
+}
+export class StaticGatewaysProvider {
+    gateways;
+    constructor({ gateways }) {
+        this.gateways = gateways;
+    }
+    async getGateways() {
+        return this.gateways;
+    }
+}
+export class SimpleCacheGatewaysProvider {
+    gatewaysProvider;
+    ttlSeconds;
+    lastUpdated;
+    gatewaysCache;
+    constructor({ gatewaysProvider, ttlSeconds = 5 * 60, // 5 minutes
+     }) {
+        this.gatewaysCache = [];
+        this.gatewaysProvider = gatewaysProvider;
+        this.ttlSeconds = ttlSeconds;
+    }
+    async getGateways() {
+        const now = Date.now();
+        if (this.gatewaysCache.length === 0 ||
+            now - this.lastUpdated > this.ttlSeconds * 1000) {
+            try {
+                // preserve the cache if the fetch fails
+                const allGateways = await this.gatewaysProvider.getGateways();
+                this.gatewaysCache = allGateways.filter((g) => g.status === 'joined');
+                this.lastUpdated = now;
+            }
+            catch (error) {
+                console.error('Error fetching gateways', error);
+            }
+        }
+        return this.gatewaysCache;
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export * from './wayfinder.js';
+// routers
+export * from './routers/random.js';
+export * from './routers/priority.js';
+export * from './routers/fixed.js';

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

@@ -0,0 +1,10 @@
+export class FixedGatewayRouter {
+    name = 'fixed';
+    gateway;
+    constructor({ gateway }) {
+        this.gateway = gateway;
+    }
+    async getTargetGateway() {
+        return this.gateway;
+    }
+}

package/lib/esm/common/wayfinder/routers/fixed.test.js

@@ -0,0 +1,12 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { FixedGatewayRouter } from './fixed.js';
+describe('FixedRouter', () => {
+    it('should return the provided gateway', async () => {
+        const router = new FixedGatewayRouter({
+            gateway: new URL('http://test-gateway.net'),
+        });
+        const result = await router.getTargetGateway();
+        assert.deepStrictEqual(result, new URL('http://test-gateway.net'));
+    });
+});

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

@@ -0,0 +1,34 @@
+import { randomInt } from '../wayfinder.js';
+// TODO: one of N where N are in the last time window have met certain performance thresholds
+// TODO: look at bitorrent routing protocols for inspiration
+// TODO: router that looks at local stats/metrics and adjusts based on those
+export class PriorityGatewayRouter {
+    name = 'priority';
+    gatewaysProvider;
+    limit;
+    sortBy;
+    sortOrder;
+    blocklist;
+    constructor({ gatewaysProvider, limit = 1, sortBy = 'operatorStake', sortOrder = 'desc', blocklist = [], }) {
+        this.gatewaysProvider = gatewaysProvider;
+        this.limit = limit;
+        this.sortBy = sortBy;
+        this.sortOrder = sortOrder;
+        this.blocklist = blocklist;
+    }
+    async getTargetGateway() {
+        const allGateways = await this.gatewaysProvider.getGateways();
+        const gateways = allGateways.filter((gateway) => gateway.status === 'joined' &&
+            !this.blocklist.includes(gateway.settings.fqdn));
+        const sortedGateways = gateways
+            .sort(this.sortOrder === 'asc'
+            ? (a, b) => a[this.sortBy] - b[this.sortBy]
+            : (a, b) => b[this.sortBy] - a[this.sortBy])
+            .slice(0, this.limit);
+        const targetGateway = sortedGateways[randomInt(0, sortedGateways.length)];
+        if (targetGateway === undefined) {
+            throw new Error('No target gateway found');
+        }
+        return new URL(`${targetGateway.settings.protocol}://${targetGateway.settings.fqdn}:${targetGateway.settings.port}`);
+    }
+}