Django Broadcaster

A Django app that implements the transactional outbox pattern with CloudEvents support, enabling reliable event publishing in distributed systems.

Features

• 🔄 Transactional Broadcaster Pattern: Ensures events are published reliably
• ☁️ CloudEvents Compatible: Follows CloudEvents specification
• 🔌 Multiple Backends: Redis Streams, Kafka, NATS support
• 🔁 Retry Logic: Exponential backoff with configurable retries
• 🔑 Idempotency: Prevents duplicate event processing
• 📊 Monitoring: Built-in metrics and health checks
• 🎯 Event Handlers: Local event processing framework
• 🔧 Admin Interface: Django admin integration

Quick Start

Installation

# Using pip
pip install django-broadcaster

# Using uv
uv add django-broadcaster

Configuration

Add to your Django settings:

INSTALLED_APPS = [
    # ... your other apps
    'django_broadcaster',
]

OUTBOX_PUBLISHERS = {
    'default': {
        'BACKEND': 'django_broadcaster.backends.RedisStreamBackend',
        'OPTIONS': {
            'host': 'localhost',
            'port': 6379,
            'stream_name': 'events',
        }
    }
}

Usage

from django_broadcaster.publishers import publisher

# Publish an event
event = publisher.publish_event(
    event_type='user.created',
    source='user-service',
    data={'user_id': 123, 'email': 'user@example.com'}
)

# Register event handler
from django_broadcaster.registry import event_registry

@event_registry.register('user.created')
def handle_user_created(event):
    print(f"User created: {event.data}")

Running the Worker

python manage.py outbox_worker

Documentation

Full documentation is available at https://django-broadcaster.readthedocs.io/en/latest/.

Building and Serving Documentation Locally

To build the documentation locally:

# Build the documentation
make docs-build

# Serve the documentation locally at http://localhost:8080
make docs-serve

After running make docs-serve, you can access the documentation by opening http://localhost:8080 in your web browser.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.