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.2 KB
Raw Blame
// Tests for the HuggingFace provider's durable re-host of the reconstructed GLB.
//
// The Space serves the finished mesh from an ephemeral gradio /tmp path that is
// purged within minutes, so every later consumer (forge image lane, avatar
// reconstruct poll) can 404 against it. The provider re-hosts the bytes to our
// own object storage the instant the SSE completes and returns that durable URL.
//
// Invariants under test:
//   • With object storage configured, the returned resultGlbUrl is the durable
//     R2 URL, not the raw Space URL, and the mesh was uploaded exactly once.
//   • With storage configured, a 404 on the (already-expired) Space file must NOT
//     leak the ephemeral URL downstream: the provider fails over to the next
//     Space and regenerates, and if none remain it throws a designed error
//     instead of handing back a URL guaranteed to 404 in materializeCreation.
//   • Without storage configured, re-host is skipped entirely (no fetch of the
//     mesh, no upload) and the raw Space URL is returned, unchanged behavior.

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

const putObject = vi.fn(async () => {});
const publicUrl = vi.fn((key) => `https://cdn.example/${key}`);
vi.mock('../../api/_lib/r2.js', () => ({ putObject, publicUrl }));

const ORIGINAL_FETCH = globalThis.fetch;
const S3_KEYS = ['S3_ENDPOINT', 'S3_BUCKET', 'S3_PUBLIC_DOMAIN', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY'];
const ORIGINAL = {};
for (const k of [...S3_KEYS, 'HF_TOKEN', 'HF_RECONSTRUCT_SPACES']) ORIGINAL[k] = process.env[k];

function spaceUrl(slug) {
	return `https://${slug.replace(/\//g, '-').toLowerCase()}.hf.space`;
}

function sseStream(output) {
	const text = `event: complete\ndata: ${JSON.stringify(output)}\n\n`;
	const encoder = new TextEncoder();
	const stream = new ReadableStream({
		start(controller) {
			controller.enqueue(encoder.encode(text));
			controller.close();
		},
	});
	return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } });
}

function jsonResp(body, status = 200) {
	return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
}

// Minimal valid-looking GLB byte blob (header is irrelevant to the re-host copy).
function glbBytes() {
	return new Uint8Array([0x67, 0x6c, 0x54, 0x46, 1, 2, 3, 4]);
}

function setS3() {
	process.env.S3_ENDPOINT = 'https://s3.local';
	process.env.S3_BUCKET = 'bucket';
	process.env.S3_PUBLIC_DOMAIN = 'https://cdn.example';
	process.env.S3_ACCESS_KEY_ID = 'key';
	process.env.S3_SECRET_ACCESS_KEY = 'secret';
}
function clearS3() {
	for (const k of S3_KEYS) delete process.env[k];
}

beforeEach(() => {
	process.env.HF_TOKEN = 'hf_test_token';
	process.env.HF_RECONSTRUCT_SPACES = 'foo/A';
	putObject.mockClear();
	publicUrl.mockClear();
	vi.resetModules();
});

afterEach(() => {
	globalThis.fetch = ORIGINAL_FETCH;
	for (const k of [...S3_KEYS, 'HF_TOKEN', 'HF_RECONSTRUCT_SPACES']) {
		if (ORIGINAL[k] === undefined) delete process.env[k];
		else process.env[k] = ORIGINAL[k];
	}
});

