stemtrace 0.3.0__tar.gz → 0.3.1__tar.gz

{stemtrace-0.3.0 → stemtrace-0.3.1}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.3.0"
+current_version = "0.3.1"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true

{stemtrace-0.3.0 → stemtrace-0.3.1}/CHANGELOG.md

@@ -7,10 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-01-04
+
+### Added
+- UI: optional built-in form login flow for protecting the stemtrace UI
+
+### Changed
+- Config: split server broker URL from worker event transport URL (`broker_url` vs `transport_url`)
+- API: avoid blocking worker/registry refresh operations
+- Docs: clarify optional configuration and retention behavior
+
+### Fixed
+- Workers/Registry: refresh via Celery inspect to reduce stale worker/task registry data
+
 ## [0.3.0] - 2026-01-04
 
+### Added
+- RabbitMQ event transport
+
+### Changed
+- Tests: improved RabbitMQ transport coverage and reduced duplication
+
+### Fixed
+- UI: harden derived prefix sanitization
+- CI/E2E: avoid artifact name conflicts
+
 ## [0.2.2] - 2026-01-03
 
+### Added
+- README: add release version badge
+
+### Changed
+- Packaging/docs: simplify badges and metadata
+- README: pin PyPI badge to release version
+- Tests: make version assertion dynamic
+
+### Fixed
+- Version bump: sync fix
+
 ## [0.2.1] - 2026-01-03
 
 ### Added
@@ -63,7 +97,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **E2E test suite**: Docker API tests + Playwright browser tests
 - **Comprehensive test suite**: 350+ Python tests, 90%+ coverage
 
