Skip to content

feat: replace Flask with Rust HTTP server in fastled-cli #45

Closed

Description

@zackees

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-status SSE 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-server with rustls

What changes

Rust (fastled-cli)

  1. Add axum, tower-http, axum-server, tokio dependencies
  2. New module: src/server.rs - HTTP/HTTPS static file server with SSE
  3. Update src/main.rs - start server before launching Python compile subprocess
  4. Server writes build status; frontend polls/subscribes via SSE

Python (remove)

  • Remove Flask from pyproject.toml dependencies
  • Remove flask-cors from pyproject.toml dependencies
  • Remove cryptography from 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.py to 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-status SSE
  • 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

Activity

  1. zackees commented on Apr 12, 2026

    @zackees
    MemberAuthor

    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):

    Rust CLI → Python (compile + Flask server + file watch)
    

    Proposed (unified for both Tauri and browser):

    Rust CLI → Start Rust HTTP server → Open browser/Tauri → Python (--just-compile only) → Rust file watcher → recompile loop
    

    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.rs

    New function compile_and_serve():

    1. Compute output_dir = <sketch_dir>/fastled_js; create if missing
    2. Write build-status.json → {"status":"compiling","message":"Compiling..."}
    3. Start Rust HTTP server (server::start_server) — shows built-in loading page
    4. Open browser/Tauri at http://127.0.0.1:{port}
    5. Spawn python -m fastled.app --just-compile <args>
    6. On success: write build-status.json → {"status":"success"} — loading page auto-reloads
    7. On failure: write error status, print to terminal
    8. If keep_running: enter watch loop (Phase 2)

    Routing in main():

    Condition Behavior
    Directory + no --just-compile compile_and_serve() (NEW)
    --just-compile Delegate to Python, no server
    --serve-dir Existing serve_directory() (unchanged)
    --init, --install, --purge Delegate to Python (unchanged)

    Also add CORS headers via tower-http::cors::CorsLayer to server.rs.

    Phase 2: Wire watcher.rs and build.rs

    Both modules exist but are marked #[allow(dead_code)]. Wire them:

    • watcher.rs → file change detection in watch loop
    • build.rs → centralized run_build() for Python subprocess invocation
    • keyboard.rs → space-bar-to-recompile (mirrors Python's SpaceBarWatcher)
    Watch loop:
      recv file change (1s timeout) OR space-bar press →
        write build-status.json "compiling"
        run_build()  // python -m fastled.app --just-compile
        write build-status.json "success" or "error"
    

    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 — remove spawn_http_server() and Flask imports; keep Tauri viewer helpers
    • compile_native.py — run_native_compile() becomes compile-only; remove server + watch loop
    • app.py — remove --serve-dir Flask path (Rust intercepts before Python runs)
    • __init__.py — Test.spawn_http_server() → spawn fastled --serve-dir as subprocess
    • pyproject.toml — remove Flask, flask-cors, cryptography

    Phase 4: Update tests

    • Delete tests/unit/test_debug_routes.py (debug routes deferred)
    • Update integration tests to use HTTP instead of HTTPS

    Key Design Decisions

    Decision Rationale
    HTTP-only (drop HTTPS) localhost is a secure context — SharedArrayBuffer works without TLS. Eliminates cert management + cryptography dep. rustls can be added later.
    Debug routes deferred /dwarfsource and /debug/source-roots require porting DebugSymbolResolver (~200 lines complex path resolution). Most users don't use DWARF debugging. Follow-up PR.
    Python = compile-only Emscripten compilation stays in Python. Only server/watch/browser lifecycle moves to Rust.
    No auto-reload on recompile Current Flask behavior doesn't auto-reload either. SSE live-reload is a future enhancement.
    build-status.json as IPC Rust writes status file, loading page polls it. Simple file-based protocol.

    Dependencies Removed

    Package Size Replaced By
    Flask ~1 MB Rust Axum server (already exists)
    flask-cors ~50 KB tower-http::cors
    cryptography ~4 MB Dropped (HTTP-only)
    Werkzeug ~1 MB (Flask transitive dep)

    Remaining Acceptance Criteria After This Work

  2. zackees commented on Apr 12, 2026

    @zackees
    MemberAuthor

    Completed in PR #48 — Flask removed, Rust HTTP server handles the full compile+serve+watch lifecycle.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions