stemtrace 0.2.2__tar.gz → 0.3.1__tar.gz

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

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

{stemtrace-0.2.2 → stemtrace-0.3.1}/.github/workflows/e2e.yml

@@ -13,6 +13,12 @@ jobs:
     name: API E2E Tests
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        broker:
+          - redis
+          - rabbitmq
 
     steps:
       - uses: actions/checkout@v6
@@ -20,13 +26,25 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      - name: Select compose file and Celery env
+        run: |
+          if [ "${{ matrix.broker }}" = "rabbitmq" ]; then
+            echo "COMPOSE_FILE=docker-compose.e2e.rabbitmq.yml" >> "$GITHUB_ENV"
+            echo "CELERY_BROKER_URL=amqp://guest:guest@localhost:5672//" >> "$GITHUB_ENV"
+            echo "CELERY_RESULT_BACKEND=redis://localhost:16380/1" >> "$GITHUB_ENV"
+          else
+            echo "COMPOSE_FILE=docker-compose.e2e.yml" >> "$GITHUB_ENV"
+            echo "CELERY_BROKER_URL=redis://localhost:16379/0" >> "$GITHUB_ENV"
+            echo "CELERY_RESULT_BACKEND=redis://localhost:16379/1" >> "$GITHUB_ENV"
+          fi
+
       - name: Build images
         run: |
-          docker compose -f docker-compose.e2e.yml build
+          docker compose -f "$COMPOSE_FILE" build
 
       - name: Start services
         run: |
-          docker compose -f docker-compose.e2e.yml up -d
+          docker compose -f "$COMPOSE_FILE" up -d
           # Wait for services to be healthy
           echo "Waiting for services..."
           timeout 120 bash -c 'until curl -sf http://localhost:8000/stemtrace/api/health -o /dev/null; do sleep 2; done'
@@ -51,16 +69,23 @@ jobs:
       - name: Show logs on failure
         if: failure()
         run: |
-          docker compose -f docker-compose.e2e.yml logs
+          docker compose -f "$COMPOSE_FILE" logs
 
       - name: Stop services
         if: always()
-        run: docker compose -f docker-compose.e2e.yml down -v
+        run: |
+          docker compose -f "$COMPOSE_FILE" down -v
 
   playwright:
     name: Playwright E2E Tests
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        broker:
+          - redis
+          - rabbitmq
 
     steps:
       - uses: actions/checkout@v6
@@ -68,13 +93,25 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      - name: Select compose file and Celery env
+        run: |
+          if [ "${{ matrix.broker }}" = "rabbitmq" ]; then
+            echo "COMPOSE_FILE=docker-compose.e2e.rabbitmq.yml" >> "$GITHUB_ENV"
+            echo "CELERY_BROKER_URL=amqp://guest:guest@localhost:5672//" >> "$GITHUB_ENV"
+            echo "CELERY_RESULT_BACKEND=redis://localhost:16380/1" >> "$GITHUB_ENV"
+          else
+            echo "COMPOSE_FILE=docker-compose.e2e.yml" >> "$GITHUB_ENV"
+            echo "CELERY_BROKER_URL=redis://localhost:16379/0" >> "$GITHUB_ENV"
+            echo "CELERY_RESULT_BACKEND=redis://localhost:16379/1" >> "$GITHUB_ENV"
+          fi
+
       - name: Build images
         run: |
-          docker compose -f docker-compose.e2e.yml build
+          docker compose -f "$COMPOSE_FILE" build
 
       - name: Start services
         run: |
-          docker compose -f docker-compose.e2e.yml up -d
+          docker compose -f "$COMPOSE_FILE" up -d
           echo "Waiting for services..."
           timeout 120 bash -c 'until curl -sf http://localhost:8000/stemtrace/api/health -o /dev/null; do sleep 2; done'
           echo "Services ready!"
@@ -133,7 +170,7 @@ jobs:
         uses: actions/upload-artifact@v6
         if: always()
         with:
-          name: playwright-report
+          name: playwright-report-${{ matrix.broker }}
           path: src/stemtrace/server/ui/frontend/playwright-report/
           retention-days: 7
 
@@ -141,15 +178,16 @@ jobs:
         uses: actions/upload-artifact@v6
         if: failure()
         with:
-          name: playwright-test-results
+          name: playwright-test-results-${{ matrix.broker }}
           path: src/stemtrace/server/ui/frontend/test-results/
           retention-days: 7
 
       - name: Show logs on failure
         if: failure()
         run: |
-          docker compose -f docker-compose.e2e.yml logs
+          docker compose -f "$COMPOSE_FILE" logs
 
       - name: Stop services
         if: always()
-        run: docker compose -f docker-compose.e2e.yml down -v
+        run: |
+          docker compose -f "$COMPOSE_FILE" down -v

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

@@ -7,8 +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
@@ -61,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.2.2 → stemtrace-0.3.1}/Makefile

@@ -168,9 +168,10 @@ e2e-mock:
 
 # Start E2E test environment (Docker)
 e2e-up:
+	docker compose -f docker-compose.e2e.yml build
 	docker compose -f docker-compose.e2e.yml up -d --wait
 	@echo "Waiting for services..."
-	@timeout 60 bash -c 'until curl -sf http://localhost:8000/stemtrace/api/health -o /dev/null; do sleep 2; done' || (echo "❌ Service failed to become healthy"; exit 1)
+	@uv run python scripts/wait_for_http.py http://localhost:8000/stemtrace/api/health --timeout 60
 	@echo "✅ E2E environment ready at http://localhost:8000"
 
 # Stop E2E test environment
