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

package/lib/esm/common/wayfinder/routing/strategies/ping.js

@@ -0,0 +1,68 @@
+export class FastestPingRoutingStrategy {
+    timeoutMs;
+    probePath;
+    constructor({ timeoutMs = 500, probePath = '/ar-io/info', // TODO: limit to allowed /ar-io and arweave node endpoints
+     } = {}) {
+        this.timeoutMs = timeoutMs;
+        this.probePath = probePath;
+    }
+    async selectGateway({ gateways }) {
+        if (gateways.length === 0) {
+            throw new Error('No gateways provided');
+        }
+        try {
+            const results = await Promise.allSettled(gateways.map(async (gateway) => {
+                try {
+                    const startTime = Date.now();
+                    const response = await fetch(`${gateway.toString().replace(/\/$/, '')}${this.probePath}`, {
+                        method: 'HEAD',
+                        signal: AbortSignal.timeout(this.timeoutMs),
+                    });
+                    const endTime = Date.now();
+                    const durationMs = endTime - startTime;
+                    return {
+                        gateway,
+                        status: response.status,
+                        durationMs,
+                        error: null,
+                    };
+                }
+                catch (error) {
+                    // Handle network errors
+                    return {
+                        gateway,
+                        status: 'rejected',
+                        durationMs: Infinity,
+                        error,
+                    };
+                }
+            }));
+            // Process results
+            const processedResults = results.map((result, index) => {
+                if (result.status === 'fulfilled') {
+                    return result.value;
+                }
+                else {
+                    return {
+                        gateway: gateways[index],
+                        status: 'rejected',
+                        durationMs: Infinity,
+                        error: result.reason,
+                    };
+                }
+            });
+            // Filter healthy gateways and sort by latency
+            const healthyGateways = processedResults
+                .filter((result) => result.status === 200)
+                .sort((a, b) => a.durationMs - b.durationMs);
+            if (healthyGateways.length > 0) {
+                return healthyGateways[0].gateway;
+            }
+            throw new Error('No healthy gateways found');
+        }
+        catch (error) {
+            throw new Error('Failed to ping gateways: ' +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/ping.test.js

@@ -0,0 +1,151 @@
+/**
+ * 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 assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { FastestPingRoutingStrategy } from './ping.js';
+describe('FastestPingRoutingStrategy', () => {
+    // Original fetch function
+    const originalFetch = global.fetch;
+    // Mock response options for each gateway
+    const mockResponses = new Map();
+    beforeEach(() => {
+        // reset mock responses
+        mockResponses.clear();
+        // mock fetch to simulate network latency and response status
+        global.fetch = async (url) => {
+            const urlString = url.toString();
+            // find the matching gateway
+            let matchingGateway = '';
+            for (const gateway of mockResponses.keys()) {
+                if (urlString.startsWith(gateway)) {
+                    matchingGateway = gateway;
+                    break;
+                }
+            }
+            if (!matchingGateway) {
+                return Promise.reject(new Error(`No mock response for URL: ${urlString}`));
+            }
+            const { status, delayMs } = mockResponses.get(matchingGateway);
+            // simulate network delay
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            return new Response(null, { status });
+        };
+        // mock AbortSignal.timeout
+        if (!AbortSignal.timeout) {
+            AbortSignal.timeout = (ms) => {
+                const controller = new AbortController();
+                setTimeout(() => controller.abort(), ms);
+                return controller.signal;
+            };
+        }
+    });
+    // restore original fetch after tests
+    afterEach(() => {
+        global.fetch = originalFetch;
+    });
+    it('selects the gateway with the lowest latency', async () => {
+        const gateways = [
+            new URL('https://slow.com'),
+            new URL('https://fast.com'),
+            new URL('https://medium.com'),
+        ];
+        // configure mock responses
+        mockResponses.set('https://slow.com', { status: 200, delayMs: 300 });
+        mockResponses.set('https://fast.com', { status: 200, delayMs: 50 });
+        mockResponses.set('https://medium.com', { status: 200, delayMs: 150 });
+        const strategy = new FastestPingRoutingStrategy({ timeoutMs: 500 });
+        // select the gateway with the lowest latency
+        const selectedGateway = await strategy.selectGateway({
+            gateways,
+        });
+        assert.equal(selectedGateway.toString(), 'https://fast.com/', 'Should select the gateway with the lowest latency');
+    });
+    it('ignores gateways that return non-200 status codes', async () => {
+        const gateways = [
+            new URL('https://error.com'),
+            new URL('https://success.com'),
+            new URL('https://another-error.com'),
+        ];
+        // configure mock responses
+        mockResponses.set('https://error.com', { status: 404, delayMs: 50 });
+        mockResponses.set('https://success.com', { status: 200, delayMs: 100 });
+        mockResponses.set('https://another-error.com', {
+            status: 500,
+            delayMs: 75,
+        });
+        const strategy = new FastestPingRoutingStrategy({ timeoutMs: 500 });
+        // select the gateway with the lowest latency
+        const selectedGateway = await strategy.selectGateway({
+            gateways,
+        });
+        assert.equal(selectedGateway.toString(), 'https://success.com/', 'Should select the gateway that returns a 200 status code');
+    });
+    it('throws an error when all gateways fail', async () => {
+        const gateways = [
+            new URL('https://error1.com'),
+            new URL('https://error2.com'),
+        ];
+        // configure mock responses
+        mockResponses.set('https://error1.com', { status: 404, delayMs: 50 });
+        mockResponses.set('https://error2.com', { status: 500, delayMs: 75 });
+        const strategy = new FastestPingRoutingStrategy({ timeoutMs: 500 });
+        // select the gateway with the lowest latency
+        await assert.rejects(async () => await strategy.selectGateway({ gateways }), /No healthy gateways found/, 'Should throw an error when all gateways fail');
+    });
+    it('handles network errors gracefully', async () => {
+        const gateways = [
+            new URL('https://network-error.com'),
+            new URL('https://success.com'),
+        ];
+        // configure mock responses
+        mockResponses.set('https://success.com', { status: 200, delayMs: 100 });
+        // override fetch for the network error case
+        const originalFetchMock = global.fetch;
+        global.fetch = async (url) => {
+            if (url.toString().includes('network-error')) {
+                throw new Error('Network error');
+            }
+            return originalFetchMock(url);
+        };
+        const strategy = new FastestPingRoutingStrategy({ timeoutMs: 500 });
+        // select the gateway with the lowest latency
+        const selectedGateway = await strategy.selectGateway({
+            gateways,
+        });
+        assert.equal(selectedGateway.toString(), 'https://success.com/', 'Should handle network errors and select the working gateway');
+    });
+    it('respects the timeout parameter', async () => {
+        const gateways = [
+            new URL('https://timeout.com'),
+            new URL('https://fast.com'),
+        ];
+        // configure mock responses
+        mockResponses.set('https://timeout.com', { status: 200, delayMs: 300 });
+        mockResponses.set('https://fast.com', { status: 200, delayMs: 50 });
+        // set a short timeout
+        const strategy = new FastestPingRoutingStrategy({ timeoutMs: 100 });
+        const selectedGateway = await strategy.selectGateway({
+            gateways,
+        });
+        assert.equal(selectedGateway.toString(), 'https://fast.com/', 'Should respect the timeout and select only gateways that respond within the timeout');
+    });
+    it('throws an error when no gateways are provided', async () => {
+        const gateways = [];
+        const strategy = new FastestPingRoutingStrategy();
+        // select the gateway with the lowest latency
+        await assert.rejects(async () => await strategy.selectGateway({ gateways }), /No gateways provided/, 'Should throw an error when no gateways are provided');
+    });
+});

package/lib/esm/common/wayfinder/routing/strategies/random.js

@@ -0,0 +1,9 @@
+import { randomInt } from '../../../../utils/random.js';
+export class RandomRoutingStrategy {
+    async selectGateway({ gateways }) {
+        if (gateways.length === 0) {
+            throw new Error('No gateways available');
+        }
+        return gateways[randomInt(0, gateways.length)];
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/random.test.js

@@ -0,0 +1,63 @@
+/**
+ * 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 assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { RandomRoutingStrategy } from './random.js';
+describe('RandomRoutingStrategy', () => {
+    it('selects a gateway from the provided list', async () => {
+        // Arrange
+        const gateways = [
+            new URL('https://example1.com'),
+            new URL('https://example2.com'),
+            new URL('https://example3.com'),
+        ];
+        const strategy = new RandomRoutingStrategy();
+        const selectedGateway = await strategy.selectGateway({ gateways });
+        assert.ok(gateways.includes(selectedGateway), 'The selected gateway should be one of the gateways provided');
+    });
+    it('throws error when no gateways are provided', async () => {
+        const gateways = [];
+        const strategy = new RandomRoutingStrategy();
+        await assert.rejects(async () => await strategy.selectGateway({ gateways }), /No gateways available/, 'Should throw an error when no gateways are provided');
+    });
+    it('should distribute gateway selection somewhat randomly', async () => {
+        const gateways = [
+            new URL('https://example1.com'),
+            new URL('https://example2.com'),
+            new URL('https://example3.com'),
+            new URL('https://example4.com'),
+            new URL('https://example5.com'),
+        ];
+        const strategy = new RandomRoutingStrategy();
+        const selections = new Map();
+        // select gateways multiple times
+        const iterations = 100;
+        for (let i = 0; i < iterations; i++) {
+            const gateway = await strategy.selectGateway({ gateways });
+            const key = gateway.toString();
+            selections.set(key, (selections.get(key) || 0) + 1);
+        }
+        // each gateway should be selected at least once
+        for (const gateway of gateways) {
+            const key = gateway.toString();
+            assert.ok(selections.has(key), `Gateway ${key} should be selected at least once`);
+        }
+        // no gateway should be selected more than 50% of the time
+        for (const [key, count] of selections.entries()) {
+            assert.ok(count < iterations * 0.5, `Gateway ${key} was selected ${count} times, which is more than 50% of iterations`);
+        }
+    });
+});

package/lib/esm/common/wayfinder/routing/strategies/round-robin.js

@@ -0,0 +1,38 @@
+/**
+ * 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 { Logger } from '../../../../common/logger.js';
+export class RoundRobinRoutingStrategy {
+    gateways;
+    currentIndex;
+    logger;
+    constructor({ gateways, logger = Logger.default, }) {
+        this.gateways = gateways;
+        this.currentIndex = 0;
+        this.logger = logger;
+    }
+    // provided gateways are ignored
+    async selectGateway({ gateways = [], } = {}) {
+        if (gateways.length > 0) {
+            this.logger.warn('RoundRobinRoutingStrategy does not accept provided gateways. Ignoring provided gateways...', {
+                providedGateways: gateways.length,
+                internalGateways: this.gateways,
+            });
+        }
+        const gateway = this.gateways[this.currentIndex];
+        this.currentIndex = (this.currentIndex + 1) % this.gateways.length;
+        return gateway;
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/round-robin.test.js

@@ -0,0 +1,73 @@
+/**
+ * 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 assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { Logger } from '../../../../common/logger.js';
+import { RoundRobinRoutingStrategy } from './round-robin.js';
+Logger.default.setLogLevel('none');
+describe('RoundRobinRoutingStrategy', () => {
+    it('selects gateways in order and cycles back to the beginning', async () => {
+        const gateways = [
+            new URL('https://example1.com'),
+            new URL('https://example2.com'),
+            new URL('https://example3.com'),
+        ];
+        const strategy = new RoundRobinRoutingStrategy({ gateways });
+        const selection1 = await strategy.selectGateway();
+        assert.equal(selection1.toString(), gateways[0].toString(), 'Should select the first gateway first');
+        const selection2 = await strategy.selectGateway();
+        assert.equal(selection2.toString(), gateways[1].toString(), 'Should select the second gateway second');
+        const selection3 = await strategy.selectGateway();
+        assert.equal(selection3.toString(), gateways[2].toString(), 'Should select the third gateway third');
+        // should cycle back to the first gateway
+        const selection4 = await strategy.selectGateway();
+        assert.equal(selection4.toString(), gateways[0].toString(), 'Should cycle back to the first gateway');
+    });
+    it('uses the internal list even when a different list is provided', async () => {
+        const initialGateways = [
+            new URL('https://example1.com'),
+            new URL('https://example2.com'),
+        ];
+        const newGateways = [
+            new URL('https://example3.com'),
+            new URL('https://example4.com'),
+        ];
+        const strategy = new RoundRobinRoutingStrategy({
+            gateways: initialGateways,
+        });
+        const selection1 = await strategy.selectGateway({
+            gateways: newGateways,
+        });
+        assert.equal(selection1.toString(), initialGateways[0].toString(), 'Should use the internal list even when a different list is provided');
+        const selection2 = await strategy.selectGateway({
+            // @ts-ignore
+            gateways: newGateways,
+        });
+        assert.equal(selection2.toString(), initialGateways[1].toString(), 'Should use the internal list even when a different list is provided');
+    });
+    it('handles a single gateway by returning it repeatedly', async () => {
+        const gateways = [new URL('https://example1.com')];
+        const strategy = new RoundRobinRoutingStrategy({ gateways });
+        const selection1 = await strategy.selectGateway({
+            gateways: [new URL('https://example2.com')],
+        });
+        assert.equal(selection1.toString(), gateways[0].toString(), 'Should return the single gateway');
+        const selection2 = await strategy.selectGateway({
+            gateways: [new URL('https://example2.com')],
+        });
+        assert.equal(selection2.toString(), gateways[0].toString(), 'Should return the single gateway again');
+    });
+});

package/lib/esm/common/wayfinder/routing/strategies/static.js

@@ -0,0 +1,25 @@
+import { Logger } from '../../../logger.js';
+export class StaticRoutingStrategy {
+    name = 'static';
+    gateway;
+    logger;
+    constructor({ gateway, logger = Logger.default, }) {
+        try {
+            this.gateway = new URL(gateway);
+        }
+        catch (error) {
+            throw new Error(`Invalid URL provided for static gateway: ${gateway}`);
+        }
+        this.logger = logger;
+    }
+    // provided gateways are ignored
+    async selectGateway({ gateways = [], } = {}) {
+        if (gateways.length > 0) {
+            this.logger.warn('StaticRoutingStrategy does not accept provided gateways. Ignoring provided gateways...', {
+                providedGateways: gateways.length,
+                internalGateway: this.gateway,
+            });
+        }
+        return this.gateway;
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/static.test.js

@@ -0,0 +1,35 @@
+/**
+ * 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 assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { StaticRoutingStrategy } from './static.js';
+describe('StaticRoutingStrategy', () => {
+    it('returns the configured gateway regardless of the gateways parameter', async () => {
+        const staticGateway = 'https://static-example.com/';
+        const strategy = new StaticRoutingStrategy({
+            gateway: staticGateway,
+        });
+        const result1 = await strategy.selectGateway();
+        const result2 = await strategy.selectGateway();
+        const result3 = await strategy.selectGateway();
+        assert.equal(result1.toString(), staticGateway, 'Should return the static gateway');
+        assert.equal(result2.toString(), staticGateway, 'Should return the static gateway');
+        assert.equal(result3.toString(), staticGateway, 'Should return the static gateway even when no gateways are provided');
+    });
+    it('throws an error when an invalid URL is provided', () => {
+        assert.throws(() => new StaticRoutingStrategy({ gateway: 'not-a-valid-url' }), /Invalid URL provided for static gateway/, 'Should throw an error when an invalid URL is provided');
+    });
+});

package/lib/esm/common/wayfinder/verification/{data-root-verifier.js → strategies/data-root-verifier.js}

@@ -16,7 +16,7 @@
 import Arweave from 'arweave';
 import { MAX_CHUNK_SIZE, MIN_CHUNK_SIZE, buildLayers, generateLeaves, } from 'arweave/node/lib/merkle.js';
 import { Readable } from 'node:stream';
-import { toB64Url } from '../../../utils/base64.js';
+import { toB64Url } from '../../../../utils/base64.js';
 export async function convertBufferToDataRoot({ buffer, }) {
     const chunks = [];
     let cursor = 0;
@@ -83,7 +83,7 @@ export const convertReadableToDataRoot = async ({ iterable, }) => {
     const root = await buildLayers(leaves);
     return toB64Url(Buffer.from(root.id));
 };
-export class DataRootVerifier {
+export class DataRootVerificationStrategy {
     trustedDataRootProvider;
     constructor({ trustedDataRootProvider, }) {
         this.trustedDataRootProvider = trustedDataRootProvider;

package/lib/esm/common/wayfinder/verification/{hash-verifier.js → strategies/hash-verifier.js}

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { Readable } from 'node:stream';
-import { hashBufferToB64Url, hashReadableStreamToB64Url, hashReadableToB64Url, } from '../../../utils/hash.js';
-export class HashVerifier {
+import { hashBufferToB64Url, hashReadableStreamToB64Url, hashReadableToB64Url, } from '../../../../utils/hash.js';
+export class HashVerificationStrategy {
     trustedHashProvider;
     constructor({ trustedHashProvider, }) {
         this.trustedHashProvider = trustedHashProvider;

package/lib/esm/common/wayfinder/{gateways/trusted-gateways.js → verification/trusted.js}

@@ -47,7 +47,7 @@ export class TrustedGatewaysHashProvider {
             }
         }
         if (hashSet.size === 0) {
-            throw new Error(`No trusted gateways found for txId ${txId}`);
+            throw new Error(`No trusted gateways returned a hash for txId ${txId}`);
         }
         if (hashSet.size > 1) {
             throw new Error(`Failed to get consistent hash from all trusted gateways. ${JSON.stringify(hashResults)}`);