rmq-healer 0.1.0__tar.gz

rmq_healer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grimnexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rmq_healer-0.1.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: rmq-healer
+Version: 0.1.0
+Summary: Abstract, extensible RabbitMQ error-queue remediation tool
+License: MIT License
+        
+        Copyright (c) 2026 grimnexo
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pika>=1.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonpath-ng>=1.6
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-pika; extra == "dev"
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.19; extra == "metrics"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/img/rmq-healer-gh-banner.png" alt="RMQ Healer" width="100%"/>
+</p>
+
+<p align="center">
+  <img src="assets/img/rmq-healer-logo.png" alt="RMQ Healer Logo" width="180"/>
+</p>
+
+<p align="center">
+  <strong>Abstract, extensible RabbitMQ error-queue remediation.</strong><br/>
+  Classify &rarr; remediate &rarr; audit &mdash; fully configurable, no code required for common cases.
+</p>
+
+<p align="center">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white"/>
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green"/>
+  <img alt="CI" src="https://github.com/grimnexo/RMQ-Healer/actions/workflows/ci.yml/badge.svg"/>
+  <img alt="Coverage" src="https://img.shields.io/codecov/c/github/grimnexo/RMQ-Healer?logo=codecov"/>
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/rmq-healer?logo=pypi&logoColor=white"/>
+  <img alt="Docker" src="https://img.shields.io/docker/pulls/grimnexo/rmq-healer?logo=docker"/>
+  <img alt="Code style" src="https://img.shields.io/badge/code%20style-ruff-orange?logo=python"/>
+</p>
+
+---
+
+## What Is It?
+
+RMQ Healer watches RabbitMQ error queues and **automatically remediates known failure patterns** without touching your application code. You write YAML rules; the healer classifies every message and runs the matching workflow.
+
+### Core Features
+
+| | Feature |
+|---|---|
+| **Zero-loss processing** | Messages are acked *only* after a terminal action succeeds. If anything fails the message stays in the queue — untouched. |
+| **Declarative rules** | YAML rule files with nested boolean logic: `body_contains`, `json_path`, `header_equals`, `property_equals`, and combinators (`all`/`any`/`not`). |
+| **Rich workflow engine** | `log`, `mutate_json`, `set_headers`, `python_script`, `republish`, `quarantine`, `route_unknown`, `drop`. |
+| **Jinja2 templating** | Every action param is a Jinja2 template — reference headers, body fields, script outputs, queue config. |
+| **Python script plugins** | Drop any Python script in; it receives full message context on stdin and returns a JSON decision on stdout. |
+| **Idempotency guard** | Bump-and-quarantine: after N failed runs the message is quarantined automatically. |
+| **Structured audit log** | JSON-lines output — pipe straight to Fluentd, Loki, or CloudWatch. |
+| **Non-destructive peek** | Inspect queue contents without consuming — broker requeues automatically after peek. |
+| **Graceful shutdown** | SIGTERM/SIGINT safe — finishes the current message before stopping. |
+| **Developer GUI** | PyQt6 desktop app for editing configs, viewing chains, peeking live queues, and browsing audit logs. |
+| **Plugin architecture** | Register custom actions via Python `entry_points` or a local `plugins/` directory. |
+| **Prometheus metrics** | Optional `prometheus_client` integration — zero-overhead when not installed. |
+| **Dry-run with diffs** | See exactly what `mutate_json` would change before committing. |
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+    EQ[("Error Queue")]
+    CL["Classifier\n(first match wins)"]
+    WF["WorkflowRunner"]
+    AU["AuditLogger\n(JSON-lines)"]
+
+    EQ -->|basic_get| CL
+    CL -->|matched rule| WF
+    CL -->|no match| UQ[("Unknown Queue")]
+    WF --> A1["log / set_headers\nmutate_json / python_script"]
+    A1 --> T{"Terminal\naction"}
+    T -->|republish| RQ[("Repaired Queue")]
+    T -->|quarantine| Q[("Quarantine Queue")]
+    T -->|route_unknown| UQ
+    T -->|drop| DONE["Ack + discard"]
+    WF --> AU
+    CL --> AU
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install -e ".[dev]"
+
+# 2. Set broker URL
+export RMQ_URL="amqp://guest:guest@localhost/"
+
+# 3. Generate config interactively
+rmq-healer configure --output config/queues.yml
+
+# 4. Validate
+rmq-healer validate --config config/queues.yml
+
+# 5. Test a rule against a sample message
+rmq-healer test-rule --config config/queues.yml \
+  --queue order-service.error --message examples/retry-timeout/sample.json
+
+# 6. Dry-run with mutation diffs — nothing acked or published
+rmq-healer dry-run --config config/queues.yml --all --pretty
+
+# 7. Live run
+rmq-healer run --config config/queues.yml --all --pretty
+
+# 8. Peek without consuming
+rmq-healer peek --config config/queues.yml --queue order-service.error --count 10
+
+# 9. Visualise a workflow as a Mermaid diagram
+rmq-healer workflow render --config config/queues.yml --queue order-service.error
+
+# 10. Search audit logs
+rmq-healer audit-search --log audit.jsonl --outcome quarantine
+```
+
+---
+
+## Example Configuration
+
+```yaml
+rabbitmq:
+  url: "${RMQ_URL}"
+  prefetch: 10
+
+idempotency:
+  enabled: true
+  max_handler_attempts: 3
+
+queues:
+  - name: order-service.error
+    enabled: true
+    rules_file: rules/order-errors.yml
+    repaired_exchange: order.events
+    repaired_routing_key: order.retry
+    quarantine_exchange: ops.errors
+    quarantine_routing_key: order.quarantine
+```
+
+```yaml
+# rules/order-errors.yml
+rules:
+  - id: transient_timeout
+    match:
+      any:
+        - body_contains: "ETIMEDOUT"
+        - json_path: $.error.code
+          equals: "TIMEOUT"
+    workflow:
+      - action: set_headers
+        params:
+          headers:
+            x-rmq-healer-rule: transient_timeout
+      - action: republish
+        params:
+          exchange: "{{ queue.repaired_exchange }}"
+          routing_key: "{{ queue.repaired_routing_key }}"
+
+  - id: missing_customer_id
+    match:
+      all:
+        - json_path: $.customer_id
+          equals: null
+    workflow:
+      - action: python_script
+        params:
+          script: scripts/lookup_customer.py
+          timeout: 30
+          output:
+            save_as: customer
+      - action: mutate_json
+        params:
+          set:
+            "$.customer_id": "{{ customer.id }}"
+      - action: republish
+        params:
+          exchange: "{{ queue.repaired_exchange }}"
+          routing_key: "{{ queue.repaired_routing_key }}"
+```
+
+See the `examples/` directory for complete, runnable scenarios.
+
+---
+
+## Documentation
+
+| Topic | Guide |
+|---|---|
+| Installation & setup | [docs/installation.md](docs/installation.md) |
+| Configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Writing rules | [docs/rules.md](docs/rules.md) |
+| Python script actions | [docs/python-scripts.md](docs/python-scripts.md) |
+| CLI reference (all commands) | [docs/cli-reference.md](docs/cli-reference.md) |
+| Operations guide | [docs/operations.md](docs/operations.md) |
+| Docker deployment | [docs/docker.md](docs/docker.md) |
+| Developer GUI | [docs/developer-gui.md](docs/developer-gui.md) |
+| Plugin architecture | [docs/plugins.md](docs/plugins.md) |
+| Metrics & observability | [docs/metrics.md](docs/metrics.md) |
+| Contributing & tooling | [docs/contributing.md](docs/contributing.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+
+> **[Browse all docs &rarr;](docs/README.md)**
+
+---
+
+## Developer Environment
+
+```powershell
+# Windows
+.\developer\scripts\setup.ps1      # start RabbitMQ + seed fixtures
+.\developer\scripts\run-test.ps1   # dry-run
+.\developer\scripts\launch-gui.ps1 # open GUI
+.\developer\scripts\teardown.ps1   # stop
+```
+
+```bash
+# Linux / macOS
+bash developer/scripts/setup.sh
+bash developer/scripts/run-test.sh
+bash developer/scripts/launch-gui.sh
+bash developer/scripts/teardown.sh
+
+# Or cross-platform Python
+python developer/scripts/dev_setup.py
+python developer/scripts/run_test.py
+python developer/scripts/launch_gui.py
+```
+
+---
+
+## License
+
+MIT &mdash; see [LICENSE](LICENSE).

rmq_healer-0.1.0/README.md

@@ -0,0 +1,225 @@
+<p align="center">
+  <img src="assets/img/rmq-healer-gh-banner.png" alt="RMQ Healer" width="100%"/>
+</p>
+
+<p align="center">
+  <img src="assets/img/rmq-healer-logo.png" alt="RMQ Healer Logo" width="180"/>
+</p>
+
+<p align="center">
+  <strong>Abstract, extensible RabbitMQ error-queue remediation.</strong><br/>
+  Classify &rarr; remediate &rarr; audit &mdash; fully configurable, no code required for common cases.
+</p>
+
+<p align="center">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white"/>
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green"/>
+  <img alt="CI" src="https://github.com/grimnexo/RMQ-Healer/actions/workflows/ci.yml/badge.svg"/>
+  <img alt="Coverage" src="https://img.shields.io/codecov/c/github/grimnexo/RMQ-Healer?logo=codecov"/>
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/rmq-healer?logo=pypi&logoColor=white"/>
+  <img alt="Docker" src="https://img.shields.io/docker/pulls/grimnexo/rmq-healer?logo=docker"/>
+  <img alt="Code style" src="https://img.shields.io/badge/code%20style-ruff-orange?logo=python"/>
+</p>
+
+---
+
+## What Is It?
+
+RMQ Healer watches RabbitMQ error queues and **automatically remediates known failure patterns** without touching your application code. You write YAML rules; the healer classifies every message and runs the matching workflow.
+
+### Core Features
+
+| | Feature |
+|---|---|
+| **Zero-loss processing** | Messages are acked *only* after a terminal action succeeds. If anything fails the message stays in the queue — untouched. |
+| **Declarative rules** | YAML rule files with nested boolean logic: `body_contains`, `json_path`, `header_equals`, `property_equals`, and combinators (`all`/`any`/`not`). |
+| **Rich workflow engine** | `log`, `mutate_json`, `set_headers`, `python_script`, `republish`, `quarantine`, `route_unknown`, `drop`. |
+| **Jinja2 templating** | Every action param is a Jinja2 template — reference headers, body fields, script outputs, queue config. |
+| **Python script plugins** | Drop any Python script in; it receives full message context on stdin and returns a JSON decision on stdout. |
+| **Idempotency guard** | Bump-and-quarantine: after N failed runs the message is quarantined automatically. |
+| **Structured audit log** | JSON-lines output — pipe straight to Fluentd, Loki, or CloudWatch. |
+| **Non-destructive peek** | Inspect queue contents without consuming — broker requeues automatically after peek. |
+| **Graceful shutdown** | SIGTERM/SIGINT safe — finishes the current message before stopping. |
+| **Developer GUI** | PyQt6 desktop app for editing configs, viewing chains, peeking live queues, and browsing audit logs. |
+| **Plugin architecture** | Register custom actions via Python `entry_points` or a local `plugins/` directory. |
+| **Prometheus metrics** | Optional `prometheus_client` integration — zero-overhead when not installed. |
+| **Dry-run with diffs** | See exactly what `mutate_json` would change before committing. |
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+    EQ[("Error Queue")]
+    CL["Classifier\n(first match wins)"]
+    WF["WorkflowRunner"]
+    AU["AuditLogger\n(JSON-lines)"]
+
+    EQ -->|basic_get| CL
+    CL -->|matched rule| WF
+    CL -->|no match| UQ[("Unknown Queue")]
+    WF --> A1["log / set_headers\nmutate_json / python_script"]
+    A1 --> T{"Terminal\naction"}
+    T -->|republish| RQ[("Repaired Queue")]
+    T -->|quarantine| Q[("Quarantine Queue")]
+    T -->|route_unknown| UQ
+    T -->|drop| DONE["Ack + discard"]
+    WF --> AU
+    CL --> AU
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install -e ".[dev]"
+
+# 2. Set broker URL
+export RMQ_URL="amqp://guest:guest@localhost/"
+
+# 3. Generate config interactively
+rmq-healer configure --output config/queues.yml
+
+# 4. Validate
+rmq-healer validate --config config/queues.yml
+
+# 5. Test a rule against a sample message
+rmq-healer test-rule --config config/queues.yml \
+  --queue order-service.error --message examples/retry-timeout/sample.json
+
+# 6. Dry-run with mutation diffs — nothing acked or published
+rmq-healer dry-run --config config/queues.yml --all --pretty
+
+# 7. Live run
+rmq-healer run --config config/queues.yml --all --pretty
+
+# 8. Peek without consuming
+rmq-healer peek --config config/queues.yml --queue order-service.error --count 10
+
+# 9. Visualise a workflow as a Mermaid diagram
+rmq-healer workflow render --config config/queues.yml --queue order-service.error
+
+# 10. Search audit logs
+rmq-healer audit-search --log audit.jsonl --outcome quarantine
+```
+
+---
+
+## Example Configuration
+
+```yaml
+rabbitmq:
+  url: "${RMQ_URL}"
+  prefetch: 10
+
+idempotency:
+  enabled: true
+  max_handler_attempts: 3
+
+queues:
+  - name: order-service.error
+    enabled: true
+    rules_file: rules/order-errors.yml
+    repaired_exchange: order.events
+    repaired_routing_key: order.retry
+    quarantine_exchange: ops.errors
+    quarantine_routing_key: order.quarantine
+```
+
+```yaml
+# rules/order-errors.yml
+rules:
+  - id: transient_timeout
+    match:
+      any:
+        - body_contains: "ETIMEDOUT"
+        - json_path: $.error.code
+          equals: "TIMEOUT"
+    workflow:
+      - action: set_headers
+        params:
+          headers:
+            x-rmq-healer-rule: transient_timeout
+      - action: republish
+        params:
+          exchange: "{{ queue.repaired_exchange }}"
+          routing_key: "{{ queue.repaired_routing_key }}"
+
+  - id: missing_customer_id
+    match:
+      all:
+        - json_path: $.customer_id
+          equals: null
+    workflow:
+      - action: python_script
+        params:
+          script: scripts/lookup_customer.py
+          timeout: 30
+          output:
+            save_as: customer
+      - action: mutate_json
+        params:
+          set:
+            "$.customer_id": "{{ customer.id }}"
+      - action: republish
+        params:
+          exchange: "{{ queue.repaired_exchange }}"
+          routing_key: "{{ queue.repaired_routing_key }}"
+```
+
+See the `examples/` directory for complete, runnable scenarios.
+
+---
+
+## Documentation
+
+| Topic | Guide |
+|---|---|
+| Installation & setup | [docs/installation.md](docs/installation.md) |
+| Configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Writing rules | [docs/rules.md](docs/rules.md) |
+| Python script actions | [docs/python-scripts.md](docs/python-scripts.md) |
+| CLI reference (all commands) | [docs/cli-reference.md](docs/cli-reference.md) |
+| Operations guide | [docs/operations.md](docs/operations.md) |
+| Docker deployment | [docs/docker.md](docs/docker.md) |
+| Developer GUI | [docs/developer-gui.md](docs/developer-gui.md) |
+| Plugin architecture | [docs/plugins.md](docs/plugins.md) |
+| Metrics & observability | [docs/metrics.md](docs/metrics.md) |
+| Contributing & tooling | [docs/contributing.md](docs/contributing.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+
+> **[Browse all docs &rarr;](docs/README.md)**
+
+---
+
+## Developer Environment
+
+```powershell
+# Windows
+.\developer\scripts\setup.ps1      # start RabbitMQ + seed fixtures
+.\developer\scripts\run-test.ps1   # dry-run
+.\developer\scripts\launch-gui.ps1 # open GUI
+.\developer\scripts\teardown.ps1   # stop
+```
+
+```bash
+# Linux / macOS
+bash developer/scripts/setup.sh
+bash developer/scripts/run-test.sh
+bash developer/scripts/launch-gui.sh
+bash developer/scripts/teardown.sh
+
+# Or cross-platform Python
+python developer/scripts/dev_setup.py
+python developer/scripts/run_test.py
+python developer/scripts/launch_gui.py
+```
+
+---
+
+## License
+
+MIT &mdash; see [LICENSE](LICENSE).

rmq_healer-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rmq-healer"
+version = "0.1.0"
+description = "Abstract, extensible RabbitMQ error-queue remediation tool"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pika>=1.3",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "PyYAML>=6.0",
+    "jsonpath-ng>=1.6",
+    "Jinja2>=3.1",
+    "click>=8.1",
+]
+
+[project.scripts]
+rmq-healer = "rmq_healer.main:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+    "ruff>=0.4",
+    "mypy>=1.8",
+    "types-PyYAML",
+    "types-pika",
+]
+metrics = [
+    "prometheus-client>=0.19",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --cov=rmq_healer --cov-report=term-missing --cov-report=xml"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = false
+ignore_missing_imports = true
+no_strict_optional = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rmq_healer*"]

rmq_healer-0.1.0/rmq_healer/__init__.py

@@ -0,0 +1,3 @@
+"""RMQ Healer — abstract, extensible RabbitMQ error-queue remediation tool."""
+
+__version__ = "0.1.0"