django-socket 0.2.0__py3-none-any.whl

django_socket/management/commands/runserver.py

@@ -0,0 +1,81 @@
+"""`manage.py runserver` sobre uvicorn, para que los WebSockets funcionen en dev.
+
+El runserver de Django es WSGI puro y rechaza el scope 'websocket'. Este
+comando reutiliza el parseo de argumentos de Django (addrport, --ipv6,
+--noreload) y arranca uvicorn contra tu ASGI_APPLICATION.
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.management import CommandError
+from django.core.management.commands.runserver import Command as RunserverCommand
+
+
+class Command(RunserverCommand):
+    help = "Arranca un servidor de desarrollo ASGI (uvicorn) con soporte WebSocket."
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--log-level",
+            default="info",
+            help="Nivel de log de uvicorn (critical, error, warning, info, debug, trace).",
+        )
+
+    def run(self, **options):
+        try:
+            import uvicorn
+        except ImportError as exc:
+            raise CommandError(
+                "django_socket necesita uvicorn para el servidor de desarrollo.\n"
+                "  pip install 'uvicorn[standard]'"
+            ) from exc
+
+        app_path, is_factory, origen = self._import_string()
+
+        from ... import routing
+
+        rutas = routing.get_routes()
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"django_socket sobre uvicorn -- http://{self.addr}:{self.port}/"
+            )
+        )
+        self.stdout.write(
+            f"  {len(rutas)} ruta(s) websocket"
+            + (": " + ", ".join(f"/{r.route}" for r in rutas) if rutas else "")
+        )
+        self.stdout.write(f"  app: {app_path}  ({origen})")
+        self.stdout.write("Ctrl-C para salir.\n")
+
+        uvicorn.run(
+            app_path,
+            factory=is_factory,
+            host=self.addr,
+            port=int(self.port),
+            reload=options["use_reloader"],
+            log_level=options["log_level"],
+            # Django ya loguea las peticiones cuando DEBUG esta activo.
+            access_log=True,
+        )
+
+    def _import_string(self) -> tuple[str, bool, str]:
+        """
+        Devuelve (ruta_de_importacion, es_factory, de_donde_sale).
+
+        Si el proyecto declara ASGI_APPLICATION la respetamos; si no, montamos
+        una al vuelo, para que la libreria funcione recien instalada sin pedir
+        ni una linea de configuracion.
+        """
+        path = getattr(settings, "ASGI_APPLICATION", None)
+        if not path:
+            return "django_socket.asgi:factory", True, "generada al vuelo"
+
+        module, _, attr = path.rpartition(".")
+        if not module:
+            raise CommandError(
+                f"ASGI_APPLICATION invalido: {path!r}. Deberia ser algo como "
+                f'"miproyecto.asgi.application".'
+            )
+        return f"{module}:{attr}", False, "ASGI_APPLICATION"

django_socket/management/commands/ws.py

@@ -0,0 +1,64 @@
+"""`manage.py ws` -- que rutas hay y como esta montado todo."""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.management.base import BaseCommand
+
+from ... import patch, routing
+
+
+class Command(BaseCommand):
+    help = "Lista las rutas WebSocket registradas y revisa la integracion."
+
+    def handle(self, *args, **options):
+        conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+        routes = routing.get_routes()
+
+        self.stdout.write(self.style.MIGRATE_HEADING("Rutas WebSocket"))
+        if not routes:
+            self.stdout.write(
+                "  ninguna. Crea <tu_app>/sockets.py y decora un 'async def' con @ws()."
+            )
+        for r in routes:
+            flags = []
+            if r.group:
+                flags.append(f"group={r.group}")
+            if not r.auth:
+                flags.append("auth=False")
+            suffix = f"  [{', '.join(flags)}]" if flags else ""
+            where = f"{r.handler.__module__}.{r.handler.__name__}"
+            self.stdout.write(f"  ws:///{r.route}".ljust(42) + f"{where}{suffix}")
+
+        self.stdout.write("")
+        self.stdout.write(self.style.MIGRATE_HEADING("Integracion"))
+        self._row("Capa de difusion", conf.get("LAYER", "memory"))
+        if conf.get("LAYER") == "redis":
+            self._row("Redis", conf.get("REDIS_URL", "redis://localhost:6379/0"))
+        self._row(
+            "asgi.py",
+            "no hace falta tocarlo (ASGIHandler ampliado)"
+            if patch.is_installed()
+            else "PATCH_ASGI=False -> debes usar ASGIApplication() a mano",
+        )
+        self._row(
+            "Origenes permitidos",
+            conf.get("ALLOWED_ORIGINS")
+            or f"ALLOWED_HOSTS={list(settings.ALLOWED_HOSTS) or '[] (DEBUG: localhost)'}",
+        )
+        self._row(
+            "Origin ausente",
+            "rechazado" if conf.get("REQUIRE_ORIGIN") else "aceptado (clientes nativos)",
+        )
+
+        if settings.DEBUG and conf.get("LAYER", "memory") == "memory":
+            self.stdout.write("")
+            self.stdout.write(
+                self.style.WARNING(
+                    "  Aviso: con la capa 'memory' un broadcast no cruza entre\n"
+                    "  procesos. En produccion con varios workers usa LAYER='redis'."
+                )
+            )
+
+    def _row(self, label: str, value) -> None:
+        self.stdout.write(f"  {label:<22}{value}")

django_socket/middleware.py

@@ -0,0 +1,166 @@
+"""Middleware: envuelve cada conexion, para lo que hay que hacer en todas.
+
+Trazas, metricas, reportar errores a Sentry, limitar conexiones por usuario.
+Un middleware es `async def (sock, siguiente)`, y `siguiente()` corre el resto
+de la cadena y al final tu handler:
+
+    # miapp/ws.py
+    import time, logging
+
+    log = logging.getLogger("miapp.sockets")
+
+    async def medir(sock, siguiente):
+        inicio = time.monotonic()
+        try:
+            await siguiente()
+        finally:
+            log.info("%s duro %.1fs", sock.path, time.monotonic() - inicio)
+
+    # settings.py
+    DJANGO_SOCKET = {"MIDDLEWARE": ["miapp.ws.medir"]}
+
+Se aplican en orden: el primero de la lista es el mas externo, igual que el
+MIDDLEWARE de Django.
+
+Para cortar una conexion, cierra y no llames a `siguiente()`:
+
+    async def solo_de_pago(sock, siguiente):
+        if not await es_de_pago(sock.user):
+            await sock.close(4403, "Plan insuficiente")
+            return
+        await siguiente()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Awaitable, Callable
+
+logger = logging.getLogger("django_socket")
+
+Siguiente = Callable[[], Awaitable[None]]
+Middleware = Callable[..., Awaitable[None]]
+
+_cadena: list[Middleware] | None = None
+
+
+def get_middleware() -> list[Middleware]:
+    """Lee y cachea la lista de settings. Se resuelve una vez, no por conexion."""
+    global _cadena
+    if _cadena is None:
+        from django.conf import settings
+        from django.utils.module_loading import import_string
+
+        conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+        _cadena = [
+            import_string(m) if isinstance(m, str) else m
+            for m in conf.get("MIDDLEWARE", [])
+        ]
+        if _cadena:
+            logger.debug(
+                "django_socket: %d middleware(s): %s",
+                len(_cadena),
+                ", ".join(getattr(m, "__name__", str(m)) for m in _cadena),
+            )
+    return _cadena
+
+
+def limpiar_cache() -> None:
+    """Solo para tests: obliga a releer MIDDLEWARE de settings."""
+    global _cadena
+    _cadena = None
+
+
+async def aplicar(sock, handler_final: Siguiente) -> None:
+    """
+    Corre la cadena y, al final, el handler.
+
+    Se monta de dentro hacia fuera para que el primero de la lista quede el mas
+    externo, que es lo que la gente espera al leer un MIDDLEWARE de Django.
+    """
+    cadena = get_middleware()
+    if not cadena:
+        await handler_final()
+        return
+
+    siguiente = handler_final
+    for mw in reversed(cadena):
+        siguiente = _envolver(mw, sock, siguiente)
+    await siguiente()
+
+
+def _envolver(mw: Middleware, sock, siguiente: Siguiente) -> Siguiente:
+    async def llamada() -> None:
+        await mw(sock, siguiente)
+
+    llamada.__name__ = getattr(mw, "__name__", "middleware")
+    return llamada
+
+
+# ------------------------------------------------------- middlewares utiles
+
+
+def max_conexiones_por_usuario(limite: int = 5, code: int = 4429):
+    """
+    Corta al usuario que abre mas de `limite` sockets a la vez.
+
+        DJANGO_SOCKET = {
+            "MIDDLEWARE": [max_conexiones_por_usuario(10)],
+        }
+
+    Cuenta por proceso. Con varios workers el limite real es
+    `limite x workers`; para un tope global harian falta contadores en Redis, y
+    eso vale la pena solo si de verdad te hace falta esa precision.
+    """
+    from collections import defaultdict
+
+    abiertas: dict[object, int] = defaultdict(int)
+
+    async def middleware(sock, siguiente):
+        user = getattr(sock, "user", None)
+        clave = getattr(user, "pk", None) if getattr(user, "is_authenticated", False) else None
+        if clave is None:
+            clave = (sock.client or ("?", 0))[0]      # anonimos, por IP
+
+        if abiertas[clave] >= limite:
+            logger.warning(
+                "django_socket: %r supero %d conexiones simultaneas en %s",
+                clave, limite, sock.path,
+            )
+            await sock.close(code, "Too many connections")
+            return
+
+        abiertas[clave] += 1
+        try:
+            await siguiente()
+        finally:
+            abiertas[clave] -= 1
+            if abiertas[clave] <= 0:
+                abiertas.pop(clave, None)
+
+    middleware.__name__ = "max_conexiones_por_usuario"
+    return middleware
+
+
+def registrar(nivel: int = logging.INFO, logger_name: str = "django_socket.access"):
+    """Una linea por conexion: ruta, usuario, duracion y como termino."""
+    import time
+
+    log = logging.getLogger(logger_name)
+
+    async def middleware(sock, siguiente):
+        inicio = time.monotonic()
+        try:
+            await siguiente()
+        finally:
+            log.log(
+                nivel,
+                "%s user=%s dur=%.2fs code=%s",
+                sock.path,
+                getattr(sock.user, "pk", None) or "anon",
+                time.monotonic() - inicio,
+                sock.close_code,
+            )
+
+    middleware.__name__ = "registrar"
+    return middleware