@@ -193,5 +194,34 @@ e2e:
 	$(MAKE) e2e-down; \
 	exit $$status
 
+# =============================================================================
+# E2E Testing (RabbitMQ broker)
+# =============================================================================
+
+e2e-up-rabbitmq:
+	docker compose -f docker-compose.e2e.rabbitmq.yml build
+	docker compose -f docker-compose.e2e.rabbitmq.yml up -d --wait
+	@echo "Waiting for services..."
+	@uv run python scripts/wait_for_http.py http://localhost:8000/stemtrace/api/health --timeout 60
+	@echo "✅ RabbitMQ E2E environment ready at http://localhost:8000"
+
+e2e-down-rabbitmq:
+	docker compose -f docker-compose.e2e.rabbitmq.yml down -v
+
+e2e-api-rabbitmq:
+	CELERY_BROKER_URL=amqp://guest:guest@localhost:5672// \
+	CELERY_RESULT_BACKEND=redis://localhost:16380/1 \
+	uv run pytest tests/e2e/ -m e2e -v
+
+e2e-playwright-real-rabbitmq:
+	cd $(FRONTEND_DIR) && E2E_MODE=real PLAYWRIGHT_BASE_URL=http://localhost:8000 npm test
+
+e2e-rabbitmq:
+	$(MAKE) e2e-up-rabbitmq
+	$(MAKE) e2e-api-rabbitmq && $(MAKE) e2e-playwright-real-rabbitmq; \
+	status=$$?; \
+	$(MAKE) e2e-down-rabbitmq; \
+	exit $$status
+
 # Quick E2E alias (mock mode, no Docker)
 e2e-quick: e2e-mock

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.2.2
+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.2.2-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)
@@ -72,7 +72,7 @@ Ever stared at a failed Celery task wondering "what called this?" or "why did it
 
 Stemtrace captures your task executions as a graph — visualize parent→child flows, see retry chains, track groups and chords, all without adding any new infrastructure.
 
-**Today stemtrace supports Redis** for event transport (via Redis Streams). **RabbitMQ support is planned.**
+**stemtrace supports Redis and RabbitMQ** for event transport.
 
 ## ✨ Features
 
@@ -91,7 +91,7 @@ Stemtrace captures your task executions as a graph — visualize parent→child
 - **Registry status badges** — Quickly spot tasks that are active, never run, or not registered by any current worker
 
 **Production Ready**
-- **Zero Infrastructure** — Uses your existing Redis broker, no database needed
+- **Zero Infrastructure** — Uses your existing broker (Redis or RabbitMQ), no database needed
 - **Sensitive Data Scrubbing** — Passwords and API keys filtered automatically
 - **Read-Only** — Safe for production; never modifies your task queue
 - **FastAPI Integration** — Mount into your existing app with one line
@@ -162,6 +162,14 @@ stemtrace server
 
 Open [http://localhost:8000](http://localhost:8000).
 
+Tip: make sure the server is pointed at the same broker as your workers:
+
+```bash
+stemtrace server --broker-url redis://localhost:6379/0
+# or:
+stemtrace server --broker-url amqp://guest:guest@localhost:5672//
+```
+
 **Option B: Embed in your FastAPI app** (no extra container)
 
 ```python
@@ -175,7 +183,7 @@ stemtrace.init_app(app, broker_url="redis://localhost:6379/0")
 
 Access at `/stemtrace/` in your existing app — no new services to deploy.
 
-See [Deployment Options](#️-deployment-options) for auth, scaling, and more.
+See [Deployment Options](#deployment-options) for auth, scaling, and more.
 
 ## 📦 Architecture
 
@@ -294,18 +302,58 @@ 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
 
 | Broker | URL Scheme | Status |
 |--------|------------|--------|
 | Redis | `redis://`, `rediss://` | ✅ Supported |
-| RabbitMQ | `amqp://`, `amqps://` | 🚧 Planned |
+| 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
 
@@ -315,6 +363,23 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+RabbitMQ example:
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=amqp://guest:guest@host.docker.internal:5672// \
+    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
@@ -327,6 +392,8 @@ services:
       - STEMTRACE_BROKER_URL=redis://redis:6379/0
 ```
 
+For a local RabbitMQ setup, see [`docker-compose.rabbitmq.yml`](docker-compose.rabbitmq.yml).
+
 ## 🖥️ Deployment Options
 
 `stemtrace` offers two deployment modes depending on your needs:
@@ -353,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.
@@ -379,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
@@ -388,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
@@ -407,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
@@ -437,12 +537,12 @@ stemtrace.init_app(
 - ✅ **Sensitive data scrubbing** — Passwords and API keys filtered automatically
 - ✅ **Real-time updates** — WebSocket-powered live dashboard
 - ✅ **FastAPI integration** — Mount into your existing app
+- ✅ **RabbitMQ support** — Use your existing RabbitMQ broker (`amqp://`, `amqps://`, `pyamqp://`)
 - ✅ **Workers page** — Monitor online/offline workers and their registered tasks
 - ✅ **Task registry** — Browse discovered + registered tasks with clear status badges
 
 ### Coming Soon
 
-- 🔜 **RabbitMQ support** — Use your existing RabbitMQ broker
 - 🔜 **Anomaly detection** — Spot stuck, orphaned, or failed tasks
 - 🔜 **Dashboard with stats** — Success rates, durations, failure trends
 - 🔜 **OpenTelemetry export** — Send traces to Jaeger, Tempo, Datadog