django-socket 0.2.0__py3-none-any.whl

django_socket/__init__.py

@@ -0,0 +1,61 @@
+"""
+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 .authentication import extraer_token, 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",
+    "extraer_token",
+    # 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,10 @@
+"""Compatibilidad. La implementacion vive ahora en `authentication.py`.
+
+Se mantiene porque `django_socket.auth` existia en 0.1.0 y alguien pudo
+importarlo. Lo nuevo (autenticadores conectables, token) esta en
+`django_socket.authentication`.
+"""
+
+from .authentication import login_required, resolve  # noqa: F401
+
+__all__ = ["resolve", "login_required"]

django_socket/authentication.py

@@ -0,0 +1,278 @@
+"""Autenticacion conectable.
+
+Un autenticador es `async def (sock) -> user | None`. Se prueban en orden y
+gana el primero que devuelva algo:
+
+    DJANGO_SOCKET = {
+        "AUTH": ["session", "token"],
+        "TOKEN_RESOLVER": "miapp.auth.desde_jwt",
+    }
+
+o por ruta, cuando solo un endpoint lo necesita:
+
+    @ws("feed/", auth="token")
+    @ws("panel/", auth=["session", "token"])
+    @ws("publico/", auth=False)          # ni lo intentes
+
+Escribir el tuyo es una funcion:
+
+    async def por_api_key(sock):
+        clave = sock.query_params.get("k")
+        return await Cliente.objects.filter(api_key=clave).afirst()
+
+    DJANGO_SOCKET = {"AUTH": ["miapp.auth.por_api_key"]}
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger("django_socket")
+
+# Como llega el token, en orden de preferencia.
+ESQUEMA = "bearer"
+
+
+# --------------------------------------------------------------------- sesion
+
+
+class _SessionCarrier:
+    """Lo minimo que `django.contrib.auth.aget_user` espera de un request."""
+
+    __slots__ = ("session",)
+
+    def __init__(self, session):
+        self.session = session
+
+
+async def session(sock) -> Any | None:
+    """
+    La cookie de sesion de Django. Es el modo por defecto.
+
+    Solo funciona si el navegador manda la cookie, o sea con el frontend
+    servido desde el mismo sitio. Para un SPA en otro dominio o una app movil
+    no hay cookie: usa `token`.
+    """
+    from importlib import import_module
+
+    from django.apps import apps
+    from django.conf import settings
+
+    if not (
+        apps.is_installed("django.contrib.auth")
+        and apps.is_installed("django.contrib.sessions")
+    ):
+        return None
+
+    engine = import_module(settings.SESSION_ENGINE)
+    clave = sock.cookies.get(settings.SESSION_COOKIE_NAME)
+    sock.session = engine.SessionStore(clave)
+
+    try:
+        from django.contrib.auth import aget_user
+    except ImportError:  # Django < 5.0
+        from asgiref.sync import sync_to_async
+        from django.contrib.auth import get_user
+
+        user = await sync_to_async(get_user)(_SessionCarrier(sock.session))
+    else:
+        user = await aget_user(_SessionCarrier(sock.session))
+
+    return user if getattr(user, "is_authenticated", False) else None
+
+
+# ---------------------------------------------------------------------- token
+
+
+def extraer_token(sock) -> str | None:
+    """
+    Saca el token de donde el cliente haya podido ponerlo.
+
+    Hay tres sitios porque **el navegador no puede fijar cabeceras** en un
+    WebSocket: la API `new WebSocket(url, protocols)` solo deja tocar la URL y
+    `Sec-WebSocket-Protocol`. Asi que:
+
+    1. `Sec-WebSocket-Protocol: bearer, <token>` -- la via recomendada para
+       navegadores. No se ve en la URL, luego no acaba en los logs.
+    2. `Authorization: Bearer <token>` -- para clientes nativos, que si pueden
+       poner cabeceras.
+    3. `?token=<token>` -- funciona en todas partes, pero **queda escrito en
+       los logs de acceso del servidor y de cualquier proxy por el que pase**.
+       Usalo solo con tokens de un solo uso y vida corta.
+    """
+    protocolos = [p.strip() for p in sock.subprotocols]
+    if len(protocolos) >= 2 and protocolos[0].lower() == ESQUEMA:
+        return protocolos[1]
+
+    cabecera = sock.headers.get("authorization", "")
+    if cabecera.lower().startswith(ESQUEMA + " "):
+        return cabecera[len(ESQUEMA) + 1:].strip()
+
+    return sock.query_params.get("token")
+
+
+async def token(sock) -> Any | None:
+    """
+    Un token, resuelto por la funcion que tu indiques.
+
+    La libreria no sabe validar tu token -- puede ser un JWT, el de DRF, o algo
+    tuyo -- asi que solo hace el transporte y te delega la parte que importa:
+
+        DJANGO_SOCKET = {"TOKEN_RESOLVER": "miapp.auth.desde_jwt"}
+
+        async def desde_jwt(token):
+            datos = jwt.decode(token, KEY, algorithms=["HS256"])
+            return await User.objects.filter(pk=datos["sub"]).afirst()
+
+    Si no configuras `TOKEN_RESOLVER` y tienes `rest_framework.authtoken`
+    instalado, se usa ese como atajo razonable.
+    """
+    crudo = extraer_token(sock)
+    if not crudo:
+        return None
+
+    resolver = _get_token_resolver()
+    if resolver is None:
+        logger.warning(
+            "django_socket: llego un token pero no hay quien lo valide. "
+            "Define DJANGO_SOCKET['TOKEN_RESOLVER'] con una funcion "
+            "async(token) -> user | None."
+        )
+        return None
+
+    try:
+        return await resolver(crudo)
+    except Exception:
+        # Un token invalido es lo normal, no un incidente: no ensucies el log
+        # con una traza por cada intento.
+        logger.debug("django_socket: el resolver rechazo el token", exc_info=True)
+        return None
+
+
+_resolver_cache: Callable | None = None
+_resolver_resuelto = False
+
+
+def _get_token_resolver() -> Callable | None:
+    global _resolver_cache, _resolver_resuelto
+    if _resolver_resuelto:
+        return _resolver_cache
+
+    from django.conf import settings
+    from django.utils.module_loading import import_string
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    ruta = conf.get("TOKEN_RESOLVER")
+
+    if ruta:
+        _resolver_cache = import_string(ruta) if isinstance(ruta, str) else ruta
+    else:
+        _resolver_cache = _resolver_drf()
+
+    _resolver_resuelto = True
+    return _resolver_cache
+
+
+def _resolver_drf() -> Callable | None:
+    """Atajo para quien ya use `rest_framework.authtoken`."""
+    from django.apps import apps
+
+    if not apps.is_installed("rest_framework.authtoken"):
+        return None
+
+    async def desde_drf(crudo):
+        from rest_framework.authtoken.models import Token as DRFToken
+
+        fila = await DRFToken.objects.select_related("user").filter(
+            key=crudo
+        ).afirst()
+        return fila.user if fila else None
+
+    return desde_drf
+
+
+# ------------------------------------------------------------------ registro
+
+INCORPORADOS: dict[str, Callable] = {"session": session, "token": token}
+
+
+def resolver_lista(spec) -> list[Callable]:
+    """Normaliza lo que venga en `auth=` o en settings a una lista de funciones."""
+    from django.utils.module_loading import import_string
+
+    if spec is True or spec is None:
+        spec = _por_defecto()
+    if isinstance(spec, (str, bytes)) or callable(spec):
+        spec = [spec]
+
+    salida = []
+    for item in spec:
+        if callable(item):
+            salida.append(item)
+        elif item in INCORPORADOS:
+            salida.append(INCORPORADOS[item])
+        else:
+            try:
+                salida.append(import_string(item))
+            except ImportError as exc:
+                raise ValueError(
+                    f"Autenticador desconocido: {item!r}. Usa "
+                    f"{sorted(INCORPORADOS)}, una ruta importable, o una "
+                    f"funcion async(sock) -> user | None."
+                ) from exc
+    return salida
+
+
+def _por_defecto():
+    from django.conf import settings
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    return conf.get("AUTH", ["session"])
+
+
+async def resolve(sock, spec=True) -> None:
+    """Rellena `sock.user` con el primer autenticador que reconozca a alguien."""
+    from django.contrib.auth.models import AnonymousUser
+
+    for autenticador in resolver_lista(spec):
+        try:
+            user = await autenticador(sock)
+        except Exception:
+            logger.exception(
+                "django_socket: el autenticador %s fallo",
+                getattr(autenticador, "__name__", autenticador),
+            )
+            continue
+        if user is not None:
+            sock.user = user
+            return
+
+    sock.user = AnonymousUser()
+
+
+def _limpiar_cache_resolver() -> None:
+    """Solo para tests: obliga a releer TOKEN_RESOLVER de settings."""
+    global _resolver_cache, _resolver_resuelto
+    _resolver_cache, _resolver_resuelto = None, False
+
+
+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,114 @@
+"""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",
+    "AUTH",
+    "TOKEN_RESOLVER",
+    "MIDDLEWARE",
+    "RATE_LIMIT",
+    "RATE_LIMIT_BURST",
+}
+
+
+@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,
+        )
+    ]
+
+
+W004 = "django_socket.W004"  # token por query sin resolver configurado
+
+
+@register()
+def check_auth(app_configs, **kwargs):
+    """Avisa de la combinacion que deja a todo el mundo anonimo en silencio."""
+    from django.conf import settings
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    autenticadores = conf.get("AUTH", ["session"])
+    usa_token = any(
+        a == "token" or getattr(a, "__name__", "") == "token" for a in autenticadores
+    )
+    if usa_token and not conf.get("TOKEN_RESOLVER"):
+        from django.apps import apps
+
+        if not apps.is_installed("rest_framework.authtoken"):
+            return [
+                Warning(
+                    "DJANGO_SOCKET['AUTH'] incluye 'token' pero no hay "
+                    "TOKEN_RESOLVER.",
+                    hint=(
+                        "La libreria transporta el token pero no sabe validarlo. "
+                        "Define TOKEN_RESOLVER con una funcion "
+                        "async(token) -> user | None, o instala "
+                        "rest_framework.authtoken. Sin eso, todo el mundo "
+                        "entra como anonimo y no es evidente por que."
+                    ),
+                    id=W004,
+                )
+            ]
+    return []