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.

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.js
index 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.md
index 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.js
index 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);