django-socket 0.2.1__tar.gz → 0.3.0__tar.gz

{django_socket-0.2.1 → django_socket-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-socket
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -22,6 +22,7 @@ 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
@@ -155,14 +156,14 @@ python manage.py ws
 ```
 
 ```
-Rutas WebSocket
+WebSocket routes
   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)
+Integration
+  Broadcast layer       memory
+  asgi.py               nothing to do there (ASGIHandler widened)
+  Allowed origins       ALLOWED_HOSTS=[] (DEBUG)
+  Missing Origin        accepted (native clients)
 ```
 
 Run this first whenever something doesn't work: it tells you which routes exist,
@@ -662,15 +663,15 @@ async def paid_only(sock, next_):
 Two come included:
 
 ```python
-from django_socket.middleware import max_conexiones_por_usuario, registrar
+from django_socket.middleware import log_connections, max_connections_per_user
 
 DJANGO_SOCKET = {"MIDDLEWARE": [
-    max_conexiones_por_usuario(10),   # closes the 11th with 4429
-    registrar(),                      # one log line per connection
+    max_connections_per_user(10),   # closes the 11th with 4429
+    log_connections(),              # one log line per connection
 ]}
 ```
 
-`max_conexiones_por_usuario` counts per process: with N workers the real ceiling
+`max_connections_per_user` 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.
 
@@ -878,7 +879,7 @@ sustained rate:
 ```
 
 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
+of connections — for that you want `max_connections_per_user` and something in
 front of the app.
 
 ---

{django_socket-0.2.1 → django_socket-0.3.0}/README.md

@@ -112,14 +112,14 @@ python manage.py ws
 ```
 
 ```
-Rutas WebSocket
+WebSocket routes
   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)
+Integration
+  Broadcast layer       memory
+  asgi.py               nothing to do there (ASGIHandler widened)
+  Allowed origins       ALLOWED_HOSTS=[] (DEBUG)
+  Missing Origin        accepted (native clients)
 ```
 
 Run this first whenever something doesn't work: it tells you which routes exist,
@@ -619,15 +619,15 @@ async def paid_only(sock, next_):
 Two come included:
 
 ```python
-from django_socket.middleware import max_conexiones_por_usuario, registrar
+from django_socket.middleware import log_connections, max_connections_per_user
 
 DJANGO_SOCKET = {"MIDDLEWARE": [
-    max_conexiones_por_usuario(10),   # closes the 11th with 4429
-    registrar(),                      # one log line per connection
+    max_connections_per_user(10),   # closes the 11th with 4429
+    log_connections(),              # one log line per connection
 ]}
 ```
 
-`max_conexiones_por_usuario` counts per process: with N workers the real ceiling
+`max_connections_per_user` 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.
 
@@ -835,7 +835,7 @@ sustained rate:
 ```
 
 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
+of connections — for that you want `max_connections_per_user` and something in
 front of the app.
 
 ---

{django_socket-0.2.1 → django_socket-0.3.0}/django_socket/__init__.py

@@ -1,19 +1,24 @@
 """
-django_socket -- WebSockets en Django sin ceremonia.
+django_socket -- WebSockets in Django without ceremony.
 
-Instalar es: `pip install django-socket` y añadirlo a INSTALLED_APPS. Ya esta.
+Installing is: `pip install django-socket` and adding it to INSTALLED_APPS.
+That is all.
 
-    # miapp/sockets.py
+    # 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({"de": str(sock.user), "texto": msg.text})
+            await sock.broadcast({"from": str(sock.user), "text": msg.text})
 """
 
 from .asgi import ASGIApplication
