Metadata-Version: 2.4
Name: django-socket
Version: 0.2.2
Summary: WebSockets for Django: one decorator, one async function, one line in INSTALLED_APPS.
License-Expression: MIT
Project-URL: Homepage, https://github.com/ramon3198/django-socket
Project-URL: Documentation, https://github.com/ramon3198/django-socket#readme
Project-URL: Changelog, https://github.com/ramon3198/django-socket/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ramon3198/django-socket/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Requires-Dist: asgiref>=3.6
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: dev
Requires-Dist: uvicorn[standard]>=0.27; extra == "dev"
Requires-Dist: websockets>=12; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Requires-Dist: redis>=5.0; extra == "dev"
Requires-Dist: coverage>=7; extra == "dev"
Dynamic: license-file

# django_socket

[![PyPI](https://img.shields.io/pypi/v/django-socket)](https://pypi.org/project/django-socket/)
[![tests](https://github.com/ramon3198/django-socket/actions/workflows/tests.yml/badge.svg)](https://github.com/ramon3198/django-socket/actions/workflows/tests.yml)
[![python](https://img.shields.io/badge/python-3.10%20%E2%80%93%203.13-blue)](https://github.com/ramon3198/django-socket)
[![django](https://img.shields.io/badge/django-4.2%20%E2%80%93%206.1-0C4B33)](https://github.com/ramon3198/django-socket)
[![license](https://img.shields.io/badge/license-MIT-green)](https://github.com/ramon3198/django-socket/blob/main/LICENSE)

**English** · [Español](https://github.com/ramon3198/django-socket/blob/main/README.es.md)

**WebSockets for Django.** One decorator, one `async` function, and it runs.

```python
# myapp/sockets.py
from django_socket import ws

@ws("chat/<str:room>/", group="room:{room}")
async def chat(sock, room):
    async for msg in sock:
        await sock.broadcast({"from": str(sock.user), "text": msg.text})
```

That's the whole file. Connection state lives in local variables, disconnect is
the code after the loop, and Django's user is right where you'd expect it.

---

## Contents

**Getting started** ·
[Install](#install) ·
[Your first socket in 5 minutes](#your-first-socket-in-5-minutes) ·
[Why you don't touch `asgi.py`](#why-you-dont-touch-asgipy)

**Guide** ·
[The `@ws` decorator](#the-ws-decorator) ·
[The `sock` object](#the-sock-object) ·
[Groups and broadcast](#groups-and-broadcast) ·
[JSON](#json) ·
[`Events`](#routing-by-message-type-with-events) ·
[Authentication](#users-and-authentication) ·
[JavaScript client](#javascript-client) ·
[Middleware](#middleware) ·
[Testing](#testing-your-handlers)

**Operations** ·
[Production](#production) ·
[Behind a proxy](#behind-a-reverse-proxy) ·
[Security](#security-origin-validation) ·
[Rate limiting](#rate-limiting) ·
[Slow clients](#slow-clients) ·
[Zombie connections](#zombie-connections) ·
[Settings](#all-settings) ·
[Close codes](#close-codes)

**Reference** ·
[How it works inside](#how-it-works-inside) ·
[Performance](#performance) ·
[Known limits](#known-limits) ·
[Development](#development)

---

# Getting started

## Install

```bash
pip install django-socket
```

```python
# settings.py
INSTALLED_APPS = [
    "django_socket",
    ...
]
```

**That's it. There is no third step.**

You don't touch `asgi.py`, you don't declare `ASGI_APPLICATION`, you don't set
up Redis, you don't switch servers. The `asgi.py` that `startproject` generated
serves WebSockets as-is, and `manage.py runserver` serves them on the same port
as HTTP.

Requires Python 3.10+ and Django 4.2+. For development you also need
`pip install "uvicorn[standard]"`.

---

## Your first socket in 5 minutes

### 1. Write the handler

Create `<your_app>/sockets.py`. It is auto-discovered, the same way `admin.py`
is:

```python
from django_socket import ws

@ws("echo/")
async def echo(sock):
    async for msg in sock:
        await sock.send(f"you said: {msg.text}")
```

### 2. Check it registered

```bash
python manage.py ws
```

```
Rutas WebSocket
  ws:///echo/                   myapp.sockets.echo

Integracion
  Capa de difusion      memory
  asgi.py               no hace falta tocarlo (ASGIHandler ampliado)
  Origenes permitidos   ALLOWED_HOSTS=[] (DEBUG: localhost)
  Origin ausente        aceptado (clientes nativos)
```

Run this first whenever something doesn't work: it tells you which routes exist,
with which group, and how the integration is wired.

### 3. Start it and try it

```bash
python manage.py runserver
```

From the browser console, on any page of your site:

```js
const s = new WebSocket("ws://localhost:8000/echo/");
s.onmessage = (e) => console.log(e.data);
s.onopen = () => s.send("hi");
// -> you said: hi
```

### 4. Now a chat room

```python
@ws("chat/<str:room>/", group="room:{room}")
async def chat(sock, room):
    who = sock.user.username if sock.user.is_authenticated else "anonymous"

    await sock.broadcast({"kind": "join", "who": who}, exclude_self=True)

    async for msg in sock:
        await sock.broadcast({"kind": "message", "who": who, "text": msg.text})

    # Reached when the client goes away.
    await sock.broadcast({"kind": "leave", "who": who})
```

Everything you need to know is in those lines:

- **`<str:room>`** is `django.urls.path` syntax. It reaches the handler already
  converted (`<int:pk>` gives you a real `int`).
- **`group="room:{room}"`** is filled from that parameter. The socket joins on
  connect and leaves on disconnect, without you calling anything.
- **`sock.broadcast(...)`** goes to that group by default.
- **`sock.user`** is the Django user, resolved from the session cookie.
- **The code after the `for`** runs when the client leaves. That's your
  `disconnect`.

---

## Why you don't touch `asgi.py`

Django has been ASGI since 3.0. All its handler does with a WebSocket is this:

```python
if scope["type"] != "http":
    raise ValueError("Django can only handle ASGI/HTTP connections, not %s.")
    # Django itself leaves a "FIXME: Allow to override this." right there.
```

It isn't that Django *can't* speak WebSocket — it refuses to look at that scope.
And since `django.setup()` runs every app's `ready()` **before** instantiating
the handler, our `AppConfig.ready()` gets there in time to widen that door. That
is why installing is just `INSTALLED_APPS`.

If you'd rather nothing of yours be touched, turn it off and declare it
yourself:

```python
DJANGO_SOCKET = {"PATCH_ASGI": False}
```

```python
# asgi.py
from django_socket import ASGIApplication
application = ASGIApplication()
```

---

# Guide

## The `@ws` decorator

```python
@ws(route, *, group=None, auth=True, name=None)
```

| | |
|---|---|
| `route` | `django.urls.path` syntax, with its converters |
| `group` | Group template; joins on connect, leaves on disconnect |
| `auth` | `False` skips session resolution (one query less) |
| `name` | Label for the `manage.py ws` listing |

```python
@ws("game/<int:pk>/player/<slug:nick>/")
async def game(sock, pk, nick):      # pk really is an int
    ...
```

If `group=` mentions a parameter the route doesn't have, it **fails at import
time** naming the culprit, not on the first connection.

The handler must be `async def`. Pass a regular function and the error explains
why, and what to use instead.

---

## The `sock` object

### Receiving

```python
async for msg in sock: ...          # ends when the client closes
msg.text   msg.bytes   msg.json()
if msg == "ping": ...               # Message compares against str directly

await sock.receive_text()           # also receive_json / receive_bytes
async for txt in sock.iter_text(): ...      # and iter_json()
```

### Sending

```python
await sock.send("hi")               # str    -> text frame
await sock.send(b"\x00")            # bytes  -> binary frame
await sock.send({"a": 1})           # rest   -> JSON
await sock.send_json(obj)           # also send_text / send_bytes
```

### Connection context

```python
sock.user            # User or AnonymousUser, from the session cookie
sock.session         # Django's SessionStore
sock.path_params     # {"room": "general"}
sock.query_params    # {"token": "abc"}   (query_lists for repeated keys)
sock.headers   sock.cookies   sock.client   sock.subprotocols   sock.scope
```

### Control

```python
await sock.accept(subprotocol="graphql-ws")   # only if you need to negotiate
await sock.close(4001, "room full")           # the code reaches onclose
await sock.deny()                             # kill the handshake with a 403
```

You don't need to call `accept()`: the handshake completes on its own the first
time you send, receive or iterate.

---

## Groups and broadcast

```python
await sock.join("global")            # the first one becomes the default target
await sock.leave("global")

await sock.broadcast(data)                    # to the default group
await sock.broadcast(data, to="other:group")
await sock.broadcast(data, exclude_self=True)

sock.group     # default target for broadcast()
sock.groups    # which groups you're a member of right now
```

`sock.group` and `sock.groups` are deliberately different. `groups` is which
groups you're a **member** of (it empties on disconnect); `group` is where
`broadcast()` points by **default**, and it survives disconnection so this
pattern works:

```python
async for msg in sock:
    await sock.broadcast(msg.text)
await sock.broadcast("someone left")     # <- you're no longer a member here
```

### From outside a handler

```python
from django_socket import broadcast, broadcast_sync

await broadcast({"notice": "maintenance"}, to="room:1")   # async view or task
broadcast_sync({"notice": "maintenance"}, to="room:1")    # sync view, signal, Celery
```

> With the default layer (`memory`), `broadcast_sync` only reaches the current
> process. With several workers you need Redis — see [Production](#production).

---

## JSON

It's the common case, so it's frictionless both ways:

```python
@ws("echo/")
async def echo(sock):
    async for data in sock.iter_json():         # already parsed
        await sock.send_json({"got": data})     # dict/list -> JSON
```

### Django types serialize themselves

`DjangoJSONEncoder` is used, so this just works:

```python
await sock.send_json({
    "when": timezone.now(),        # "2026-08-26T19:43:30.251Z"
    "price": Decimal("9.99"),      # "9.99"  (string: no precision loss)
    "id": uuid4(),                 # "0d8f...-..."
    "notice": _("Hello"),          # lazy translation strings too
})
```

<details>
<summary><b>Why the date matters more than it looks</b></summary>

With `str()` you'd get `"2026-08-26 19:43:30.251057+00:00"`, which has two
problems:

1. **ISO-8601 is the only format the ECMAScript spec requires `Date` to
   parse.** Anything else is each engine's fallback: V8 is lenient and accepts
   it, others historically aren't.
2. **`str()` emits microseconds** (6 digits), which `Date` cannot represent. The
   encoder truncates to milliseconds, which is what JS understands.

</details>

### An object it can't serialize fails loudly

```
TypeError: No se puede enviar un Usuario por el socket. Los tipos de Django
habituales (datetime, date, time, timedelta, Decimal, UUID, cadenas lazy) van
solos; el resto conviértelo tú: un modelo a dict, un QuerySet a lista.
Si prefieres el comportamiento antiguo: sock.send_json(dato, default=str).
```

That's on purpose. Staying quiet and shipping `"User object (3)"` to the browser
is worse: you find out in production.

### Invalid JSON is the client's fault, not yours

If a client sends garbage, the connection closes with **4400 "Invalid JSON"**
and leaves a `WARNING` in the log. Not a `1011 Internal error`, and not a
traceback that sends you hunting for a bug of yours that doesn't exist.

```python
from django_socket import InvalidJSON     # it's a ValueError

async for msg in sock:
    try:
        data = msg.json()
    except InvalidJSON:
        await sock.send_json({"error": "that wasn't JSON"})
```

---

## Routing by message type with `Events`

Most apps send `{"type": "something", ...}` and end up with a long if/elif.
`Events` turns that into named functions:

```python
from django_socket import Events, ws

board = Events()

@board.on("draw")
async def draw(sock, data):
    await sock.broadcast({"type": "draw", **data}, exclude_self=True)

@board.on("clear")
async def clear(sock):              # if you don't use the data, don't ask for it
    await sock.broadcast({"type": "clear"})

@board.on("join", "leave")          # several types at once
async def move(sock, data): ...

@board.on("*")                      # whatever didn't match anything else
async def rest(sock, data): ...

@ws("board/<str:room>/", group="board:{room}")
async def handler(sock, room):
    await board.run(sock)
```

- The `type` field does **not** arrive inside `data`.
- `"*"` is a **fallback**, not a spy: it only runs when nobody else took the
  message.
- An unhandled type is ignored and leaves a `WARNING` listing the registered
  ones — it's almost always a typo.
- `Events(strict=True)` closes with 4400 instead.
- `Events(key="action")` changes the field name.

It's entirely optional: `async for msg in sock` is still there.

---

## Users and authentication

`sock.user` is always available, resolved from the handshake's session cookie.
Nothing to wrap in `asgi.py`.

```python
from django_socket import login_required, ws

@ws("dashboard/")
@login_required                 # closes with 4401 when there's no session
async def dashboard(sock):
    await sock.send_json({"hello": sock.user.username})
```

### Token auth, for SPAs and mobile apps

The session cookie only works when the browser sends it — same-site frontend.
A React app on another domain, or a mobile client, has no cookie. For those:

```python
DJANGO_SOCKET = {
    "AUTH": ["session", "token"],       # tried in order, first match wins
    "TOKEN_RESOLVER": "myapp.auth.from_jwt",
}
```

```python
async def from_jwt(token):
    data = jwt.decode(token, KEY, algorithms=["HS256"])
    return await User.objects.filter(pk=data["sub"]).afirst()
```

The library moves the token; validating it is yours, because it could be a JWT,
a DRF token, or something of your own. If you already use
`rest_framework.authtoken` and set no resolver, that one is used.

**Where the token travels matters.** Browsers *cannot set headers* on a
WebSocket — the `new WebSocket(url, protocols)` API only lets you touch the URL
and `Sec-WebSocket-Protocol`. So:

| How | Who can use it | Note |
|---|---|---|
| `Sec-WebSocket-Protocol: bearer, <token>` | browsers | **recommended**: not in the URL, so not in your logs |
| `Authorization: Bearer <token>` | native clients | browsers can't |
| `?token=<token>` | everyone | **ends up in access logs**, yours and every proxy's |

```js
new WebSocket("wss://api.example.com/feed/", ["bearer", token]);
```

They're read in that order, so the safest one wins if several are present.

### Per-route, and your own

```python
@ws("feed/", auth="token")                 # only token here
@ws("panel/", auth=["session", "token"])   # either
@ws("public/", auth=False)                 # don't even try; sock.user is None
@ws("iot/", auth=my_authenticator)         # async(sock) -> user | None
```

An authenticator is just a function:

```python
async def by_api_key(sock):
    key = sock.query_params.get("k")
    return await Client.objects.filter(api_key=key).afirst()
```

An unknown authenticator name fails **at import time**, not on someone's first
connection.

> With auth active, `sock.user` is always a user object — `AnonymousUser` when
> nobody recognised the client. It's `None` only with `auth=False`, so
> `sock.user.is_authenticated` never needs a `None` check first.

### The ORM works normally

```python
@ws("users/")
async def users(sock):
    total = await User.objects.acount()                        # async API
    names = [u.username async for u in User.objects.all()]
    x = await sync_to_async(lambda: User.objects.first())()     # sync ORM
```

The handler runs inside a `ThreadSensitiveContext`, so
`sync_to_async(thread_sensitive=True)` — the default — shares a thread just like
it does in a view.

---

## JavaScript client

Reconnecting properly is one of those things everyone rewrites and almost
nobody gets right. It ships included:

```html
{% load django_socket %}
{% ws_client %}

<script>
  const sock = djangoSocket("/chat/general/");

  sock.on("message", (d) => render(d.text));
  sock.on("join",    (d) => notify(`${d.who} joined`));
  sock.on("*",       (d) => console.log("no handler:", d));

  sock.send({type: "message", text: "hi"});   // object -> JSON
</script>
```

`ws://` or `wss://` depending on the page protocol, JSON both ways, and routing
by `type` just like `Events` on the Python side.

### What sets it apart

**It does not reconnect when the server closed on purpose.** A 4401 (login
required) or a 4404 (no such route) don't get fixed by retrying: reconnecting
there is an infinite loop hammering your server. 1000, 1008 and the whole
4000–4999 range are treated as final; everything else (1006, 1011, network
drops) is retried.

**Exponential backoff with jitter.** 0.5 s, 1 s, 2 s… up to 15 s, each wait
multiplied by a random factor. Without jitter, a thousand clients that drop
together all come back in the same millisecond and take the server down again.

**It queues what you write while offline** and flushes on reconnect. `send()`
returns `false` when it had to queue:

```js
if (!sock.send(text)) show("offline: will send on reconnect");
```

**With no network it doesn't burn attempts**: it waits for the browser's
`online` event. With the tab hidden it **keeps retrying**, on purpose — a chat
in a background tab that silently stops reconnecting is broken. If your case
tolerates falling behind, `{pauseWhenHidden: true}`.

### Options

```js
djangoSocket("/route/", {
  key: "type",             // the routing field
  reconnect: true,
  minDelay: 500, maxDelay: 15000, maxRetries: Infinity,
  queue: true, maxQueue: 100,
  pauseWhenHidden: false,
  protocols: ["graphql-ws"],
  shouldReconnect: (e) => e.code !== 4001,   // your own rule
  onOpen(isReconnect) {}, onClose(e, willRetry) {},
  onRetry(attempt, delayMs) {}, onError(e) {}, onMessage(data) {},
});
```

Plus `sock.connected`, `sock.pending`, `sock.close()`, `sock.reconnect()`,
`sock.on(type, fn)`, `sock.off(type, fn)`.

---

## Middleware

For what has to happen on every connection: tracing, metrics, reporting errors,
connection limits.

```python
# myapp/ws.py
import time, logging

log = logging.getLogger("myapp.sockets")

async def measure(sock, next_):
    start = time.monotonic()
    try:
        await next_()
    finally:
        log.info("%s took %.1fs", sock.path, time.monotonic() - start)
```

```python
DJANGO_SOCKET = {"MIDDLEWARE": ["myapp.ws.measure"]}
```

Applied in order — the first in the list is the outermost, the same as Django's
`MIDDLEWARE`. It runs **after** authentication, so `sock.user` is already there.
To reject a connection, close and don't call `next_()`:

```python
async def paid_only(sock, next_):
    if not await is_paid(sock.user):
        await sock.close(4403, "Plan required")
        return
    await next_()
```

Two come included:

```python
from django_socket.middleware import max_conexiones_por_usuario, registrar

DJANGO_SOCKET = {"MIDDLEWARE": [
    max_conexiones_por_usuario(10),   # closes the 11th with 4429
    registrar(),                      # one log line per connection
]}
```

`max_conexiones_por_usuario` counts per process: with N workers the real ceiling
is `limit × N`. A global one would need counters in Redis, which is only worth
it if you actually need that precision.

---

## Testing your handlers

No server, no ports, milliseconds:

```python
from django_socket.testing import WebSocketClient

async def test_chat_fans_out():
    async with WebSocketClient("/chat/general/") as a, \
               WebSocketClient("/chat/general/") as b:
        await b.send_json({"type": "message", "text": "hi"})
        assert (await a.receive_json())["text"] == "hi"
```

It goes through the same path a real connection does — route, converters, origin
validation, session, groups — but speaking ASGI straight to the dispatcher.

```python
# Authenticated user without hand-rolling cookies
async with WebSocketClient("/dashboard/", user=my_user) as c:
    assert (await c.receive_json())["who"] == "ramon"

# Rejections
async with WebSocketClient("/dashboard/") as c:
    assert await c.wait_closed() == 4401
    assert not c.connected

# Room isolation
async with WebSocketClient("/room/one/") as a, WebSocketClient("/room/two/") as b:
    await b.send("private")
    assert await a.receive_nothing()
```

| | |
|---|---|
| `send` / `send_json` / `send_text` / `send_bytes` | `str`→text, `bytes`→binary, rest→JSON |
| `receive` / `receive_json` / `receive_text` / `receive_bytes` | with timeout, fail fast |
| `receive_all()` | everything pending right now |
| `receive_nothing()` | `True` if nothing arrives — to assert isolation |
| `wait_closed()` | the close code |
| `connected` `accepted` `close_code` `close_reason` `subprotocol` | state |

`WebSocketClient(path, user=, headers=, cookies=, query=, subprotocols=, origin=)`

> `connected` and `accepted` are not the same: `accepted` says whether a
> `websocket.accept` arrived, and a coded rejection looks like accept + close on
> the wire (so the code reaches the browser). For "did it let me in?" use
> `connected`.

Every `receive` has a 1 s timeout: a test waiting for something that never
arrives fails in one second, with the path in the message, instead of hanging
the suite.

---

# Operations

## Production

Your project's `asgi.py` already works, unchanged:

```bash
uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000 --workers 4
```

```bash
gunicorn myproject.asgi:application -k uvicorn.workers.UvicornWorker -w 4
```

### Behind a reverse proxy

This is where most WebSocket deployments break, and the symptom — a 400 or a 502
— looks like a library bug when it isn't. The proxy has to be told to let the
protocol upgrade through:

```nginx
location /ws/ {
    proxy_pass http://app;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;      # <- these two
    proxy_set_header Connection "upgrade";       # <- are the whole thing
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;                    # or idle sockets get cut at 60s
}
```

Caddy needs nothing — it proxies WebSockets by default:

```
example.com {
    reverse_proxy app:8000
}
```

**How to tell if your proxy is eating the upgrade.** A successful handshake is
an `HTTP/1.1 101 Switching Protocols`. Check it without a browser in the way:

```bash
curl -i -N -o -   -H "Connection: Upgrade" -H "Upgrade: websocket"   -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=="   -H "Sec-WebSocket-Version: 13"   -H "Origin: https://example.com"   https://example.com/ws/echo/
```

- `101` — the proxy is fine, the problem is elsewhere.
- `400` — it reached Django, but the origin or the route was rejected. Check
  `manage.py ws` and your `ALLOWED_HOSTS`.
- `200` or `502` — the proxy swallowed the upgrade. Those two headers are
  missing.

If you're behind a load balancer, WebSockets are long-lived connections: raise
the idle timeout (ALB defaults to 60 s) or your sockets will drop every minute
for no visible reason.

### With more than one worker you need Redis

The memory layer only knows the sockets in its own process, so a broadcast
doesn't cross from one worker to another.

```python
DJANGO_SOCKET = {"LAYER": "redis", "REDIS_URL": "redis://localhost:6379/0"}
```

```bash
pip install "django-socket[redis]"
```

Each process publishes its broadcasts to a pub/sub channel and delivers to its
local members whatever it receives from the rest. Your handlers don't change:
`sock.broadcast(...)` is the same call.

Verified with two real workers against Redis 7.4: the message crosses both ways,
rooms stay isolated, and the publishing process doesn't deliver its own echo
twice.

### When Redis goes down

A Redis outage **does not take your users' connections down**:

- in-process delivery keeps working normally
- `broadcast()` doesn't raise; it logs an `ERROR` saying the group only got
  local delivery
- the process retries subscribing with exponential backoff (0.5 s → 10 s)
- when Redis returns, it resubscribes on its own and fan-out resumes without a
  restart

Anything published while Redis is down **is lost**: this is pub/sub, not a
queue. If you need delivery guarantees you have to persist the message yourself,
with the database or a real queue.

---

## Security: origin validation

**WebSockets are not subject to the same-origin policy.** Without validating the
`Origin` header, any website can open a socket against yours and the browser
will attach the victim's session cookies (*cross-site WebSocket hijacking*).
That's why the check isn't optional.

**It's on by default.** Validation runs against `ALLOWED_HOSTS` +
`CSRF_TRUSTED_ORIGINS`, and a foreign origin is rejected with a 403 **during the
handshake**, before anything is accepted.

A **missing** `Origin` is accepted, because browsers always send it: only native
clients omit it (a mobile app, a script). If your endpoint is browser-only, make
it strict:

```python
DJANGO_SOCKET = {
    "REQUIRE_ORIGIN": True,
    # or an explicit list, which ignores ALLOWED_HOSTS:
    "ALLOWED_ORIGINS": ["https://myapp.com", "https://admin.myapp.com"],
}
```

`manage.py check` warns if you leave `"*"` with `DEBUG=False`.

---

## Rate limiting

Before you expose a socket publicly, cap how fast a client can send:

```python
@ws("chat/", rate_limit="60/m")            # per route
DJANGO_SOCKET = {"RATE_LIMIT": "60/m"}     # or for all of them
```

Formats: `"10/s"`, `"60/m"`, `"100/5m"`, `"1000/h"`. Going over closes with
**4429**, and the reason says how long to wait.

It's a **token bucket, not a per-window counter**, and the difference is what
makes it usable: a counter rejects message 11 even when the previous 10 were 59
seconds ago. The bucket refills continuously, so it absorbs the normal burst of
someone typing fast and only cuts when the *sustained* rate goes over.

For streams that legitimately spike, raise the burst without raising the
sustained rate:

```python
@ws("cursor/", rate_limit="30/s", burst=100)
```

The limit is per socket. It is not a defence against a botnet opening thousands
of connections — for that you want `max_conexiones_por_usuario` and something in
front of the app.

---

## Slow clients

A client that stops reading — bad network, a phone going to sleep, or someone
acting in bad faith — cannot drag the rest down with it.

<details>
<summary><b>The problem, measured</b></summary>

uvicorn does apply backpressure: it buffers about **24 MB** toward a client
that isn't reading, and past that `send()` stops returning. With delivery that
awaited every member, that meant `broadcast()` **never returned**: the
broadcasting handler hung, stopped reading its own socket, and never ran its
cleanup. One client on a bad network killed the whole room.

</details>

**How it's solved.** Each socket has a bounded outbox and a task that writes it.
`broadcast()` enqueues and returns; it waits for nobody. If someone's outbox
fills up, that client is too far behind and gets evicted with a **1013 (Try
Again Later)** instead of being allowed to slow the group down.

```python
DJANGO_SOCKET = {
    "SEND_QUEUE_MAX": 256,       # queued messages per socket
    "SEND_QUEUE_FULL": "close",  # "close" | "drop_oldest"
}
```

`drop_oldest` is for streams that tolerate gaps — cursor positions, telemetry, a
live counter: better to lose an old value than to evict the client. For a chat
you want `close`.

**How to size it.** The outbox is measured in messages, but what matters is
*time*: `outbox ÷ messages_per_second = seconds of tolerance`. Measured, one
process publishes ~1,500 broadcasts/s against Redis, so 256 is ~165 ms in the
worst case and tens of seconds at normal chat rates. Only stuck clients pay the
memory — one that keeps up has an empty outbox — so the cost is
`stuck × 256 × message_size`.

**`sock.send()` still waits, on purpose.** There, blocking is healthy: in a
one-to-one stream, if the client can't keep up with you, your handler slowing
down is the correct outcome. The outbox is only for fan-out, which is where
waiting does damage.

**In a test, `await sock.drain()`** waits for what's queued to go out, so you
can assert without sleeping blindly. In production you don't need it.

---

## Zombie connections

A laptop whose lid gets closed leaves a TCP connection "open" with nobody on the
other end: no `close`, no error. Without detection that socket stays in its
group forever and you broadcast into the void.

**You don't have to do anything, and this library doesn't need to add a
heartbeat.** uvicorn already sends protocol pings and closes what doesn't
answer. Measured with a client that completes the handshake and then goes
completely silent:

```
t=  10s  in the group: 1
t=  20s  in the group: 1
t=  30s  in the group: 1
detected and cleaned up after 39s
```

39 seconds: `ws_ping_interval` (20 s) + `ws_ping_timeout` (20 s). The handler
exits through its `finally`, the socket leaves its groups, everything cleans up
by itself.

If you need it detected sooner:

```bash
uvicorn project.asgi:application --ws-ping-interval 5 --ws-ping-timeout 5
```

> This is uvicorn behaviour, not protocol behaviour. With a different ASGI
> server, check it.

---

## All settings

Everything is optional. These are the defaults:

```python
DJANGO_SOCKET = {
    "LAYER": "memory",            # "memory" | "redis" | callable -> BaseLayer
    "REDIS_URL": "redis://localhost:6379/0",
    "PREFIX": "djws",             # Redis channel prefix
    "ALLOWED_ORIGINS": None,      # None = ALLOWED_HOSTS + CSRF_TRUSTED_ORIGINS
    "REQUIRE_ORIGIN": False,      # True = also reject requests without Origin
    "PATCH_ASGI": True,           # False = declare ASGIApplication() yourself
    "SEND_QUEUE_MAX": 256,        # messages queued per socket, for fan-out
    "SEND_QUEUE_FULL": "close",   # "close" (evict the slow one) | "drop_oldest"

    "AUTH": ["session"],          # authenticators, tried in order
    "TOKEN_RESOLVER": None,       # async(token) -> user | None
    "MIDDLEWARE": [],             # async(sock, next) wrappers
    "RATE_LIMIT": None,           # "60/m" for every route
    "RATE_LIMIT_BURST": None,     # allowance above the sustained rate
}
```

A misspelled key is caught by `manage.py check` (`django_socket.E001`).

---

## Close codes

| Code | Meaning |
|---|---|
| `4400` | The client sent something that isn't valid JSON |
| `4401` | `@login_required` and there's no session |
| `4404` | No route matches that path |
| `4429` | Too fast: rate limit, or too many simultaneous connections |
| `1013` | The client isn't consuming: outbox full, evicted from the group |
| `1011` | Uncaught exception in the handler (it's in the log) |
| HTTP 403 | Origin not allowed — the handshake never completes |

`sock.close(code, reason)` accepts the handshake before closing if it hadn't
been accepted yet, precisely so your code reaches the client's `onclose`.
Closing without accepting produces an HTTP 403 and the browser only sees a
reasonless `1006`, which helps nobody debug.

---

# Reference

## How it works inside

Four decisions explain almost all of the library's behaviour.

### Connection state lives on a coroutine's stack

A WebSocket is a conversation with a beginning and an end. Modelling it as an
`async` function that runs start to finish means state goes in local variables
and the flow reads top to bottom:

```python
@ws("game/<int:pk>/", group="game:{pk}")
async def game(sock, pk):
    hand = deal()                      # state: a local variable
    turns = 0

    async for move in sock.iter_json():
        turns += 1
        hand = apply(hand, move)
        await sock.broadcast({"turns": turns})

    await record_abandon(pk, turns)    # disconnect is just the end
```

There are no instance attributes to keep in sync across callbacks, and no object
that outlives the connection. When the coroutine ends, there's nothing left to
clean up beyond what its own `finally` already does.

### Widening Django's door instead of building another one

Django is already ASGI. Its handler simply refuses to look at the `websocket`
scope, and it does so with a `FIXME` in the code. Since `django.setup()` runs
every app's `ready()` before instantiating that handler, the `AppConfig` gets
there in time to widen it.

That's where the most visible property comes from: **installing is adding one
line to `INSTALLED_APPS`**. No `asgi.py` to rewrite, no nested wrappers, no
second routing tree running parallel to Django's. And HTTP traffic never passes
through here at all.

### Fan-out waits for nobody

Each socket has a bounded outbox and a task that writes it. `broadcast()`
enqueues and returns.

The alternative — awaiting every member's delivery — looks simpler until you
measure it: a client that stops reading makes `send()` stop returning, and with
that the broadcasting handler hangs forever. It stops reading its own socket and
never runs its cleanup. One phone with bad reception takes the whole room down.
With an outbox, that client falls behind alone and is eventually evicted without
dragging anyone with it.

`sock.send()` does wait, and that's deliberate: in a one-to-one stream,
backpressure is healthy. Only fan-out needs to be decoupled.

### The fan-out layer is replaceable

`sock.broadcast(...)` is the same call whether you're on one process or twelve.
The only thing that changes is which layer sits underneath: in-memory for one
process, Redis pub/sub for several, or your own implementing `BaseLayer`.

Handlers never find out. There's no code to rewrite in order to scale, and no
two paths to maintain depending on the deployment.

---

## Performance

Measured on a laptop, Redis 7.4 in Docker, everything against `localhost`.
Reproducible:

```bash
python bench_redis.py      # layer cost
python bench_carga.py      # concurrent connections
```

### Layer cost

| | |
|---|---|
| broadcast, memory, 1 member | 0.003 ms |
| broadcast, memory, 1000 members | 0.104 ms |
| broadcast, Redis | ~0.65 ms → **~1,500/s per process** |
| cross-process latency | median 0.59 ms · p95 0.80 ms · p99 0.90 ms |

With Redis the cost is nearly flat in the number of members: the round trip to
Redis dominates, not local delivery. Those ~1,500 broadcasts/s are per process,
so they scale with workers.

### Concurrent connections

One process, memory layer, a freshly started server per measurement:

| connections | memory | fan-out p50 | p95 | delivered |
|---|---|---|---|---|
| 1,000 | 125 MB · 122 KB/conn | 28 ms | 40 ms | 100 % |
| 3,000 | 371 MB · 121 KB/conn | 157 ms | 200 ms | 100 % |
| 6,000 | 741 MB · 121 KB/conn | 130 ms | 216 ms | 100 % |

At 6,000 connections: all of them open (1,600/s), and 120,000 broadcast messages
arrive **without losing a single one**, at ~24,500 msg/s. With the Redis layer at
1,000 connections, fan-out goes from 28 to 58 ms median — the Redis round trip —
with the same memory and the same complete delivery.

**Memory is the binding constraint**: ~121 KB per connection, constant from
1,000 to 6,000. That's roughly **8,000 connections per GB**, and that number
comes from uvicorn and socket buffers, not from this library.

### What these figures do NOT say

- The benchmark client is **a single Python process** reading N websockets, so
  the latencies include its own scheduler. With real, distributed clients they'd
  be better.
- Everything is `localhost`: no network latency, no loss, no TLS.
- Not tested with large messages, a remote Redis, or over hours.

Re-run the benchmarks in your own environment before sizing anything.

---

## Known limits

- **Everything measured is `localhost`**: there are numbers up to 6,000
  connections and with Redis, but not against a real network, TLS, large
  messages or long sessions.
- **Django 4.2 → 6.1 and Python 3.10 → 3.13 pass in CI**, including the
  alternative path for the `aget_user` that doesn't exist before Django 5.0: on
  4.2 it really executes, not forced with a monkeypatch. What CI doesn't cover
  is Windows and macOS — it only runs on Linux.
- **The ~24 MB uvicorn buffers per connection** sit below this layer: the outbox
  bounds what piles up on top, not what's underneath. With 100 stuck clients at
  once that's 2.4 GB that can't be avoided from application level; that gets
  limited at the server.
- **No background task runner.** For deferred work use Celery or whatever runner
  you already have, and notify over the socket with `broadcast_sync`.
- **Synchronous handlers are not supported**, on purpose: `@ws` requires
  `async def` and says so when it fails. A plain `def` would occupy a thread per
  open connection.
- **Route resolution is linear and first match wins**, same as Django. With
  hundreds of routes it would want indexing.
- `broadcast_sync` with `LAYER="memory"` only reaches the current process — it's
  what you'd expect, but it's easy to trip over in development and not notice
  until production.

---

## Development

```bash
git clone https://github.com/ramon3198/django-socket.git && cd django-socket
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### Tests

```bash
pytest                              # 261 tests, ~10 s, nothing to start
node --test tests/js/*.test.js      # 35 tests for the JS client, no npm install
```

The Python suite needs no server: it uses the same `WebSocketClient` documented
above, plus a fake transport for the lower-level bits. Coverage: **94 %**.

The JS client uses the test runner and fake timers that ship with Node (≥20), so
there's nothing to install. It covers backoff with jitter, which codes are not
retried, the offline queue, the no-network pause, and `type` routing.

### Against real services

```bash
# A real Redis: the tests detect it and tell you which one they used
docker run -d --rm -p 6379:6379 redis:7-alpine
pytest tests/test_redis_layer.py -s

# Integration against a running server
python manage.py runserver 8000
python test_sockets.py 8000                 # 24 tests

# Fan-out across separate processes (with memory, this one MUST hang)
DJANGO_SOCKET_LAYER=redis python manage.py runserver 8091
DJANGO_SOCKET_LAYER=redis python manage.py runserver 8092
python test_multiproceso.py 8091 8092
```

### Demo

```bash
python manage.py migrate
python manage.py runserver
```

- `http://127.0.0.1:8000/ejemplos/` — **four patterns people actually build**,
  each one runnable in the page: background task progress, per-user
  notifications, presence, and a live dashboard. The commented source is in
  [`ejemplos/sockets.py`](ejemplos/sockets.py).
- `http://127.0.0.1:8000/sala/general/` — chat, open it in two tabs. To see the
  reconnect, stop the server and start it again.
- `chat/sockets.py` — every example in one file.

---

## License

MIT.
