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/
```