Tools Route Split Plan

Status: completed for public nginx split, started 2026-06-12. Goal: remove /api/platform/tools/* -> Dell as a control-plane exception without breaking R/Python execution, result files, or public demo assets.

Current Rule

Known /api/platform/tools/* routes terminate at ECS platform. ECS calls Dell only through internal-token routes for execution, local process control, result files, demo input files, and public demo assets.

The old broad Dell-backed route is intentionally closed with 404 so unknown public tools paths do not silently make Dell a platform gateway again.

Endpoint Ownership

Endpoint	Class	Owner Now	Target Owner	Notes
GET /api/tools/history	Metadata	ECS platform	ECS platform	Reads tool_jobs from PostgreSQL only. First narrow nginx cut.
GET /api/tools/status/:id	Metadata + result JSON	ECS platform	ECS platform	Reads tool_jobs.result_json; user result file URLs are served by the ECS -> Dell internal private file proxy.
PUT /api/tools/job/:id/name	Metadata	ECS platform	ECS platform	Served by the job regex nginx cut.
PUT /api/tools/job/:id/public	Metadata/admin	ECS platform	ECS platform	Second narrow nginx cut. Immutable public demo asset fallback remains Dell-backed through /public-demo and /public-file.
POST /api/tools/cancel/:id	Control	ECS platform -> Dell internal	ECS platform -> Dell internal	ECS checks owner/admin and marks tool_jobs cancelled; Dell internal stops any active local process best-effort.
DELETE /api/tools/job/:id	Mixed metadata + file cleanup	ECS platform -> Dell internal	ECS platform -> Dell internal	ECS checks owner/admin, preserves public-demo guard, asks Dell to remove local output, then deletes the PG row. Immutable public demo asset dirs are protected from local deletion.
POST /api/tools/run	Execution submit	ECS platform -> Dell internal	ECS platform -> Dell internal or worker queue	ECS owns public auth/module gating. Dell internal receives original user context, writes job dirs, inserts tool_jobs, and starts local execution.
GET /api/tools/file/:jobId/:filename	Private file serving	ECS platform -> Dell internal	ECS platform -> Dell internal	ECS checks tool_jobs owner/admin in PostgreSQL, then streams Dell-local result files through internal-token routes.
PUT /api/tools/file/:jobId/:filename	File write	ECS platform -> Dell internal	ECS platform -> Dell internal	ECS checks owner/admin, then writes Dell-local plot/report files through internal-token routes; raw body is preserved for FigCode image/code saves.
GET /api/tools/public-demo/:toolId	Public demo	ECS platform -> Dell internal	ECS platform -> Dell internal	ECS authenticates routing boundary, then uses BIOF3_INTERNAL_TOKEN to read Dell asset/job metadata.
GET /api/tools/public-file/:jobId/:filename	Public file serving	ECS platform -> Dell internal	ECS platform -> Dell internal	Streams immutable public demo job output from Dell disk via ECS platform.
GET /api/tools/demo/:toolId	Legacy static	ECS platform -> Dell internal	Retire or asset manifest	Compatibility path for old fallback URLs; main UI uses public-demo.
GET /api/tools/demo/:toolId/:filename	Legacy static file	ECS platform -> Dell internal	Retire or asset manifest	Compatibility path for old fallback URLs; disabled when static demo dirs are disabled.
GET /api/tools/demo-data/:toolId/:filename	Demo input file	ECS platform -> Dell internal	ECS static asset or Dell proxy	Used by the form "example data" loader; now proxied through ECS while files remain on Dell.

Current Public Cuts

Nginx adds narrow locations before the broad tools route:

location = /api/platform/tools/history { ... -> ECS :3011/api/tools/history }
location /api/platform/tools/status/ { ... -> ECS :3011/api/tools/status/ }
location = /api/platform/tools/run { ... -> ECS :3011/api/tools/run -> Dell internal }
location ~ ^/api/platform/tools/job/[^/]+(/(name|public))?$ { ... -> ECS :3011 -> Dell internal for DELETE }
location /api/platform/tools/public-demo/ { ... -> ECS :3011 -> Dell internal }
location /api/platform/tools/public-file/ { ... -> ECS :3011 -> Dell internal }
location /api/platform/tools/demo-data/ { ... -> ECS :3011 -> Dell internal }
location /api/platform/tools/demo/ { ... -> ECS :3011 -> Dell internal }
location /api/platform/tools/file/ { ... -> ECS :3011 -> Dell internal }
location /api/platform/tools/cancel/ { ... -> ECS :3011 -> Dell internal }

The broad route is closed:

location /api/platform/tools/ { return 404; }

Known first-party routes must be represented explicitly above.

Validation

After deployment:

curl -sk -H 'X-API-Token: ...' https://biof3.com/api/platform/tools/history
curl -sk -X PUT -H 'X-API-Token: ...' -H 'Content-Type: application/json' \
  -d '{"name":"..."}' https://biof3.com/api/platform/tools/job/JOB_ID/name
curl -sk -H 'X-API-Token: ...' https://biof3.com/api/platform/tools/public-demo/deseq2
curl -sk -H 'X-API-Token: ...' https://biof3.com/api/platform/tools/demo/deseq2
curl -sk -X POST -H 'Authorization: Bearer ...' -H 'Content-Type: application/json' \
  -d '{"toolId":"deseq2","params":{},"files":{}}' \
  https://biof3.com/api/platform/tools/run
curl -skI -H 'X-API-Token: ...' \
  https://biof3.com/api/platform/tools/public-file/job_5c2047cb727e4d42/heatmap.png
curl -skI -H 'X-API-Token: ...' \
  https://biof3.com/api/platform/tools/file/JOB_ID/heatmap.png
curl -sk -X POST -H 'X-API-Token: ...' \
  https://biof3.com/api/platform/tools/cancel/JOB_ID
curl -sk -X DELETE -H 'X-API-Token: ...' \
  https://biof3.com/api/platform/tools/job/JOB_ID
curl -sk -H 'X-API-Token: ...' https://biof3.com/api/platform/admin/cache/stats
curl -sk -o /dev/null -w '%{http_code}\n' https://biof3.com/api/platform/tools/not-a-route

Expected:

• history returns 200 from ECS platform.
• job name/public metadata updates return 200 from ECS platform.
• public-demo/deseq2 returns source:"asset" through ECS -> Dell internal.
• legacy demo/deseq2 returns ECS -> Dell internal compatibility output (source:"none" or files depending on whether static demo dirs are enabled).
• run is accepted by ECS public auth/module gating and forwarded to Dell internal with the original user id; job ownership must not become __internal__.
• public-file/.../heatmap.png returns 200 image/png through ECS -> Dell internal.
• private tools/file/... returns the result file through ECS auth -> Dell internal; unauthorized users remain blocked by ECS before Dell disk access.
• cancel/JOB_ID returns cancelled from ECS auth -> Dell internal. If the job is not active locally, the response still succeeds with local.active=false.
• DELETE job/JOB_ID removes the PG row and returns Dell local cleanup details. Public demo asset directories are not removed even if their PG row is deleted.
• cache stats still returns real Dell cache data through ECS internal proxy.
• an unknown /api/platform/tools/* path returns 404 from nginx and does not proxy to Dell.

Deployment note:

• Dell biof3-r-server must be restarted with /etc/biof3.env loaded so BIOF3_INTERNAL_TOKEN reaches the PM2 child process. Otherwise internal /api/internal/tools/* routes return 401 even though the shell has the token.

Rollback

Replace the final location /api/platform/tools/ { return 404; } with the old Dell proxy block and reload nginx. If a specific cut must be rolled back, remove that narrow location too so it falls through to the restored Dell block.