fluxlit 0.8.1

Production-oriented unified runtime for FastAPI + Streamlit

FluxLit

FastAPI and Streamlit on one public port. FluxLit gives you one FluxLit app object, a Uvicorn-powered ASGI gateway, and a managed Streamlit sidecar so your API and UI deploy together without hand-rolling a reverse proxy.

• UI: served from the app root on the URL Uvicorn prints, typically http://127.0.0.1:8000.
• API: mounted under /api by default, with OpenAPI at /api/docs.
• Routing: /api/* goes to FastAPI; everything else, including Streamlit WebSockets, is proxied to Streamlit.

Docs: fluxlit.readthedocs.io · Security: SECURITY.md · Roadmap: ROADMAP.md · Changelog: CHANGELOG.md (current release 0.8.1; Unreleased is for work after that tag)

---

Install

Python 3.10+.

pip install fluxlit

Optional JWT / OIDC / BFF helpers: pip install "fluxlit[auth]" — see Auth recipes.

For local development on FluxLit itself, clone the repository and run pip install -e ".[dev]".

---

Quick Start

fluxlit new my-app && cd my-app   # optional

app.py:

from fluxlit import FluxLit

app = FluxLit(title="Admin Portal")

@app.api.get("/users")
def users():
    return [{"name": "Ada"}]

@app.page("/")
def home(st, client):
    st.title("Dashboard")
    st.write(client.get("/users").json())

fluxlit dev    # default target app:app; or fluxlit dev your.module:app

Open the URL Uvicorn prints. The default gateway is http://127.0.0.1:8000; try GET /api/users or visit /api/docs.

In Streamlit, use paths like client.get("/users"), not "/api/users". Secured routes need a client with credentials — Auth recipes.

---

What Ships

• One app object: FluxLit exposes .api for FastAPI and @app.page(...) for Streamlit pages.
• Gateway runtime: fluxlit dev and fluxlit run start Uvicorn plus a managed Streamlit subprocess.
• Operational defaults: health/readiness probes, request IDs, optional JSON logs, configurable gateway timeouts, body limits, concurrency, and graceful shutdown.
• Quality gate: package tests enforce 100% line coverage for src/fluxlit in CI; a single internal import guard in the test helpers uses # pragma: no cover for an unreachable defensive branch.
• Deployment paths: fluxlit build, Docker Compose, Kubernetes manifests, proxy smoke tests (strip-prefix, full-path, root, HTTPS, and /apps/my-app), and production TLS/proxy guidance.
• Optional auth: JWT validation, OIDC/BFF helpers, Streamlit-safe API clients, and security docs via fluxlit[auth].
• Testing and diagnostics: FluxLitTestClient, streamlit_main_path(), AppTest recipes (including apptest_select_page / apptest_assert_no_errors for multipage and query params), URL-session test-mode defaults, optional ?page= deep links before st.navigation with multipage apps, and expanded fluxlit doctor diagnostics for imports, proxy/config state, and optional extras.

Start with the Quick start, then see Architecture, CLI, Configuration, and Deployment.

---

Configuration

Precedence: CLI → environment (FLUXLIT_*, .env) → fluxlit.toml / [tool.fluxlit] → defaults.

# fluxlit.toml (optional)
target = "app:app"
gateway_host = "127.0.0.1"
gateway_port = 8000

Variable reference: Configuration.

Gateway → Streamlit (optional env): tune upstream HTTP timeouts, max proxied request body (returns 413 when exceeded), concurrent upstream HTTP cap, httpx connection limits, WebSocket open/ping/close timeouts, and optional frame size — see the Gateway proxy rows in Configuration. FLUXLIT_UVICORN_GRACEFUL_SHUTDOWN_TIMEOUT_S maps to Uvicorn’s graceful drain window when set (fluxlit dev / fluxlit run).

Logs: enable structured gateway lines with FLUXLIT_ENABLE_GATEWAY_ACCESS_LOG=1; for one JSON object per line in log aggregators, use fluxlit.logging.JsonLogFormatter (examples in Observability). Avoid logging secrets—see Secrets.

TLS / edge: behind a real proxy, tighten FLUXLIT_FORWARDED_ALLOW_IPS, validate X-Forwarded-Proto, and read Production TLS before enabling strict HSTS or CSP elsewhere.

---

Production References

• Deployment: containers, probes, scaling, and Kubernetes graceful shutdown.
• Observability: request correlation, JSON logs, Prometheus metrics, SLO notes, and runbooks.
• Security architecture, Production TLS, and Secrets: auth boundaries, proxy trust, key rotation, and log hygiene.
• Support matrix: Python and dependency versions tested in CI, pinning guidance (uv / pip-tools / constraints), and upgrade notes for FluxLitTestClient and Streamlit AppTest.
• examples/kubernetes/, examples/docker_compose/, examples/path_prefixed_proxy/, examples/multipage_apptest/, and examples/fullstack_demo/: reference deployment and application patterns. Runnable nginx + FluxLit smoke stacks (including /apps/my-app) live under docker/proxy-deployment/.

---

Project Layout

my_app/
├── app.py
├── fluxlit.toml
├── .env              # not committed
└── pkg/pages/        # optional: discover_pages(...)

---

Contributors

pip install -e ".[dev]"
python -m ruff format && python -m ruff check
python -m mypy src/fluxlit
ty check
python -m pytest -n auto --cov=fluxlit --cov-report=term-missing --cov-fail-under=100

Contributing · Testing

---

Status

FluxLit is in the 0.x line and actively hardening toward production use. Current releases include the unified gateway, page discovery, typed ApiClient, health/readiness probes, auth helpers, URL session utilities, AppTest-friendly navigation and query-param helpers, expanded doctor diagnostics, gateway limits, structured logging helpers, Prometheus metrics, CI security audit/SBOM generation, Docker/Kubernetes examples, path-prefixed reverse-proxy documentation and smoke coverage, deployment runbooks, and a 100% package line-coverage gate for src/fluxlit in CI.

See the changelog, support matrix, and roadmap for release status and remaining work.

MIT — see LICENSE.