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.

10.5 KB
Raw Blame
// Shared multi-provider failover fetch. Isomorphic: imported by browser code
// (src/*) and Vercel functions (api/_lib/*) alike.
//
// The platform rule is that no external data source is a single point of
// failure: every category of fetch (RPC, prices, token metadata, geocoding)
// runs against an ordered list of free providers, and a failure moves on to
// the next provider immediately instead of surfacing an error. Solana RPC
// (api/_lib/solana/connection.js), EVM RPC (api/_lib/evm/rpc.js), token
// market data (api/_lib/market/token-market.js) and IPFS gateways
// (src/ipfs.js) already implement this per-category; this module is the
// generic version for everything else, so new call sites don't grow their own
// bespoke retry loops.
//
// Semantics:
// - Providers are tried in order with a short per-attempt timeout, so the
//   worst case is bounded (~timeoutMs × providers) and the common case — the
//   first healthy provider — costs nothing extra.
// - A provider that errors (network failure, timeout, non-2xx) goes into a
//   per-process cooldown and is skipped on subsequent calls until it expires,
//   so one dead host doesn't tax every future request with its timeout.
// - A provider whose `parse` returns null/undefined is a MISS, not a failure:
//   "this source doesn't know this token" shouldn't cool the source down for
//   callers asking about other tokens. The chain just moves on.
// - If every provider is cooling down, they're all tried anyway (a full chain
//   of dead providers must still probe for recovery rather than fail cold).

const _cooldowns = new Map(); // provider name -> epoch ms until which it is skipped

// Brownout hooks. This module is isomorphic (the browser bundle imports it), and
// provenance/chaos are node:async_hooks, so they are loaded lazily behind an
// isServer() gate exactly as api/_lib/solana/connection.js loads the shared
// cache. In a browser both resolve to no-ops, which is correct: there is no
// request to attribute a source to, and nothing should be able to inject a
// fault from the client side.
let _brownoutPromise;
// Resolved module, once the import lands. Recording has to be SYNCHRONOUS in the
// hot path: the response header is written when the handler ends, and an await
// here would let a record arrive after its own response had already gone out.
// That is not a lost log line, it is a trace that omits the rung that answered.
let _brownoutMod = null;
// The specifier is assembled at runtime instead of written as a literal, and it
// has to stay that way. The CDN lib target builds with
// `rollupOptions.output.inlineDynamicImports` (vite.config.js), which flattens
// EVERY dynamic import into the single bundle. That turns this server-only
// branch into a static edge, and the build dies on
// `"AsyncLocalStorage" is not exported by "__vite-browser-external"` even though
// the guard above means a browser never evaluates it. Rollup resolves a string
// literal here regardless of @vite-ignore, and constant-folds a `const` holding
// one.
//
// A local `['..', 'api', …].join('/')` was the first attempt and it stopped
// working: Rollup 4 folds that expression too, and the deploy build died again
// on the same line. So the path is parked on `globalThis` and read back from a
// member expression, which no bundler can evaluate at build time because it
// cannot know what else may have written there. Node resolves the relative
// specifier against THIS module, which is what the server needs.
globalThis.__threewsBrownoutSpecifier ||= ['..', '..', 'api', '_lib', 'brownout', 'index.js'].join('/');
function brownout() {
	if (_brownoutPromise !== undefined) return _brownoutPromise;
	_brownoutPromise = null;
	if (typeof window === 'undefined') {
		_brownoutPromise = import(/* @vite-ignore */ globalThis.__threewsBrownoutSpecifier)
			.then((m) => {
				_brownoutMod = m;
				return m;
			})
			.catch(() => null);
	}
	return _brownoutPromise;
}
// Warm the import at module load on the server, so by the time a request runs
// the module is in hand and every record is written synchronously.
brownout();

function noteSource(rec) {
	if (_brownoutMod) {
		_brownoutMod.recordSource?.(rec);
		return;
	}
	// Only on the very first call of a cold process, before the import lands.
	const pending = brownout();
	if (pending) void pending.then((m) => m?.recordSource?.(rec));
}
async function faultForProvider(name) {
	if (_brownoutMod) return _brownoutMod.faultFor?.(name) ?? null;
	const mod = await brownout();
	return mod?.faultFor?.(name) ?? null;
}

/**
 * @typedef {object} Provider
 * @property {string} name                       Stable id; keys the cooldown map.
 * @property {string} url                        Request URL.
 * @property {RequestInit} [init]                Extra fetch options (headers, method…).
 * @property {(res: Response) => Promise<any>} [parse]
 *   Extract the value from a 2xx response. Defaults to `res.json()`. Return
 *   null/undefined to signal "no data here, try the next provider" without
 *   penalising this provider. Throw to penalise it.
 */

/**
 * Try each provider in order until one yields a value.
 *
 * @param {Provider[]} providers   Ordered preference list.
 * @param {object} [opts]
 * @param {number} [opts.timeoutMs=4000]    Per-provider attempt timeout.
 * @param {number} [opts.cooldownMs=60000]  Skip window after a provider errors.
 * @param {string} [opts.label]             Prefix for the aggregate error message.
 * @returns {Promise<{value: any, source: string}>}
 * @throws when every provider fails or misses.
 */
