Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

5.3 KB
Raw Blame
// Reading content-addressed bytes back off IPFS.
//
// This is the retrieval half of signed agent manifests (specs/AGENT_MANIFEST.md
// § Signed envelope). It is the path an outside verifier walks, so its failure
// modes are the ones that decide whether "anyone can check this" is true or
// merely claimed. Two of them are covered here because both have bitten us:
// a retired gateway left in the fallback chain, and a serial walk that lets one
// hung gateway decide the whole read timed out.

import { describe, it, expect, afterEach, vi } from 'vitest';

import { IPFS_READ_GATEWAYS, fetchFromGateways } from '../api/_lib/ipfs-pin.js';

const CID = 'Qmc2vc5fgpQX9m5d2YJS7XvdAfF1yQLJpRyQtrHyW3kVy1';

const realFetch = globalThis.fetch;
afterEach(() => {
	globalThis.fetch = realFetch;
	vi.restoreAllMocks();
});

/** A fetch stub driven by a per-host script of outcomes. */
function stubFetch(plan) {
	const seen = [];
	globalThis.fetch = vi.fn(async (url) => {
		seen.push(url);
		const entry = Object.entries(plan).find(([host]) => String(url).includes(host));
		const outcome = entry ? entry[1] : { status: 504 };
		if (outcome.delayMs) await new Promise((r) => setTimeout(r, outcome.delayMs));
		if (outcome.throws) throw new Error(outcome.throws);
		return {
			ok: !outcome.status || outcome.status === 200,
			status: outcome.status || 200,
			headers: { get: (h) => (h === 'content-length' ? String(outcome.length ?? (outcome.body || '').length) : null) },
			text: async () => outcome.body ?? '',
		};
	});
	return seen;
}

describe('IPFS_READ_GATEWAYS', () => {
	// Cloudflare retired both of its public gateways in 2024, flk-ipfs.xyz
	// stopped accepting connections, and since Oct 2026 ipfs.io, dweb.link,
	// w3s.link and nftstorage.link answer programmatic reads with 429. A dead
	// host in a fallback chain is worse than a missing one: it consumes the retry
	// budget and reports a refusal as though the document were unretrievable.
	it('lists no retired gateway hosts', () => {
		const retired = [
			'cloudflare-ipfs.com',
			'cf-ipfs.com',
			'flk-ipfs.xyz',
			'//ipfs.io',
			'dweb.link',
			'w3s.link',
			'nftstorage.link',
		];
		for (const host of retired) {
			expect(IPFS_READ_GATEWAYS.some((g) => g.includes(host))).toBe(false);
		}
	});

	it('leads with gateways that are independent of the platform and its pinning vendor', () => {
		expect(IPFS_READ_GATEWAYS[0]).not.toContain('pinata');
		expect(IPFS_READ_GATEWAYS.some((g) => g.includes('three.ws'))).toBe(false);
	});

	// A freshly pinned CID can take hours to propagate across the DHT. Until it
	// does, the pinning provider's own gateway is the only copy in existence, so
	// dropping it would make every just-published manifest unverifiable.
	it('keeps the pinning provider gateway as the guaranteed-complete copy', () => {
		expect(IPFS_READ_GATEWAYS.some((g) => g.includes('pinata'))).toBe(true);
	});
});

describe('fetchFromGateways', () => {
	it('returns the body and the gateway that actually served it', async () => {
		stubFetch({ 'filebase': { body: '{"ok":true}' } });
		const got = await fetchFromGateways(CID);
		expect(JSON.parse(got.text)).toEqual({ ok: true });
		expect(got.gateway).toBe(`https://ipfs.filebase.io/ipfs/${CID}`);
	});

	it('takes the one gateway holding the document when the rest 504', async () => {
		stubFetch({
			'filebase': { status: 504 },
			'4everland': { status: 504 },
			'pinata': { body: '{"pinned":true}' },
		});
		const got = await fetchFromGateways(CID);
		expect(got.gateway).toContain('pinata');
		expect(JSON.parse(got.text)).toEqual({ pinned: true });
	});

	// The regression this guards: walking the list serially made the slowest
	// gateway the floor on every read, so a document one gateway could serve
	// immediately sat behind the timeouts of the ones that could not.
	it('queries every gateway concurrently rather than waiting out the slow ones', async () => {
		const seen = stubFetch({
			'filebase': { delayMs: 60, status: 504 },
			'4everland': { delayMs: 60, status: 504 },
			'pinata': { body: '{"fast":true}' },
		});
		const started = Date.now();
		const got = await fetchFromGateways(CID);
		const elapsed = Date.now() - started;

		expect(got.gateway).toContain('pinata');
		expect(seen).toHaveLength(IPFS_READ_GATEWAYS.length);
		// Serial would have paid both 60ms delays before reaching the winner.
		expect(elapsed).toBeLessThan(120);
	});

	it('reports every gateway it tried when none of them serve the CID', async () => {
		stubFetch({
			'filebase': { status: 504 },
			'4everland': { throws: 'ENOTFOUND' },
			'pinata': { status: 403 },
		});
		await expect(fetchFromGateways(CID)).rejects.toMatchObject({ code: 'gateway_unreachable' });
		await expect(fetchFromGateways(CID)).rejects.toThrow(/504.*ENOTFOUND|ENOTFOUND.*504/s);
	});

	it('refuses a body larger than the budget the caller set', async () => {
		stubFetch({ 'filebase': { body: 'x'.repeat(500), length: 500 } });
		await expect(fetchFromGateways(CID, { maxBytes: 100 })).rejects.toMatchObject({
			code: 'gateway_unreachable',
		});
	});

	it('honors an explicit gateway list', async () => {
		const seen = stubFetch({ 'example.test': { body: '{}' } });
		const got = await fetchFromGateways(CID, { gateways: ['https://example.test/ipfs/'] });
		expect(seen).toEqual([`https://example.test/ipfs/${CID}`]);
		expect(got.gateway).toContain('example.test');
	});
});