django-socket 0.1.0__py3-none-any.whl

django_socket/__init__.py

@@ -0,0 +1,60 @@
+"""
+django_socket -- WebSockets en Django sin ceremonia.
+
+Instalar es: `pip install django-socket` y añadirlo a INSTALLED_APPS. Ya esta.
+
+    # miapp/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({"de": str(sock.user), "texto": msg.text})
+"""
+
+from .asgi import ASGIApplication
+from .auth import login_required
+from .events import Events
+from .groups import (
+    BaseLayer,
+    MemoryLayer,
+    RedisLayer,
+    broadcast,
+    broadcast_sync,
+    group_size,
+    set_layer,
+)
+from .routing import get_routes, ws
+from .websocket import (
+    InvalidJSON,
+    Message,
+    WebSocket,
+    WebSocketClosed,
+    WebSocketDisconnect,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Lo que usaras el 99% del tiempo
+    "ws",
+    "Events",
+    "broadcast",
+    "broadcast_sync",
+    "login_required",
+    # Tipos, para anotar
+    "WebSocket",
+    "Message",
+    "WebSocketDisconnect",
+    "WebSocketClosed",
+    "InvalidJSON",
+    # Puntos de extension
+    "ASGIApplication",
+    "BaseLayer",
+    "MemoryLayer",
+    "RedisLayer",
+    "set_layer",
+    "group_size",
+    "get_routes",
+    "__version__",
+]

django_socket/apps.py

@@ -0,0 +1,32 @@
+import logging
+
+from django.apps import AppConfig
+
+logger = logging.getLogger("django_socket")
+
+
+class DjangoSocketConfig(AppConfig):
+    name = "django_socket"
+    label = "django_socket"
+    verbose_name = "Django Socket"
+
+    def ready(self):
+        from django.conf import settings
+        from django.utils.module_loading import autodiscover_modules
+
+        from . import checks  # noqa: F401  (se registran al importarse)
+        from . import patch, routing
+
+        # Importa <cada_app>/sockets.py, igual que el admin con admin.py.
+        autodiscover_modules("sockets")
+
+        conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+        if conf.get("PATCH_ASGI", True):
+            patch.install()
+
+        found = routing.get_routes()
+        logger.debug(
+            "django_socket: %d ruta(s): %s",
+            len(found),
+            ", ".join(f"/{r.route}" for r in found) or "(ninguna)",
+        )

django_socket/asgi.py

@@ -0,0 +1,62 @@
+"""Punto de entrada ASGI explicito.
+
+Normalmente **no necesitas nada de aqui**: basta con añadir "django_socket" a
+INSTALLED_APPS y el `asgi.py` que genero `startproject` sirve WebSockets tal
+cual (ver `patch.py`).
+
+`ASGIApplication` existe para quien prefiere declararlo a mano, para componer
+con otro middleware ASGI, o para quien puso PATCH_ASGI=False.
+"""
+
+from __future__ import annotations
+
+from . import dispatch
+
+
+class ASGIApplication:
+    """
+    Uso explicito en tu `asgi.py`:
+
+        from django_socket import ASGIApplication
+        application = ASGIApplication()
+
+    El trafico HTTP va a Django sin tocarse; solo se intercepta el scope
+    'websocket' (y 'lifespan', para arrancar y parar la capa de difusion).
+    """
+
+    def __init__(self, http_app=None):
+        if http_app is None:
+            from django.core.asgi import get_asgi_application
+
+            http_app = _wrap_static(get_asgi_application())  # hace django.setup()
+        self.http_app = http_app
+
+    async def __call__(self, scope, receive, send):
+        kind = scope["type"]
+        if kind == "websocket":
+            return await dispatch.handle_websocket(scope, receive, send)
+        if kind == "lifespan":
+            return await dispatch.handle_lifespan(scope, receive, send)
+        return await self.http_app(scope, receive, send)
+
+
+def factory():
+    """
+    App ASGI construida al vuelo, sin que el proyecto declare nada.
+
+    La usa `runserver` cuando no hay ASGI_APPLICATION en settings, para que la
+    libreria funcione recien instalada.
+    """
+    return ASGIApplication()
+
+
+def _wrap_static(app):
+    """En DEBUG sirve /static/ igual que hace `runserver`, sin tocar websockets."""
+    from django.apps import apps
+    from django.conf import settings
+
+    if not settings.DEBUG or not apps.is_installed("django.contrib.staticfiles"):
+        return app
+    from django.contrib.staticfiles.handlers import ASGIStaticFilesHandler
+
+    return ASGIStaticFilesHandler(app)

