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 TripoSplat gaussian-splat generation endpoint, GPU worker and provider
nirholas3bd57493dd7e
diff --git a/api/_providers/gcp.js b/api/_providers/gcp.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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 nudgediff --git a/tests/api/forge-splat.test.js b/tests/api/forge-splat.test.jsnew file mode 100644index 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.jsnew file mode 100644index 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/Dockerfilenew file mode 100644index 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.yamlnew file mode 100644index 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: 1800sdiff --git a/workers/model-triposplat/main.py b/workers/model-triposplat/main.pynew file mode 100644index 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)++[email protected]("/")+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"],+ }++[email protected]("/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.txtnew file mode 100644index 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.0diff --git a/workers/model-triposplat/splat_prep.py b/workers/model-triposplat/splat_prep.pynew file mode 100644index 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.shnew file mode 100755index 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.pynew file mode 100644index 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.pynew file mode 100644index 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})"