repospace / SPEC.md
2Btainment's picture
fix(api): stop preview polls from false 429s; stronger Einswarm gold mesh
1fce13c verified
|
Raw History Blame Contribute Delete
3.59 kB

RepoSpace β€” Architecture Spec (HF Space MVP)

One-liner

Temporary, instantly usable live environments for GitHub repos in the browser.

MVP loop

GitHub URL β†’ validate β†’ clone (tarball) β†’ detect β†’ build/run in constrained subprocess β†’ reverse-proxy preview in iframe under /s/{id}/ β†’ auto-shutdown after 15 min inactivity (hard cap 60 min).

META-BLUEPRINT β†’ HF reality (honest deltas)

Blueprint (ideal) HF Space MVP Notes
AWS EKS + Firecracker / MicroVMs Not available inside a single HF Space Documented; no fake K8s claims
Go control plane Python FastAPI Prefer FastAPI for HF Docker reliability
Per-VM network isolation Best-effort subprocess + localhost ports Shared Space network namespace
Docker-in-Docker Disabled HF does not offer privileged DinD for this use
Full node/Python/Docker workloads Static / simple Node build+serve / simple Python web Next.js full server, heavy Docker images β†’ clear failure + log diagnosis
Distributed session store SQLite in /data (or /tmp/repospace) TTL + inactivity cleaner
Unlimited concurrent sessions Soft cap MAX_CONCURRENT_SESSIONS (default 3) cpu-basic constraints

Features F1–F4 (as far as HF allows)

  • F1 Launch from GitHub URL β€” βœ… public tarball; private with user-supplied token (never logged; docs use [ERSATZ_KEY])
  • F2 Live preview iframe β€” βœ… /s/{id}/ reverse proxy when runnable
  • F3 Build logs β€” βœ… poll + optional SSE (?sse=1)
  • F4 Auto-teardown β€” βœ… 15 min inactivity + 60 min hard TTL + DELETE API

Stack

  • Deploy: Hugging Face Space, Docker SDK, cpu-basic (upgrade if needed)
  • Backend: Python 3.11 + FastAPI (API + static UI + proxy)
  • Frontend: React 18 + TypeScript + Vite (UI English, i18n-ready)
  • Session store: SQLite
  • Sandbox: isolated asyncio subprocesses with setsid, CPU/AS soft resource limits, timeouts, temp dirs under /data/sessions/{id}

API

  • POST /api/sessions {repo_url, github_token?, ref?}
  • GET /api/sessions/{id}
  • GET /api/sessions/{id}/logs?after=&sse=
  • DELETE /api/sessions/{id}
  • Proxy: /s/{id}/… β†’ 127.0.0.1:{port}/…
  • GET /api/health

Preview strategies

  1. static β€” index.html in root / dist / build / public / out β†’ python -m http.server
  2. node β€” npm install (+ optional build β†’ static) or npm run preview|start with $PORT
  3. python β€” FastAPI/Flask/Streamlit heuristics with pip install from requirements.txt
  4. unsupported β€” Dockerfile-only / Next.js heavy / unknown β†’ honest error + hints (build log diagnosis)

Security

  • Never execute untrusted code in the main API process
  • Temp dirs per session; path traversal blocked on URL, archive members, proxy paths, session ids
  • Rate limit by IP: create 8/min, delete 30/min, status GET + logs poll 600/min (preview UI polls ~1/s)
  • Credential-like env vars stripped from child processes
  • Tokens redacted in logs; placeholders [ERSATZ_KEY]
  • No host secret mounts into sandboxes
  • Public repos without token; private only with user-supplied token

Status machine

pending β†’ building β†’ running | failed β†’ terminated

File tree

repospace/
β”œβ”€β”€ SPEC.md
β”œβ”€β”€ RESULT.md
β”œβ”€β”€ README.md          # HF Space card + YAML frontmatter
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ requirements.txt
β”œβ”€β”€ backend/app/…
β”œβ”€β”€ backend/tests/…
β”œβ”€β”€ frontend/…
└── scripts/