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
fix(sim-readiness): meter the lane that downloads, and leave the lookup lane free
nirholas38355e275bf3
diff --git a/api/sim-readiness.js b/api/sim-readiness.jsindex 4c8e25735..cef842952 100644--- a/api/sim-readiness.js+++ b/api/sim-readiness.js@@ -20,7 +20,8 @@* Spec: specs/SIM_READINESS.md.*/-import { cors, method, wrap } from './_lib/http.js';+import { cors, method, rateLimited, wrap } from './_lib/http.js';+import { clientIp, limits } from './_lib/rate-limit.js';import { gradeForCaller } from './_mcp3d/tools/sim-readiness.js';// A grade is immutable for fixed bytes under a fixed grader, so the only thing@@ -32,6 +33,18 @@ const CACHE_HEADER = 'public, max-age=60, s-maxage=300';// Anything unmapped is a 500 and reaches the wrap() error path.const STATUS_BY_CODE = { invalid_input: 400, not_graded: 404, too_large: 413, fetch_failed: 502 };+// Only `?src=` is metered, and it is metered on the generic per-IP bucket sized+// for this traffic shape rather than a bucket of its own. The two lanes cost+// wildly different things: `?hash=` is one indexed row read, while `?src=`+// makes this server fetch up to 64 MB from an arbitrary host and build a convex+// hull over it. Capping the expensive lane at 30 per 5 minutes per IP leaves a+// person grading a folder of assets, or an agent screening a shortlist, far+// more headroom than either needs, while stopping the endpoint from being used+// as a free fetch-and-compute treadmill. The cheap lane stays uncapped on+// purpose: a client that pages through known hashes is exactly the usage this+// design is trying to encourage.+const GRADE_LIMIT = { limit: 30, window: '5 m' };+function fail(res, status, body) {res.statusCode = status;res.setHeader('content-type', 'application/json; charset=utf-8');@@ -49,6 +62,13 @@ export default wrap(async (req, res) => {const src = url.searchParams.get('src') || url.searchParams.get('glb_url') || '';const hash = url.searchParams.get('hash') || '';+ if (src) {+ const rl = await limits.apiIp(clientIp(req), GRADE_LIMIT);+ if (!rl.success) {+ return rateLimited(res, rl, 'too many grades from this address; grade by content hash, or retry shortly');+ }+ }+let envelope;try {envelope = await gradeForCaller({ glb_url: src || undefined, hash: hash || undefined });diff --git a/docs/sim-readiness.md b/docs/sim-readiness.mdindex bc0ba95f0..82be5a263 100644--- a/docs/sim-readiness.md+++ b/docs/sim-readiness.md@@ -68,6 +68,8 @@ curl "https://three.ws/api/sim-readiness?hash=b7001eaeea8254bd…"A hash nobody has graded returns `404 {"error": "not graded"}`. That is the cheap call: use it in a loop, and fall back to `?src=` only when you need bytes fetched and measured.+The two lanes cost very different things, so only one is metered. `?hash=` is a single indexed row read and is uncapped. `?src=` makes this server fetch up to 64 MB from a host you named and build a convex hull over it, so it is capped at 30 per five minutes per address; over that you get a `429` with `Retry-After`. If you are screening a large catalogue, grade once and use the hashes afterwards.+### Every response| Case | Status | Body |@@ -78,6 +80,7 @@ A hash nobody has graded returns `404 {"error": "not graded"}`. That is the chea| `src` is not a public https URL | 400 | `{ "error": "src must be a public https URL" }` || Asset over 64 MB | 413 | `{ "error": "asset exceeds 64 MB" }` || The upstream fetch failed | 502 | `{ "error": "could not fetch the asset", "status": 404 }` |+| More than 30 `?src=` grades in 5 minutes from one address | 429 | `{ "error": "rate_limited", "retry_after": 294 }` with `Retry-After` || Not binary glTF 2.0 | 200 | `{ "readable": false, "verdict": "unreadable", "blockers": ["unreadable_glb"] }` |That last row is not a mistake. "This is not a GLB" is a valid grade, not a server error, and a client that gates on `verdict` handles it without a second code path.diff --git a/tests/api/sim-readiness-endpoint.test.js b/tests/api/sim-readiness-endpoint.test.jsindex 42b924c4a..b124fc5ad 100644--- a/tests/api/sim-readiness-endpoint.test.js+++ b/tests/api/sim-readiness-endpoint.test.js@@ -53,6 +53,17 @@ vi.mock('../../api/_lib/ssrf-guard.js', () => ({}),}));+// Switchable per-IP quota, so the metered lane is asserted rather than assumed.+let rlOk = true;+vi.mock('../../api/_lib/rate-limit.js', () => ({+ limits: {+ apiIp: async () => (rlOk+ ? { success: true, limit: 30, remaining: 29, reset: Date.now() + 300_000 }+ : { success: false, limit: 30, remaining: 0, reset: Date.now() + 300_000 }),+ },+ clientIp: () => '203.0.113.9',+}));+vi.mock('../../api/_lib/sim-readiness-store.js', () => ({simReadinessStoreEnabled: () => true,getGrade: vi.fn(async (hash) => stored.get(hash) ?? null),@@ -65,6 +76,7 @@ vi.mock('../../api/_lib/sim-readiness-store.js', () => ({}));beforeEach(() => {+ rlOk = true;upstream = { status: 200, body: REAL_GLB, throws: null };stored = new Map();puts = [];@@ -130,6 +142,24 @@ describe('GET /api/sim-readiness: the request contract', () => {expect(fetchSafePublicUrlPinned).not.toHaveBeenCalled();});+ it('meters the expensive lane and tells the caller to use a hash instead', async () => {+ rlOk = false;+ const { fetchSafePublicUrlPinned } = await import('../../api/_lib/ssrf-guard.js');+ const r = await get('/api/sim-readiness?src=https%3A%2F%2Fthree.ws%2Fa.glb');+ expect(r.status).toBe(429);+ expect(r.body.error).toBe('rate_limited');+ expect(r.headers['retry-after']).toBeTruthy();+ // The whole point of the cap: the fetch never happened.+ expect(fetchSafePublicUrlPinned).not.toHaveBeenCalled();+ });++ it('never meters the cheap hash lookup, which is one indexed read', async () => {+ rlOk = false;+ const r = await get(`/api/sim-readiness?hash=${'b'.repeat(64)}`);+ // 404 rather than 429: the lookup ran.+ expect(r.status).toBe(404);+ });+it('refuses a POST: grading is a read', async () => {const r = await get('/api/sim-readiness?src=https://three.ws/a.glb', 'POST');expect(r.status).toBe(405);