How fanout/django-eventstream works
Project type and purpose
• This is a reusable Django library (django-eventstream) that adds Server-Sent Events (SSE) support to any Django project.
• It exposes Django views and DRF viewsets to stream real-time events over HTTP, with optional persistence (database) and scalability (Redis or GRIP proxy).
File structure
• Top-level module: django_eventstream/
• channelmanager.py – authorization hooks for per-user channels
• event*.py & eventstream.py – core request/response and stream handling
• storage.py & migrations – optional DB persistence of events
• renderers/ – SSE and browsable-API renderers for DRF integration
• static/ + templates/ – client-side JS/CSS for browsers
• views.py, viewsets.py – Django and DRF endpoints
• management/commands – utilities, e.g. runserver_ngrok
• examples/ – three sample Django projects demonstrating basic usage, DRF integration, and templating
• tests/ – unit tests for storage and streaming
Extract additional insights from README
• Protocol: Clients connect with “Accept: text/event-stream” to long-running HTTP GET.
• send_event API publishes to channels.
• Scaling options:
• Single process (no storage): events lost on disconnect
• Database storage via DjangoModelStorage for reliable delivery
• Redis pub/sub or GRIP proxy (Pushpin/Fanout) for multi-instance architectures
• DRF integration: configurable EventsViewSet + custom SSE renderers
• Client layer
• Browser or native app with EventSource / ReconnectingEventSource libraries
• Ingress / Edge
• (Optional) Load Balancer or API Gateway
• (Optional) GRIP proxy (e.g., Pushpin) for connection offloading
• Application server
• ASGI server (Daphne) running Django + django_eventstream
• Django middleware stack (including GripMiddleware if used)
• URL router → SSE endpoints (django_eventstream.urls)
• DRF router → EventsViewSet (if DRF used)
• Event pipeline
• send_event() call → ChannelManager authorization → storage layer → publish to subscribers
• Storage & pub/sub
• Primary database (PostgreSQL/MySQL) for models & optional DjangoModelStorage
• Redis (optional) for cross-instance pub/sub
• External services
• GRIP proxy (Pushpin or Fastly Fanout)
• Redis server
• Upstream data sources (your app code that calls send_event)
b. Relationships & data flows
• Client GET → Load Balancer → (GRIP proxy) → Daphne
• Event request enters Django, passes through ChannelManager
• Long-running HTTP connection held open by Daphne/GRIP
• send_event in application code pushes event into storage or Redis
• Subscriber loop in django_eventstream fetches new events → SSE frames → client
• On multiple instances, Redis or GRIP proxy fan-out events across all backends
c. Architectural patterns & design principles
• Pub/Sub (channels)
• Event sourcing with optional persistent store
• Plug-in architecture: channel managers, storage backends, renderers
• ASGI for long-lived connections
• Integration with DRF via viewsets and renderers
d. Key technologies & frameworks
• Python, Django, ASGI, Daphne
• Django REST Framework (optional)
• Redis (optional)
• GRIP protocol / Pushpin (optional)
• PostgreSQL / MySQL / SQLite for event storage
• Browser EventSource / reconnecting-eventsource.js
Final advice
• Be exhaustive in listing the components the library provides and integrates with
• Both the control flow (authorization, routing) and data flow (event publish/subscribe)
• Extension points: custom ChannelManager, storage backends, renderer classes
• Iterate as you confirm which features (Redis, GRIP, DRF) are enabled in a given deployment