django-sio

Socket.IO for Django, powered by Channels and compatible with the official Socket.IO clients.

django-sio implements the Socket.IO v5 protocol on top of an in-process Engine.IO v4 server, using Django Channels for HTTP/WebSocket handling and broadcasts.

It is designed to work with the official Socket.IO clients: browser JavaScript, Node.js, python-socketio, and other Socket.IO-compatible clients.

What this gives you

• A Socket.IO server running inside Django/Channels.

• Support for both WebSocket and HTTP long-polling.

• A simple, class-based consumer API:

  • connect(self, socket, auth)

  • disconnect(self, socket, reason)

  • event_<name>(self, socket, *args, ack=None)

If you already know Socket.IO from Node.js, this behaves very similarly on the server side, but lives inside your Django project.

Getting started

New to the project? Start with Introduction, then follow the Tutorial.

Already using Django Channels? Jump to Installation and Routing.

Contents

First steps

• Introduction
  • Mental model
  • Where Channels fits
  • What you normally write
  • What this project is not
• Installation
  • Install the package
  • Django settings
  • ASGI routing
  • Next steps
• Tutorial
  • What you will build
  • Tutorial parts

Topics

• Consumers
  • Basic layout
  • Connection handling
  • Disconnect handling
  • Event handlers
  • Event arguments
  • Acknowledgements
  • Consumer registration
• Routing
  • Recommended endpoint
  • Complete ASGI example
  • Why HTTP routing is required
  • Why WebSocket routing is required
  • Middleware
  • Fallback to Django HTTP
• Clients
  • Browser JavaScript
  • Path and namespace
  • Transport selection
  • Python client
  • Authentication payloads
• Configuration
  • Engine.IO timing and payload limits
• Logging and debugging
  • Logger names
  • Enable debug logging
  • What you will see
  • Production logging
• Architecture overview
  • Transport flow
  • Engine.IO layer
  • Socket.IO layer
  • Consumer integration
• Deployment and scaling
  • What in-memory sessions mean
  • Production requirement
  • Channel layer role
  • ASGI servers
  • Future session storage
• Testing and development
  • Unit tests
  • Integration tests
  • Run tests
  • Coverage
  • Development logging
  • Transport matrix

How-to guides

• Add django-sio to an existing Django project
  • 1. Install dependencies
  • 2. Enable Channels
  • 3. Add a consumer
  • 4. Route Socket.IO before Django HTTP fallback
  • 5. Connect a client
• Broadcast from event handlers
  • Join a room
  • Leave a room
  • Broadcast to a room
  • Why namespace matters
  • Broadcast only to the current client
• Production checklist
  • Routing
  • Workers and sessions
  • Channel layer
  • Timeouts
  • Payloads
  • Logging
  • Tests

Reference

• Consumer API reference
  • SocketIOConsumer
• Socket API reference
  • Common attributes
  • Common methods
  • Server emits
• Settings reference
  • SIO_ENGINEIO_PING_INTERVAL_MS
  • SIO_ENGINEIO_PING_TIMEOUT_MS
  • SIO_ENGINEIO_MAX_PAYLOAD_BYTES
  • Import-time behaviour
  • Used by
• Protocol layers reference
  • ASGI and Channels
  • Engine.IO
  • Socket.IO
  • Consumer API
• Loggers reference
  • Logger hierarchy
  • Suggested development level
  • Suggested production level