describe('huggingface provider — durable GLB re-host', () => {
	it('re-hosts the freshly-produced mesh to R2 and returns the durable URL', async () => {
		setS3();
		const fetchMock = vi.fn(async (url, opts) => {
			if (url === `${spaceUrl('foo/A')}/call/generation_all`) return jsonResp({ event_id: 'evt-A' });
			if (url === `${spaceUrl('foo/A')}/call/generation_all/evt-A`) {
				return sseStream([{ url: 'https://files.hf/tmp/gradio/abc/model.glb' }]);
			}
			if (url === 'https://files.hf/tmp/gradio/abc/model.glb') {
				// Re-host fetch must forward the HF bearer token for private Spaces.
				expect(opts?.headers?.authorization).toBe('Bearer hf_test_token');
				return new Response(glbBytes(), { status: 200, headers: { 'content-type': 'model/gltf-binary' } });
			}
			throw new Error(`unexpected url ${url}`);
		});
		globalThis.fetch = fetchMock;

		const { createRegenProvider } = await import('../../api/_providers/huggingface.js');
		const out = await createRegenProvider().submit({
			mode: 'reconstruct',
			params: { images: ['data:image/jpeg;base64,AAA'] },
		});

		const decoded = JSON.parse(Buffer.from(out.extJobId, 'base64url').toString('utf8'));
		expect(decoded.resultGlbUrl).toMatch(/^https:\/\/cdn\.example\/hf-recon\/[0-9a-f-]+\.glb$/);
		expect(decoded.resultGlbUrl).not.toContain('files.hf');
		expect(putObject).toHaveBeenCalledTimes(1);
		expect(putObject.mock.calls[0][0]).toMatchObject({ contentType: 'model/gltf-binary' });
	});

	it('regenerates on the next Space when the first Space\'s mesh already 404s, never leaking the ephemeral URL', async () => {
		setS3();
		// foo/A produces a GLB whose temp file is already gone (404 on rehost); bar/B
		// produces a live one. The doomed foo/A URL must never escape — we expect a
		// durable bar/B copy instead.
		process.env.HF_RECONSTRUCT_SPACES = 'foo/A,bar/B';
		const fetchMock = vi.fn(async (url, opts) => {
			if (url === `${spaceUrl('foo/A')}/call/generation_all`) return jsonResp({ event_id: 'evt-A' });
			if (url === `${spaceUrl('foo/A')}/call/generation_all/evt-A`) {
				return sseStream([{ url: 'https://files.hf/tmp/gradio/gone/model.glb' }]);
			}
			if (url === 'https://files.hf/tmp/gradio/gone/model.glb') return new Response('', { status: 404 });
			if (url === `${spaceUrl('bar/B')}/call/generation_all`) return jsonResp({ event_id: 'evt-B' });
			if (url === `${spaceUrl('bar/B')}/call/generation_all/evt-B`) {
				return sseStream([{ url: 'https://files.hf/tmp/gradio/live/model.glb' }]);
			}
			if (url === 'https://files.hf/tmp/gradio/live/model.glb') {
				expect(opts?.headers?.authorization).toBe('Bearer hf_test_token');
				return new Response(glbBytes(), { status: 200, headers: { 'content-type': 'model/gltf-binary' } });
			}
			throw new Error(`unexpected url ${url}`);
		});
		globalThis.fetch = fetchMock;

		const { createRegenProvider } = await import('../../api/_providers/huggingface.js');
		const out = await createRegenProvider().submit({
			mode: 'reconstruct',
			params: { images: ['data:image/jpeg;base64,AAA'] },
		});

		const decoded = JSON.parse(Buffer.from(out.extJobId, 'base64url').toString('utf8'));
		expect(decoded.resultGlbUrl).toMatch(/^https:\/\/cdn\.example\/hf-recon\/[0-9a-f-]+\.glb$/);
		expect(decoded.resultGlbUrl).not.toContain('files.hf');
		expect(decoded.space).toBe('bar/B');
		expect(decoded.fellBackFrom).toEqual(['foo/A']);
		expect(putObject).toHaveBeenCalledTimes(1);
	});

	it('throws a designed error rather than returning the ephemeral URL when every Space\'s mesh 404s', async () => {
		setS3();
		const fetchMock = vi.fn(async (url) => {
			if (url === `${spaceUrl('foo/A')}/call/generation_all`) return jsonResp({ event_id: 'evt-A' });
			if (url === `${spaceUrl('foo/A')}/call/generation_all/evt-A`) {
				return sseStream([{ url: 'https://files.hf/tmp/gradio/gone/model.glb' }]);
			}
			if (url === 'https://files.hf/tmp/gradio/gone/model.glb') return new Response('', { status: 404 });
			throw new Error(`unexpected url ${url}`);
		});
		globalThis.fetch = fetchMock;

		const { createRegenProvider } = await import('../../api/_providers/huggingface.js');
		await expect(
			createRegenProvider().submit({
				mode: 'reconstruct',
				params: { images: ['data:image/jpeg;base64,AAA'] },
			}),
		).rejects.toMatchObject({
			code: 'all_providers_failed',
			message: expect.stringMatching(/not persistable/),
		});
		// The doomed ephemeral URL was never persisted.
		expect(putObject).not.toHaveBeenCalled();
	});

	it('recovers the mesh via the canonical /file= route when the Space\'s self-reported url is a stale proxy path', async () => {
		setS3();
		// Observed live on stabilityai/TripoSR (2026-07-16): the FileData `url`
		// carries a replica-router prefix ("/ca/file=...") that 404s, while the
		// same file serves fine at `${spaceUrl}/file=${path}`. The provider must
		// build the canonical route from `path` instead of dying on the bad url.
		const base = spaceUrl('foo/A');
		const fetchMock = vi.fn(async (url) => {
			if (url === `${base}/call/generation_all`) return jsonResp({ event_id: 'evt-A' });
			if (url === `${base}/call/generation_all/evt-A`) {
				return sseStream([
					{ path: '/tmp/gradio/abc/mesh.obj', url: `${base}/ca/file=/tmp/gradio/abc/mesh.obj` },
					{ path: '/tmp/gradio/abc/mesh.glb', url: `${base}/ca/file=/tmp/gradio/abc/mesh.glb` },
				]);
			}
			if (url === `${base}/file=/tmp/gradio/abc/mesh.glb`) {
				return new Response(glbBytes(), { status: 200, headers: { 'content-type': 'model/gltf-binary' } });
			}
			// The stale proxy-prefixed url 404s, as it does live.
			if (url === `${base}/ca/file=/tmp/gradio/abc/mesh.glb`) return new Response('', { status: 404 });
			throw new Error(`unexpected url ${url}`);
		});
		globalThis.fetch = fetchMock;

		const { createRegenProvider } = await import('../../api/_providers/huggingface.js');
		const out = await createRegenProvider().submit({
			mode: 'reconstruct',
			params: { images: ['data:image/jpeg;base64,AAA'] },
		});

		const decoded = JSON.parse(Buffer.from(out.extJobId, 'base64url').toString('utf8'));
		expect(decoded.resultGlbUrl).toMatch(/^https:\/\/cdn\.example\/hf-recon\/[0-9a-f-]+\.glb$/);
		expect(putObject).toHaveBeenCalledTimes(1);
	});

	it('skips re-host entirely (no mesh fetch, no upload) when storage is unconfigured', async () => {
		clearS3();
		const fetchMock = vi.fn(async (url) => {
			if (url === `${spaceUrl('foo/A')}/call/generation_all`) return jsonResp({ event_id: 'evt-A' });
			if (url === `${spaceUrl('foo/A')}/call/generation_all/evt-A`) {
				return sseStream([{ url: 'https://files.hf/tmp/gradio/x/model.glb' }]);
			}
			throw new Error(`unexpected url ${url}`); // a mesh fetch here would fail the test
		});
		globalThis.fetch = fetchMock;

		const { createRegenProvider } = await import('../../api/_providers/huggingface.js');
		const out = await createRegenProvider().submit({
			mode: 'reconstruct',
			params: { images: ['data:image/jpeg;base64,AAA'] },
		});

		const decoded = JSON.parse(Buffer.from(out.extJobId, 'base64url').toString('utf8'));
		expect(decoded.resultGlbUrl).toBe('https://files.hf/tmp/gradio/x/model.glb');
		expect(putObject).not.toHaveBeenCalled();
		// enqueue + SSE only — the mesh URL was never fetched.
		expect(fetchMock.mock.calls.length).toBe(2);
	});
});