django_socket/patch.py

@@ -0,0 +1,54 @@
+"""Hace que el `asgi.py` que genera `startproject` sirva WebSockets sin tocarlo.
+
+`django.core.asgi.get_asgi_application()` devuelve un `ASGIHandler` que rechaza
+todo scope que no sea 'http' -- el propio codigo de Django lleva ahi un
+`# FIXME: Allow to override this.`. Como `django.setup()` ejecuta los `ready()`
+de las apps *antes* de instanciar el handler, desde nuestro `ready()` llegamos
+a tiempo de ensanchar esa puerta.
+
+El resultado es que integrar la libreria son dos pasos: instalarla y añadirla a
+INSTALLED_APPS. Desactivalo con DJANGO_SOCKET = {"PATCH_ASGI": False} si
+prefieres declarar `ASGIApplication()` a mano.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("django_socket")
+
+FLAG = "_django_socket_patched"
+
+
+def install() -> bool:
+    """Devuelve True si el parche quedo instalado (o ya lo estaba)."""
+    from django.core.handlers.asgi import ASGIHandler
+
+    if getattr(ASGIHandler, FLAG, False):
+        return True
+
+    original_call = ASGIHandler.__call__
+
+    async def __call__(self, scope, receive, send):
+        kind = scope["type"]
+        if kind == "websocket":
+            from . import dispatch
+
+            return await dispatch.handle_websocket(scope, receive, send)
+        if kind == "lifespan":
+            from . import dispatch
+
+            return await dispatch.handle_lifespan(scope, receive, send)
+        return await original_call(self, scope, receive, send)
+
+    __call__.__doc__ = ASGIHandler.__call__.__doc__
+    ASGIHandler.__call__ = __call__
+    setattr(ASGIHandler, FLAG, True)
+    logger.debug("django_socket: ASGIHandler ampliado con websocket + lifespan")
+    return True
+
+
+def is_installed() -> bool:
+    from django.core.handlers.asgi import ASGIHandler
+
+    return getattr(ASGIHandler, FLAG, False)

django_socket/ratelimit.py

@@ -0,0 +1,93 @@
+"""Limite de mensajes entrantes por socket.
+
+    DJANGO_SOCKET = {"RATE_LIMIT": "60/m"}      # para todas las rutas
+    @ws("chat/", rate_limit="10/s")             # o solo para esta
+
+Es un *token bucket*, no un contador por ventana, y la diferencia importa: un
+contador rechaza el mensaje 11 aunque los 10 anteriores fueran de hace 59
+segundos. El cubo se rellena de forma continua, asi que aguanta la rafaga
+normal de alguien escribiendo rapido y solo corta cuando el ritmo *sostenido*
+pasa del limite.
+
+Al agotarse se cierra con **4429**. Para dejar pasar picos mas grandes, sube el
+`burst`:
+
+    @ws("cursor/", rate_limit="30/s", burst=100)
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+UNIDADES = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
+_FORMATO = re.compile(r"^\s*(\d+)\s*/\s*(\d*)\s*([smhd])\s*$", re.I)
+
+CLOSE_RATE_LIMIT = 4429
+
+
+def parsear(spec: str) -> tuple[float, float]:
+    """
+    "60/m" -> (60 mensajes, 60 segundos).  Tambien "100/5m", "10/s".
+
+    Devuelve (cantidad, periodo_en_segundos).
+    """
+    if not isinstance(spec, str):
+        raise ValueError(f"rate_limit debe ser una cadena como '60/m', no {spec!r}")
+
+    m = _FORMATO.match(spec)
+    if not m:
+        raise ValueError(
+            f"rate_limit invalido: {spec!r}. El formato es "
+            f"'<cantidad>/<periodo>', por ejemplo '60/m', '10/s' o '100/5m'."
+        )
+
+    cantidad, multiplo, unidad = m.groups()
+    if int(cantidad) <= 0:
+        raise ValueError(f"rate_limit invalido: {spec!r}. La cantidad debe ser > 0.")
+    return float(cantidad), float(multiplo or 1) * UNIDADES[unidad.lower()]
+
+
+class Cubo:
+    """Token bucket. `consumir()` devuelve False cuando ya no queda margen."""
+
+    __slots__ = ("capacidad", "por_segundo", "restante", "sello")
+
+    def __init__(self, cantidad: float, periodo: float, burst: float | None = None):
+        self.capacidad = float(burst if burst is not None else cantidad)
+        self.por_segundo = cantidad / periodo
+        self.restante = self.capacidad
+        self.sello = time.monotonic()
+
+    def consumir(self, coste: float = 1.0) -> bool:
+        ahora = time.monotonic()
+        self.restante = min(
+            self.capacidad, self.restante + (ahora - self.sello) * self.por_segundo
+        )
+        self.sello = ahora
+        if self.restante < coste:
+            return False
+        self.restante -= coste
+        return True
+
+    @property
+    def espera(self) -> float:
+        """Segundos hasta que vuelva a haber margen. Util para avisar al cliente."""
+        if self.restante >= 1:
+            return 0.0
+        return (1 - self.restante) / self.por_segundo
+
+
+def crear(spec=None, burst=None) -> Cubo | None:
+    """Cubo para una ruta, o None si no hay limite configurado en ningun sitio."""
+    if spec is None:
+        from django.conf import settings
+
+        conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+        spec = conf.get("RATE_LIMIT")
+        burst = burst if burst is not None else conf.get("RATE_LIMIT_BURST")
+
+    if not spec:
+        return None
+    cantidad, periodo = parsear(spec)
+    return Cubo(cantidad, periodo, burst)