export async function fetchFirst(providers, { timeoutMs = 4000, cooldownMs = 60_000, label = 'fetchFirst' } = {}) {
	const now = Date.now();
	const hot = providers.filter((p) => (_cooldowns.get(p.name) || 0) <= now);
	const order = hot.length ? hot : providers;

	let lastErr;
	for (const p of order) {
		const startedAt = Date.now();
		const ctrl = new AbortController();
		const timer = setTimeout(() => ctrl.abort(), timeoutMs);
		// A caller-supplied signal (stale-search abort) composes with the
		// per-attempt timeout rather than being replaced by it.
		const signal = p.init?.signal ? AbortSignal.any([ctrl.signal, p.init.signal]) : ctrl.signal;
		try {
			// A declared fault stands in for the real one, in the same position the
			// real failure would occupy, so the ladder below fails over identically.
			const fault = await faultForProvider(p.name);
			let res;
			if (fault) {
				const mod = _brownoutMod || (await brownout());
				const injected = await mod.applyFault(fault, p.url);
				if (injected) res = injected;
			}
			if (!res) {
				res = await fetch(p.url, {
					headers: { accept: 'application/json' },
					...p.init,
					signal,
				});
			}
			if (!res.ok) throw new Error(`http_${res.status}`);
			const value = await (p.parse ? p.parse(res) : res.json());
			if (value != null) {
				// The rung that answered is `live`; the ones before it are recorded
				// in the catch below, so a trace shows the whole walk, not just the
				// winner. That is the difference between "we have a ladder" and
				// "here is the ladder working".
				noteSource({ name: p.name, outcome: 'ok', ms: Date.now() - startedAt, tier: 'live' });
				return { value, source: p.name };
			}
			// Miss: provider is healthy but has no data for this query.
			noteSource({ name: p.name, outcome: 'skip', ms: Date.now() - startedAt, tier: 'live', detail: 'no_data' });
			lastErr = new Error(`${p.name}: no_data`);
		} catch (err) {
			lastErr = err instanceof Error ? err : new Error(String(err));
			noteSource({
				name: p.name,
				outcome: 'fail',
				ms: Date.now() - startedAt,
				tier: 'live',
				detail: /http_(\d{3})/.exec(lastErr.message)?.[1] || (lastErr.name === 'TimeoutError' ? 'timeout' : 'error'),
			});
			// Caller abandoned the request (stale search) — stop the whole chain
			// and don't penalise the provider for it.
			if (p.init?.signal?.aborted) {
				clearTimeout(timer);
				break;
			}
			_cooldowns.set(p.name, Date.now() + cooldownMs);
		} finally {
			clearTimeout(timer);
		}
	}
	throw new Error(`${label}: all ${order.length} providers failed (${lastErr?.message || 'unknown'})`);
}

/**
 * Like fetchFirst but resolves to `fallback` (default null) instead of
 * throwing — for best-effort call sites where missing data is a designed
 * state (metadata enrichment, place labels) rather than an error.
 *
 * @param {Provider[]} providers
 * @param {object} [opts]  Same options as fetchFirst, plus `fallback`.
 * @returns {Promise<any>} The first provider's parsed value, or `fallback`.
 */
export async function fetchFirstOrNull(providers, opts = {}) {
	const { fallback = null, ...rest } = opts;
	try {
		return (await fetchFirst(providers, rest)).value;
	} catch {
		return fallback;
	}
}

const RETRYABLE_STATUSES = [408, 425, 429, 500, 502, 503, 504];

/**
 * fetch with a bounded retry for a single URL: network errors and retryable
 * statuses (429, 5xx) are retried with exponential backoff; any other response
 * is returned as-is on the first attempt. The last retryable response is
 * returned (not thrown) once attempts are exhausted, so callers keep their
 * normal `res.ok` handling. Use this for an idempotent GET against one host;
 * a POST that must run exactly once (a swap build) stays single-shot.
 *
 * @param {string} url
 * @param {RequestInit} [init]
 * @param {object} [opts]
 * @param {number} [opts.attempts=3]        Total attempts, including the first.
 * @param {number} [opts.backoffMs=400]     Base delay; doubles per retry.
 * @param {number} [opts.timeoutMs]         Per-attempt deadline (composes with init.signal).
 * @param {number[]} [opts.retryOn]         Statuses that trigger a retry.
 * @returns {Promise<Response>}
 */
export async function retryFetch(url, init = {}, { attempts = 3, backoffMs = 400, timeoutMs, retryOn = RETRYABLE_STATUSES } = {}) {
	let lastErr;
	for (let i = 0; i < attempts; i++) {
		if (i > 0) await new Promise((r) => setTimeout(r, backoffMs * 2 ** (i - 1)));
		const signals = [];
		if (init.signal) signals.push(init.signal);
		if (timeoutMs) signals.push(AbortSignal.timeout(timeoutMs));
		const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
		try {
			const res = await fetch(url, signal ? { ...init, signal } : init);
			if (!retryOn.includes(res.status) || i === attempts - 1) return res;
			lastErr = new Error(`http_${res.status}`);
		} catch (err) {
			// The caller gave up (stale request): stop, and never mask that as a retry.
			if (init.signal?.aborted) throw err;
			lastErr = err;
			if (i === attempts - 1) throw err;
		}
	}
	throw lastErr;
}