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.

9.2 KB
Raw Blame
/**
 * GET /api/objects/library, CC0 prop manifest proxy.
 *
 * The endpoint proxies the R2-hosted object manifest (published by
 * scripts/build-object-library.mjs). Contract under test:
 *   - pre-launch (manifest object missing) → 200 { objects: [], total: 0 },
 *     never an error, so /objects and the AR Studio Objects tray feature-detect
 *     by emptiness;
 *   - a real storage outage also degrades to empty, but with no-store so the
 *     edge cache cannot pin "no objects" for the next 300s;
 *   - published manifest ({ objects: [...] } shape) → passed through with total
 *     derived server-side; bare-array manifests (legacy shape) also accepted;
 *   - opt-in pagination via ?limit / ?offset, with a malformed cursor rejected
 *     as 400 JSON rather than silently coerced into a page nobody asked for;
 *   - non-GET → 405.
 */

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

const readManifest = vi.fn();
vi.mock('../api/_lib/r2.js', () => ({ getPublicObjectBuffer: (...a) => readManifest(...a) }));

const { default: handler } = await import('../api/objects/library.js');

function fakeReq(method = 'GET', url = '/api/objects/library') {
	return { method, url, headers: {} };
}

function fakeRes() {
	const headers = {};
	return {
		statusCode: 0,
		body: undefined,
		ended: false,
		setHeader(k, v) { headers[String(k).toLowerCase()] = v; },
		getHeader(k) { return headers[String(k).toLowerCase()]; },
		end(b) { this.body = b; this.ended = true; },
		_headers: headers,
	};
}

async function get(query = '') {
	const res = fakeRes();
	await handler(fakeReq('GET', `/api/objects/library${query}`), res);
	return { res, body: JSON.parse(res.body) };
}

const OBJECT = {
	name: 'adjustable_wrench',
	label: 'Adjustable Wrench',
	url: 'https://cdn.example/objects/polyhaven/glb/adjustable_wrench.glb',
	thumb: 'https://cdn.example/objects/polyhaven/thumbs/adjustable_wrench.png',
	bytes: 2639744,
	categories: ['props', 'tools'],
	tags: ['vintage', 'hand tool'],
	license: 'CC0',
	source: 'polyhaven',
};