django_socket/routing.py

@@ -0,0 +1,148 @@
+"""Registro y resolucion de rutas WebSocket."""
+
+from __future__ import annotations
+
+import inspect
+import string
+from typing import Any, Callable, NamedTuple
+
+from django.urls.resolvers import RoutePattern
+
+
+class Route(NamedTuple):
+    pattern: RoutePattern
+    handler: Callable
+    name: str
+    auth: Any
+    group: str | None
+    route: str
+    rate_limit: str | None
+    burst: float | None
+
+
+_routes: list[Route] = []
+
+
+def ws(
+    route: str,
+    *,
+    group: str | None = None,
+    auth: Any = True,
+    rate_limit: str | None = None,
+    burst: float | None = None,
+    name: str | None = None,
+):
+    """
+    Registra un handler WebSocket.
+
+        @ws("chat/<str:room>/", group="room:{room}")
+        async def chat(sock, room):
+            async for msg in sock:
+                await sock.broadcast(msg.text)
+
+    `route` usa la sintaxis de `django.urls.path` y sus mismos conversores
+    (`<int:pk>`, `<slug:x>`, `<uuid:x>`...), asi que los parametros llegan al
+    handler ya convertidos.
+
+    `group` se rellena con esos mismos parametros: el socket entra en el grupo
+    al conectar, sale al desconectar, y `sock.broadcast(dato)` va ahi por
+    defecto.
+
+    `auth` decide como se resuelve `sock.user`:
+
+        auth=True                  los autenticadores de settings (por defecto,
+                                   la sesion de Django)
+        auth=False                 ninguno; `sock.user` queda a None
+        auth="token"               solo por token
+        auth=["session", "token"]  el primero que reconozca a alguien
+        auth=mi_funcion            async(sock) -> user | None
+
+    Ver `django_socket.authentication`.
+
+    `rate_limit` acota los mensajes entrantes de cada socket ("60/m", "10/s").
+    Al pasarse se cierra con 4429. `burst` deja pasar picos mayores sin subir
+    el ritmo sostenido. Ver `django_socket.ratelimit`.
+    """
+
+    def decorator(handler: Callable) -> Callable:
+        if not inspect.iscoroutinefunction(handler):
+            raise TypeError(
+                f"@ws espera 'async def', y {handler.__name__} es una funcion "
+                f"normal.\n"
+                f"    async def {handler.__name__}(sock, ...):\n"
+                f"Un WebSocket vive en el loop de eventos. Para tocar el ORM "
+                f"usa su API async (await Model.objects.aget(...)) o envuelve "
+                f"lo sincrono en asgiref.sync.sync_to_async."
+            )
+        normalized = route.lstrip("/")
+        _check_group_template(group, normalized, handler)
+        if auth is not False:
+            # Falla al importar si el autenticador no existe, no en la primera
+            # conexion del primer usuario.
+            from .authentication import resolver_lista
+
+            resolver_lista(auth)
+        if rate_limit is not None:
+            from .ratelimit import parsear
+
+            parsear(rate_limit)     # revienta ahora si el formato esta mal
+
+        for existing in _routes:
+            if existing.route == normalized:
+                raise ValueError(
+                    f"La ruta '{normalized}' ya la tiene registrada "
+                    f"{existing.handler.__module__}.{existing.handler.__name__}."
+                )
+
+        _routes.append(
+            Route(
+                pattern=RoutePattern(normalized, is_endpoint=True),
+                handler=handler,
+                name=name or handler.__name__,
+                auth=auth,
+                group=group,
+                route=normalized,
+                rate_limit=rate_limit,
+                burst=burst,
+            )
+        )
+        return handler
+
+    return decorator
+
+
+def _check_group_template(group: str | None, route: str, handler: Callable) -> None:
+    """Falla al importar, no en la primera conexion, si el grupo no cuadra."""
+    if not group:
+        return
+    referenced = {
+        field for _, field, _, _ in string.Formatter().parse(group) if field
+    }
+    available = set(RoutePattern(route, is_endpoint=True).regex.groupindex)
+    missing = referenced - available
+    if missing:
+        raise ValueError(
+            f"group={group!r} en {handler.__name__} usa "
+            f"{sorted(missing)}, que no existe(n) en la ruta '{route}'. "
+            f"Disponibles: {sorted(available) or 'ninguno'}."
+        )
+
+
+def resolve(path: str) -> tuple[Route, dict[str, Any]] | None:
+    """Devuelve (ruta, kwargs) para un path ASGI, o None si no casa ninguna."""
+    candidate = path.lstrip("/")
+    for r in _routes:
+        match = r.pattern.match(candidate)
+        if match is not None:
+            _, _, kwargs = match
+            return r, kwargs
+    return None
+
+
+def get_routes() -> list[Route]:
+    return list(_routes)
+
+
+def clear_routes() -> None:
+    """Solo para tests."""
+    _routes.clear()