Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

12.9 KB
Raw Blame
"""Subscription-map bookkeeping for the Socket.IO layer.

Ported from ``tests/web_services/test_socket_service.py`` on main (deleted
by the FastAPI migration). Most of that file's 58 tests have successors on
this branch — ownership (``tests/security/test_socket_ownership_edges_fastapi.py``),
owner-scoped delivery (``tests/web/services/test_subscription_owner_scoping.py``),
emit contracts (``test_socket_service_emit_contracts.py``), the connect gate
(``test_socketio_connect_gate.py``) — but four *bookkeeping* properties of the
unsubscribe path had none, and one registration property was pinned only
against Flask-SocketIO's ``socketio.on(...)`` API.

What is pinned here, and what breaks without it:

1. **The empty set is pruned.** ``on_unsubscribe`` deletes the
   ``(owner, research_id)`` key once its last sid leaves. Without the prune,
   ``_subscriptions`` accumulates a permanently-empty entry for every
   research_id any client has ever watched — unbounded growth on a
   long-running server, keyed by data the process can never garbage collect.
   (main: ``test_unsubscribe_prunes_empty_subscription_set``)

2. **A non-empty set survives.** The prune must not fire while other tabs
   are still subscribed, or one tab closing silently stops delivery to the
   user's other tabs. (main: ``test_unsubscribe_keeps_set_when_other_clients_remain``)

3. **Malformed and unknown payloads are no-ops, not crashes.** An
   unsubscribe with no ``research_id``, with ``data=None``, or naming a
   research_id nobody is subscribed to must leave the map untouched. An
   exception here escapes into the Socket.IO dispatcher.
   (main: ``test_unsubscribe_ignores_missing_research_id``,
   ``test_unsubscribe_handles_unknown_research_id``)

4. **Every event the shipped JS client emits has a server handler.** main
   pinned this as six separate ``socketio.on.assert_any_call("...")``
   assertions against the Flask-SocketIO constructor. The Flask-SocketIO
   registration API has no meaning here, but the underlying property does
   and is stronger stated as a census: an event the browser emits with no
   registered handler is silently dropped by python-socketio — no error,
   no log, the feature just stops working.

   main also registered ``"join"``/``"leave"`` aliases for
   subscribe/unsubscribe. They are NOT restored: no client in the repo —
   ``web/static/js`` on either main or this branch, the UI suites, or any
   Python socketio client — ever emits them, so they were dead
   registrations. The census below is what would catch it if a client
   started to.
"""

import asyncio

import pytest

from local_deep_research.web.auth.session_manager import session_manager
from local_deep_research.web.services import socketio_asgi as sio_mod

USER = "bookkeeping-user"
RESEARCH_ID = "research-abc-123"


@pytest.fixture
def socket_state(monkeypatch):
    """Isolated per-socket module state plus a capturing ``sio.emit``."""
    monkeypatch.setattr(sio_mod, "_lock", asyncio.Lock())
    monkeypatch.setattr(sio_mod, "_subscriptions", {})
    monkeypatch.setattr(sio_mod, "_sid_users", {})
    monkeypatch.setattr(sio_mod, "_sid_sessions", {})

    emitted: list[tuple] = []

    async def _capture(event, data=None, room=None, **kwargs):
        emitted.append((room, event, data))

    monkeypatch.setattr(sio_mod.sio, "emit", _capture)
    return emitted


def _register(sid, username=USER):
    """Register ``sid`` against a REAL live server-side session.

    Both handlers call ``_socket_session_still_valid``, so a fabricated
    session id would send every call below down the "session expired"
    branch and the tests would prove nothing about the paths they name.
    """
    token = session_manager.create_session(username, remember_me=False)
    sio_mod._sid_users[sid] = username
    sio_mod._sid_sessions[sid] = token
    return token


def _subscribe(sid, research_id=RESEARCH_ID, monkeypatch=None):
    """Drive the real ``on_subscribe`` with ownership granted."""
    orig = sio_mod._user_owns_research

    async def _owns(*_a, **_k):
        return True

    sio_mod._user_owns_research = _owns
    try:
        asyncio.run(sio_mod.on_subscribe(sid, {"research_id": research_id}))
    finally:
        sio_mod._user_owns_research = orig