-[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.2.1...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/iansokolskyi/stemtrace/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/iansokolskyi/stemtrace/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/iansokolskyi/stemtrace/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/iansokolskyi/stemtrace/compare/v0.1.0...v0.1.1

{stemtrace-0.3.0 → stemtrace-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.3.0
+Version: 0.3.1
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.0-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.1-darklime)](https://pypi.org/project/stemtrace)
 [![Python](https://img.shields.io/pypi/pyversions/stemtrace.svg)](https://pypi.org/project/stemtrace/)
 [![CI](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml/badge.svg)](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/iansokolskyi/stemtrace/graph/badge.svg)](https://codecov.io/gh/iansokolskyi/stemtrace)
@@ -302,11 +302,33 @@ batch_processor
 - **Timing** — Each node displays start time and duration directly in the graph
 - **Aggregate state** — Container shows running/success/failure based on member states
 
-### Environment Variables
+### Environment Variables (Optional)
+
+You **do not need** these environment variables if you’re using the Python APIs:
+- `stemtrace.init_worker(app, transport_url=..., prefix=..., ttl=...)`
+- `stemtrace.init_app(app, broker_url=..., transport_url=...)`
+
+They exist mainly as **convenient defaults** for:
+- `stemtrace server` / `stemtrace consume`
+- container/Docker setups where passing flags is awkward
+
+If your app already uses env vars like `BROKER_URL`, `REDIS_URL`, etc., just pass them through:
+
+```python
+import os
+import stemtrace
+
+stemtrace.init_app(
+    app,
+    broker_url=os.environ["BROKER_URL"],
+    transport_url=os.getenv("STEMTRACE_TRANSPORT_URL") or os.environ["BROKER_URL"],
+)
+```
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `STEMTRACE_BROKER_URL` | Broker URL for `stemtrace server` / `stemtrace consume` and `stemtrace.init_app()` | `redis://localhost:6379/0` |
+| `STEMTRACE_BROKER_URL` | Celery broker URL (used for on-demand worker/registry inspection). Also used as the default for `STEMTRACE_TRANSPORT_URL`. | `redis://localhost:6379/0` |
+| `STEMTRACE_TRANSPORT_URL` | Event transport URL (where stemtrace publishes/consumes events).  | Defaults to `STEMTRACE_BROKER_URL`. |
 
 ### Supported Brokers
 
@@ -315,6 +337,24 @@ batch_processor
 | Redis | `redis://`, `rediss://` | ✅ Supported |
 | RabbitMQ | `amqp://`, `amqps://`, `pyamqp://` | ✅ Supported |
 
+### Event Retention & Server Restarts (Important)
+
+stemtrace builds the UI from **events** and keeps state in an **in-memory** graph store.
+That means a `stemtrace server` restart starts from an empty store and only becomes “full”
+again once events are re-consumed.
+
+- **Redis (Streams)**: On restart, the server can rebuild state by replaying events that are
+  still retained in the stream (bounded by `ttl` / stream trimming).
+- **RabbitMQ (fanout + per-consumer queue)**:
+  - Events already consumed/acked by the server are **gone**.
+  - Events published while the server is down are only visible after restart if the server’s
+    durable per-consumer queue still exists and the messages are still within TTL.
+- **Workers + Registry tabs**: stemtrace uses **Celery inspect** on demand to populate workers
+  and registered tasks, so those pages work even if the server missed `worker_ready` events.
+- **If you need durable history across restarts**: point stemtrace events at Redis even if your
+  Celery broker is RabbitMQ (set `transport_url` in `stemtrace.init_worker(...)` and set
+  `STEMTRACE_TRANSPORT_URL` for the server / embedded setup).
+
 ## 🐳 Docker
 
 ```bash
@@ -331,6 +371,15 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+RabbitMQ broker + Redis event transport (recommended if you want history across server restarts):
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=amqp://guest:guest@host.docker.internal:5672// \
+    -e STEMTRACE_TRANSPORT_URL=redis://host.docker.internal:6379/0 \
+    ghcr.io/iansokolskyi/stemtrace
+```
+
 Or with Docker Compose:
 
 ```yaml
@@ -371,11 +420,22 @@ Open [http://localhost:8000](http://localhost:8000) to view the dashboard.
 ```bash
 stemtrace server \
     --broker-url redis://myredis:6379/0 \
+    --transport-url redis://myredis:6379/0 \
     --host 0.0.0.0 \
     --port 8000 \
     --reload  # For development
 ```
 
+#### Protecting the Server (Built-in Login Page)
+
+```bash
+stemtrace server \
+    --broker-url redis://myredis:6379/0 \
+    --login-username admin \
+    --login-password secret \
+    --login-secret change-me
+```
+
 #### High-Scale Production Setup
 
 Note: `stemtrace server` includes an embedded consumer today (single-process). A multi-process deployment mode is planned.
@@ -397,6 +457,8 @@ That's it. `init_app()` automatically:
 - Mounts the dashboard at `/stemtrace/`
 - Starts the event consumer
 
+Tip: you can also set `transport_url` if you want stemtrace events stored separately from your Celery broker.
+
 #### Configuration Options
 
 ```python
@@ -406,6 +468,7 @@ import stemtrace
 extension = stemtrace.init_app(
     app,
     broker_url="redis://localhost:6379/0",
+    transport_url=None,          # Defaults to broker_url
     prefix="/stemtrace",        # Mount path AND event stream prefix (normalized)
     ttl=86400,                  # Event TTL in seconds
     max_nodes=10000,            # Max nodes in memory
@@ -425,7 +488,26 @@ from your_app.auth import require_admin
 stemtrace.init_app(app, broker_url="redis://localhost:6379/0", auth_dependency=Depends(require_admin))
 ```
 
-Or use built-in auth helpers:
+#### With Built-in Login Page (Recommended for UI-first)
+
+If you primarily use the UI, the easiest way to protect **UI + assets + API + WebSocket**
+is the built-in form login (cookie session):
+
+```python
+import stemtrace
+
+stemtrace.init_app(
+    app,
+    broker_url="redis://localhost:6379/0",
+    login_username="admin",
+    login_password="secret",
+    login_secret="change-me",  # recommended for production
+)
+```
+
+This serves a sign-in page at `/stemtrace/login` and protects everything under `/stemtrace`.
+
+#### Built-in Auth Helpers (Basic / API key)
 
 ```python
 import stemtrace

{stemtrace-0.3.0 → stemtrace-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.0-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.1-darklime)](https://pypi.org/project/stemtrace)
 [![Python](https://img.shields.io/pypi/pyversions/stemtrace.svg)](https://pypi.org/project/stemtrace/)
 [![CI](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml/badge.svg)](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/iansokolskyi/stemtrace/graph/badge.svg)](https://codecov.io/gh/iansokolskyi/stemtrace)
@@ -248,11 +248,33 @@ batch_processor
 - **Timing** — Each node displays start time and duration directly in the graph
 - **Aggregate state** — Container shows running/success/failure based on member states
 
-### Environment Variables
+### Environment Variables (Optional)
+
+You **do not need** these environment variables if you’re using the Python APIs:
+- `stemtrace.init_worker(app, transport_url=..., prefix=..., ttl=...)`
+- `stemtrace.init_app(app, broker_url=..., transport_url=...)`
+
+They exist mainly as **convenient defaults** for:
+- `stemtrace server` / `stemtrace consume`
+- container/Docker setups where passing flags is awkward
+
+If your app already uses env vars like `BROKER_URL`, `REDIS_URL`, etc., just pass them through:
+
+```python
+import os
+import stemtrace
+
+stemtrace.init_app(
+    app,
+    broker_url=os.environ["BROKER_URL"],
+    transport_url=os.getenv("STEMTRACE_TRANSPORT_URL") or os.environ["BROKER_URL"],
+)
+```
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `STEMTRACE_BROKER_URL` | Broker URL for `stemtrace server` / `stemtrace consume` and `stemtrace.init_app()` | `redis://localhost:6379/0` |
+| `STEMTRACE_BROKER_URL` | Celery broker URL (used for on-demand worker/registry inspection). Also used as the default for `STEMTRACE_TRANSPORT_URL`. | `redis://localhost:6379/0` |
+| `STEMTRACE_TRANSPORT_URL` | Event transport URL (where stemtrace publishes/consumes events).  | Defaults to `STEMTRACE_BROKER_URL`. |
 
 ### Supported Brokers
 
@@ -261,6 +283,24 @@ batch_processor
 | Redis | `redis://`, `rediss://` | ✅ Supported |
 | RabbitMQ | `amqp://`, `amqps://`, `pyamqp://` | ✅ Supported |
 
+### Event Retention & Server Restarts (Important)
+
+stemtrace builds the UI from **events** and keeps state in an **in-memory** graph store.
+That means a `stemtrace server` restart starts from an empty store and only becomes “full”
+again once events are re-consumed.
+
+- **Redis (Streams)**: On restart, the server can rebuild state by replaying events that are
+  still retained in the stream (bounded by `ttl` / stream trimming).
+- **RabbitMQ (fanout + per-consumer queue)**:
+  - Events already consumed/acked by the server are **gone**.
+  - Events published while the server is down are only visible after restart if the server’s
+    durable per-consumer queue still exists and the messages are still within TTL.
+- **Workers + Registry tabs**: stemtrace uses **Celery inspect** on demand to populate workers
+  and registered tasks, so those pages work even if the server missed `worker_ready` events.
+- **If you need durable history across restarts**: point stemtrace events at Redis even if your
+  Celery broker is RabbitMQ (set `transport_url` in `stemtrace.init_worker(...)` and set
+  `STEMTRACE_TRANSPORT_URL` for the server / embedded setup).
+
 ## 🐳 Docker
 
 ```bash
@@ -277,6 +317,15 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+RabbitMQ broker + Redis event transport (recommended if you want history across server restarts):
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=amqp://guest:guest@host.docker.internal:5672// \
+    -e STEMTRACE_TRANSPORT_URL=redis://host.docker.internal:6379/0 \
+    ghcr.io/iansokolskyi/stemtrace
+```
+
 Or with Docker Compose:
 
 ```yaml
@@ -317,11 +366,22 @@ Open [http://localhost:8000](http://localhost:8000) to view the dashboard.
 ```bash
 stemtrace server \
     --broker-url redis://myredis:6379/0 \
+    --transport-url redis://myredis:6379/0 \
     --host 0.0.0.0 \
     --port 8000 \
     --reload  # For development
 ```
 
+#### Protecting the Server (Built-in Login Page)
+
+```bash
+stemtrace server \
+    --broker-url redis://myredis:6379/0 \
+    --login-username admin \
+    --login-password secret \
+    --login-secret change-me
+```
+
 #### High-Scale Production Setup
 
 Note: `stemtrace server` includes an embedded consumer today (single-process). A multi-process deployment mode is planned.
@@ -343,6 +403,8 @@ That's it. `init_app()` automatically:
 - Mounts the dashboard at `/stemtrace/`
 - Starts the event consumer
 
+Tip: you can also set `transport_url` if you want stemtrace events stored separately from your Celery broker.
+
 #### Configuration Options
 
 ```python
@@ -352,6 +414,7 @@ import stemtrace
 extension = stemtrace.init_app(
     app,
     broker_url="redis://localhost:6379/0",
+    transport_url=None,          # Defaults to broker_url
     prefix="/stemtrace",        # Mount path AND event stream prefix (normalized)
     ttl=86400,                  # Event TTL in seconds
     max_nodes=10000,            # Max nodes in memory
@@ -371,7 +434,26 @@ from your_app.auth import require_admin
 stemtrace.init_app(app, broker_url="redis://localhost:6379/0", auth_dependency=Depends(require_admin))
 ```
 
-Or use built-in auth helpers:
+#### With Built-in Login Page (Recommended for UI-first)
+
+If you primarily use the UI, the easiest way to protect **UI + assets + API + WebSocket**
+is the built-in form login (cookie session):
+
+```python
+import stemtrace
+
+stemtrace.init_app(
+    app,
+    broker_url="redis://localhost:6379/0",
+    login_username="admin",
+    login_password="secret",
+    login_secret="change-me",  # recommended for production
+)
+```
+
+This serves a sign-in page at `/stemtrace/login` and protects everything under `/stemtrace`.
+
+#### Built-in Auth Helpers (Basic / API key)
 
 ```python
 import stemtrace

{stemtrace-0.3.0 → stemtrace-0.3.1}/docker-compose.yml

@@ -44,7 +44,7 @@ services:
   #   depends_on:
   #     redis:
   #       condition: service_healthy
-  #   command: ["consume", "--broker-url", "redis://redis:6379"]
+  #   command: ["consume", "--transport-url", "redis://redis:6379"]
 
 volumes:
   redis-data:

{stemtrace-0.3.0 → stemtrace-0.3.1}/examples/celery_app.py

@@ -9,18 +9,38 @@ task events for visualization, including:
 - Group/chord visualization with synthetic GROUP nodes
 
 Usage:
-    # Install dependencies
-    pip install stemtrace[redis]
+    # Install dependencies (PyPI)
+    pip install stemtrace
+
+    # Or (from repo)
+    uv sync --extra dev
 
     # Start Redis
     docker run -d -p 6379:6379 redis:alpine
 
+    # (Optional) Start RabbitMQ (for RabbitMQ broker tests)
+    docker run -d -p 5672:5672 -p 15672:15672 rabbitmq:3-management
+
     # Start worker
     celery -A examples.celery_app worker --loglevel=info
 
     # Start stemtrace server (in another terminal)
     stemtrace server
 
+    # Switch between Redis and RabbitMQ using environment variables:
+    #   - CELERY_BROKER_URL controls where Celery sends tasks (default: Redis)
+    #   - CELERY_RESULT_BACKEND controls result backend (default: Redis)
+    #
+    # RabbitMQ note: chord-style workflows require a result backend that supports
+    # chords; `redis://` works well.
+    #
+    # Example (RabbitMQ broker + Redis result backend):
+    #   export CELERY_BROKER_URL="amqp://guest:guest@localhost:5672//"
+    #   export CELERY_RESULT_BACKEND="redis://localhost:6379/1"
+    #
+    # (Optional) override stemtrace's event transport independent of Celery:
+    #   export STEMTRACE_TRANSPORT_URL="amqp://guest:guest@localhost:5672//"
+
     # Run demo tasks
     python examples/celery_app.py workflow  # Complex workflow (chain + group)
     python examples/celery_app.py group     # Parallel group (synthetic GROUP node)
@@ -32,6 +52,7 @@ Usage:
 
 from __future__ import annotations
 
+import os
 import random
 import sys
 from typing import Any
@@ -40,15 +61,24 @@ from celery import Celery, chain, chord, group
 
 import stemtrace
 
+# Defaults (Redis local)
+_DEFAULT_REDIS_BROKER = "redis://localhost:6379/0"
+_DEFAULT_REDIS_BACKEND = "redis://localhost:6379/1"
+
+# Allow env-driven configuration so the same example can test Redis or RabbitMQ.
+_CELERY_BROKER_URL = os.getenv("CELERY_BROKER_URL", _DEFAULT_REDIS_BROKER)
+_CELERY_RESULT_BACKEND = os.getenv("CELERY_RESULT_BACKEND", _DEFAULT_REDIS_BACKEND)
+
 # Create Celery app
 app = Celery(
     "examples",
-    broker="redis://localhost:6379/0",
-    backend="redis://localhost:6379/1",
+    broker=_CELERY_BROKER_URL,
+    backend=_CELERY_RESULT_BACKEND,
 )
 
 # Initialize stemtrace tracking
-stemtrace.init_worker(app)
+_STEMTRACE_TRANSPORT_URL = os.getenv("STEMTRACE_TRANSPORT_URL")
+stemtrace.init_worker(app, transport_url=_STEMTRACE_TRANSPORT_URL)
 
 
 # =============================================================================

{stemtrace-0.3.0 → stemtrace-0.3.1}/examples/fastapi_integration.py

@@ -5,7 +5,7 @@ This example shows how to mount stemtrace as a router in your existing
 FastAPI app, with an embedded consumer for development.
 
 Usage:
-    pip install stemtrace[server]
+    pip install stemtrace
     uvicorn examples.fastapi_integration:app --reload
 """
 
@@ -14,19 +14,22 @@ from fastapi import FastAPI
 import stemtrace
 
 # Configuration
+#
+# `broker_url` is Celery's broker (used for on-demand worker inspection).
+# `transport_url` is where stemtrace consumes events from (defaults to broker_url).
 BROKER_URL = "redis://localhost:6379/0"
+TRANSPORT_URL = None  # e.g. "redis://localhost:6379/0"
 
 # Create FastAPI app
 app = FastAPI(
     title="My App with stemtrace",
 )
 
-# Initialize stemtrace in one line (convenience API)
+# Initialize stemtrace in one line
 stemtrace.init_app(
     app,
     broker_url=BROKER_URL,
-    embedded_consumer=True,  # Run consumer in background
-    serve_ui=True,  # Serve the React UI
+    transport_url=TRANSPORT_URL,
 )
 
 
@@ -40,13 +43,6 @@ async def root() -> dict[str, str]:
 @app.get("/health")
 async def health() -> dict[str, str]:
     """Health check endpoint."""
-    # Note: With convenience API, you don't have access to the extension instance
-    # Use StemtraceExtension directly if you need programmatic access:
-    #
-    # from stemtrace import StemtraceExtension
-    # flow = StemtraceExtension(broker_url=...)
-    # flow.init_app(app)
-    # return {"status": flow.consumer.is_running}
     #
     return {"status": "ok"}
 

{stemtrace-0.3.0 → stemtrace-0.3.1}/examples/with_auth.py

@@ -5,7 +5,7 @@ This example shows how to protect stemtrace endpoints with
 basic authentication or API key authentication.
 
 Usage:
-    pip install stemtrace[server]
+    pip install stemtrace
     uvicorn examples.with_auth:app --reload
 """
 
@@ -23,11 +23,10 @@ app = FastAPI(
     title="stemtrace with Auth",
 )
 
-# Initialize stemtrace with authentication (convenience API)
+# Initialize stemtrace with authentication
 stemtrace.init_app(
     app,
     broker_url=BROKER_URL,
-    embedded_consumer=True,
     auth_dependency=require_basic_auth(AUTH_USERNAME, AUTH_PASSWORD),
 )
 

stemtrace-0.3.1/examples/with_login.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Example: stemtrace with built-in form login.
+
+This example shows how to protect the stemtrace UI with a pretty login page.
+
+Usage:
+    pip install stemtrace[server]
+    uvicorn examples.with_login:app --reload
+"""
+
+from fastapi import FastAPI
+
+import stemtrace
+
+# Configuration
+BROKER_URL = "redis://localhost:6379/0"
+LOGIN_USERNAME = "admin"
+LOGIN_PASSWORD = "secret"  # NOSONAR - example credential for local demo only
+LOGIN_SECRET = "change-me"  # recommended for production
+
+app = FastAPI(title="stemtrace with Login")
+
+stemtrace.init_app(
+    app,
+    broker_url=BROKER_URL,
+    embedded_consumer=True,
+    serve_ui=True,
+    login_username=LOGIN_USERNAME,
+    login_password=LOGIN_PASSWORD,
+    login_secret=LOGIN_SECRET,
+)
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    """Public endpoint."""
+    return {"message": "Visit /stemtrace (login required)"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

{stemtrace-0.3.0 → stemtrace-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stemtrace"
-version = "0.3.0"
+version = "0.3.1"
 description = "A lightweight Celery task flow visualizer"
 readme = "README.md"
 license = { text = "MIT" }
@@ -76,6 +76,7 @@ build-backend = "hatchling.build"
 packages = ["src/stemtrace"]
 artifacts = [
     "src/stemtrace/server/ui/frontend/dist/**",
+    "src/stemtrace/server/ui/templates/**",
 ]
 
 [tool.hatch.build.targets.wheel.hooks.custom]