django-socket 0.1.0__py3-none-any.whl

django_socket/groups.py

@@ -0,0 +1,287 @@
+"""Capa de difusion: grupos y broadcast.
+
+`MemoryLayer` sirve para un solo proceso (dev, o un unico worker).
+`RedisLayer` reparte el fan-out entre procesos via pub/sub.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger("django_socket")
+
+
+class BaseLayer:
+    async def startup(self) -> None: ...
+
+    async def shutdown(self) -> None: ...
+
+    async def add(self, group: str, sock) -> None:
+        raise NotImplementedError
+
+    async def discard(self, group: str, sock) -> None:
+        raise NotImplementedError
+
+    async def send(self, group: str, data: Any, *, exclude=None) -> None:
+        raise NotImplementedError
+
+    async def size(self, group: str) -> int:
+        raise NotImplementedError
+
+
+class MemoryLayer(BaseLayer):
+    """Grupos en memoria del proceso. Sin dependencias externas."""
+
+    def __init__(self):
+        self._groups: dict[str, set] = {}
+
+    async def add(self, group: str, sock) -> None:
+        self._groups.setdefault(group, set()).add(sock)
+
+    async def discard(self, group: str, sock) -> None:
+        members = self._groups.get(group)
+        if members:
+            members.discard(sock)
+            if not members:
+                del self._groups[group]
+
+    async def size(self, group: str) -> int:
+        return len(self._groups.get(group, ()))
+
+    async def send(self, group: str, data: Any, *, exclude=None) -> None:
+        await self._deliver_local(group, data, exclude=exclude)
+
+    async def _deliver_local(self, group: str, data: Any, *, exclude=None) -> None:
+        """
+        Reparte encolando, sin esperar a que nadie lea.
+
+        Esperar seria el bug: un solo miembro que no consume dejaria colgado
+        para siempre al que difunde. Cada socket tiene un buzon acotado; si se
+        llena, ese cliente va demasiado atrasado y se le echa en vez de dejar
+        que arrastre a los demas.
+        """
+        miembros = [s for s in self._groups.get(group, ()) if s is not exclude]
+        if not miembros:
+            return
+
+        lentos = []
+        for sock in miembros:
+            if not await sock.enqueue(data):
+                lentos.append(sock)
+
+        # Cede el turno una vez por difusion, no una por miembro: es donde
+        # corren los escritores. Sin esto, un handler que difunde en bucle
+        # (`for fila in lote: await sock.broadcast(fila)`) no soltaria nunca el
+        # loop, los buzones se llenarian y acabaria echando a clientes sanos.
+        await asyncio.sleep(0)
+
+        for sock in lentos:
+            logger.warning(
+                "django_socket: %r no consume (buzon lleno); se le echa del "
+                "grupo %r. Sube DJANGO_SOCKET['SEND_QUEUE_MAX'] si tu caso "
+                "manda rafagas legitimas.",
+                sock, group,
+            )
+            sock.evict()
+            await self.discard(group, sock)
+
+
+class RedisLayer(MemoryLayer):
+    """
+    Mantiene los miembros locales igual que MemoryLayer, pero publica cada
+    broadcast en Redis para que los demas procesos entreguen a los suyos.
+
+    Sobrevive a que Redis se caiga: la entrega local sigue funcionando, los
+    sockets de los usuarios no se cierran, y al volver Redis el proceso se
+    resuscribe solo. Lo que se publique mientras esta caido se pierde -- esto
+    es pub/sub, no una cola.
+    """
+
+    ESPERA_MAX = 10.0          # tope del backoff al reconectar
+    LATIDO = 15.0              # health check de redis-py, en segundos
+
+    def __init__(self, url: str = "redis://localhost:6379/0", prefix: str = "djws"):
+        super().__init__()
+        self.url = url
+        self.channel = f"{prefix}:broadcast"
+        self._redis = None
+        self._pubsub = None
+        self._listener: asyncio.Task | None = None
+        self._conectado = False
+        # Identifica a este proceso para no entregar dos veces lo que ya
+        # entregamos localmente.
+        self._origin = f"{id(self)}"
+
+    async def startup(self) -> None:
+        try:
+            import redis.asyncio as aioredis
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "RedisLayer necesita el paquete 'redis'. Instalalo con: pip install redis"
+            ) from exc
+        self._redis = aioredis.from_url(
+            self.url,
+            health_check_interval=self.LATIDO,   # sin esto no detecta la caida
+            retry_on_timeout=True,
+        )
+        self._pubsub = self._redis.pubsub()
+        await self._pubsub.subscribe(self.channel)
+        self._conectado = True
+        self._listener = asyncio.create_task(self._listen())
+        logger.info("django_socket: RedisLayer conectada a %s", self.url)
+
+    async def shutdown(self) -> None:
+        self._conectado = False
+        if self._listener:
+            self._listener.cancel()
+            try:
+                await self._listener
+            except asyncio.CancelledError:
+                pass
+        if self._pubsub:
+            try:
+                await self._pubsub.unsubscribe(self.channel)
+            except Exception:
+                pass
+            await self._pubsub.aclose()
+        if self._redis:
+            await self._redis.aclose()
+
+    async def send(self, group: str, data: Any, *, exclude=None) -> None:
+        # Entrega local inmediata (asi `exclude` funciona por identidad)...
+        await self._deliver_local(group, data, exclude=exclude)
+        # ...y avisa al resto de procesos.
+        carga = json.dumps(
+            {"group": group, "data": data, "origin": self._origin}, default=str
+        )
+        try:
+            await self._redis.publish(self.channel, carga)
+        except Exception as exc:
+            # Que Redis falle no puede tumbar la conexion del usuario: la
+            # entrega local ya se hizo y el handler debe seguir vivo. Se pierde
+            # el fan-out a los demas procesos, y por eso se loguea como error.
+            logger.error(
+                "django_socket: no se pudo publicar en Redis (%s: %s). "
+                "El grupo %r solo recibio la entrega local.",
+                type(exc).__name__, exc, group,
+            )
+
+    async def _listen(self) -> None:
+        """
+        Bucle de escucha resistente.
+
+        Se usa `get_message(timeout=...)` en vez de `listen()` para tener un
+        despertar periodico: ahi es donde redis-py corre su health check y
+        donde podemos detectar que la conexion se fue. Con `listen()` a secas
+        el proceso se queda sordo para siempre tras una caida.
+        """
+        espera = 0.5
+        while True:
+            try:
+                mensaje = await self._pubsub.get_message(
+                    ignore_subscribe_messages=True, timeout=1.0
+                )
+                espera = 0.5                      # todo bien, resetea el backoff
+                if mensaje is not None and mensaje.get("type") == "message":
+                    await self._entregar(mensaje)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                if not self._conectado:
+                    return
+                logger.warning(
+                    "django_socket: se perdio la conexion con Redis (%s). "
+                    "Reintentando en %.1fs.", type(exc).__name__, espera,
+                )
+                await asyncio.sleep(espera)
+                espera = min(espera * 2, self.ESPERA_MAX)
+                await self._resuscribir()
+
+    async def _entregar(self, mensaje) -> None:
+        try:
+            payload = json.loads(mensaje["data"])
+        except (ValueError, KeyError, TypeError):
+            logger.warning("django_socket: mensaje ilegible en %s", self.channel)
+            return
+        if payload.get("origin") == self._origin:
+            return  # ya lo entregamos localmente
+        await self._deliver_local(payload["group"], payload["data"])
+
+    async def _resuscribir(self) -> None:
+        """Vuelve a suscribirse tras un corte. Si Redis sigue caido, lo dira el bucle."""
+        try:
+            await self._pubsub.aclose()
+        except Exception:
+            pass
+        self._pubsub = self._redis.pubsub()
+        await self._pubsub.subscribe(self.channel)
+        logger.info("django_socket: resuscrito a %s", self.channel)
+
+
+# --------------------------------------------------------------- layer global
+
+_layer: BaseLayer | None = None
+
+
+def get_layer() -> BaseLayer:
+    global _layer
+    if _layer is None:
+        _layer = _build_layer()
+    return _layer
+
+
+def set_layer(layer: BaseLayer) -> None:
+    global _layer
+    _layer = layer
+
+
+def _build_layer() -> BaseLayer:
+    from django.conf import settings
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    backend = conf.get("LAYER", "memory")
+    if backend == "memory":
+        return MemoryLayer()
+    if backend == "redis":
+        return RedisLayer(
+            url=conf.get("REDIS_URL", "redis://localhost:6379/0"),
+            prefix=conf.get("PREFIX", "djws"),
+        )
+    if callable(backend):
+        return backend()
+    raise ValueError(
+        f"DJANGO_SOCKET['LAYER'] invalido: {backend!r}. Usa 'memory', 'redis' "
+        f"o un callable que devuelva una BaseLayer."
+    )
+
+
+# ------------------------------------------------------------- API de usuario
+
+
+async def broadcast(data: Any, *, to: str) -> None:
+    """
+    Envia a todos los miembros de un grupo, desde fuera de un handler.
+
+        await broadcast({"aviso": "mantenimiento"}, to="room:1")
+    """
+    await get_layer().send(to, data)
+
+
+async def group_size(group: str) -> int:
+    """Cuantos sockets locales hay en el grupo."""
+    return await get_layer().size(group)
+
+
+def broadcast_sync(data: Any, *, to: str) -> None:
+    """
+    Igual que `broadcast`, para vistas sincronas, señales o tareas Celery.
+
+    Con la capa 'memory' solo alcanza a los sockets del mismo proceso; para
+    llegar a todos los workers necesitas LAYER='redis'.
+    """
+    from asgiref.sync import async_to_sync
+
+    async_to_sync(broadcast)(data, to=to)

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/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/routing.py

@@ -0,0 +1,120 @@
+"""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: bool
+    group: str | None
+    route: str
+
+
+_routes: list[Route] = []
+
+
+def ws(
+    route: str,
+    *,
+    group: str | None = None,
+    auth: bool = True,
+    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=False` salta la resolucion de sesion y usuario si el endpoint es
+    publico (una consulta menos por conexion).
+    """
+
+    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)
+
+        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,
+            )
+        )
+        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()