Protocol layers reference

django-sio has three main layers above the ASGI server.

ASGI and Channels

The ASGI server accepts HTTP and WebSocket connections. Django Channels routes those scopes to the ASGI application returned by SocketIOConsumer.as_asgi().

Engine.IO

Engine.IO provides transport-level behaviour:

  • query parsing for EIO=4 and transport=...;

  • HTTP long-polling;

  • WebSocket transport;

  • polling-to-WebSocket upgrade;

  • ping/pong heartbeats;

  • per-connection session state;

  • packet and payload encoding.

Implemented in sio.engineio.

Socket.IO

Socket.IO provides application-level semantics:

  • namespaces;

  • events;

  • acknowledgements;

  • rooms;

  • room broadcasts;

  • packet parsing and encoding;

  • binary attachment handling and placeholder substitution.

Implemented in sio.socketio.

Consumer API

The consumer API is the application-facing layer:

class ChatConsumer(SocketIOConsumer):
    namespace = "/chat"

    async def connect(self, socket, auth):
        return True

    async def event_chat_message(self, socket, payload, ack=None):
        ...

Most application code should stay at this layer.