cerberus-django 0.1.4__tar.gz

cerberus_django-0.1.4/.gitignore

@@ -0,0 +1,120 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project-specific
+*.pyc

cerberus_django-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Griffin Potrock
+
+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.

cerberus_django-0.1.4/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: cerberus-django
+Version: 0.1.4
+Summary: Django middleware for capturing and streaming HTTP request metrics via WebSocket
+Project-URL: Homepage, https://github.com/gpotrock/cerberus
+Project-URL: Documentation, https://github.com/gpotrock/cerberus#readme
+Project-URL: Repository, https://github.com/gpotrock/cerberus.git
+Project-URL: Issues, https://github.com/gpotrock/cerberus/issues
+Author: Griffin Potrock
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,async,django,metrics,middleware,monitoring,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: django>=4.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-django>=4.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cerberus Django
+
+[![PyPI version](https://badge.fury.io/py/cerberus-django.svg)](https://badge.fury.io/py/cerberus-django)
+[![Python Versions](https://img.shields.io/pypi/pyversions/cerberus-django.svg)](https://pypi.org/project/cerberus-django/)
+[![Django Versions](https://img.shields.io/badge/django-4.0%20%7C%204.1%20%7C%204.2%20%7C%205.0-blue.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Django middleware for capturing and streaming HTTP request metrics to a backend analytics server via WebSocket. Designed for high-performance, non-blocking operation in both WSGI and ASGI environments.
+
+## Features
+
+- **Non-blocking**: Events are queued and sent asynchronously via a background thread
+- **WSGI & ASGI Compatible**: Works with both synchronous and asynchronous Django deployments
+- **Privacy-First**: Built-in HMAC-SHA256 hashing for PII (IP addresses) before transmission
+- **Custom Metrics**: Attach application-specific metrics to any request
+- **Automatic Reconnection**: WebSocket client handles connection failures gracefully
+- **Zero Configuration Required**: Sensible defaults with optional customization
+
+## Installation
+
+```bash
+pip install cerberus-django
+```
+
+## Quick Start
+
+### 1. Add to Django Settings
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    # ... your apps
+]
+
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    # ... other middleware
+    'cerberus_django.CerberusMiddleware',  # Add Cerberus
+]
+
+# Cerberus Configuration
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://your-analytics-server.com/ws/events',
+    'token': 'your-api-key',
+    'client_id': 'your-client-id',
+}
+```
+
+### 2. That's It!
+
+Cerberus will now capture metrics for every HTTP request and send them to your analytics backend.
+
+## Configuration
+
+All configuration is done via the `CERBERUS_CONFIG` dictionary in your Django settings:
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `ws_url` | Yes | WebSocket URL for the analytics backend |
+| `token` | Yes | API key for authentication |
+| `client_id` | Yes | Unique identifier for your application |
+| `backend_url` | No | HTTP URL to auto-fetch the HMAC secret key |
+| `secret_key` | No | HMAC secret key for PII hashing (auto-fetched if `backend_url` is set) |
+
+### Example Configurations
+
+**Basic (no PII hashing):**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+}
+```
+
+**With automatic secret key fetching:**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+    'backend_url': 'https://analytics.example.com',  # Will fetch secret from /api/secret-key
+}
+```
+
+**With manual secret key:**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+    'secret_key': 'your-hmac-secret-key',  # For consistent PII hashing
+}
+```
+
+## Custom Metrics
+
+Attach custom metrics to any request by adding them to the response:
+
+```python
+from rest_framework.decorators import api_view
+from rest_framework.response import Response
+
+@api_view(['GET'])
+def my_endpoint(request):
+    # Your business logic
+    items = process_items()
+
+    response = Response({'items': items})
+
+    # Add custom metrics (will be included in the event)
+    response.data['_cerberus_metrics'] = {
+        'items_processed': len(items),
+        'cache_hit': True,
+        'processing_time_ms': 42,
+    }
+
+    return response
+```
+
+The `_cerberus_metrics` key is automatically extracted from the response and included in the event payload. It will not be sent to the client.
+
+## Event Payload
+
+Each event sent to your analytics backend includes:
+
+```json
+{
+    "api_key": "your-api-key",
+    "client_id": "your-client-id",
+    "token": "your-api-key",
+    "source_ip": "hashed-ip-address",
+    "endpoint": "/api/users/",
+    "scheme": true,
+    "method": "GET",
+    "custom_data": {
+        "items_processed": 10,
+        "cache_hit": true
+    }
+}
+```
+
+## Privacy & Security
+
+### PII Hashing
+
+When a `secret_key` is configured, source IP addresses are hashed using HMAC-SHA256 before transmission:
+
+- **Consistent**: Same IP always produces the same hash (enabling analytics)
+- **Irreversible**: Original IP cannot be recovered from the hash
+- **Secure**: Uses cryptographically strong HMAC-SHA256
+
+### What's Captured
+
+| Field | Description | Privacy |
+|-------|-------------|---------|
+| `source_ip` | Client IP address | Hashed if `secret_key` configured |
+| `endpoint` | Request path | Sent as-is |
+| `method` | HTTP method (GET, POST, etc.) | Sent as-is |
+| `scheme` | Whether HTTPS was used | Sent as-is |
+| `custom_data` | Your custom metrics | Sent as-is |
+
+### What's NOT Captured
+
+- Request/response bodies
+- HTTP headers
+- Query parameters
+- Cookies or session data
+- Authentication tokens
+
+## Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export CERBERUS_DEBUG=true
+```
+
+Or in your Django settings:
+
+```python
+import os
+os.environ['CERBERUS_DEBUG'] = 'true'
+```
+
+This will log:
+- Middleware initialization
+- WebSocket connection attempts
+- Events being queued and sent
+- Any errors encountered
+
+## Architecture
+
+```
+┌─────────────────────────┐     ┌──────────────────────────────┐
+│   Django Request        │     │   Background Thread          │
+│   (WSGI or ASGI)        │     │   (Daemon)                   │
+├─────────────────────────┤     ├──────────────────────────────┤
+│ CerberusMiddleware      │     │  Event Loop                  │
+│   └── queue.put(event)  │────▶│    └── WebSocket.send()     │
+└─────────────────────────┘     └──────────────────────────────┘
+         │                                    │
+         │  Thread-safe Queue                 │  Async WebSocket
+         └────────────────────────────────────┘
+```
+
+- **Middleware**: Runs synchronously in the request/response cycle
+- **Queue**: Thread-safe `queue.Queue` for passing events
+- **Background Thread**: Daemon thread with its own event loop for async WebSocket communication
+
+This architecture ensures:
+- No blocking of HTTP requests
+- No event loop conflicts in WSGI mode
+- Automatic cleanup when the process exits (daemon thread)
+
+## Requirements
+
+- Python 3.9+
+- Django 4.0+
+- websockets 12.0+
+- requests 2.28+
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/gpotrock/cerberus.git
+cd cerberus
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black src/
+ruff check src/ --fix
+
+# Type checking
+mypy src/
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request

cerberus_django-0.1.4/README.md

@@ -0,0 +1,257 @@
+# Cerberus Django
+
+[![PyPI version](https://badge.fury.io/py/cerberus-django.svg)](https://badge.fury.io/py/cerberus-django)
+[![Python Versions](https://img.shields.io/pypi/pyversions/cerberus-django.svg)](https://pypi.org/project/cerberus-django/)
+[![Django Versions](https://img.shields.io/badge/django-4.0%20%7C%204.1%20%7C%204.2%20%7C%205.0-blue.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Django middleware for capturing and streaming HTTP request metrics to a backend analytics server via WebSocket. Designed for high-performance, non-blocking operation in both WSGI and ASGI environments.
+
+## Features
+
+- **Non-blocking**: Events are queued and sent asynchronously via a background thread
+- **WSGI & ASGI Compatible**: Works with both synchronous and asynchronous Django deployments
+- **Privacy-First**: Built-in HMAC-SHA256 hashing for PII (IP addresses) before transmission
+- **Custom Metrics**: Attach application-specific metrics to any request
+- **Automatic Reconnection**: WebSocket client handles connection failures gracefully
+- **Zero Configuration Required**: Sensible defaults with optional customization
+
+## Installation
+
+```bash
+pip install cerberus-django
+```
+
+## Quick Start
+
+### 1. Add to Django Settings
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    # ... your apps
+]
+
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    # ... other middleware
+    'cerberus_django.CerberusMiddleware',  # Add Cerberus
+]
+
+# Cerberus Configuration
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://your-analytics-server.com/ws/events',
+    'token': 'your-api-key',
+    'client_id': 'your-client-id',
+}
+```
+
+### 2. That's It!
+
+Cerberus will now capture metrics for every HTTP request and send them to your analytics backend.
+
+## Configuration
+
+All configuration is done via the `CERBERUS_CONFIG` dictionary in your Django settings:
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `ws_url` | Yes | WebSocket URL for the analytics backend |
+| `token` | Yes | API key for authentication |
+| `client_id` | Yes | Unique identifier for your application |
+| `backend_url` | No | HTTP URL to auto-fetch the HMAC secret key |
+| `secret_key` | No | HMAC secret key for PII hashing (auto-fetched if `backend_url` is set) |
+
+### Example Configurations
+
+**Basic (no PII hashing):**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+}
+```
+
+**With automatic secret key fetching:**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+    'backend_url': 'https://analytics.example.com',  # Will fetch secret from /api/secret-key
+}
+```
+
+**With manual secret key:**
+```python
+CERBERUS_CONFIG = {
+    'ws_url': 'wss://analytics.example.com/ws/events',
+    'token': 'sk-your-api-key',
+    'client_id': 'my-django-app',
+    'secret_key': 'your-hmac-secret-key',  # For consistent PII hashing
+}
+```
+
+## Custom Metrics
+
+Attach custom metrics to any request by adding them to the response:
+
+```python
+from rest_framework.decorators import api_view
+from rest_framework.response import Response
+
+@api_view(['GET'])
+def my_endpoint(request):
+    # Your business logic
+    items = process_items()
+
+    response = Response({'items': items})
+
+    # Add custom metrics (will be included in the event)
+    response.data['_cerberus_metrics'] = {
+        'items_processed': len(items),
+        'cache_hit': True,
+        'processing_time_ms': 42,
+    }
+
+    return response
+```
+
+The `_cerberus_metrics` key is automatically extracted from the response and included in the event payload. It will not be sent to the client.
+
+## Event Payload
+
+Each event sent to your analytics backend includes:
+
+```json
+{
+    "api_key": "your-api-key",
+    "client_id": "your-client-id",
+    "token": "your-api-key",
+    "source_ip": "hashed-ip-address",
+    "endpoint": "/api/users/",
+    "scheme": true,
+    "method": "GET",
+    "custom_data": {
+        "items_processed": 10,
+        "cache_hit": true
+    }
+}
+```
+
+## Privacy & Security
+
+### PII Hashing
+
+When a `secret_key` is configured, source IP addresses are hashed using HMAC-SHA256 before transmission:
+
+- **Consistent**: Same IP always produces the same hash (enabling analytics)
+- **Irreversible**: Original IP cannot be recovered from the hash
+- **Secure**: Uses cryptographically strong HMAC-SHA256
+
+### What's Captured
+
+| Field | Description | Privacy |
+|-------|-------------|---------|
+| `source_ip` | Client IP address | Hashed if `secret_key` configured |
+| `endpoint` | Request path | Sent as-is |
+| `method` | HTTP method (GET, POST, etc.) | Sent as-is |
+| `scheme` | Whether HTTPS was used | Sent as-is |
+| `custom_data` | Your custom metrics | Sent as-is |
+
+### What's NOT Captured
+
+- Request/response bodies
+- HTTP headers
+- Query parameters
+- Cookies or session data
+- Authentication tokens
+
+## Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export CERBERUS_DEBUG=true
+```
+
+Or in your Django settings:
+
+```python
+import os
+os.environ['CERBERUS_DEBUG'] = 'true'
+```
+
+This will log:
+- Middleware initialization
+- WebSocket connection attempts
+- Events being queued and sent
+- Any errors encountered
+
+## Architecture
+
+```
+┌─────────────────────────┐     ┌──────────────────────────────┐
+│   Django Request        │     │   Background Thread          │
+│   (WSGI or ASGI)        │     │   (Daemon)                   │
+├─────────────────────────┤     ├──────────────────────────────┤
+│ CerberusMiddleware      │     │  Event Loop                  │
+│   └── queue.put(event)  │────▶│    └── WebSocket.send()     │
+└─────────────────────────┘     └──────────────────────────────┘
+         │                                    │
+         │  Thread-safe Queue                 │  Async WebSocket
+         └────────────────────────────────────┘
+```
+
+- **Middleware**: Runs synchronously in the request/response cycle
+- **Queue**: Thread-safe `queue.Queue` for passing events
+- **Background Thread**: Daemon thread with its own event loop for async WebSocket communication
+
+This architecture ensures:
+- No blocking of HTTP requests
+- No event loop conflicts in WSGI mode
+- Automatic cleanup when the process exits (daemon thread)
+
+## Requirements
+
+- Python 3.9+
+- Django 4.0+
+- websockets 12.0+
+- requests 2.28+
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/gpotrock/cerberus.git
+cd cerberus
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black src/
+ruff check src/ --fix
+
+# Type checking
+mypy src/
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request

cerberus_django-0.1.4/publish_package.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+cd /Users/griff/Documents/cerberus_code/cerberus
+
+# Clean old builds
+rm -rf dist/ build/ *.egg-info src/*.egg-info
+
+# Build the package
+python -m build
+
+# Upload to PyPI
+python -m twine upload dist/*

cerberus_django-0.1.4/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cerberus-django"
+version = "0.1.4"
+description = "Django middleware for capturing and streaming HTTP request metrics via WebSocket"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Griffin Potrock" }
+]
+keywords = [
+    "django",
+    "middleware",
+    "metrics",
+    "analytics",
+    "monitoring",
+    "websocket",
+    "async",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.0",
+    "Framework :: Django :: 4.1",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware",
+    "Topic :: System :: Monitoring",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "django>=4.0",
+    "websockets>=12.0",
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-django>=4.5",
+    "black>=23.0",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gpotrock/cerberus"
+Documentation = "https://github.com/gpotrock/cerberus#readme"
+Repository = "https://github.com/gpotrock/cerberus.git"
+Issues = "https://github.com/gpotrock/cerberus/issues"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.github",
+    "/tests",
+    "CLAUDE.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cerberus_django"]
+
+[tool.black]
+line-length = 100
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"

cerberus_django-0.1.4/src/cerberus_django/__init__.py

@@ -0,0 +1,13 @@
+"""
+Cerberus Django - HTTP request metrics middleware
+
+A Django middleware for capturing and streaming HTTP request metrics
+to a backend analytics server via WebSocket.
+"""
+
+from .middleware import CerberusMiddleware
+from .structs import CoreData
+from .utils import hash_pii
+
+__version__ = "0.1.4"
+__all__ = ["CerberusMiddleware", "CoreData", "hash_pii", "__version__"]

cerberus_django-0.1.4/src/cerberus_django/middleware.py

@@ -0,0 +1,410 @@
+"""
+Cerberus Django Middleware
+
+Captures HTTP request metrics and sends them asynchronously to a backend
+analytics server via WebSocket.
+
+This middleware is designed to work in both WSGI (synchronous) and ASGI
+(asynchronous) Django deployments without requiring an event loop at import time.
+
+Architecture:
+- Middleware (sync): Captures request data and puts it in a thread-safe queue
+- Background thread: Runs its own event loop to process queue and send via WebSocket
+"""
+
+from .structs import CoreData
+from .utils import fetch_secret_key
+from django.conf import settings
+import asyncio
+import json
+import os
+import logging
+import threading
+import queue as thread_queue
+from datetime import datetime, timezone
+import websockets
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+# Enable debug logging via environment variable
+DEBUG_ENABLED = os.getenv('CERBERUS_DEBUG', 'false').lower() in ('true', '1', 'yes')
+
+# Thread-safe queue for events (no event loop required at import time)
+event_queue = thread_queue.Queue()
+
+# Background thread management
+_background_thread = None
+_thread_lock = threading.Lock()
+
+
+class AsyncWebSocketClient:
+    """WebSocket client for sending events to the backend.
+
+    This client is used within the background thread's event loop,
+    so it can safely use asyncio primitives.
+    """
+
+    def __init__(self, ws_url, api_key, client_id):
+        self.ws_url = ws_url
+        self.api_key = api_key
+        self.client_id = client_id
+        self.websocket = None
+        self._async_lock = None  # Created lazily within event loop context
+
+    async def _get_lock(self):
+        """Get or create async lock within the event loop context."""
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        return self._async_lock
+
+    async def connect(self):
+        """Establish WebSocket connection to the backend."""
+        try:
+            if DEBUG_ENABLED:
+                logger.info(f"[Cerberus] Connecting to WebSocket: {self.ws_url}")
+            self.websocket = await websockets.connect(self.ws_url)
+            if DEBUG_ENABLED:
+                logger.info("[Cerberus] WebSocket connected successfully")
+        except Exception as e:
+            self.websocket = None
+            logger.error(f"[Cerberus] Failed to connect to WebSocket: {e}")
+
+    async def send(self, event_data):
+        """Send event data to backend via WebSocket.
+
+        Args:
+            event_data: CoreData object to send
+        """
+        lock = await self._get_lock()
+        async with lock:
+            # Connect if not already connected
+            if self.websocket is None:
+                await self.connect()
+
+            if self.websocket:
+                try:
+                    # Format data as expected by backend
+                    payload = {
+                        'api_key': self.api_key,
+                        'client_id': self.client_id,
+                        'token': event_data.token,
+                        'remote_addr': event_data.source_ip,  # Backend expects 'remote_addr'
+                        'endpoint': event_data.endpoint,
+                        'scheme': event_data.scheme,
+                        'method': event_data.method,
+                        'timestamp': event_data.timestamp,
+                        'custom_data': event_data.custom_data,
+                        # Additional request details
+                        'headers': event_data.headers,
+                        'query_params': event_data.query_params,
+                        'body': event_data.body,
+                        'user_agent': event_data.user_agent,
+                    }
+
+                    json_data = json.dumps(payload)
+
+                    if DEBUG_ENABLED:
+                        logger.info(f"[Cerberus] Sending event to backend: {json_data[:200]}...")
+
+                    await self.websocket.send(json_data)
+
+                    # Wait for acknowledgment
+                    response = await asyncio.wait_for(self.websocket.recv(), timeout=5.0)
+
+                    if DEBUG_ENABLED:
+                        logger.info(f"[Cerberus] Backend response: {response}")
+
+                except asyncio.TimeoutError:
+                    logger.warning("[Cerberus] Timeout waiting for backend response")
+                except websockets.exceptions.ConnectionClosed:
+                    logger.warning("[Cerberus] WebSocket connection closed, will reconnect on next send")
+                    self.websocket = None
+                except Exception as e:
+                    logger.error(f"[Cerberus] Error sending data: {e}")
+                    if self.websocket:
+                        try:
+                            await self.websocket.close()
+                        except Exception:
+                            pass
+                    self.websocket = None
+
+
+# WebSocket client - initialized in middleware __init__, used by background thread
+WS_CLIENT = None
+
+
+def _queue_get_with_timeout():
+    """Get an item from the queue with a 1-second timeout.
+
+    This is a helper function for run_in_executor since we need to pass
+    the timeout parameter.
+
+    Returns:
+        CoreData object or raises queue.Empty
+    """
+    return event_queue.get(block=True, timeout=1.0)
+
+
+async def _process_queue_async():
+    """Async coroutine that processes events from the thread-safe queue.
+
+    Runs continuously in the background thread's event loop.
+    """
+    global WS_CLIENT
+
+    if DEBUG_ENABLED:
+        logger.info("[Cerberus] Background queue processor started")
+
+    loop = asyncio.get_event_loop()
+
+    while True:
+        try:
+            # Use run_in_executor to get from sync queue without blocking event loop
+            data = await loop.run_in_executor(None, _queue_get_with_timeout)
+        except thread_queue.Empty:
+            # No events available, continue waiting
+            continue
+        except Exception as e:
+            logger.error(f"[Cerberus] Error getting from queue: {e}")
+            continue
+
+        # Check for shutdown signal (None means stop)
+        if data is None:
+            if DEBUG_ENABLED:
+                logger.info("[Cerberus] Received shutdown signal, stopping processor")
+            break
+
+        try:
+            if WS_CLIENT:
+                if DEBUG_ENABLED:
+                    logger.info(f"[Cerberus] Processing event for endpoint: {data.endpoint}")
+                await WS_CLIENT.send(data)
+            else:
+                logger.warning("[Cerberus] WebSocket client not initialized, skipping event")
+        except Exception as e:
+            logger.error(f"[Cerberus] Failed to send event: {e}")
+        finally:
+            event_queue.task_done()
+
+
+def _run_event_loop_in_thread():
+    """Run the async event processing loop in a dedicated thread.
+
+    Creates its own event loop, independent of any Django event loop.
+    """
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    if DEBUG_ENABLED:
+        logger.info("[Cerberus] Background thread started with new event loop")
+
+    try:
+        loop.run_until_complete(_process_queue_async())
+    except Exception as e:
+        logger.error(f"[Cerberus] Background event loop error: {e}")
+    finally:
+        loop.close()
+        if DEBUG_ENABLED:
+            logger.info("[Cerberus] Background thread event loop closed")
+
+
+def ensure_background_thread():
+    """Start the background processing thread if not already running.
+
+    Thread-safe: Uses a lock to prevent race conditions during startup.
+    The thread is a daemon thread, so it will automatically stop when
+    the main process exits.
+    """
+    global _background_thread
+
+    with _thread_lock:
+        if _background_thread is not None and _background_thread.is_alive():
+            return
+
+        _background_thread = threading.Thread(
+            target=_run_event_loop_in_thread,
+            name="cerberus-event-sender",
+            daemon=True  # Auto-shutdown when main process exits
+        )
+        _background_thread.start()
+
+        if DEBUG_ENABLED:
+            logger.info("[Cerberus] Started background event sender thread")
+
+
+def _extract_headers(request):
+    """Extract HTTP headers from Django request.
+
+    Converts Django's META dict (with HTTP_ prefixed headers) to a clean dict.
+    Only includes actual HTTP headers, not server variables.
+
+    Args:
+        request: Django HttpRequest object
+
+    Returns:
+        Dict of header name -> value
+    """
+    headers = {}
+    for key, value in request.META.items():
+        if key.startswith('HTTP_'):
+            # Convert HTTP_CONTENT_TYPE to Content-Type
+            header_name = key[5:].replace('_', '-').title()
+            headers[header_name] = value
+        elif key in ('CONTENT_TYPE', 'CONTENT_LENGTH'):
+            # These don't have HTTP_ prefix but are still headers
+            header_name = key.replace('_', '-').title()
+            headers[header_name] = value
+    return headers if headers else None
+
+
+def _extract_query_params(request):
+    """Extract query parameters from Django request.
+
+    Args:
+        request: Django HttpRequest object
+
+    Returns:
+        Dict of query param name -> value (or list of values if multiple)
+    """
+    if not request.GET:
+        return None
+
+    params = {}
+    for key in request.GET:
+        values = request.GET.getlist(key)
+        params[key] = values[0] if len(values) == 1 else values
+    return params
+
+
+def _extract_body(request):
+    """Extract request body from Django request.
+
+    Only attempts to parse JSON bodies. Returns None for non-JSON content.
+
+    Args:
+        request: Django HttpRequest object
+
+    Returns:
+        Parsed JSON body as dict, or None
+    """
+    if request.method not in ('POST', 'PUT', 'PATCH'):
+        return None
+
+    content_type = request.content_type or ''
+    if 'application/json' not in content_type:
+        return None
+
+    try:
+        if request.body:
+            return json.loads(request.body.decode('utf-8'))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        pass
+
+    return None
+
+
+class CerberusMiddleware:
+    """Django middleware for capturing and sending HTTP request metrics.
+
+    Compatible with both WSGI and ASGI Django deployments.
+
+    Configuration via CERBERUS_CONFIG in Django settings:
+        - token: API key for authentication
+        - client_id: Client identifier
+        - ws_url: WebSocket URL for event_ingest backend
+        - backend_url: HTTP URL for fetching secret key (optional)
+        - secret_key: HMAC key for PII hashing (optional, auto-fetched if backend_url set)
+    """
+
+    def __init__(self, get_response):
+        global WS_CLIENT
+
+        self.get_response = get_response
+        self.config = getattr(settings, 'CERBERUS_CONFIG', {})
+
+        if DEBUG_ENABLED:
+            logger.info("[Cerberus] Middleware initializing...")
+            logger.info(f"[Cerberus] Config keys: {list(self.config.keys())}")
+
+        # Auto-fetch secret_key from backend if not configured locally
+        if 'secret_key' not in self.config and 'backend_url' in self.config:
+            if DEBUG_ENABLED:
+                logger.info(f"[Cerberus] Fetching secret key from backend: {self.config['backend_url']}")
+            secret_key = fetch_secret_key(
+                self.config['backend_url'],
+                self.config.get('token', '')
+            )
+            if secret_key:
+                self.config['secret_key'] = secret_key
+                logger.info(f"[Cerberus] Successfully fetched secret key from {self.config['backend_url']}")
+            else:
+                logger.warning("[Cerberus] Failed to fetch secret key. PII will not be hashed.")
+
+        # Initialize WebSocket client
+        if 'ws_url' in self.config and 'token' in self.config and 'client_id' in self.config:
+            WS_CLIENT = AsyncWebSocketClient(
+                self.config['ws_url'],
+                self.config['token'],
+                self.config['client_id']
+            )
+            if DEBUG_ENABLED:
+                logger.info(f"[Cerberus] WebSocket client initialized: {self.config['ws_url']}")
+        else:
+            logger.warning("[Cerberus] WebSocket client not initialized. Missing ws_url, token, or client_id in CERBERUS_CONFIG")
+
+        # Start background thread for processing events
+        ensure_background_thread()
+
+    def __call__(self, request):
+        """Process a request and queue metrics for async transmission.
+
+        This method is synchronous and does not require an event loop.
+        Events are placed in a thread-safe queue and processed by the
+        background thread.
+        """
+        # Initialize custom_data attribute on the request object
+        request.cerberus_metrics = {}
+
+        # Extract request data BEFORE processing (body can only be read once)
+        headers = _extract_headers(request)
+        query_params = _extract_query_params(request)
+        body = _extract_body(request)
+        user_agent = request.META.get('HTTP_USER_AGENT')
+
+        # Process the request
+        response = self.get_response(request)
+
+        # Extract metrics from response if they exist
+        metrics = {}
+        if hasattr(response, 'data') and isinstance(response.data, dict):
+            if '_cerberus_metrics' in response.data:
+                metrics = response.data.pop('_cerberus_metrics')
+
+        # Get source IP address
+        source_ip = request.META.get('REMOTE_ADDR')
+
+        # Create the event data with current timestamp
+        d = CoreData(
+            token=self.config.get('token', ''),
+            source_ip=source_ip,
+            endpoint=request.path,
+            scheme=request.scheme == 'https',
+            method=request.method,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            custom_data=metrics,
+            headers=headers,
+            query_params=query_params,
+            body=body,
+            user_agent=user_agent,
+        )
+
+        # Queue the event (non-blocking)
+        try:
+            event_queue.put_nowait(d)
+            if DEBUG_ENABLED:
+                logger.info(f"[Cerberus] Queued event: {request.method} {request.path}")
+        except thread_queue.Full:
+            logger.warning("[Cerberus] Event queue full, dropping event")
+
+        return response

cerberus_django-0.1.4/src/cerberus_django/structs.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class CoreData:
+    """Data structure for HTTP request metrics.
+
+    Captures essential request information for analytics and monitoring.
+    """
+    token: str
+    source_ip: str
+    endpoint: str
+    scheme: bool
+    method: str
+    timestamp: str  # ISO 8601 format timestamp
+    custom_data: Optional[Dict] = None
+
+    # Additional request details
+    headers: Optional[Dict] = None
+    query_params: Optional[Dict] = None
+    body: Optional[Dict] = None
+    user_agent: Optional[str] = None

cerberus_django-0.1.4/src/cerberus_django/utils.py

@@ -0,0 +1,70 @@
+import hmac
+import hashlib
+import requests
+import os
+import logging
+from typing import Optional
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+# Enable debug logging via environment variable
+DEBUG_ENABLED = os.getenv('CERBERUS_DEBUG', 'false').lower() in ('true', '1', 'yes')
+
+def hash_pii(value, secret_key):
+    """
+    Consistently hash PII using HMAC-SHA256 for pseudoanonymization.
+
+    Args:
+        value: The PII string to hash (e.g., IP address)
+        secret_key: Secret key for HMAC (from CERBERUS_CONFIG['secret_key'])
+
+    Returns:
+        Hex-encoded HMAC digest string
+    """
+    if value is None:
+        return None
+
+    # Convert both to bytes if they aren't already
+    if isinstance(value, str):
+        value = value.encode('utf-8')
+    if isinstance(secret_key, str):
+        secret_key = secret_key.encode('utf-8')
+
+    return hmac.new(secret_key, value, hashlib.sha256).hexdigest()
+
+def fetch_secret_key(backend_url: str, api_key: str, timeout: int = 5) -> Optional[str]:
+    """
+    Fetch the shared HMAC secret key from the backend server.
+
+    Args:
+        backend_url: Base URL of the backend server (e.g., 'https://cerberus.example.com')
+        api_key: Client API key for authentication
+        timeout: Request timeout in seconds (default: 5)
+
+    Returns:
+        The secret key string, or None if fetch fails
+
+    Raises:
+        requests.RequestException: On network/HTTP errors
+    """
+    try:
+        url = f"{backend_url.rstrip('/')}/api/secret-key"
+        if DEBUG_ENABLED:
+            logger.info(f"[Cerberus] Making HTTP request to fetch secret key: {url}")
+
+        response = requests.get(
+            url,
+            headers={'X-API-Key': api_key},
+            timeout=timeout
+        )
+
+        if DEBUG_ENABLED:
+            logger.info(f"[Cerberus] Secret key fetch response: {response.status_code}")
+
+        response.raise_for_status()
+        data = response.json()
+        return data.get('secret_key')
+    except requests.RequestException as e:
+        logger.error(f"[Cerberus] Failed to fetch secret key from {backend_url}: {e}")
+        return None