Repository navigation
Closed
Description
Goal
Replace the Python Flask server with a native Rust HTTP/HTTPS server built into fastled-cli. This eliminates Flask, flask-cors, and cryptography as runtime dependencies, and enables live build streaming to the Tauri viewer.
Current architecture
Python entry point (fastled.cli)
-> compile (Python/Emscripten)
-> spawn Flask server (Python multiprocessing)
-> open Tauri viewer or system browser
Problems:
- Flask server runs in a separate Python process (~30 MB memory)
- Cannot stream build output to the viewer (compilation is synchronous, Flask is in another process)
- Flask + flask-cors + cryptography are heavyweight runtime dependencies
- Server starts AFTER compilation - user sees nothing during the build
Proposed architecture
fastled CLI (Rust)
-> start Rust HTTP/HTTPS server (background thread)
-> open Tauri viewer pointing at server URL
-> compile (Python subprocess), streaming status to server
-> server pushes updates to viewer via SSE
Rust HTTP server responsibilities
- Serve static files from the output directory (JS, WASM, HTML, CSS, fonts)
- Serve a built-in loading page when index.html does not exist yet
- Expose
/build-statusSSE endpoint for live compilation streaming - Set COOP/COEP headers for SharedArrayBuffer support
- HTTPS with bundled localhost certificates
- No-cache headers on all responses
Suggested crate: axum
- Mature, production-grade, async (tokio-based)
- Built-in static file serving via
tower-http - SSE support via
axum::response::sse - TLS via
axum-serverwithrustls
What changes
Rust (fastled-cli)
- Add
axum,tower-http,axum-server,tokiodependencies - New module:
src/server.rs- HTTP/HTTPS static file server with SSE - Update
src/main.rs- start server before launching Python compile subprocess - Server writes build status; frontend polls/subscribes via SSE
Python (remove)
- Remove
Flaskfrom pyproject.toml dependencies - Remove
flask-corsfrom pyproject.toml dependencies - Remove
cryptographyfrom pyproject.toml dependencies (unless needed elsewhere) - Remove
src/fastled/server_flask.py - Remove server spawning code from
src/fastled/open_browser.py - Update
compile_native.pyto delegate server lifecycle to Rust CLI
Tauri viewer
- Opens the Rust server URL (e.g.,
https://127.0.0.1:8122) instead of custom protocol - Enables SSE streaming from the server
Frontend
- Add build status polling: subscribe to
/build-statusSSE - Show loading/compiling overlay during builds
- Auto-refresh when compilation succeeds
Live build streaming flow
1. User runs: fastled examples/wasm
2. Rust CLI starts HTTP server on random port
3. Rust CLI opens Tauri viewer -> https://127.0.0.1:{port}
4. Viewer loads loading page (index.html does not exist yet)
5. Viewer subscribes to /build-status SSE
6. Rust CLI spawns: python -m fastled.compile_native ...
7. Python writes build-status.json during compilation
8. Server detects file changes, pushes SSE events
9. Viewer shows live build log
10. Compilation succeeds -> index.html appears
11. Viewer auto-refreshes to show the sketch
12. Watch mode: on file change, repeat steps 6-11
Dependencies removed
| Package | Size | Reason for removal |
|---|---|---|
| Flask | ~1 MB | Replaced by Rust axum server |
| flask-cors | ~50 KB | CORS handled in Rust |
| cryptography | ~4 MB | TLS handled by rustls |
| Werkzeug | ~1 MB | Flask dependency |
Dependencies added (Rust)
| Crate | Purpose |
|---|---|
| axum | HTTP framework |
| tower-http | Static file serving, CORS |
| axum-server | TLS/HTTPS support |
| tokio (already present via reqwest) | Async runtime |
Acceptance criteria
- Rust HTTP server serves static files with correct MIME types
- HTTPS works with bundled localhost certificates
- COOP/COEP headers set on all responses
- Loading page shown during compilation
- /build-status endpoint streams compilation progress
- Tauri viewer auto-refreshes when compilation succeeds
- Terminal prints server URL and port
- Flask, flask-cors, cryptography removed from runtime deps
- All existing tests pass (may need test server updates)
- Watch mode recompilation streams status to viewer
Metadata
Metadata
Assignees
Labels
No labels
Activity
feat: add Rust HTTP server module to fastled-cli (#45)
feat: add Rust HTTP server module to fastled-cli (#45) (#46)
feat: wire Rust HTTP server into CLI with --serve-dir and tests (#45)
feat: wire Rust HTTP server into CLI with tests (#45) (#47)
zackees commentedon Apr 12, 2026
Implementation Plan: Flask → Rust HTTP Server Migration
Current State
PRs #46 and #47 landed the Rust Axum HTTP server module and wired it for
--serve-dir. The normal compilation flow still uses Flask. This plan covers removing Flask entirely.Architecture Change
Current (non-Tauri):
Proposed (unified for both Tauri and browser):
Python becomes a compile-only subprocess. Rust handles all server, browser, and watch lifecycle.
Phase 1: Rust CLI orchestrates full lifecycle
Files:
main.rs,server.rsNew function
compile_and_serve():output_dir = <sketch_dir>/fastled_js; create if missingbuild-status.json→{"status":"compiling","message":"Compiling..."}server::start_server) — shows built-in loading pagehttp://127.0.0.1:{port}python -m fastled.app --just-compile <args>build-status.json→{"status":"success"}— loading page auto-reloadskeep_running: enter watch loop (Phase 2)Routing in
main():--just-compilecompile_and_serve()(NEW)--just-compile--serve-dirserve_directory()(unchanged)--init,--install,--purgeAlso add CORS headers via
tower-http::cors::CorsLayertoserver.rs.Phase 2: Wire
watcher.rsandbuild.rsBoth modules exist but are marked
#[allow(dead_code)]. Wire them:watcher.rs→ file change detection in watch loopbuild.rs→ centralizedrun_build()for Python subprocess invocationkeyboard.rs→ space-bar-to-recompile (mirrors Python'sSpaceBarWatcher)Phase 3: Remove Flask from Python
Delete:
src/fastled/server_flask.py(227 lines)src/fastled/debug_routes.py(48 lines)Modify:
open_browser.py— removespawn_http_server()and Flask imports; keep Tauri viewer helperscompile_native.py—run_native_compile()becomes compile-only; remove server + watch loopapp.py— remove--serve-dirFlask path (Rust intercepts before Python runs)__init__.py—Test.spawn_http_server()→ spawnfastled --serve-diras subprocesspyproject.toml— removeFlask,flask-cors,cryptographyPhase 4: Update tests
tests/unit/test_debug_routes.py(debug routes deferred)Key Design Decisions
localhostis a secure context — SharedArrayBuffer works without TLS. Eliminates cert management +cryptographydep.rustlscan be added later./dwarfsourceand/debug/source-rootsrequire portingDebugSymbolResolver(~200 lines complex path resolution). Most users don't use DWARF debugging. Follow-up PR.build-status.jsonas IPCDependencies Removed
tower-http::corsRemaining Acceptance Criteria After This Work
HTTPS with bundled localhost certificates→ deferred (HTTP-only; localhost is secure context)/build-statusendpoint streams compilation progress → partial: file-based polling, not SSE streaming (future enhancement)feat: replace Flask with Rust HTTP server for compilation flow (#45)
feat: replace Flask with Rust HTTP server for compilation flow (#45) (#…
zackees commentedon Apr 12, 2026
Completed in PR #48 — Flask removed, Rust HTTP server handles the full compile+serve+watch lifecycle.