django_socket/auth.py

@@ -0,0 +1,81 @@
+"""Sesion y usuario de Django a partir de las cookies del handshake.
+
+Todo es async de verdad: Django 5+ expone `aget_user` y `SessionStore.aget`,
+asi que no hace falta pasar por un thread pool.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import import_module
+
+logger = logging.getLogger("django_socket")
+
+
+class _SessionCarrier:
+    """Lo minimo que `django.contrib.auth.aget_user` espera de un request."""
+
+    __slots__ = ("session",)
+
+    def __init__(self, session):
+        self.session = session
+
+
+def _auth_installed() -> bool:
+    from django.apps import apps
+
+    return apps.is_installed("django.contrib.auth") and apps.is_installed(
+        "django.contrib.sessions"
+    )
+
+
+async def resolve(sock) -> None:
+    """Rellena `sock.session` y `sock.user`. Nunca lanza."""
+    from django.conf import settings
+
+    if not _auth_installed():
+        return
+
+    engine = import_module(settings.SESSION_ENGINE)
+    session_key = sock.cookies.get(settings.SESSION_COOKIE_NAME)
+    session = engine.SessionStore(session_key)
+    sock.session = session
+
+    carrier = _SessionCarrier(session)
+    try:
+        try:
+            from django.contrib.auth import aget_user
+        except ImportError:
+            # Django < 5.0 no tiene ni aget_user ni SessionStore.aget: al hilo.
+            from asgiref.sync import sync_to_async
+            from django.contrib.auth import get_user
+
+            sock.user = await sync_to_async(get_user)(carrier)
+        else:
+            sock.user = await aget_user(carrier)
+    except Exception:
+        logger.exception("django_socket: fallo al resolver el usuario")
+        from django.contrib.auth.models import AnonymousUser
+
+        sock.user = AnonymousUser()
+
+
+def login_required(handler):
+    """
+    Cierra la conexion con 4401 si el usuario no esta autenticado.
+
+        @ws("panel/")
+        @login_required
+        async def panel(sock): ...
+    """
+    import functools
+
+    @functools.wraps(handler)
+    async def wrapper(sock, *args, **kwargs):
+        user = getattr(sock, "user", None)
+        if user is None or not user.is_authenticated:
+            await sock.close(4401, "Authentication required")
+            return
+        return await handler(sock, *args, **kwargs)
+
+    return wrapper

django_socket/checks.py

@@ -0,0 +1,75 @@
+"""Avisos via `manage.py check`, para que los fallos de integracion salgan
+antes de desplegar y no como un socket que calla.
+"""
+
+from __future__ import annotations
+
+from django.core.checks import Error, Warning, register
+
+W001 = "django_socket.W001"  # capa memory con varios workers
+W002 = "django_socket.W002"  # ninguna ruta registrada
+W003 = "django_socket.W003"  # origenes abiertos a todo
+E001 = "django_socket.E001"  # opcion desconocida en DJANGO_SOCKET
+
+KNOWN_KEYS = {
+    "LAYER",
+    "REDIS_URL",
+    "PREFIX",
+    "ALLOWED_ORIGINS",
+    "REQUIRE_ORIGIN",
+    "PATCH_ASGI",
+    "SEND_QUEUE_MAX",
+    "SEND_QUEUE_FULL",
+}
+
+
+@register()
+def check_settings(app_configs, **kwargs):
+    from django.conf import settings
+
+    problems = []
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+
+    unknown = set(conf) - KNOWN_KEYS
+    if unknown:
+        problems.append(
+            Error(
+                f"Opcion(es) desconocida(s) en DJANGO_SOCKET: {sorted(unknown)}.",
+                hint=f"Las validas son: {sorted(KNOWN_KEYS)}.",
+                id=E001,
+            )
+        )
+
+    allowed = conf.get("ALLOWED_ORIGINS")
+    if allowed and "*" in allowed and not settings.DEBUG:
+        problems.append(
+            Warning(
+                "DJANGO_SOCKET['ALLOWED_ORIGINS'] contiene '*' con DEBUG=False.",
+                hint=(
+                    "Cualquier web podra abrir un socket contra la tuya con las "
+                    "cookies de sesion de tus usuarios (cross-site WebSocket "
+                    "hijacking). Enumera los origenes que confias."
+                ),
+                id=W003,
+            )
+        )
+
+    return problems
+
+
+@register()
+def check_routes(app_configs, **kwargs):
+    from . import routing
+
+    if routing.get_routes():
+        return []
+    return [
+        Warning(
+            "django_socket esta instalado pero no hay ninguna ruta websocket.",
+            hint=(
+                "Crea <tu_app>/sockets.py y decora un 'async def' con @ws('...'). "
+                "Se autodescubre igual que admin.py."
+            ),
+            id=W002,
+        )
+    ]

django_socket/dispatch.py

@@ -0,0 +1,191 @@
+"""El nucleo: atiende los scopes 'websocket' y 'lifespan'.
+
+Vive aparte de `asgi.py` porque hay dos caminos que llegan aqui: el parche
+sobre `ASGIHandler` (modo cero-configuracion) y `ASGIApplication` explicito.
+Los dos comparten este codigo.
+"""
+
+from __future__ import annotations
+
+import logging
+from urllib.parse import urlparse
+
+from asgiref.sync import ThreadSensitiveContext
+
+from . import auth as auth_mod
+from . import groups, routing
+from .websocket import InvalidJSON, WebSocket, WebSocketDisconnect
+
+logger = logging.getLogger("django_socket")
+
+# Codigos de cierre propios (rango privado 4000-4999).
+CLOSE_NO_ROUTE = 4404
+CLOSE_BAD_DATA = 4400      # el cliente mando algo que no se puede parsear
+CLOSE_SERVER_ERROR = 1011
+
+_layer_started = False
+
+
+def _settings():
+    from django.conf import settings
+
+    return getattr(settings, "DJANGO_SOCKET", {}) or {}
+
+
+async def _start_layer() -> None:
+    global _layer_started
+    if not _layer_started:
+        await groups.get_layer().startup()
+        _layer_started = True
+
+
+async def _stop_layer() -> None:
+    global _layer_started
+    if _layer_started:
+        await groups.get_layer().shutdown()
+        _layer_started = False
+
+
+# ---------------------------------------------------------------- lifespan
+
+
+async def handle_lifespan(scope, receive, send) -> None:
+    while True:
+        message = await receive()
+        if message["type"] == "lifespan.startup":
+            try:
+                await _start_layer()
+            except Exception as exc:
+                logger.exception("django_socket: fallo en el arranque")
+                await send({"type": "lifespan.startup.failed", "message": str(exc)})
+                return
+            await send({"type": "lifespan.startup.complete"})
+        elif message["type"] == "lifespan.shutdown":
+            try:
+                await _stop_layer()
+            finally:
+                await send({"type": "lifespan.shutdown.complete"})
+            return
+
+
+# --------------------------------------------------------------- websocket
+
+
+async def handle_websocket(scope, receive, send) -> None:
+    # El primer evento del protocolo siempre es websocket.connect.
+    event = await receive()
+    if event["type"] != "websocket.connect":
+        return
+
+    await _start_layer()  # por si el servidor no soporta lifespan
+    sock = WebSocket(scope, receive, send, layer=groups.get_layer())
+
+    if not origin_allowed(sock):
+        logger.warning(
+            "django_socket: origen rechazado %r para %s",
+            sock.headers.get("origin"),
+            sock.path,
+        )
+        # En seco: un origen ajeno no debe tener un socket abierto ni un instante.
+        await sock.deny()
+        return
+
+    match = routing.resolve(sock.path)
+    if match is None:
+        logger.warning(
+            "django_socket: ninguna ruta casa con %s. Registradas: %s",
+            sock.path,
+            ", ".join(f"/{r.route}" for r in routing.get_routes()) or "(ninguna)",
+        )
+        await sock.close(CLOSE_NO_ROUTE, "No route")
+        return
+
+    route, kwargs = match
+    sock.path_params = kwargs
+
+    async with ThreadSensitiveContext():
+        if route.auth:
+            await auth_mod.resolve(sock)
+
+        try:
+            if route.group:
+                # group="room:{room}" se rellena con los parametros de la ruta.
+                await sock.join(route.group.format(**kwargs))
+            await route.handler(sock, **kwargs)
+        except WebSocketDisconnect:
+            pass  # el cliente se fue; salida normal
+        except InvalidJSON as exc:
+            # Culpa del cliente, no del servidor: un aviso y un codigo que lo
+            # diga. Nada de traceback ni de 1011, que harian pensar que el bug
+            # es tuyo cada vez que alguien mande basura por el socket.
+            logger.warning(
+                "django_socket: %s en %s (cliente %s)", exc, sock.path, sock.client
+            )
+            await sock.close(CLOSE_BAD_DATA, "Invalid JSON")
+            return
+        except Exception:
+            logger.exception("django_socket: excepcion en el handler de %s", sock.path)
+            await sock.close(CLOSE_SERVER_ERROR, "Internal error")
+            return
+        await sock.close()
+
+
+# ------------------------------------------------------------------ origen
+
+
+def origin_allowed(sock) -> bool:
+    """
+    Los WebSockets no estan sujetos a la politica de mismo origen: sin esta
+    comprobacion cualquier web podria abrir un socket autenticado contra la
+    tuya (cross-site WebSocket hijacking).
+
+    Un Origin ausente se acepta: los navegadores siempre lo mandan, asi que
+    solo lo omiten clientes nativos. Ponlo estricto con REQUIRE_ORIGIN.
+    """
+    from django.conf import settings
+
+    conf = _settings()
+    origin = sock.headers.get("origin")
+    if origin is None:
+        return not conf.get("REQUIRE_ORIGIN", False)
+
+    allowed = conf.get("ALLOWED_ORIGINS")
+    if allowed is not None:
+        if "*" in allowed:
+            return True
+        return origin in allowed or _host_of(origin) in allowed
+
+    # Por defecto: ALLOWED_HOSTS + CSRF_TRUSTED_ORIGINS, como hace Django.
+    host = _host_of(origin)
+    if not host:
+        return False
+
+    trusted = {
+        _host_of(o) for o in getattr(settings, "CSRF_TRUSTED_ORIGINS", []) or []
+    }
+    if host in trusted:
+        return True
+
+    hosts = list(getattr(settings, "ALLOWED_HOSTS", []) or [])
+    if settings.DEBUG and not hosts:
+        hosts = ["localhost", "127.0.0.1", "[::1]"]
+    return any(_host_matches(host, pattern) for pattern in hosts)
+
+
+def _host_of(origin: str) -> str:
+    """'https://ejemplo.com:8000' -> 'ejemplo.com'."""
+    try:
+        return (urlparse(origin).hostname or "").lower()
+    except ValueError:
+        return ""
+
+
+def _host_matches(host: str, pattern: str) -> bool:
+    pattern = pattern.lower()
+    if pattern == "*":
+        return True
+    if pattern.startswith("."):  # ".ejemplo.com" cubre subdominios y el apex
+        return host == pattern[1:] or host.endswith(pattern)
+    if pattern.startswith("*."):
+        return host == pattern[2:] or host.endswith(pattern[1:])
+    return host == pattern

django_socket/events.py

@@ -0,0 +1,143 @@
+"""Enrutado de mensajes JSON por tipo.
+
+Casi toda app que habla JSON por el socket manda `{"type": "algo", ...}` y
+acaba con un if/elif largo dentro del bucle. Esto lo convierte en funciones con
+nombre, sin que dejes de ver el flujo:
+
+    from django_socket import Events, ws
+
+    chat = Events()
+
+    @chat.on("mensaje")
+    async def mensaje(sock, datos):
+        await sock.broadcast({"type": "mensaje", "texto": datos["texto"]})
+
+    @chat.on("escribiendo")
+    async def escribiendo(sock):            # si no usas los datos, no los pidas
+        await sock.broadcast({"type": "escribiendo"}, exclude_self=True)
+
+    @ws("chat/<str:room>/", group="room:{room}")
+    async def handler(sock, room):
+        await chat.run(sock)
+
+Es opcional del todo: `async for msg in sock` sigue estando ahi y no necesitas
+saber que esto existe.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+
+from .websocket import InvalidJSON
+
+logger = logging.getLogger("django_socket")
+
+CUALQUIERA = "*"
+
+
+class Events:
+    """
+    Despacha mensajes JSON segun un campo (por defecto `"type"`).
+
+    `key`     -- el campo que decide el tipo. Usa `Events(key="action")` si tu
+                 protocolo se llama de otra forma.
+    `strict`  -- que hacer con un tipo que nadie maneja. Por defecto se ignora
+                 (y se anota en el log); con `strict=True` se cierra con 4400.
+    """
+
+    def __init__(self, key: str = "type", strict: bool = False):
+        self.key = key
+        self.strict = strict
+        self._handlers: dict[str, tuple] = {}
+
+    def on(self, *tipos: str):
+        """
+        Registra un handler para uno o varios tipos.
+
+            @chat.on("mensaje")
+            @chat.on("entrar", "salir")     # varios de golpe
+            @chat.on("*")                   # lo que no case con nada mas
+
+        El handler puede pedir los datos o no:
+
+            async def handler(sock, datos)  -> datos = el mensaje sin el campo key
+            async def handler(sock)         -> te basta con saber que llego
+        """
+        if not tipos:
+            raise TypeError("@on() necesita al menos un tipo: @on('mensaje')")
+
+        def decorator(fn):
+            if not inspect.iscoroutinefunction(fn):
+                raise TypeError(
+                    f"@on espera 'async def', y {fn.__name__} es una funcion "
+                    f"normal."
+                )
+            quiere_datos = _quiere_datos(fn)
+            for tipo in tipos:
+                if tipo in self._handlers:
+                    anterior = self._handlers[tipo][0].__name__
+                    raise ValueError(
+                        f"El tipo {tipo!r} ya lo maneja {anterior}."
+                    )
+                self._handlers[tipo] = (fn, quiere_datos)
+            return fn
+
+        return decorator
+
+    @property
+    def tipos(self) -> list[str]:
+        return sorted(self._handlers)
+
+    async def run(self, sock) -> None:
+        """Consume mensajes hasta que el cliente cierra."""
+        async for msg in sock:
+            await self.handle(sock, msg.json())
+
+    async def handle(self, sock, datos) -> None:
+        """Despacha un mensaje ya parseado. Util para testear un handler suelto."""
+        if not isinstance(datos, dict):
+            raise InvalidJSON(datos, f"se esperaba un objeto con {self.key!r}")
+
+        tipo = datos.get(self.key)
+        entrada = self._handlers.get(tipo) or self._handlers.get(CUALQUIERA)
+
+        if entrada is None:
+            if self.strict:
+                raise InvalidJSON(
+                    datos, f"tipo {tipo!r} desconocido; hay: {self.tipos}"
+                )
+            # A nivel WARNING a proposito: casi siempre es una errata en el
+            # nombre del tipo, y en DEBUG no la ve nadie. Si tu protocolo manda
+            # tipos que de verdad quieres ignorar, registra un @on("*") vacio.
+            logger.warning(
+                "django_socket: nadie maneja %s=%r en %s (registrados: %s)",
+                self.key, tipo, sock.path, self.tipos or "ninguno",
+            )
+            return
+
+        handler, quiere_datos = entrada
+        if quiere_datos:
+            await handler(sock, {k: v for k, v in datos.items() if k != self.key})
+        else:
+            await handler(sock)
+
+
+def _quiere_datos(fn) -> bool:
+    """
+    Mira si el handler pide el payload ademas del socket.
+
+    Se resuelve una vez al registrar, no en cada mensaje.
+    """
+    params = [
+        p for p in inspect.signature(fn).parameters.values()
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(params) == 1:
+        return False
+    if len(params) == 2:
+        return True
+    raise TypeError(
+        f"{fn.__name__} debe aceptar (sock) o (sock, datos), no "
+        f"{len(params)} parametros posicionales."
+    )