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.

3.6 KB
Raw Blame
// GET /api/cron/forge-thumbnail-backfill
//
// Steady-state drain of the Forge thumbnail coverage gap.
//
// ~79% of finished forge models ship with `preview_image_url = NULL` — the free
// NVIDIA/TRELLIS lane (the majority of all generations) is geometry-first and
// paints no reference image, and the client-side poster capture only fires while
// the maker is watching their own result. So every card that renders those
// models — the "Fresh from the Forge" showcase, the gallery, creator portfolios,
// /community, /search — falls back to a gradient placeholder, and the browse
// loop that brings people back looks broken because most of it is empty squares.
//
// Each tick claims the most-recent previewless models, renders each GLB to a
// 768² PNG with the shared headless-chromium renderer, uploads it, and fills the
// preview slot — object confirmed in R2 before the key is committed, so a card
// never points at a missing image. Fill-only: a poster the maker captured in the
// meantime always wins.
//
// Env:
//   CRON_SECRET                       required (Bearer)
//   FORGE_THUMBNAIL_RENDER_BATCH      models rendered per tick (default 8)
//   FORGE_THUMBNAIL_CONCURRENCY       parallel renders (default 2)
//
// Sizing: a render is ~3-6s, so 8 models at concurrency 2 lands ~25-40s, inside
// maxDuration=120. At */5 that is ~96 models/hour; a large backlog is cleared
// faster with the bulk loop script (scripts/backfill-forge-thumbnails.mjs),
// which shares this claim ledger. `?dry_run=1` reports coverage without
// rendering. Skips cleanly when forge persistence is unconfigured.

import { json, method, wrapCron } from '../_lib/http.js';
import { logger } from '../_lib/usage.js';
import { forgeStoreEnabled } from '../_lib/forge-store.js';
import { renderBatch, coverage } from '../_lib/forge-thumbs.js';
import { requireCron } from '../_lib/cron-auth.js';

export const maxDuration = 120;

const log = logger('forge-thumbnail-backfill');

const RENDER_BATCH = Math.max(0, Number(process.env.FORGE_THUMBNAIL_RENDER_BATCH || 8));
const CONCURRENCY = Math.max(1, Number(process.env.FORGE_THUMBNAIL_CONCURRENCY || 2));

export default wrapCron(async (req, res) => {
	if (!method(req, res, ['GET'])) return;
	if (!requireCron(req, res)) return;

	// Renders upload to R2 and read/write the DB — no store, nothing to do.
	if (!forgeStoreEnabled()) {
		return json(res, 200, { ok: false, reason: 'persistence_unconfigured' });
	}

	const url = new URL(req.url || '/', 'https://three.ws');
	const dryRun = url.searchParams.get('dry_run') === '1';

	const cov = await coverage();
	if (dryRun) {
		return json(res, 200, { ok: true, dry_run: true, coverage: cov, render_batch: RENDER_BATCH });
	}

	if (RENDER_BATCH === 0 || cov.missing === 0) {
		return json(res, 200, { ok: true, coverage: cov, rendered: 0, note: 'nothing to render' });
	}

	let result;
	try {
		result = await renderBatch({ limit: RENDER_BATCH, concurrency: CONCURRENCY });
	} catch (err) {
		log.warn('render_batch_failed', { message: err?.message });
		return json(res, 200, { ok: false, reason: `render_failed: ${err?.message}`, coverage: cov });
	}

	for (const r of result.results) {
		if (r.status === 'done') log.info('rendered', { id: r.id, bytes: r.bytes, ms: r.ms });
		else if (r.status === 'failed') log.warn('render_failed', { id: r.id, error: r.error });
	}
	if (result.aborted) log.warn('batch_aborted', { reason: result.aborted });

	return json(res, 200, {
		ok: true,
		coverage: cov,
		claimed: result.claimed,
		rendered: result.rendered,
		failed: result.failed,
		aborted: result.aborted,
	});
}, { maxDurationMs: maxDuration * 1000 });