Skip to content

7B. The ASGI stack


WSGI vs ASGI

WSGI ASGI
Standard PEP 3333 (2010) ASGI specification (asgi.readthedocs.io, not a PEP)
Protocols HTTP only HTTP + WebSocket + others
Model Synchronous (one request = one thread) Asynchronous (coroutines)
Servers Gunicorn, uWSGI Uvicorn, Daphne, Hypercorn
Django Standard runserver Requires an ASGI application + channels
WebSocket ❌ Not supported ✅ Natively

Architecture of the notes_chat_app ASGI stack

Browser (HTTP)          Browser (WebSocket)
      │                        │
      ▼                        ▼
   nginx :80  (reverse proxy — forwards requests)
      │                        │
      ▼                        ▼
   Uvicorn ASGI :8001  (one process — both protocols)
      │
      ▼
   ProtocolTypeRouter  (notes_project/asgi.py)
      │
      ├── protocol == "http"
      │       ▼
      │   Django HTTP app (views.py, urls.py, templates)
      │
      └── protocol == "websocket"
              ▼
          AuthMiddlewareStack
              ▼
          WebSocket URLRouter  (notes_project/routing.py)
              ▼
          GroupChatConsumer  (notes_app/consumers.py)
              │
              ├──► PostgreSQL (via database_sync_to_async)
              └──► InMemoryChannelLayer / RedisChannelLayer (pub/sub)
Component Role Equivalent in HTTP Django
ProtocolTypeRouter Distinguishes HTTP and WS by protocol type ROOT_URLCONF
AuthMiddlewareStack Reads the session cookie → scope['user'] @login_required decorator
WebSocket URLRouter Routes a WS URL to a Consumer urls.py
GroupChatConsumer Handles the WS connection for its whole lifetime view (but lives longer)
InMemoryChannelLayer Pub/sub broadcast between consumers (no direct equivalent)

asgi.py — the entry point

# notes_project/asgi.py
import os
from django.core.asgi import get_asgi_application
from django.contrib.staticfiles.handlers import ASGIStaticFilesHandler

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'notes_project.settings')

# CRITICAL: get_asgi_application() BEFORE any import from notes_app
# The Django app registry (AppConfig.ready()) must be initialized
# BEFORE importing models or consumers.
# If you change the order → AppRegistryNotReady exception.
django_asgi_app = get_asgi_application()

# Only after get_asgi_application() is it safe to import from notes_app
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from notes_project.routing import websocket_urlpatterns

application = ProtocolTypeRouter({
    # HTTP → regular Django (views.py, templates);
    # ASGIStaticFilesHandler serves /static/ straight from Django (handy in development;
    # in the Docker stack nginx serves /static/)
    "http": ASGIStaticFilesHandler(django_asgi_app),

    # WebSocket → Auth middleware → URL router → Consumer
    "websocket": AuthMiddlewareStack(
        URLRouter(websocket_urlpatterns)
    ),
})

The critical import order

# ❌ WRONG — AppRegistryNotReady:
from notes_project.routing import websocket_urlpatterns   # ← BEFORE get_asgi_application()
django_asgi_app = get_asgi_application()

# ✅ CORRECT:
django_asgi_app = get_asgi_application()                  # ← FIRST
from notes_project.routing import websocket_urlpatterns   # ← THEN

Why this matters so much:

The Django app registry is initialized when get_asgi_application() is called.
Until that moment:
  - models are not loaded
  - AppConfig.ready() has not run
  - any import from notes_app.consumers → AppRegistryNotReady

A typical mistake:
  from notes_project.routing import websocket_urlpatterns
  # routing.py: from notes_app import consumers
  # consumers.py: from notes_app.models import ChatMessage
  # → AppRegistryNotReady!

AuthMiddlewareStack — scope["user"] from the session

WebSocket handshake request:
  GET /ws/groups/7/chat/
  Cookie: sessionid=abc123xyz

AuthMiddlewareStack:
  1. Reads the sessionid cookie from the handshake headers
  2. Finds the session in the Django session backend (DB)
  3. Loads the User from the session
  4. Puts it into scope['user']

Consumer:
  self.user = self.scope['user']
  # → User object (or AnonymousUser if not logged in)

What scope is

In ASGI, scope is a dictionary with the connection's metadata. It is the equivalent of request in HTTP views, but for WebSocket:

# scope for a WebSocket connection:
{
    'type': 'websocket',
    'path': '/ws/groups/7/chat/',
    'url_route': {
        'kwargs': {'group_pk': '7'}   # ← from the URL pattern
    },
    'user': <User: viktor>,           # ← loaded by AuthMiddlewareStack
    'headers': [...],                 # ← handshake request headers
    'session': <Session>,             # ← Django session
}

How the Consumer uses scope

async def connect(self):
    self.user = self.scope['user']
    # ↑ User is already loaded by AuthMiddlewareStack

    self.group_pk = int(self.scope['url_route']['kwargs']['group_pk'])
    # ↑ group_pk from the URL /ws/groups/<group_pk>/chat/

routing.py — WebSocket URL patterns

# notes_project/routing.py
from django.urls import re_path
from notes_app import consumers

websocket_urlpatterns = [
    re_path(
        r'^ws/groups/(?P<group_pk>\d+)/chat/$',
        consumers.GroupChatConsumer.as_asgi(),
    ),
]

# URL: ws://host/ws/groups/7/chat/
# group_pk=7 → scope['url_route']['kwargs']['group_pk']

re_path vs path for WebSocket

# path() — simpler:
from django.urls import path
websocket_urlpatterns = [
    path('ws/groups/<int:group_pk>/chat/', consumers.GroupChatConsumer.as_asgi()),
]

# re_path() — regex, more control:
from django.urls import re_path
websocket_urlpatterns = [
    re_path(r'^ws/groups/(?P<group_pk>\d+)/chat/$', consumers.GroupChatConsumer.as_asgi()),
]

# Both options work.
# re_path is the traditional choice for WebSocket (more examples in the documentation)

Consumer.as_asgi()

consumers.GroupChatConsumer.as_asgi()
# Equivalent of View.as_view() in HTTP — turns the Consumer class into an ASGI callable
# Each WebSocket connection → a separate Consumer instance

nginx: WebSocket proxy

When running behind nginx, WebSocket needs special headers.

# nginx.conf — WebSocket location
location /ws/ {
    proxy_pass http://web:8001;
    proxy_http_version 1.1;          # ← HTTP/1.1 is required for the WS Upgrade
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 300s;         # ← 5 minutes for idle WS connections
}

Why proxy_http_version 1.1: The WebSocket Upgrade only works over HTTP/1.1. By default, nginx uses HTTP/1.0 for upstream requests. Without this line the WS Upgrade will not happen → the browser gets HTTP 400.

Why proxy_read_timeout 300s: By default, nginx closes the upstream connection after 60 sec without a response. A WebSocket can stay open for hours without traffic → increase the timeout to 5+ minutes.


Common mistakes in the ASGI stack

Error Cause Fix
AppRegistryNotReady Import from notes_app BEFORE get_asgi_application() Move the imports after the call
WS 400 through nginx Missing Upgrade headers proxy_http_version 1.1 + Upgrade headers
Consumer not found routing.py is not wired into asgi.py Include websocket_urlpatterns
scope['user'] is AnonymousUser AuthMiddlewareStack is missing or the session has expired Check is_authenticated in connect()

Next

Next chapter: 7B. Channel Layers and Daphne — Daphne in INSTALLED_APPS, InMemoryChannelLayer vs RedisChannelLayer, socket_timeout=None.