-from .authentication import extraer_token, login_required
+from .authentication import (
+    extract_token,
+    extraer_token,  # noqa: F401  0.2.x alias, removed at 1.0
+    login_required,
+)
 from .events import Events
 from .groups import (
     BaseLayer,
@@ -33,23 +38,26 @@ from .websocket import (
     WebSocketDisconnect,
 )
 
-__version__ = "0.1.0"
+# Single source of truth for the version. `pyproject.toml` reads it from here
+# via `dynamic = ["version"]`, so the two cannot drift: they used to be
+# declared separately and the module stayed at 0.1.0 while PyPI was on 0.2.1.
+__version__ = "0.3.0"
 
 __all__ = [
-    # Lo que usaras el 99% del tiempo
+    # What you will use 99% of the time
     "ws",
     "Events",
     "broadcast",
     "broadcast_sync",
     "login_required",
-    "extraer_token",
-    # Tipos, para anotar
+    "extract_token",
+    # Types, for annotations
     "WebSocket",
     "Message",
     "WebSocketDisconnect",
     "WebSocketClosed",
     "InvalidJSON",
-    # Puntos de extension
+    # Extension points
     "ASGIApplication",
     "BaseLayer",
     "MemoryLayer",

{django_socket-0.2.1 → django_socket-0.3.0}/django_socket/apps.py

@@ -14,10 +14,13 @@ class DjangoSocketConfig(AppConfig):
         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
+        from . import (
+            checks,  # noqa: F401  (registered on import)
+            patch,
+            routing,
+        )
 
-        # Importa <cada_app>/sockets.py, igual que el admin con admin.py.
+        # Import <each_app>/sockets.py, the same way admin does with admin.py.
         autodiscover_modules("sockets")
 
         conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
@@ -26,7 +29,7 @@ class DjangoSocketConfig(AppConfig):
 
         found = routing.get_routes()
         logger.debug(
-            "django_socket: %d ruta(s): %s",
+            "django_socket: %d path(s): %s",
             len(found),
-            ", ".join(f"/{r.route}" for r in found) or "(ninguna)",
+            ", ".join(f"/{r.route}" for r in found) or "(none)",
         )

{django_socket-0.2.1 → django_socket-0.3.0}/django_socket/asgi.py

@@ -1,11 +1,11 @@
-"""Punto de entrada ASGI explicito.
+"""Explicit ASGI entry point.
 
-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`).
+You normally **need nothing from here**: adding "django_socket" to
+INSTALLED_APPS is enough, and the `asgi.py` that `startproject` generated
+serves WebSockets as-is (see `patch.py`).
 
-`ASGIApplication` existe para quien prefiere declararlo a mano, para componer
-con otro middleware ASGI, o para quien puso PATCH_ASGI=False.
+`ASGIApplication` exists for anyone who would rather declare it by hand, to
+compose with other ASGI middleware, or for anyone who set PATCH_ASGI=False.
 """
 
 from __future__ import annotations
@@ -15,20 +15,20 @@ from . import dispatch
 
 class ASGIApplication:
     """
-    Uso explicito en tu `asgi.py`:
+    Explicit use in your `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).
+    HTTP traffic goes to Django untouched; only the 'websocket' scope is
+    intercepted (and 'lifespan', to start and stop the fan-out layer).
     """
 
     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()
+            http_app = _wrap_static(get_asgi_application())  # runs django.setup()
         self.http_app = http_app
 
     async def __call__(self, scope, receive, send):
@@ -42,16 +42,16 @@ class ASGIApplication:
 
 def factory():
     """
-    App ASGI construida al vuelo, sin que el proyecto declare nada.
+    An ASGI app built on the fly, with nothing declared by the project.
 
-    La usa `runserver` cuando no hay ASGI_APPLICATION en settings, para que la
-    libreria funcione recien instalada.
+    `runserver` uses it when there is no ASGI_APPLICATION in settings, so the
+    library works straight after installing.
     """
     return ASGIApplication()
 
 
 def _wrap_static(app):
-    """En DEBUG sirve /static/ igual que hace `runserver`, sin tocar websockets."""
+    """In DEBUG serve /static/ like `runserver` does, without touching sockets."""
     from django.apps import apps
     from django.conf import settings
 

django_socket-0.3.0/django_socket/auth.py

@@ -0,0 +1,10 @@
+"""Compatibility. The implementation now lives in `authentication.py`.
+
+Kept because `django_socket.auth` existed in 0.1.0 and somebody may have
+imported it. The newer parts (pluggable authenticators, token) are in
+`django_socket.authentication`.
+"""
+
+from .authentication import login_required, resolve  # noqa: F401
+
+__all__ = ["resolve", "login_required"]

django_socket-0.3.0/django_socket/authentication.py

@@ -0,0 +1,283 @@
+"""Pluggable authentication.
+
+An authenticator is `async def (sock) -> user | None`. They are tried in order
+and the first one that returns something wins:
+
+    DJANGO_SOCKET = {
+        "AUTH": ["session", "token"],
+        "TOKEN_RESOLVER": "myapp.auth.from_jwt",
+    }
+
+or per route, when only one endpoint needs it:
+
+    @ws("feed/", auth="token")
+    @ws("panel/", auth=["session", "token"])
+    @ws("public/", auth=False)          # don't even try
+
+Writing your own is just a function:
+
+    async def by_api_key(sock):
+        key = sock.query_params.get("k")
+        return await Client.objects.filter(api_key=key).afirst()
+
+    DJANGO_SOCKET = {"AUTH": ["myapp.auth.by_api_key"]}
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger("django_socket")
+
+# How the token arrives, in order of preference.
+SCHEME = "bearer"
+
+
+# ------------------------------------------------------------------- session
+
+
+class _SessionCarrier:
+    """The minimum `django.contrib.auth.aget_user` expects from a request."""
+
+    __slots__ = ("session",)
+
+    def __init__(self, session):
+        self.session = session
+
+
+async def session(sock) -> Any | None:
+    """
+    Django's session cookie. This is the default.
+
+    It only works when the browser sends the cookie, which means a same-site
+    frontend. A SPA on another domain or a mobile app has no cookie: use
+    `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)
+    key = sock.cookies.get(settings.SESSION_COOKIE_NAME)
+    sock.session = engine.SessionStore(key)
+
+    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 extract_token(sock) -> str | None:
+    """
+    Pull the token from wherever the client was able to put it.
+
+    There are three places because **a browser cannot set headers** on a
+    WebSocket: the `new WebSocket(url, protocols)` API only lets you touch the
+    URL and `Sec-WebSocket-Protocol`. So:
+
+    1. `Sec-WebSocket-Protocol: bearer, <token>` -- the recommended route for
+       browsers. Not in the URL, so it never reaches your access logs.
+    2. `Authorization: Bearer <token>` -- for native clients, which can set
+       headers.
+    3. `?token=<token>` -- works everywhere, but **ends up written in the
+       access logs of your server and of every proxy in between**. Use it only
+       with short-lived, single-use tokens.
+    """
+    protos = [p.strip() for p in sock.subprotocols]
+    if len(protos) >= 2 and protos[0].lower() == SCHEME:
+        return protos[1]
+
+    header = sock.headers.get("authorization", "")
+    if header.lower().startswith(SCHEME + " "):
+        return header[len(SCHEME) + 1:].strip()
+
+    return sock.query_params.get("token")
+
+
+async def token(sock) -> Any | None:
+    """
+    A token, validated by the function you point us at.
+
+    The library cannot validate your token -- it might be a JWT, DRF's, or
+    something of your own -- so it only handles the transport and delegates the
+    part that matters:
+
+        DJANGO_SOCKET = {"TOKEN_RESOLVER": "myapp.auth.from_jwt"}
+
+        async def from_jwt(token):
+            data = jwt.decode(token, KEY, algorithms=["HS256"])
+            return await User.objects.filter(pk=data["sub"]).afirst()
+
+    If you set no `TOKEN_RESOLVER` and have `rest_framework.authtoken`
+    installed, that one is used as a reasonable shortcut.
+    """
+    raw = extract_token(sock)
+    if not raw:
+        return None
+
+    resolver = _get_token_resolver()
+    if resolver is None:
+        logger.warning(
+            "django_socket: a token arrived but nothing validates it. "
+            "Set DJANGO_SOCKET['TOKEN_RESOLVER'] to an "
+            "async(token) -> user | None function."
+        )
+        return None
+
+    try:
+        return await resolver(raw)
+    except Exception:
+        # An invalid token is normal, not an incident: don't fill the log with
+        # a traceback on every attempt.
+        logger.debug("django_socket: the resolver rejected the token", exc_info=True)
+        return None
+
+
+_resolver_cache: Callable | None = None
+_resolver_resolved = False
+
+
+def _get_token_resolver() -> Callable | None:
+    global _resolver_cache, _resolver_resolved
+    if _resolver_resolved:
+        return _resolver_cache
+
+    from django.conf import settings
+    from django.utils.module_loading import import_string
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    path = conf.get("TOKEN_RESOLVER")
+
+    if path:
+        _resolver_cache = import_string(path) if isinstance(path, str) else path
+    else:
+        _resolver_cache = _drf_resolver()
+
+    _resolver_resolved = True
+    return _resolver_cache
+
+
+def _drf_resolver() -> Callable | None:
+    """A shortcut for anyone already using `rest_framework.authtoken`."""
+    from django.apps import apps
+
+    if not apps.is_installed("rest_framework.authtoken"):
+        return None
+
+    async def from_drf(raw):
+        from rest_framework.authtoken.models import Token as DRFToken
+
+        row = await DRFToken.objects.select_related("user").filter(key=raw).afirst()
+        return row.user if row else None
+
+    return from_drf
+
+
+# ------------------------------------------------------------------ registry
+
+BUILTIN: dict[str, Callable] = {"session": session, "token": token}
+
+
+def resolve_authenticators(spec) -> list[Callable]:
+    """Normalize whatever `auth=` or settings hold into a list of functions."""
+    from django.utils.module_loading import import_string
+
+    if spec is True or spec is None:
+        spec = _default_spec()
+    if isinstance(spec, (str, bytes)) or callable(spec):
+        spec = [spec]
+
+    out = []
+    for item in spec:
+        if callable(item):
+            out.append(item)
+        elif item in BUILTIN:
+            out.append(BUILTIN[item])
+        else:
+            try:
+                out.append(import_string(item))
+            except ImportError as exc:
+                raise ValueError(
+                    f"Unknown authenticator: {item!r}. Use one of "
+                    f"{sorted(BUILTIN)}, an importable path, or an "
+                    f"async(sock) -> user | None function."
+                ) from exc
+    return out
+
+
+def _default_spec():
+    from django.conf import settings
+
+    conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
+    return conf.get("AUTH", ["session"])
+
+
+async def resolve(sock, spec=True) -> None:
+    """Fill `sock.user` with the first authenticator that recognises anyone."""
+    from django.contrib.auth.models import AnonymousUser
+
+    for authenticator in resolve_authenticators(spec):
+        try:
+            user = await authenticator(sock)
+        except Exception:
+            logger.exception(
+                "django_socket: authenticator %s failed",
+                getattr(authenticator, "__name__", authenticator),
+            )
+            continue
+        if user is not None:
+            sock.user = user
+            return
+
+    sock.user = AnonymousUser()
+
+
+def _clear_resolver_cache() -> None:
+    """Tests only: force TOKEN_RESOLVER to be read from settings again."""
+    global _resolver_cache, _resolver_resolved
+    _resolver_cache, _resolver_resolved = None, False
+
+
+def login_required(handler):
+    """
+    Close the connection with 4401 when the user is not authenticated.
+
+        @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
+
+
+# --------------------------------------------------------- 0.2.x compatibility
+# `extraer_token` was exported from `django_socket` in 0.2.x. Kept so upgrading
+# does not break anyone; removed at 1.0.
+extraer_token = extract_token

{django_socket-0.2.1 → django_socket-0.3.0}/django_socket/checks.py

@@ -1,15 +1,15 @@
-"""Avisos via `manage.py check`, para que los fallos de integracion salgan
-antes de desplegar y no como un socket que calla.
+"""Warnings via `manage.py check`, so integration mistakes surface before a
+deploy rather than as a socket that quietly does nothing.
 """
 
 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
+W001 = "django_socket.W001"  # memory layer with several workers
+W002 = "django_socket.W002"  # no routes registered
+W003 = "django_socket.W003"  # origins open to everything
+E001 = "django_socket.E001"  # unknown option in DJANGO_SOCKET
 
 KNOWN_KEYS = {
     "LAYER",
@@ -39,8 +39,8 @@ def check_settings(app_configs, **kwargs):
     if unknown:
         problems.append(
             Error(
-                f"Opcion(es) desconocida(s) en DJANGO_SOCKET: {sorted(unknown)}.",
-                hint=f"Las validas son: {sorted(KNOWN_KEYS)}.",
+                f"Unknown option(s) in DJANGO_SOCKET: {sorted(unknown)}.",
+                hint=f"The valid ones are: {sorted(KNOWN_KEYS)}.",
                 id=E001,
             )
         )
@@ -49,11 +49,11 @@ def check_settings(app_configs, **kwargs):
     if allowed and "*" in allowed and not settings.DEBUG:
         problems.append(
             Warning(
-                "DJANGO_SOCKET['ALLOWED_ORIGINS'] contiene '*' con DEBUG=False.",
+                "DJANGO_SOCKET['ALLOWED_ORIGINS'] contains '*' with 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."
+                    "Any website will be able to open a socket against yours carrying "
+                    "your users' session cookies (cross-site WebSocket "
+                    "hijacking). List the origins you trust."
                 ),
                 id=W003,
             )
@@ -70,22 +70,22 @@ def check_routes(app_configs, **kwargs):
         return []
     return [
         Warning(
-            "django_socket esta instalado pero no hay ninguna ruta websocket.",
+            "django_socket is installed but there are no websocket routes.",
             hint=(
-                "Crea <tu_app>/sockets.py y decora un 'async def' con @ws('...'). "
-                "Se autodescubre igual que admin.py."
+                "Create <your_app>/sockets.py and decorate an 'async def' with "
+                "@ws('...'). It is auto-discovered, the same way admin.py is."
             ),
             id=W002,
         )
     ]
 
 
-W004 = "django_socket.W004"  # token por query sin resolver configurado
+W004 = "django_socket.W004"  # token auth with no resolver configured
 
 
 @register()
 def check_auth(app_configs, **kwargs):
-    """Avisa de la combinacion que deja a todo el mundo anonimo en silencio."""
+    """Warn about the combination that silently leaves everyone anonymous."""
     from django.conf import settings
 
     conf = getattr(settings, "DJANGO_SOCKET", {}) or {}
@@ -99,14 +99,14 @@ def check_auth(app_configs, **kwargs):
         if not apps.is_installed("rest_framework.authtoken"):
             return [
                 Warning(
-                    "DJANGO_SOCKET['AUTH'] incluye 'token' pero no hay "
+                    "DJANGO_SOCKET['AUTH'] includes 'token' but there is no "
                     "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."
+                        "The library carries the token but cannot validate it. "
+                        "Set TOKEN_RESOLVER to an async(token) -> user | None "
+                        "function, or install rest_framework.authtoken. "
+                        "Without it everyone comes in anonymous and it is not "
+                        "obvious why."
                     ),
                     id=W004,
                 )