// No beforeEach reset: every test installs its own mockResolvedValue/
// mockRejectedValue, which fully replaces the previous implementation.
describe('GET /api/objects/library', () => {
	it('returns an empty library when the manifest has not been uploaded yet', async () => {
		const missing = Object.assign(new Error('no such key'), { name: 'NoSuchKey' });
		readManifest.mockRejectedValue(missing);
		const { res, body } = await get();
		expect(res.statusCode).toBe(200);
		expect(body).toEqual({ objects: [], total: 0, generated_at: null });
		// A library that simply has not launched yet is a steady state, so it keeps
		// the normal edge cache.
		expect(res.getHeader('cache-control')).toContain('s-maxage=300');
	});

	it('degrades to an empty library on storage errors without caching the emptiness', async () => {
		readManifest.mockRejectedValue(new Error('socket hang up'));
		const { res, body } = await get();
		expect(res.statusCode).toBe(200);
		expect(body.objects).toEqual([]);
		expect(res.getHeader('cache-control')).toBe('no-store');
	});

	it('passes through a published { objects } manifest and derives total', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify({
			generated_at: '2026-07-21T13:16:14.305Z',
			total: 1,
			objects: [OBJECT],
		})));
		const { res, body } = await get();
		expect(res.statusCode).toBe(200);
		expect(body.objects).toEqual([OBJECT]);
		expect(body.total).toBe(1);
		expect(body.generated_at).toBe('2026-07-21T13:16:14.305Z');
		expect(res.getHeader('cache-control')).toContain('s-maxage=300');
	});

	it('accepts a bare-array manifest shape', async () => {
		readManifest.mockResolvedValue(Buffer.from(JSON.stringify([OBJECT])));
		const { body } = await get();
		expect(body.objects).toEqual([OBJECT]);
	});

	it('rejects non-GET methods', async () => {
		readManifest.mockResolvedValue(Buffer.from('[]'));
		const res = fakeRes();
		await handler(fakeReq('POST'), res);
		expect(res.statusCode).toBe(405);
	});

	// ── Bounded pagination (opt-in via ?limit) ──────────────────────────────
	const OBJECTS = Array.from({ length: 5 }, (_, i) => ({ ...OBJECT, name: `prop-${i}` }));
	const publish = () => readManifest.mockResolvedValue(Buffer.from(JSON.stringify({ objects: OBJECTS })));

	it('pages a large manifest with ?limit and exposes next_offset', async () => {
		publish();
		const { body } = await get('?limit=2');
		expect(body.total).toBe(5); // full catalog size, not the page size
		expect(body.objects.map((o) => o.name)).toEqual(['prop-0', 'prop-1']);
		expect(body.offset).toBe(0);
		expect(body.next_offset).toBe(2);
	});

	it('honors ?offset and returns next_offset=null on the final page', async () => {
		publish();
		const { body } = await get('?limit=2&offset=4');
		expect(body.objects.map((o) => o.name)).toEqual(['prop-4']);
		expect(body.offset).toBe(4);
		expect(body.next_offset).toBe(null);
	});

	it('returns an empty page (not an error) when offset runs past the end', async () => {
		publish();
		const { body } = await get('?limit=2&offset=99');
		expect(body.objects).toEqual([]);
		expect(body.total).toBe(5);
		expect(body.next_offset).toBe(null);
	});

	it('clamps an oversized limit to the documented maximum instead of failing', async () => {
		publish();
		const { res, body } = await get('?limit=99999');
		expect(res.statusCode).toBe(200);
		expect(body.objects).toHaveLength(5);
		expect(body.next_offset).toBe(null);
	});

	it('omits pagination fields entirely when ?limit is absent (legacy contract)', async () => {
		publish();
		const { body } = await get();
		expect(body).toEqual({ objects: OBJECTS, total: 5, generated_at: null });
		expect('next_offset' in body).toBe(false);
	});

	// ── Malformed cursors are the caller's bug, not a silently coerced page ──
	for (const bad of ['abc', '', '0', '-5', '2.7', '1e3', 'NaN']) {
		it(`rejects ?limit=${JSON.stringify(bad)} with a 400 JSON error`, async () => {
			publish();
			const { res, body } = await get(`?limit=${encodeURIComponent(bad)}`);
			expect(res.statusCode).toBe(400);
			expect(body.error).toBe('invalid_limit');
			expect(body.error_description).toContain('1 to 1000');
			expect(res.getHeader('cache-control')).toBe('no-store');
		});
	}

	for (const bad of ['abc', '-3', '1.5', '']) {
		it(`rejects ?offset=${JSON.stringify(bad)} with a 400 JSON error`, async () => {
			publish();
			const { res, body } = await get(`?limit=2&offset=${encodeURIComponent(bad)}`);
			expect(res.statusCode).toBe(400);
			expect(body.error).toBe('invalid_offset');
		});
	}

	it('rejects ?offset without ?limit rather than ignoring it', async () => {
		publish();
		const { res, body } = await get('?offset=2');
		expect(res.statusCode).toBe(400);
		expect(body.error).toBe('invalid_offset');
		expect(body.error_description).toContain('limit');
	});

	// A doomed request must not pay for an upstream read first. The 400 cannot
	// change based on what R2 returns, so fetching the manifest anyway is pure
	// added latency on every client-side pagination bug.
	it('rejects a malformed cursor without touching storage', async () => {
		publish();
		readManifest.mockClear();
		const { res } = await get('?limit=abc');
		expect(res.statusCode).toBe(400);
		expect(readManifest).not.toHaveBeenCalled();
	});

	// ── Corrupt manifests are an outage, not an empty library ────────────────
	it('degrades without caching when the manifest is not valid JSON', async () => {
		readManifest.mockResolvedValue(Buffer.from('{"objects": [truncated'));
		const { res, body } = await get();
		expect(res.statusCode).toBe(200);
		expect(body.objects).toEqual([]);
		expect(res.getHeader('cache-control')).toBe('no-store');
	});

	it('degrades without caching when the manifest carries no object list', async () => {
		// Parses fine, but a `null` / wrong-shape body means a bad upload, and
		// caching "no objects" for 300s would outlive the bad upload.
		for (const bad of ['null', '{"objects":"nope"}', '"a string"']) {
			readManifest.mockResolvedValue(Buffer.from(bad));
			const { res, body } = await get();
			expect(res.statusCode).toBe(200);
			expect(body.objects).toEqual([]);
			expect(body.total).toBe(0);
			expect(res.getHeader('cache-control')).toBe('no-store');
		}
	});

	it('keeps the normal cache for a manifest that is legitimately empty', async () => {
		readManifest.mockResolvedValue(Buffer.from('{"objects":[]}'));
		const { res, body } = await get();
		expect(body.objects).toEqual([]);
		expect(res.getHeader('cache-control')).toContain('s-maxage=300');
	});

	it('does not cache a degraded response on the paginated path either', async () => {
		readManifest.mockRejectedValue(new Error('socket hang up'));
		const { res, body } = await get('?limit=2');
		expect(res.statusCode).toBe(200);
		expect(body.objects).toEqual([]);
		expect(body.next_offset).toBe(null);
		expect(res.getHeader('cache-control')).toBe('no-store');
	});

	// HEAD must behave like GET (api/_lib/http.js normalizes it); Node strips the
	// body. A handler that fell through on HEAD would hang until the timeout.
	it('answers HEAD like GET', async () => {
		publish();
		const res = fakeRes();
		await handler(fakeReq('HEAD'), res);
		expect(res.statusCode).toBe(200);
		expect(res.getHeader('cache-control')).toContain('s-maxage=300');
	});
});