def _unsubscribe(sid, data):
    """Drive the real ``on_unsubscribe`` with ownership granted."""
    orig = sio_mod._user_owns_research

    async def _owns(*_a, **_k):
        return True

    sio_mod._user_owns_research = _owns
    try:
        asyncio.run(sio_mod.on_unsubscribe(sid, data))
    finally:
        sio_mod._user_owns_research = orig


# ---------------------------------------------------------------------------
# 1-2. Prune / keep
# ---------------------------------------------------------------------------


class TestUnsubscribePruning:
    def test_removing_the_last_sid_deletes_the_entry(self, socket_state):
        """The registry must not accumulate empty sets forever."""
        token = _register("sid-only")
        try:
            _subscribe("sid-only")
            key = sio_mod._subscription_key(USER, RESEARCH_ID)
            assert sio_mod._subscriptions == {key: {"sid-only"}}, (
                "positive control: the subscribe itself must have landed, "
                "or the prune assertion below passes vacuously"
            )

            _unsubscribe("sid-only", {"research_id": RESEARCH_ID})

            assert key not in sio_mod._subscriptions, (
                "the last subscriber left but the (owner, research_id) key "
                "survives as an empty set — _subscriptions grows without "
                "bound over the life of the process"
            )
        finally:
            session_manager.destroy_session(token)

    def test_the_entry_survives_while_another_tab_holds_it(self, socket_state):
        """Prune must be conditional. One tab closing must not stop
        delivery to the same user's other open tabs."""
        token = _register("sid-tab-1")
        try:
            _subscribe("sid-tab-1")
            key = sio_mod._subscription_key(USER, RESEARCH_ID)
            # A second tab of the same user, same session.
            sio_mod._sid_users["sid-tab-2"] = USER
            sio_mod._sid_sessions["sid-tab-2"] = token
            sio_mod._subscriptions[key].add("sid-tab-2")

            _unsubscribe("sid-tab-1", {"research_id": RESEARCH_ID})

            assert sio_mod._subscriptions[key] == {"sid-tab-2"}, (
                "unsubscribing one tab dropped the whole entry; the user's "
                "other tab stops receiving progress"
            )
        finally:
            session_manager.destroy_session(token)

    def test_only_the_calling_sid_is_removed_from_a_shared_entry(
        self, socket_state
    ):
        """``discard`` must name the caller, never clear the set."""
        token = _register("sid-caller")
        try:
            _subscribe("sid-caller")
            key = sio_mod._subscription_key(USER, RESEARCH_ID)
            sio_mod._subscriptions[key].update({"sid-x", "sid-y"})

            _unsubscribe("sid-caller", {"research_id": RESEARCH_ID})

            assert sio_mod._subscriptions[key] == {"sid-x", "sid-y"}
        finally:
            session_manager.destroy_session(token)


# ---------------------------------------------------------------------------
# 3. Malformed / unknown payloads
# ---------------------------------------------------------------------------


