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.

feat(forge): add TripoSplat gaussian-splat generation endpoint, GPU worker and provider

nirholas3bd57493dd7e
diff --git a/api/_providers/gcp.js b/api/_providers/gcp.js
index 54f83631d..17f1af862 100644
--- a/api/_providers/gcp.js
+++ b/api/_providers/gcp.js
@@ -30,6 +30,9 @@
// POST /infer → { task_id } GET /tasks/:id → result_gcs_url.
// NOT the avatar controller's /reconstruct + /jobs/:id shape.
//
+// triposplat → MODEL_TRIPOSPLAT_URL (workers/model-triposplat, MIT)
+// One image → 3D Gaussian splat (.splat + .ply). Standard
+// /infer + /tasks/:id shape; the result is a splat, not a GLB.
// remesh → GCP_REMESH_URL (workers/remesh)
// stylize → GCP_STYLIZE_URL (workers/stylize)
// retex → GCP_TEXTURE_URL (workers/texture)
@@ -136,6 +139,10 @@ function serviceUrlForMode(mode) {
// output of `segment`), preserving part node names. Same
// /infer + /tasks/:id task shape.
return readEnv('MODEL_HOLOPART_URL');
+ case 'triposplat':
+ // Self-hosted TripoSplat worker (workers/model-triposplat): image to
+ // Gaussian splat. Same /infer + /tasks/:id task shape.
+ return readEnv('MODEL_TRIPOSPLAT_URL');
case 'modly':
case 'modly_hunyuan':
// Self-hosted Modly worker (workers/modly): one service, two models.
@@ -302,6 +309,21 @@ function buildWorkerRequest(request) {
};
}
+ if (mode === 'triposplat') {
+ // Self-hosted TripoSplat (workers/model-triposplat): the worker
+ // conditions on the first reference image only.
+ const photos = Array.isArray(params?.images) && params.images.length
+ ? params.images
+ : [sourceUrl].filter(Boolean);
+ const body = { images: photos };
+ if (Number.isFinite(Number(params?.num_gaussians))) body.num_gaussians = Math.round(Number(params.num_gaussians));
+ return {
+ path: '/infer',
+ resultKey: 'splat_url',
+ body,
+ };
+ }
+
if (mode === 'holopart') {
// Self-hosted HoloPart (workers/model-holopart): an already part-
// segmented mesh in (one named geometry per part, e.g. workers/segment's
@@ -609,6 +631,8 @@ const MODE_ETA = {
// Per-part point-cloud conditioning + diffusion decode for every part in
// an already-segmented mesh.
holopart: 100,
+ // Single-pass flow-matching denoise plus a decoder replay on the L4.
+ triposplat: 45,
// TripoSG's 20 to 50 flow steps plus repair and decimate on the L4.
modly: 60,
// Hunyuan3D 2 Mini Turbo is a few-step distilled sampler.
@@ -719,7 +743,7 @@ export function createRegenProvider({ reconstructUrl } = {}) {
// on the primary view only (report 1 so a multi-view request is never
// silently claimed as fused); other modes are single-source.
const viewsUsed =
- mode === 'hunyuan' || mode === 'trellis2' || mode === 'modly' || mode === 'modly_hunyuan' || mode === 'anigen' || mode === 'partcrafter'
+ mode === 'hunyuan' || mode === 'triposplat' || mode === 'trellis2' || mode === 'modly' || mode === 'modly_hunyuan' || mode === 'anigen' || mode === 'partcrafter'
? 1
: (mode === 'reconstruct' || mode === 'trellis' || mode === 'pixal3d') && Array.isArray(workerReq.body.images)
? workerReq.body.images.length
@@ -795,6 +819,12 @@ export function createRegenProvider({ reconstructUrl } = {}) {
if (data.mask_url) result.maskUrl = data.mask_url;
if (typeof data.frames === 'number') result.frames = data.frames;
if (typeof data.fps === 'number') result.fps = data.fps;
+ } else if (mode === 'triposplat') {
+ // A Gaussian splat, not a mesh: the compact .splat is the
+ // primary result and the .ply rides along for download.
+ result.resultSplatUrl = url;
+ if (data.ply_url) result.plyUrl = data.ply_url;
+ if (typeof data.num_gaussians === 'number') result.numGaussians = data.num_gaussians;
} else if (mode === 'video2scene') {
// The result is a .ply point cloud, not a GLB mesh. Surface the
// reconstruction telemetry so the client can show point/frame counts.
diff --git a/api/cron/gpu-keepwarm.js b/api/cron/gpu-keepwarm.js
index a5419e6bb..7e6d0c934 100644
--- a/api/cron/gpu-keepwarm.js
+++ b/api/cron/gpu-keepwarm.js
@@ -81,6 +81,17 @@ export const KEEPWARM_LANES = [
safeByDefault: false,
reason: 'same Modly worker as the modly lane; warming either keeps both resident',
},
+ {
+ id: 'pixal3d',
+ urlEnv: 'MODEL_PIXAL3D_URL',
+ region: 'us-central1',
+ accelerator: 'nvidia-l4',
+ safeByDefault: false,
+ // Opt-in "Match my photo" lane (workers/model-pixal3d): never a default or
+ // failover target, so its cold start only matters to callers who asked for it
+ // and the shared us-central1 L4 grant goes to the default lanes first.
+ reason: 'us-central1 L4 grant is shared with the default image lanes; an opt-in lane does not earn a warm floor by default',
+ },
{
id: 'hunyuan3d',
urlEnv: 'GCP_HUNYUAN3D_URL',
diff --git a/api/forge-splat.js b/api/forge-splat.js
new file mode 100644
index 000000000..71c83339b
--- /dev/null
+++ b/api/forge-splat.js
@@ -0,0 +1,117 @@
+/**
+ * /api/forge-splat: image to 3D Gaussian splat (TripoSplat, MIT).
+ *
+ * POST /api/forge-splat { image_url: string, num_gaussians?: int }
+ * → 202 { job_id, status, eta_seconds }
+ *
+ * GET /api/forge-splat?job=<id>
+ * → { job_id, status, splat_url?, ply_url?, num_gaussians?, viewer_url?, error? }
+ *
+ * Routes to workers/model-triposplat (GCP Cloud Run) when MODEL_TRIPOSPLAT_URL
+ * is set. The result opens in the Splat Viewer (/splat?url=...).
+ */
+
+import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
+import { limits, clientIp } from './_lib/rate-limit.js';
+import { assertPublicHttpsUrl, SsrfError } from './_lib/ssrf.js';
+import { createRegenProvider } from './_providers/gcp.js';
+
+const JOB_ID_RE = /^[A-Za-z0-9_-]{20,600}$/;
+export const MIN_GAUSSIANS = 8192;
+export const MAX_GAUSSIANS = 262144;
+
+function unconfigured(res) {
+ return json(res, 503, {
+ error: 'unconfigured',
+ message:
+ 'Image-to-splat is not configured. Set MODEL_TRIPOSPLAT_URL and GCP_RECONSTRUCTION_KEY ' +
+ 'to the URL and bearer secret of your deployed workers/model-triposplat Cloud Run service.',
+ });
+}
+
+export function parseNumGaussians(raw) {
+ if (raw === undefined || raw === null) return { value: undefined };
+ if (!Number.isInteger(raw) || raw < MIN_GAUSSIANS || raw > MAX_GAUSSIANS) {
+ return { error: `num_gaussians must be an integer between ${MIN_GAUSSIANS} and ${MAX_GAUSSIANS}.` };
+ }
+ return { value: raw };
+}
+
+async function startJob(req, res) {
+ const rl = await limits.mcp3dGenerate(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const body = await readJson(req, 4_000).catch(() => null);
+ let imageUrl;
+ try {
+ imageUrl = await assertPublicHttpsUrl(typeof body?.image_url === 'string' ? body.image_url.trim() : '');
+ } catch (err) {
+ return json(res, 400, {
+ error: 'invalid_image_url',
+ message: err instanceof SsrfError ? `image_url rejected: ${err.message}` : 'image_url must be a public https URL.',
+ });
+ }
+
+ const count = parseNumGaussians(body?.num_gaussians);
+ if (count.error) return json(res, 400, { error: 'invalid_num_gaussians', message: count.error });
+
+ let provider;
+ try {
+ provider = createRegenProvider();
+ if (!provider.supportsMode('triposplat')) return unconfigured(res);
+ } catch {
+ return unconfigured(res);
+ }
+
+ try {
+ const job = await provider.submit({
+ mode: 'triposplat',
+ sourceUrl: imageUrl,
+ params: { num_gaussians: count.value },
+ });
+ return json(res, 202, { job_id: job.extJobId, status: 'queued', eta_seconds: job.eta });
+ } catch (err) {
+ return json(res, 502, { error: 'triposplat_failed', message: err?.message || 'Splat generation could not start.' });
+ }
+}
+
+async function pollJob(req, res, jobId) {
+ if (!JOB_ID_RE.test(jobId)) return json(res, 400, { error: 'invalid_job', message: 'Malformed job id.' });
+
+ const rl = await limits.mcp3dStatus(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ let provider;
+ try {
+ provider = createRegenProvider();
+ } catch {
+ return unconfigured(res);
+ }
+
+ let result;
+ try {
+ result = await provider.status(jobId);
+ } catch (err) {
+ return json(res, 502, { error: 'triposplat_status_failed', message: err?.message || 'Could not read the splat job.' });
+ }
+ const splatUrl = result.resultSplatUrl || null;
+ return json(res, 200, {
+ job_id: jobId,
+ status: result.status,
+ splat_url: splatUrl,
+ ply_url: result.plyUrl || null,
+ num_gaussians: result.numGaussians ?? null,
+ viewer_url: splatUrl ? `/splat?url=${encodeURIComponent(splatUrl)}` : null,
+ error: result.error || null,
+ });
+}
+
+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 startJob(req, res);
+
+ const jobId = (new URL(req.url, 'http://localhost').searchParams.get('job') || '').trim();
+ if (!jobId) return json(res, 400, { error: 'missing_job', message: 'Pass ?job=<id> to poll.' });
+ return pollJob(req, res, jobId);
+});
diff --git a/src/home-forge.js b/src/home-forge.js
index d3c44773c..77f10f7d4 100644
--- a/src/home-forge.js
+++ b/src/home-forge.js
@@ -56,8 +56,6 @@ const MAX_POLL_MS = 12 * 60 * 1000;
// keeps holding until the network has been unusable for this long.
const POLL_MAX_BACKOFF_MS = 20_000;
const POLL_TRANSPORT_GRACE_MS = 90_000;
-const MODEL_VIEWER_SRC =
- 'https://ajax.googleapis.com/ajax/libs/model-viewer/4.3.1/model-viewer.min.js';
const HISTORY_KEY = 'forge:home:history';
const HISTORY_MAX = 6;
// Cumulative models forged on this device, driving the sparse milestone nudge
diff --git a/tests/api/forge-splat.test.js b/tests/api/forge-splat.test.js
new file mode 100644
index 000000000..cea7edee7
--- /dev/null
+++ b/tests/api/forge-splat.test.js
@@ -0,0 +1,154 @@
+/**
+ * Tests for the image-to-splat endpoint (api/forge-splat.js). The TripoSplat
+ * worker is stubbed at the provider boundary, so this pins the endpoint's own
+ * contract: image_url SSRF validation, density bounds, the async submit/poll
+ * shape and the viewer deep link. The model itself is covered by the worker's
+ * Python suite and a live run.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Readable } from 'node:stream';
+
+const submit = vi.fn(async () => ({ extJobId: `task-triposplat-${'x'.repeat(20)}`, eta: 45 }));
+const status = vi.fn(async () => ({
+ status: 'done',
+ resultSplatUrl: 'https://storage.googleapis.com/bucket/raw-splats/triposplat/t.splat',
+ plyUrl: 'https://storage.googleapis.com/bucket/raw-splats/triposplat/t.ply',
+ numGaussians: 131072,
+}));
+let supported = true;
+
+vi.mock('../../api/_providers/gcp.js', () => ({
+ createRegenProvider: () => ({
+ supportsMode: (m) => m === 'triposplat' && supported,
+ submit,
+ status,
+ }),
+}));
+
+vi.mock('../../api/_lib/ssrf.js', async (importOriginal) => {
+ const mod = await importOriginal();
+ return {
+ ...mod,
+ assertPublicHttpsUrl: vi.fn(async (url) => {
+ if (new URL(url).protocol !== 'https:') throw new mod.SsrfError('https required');
+ return url;
+ }),
+ };
+});
+
+vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
+ const actual = await importActual();
+ return {
+ ...actual,
+ clientIp: () => '203.0.113.9',
+ limits: {
+ ...actual.limits,
+ mcp3dGenerate: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ mcp3dStatus: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ },
+ };
+});
+
+const { default: handler, parseNumGaussians } = await import('../../api/forge-splat.js');
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: null,
+ setHeader(n, v) {
+ this.headers[String(n).toLowerCase()] = v;
+ },
+ end(b) {
+ this.body = b ?? null;
+ },
+ };
+}
+
+function makeReq({ method = 'POST', url = '/api/forge-splat', body = null } = {}) {
+ const stream = Readable.from(body == null ? [] : [Buffer.from(JSON.stringify(body), 'utf8')]);
+ stream.method = method;
+ stream.url = url;
+ stream.headers = { 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9' };
+ return stream;
+}
+
+const IMAGE = 'https://example.com/house.webp';
+
+beforeEach(() => {
+ submit.mockClear();
+ status.mockClear();
+ supported = true;
+});
+
+describe('parseNumGaussians', () => {
+ it('accepts absent and in-range integers, rejects the rest', () => {
+ expect(parseNumGaussians(undefined)).toEqual({ value: undefined });
+ expect(parseNumGaussians(262144)).toEqual({ value: 262144 });
+ for (const bad of [0, 8191, 262145, 9000.5, '9000', true]) {
+ expect(parseNumGaussians(bad).error).toMatch(/between 8192 and 262144/);
+ }
+ });
+});
+
+describe('POST /api/forge-splat', () => {
+ it('queues a triposplat job for the image', async () => {
+ const res = makeRes();
+ await handler(makeReq({ body: { image_url: IMAGE, num_gaussians: 65536 } }), res);
+ expect(res.statusCode).toBe(202);
+ expect(JSON.parse(res.body)).toMatchObject({ status: 'queued', eta_seconds: 45 });
+ const call = submit.mock.calls[0][0];
+ expect(call.mode).toBe('triposplat');
+ expect(call.sourceUrl).toBe(IMAGE);
+ expect(call.params.num_gaussians).toBe(65536);
+ });
+
+ it('rejects a non-public image_url before calling the worker', async () => {
+ const res = makeRes();
+ await handler(makeReq({ body: { image_url: 'http://169.254.169.254/x.png' } }), res);
+ expect(res.statusCode).toBe(400);
+ expect(JSON.parse(res.body).error).toBe('invalid_image_url');
+ expect(submit).not.toHaveBeenCalled();
+ });
+
+ it('rejects an out-of-range density', async () => {
+ const res = makeRes();
+ await handler(makeReq({ body: { image_url: IMAGE, num_gaussians: 5 } }), res);
+ expect(res.statusCode).toBe(400);
+ expect(JSON.parse(res.body).error).toBe('invalid_num_gaussians');
+ expect(submit).not.toHaveBeenCalled();
+ });
+
+ it('answers 503 with setup guidance when the worker is not configured', async () => {
+ supported = false;
+ const res = makeRes();
+ await handler(makeReq({ body: { image_url: IMAGE } }), res);
+ expect(res.statusCode).toBe(503);
+ expect(JSON.parse(res.body).message).toMatch(/MODEL_TRIPOSPLAT_URL/);
+ });
+});
+
+describe('GET /api/forge-splat?job=', () => {
+ it('returns the splat, ply and a viewer deep link when done', async () => {
+ const res = makeRes();
+ await handler(makeReq({ method: 'GET', url: `/api/forge-splat?job=${'a'.repeat(24)}` }), res);
+ const body = JSON.parse(res.body);
+ expect(res.statusCode).toBe(200);
+ expect(body.status).toBe('done');
+ expect(body.splat_url).toMatch(/\.splat$/);
+ expect(body.ply_url).toMatch(/\.ply$/);
+ expect(body.num_gaussians).toBe(131072);
+ expect(body.viewer_url).toBe(`/splat?url=${encodeURIComponent(body.splat_url)}`);
+ });
+
+ it('rejects a missing or malformed job id', async () => {
+ const a = makeRes();
+ await handler(makeReq({ method: 'GET', url: '/api/forge-splat' }), a);
+ expect(a.statusCode).toBe(400);
+ const b = makeRes();
+ await handler(makeReq({ method: 'GET', url: '/api/forge-splat?job=../etc' }), b);
+ expect(b.statusCode).toBe(400);
+ expect(status).not.toHaveBeenCalled();
+ });
+});
diff --git a/tests/api/gcp-triposplat-provider.test.js b/tests/api/gcp-triposplat-provider.test.js
new file mode 100644
index 000000000..044f555bb
--- /dev/null
+++ b/tests/api/gcp-triposplat-provider.test.js
@@ -0,0 +1,71 @@
+/**
+ * The gcp provider's `triposplat` mode (api/_providers/gcp.js): request shape
+ * sent to workers/model-triposplat and how a finished task maps to a splat
+ * result. fetch is mocked at the network boundary only.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const realFetch = globalThis.fetch;
+const WORKER = 'https://triposplat.example.run.app';
+
+beforeEach(() => {
+ process.env.GCP_RECONSTRUCTION_KEY = 'test-key';
+ process.env.MODEL_TRIPOSPLAT_URL = WORKER;
+});
+afterEach(() => {
+ globalThis.fetch = realFetch;
+ delete process.env.MODEL_TRIPOSPLAT_URL;
+});
+
+const { createRegenProvider } = await import('../../api/_providers/gcp.js');
+
+describe('gcp provider: triposplat', () => {
+ it('is supported only when MODEL_TRIPOSPLAT_URL is set', () => {
+ expect(createRegenProvider().supportsMode('triposplat')).toBe(true);
+ delete process.env.MODEL_TRIPOSPLAT_URL;
+ expect(createRegenProvider().supportsMode('triposplat')).toBe(false);
+ });
+
+ it('posts the image and density to /infer and reports one conditioning view', async () => {
+ const fetchMock = vi.fn(async () => new Response(JSON.stringify({ task_id: 't-1', status: 'queued' }), { status: 202 }));
+ globalThis.fetch = fetchMock;
+ const job = await createRegenProvider().submit({
+ mode: 'triposplat',
+ sourceUrl: 'https://example.com/a.png',
+ params: { num_gaussians: 65536 },
+ });
+ const [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe(`${WORKER}/infer`);
+ expect(JSON.parse(init.body)).toEqual({ images: ['https://example.com/a.png'], num_gaussians: 65536 });
+ expect(job.viewsUsed).toBe(1);
+ expect(job.eta).toBe(45);
+ });
+
+ it('maps a done task to the splat, ply and count', async () => {
+ let extJobId;
+ globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({ task_id: 't-2' }), { status: 202 }));
+ const provider = createRegenProvider();
+ ({ extJobId } = await provider.submit({ mode: 'triposplat', sourceUrl: 'https://example.com/a.png', params: {} }));
+ globalThis.fetch = vi.fn(async () =>
+ new Response(
+ JSON.stringify({
+ task_id: 't-2',
+ status: 'done',
+ splat_url: 'https://storage.googleapis.com/b/t.splat',
+ ply_url: 'https://storage.googleapis.com/b/t.ply',
+ num_gaussians: 65536,
+ }),
+ { status: 200 },
+ ),
+ );
+ const out = await provider.status(extJobId);
+ expect(out).toMatchObject({
+ status: 'done',
+ resultSplatUrl: 'https://storage.googleapis.com/b/t.splat',
+ plyUrl: 'https://storage.googleapis.com/b/t.ply',
+ numGaussians: 65536,
+ });
+ expect(out.resultGlbUrl).toBeUndefined();
+ });
+});
diff --git a/workers/model-triposplat/Dockerfile b/workers/model-triposplat/Dockerfile
new file mode 100644
index 000000000..14658886f
--- /dev/null
+++ b/workers/model-triposplat/Dockerfile
@@ -0,0 +1,32 @@
+FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
+
+# TripoSplat is not a pip package: clone the MIT repo to /opt/triposplat and put
+# it on the path. Its only deps are numpy, safetensors, pillow, tqdm and torch.
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PIP_NO_CACHE_DIR=1 \
+ DEBIAN_FRONTEND=noninteractive \
+ TRIPOSPLAT_REPO=/opt/triposplat
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ python3.10 python3-pip git curl libgl1 libglib2.0-0 \
+ && rm -rf /var/lib/apt/lists/* \
+ && ln -sf /usr/bin/python3.10 /usr/bin/python3 \
+ && ln -sf /usr/bin/python3.10 /usr/bin/python \
+ && pip install --upgrade pip setuptools wheel
+
+RUN pip install torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu121
+
+RUN git clone --depth 1 https://github.com/VAST-AI-Research/TripoSplat.git /opt/triposplat
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install -r /app/requirements.txt
+
+WORKDIR /app
+COPY worker_security.py splat_prep.py main.py test_splat_prep.py /app/
+
+# Build-time guard: input decoding, density bounds and output naming must pass.
+RUN python /app/test_splat_prep.py
+
+EXPOSE 8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1", "--timeout-keep-alive", "300"]
diff --git a/workers/model-triposplat/cloudbuild.yaml b/workers/model-triposplat/cloudbuild.yaml
new file mode 100644
index 000000000..76263ff40
--- /dev/null
+++ b/workers/model-triposplat/cloudbuild.yaml
@@ -0,0 +1,72 @@
+# Builds run as the pinned three-ws-build service account: the project's default
+# compute service account was deleted, so an unpinned submit fails with
+# "Unknown service account".
+serviceAccount: projects/aerial-vehicle-466722-p5/serviceAccounts/[email protected]
+
+substitutions:
+ _REGION: us-central1
+ _RUN_SA: avatar-reconstruction-sa@aerial-vehicle-466722-p5.iam.gserviceaccount.com
+ _SERVICE: model-triposplat
+ _REPO: model-triposplat
+ _GCS_BUCKET: three-ws-avatar-reconstructions
+ _WEIGHTS_BUCKET: three-ws-model-weights
+ _MIN_INSTANCES: "0"
+ _MAX_INSTANCES: "2"
+
+steps:
+ - id: build
+ name: gcr.io/cloud-builders/docker
+ dir: workers/model-triposplat
+ args:
+ - build
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+ - --cache-from
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+ - .
+
+ - id: push
+ name: gcr.io/cloud-builders/docker
+ args:
+ - push
+ - --all-tags
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server
+
+ - id: deploy
+ name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
+ entrypoint: gcloud
+ args:
+ - run
+ - deploy
+ - ${_SERVICE}
+ - --image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - --region=${_REGION}
+ - --service-account=${_RUN_SA}
+ - --platform=managed
+ - --port=8080
+ - --gpu=1
+ - --gpu-type=nvidia-l4
+ - --no-gpu-zonal-redundancy
+ - --no-cpu-throttling
+ - --cpu=4
+ - --memory=16Gi
+ - --min-instances=${_MIN_INSTANCES}
+ - --max-instances=${_MAX_INSTANCES}
+ - --timeout=900
+ - --allow-unauthenticated
+ - --add-volume=name=weights,type=cloud-storage,bucket=${_WEIGHTS_BUCKET}
+ - --add-volume-mount=volume=weights,mount-path=/weights
+ - --set-env-vars=GCS_BUCKET=${_GCS_BUCKET},WEIGHTS_DIR=/weights/triposplat,MAX_CONCURRENT=1
+ - --set-secrets=API_KEY=avatar-reconstruction-key:latest
+
+images:
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+
+options:
+ machineType: E2_HIGHCPU_8
+ logging: CLOUD_LOGGING_ONLY
+
+timeout: 1800s
diff --git a/workers/model-triposplat/main.py b/workers/model-triposplat/main.py
new file mode 100644
index 000000000..7ab0357a7
--- /dev/null
+++ b/workers/model-triposplat/main.py
@@ -0,0 +1,277 @@
+"""
+TripoSplat inference service: one image to a 3D Gaussian splat
+(VAST-AI-Research/TripoSplat, MIT code and weights).
+
+The Forge "Image to splat" lane behind /api/forge-splat. Unlike the mesh
+workers it returns a splat (.ply plus a compact .splat), which the Splat Viewer
+(src/splat-viewer.js, Spark) renders directly.
+
+API contract (same task shape as the other GPU workers):
+ POST /infer { images: [data-uri|https url], num_gaussians?: int, job_id?: str }
+ -> 202 { task_id, status: "queued" }
+ GET /tasks/:id -> { task_id, status, result_gcs_url?, ply_url?, splat_url?,
+ num_gaussians?, elapsed_ms?, error? }
+ GET /health -> { ok, model, gpu_available, load_error, load_attempts }
+ GET / -> unauthenticated descriptor for the platform warmth probe.
+
+Weights: gs://three-ws-model-weights/triposplat (stage-assets.sh), mounted at
+/weights. Environment: API_KEY, GCS_BUCKET, WEIGHTS_DIR, MAX_CONCURRENT.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import tempfile
+import time
+import uuid
+from contextlib import asynccontextmanager
+from typing import Optional
+
+import torch
+from fastapi import BackgroundTasks, FastAPI, Header, HTTPException, Response
+from google.api_core.exceptions import NotFound
+from google.cloud import storage
+from pydantic import BaseModel, Field
+
+from splat_prep import clamp_gaussians, decode_image, splat_blob_name, splat_public_url
+from worker_security import UnsafeUrlError, fetch_remote_bytes, require_api_key, safe_error
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+log = logging.getLogger("model-triposplat")
+
+API_KEY = os.environ["API_KEY"]
+GCS_BUCKET = os.environ["GCS_BUCKET"]
+WEIGHTS_DIR = os.environ.get("WEIGHTS_DIR", "/weights/triposplat")
+REPO_DIR = os.environ.get("TRIPOSPLAT_REPO", "/opt/triposplat")
+MAX_CONCURRENT = int(os.environ.get("MAX_CONCURRENT", "1"))
+MODEL_LOAD_ATTEMPTS = int(os.environ.get("MODEL_LOAD_ATTEMPTS", "4"))
+MODEL_LOAD_RETRY_BASE_S = float(os.environ.get("MODEL_LOAD_RETRY_BASE_S", "15"))
+
+_pipe = None
+_bucket: Optional[storage.Bucket] = None
+_sem: Optional[asyncio.Semaphore] = None
+_ready: Optional[asyncio.Event] = None
+_load_error: Optional[str] = None
+_load_attempts = 0
+_tasks: dict[str, dict] = {}
+_task_locks: dict[str, asyncio.Lock] = {}
+_TERMINAL = frozenset({"done", "failed"})
+
+
+def _load_pipeline_sync() -> None:
+ global _pipe
+ if REPO_DIR not in sys.path:
+ sys.path.insert(0, REPO_DIR)
+ from triposplat import TripoSplatPipeline
+
+ w = WEIGHTS_DIR
+ log.info("Loading TripoSplat from %s", w)
+ _pipe = TripoSplatPipeline(
+ ckpt_path=f"{w}/diffusion_models/triposplat_fp16.safetensors",
+ decoder_path=f"{w}/vae/triposplat_vae_decoder_fp16.safetensors",
+ dinov3_path=f"{w}/clip_vision/dino_v3_vit_h.safetensors",
+ flux2_vae_encoder_path=f"{w}/vae/flux2-vae.safetensors",
+ rmbg_path=f"{w}/background_removal/birefnet.safetensors",
+ device="cuda",
+ )
+
+
+async def _load_pipeline_bg() -> None:
+ """Load off the request path, retrying with backoff before latching a failure."""
+ global _load_error, _load_attempts
+ loop = asyncio.get_event_loop()
+ for attempt in range(1, max(1, MODEL_LOAD_ATTEMPTS) + 1):
+ _load_attempts = attempt
+ try:
+ await loop.run_in_executor(None, _load_pipeline_sync)
+ _load_error = None
+ _ready.set()
+ return
+ except Exception as exc: # noqa: BLE001 - surfaced via /health + task status
+ if attempt >= MODEL_LOAD_ATTEMPTS:
+ _load_error = safe_error(exc, context="model load")
+ log.error("TripoSplat load FAILED after %d attempt(s): %s", attempt, exc)
+ return
+ delay = MODEL_LOAD_RETRY_BASE_S * (2 ** (attempt - 1))
+ log.warning("TripoSplat load attempt %d failed (%s); retrying in %.0fs", attempt, exc, delay)
+ await asyncio.sleep(delay)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ global _bucket, _sem, _ready
+ _bucket = storage.Client().bucket(GCS_BUCKET)
+ _sem = asyncio.Semaphore(MAX_CONCURRENT)
+ _ready = asyncio.Event()
+ asyncio.create_task(_load_pipeline_bg())
+ yield
+
+
+app = FastAPI(title="model-triposplat", lifespan=lifespan)
+
+
+def _require_api_key(authorization: str) -> None:
+ try:
+ require_api_key(authorization, API_KEY)
+ except PermissionError as exc:
+ raise HTTPException(status_code=401, detail=str(exc)) from exc
+
+
+def _fetch_image_bytes(url: str) -> bytes:
+ try:
+ return fetch_remote_bytes(url, timeout=30)
+ except UnsafeUrlError as exc:
+ raise ValueError(f"refused to fetch image source: {exc}") from exc
+
+
+def _task_blob(task_id: str):
+ return _bucket.blob(f"tasks/triposplat/{task_id}.json")
+
+
+async def _update_task(task_id: str, **fields) -> dict:
+ """Persist every transition to GCS: polls land on any instance."""
+ lock = _task_locks.setdefault(task_id, asyncio.Lock())
+ async with lock:
+ task = _tasks.setdefault(task_id, {"task_id": task_id})
+ task.update(fields)
+ task["updated_at"] = time.time()
+ payload = json.dumps(task)
+ await asyncio.get_event_loop().run_in_executor(
+ None, lambda: _task_blob(task_id).upload_from_string(payload, content_type="application/json")
+ )
+ return task
+
+
+async def _resolve_task(task_id: str) -> dict:
+ task = _tasks.get(task_id)
+ if task is not None and task.get("status") in _TERMINAL:
+ return task
+ try:
+ data = await asyncio.get_event_loop().run_in_executor(None, _task_blob(task_id).download_as_bytes)
+ except NotFound:
+ if task is not None:
+ return task
+ raise HTTPException(status_code=404, detail="task not found")
+ except Exception as exc:
+ raise HTTPException(status_code=502, detail=safe_error(exc, context="task lookup")) from exc
+ task = json.loads(data)
+ if task.get("status") in _TERMINAL:
+ _tasks[task_id] = task
+ return task
+
+
+def _generate_sync(image, num_gaussians: int) -> tuple[bytes, bytes]:
+ with torch.no_grad():
+ gaussian, _prepared = _pipe.run(image, num_gaussians=num_gaussians, show_progress=False)
+ with tempfile.TemporaryDirectory() as tmp:
+ ply, splat = os.path.join(tmp, "o.ply"), os.path.join(tmp, "o.splat")
+ gaussian.save_ply(ply)
+ gaussian.save_splat(splat)
+ with open(ply, "rb") as a, open(splat, "rb") as b:
+ return a.read(), b.read()
+
+
+async def _run_job(task_id: str, image_src: str, num_gaussians: int) -> None:
+ await _ready.wait()
+ async with _sem:
+ await _update_task(task_id, status="running")
+ loop = asyncio.get_event_loop()
+ t0 = time.time()
+ try:
+ image = await loop.run_in_executor(None, lambda: decode_image(image_src, fetch=_fetch_image_bytes))
+ ply_bytes, splat_bytes = await loop.run_in_executor(None, _generate_sync, image, num_gaussians)
+
+ urls = {}
+ for ext, data in (("ply", ply_bytes), ("splat", splat_bytes)):
+ name = splat_blob_name(task_id, ext)
+ await loop.run_in_executor(
+ None,
+ lambda n=name, d=data: _bucket.blob(n).upload_from_string(d, content_type="application/octet-stream"),
+ )
+ urls[ext] = splat_public_url(GCS_BUCKET, name)
+
+ await _update_task(
+ task_id,
+ status="done",
+ result_gcs_url=urls["splat"],
+ splat_url=urls["splat"],
+ ply_url=urls["ply"],
+ num_gaussians=num_gaussians,
+ elapsed_ms=int((time.time() - t0) * 1000),
+ )
+ log.info("[%s] done in %.1fs, %d gaussians", task_id, time.time() - t0, num_gaussians)
+ except Exception as exc: # noqa: BLE001
+ is_input = isinstance(exc, ValueError)
+ await _update_task(
+ task_id,
+ status="failed",
+ error=str(exc) if is_input else safe_error(exc, context=f"[{task_id}] inference"),
+ error_kind="input" if is_input else "internal",
+ elapsed_ms=int((time.time() - t0) * 1000),
+ )
+ finally:
+ if torch.cuda.is_available():
+ torch.cuda.empty_cache()
+
+
+class InferRequest(BaseModel):
+ images: list[str] = Field(..., min_length=1, max_length=6)
+ num_gaussians: int | None = None
+ job_id: str | None = None
+
+
[email protected]("/infer", status_code=202)
+async def infer(body: InferRequest, background_tasks: BackgroundTasks, authorization: str = Header(...)) -> dict:
+ _require_api_key(authorization)
+ if _load_error:
+ raise HTTPException(status_code=503, detail=f"pipeline unavailable: {_load_error}")
+ try:
+ count = clamp_gaussians(body.num_gaussians)
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ task_id = str(uuid.uuid4())
+ await _update_task(task_id, status="queued", model="triposplat")
+ # TripoSplat conditions on a single image; extra frames are accepted and ignored.
+ background_tasks.add_task(_run_job, task_id, body.images[0], count)
+ return {"task_id": task_id, "status": "queued"}
+
+
[email protected]("/tasks/{task_id}")
+async def get_task(task_id: str, authorization: str = Header(...)) -> dict:
+ _require_api_key(authorization)
+ try:
+ uuid.UUID(task_id)
+ except ValueError as exc:
+ raise HTTPException(status_code=404, detail="task not found") from exc
+ return await _resolve_task(task_id)
+
+
+async def root() -> dict:
+ return {
+ "service": "model-triposplat",
+ "model": "triposplat",
+ "ready": bool(_ready and _ready.is_set()),
+ "endpoints": ["POST /infer", "GET /tasks/{task_id}", "GET /health"],
+ }
+
+
+async def health(response: Response) -> dict:
+ dead = _load_error is not None
+ if dead:
+ response.status_code = 503
+ return {
+ "ok": not dead,
+ "model": "triposplat",
+ "gpu_available": torch.cuda.is_available(),
+ "gpu_name": torch.cuda.get_device_name(0) if torch.cuda.is_available() else None,
+ "pipeline_loaded": _pipe is not None,
+ "ready": bool(_ready and _ready.is_set()),
+ "load_error": _load_error,
+ "load_attempts": _load_attempts,
+ }
diff --git a/workers/model-triposplat/requirements.txt b/workers/model-triposplat/requirements.txt
new file mode 100644
index 000000000..b1f29ccee
--- /dev/null
+++ b/workers/model-triposplat/requirements.txt
@@ -0,0 +1,11 @@
+# TripoSplat's own deps (numpy, safetensors, pillow, tqdm) plus torch from the Dockerfile.
+numpy
+safetensors
+Pillow>=10.3.0
+tqdm
+
+fastapi==0.115.0
+uvicorn[standard]==0.32.0
+pydantic>=2.0.0
+httpx>=0.27.0
+google-cloud-storage==2.18.0
diff --git a/workers/model-triposplat/splat_prep.py b/workers/model-triposplat/splat_prep.py
new file mode 100644
index 000000000..9fd186559
--- /dev/null
+++ b/workers/model-triposplat/splat_prep.py
@@ -0,0 +1,78 @@
+"""
+Pure helpers for the TripoSplat worker: input decoding, density validation and
+output naming. Free of torch, FastAPI and google-cloud so the whole pre-inference
+path runs on a CPU box and gates the Docker build (see test_splat_prep.py).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+from typing import Callable
+
+from PIL import Image, UnidentifiedImageError
+
+# Upstream caps a scene at 262,144 Gaussians (README); 8,192 is the floor below
+# which the decoder output stops resembling the subject.
+MIN_GAUSSIANS = 8192
+MAX_GAUSSIANS = 262144
+DEFAULT_GAUSSIANS = 131072
+BLOB_PREFIX = "raw-splats/triposplat"
+MAX_IMAGE_BYTES = 25 * 1024 * 1024
+
+
+def decode_data_uri(src: str) -> bytes:
+ if "," not in src:
+ raise ValueError("malformed data URI: no payload separator")
+ header, payload = src.split(",", 1)
+ if "base64" not in header:
+ raise ValueError("unsupported data URI: only base64 payloads are accepted")
+ try:
+ return base64.b64decode(payload, validate=True)
+ except (binascii.Error, ValueError) as exc:
+ raise ValueError("malformed data URI: payload is not valid base64") from exc
+
+
+def open_rgba(data: bytes) -> Image.Image:
+ if len(data) > MAX_IMAGE_BYTES:
+ raise ValueError("image is larger than the 25 MB limit")
+ try:
+ return Image.open(io.BytesIO(data)).convert("RGBA")
+ except (UnidentifiedImageError, OSError) as exc:
+ raise ValueError("image bytes could not be decoded") from exc
+
+
+def decode_image(src: str, *, fetch: Callable[[str], bytes]) -> Image.Image:
+ """One caller-supplied image source to an RGBA image.
+
+ ``data:image/...`` URIs decode in-process; ``https://`` URLs go through
+ ``fetch`` (the SSRF-hardened fetcher in worker_security). Anything else is
+ refused before it can reach the network.
+ """
+ if src.startswith("data:image"):
+ return open_rgba(decode_data_uri(src))
+ if src.startswith("https://"):
+ return open_rgba(fetch(src))
+ raise ValueError(f"unsupported image source: {src[:60]}")
+
+
+def clamp_gaussians(value: int | None) -> int:
+ """Validate a requested Gaussian count; None selects the default."""
+ if value is None:
+ return DEFAULT_GAUSSIANS
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise ValueError("num_gaussians must be an integer")
+ if value < MIN_GAUSSIANS or value > MAX_GAUSSIANS:
+ raise ValueError(f"num_gaussians must be between {MIN_GAUSSIANS} and {MAX_GAUSSIANS}")
+ return value
+
+
+def splat_blob_name(task_id: str, ext: str) -> str:
+ if ext not in ("ply", "splat"):
+ raise ValueError("unsupported splat extension")
+ return f"{BLOB_PREFIX}/{task_id}.{ext}"
+
+
+def splat_public_url(bucket: str, blob_name: str) -> str:
+ return f"https://storage.googleapis.com/{bucket}/{blob_name}"
diff --git a/workers/model-triposplat/stage-assets.sh b/workers/model-triposplat/stage-assets.sh
new file mode 100755
index 000000000..a1526d67d
--- /dev/null
+++ b/workers/model-triposplat/stage-assets.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Stage TripoSplat weights (MIT, HF VAST-AI/TripoSplat) into the shared weights bucket.
+set -euo pipefail
+DEST="${WEIGHTS_BUCKET:-gs://three-ws-model-weights}/triposplat"
+TMP="$(mktemp -d)"
+python3 -m pip install -q huggingface_hub
+python3 -c "from huggingface_hub import snapshot_download; snapshot_download('VAST-AI/TripoSplat', local_dir='$TMP')"
+gcloud storage cp -r "$TMP"/* "$DEST/"
+rm -rf "$TMP"
+echo "staged to $DEST"
diff --git a/workers/model-triposplat/test_splat_prep.py b/workers/model-triposplat/test_splat_prep.py
new file mode 100644
index 000000000..972417370
--- /dev/null
+++ b/workers/model-triposplat/test_splat_prep.py
@@ -0,0 +1,56 @@
+"""Build-time guard for the pre-inference path. Run: python test_splat_prep.py"""
+
+import base64
+import io
+import unittest
+
+from PIL import Image
+
+import splat_prep as sp
+
+
+def _png_uri(mode="RGBA", size=(8, 8)):
+ buf = io.BytesIO()
+ Image.new(mode, size, (200, 10, 10, 255)[: len(mode)]).save(buf, format="PNG")
+ return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+
+
+class SplatPrepTests(unittest.TestCase):
+ def test_data_uri_decodes_to_rgba(self):
+ img = sp.decode_image(_png_uri("RGB"), fetch=lambda u: b"")
+ self.assertEqual(img.mode, "RGBA")
+ self.assertEqual(img.size, (8, 8))
+
+ def test_https_goes_through_fetch(self):
+ raw = base64.b64decode(_png_uri().split(",", 1)[1])
+ seen = []
+ img = sp.decode_image("https://example.com/a.png", fetch=lambda u: seen.append(u) or raw)
+ self.assertEqual(seen, ["https://example.com/a.png"])
+ self.assertEqual(img.size, (8, 8))
+
+ def test_other_schemes_never_reach_fetch(self):
+ for src in ("http://example.com/a.png", "file:///etc/passwd", "gs://b/o", "ftp://x/y"):
+ with self.assertRaises(ValueError):
+ sp.decode_image(src, fetch=lambda u: self.fail("fetch called"))
+
+ def test_malformed_payloads_rejected(self):
+ for src in ("data:image/png;base64,!!!", "data:image/png,abc", "data:image/png;base64,AAAA"):
+ with self.assertRaises(ValueError):
+ sp.decode_image(src, fetch=lambda u: b"")
+
+ def test_gaussian_bounds(self):
+ self.assertEqual(sp.clamp_gaussians(None), sp.DEFAULT_GAUSSIANS)
+ self.assertEqual(sp.clamp_gaussians(262144), 262144)
+ for bad in (0, 8191, 262145, True, "9000", 9000.5):
+ with self.assertRaises(ValueError):
+ sp.clamp_gaussians(bad)
+
+ def test_blob_names(self):
+ self.assertEqual(sp.splat_blob_name("t1", "ply"), "raw-splats/triposplat/t1.ply")
+ with self.assertRaises(ValueError):
+ sp.splat_blob_name("t1", "exe")
+ self.assertEqual(sp.splat_public_url("b", "x/y.ply"), "https://storage.googleapis.com/b/x/y.ply")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/workers/model-triposplat/worker_security.py b/workers/model-triposplat/worker_security.py
new file mode 100644
index 000000000..802e1c32d
--- /dev/null
+++ b/workers/model-triposplat/worker_security.py
@@ -0,0 +1,320 @@
+"""
+Shared security helpers for the three.ws GPU/CPU workers.
+
+This module is intentionally dependency-light (stdlib only) so it can be
+COPYed verbatim into every worker's Docker build context. The same canonical
+file lives in each worker directory; keep them byte-identical when editing.
+
+It provides three primitives that every worker needs:
+
+ 1. ``require_api_key`` - constant-time bearer-token check (timing-safe).
+ 2. ``fetch_remote_bytes`` - SSRF-hardened HTTP(S) fetch of caller-supplied
+ URLs: https-only, DNS resolution with private/loopback/link-local/metadata
+ IP rejection, per-hop redirect re-validation, and a bounded response size.
+ 3. ``safe_error`` - turns an exception into an opaque, correlation-id-tagged
+ message safe to persist/return to callers, after logging the full
+ traceback server-side only.
+"""
+
+from __future__ import annotations
+
+import hmac
+import ipaddress
+import logging
+import asyncio
+import socket
+import time
+import uuid
+from typing import Iterable, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+log = logging.getLogger("worker_security")
+
+# ── auth ────────────────────────────────────────────────────────────────────────
+
+
+def require_api_key(authorization: Optional[str], api_key: str) -> None:
+ """Validate a ``Bearer <token>`` header in constant time.
+
+ Raises ``PermissionError`` on any failure so callers can translate it into
+ the framework's 401 (FastAPI workers map this to HTTPException(401)).
+ """
+ # Fail closed on an empty configured key: with api_key == "" a bare
+ # "Bearer " header would otherwise strip to "" and compare equal.
+ if not api_key:
+ raise PermissionError("worker api key not configured")
+ if not authorization or not authorization.startswith("Bearer "):
+ raise PermissionError("missing bearer token")
+ token = authorization[len("Bearer "):].strip()
+ if not token:
+ raise PermissionError("missing bearer token")
+ # Compare bytes: hmac.compare_digest is timing-safe, and on str operands it
+ # raises TypeError for non-ASCII input, which would surface as a 500.
+ if not hmac.compare_digest(token.encode("utf-8"), api_key.encode("utf-8")):
+ raise PermissionError("invalid api key")
+
+
+# ── SSRF-hardened fetch ─────────────────────────────────────────────────────────
+
+# Default cap on a fetched response. Avatar selfies / driving audio / raw meshes
+# are comfortably under this; anything larger is almost certainly abuse.
+DEFAULT_MAX_BYTES = 64 * 1024 * 1024 # 64 MiB
+_MAX_REDIRECTS = 4
+
+# Transient fetch failures are retried: a dropped connection, a timeout, or a
+# 429/5xx from the image host. The public R2 dev endpoint that serves every
+# forge reference image drops connections under load ("Server disconnected
+# without sending a response"), and before this retry each drop ended a
+# generation as an opaque internal error on TripoSG and Hunyuan3D (about 20 a
+# week measured 2026-10-09). Refusals (UnsafeUrlError), oversize bodies, and
+# other 4xx answers are final and never retried.
+_FETCH_ATTEMPTS = 3
+_FETCH_BACKOFF_SECS = (0.5, 1.5)
+
+# Hosts that enforce a User-Agent policy refuse httpx's default
+# "python-httpx/<version>": upload.wikimedia.org answers it with 403 Forbidden
+# and serves the same image to a descriptive agent (measured 2026-10-09, when
+# model-triposg failed every job whose reference photo was a Wikimedia link).
+# Callers may still pass their own User-Agent; it replaces this one.
+DEFAULT_USER_AGENT = "three.ws-worker/1.0 (+https://three.ws)"
+
+
+def _fetch_headers(headers: Optional[dict]) -> dict:
+ """Caller headers over the default User-Agent, matched case-insensitively."""
+ merged = dict(headers or {})
+ if not any(str(k).lower() == "user-agent" for k in merged):
+ merged["User-Agent"] = DEFAULT_USER_AGENT
+ return merged
+
+
+class UnsafeUrlError(ValueError):
+ """Raised when a URL targets a disallowed scheme or a private/internal IP."""
+
+
+def _is_blocked_ip(ip: ipaddress._BaseAddress) -> bool:
+ """Reject any address that could reach internal infrastructure.
+
+ Covers loopback, RFC1918 private ranges, link-local (incl. the cloud
+ metadata server at 169.254.169.254), unique-local IPv6 (fc00::/7),
+ multicast, reserved, unspecified, and any other non-global address (CGNAT
+ 100.64.0.0/10 included). IPv4-mapped IPv6 addresses
+ are unwrapped first so a mapped private v4 can't slip through.
+ """
+ if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+ ip = ip.ipv4_mapped
+ return (
+ ip.is_private
+ or ip.is_loopback
+ or ip.is_link_local
+ or ip.is_multicast
+ or ip.is_reserved
+ or ip.is_unspecified
+ # Anything not globally routable, which also covers the CGNAT shared
+ # space 100.64.0.0/10 that is_private does not flag.
+ or not ip.is_global
+ )
+
+
+def _resolve_safe_host(host: str) -> None:
+ """DNS-resolve ``host`` and raise UnsafeUrlError if ANY address is internal.
+
+ Resolving and checking every returned address closes the gap where a name
+ resolves to both a public and a private address.
+ """
+ if not host:
+ raise UnsafeUrlError("missing host")
+ try:
+ infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+ except socket.gaierror as exc:
+ raise UnsafeUrlError(f"could not resolve host: {host}") from exc
+
+ addrs = {info[4][0] for info in infos}
+ if not addrs:
+ raise UnsafeUrlError(f"no addresses for host: {host}")
+ for addr in addrs:
+ ip = ipaddress.ip_address(addr)
+ if _is_blocked_ip(ip):
+ raise UnsafeUrlError(f"host resolves to a disallowed address: {host}")
+
+
+def assert_safe_url(url: str, *, allow_http: bool = False) -> str:
+ """Validate scheme + resolved IPs for a single URL. Returns it unchanged.
+
+ https is required by default; ``allow_http`` exists only for callers that
+ legitimately need cleartext (not used by the workers).
+ """
+ parts = urlsplit(url)
+ scheme = parts.scheme.lower()
+ allowed = ("https", "http") if allow_http else ("https",)
+ if scheme not in allowed:
+ raise UnsafeUrlError(f"scheme not allowed: {scheme or '(none)'}")
+ if not parts.hostname:
+ raise UnsafeUrlError("missing host")
+ _resolve_safe_host(parts.hostname)
+ return url
+
+
+def fetch_remote_bytes(
+ url: str,
+ *,
+ timeout: float = 30.0,
+ max_bytes: int = DEFAULT_MAX_BYTES,
+ allow_http: bool = False,
+ headers: Optional[dict] = None,
+) -> bytes:
+ """Fetch ``url`` safely and return its body bytes.
+
+ Hardening applied:
+ * https-only (unless ``allow_http``).
+ * every URL - including each redirect target - is DNS-resolved and
+ rejected if it maps to a private/loopback/link-local/metadata address.
+ * redirects are followed manually (max ``_MAX_REDIRECTS``) so each hop is
+ re-validated; httpx's own redirect following is disabled.
+ * the response body is streamed and aborted once it exceeds ``max_bytes``.
+ * transient failures (dropped connection, timeout, 429/5xx) are retried
+ with a short backoff; see ``_FETCH_ATTEMPTS``.
+
+ Raises ``UnsafeUrlError`` for disallowed targets and ``httpx.HTTPError`` /
+ ``ValueError`` for transport or size failures.
+ """
+ for attempt in range(_FETCH_ATTEMPTS - 1):
+ try:
+ return _fetch_once(
+ url, timeout=timeout, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ if not _is_transient(exc):
+ raise
+ log.warning("transient fetch failure (attempt %d): %s", attempt + 1, type(exc).__name__)
+ time.sleep(_FETCH_BACKOFF_SECS[attempt])
+ return _fetch_once(
+ url, timeout=timeout, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+
+
+def _is_transient(exc: httpx.HTTPError) -> bool:
+ if isinstance(exc, httpx.HTTPStatusError):
+ code = exc.response.status_code
+ return code == 429 or code >= 500
+ return isinstance(exc, httpx.TransportError)
+
+
+def _fetch_once(
+ url: str,
+ *,
+ timeout: float,
+ max_bytes: int,
+ allow_http: bool,
+ headers: Optional[dict],
+) -> bytes:
+ current = assert_safe_url(url, allow_http=allow_http)
+ with httpx.Client(follow_redirects=False, timeout=timeout) as client:
+ for _ in range(_MAX_REDIRECTS + 1):
+ with client.stream("GET", current, headers=_fetch_headers(headers)) as resp:
+ if resp.is_redirect:
+ location = resp.headers.get("location")
+ if not location:
+ raise UnsafeUrlError("redirect without Location header")
+ current = assert_safe_url(
+ str(resp.url.join(location)), allow_http=allow_http
+ )
+ continue
+ resp.raise_for_status()
+ declared = resp.headers.get("content-length")
+ if declared is not None and declared.isdigit() and int(declared) > max_bytes:
+ raise ValueError(f"response too large: {declared} bytes")
+ chunks: list[bytes] = []
+ total = 0
+ for chunk in resp.iter_bytes(65536):
+ total += len(chunk)
+ if total > max_bytes:
+ raise ValueError(f"response exceeded {max_bytes} bytes")
+ chunks.append(chunk)
+ return b"".join(chunks)
+ raise UnsafeUrlError(f"too many redirects (>{_MAX_REDIRECTS})")
+
+
+async def fetch_remote_bytes_async(
+ client: "httpx.AsyncClient",
+ url: str,
+ *,
+ max_bytes: int = DEFAULT_MAX_BYTES,
+ allow_http: bool = False,
+ headers: Optional[dict] = None,
+) -> bytes:
+ """Async variant of ``fetch_remote_bytes`` using a caller-provided client.
+
+ The provided ``client`` MUST be constructed with ``follow_redirects=False``
+ so this function can re-validate each redirect hop itself. Transient
+ failures are retried exactly as in the sync variant.
+ """
+ for attempt in range(_FETCH_ATTEMPTS - 1):
+ try:
+ return await _fetch_once_async(
+ client, url, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ if not _is_transient(exc):
+ raise
+ log.warning("transient fetch failure (attempt %d): %s", attempt + 1, type(exc).__name__)
+ await asyncio.sleep(_FETCH_BACKOFF_SECS[attempt])
+ return await _fetch_once_async(
+ client, url, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+
+
+async def _fetch_once_async(
+ client: "httpx.AsyncClient",
+ url: str,
+ *,
+ max_bytes: int,
+ allow_http: bool,
+ headers: Optional[dict],
+) -> bytes:
+ current = assert_safe_url(url, allow_http=allow_http)
+ for _ in range(_MAX_REDIRECTS + 1):
+ async with client.stream("GET", current, headers=_fetch_headers(headers)) as resp:
+ if resp.is_redirect:
+ location = resp.headers.get("location")
+ if not location:
+ raise UnsafeUrlError("redirect without Location header")
+ current = assert_safe_url(
+ str(resp.url.join(location)), allow_http=allow_http
+ )
+ continue
+ resp.raise_for_status()
+ declared = resp.headers.get("content-length")
+ if declared is not None and declared.isdigit() and int(declared) > max_bytes:
+ raise ValueError(f"response too large: {declared} bytes")
+ chunks: list[bytes] = []
+ total = 0
+ async for chunk in resp.aiter_bytes(65536):
+ total += len(chunk)
+ if total > max_bytes:
+ raise ValueError(f"response exceeded {max_bytes} bytes")
+ chunks.append(chunk)
+ return b"".join(chunks)
+ raise UnsafeUrlError(f"too many redirects (>{_MAX_REDIRECTS})")
+
+
+# ── opaque error handling ───────────────────────────────────────────────────────
+
+
+def safe_error(exc: BaseException, *, context: str = "") -> str:
+ """Log the full traceback server-side and return an opaque client message.
+
+ Never leak ``traceback.format_exc()`` (absolute paths, library versions,
+ internal hostnames, fragments of upstream responses) to callers. A short
+ correlation id is embedded in both the log line and the returned string so
+ operators can join a client-reported failure to the server log.
+ """
+ correlation_id = uuid.uuid4().hex[:12]
+ label = f"{context} " if context else ""
+ log.exception("%serror [correlation_id=%s]", label, correlation_id)
+ return f"internal error (ref {correlation_id})"