Files

T

Keysat 05d03beeeb docs: handoff — trim Current state, move full-eval debt to ROADMAP, record SSH-input + CSRF conventions

- AGENTS.md: rewrite Current state lean for v0.19.0:0; drop the now-completed
  full-eval triage block (history lives in git log + EVALUATION.md).
- docs/guides/fastapi-image.md: add two durable conventions — user values
  crossing into SSH must go through shellsafe; new endpoints and the
  csrf_guard exempt-prefix rule.
- ROADMAP.md: park the remaining non-blocking P2/P3 tech debt from the eval.

2026-06-12 17:10:03 -05:00

2.9 KiB

Raw Blame History

paths

image/**

FastAPI image (`image/`)

Standalone FastAPI app (Python ≥3.11; ships on python:3.12-slim; UI on port 9999; vanilla HTML/CSS/JS, no framework). Python has no configured linter/formatter — match the style of the file you're editing.

Local dev (no StartOS)

cd image
python3 -m venv .venv && source .venv/bin/activate   # one-time
pip install -e .
export SPARK1_HOST=<ip> SPARK1_USER=<user> SPARK2_HOST=<ip> SPARK2_USER=<user> SSH_KEY_PATH=<private-key>
# Required outside the container — these default to paths under /data, which only exists in the image
# (missing REDACTION_MAP_DB crashes startup; missing CONNECTIVITY_LOG 500s /api/status):
export REDACTION_MAP_DB=/tmp/redaction_maps.db CONNECTIVITY_LOG=/tmp/connectivity.json
uvicorn app.server:app --host 0.0.0.0 --port 9999 --reload

Other env vars: BIND_PORT, MODELS_YAML, SSH_DIR, SSH_KNOWN_HOSTS, MODELS_OVERRIDES, SERVICES_OVERRIDES.

Tests

No pytest harness — each suite is a standalone script run with the image/.venv interpreter (system python3 has no deps). See the redaction and audio rules for the suites themselves.

Conventions

Pydantic request models go at module scope, never inside a build_router() body (FastAPI silently 422s otherwise).
New external-facing endpoints get documented in docs/ (AUDIO_API.md, EMBEDDINGS.md, REDACTION_GATEWAY.md) and noted in release notes.
SSH-input safety: any user-supplied value that reaches an SSH command on the Sparks MUST go through app/shellsafe.py — validate against a whitelist at the API boundary, then quote_arg/quote_args (shlex.quote) at the sink. Never raw f-string a user value into a command string. Existing sinks: models.build_launch_command, download, nim, services; disk.py keeps its own _SAFE_DIRNAME because it needs $HOME to expand server-side. The vLLM pre-flight (validate.py) relies on shlex.split cleanly reversing this quoting — preserve that invariant.
CSRF / same-origin: state-mutating control endpoints are guarded by the csrf_guard middleware in server.py (rejects requests whose Origin/Referer host ≠ the served host). A new endpoint meant to be called cross-origin by downstream apps (a proxy/data endpoint) must be added to _CSRF_EXEMPT_PREFIXES, or browser POSTs from those apps will 403. No app-layer token auth by design (LAN/VPN-only; would break consumers).

Layout

image/app/server.py — FastAPI entry; routers live in sibling modules (audio_proxy.py, llm_proxy.py, embeddings_proxy.py, redaction_gateway.py, swap.py, health.py, deep_health.py, connectivity.py, …).
image/app/static/ — the dashboard UI.
image/models.yaml — vLLM model catalog bundled into the image.
image/spark_embed/ — Dockerfile + app for the embeddings container; built ON a Spark (ARM64, NGC PyTorch base — see the audio/cluster rule for NGC torch-pinning caveats).

2.9 KiB Raw Blame History

FastAPI image (image/)