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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(forge): add /api/forge-batch to fan out and poll N generations as a group
nirholaseb0c6322327b
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.jsindex 233b468c7..e9b8965bb 100644--- a/api/_lib/rate-limit.js+++ b/api/_lib/rate-limit.js@@ -1009,6 +1009,23 @@ export const limits = {limit: Math.max(FREE_HOURLY_BASE, Math.round(FREE_HOURLY_BASE * (Number(multiplier) || 1))),window: '1 h',}).limit(key),+ // Batch submit (api/forge-batch.js): one call fans out to N /forge+ // submissions internally, so it needs its own, much tighter ceiling than+ // mcp3dGenerateFreeTiered guards per-item spend already (each fanned-out+ // item still passes through the free lane's own per-IP limiter). This+ // bucket just caps how many BATCH calls a principal can open per hour; the+ // same $THREE tier multiplier that raises the free lane also raises this.+ forgeBatchSubmit: (key, multiplier = 1) =>+ getLimiter('forge:batch:submit', {+ limit: Math.max(10, Math.round(10 * (Number(multiplier) || 1))),+ window: '1 h',+ }).limit(key),+ // Batch group polling (GET /api/forge-batch?batch=) fans out to N+ // /forge?job= status checks per call, same high-frequency shape as+ // mcp3dStatus, so it gets the same per-instance (`local`) treatment: a+ // distributed Redis command per poll buys no real protection here.+ forgeBatchStatus: (key) =>+ getLimiter('forge:batch:status', { limit: 120, window: '1 m', local: true }).limit(key),// Material Studio (api/material-studio.js): non-destructive material edits,// AI restyle (one watsonx call + one gltf-transform mutation pass — cheap,// no GPU job), and seeded variant fan-out. Free, hosted, and non-criticaldiff --git a/api/forge-batch.js b/api/forge-batch.jsnew file mode 100644index 000000000..4cd1e45fc--- /dev/null+++ b/api/forge-batch.js@@ -0,0 +1,269 @@+/**+ * Forge batch: submit up to MAX_ITEMS /api/forge generations in one call,+ * concurrency-capped by the caller's $THREE holder tier, and poll the group.+ *+ * POST /api/forge-batch { items: [ <any /api/forge POST body>, ... ] }+ * -> { batch_id, items: [{ index, ok, job_id?, status?, glb_url?, error? }] }+ * GET /api/forge-batch?batch=<id>+ * -> { batch_id, status: 'queued'|'running'|'done'|'partial', items: [...] }+ *+ * Each item is a full, independent /api/forge submission (api/forge.js),+ * called over HTTP against this deployment's own origin (the same self-call+ * idiom api/_mcp-studio/forge-client.js uses), so every lane-selection,+ * gating, and caching rule /api/forge already enforces applies per item+ * unchanged. This endpoint adds only the fan-out, the concurrency cap, and+ * the group bookkeeping: it never touches the database directly, since each+ * item's /api/forge call already persists its own durable forge_creations row.+ *+ * Concurrency cap: the $THREE holder-tier rate multiplier that already lifts+ * the free generation ceiling (freeLaneMultiplier in forge.js) also lifts how+ * many items of one batch submit at once (BASE_CONCURRENCY * multiplier,+ * capped at MAX_CONCURRENCY): the resolution is re-implemented locally from+ * the same primitives (three-tier.js, comp-access.js) rather than imported+ * from forge.js, which keeps the multiplier private to that module.+ *+ * Per-item isolation: one item's failure never fails the batch (mirrors+ * api/x402/mint-to-mesh-batch.js's convention): a submit error on item 2+ * still returns items 0, 1, 3... with their own real job ids.+ *+ * Group state lives in Redis only (fr:batch: prefix, mirrors the best-effort,+ * fail-open pattern in forge-job-options.js): a Redis outage at submit time+ * degrades to an un-grouped response (every item still carries a real job id+ * the caller can poll individually via GET /api/forge?job=); at poll time it+ * is a 404 for the group endpoint specifically, never a broken item result.+ */++import { randomUUID } from 'node:crypto';+import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';+import { limits, clientIp } from './_lib/rate-limit.js';+import { getRedis } from './_lib/redis.js';+import { selfOrigin } from './_lib/self-origin.js';+import { TIERS, verifyTierPass } from './_lib/three-tier.js';+import { resolveCompAccess, COMP_TIER } from './_lib/comp-access.js';++const PREFIX = 'fr:batch:';+const TTL_S = 3600;+const MAX_ITEMS = 8;+const BASE_CONCURRENCY = 2;+const MAX_CONCURRENCY = 8;+const SUBMIT_TIMEOUT_MS = 90_000;+const TERMINAL_STATUSES = new Set(['done', 'failed']);++// Same resolution as forge.js's private freeLaneMultiplier: a verified $THREE+// tier pass wins outright; a comped account (cookie-guarded, zero cost on the+// anonymous path) is the fallback. Re-implemented here rather than imported+// because freeLaneMultiplier is private to forge.js.+async function batchConcurrency(req, body) {+ const token = req.headers?.['x-three-tier-pass'] || body?.tier_pass || null;+ let multiplier = 1;+ if (token) {+ const payload = verifyTierPass(token);+ const tier = payload ? TIERS.find((t) => t.level === payload.level) : null;+ multiplier = tier?.rateMultiplier || 1;+ }+ if (multiplier <= 1) {+ const { comped } = await resolveCompAccess(req);+ if (comped) multiplier = COMP_TIER.rateMultiplier || 1;+ }+ const concurrency = Math.min(MAX_CONCURRENCY, Math.max(BASE_CONCURRENCY, Math.round(BASE_CONCURRENCY * multiplier)));+ return { multiplier, concurrency };+}++// Concurrency-capped fan-out: no p-limit-style utility exists in api/_lib, so+// a small inline worker pool runs `limit` workers pulling from a shared index.+async function runPool(items, limit, worker) {+ const results = new Array(items.length);+ let next = 0;+ async function runner() {+ for (;;) {+ const i = next++;+ if (i >= items.length) return;+ results[i] = await worker(items[i], i);+ }+ }+ await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));+ return results;+}++async function submitOne(base, headers, item, index) {+ let res;+ try {+ res = await fetch(`${base}/api/forge`, {+ method: 'POST',+ headers,+ body: JSON.stringify(item),+ signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),+ });+ } catch (err) {+ const timedOut = err?.name === 'TimeoutError' || err?.name === 'AbortError';+ return {+ index,+ ok: false,+ error: timedOut ? 'timeout' : 'provider_error',+ message: timedOut+ ? 'the 3D generator took too long to accept this item'+ : `the 3D generator is unreachable: ${err?.message || err}`,+ };+ }+ const data = await res.json().catch(() => ({}));+ if (!res.ok) {+ return {+ index,+ ok: false,+ error: data?.error || 'provider_error',+ message: data?.message || `the 3D generator returned ${res.status} for this item`,+ };+ }+ return {+ index,+ ok: true,+ job_id: data.job_id ?? null,+ creation_id: data.creation_id ?? null,+ status: data.status || (data.job_id ? 'queued' : 'done'),+ glb_url: data.glb_url ?? null,+ path: data.path ?? null,+ tier: data.tier ?? null,+ backend: data.backend ?? null,+ };+}++async function pollOne(base, item) {+ if (!item.ok || !item.job_id || TERMINAL_STATUSES.has(item.status)) return item;+ let res;+ try {+ res = await fetch(`${base}/api/forge?job=${encodeURIComponent(item.job_id)}`, {+ signal: AbortSignal.timeout(15_000),+ });+ } catch {+ return item; // transient poll failure: keep the last known status, try again next poll+ }+ const data = await res.json().catch(() => null);+ if (!data) return item;+ return {+ ...item,+ status: data.status || item.status,+ glb_url: data.glb_url ?? item.glb_url,+ ...(data.status === 'failed' && data.error ? { error: 'generation_failed', message: data.error } : {}),+ };+}++function itemTerminal(item) {+ return item.ok === false || TERMINAL_STATUSES.has(item.status);+}++function groupStatus(items) {+ if (items.every(itemTerminal)) {+ return items.every((i) => i.ok && i.status === 'done') ? 'done' : 'partial';+ }+ return items.some((i) => i.ok && i.status && i.status !== 'queued') ? 'running' : 'queued';+}++async function storeBatch(batchId, record) {+ const r = getRedis();+ if (!r) return;+ try {+ await r.set(`${PREFIX}${batchId}`, JSON.stringify(record), { ex: TTL_S });+ } catch {+ /* best-effort: items already carry their own job ids */+ }+}++async function loadBatch(batchId) {+ const r = getRedis();+ if (!r) return null;+ try {+ const raw = await r.get(`${PREFIX}${batchId}`);+ if (!raw) return null;+ return typeof raw === 'string' ? JSON.parse(raw) : raw;+ } catch {+ return null;+ }+}++async function startBatch(req, res) {+ const body = await readJson(req, 64_000).catch(() => null);+ const rawItems = Array.isArray(body?.items) ? body.items : null;+ if (!rawItems || !rawItems.length) {+ return json(res, 400, {+ error: 'missing_items',+ message: `Pass items: an array of 1..${MAX_ITEMS} /api/forge request bodies.`,+ });+ }+ if (rawItems.length > MAX_ITEMS) {+ return json(res, 400, {+ error: 'too_many_items',+ message: `A batch holds at most ${MAX_ITEMS} items; split into multiple batches.`,+ max_items: MAX_ITEMS,+ });+ }+ for (let i = 0; i < rawItems.length; i++) {+ if (!rawItems[i] || typeof rawItems[i] !== 'object' || Array.isArray(rawItems[i])) {+ return json(res, 400, {+ error: 'invalid_item',+ message: `items[${i}] must be an object, the same shape as a /api/forge POST body.`,+ });+ }+ }++ const ip = clientIp(req);+ const { multiplier, concurrency } = await batchConcurrency(req, body);+ const rl = await limits.forgeBatchSubmit(ip, multiplier);+ if (!rl.success) return rateLimited(res, rl);++ const base = selfOrigin(req);+ // Forward the real caller's IP as x-forwarded-for so /api/forge's own+ // per-IP free-lane limiter and $THREE tier gate attribute to the actual+ // caller rather than this server's own egress address; forward the+ // session cookie and tier pass so the holder/comp perk this endpoint+ // already resolved for the concurrency cap also applies inside each+ // item's own /api/forge submission. Never the internal seed header: a+ // batch submit is never platform-funded.+ const forwardHeaders = {+ 'content-type': 'application/json',+ 'x-forwarded-for': ip,+ ...(req.headers.cookie ? { cookie: req.headers.cookie } : {}),+ ...(req.headers['x-three-tier-pass'] ? { 'x-three-tier-pass': req.headers['x-three-tier-pass'] } : {}),+ ...(req.headers['x-forge-client'] ? { 'x-forge-client': req.headers['x-forge-client'] } : {}),+ };++ const items = await runPool(rawItems, concurrency, (item, index) => submitOne(base, forwardHeaders, item, index));++ const batchId = randomUUID();+ await storeBatch(batchId, { batch_id: batchId, created_at: Date.now(), items });++ return json(res, 200, { batch_id: batchId, status: groupStatus(items), items });+}++async function pollBatch(req, res, batchId) {+ const rl = await limits.forgeBatchStatus(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const record = await loadBatch(batchId);+ if (!record) {+ return json(res, 404, {+ error: 'batch_not_found',+ message: 'Unknown or expired batch id. Poll each item individually via GET /api/forge?job=<id> instead.',+ });+ }++ const base = selfOrigin(req);+ const items = await Promise.all(record.items.map((item) => pollOne(base, item)));+ const status = groupStatus(items);+ await storeBatch(batchId, { ...record, items });++ return json(res, 200, { batch_id: batchId, status, items });+}++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;+ if (!method(req, res, ['GET', 'POST'])) return;++ if (req.method === 'POST') return startBatch(req, res);++ const url = new URL(req.url, 'http://localhost');+ const batchId = (url.searchParams.get('batch') || '').trim();+ if (!batchId) {+ return json(res, 400, { error: 'missing_batch', message: 'Pass ?batch=<id> to poll a batch.' });+ }+ return pollBatch(req, res, batchId);+});diff --git a/tests/api/forge-batch.test.js b/tests/api/forge-batch.test.jsnew file mode 100644index 000000000..f46507ae7--- /dev/null+++ b/tests/api/forge-batch.test.js@@ -0,0 +1,198 @@+/**+ * POST/GET /api/forge-batch: fan out N /api/forge submissions from one call+ * and poll them as a group (api/forge-batch.js).+ *+ * /api/forge itself is never exercised here: every self-call is a mocked+ * `fetch`, so these tests pin forge-batch.js's own contract (validation,+ * per-item isolation, group status, Redis-backed retrieval) independent of+ * the real generation pipeline.+ */++import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';++beforeAll(() => {+ Object.assign(process.env, {+ APP_ORIGIN: 'https://three.ws',+ JWT_SECRET: 'test-jwt-secret-at-least-32-characters-long',+ });+});++const store = new Map();+function fakeRedis() {+ return {+ async set(key, value) {+ store.set(key, value);+ },+ async get(key) {+ return store.has(key) ? store.get(key) : null;+ },+ };+}++vi.mock('../../api/_lib/redis.js', () => ({+ getRedis: () => fakeRedis(),+}));++vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {+ const actual = await importActual();+ return {+ ...actual,+ limits: {+ ...actual.limits,+ forgeBatchSubmit: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),+ forgeBatchStatus: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),+ },+ clientIp: () => '203.0.113.9',+ };+});++const { default: handler } = await import('../../api/forge-batch.js');++function makePostReq(body, { headers = {} } = {}) {+ return {+ method: 'POST',+ url: '/api/forge-batch',+ headers: { 'content-type': 'application/json', ...headers },+ on(event, cb) {+ if (event === 'data') cb(Buffer.from(JSON.stringify(body)));+ if (event === 'end') cb();+ },+ };+}++function makeGetReq(url, { headers = {} } = {}) {+ return { method: 'GET', url, headers };+}++function makeRes() {+ return {+ statusCode: 200,+ headers: {},+ body: null,+ setHeader(name, value) {+ this.headers[String(name).toLowerCase()] = value;+ },+ getHeader(name) {+ return this.headers[String(name).toLowerCase()];+ },+ end(body) {+ this.body = body ? JSON.parse(body) : null;+ },+ };+}++function mockFetchSequence(impl) {+ vi.stubGlobal('fetch', vi.fn(impl));+}++function jsonResponse(status, data) {+ return { ok: status >= 200 && status < 300, status, json: async () => data };+}++describe('POST /api/forge-batch', () => {+ beforeEach(() => {+ store.clear();+ vi.unstubAllGlobals();+ });++ it('submits every item and returns a retrievable batch id', async () => {+ let n = 0;+ mockFetchSequence(async (url) => {+ expect(String(url)).toBe('https://three.ws/api/forge');+ n += 1;+ return jsonResponse(200, { job_id: `job-${n}`, status: 'queued', path: 'image', tier: 'draft', backend: 'nvidia' });+ });++ const req = makePostReq({ items: [{ prompt: 'a' }, { prompt: 'b' }, { prompt: 'c' }, { prompt: 'd' }] });+ const res = makeRes();+ await handler(req, res);++ expect(res.statusCode).toBe(200);+ expect(res.body.batch_id).toBeTruthy();+ expect(res.body.items).toHaveLength(4);+ expect(res.body.items.every((i) => i.ok && i.job_id)).toBe(true);+ expect(res.body.status).toBe('queued');+ });++ it('isolates one failing item: the rest still submit with real job ids', async () => {+ mockFetchSequence(async (url, init) => {+ const body = JSON.parse(init.body);+ if (body.prompt === 'bad') return jsonResponse(400, { error: 'invalid_options', message: 'nope' });+ return jsonResponse(200, { job_id: `job-${body.prompt}`, status: 'queued' });+ });++ const req = makePostReq({ items: [{ prompt: 'good1' }, { prompt: 'bad' }, { prompt: 'good2' }] });+ const res = makeRes();+ await handler(req, res);++ expect(res.statusCode).toBe(200);+ expect(res.body.items[0]).toMatchObject({ ok: true, job_id: 'job-good1' });+ expect(res.body.items[1]).toMatchObject({ ok: false, error: 'invalid_options' });+ expect(res.body.items[2]).toMatchObject({ ok: true, job_id: 'job-good2' });+ });++ it('rejects an empty items array', async () => {+ const req = makePostReq({ items: [] });+ const res = makeRes();+ await handler(req, res);+ expect(res.statusCode).toBe(400);+ expect(res.body.error).toBe('missing_items');+ });++ it('rejects a batch larger than the max', async () => {+ const items = Array.from({ length: 9 }, (_, i) => ({ prompt: `p${i}` }));+ const req = makePostReq({ items });+ const res = makeRes();+ await handler(req, res);+ expect(res.statusCode).toBe(400);+ expect(res.body.error).toBe('too_many_items');+ });+});++describe('GET /api/forge-batch?batch=', () => {+ beforeEach(() => {+ store.clear();+ vi.unstubAllGlobals();+ });++ it('completes a 4-item batch and retrieves it as a group', async () => {+ let n = 0;+ mockFetchSequence(async (url) => {+ n += 1;+ return jsonResponse(200, { job_id: `job-${n}`, status: 'queued' });+ });+ const submit = makePostReq({ items: [{ prompt: 'a' }, { prompt: 'b' }, { prompt: 'c' }, { prompt: 'd' }] });+ const submitRes = makeRes();+ await handler(submit, submitRes);+ const { batch_id } = submitRes.body;++ mockFetchSequence(async (url) => {+ const jobId = decodeURIComponent(String(url).split('job=')[1]);+ return jsonResponse(200, { job_id: jobId, status: 'done', glb_url: `https://cdn.example/${jobId}.glb` });+ });+ const poll = makeGetReq(`/api/forge-batch?batch=${batch_id}`);+ const pollRes = makeRes();+ await handler(poll, pollRes);++ expect(pollRes.statusCode).toBe(200);+ expect(pollRes.body.status).toBe('done');+ expect(pollRes.body.items).toHaveLength(4);+ expect(pollRes.body.items.every((i) => i.status === 'done' && i.glb_url)).toBe(true);+ });++ it('404s on an unknown batch id', async () => {+ const req = makeGetReq('/api/forge-batch?batch=does-not-exist');+ const res = makeRes();+ await handler(req, res);+ expect(res.statusCode).toBe(404);+ expect(res.body.error).toBe('batch_not_found');+ });++ it('400s when no batch id is passed', async () => {+ const req = makeGetReq('/api/forge-batch');+ const res = makeRes();+ await handler(req, res);+ expect(res.statusCode).toBe(400);+ expect(res.body.error).toBe('missing_batch');+ });+});