class TestUnsubscribeMalformedPayloads:
    @pytest.mark.parametrize(
        "data", [{}, None, {"research_id": ""}, {"research_id": None}, []]
    )
    def test_a_payload_without_a_research_id_changes_nothing(
        self, socket_state, data
    ):
        token = _register("sid-noisy")
        try:
            _subscribe("sid-noisy")
            before = {k: set(v) for k, v in sio_mod._subscriptions.items()}
            assert before, "positive control: seed the map first"

            _unsubscribe("sid-noisy", data)

            assert sio_mod._subscriptions == before
        finally:
            session_manager.destroy_session(token)

    @pytest.mark.parametrize("data", [{}, None, {"research_id": ""}, []])
    def test_no_research_id_never_reaches_the_ownership_lookup(
        self, socket_state, data
    ):
        """The state assertion above cannot see the ``if not research_id``
        guard on ``on_unsubscribe``: with it deleted, the handler falls
        through to ``_subscriptions.get((owner, ""))``, which is never a
        key, so ``discard`` is a no-op either way and the map is identical.
        (Verified: deleting that guard left every test above green.)

        What the guard actually buys is that a junk payload never costs an
        encrypted-DB ownership query — a free amplification vector for an
        authenticated client spraying empty unsubscribes. That IS visible,
        so pin it here."""
        token = _register("sid-guard")
        try:
            _subscribe("sid-guard")

            consulted = []
            orig = sio_mod._user_owns_research

            async def _owns(username, research_id):
                consulted.append((username, research_id))
                return True

            sio_mod._user_owns_research = _owns
            try:
                asyncio.run(sio_mod.on_unsubscribe("sid-guard", data))
            finally:
                sio_mod._user_owns_research = orig

            assert consulted == [], (
                f"an unsubscribe carrying no research_id ({data!r}) still ran "
                f"an ownership query {consulted!r}; the early return is gone"
            )
        finally:
            session_manager.destroy_session(token)

    def test_an_unknown_research_id_is_a_silent_no_op(self, socket_state):
        token = _register("sid-lost")
        try:
            _subscribe("sid-lost")
            before = {k: set(v) for k, v in sio_mod._subscriptions.items()}

            _unsubscribe("sid-lost", {"research_id": "never-subscribed"})

            assert sio_mod._subscriptions == before
        finally:
            session_manager.destroy_session(token)

    @pytest.mark.parametrize("data", [{}, None, {"research_id": ""}])
    def test_subscribe_with_no_research_id_changes_nothing(
        self, socket_state, data
    ):
        """The mirror guard on ``on_subscribe``. main pinned the empty
        string separately from the missing key; both take the same
        ``if not research_id`` exit."""
        token = _register("sid-empty")
        try:
            orig = sio_mod._user_owns_research

            async def _owns(*_a, **_k):
                return True

            sio_mod._user_owns_research = _owns
            try:
                asyncio.run(sio_mod.on_subscribe("sid-empty", data))
            finally:
                sio_mod._user_owns_research = orig

            assert sio_mod._subscriptions == {}
        finally:
            session_manager.destroy_session(token)


# ---------------------------------------------------------------------------
# 4. Handler-registration census
# ---------------------------------------------------------------------------


class TestHandlerRegistrationCensus:
    """Every event the shipped JS emits must have a registered handler."""

    @staticmethod
    def _registered_events():
        # python-socketio keeps handlers per namespace: {"/": {event: fn}}.
        return set(sio_mod.sio.handlers.get("/", {}))

    def test_the_census_reads_a_non_empty_handler_table(self):
        """Guard the guard: an API change that emptied ``sio.handlers``
        would make the census below pass vacuously."""
        assert self._registered_events(), (
            "sio.handlers['/'] is empty; the census cannot see anything"
        )

    @pytest.mark.parametrize(
        "event",
        [
            "connect",
            "disconnect",
            "subscribe_to_research",
            "unsubscribe_from_research",
        ],
    )
    def test_the_handler_is_registered(self, event):
        assert event in self._registered_events(), (
            f"no server handler for '{event}': python-socketio drops the "
            "frame silently — no error, no log, the feature just stops"
        )

    def test_every_event_the_shipped_js_emits_has_a_handler(self):
        """The census proper, read out of the checked-in client.

        Scoped to ``socket.js``, which owns the research socket; other JS
        files talk to HTTP endpoints.
        """
        import re
        from pathlib import Path

        js = (
            Path(sio_mod.__file__).resolve().parents[1]
            / "static"
            / "js"
            / "services"
            / "socket.js"
        )
        assert js.is_file(), js
        emitted = set(
            re.findall(
                r"socket\.emit\(\s*['\"]([a-zA-Z0-9_]+)['\"]", js.read_text()
            )
        )
        assert emitted, "found no socket.emit() calls; the regex is stale"

        missing = sorted(emitted - self._registered_events())
        assert not missing, (
            f"socket.js emits {missing} but the server registers no handler "
            "for them; those frames are silently discarded"
        )