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.

23.5 KB
Raw Blame
"""Socket.IO / WebSocket layer contract tests (Flask -> FastAPI migration).

src/local_deep_research/web/services/socketio_asgi.py replaces
flask-socketio with python-socketio's AsyncServer, mounted as an ASGI
sub-app at ``/ws`` (``socketio_path="/ws/socket.io"``). It authenticates
by manually verifying an itsdangerous-signed session cookie -- the same
scheme Starlette's SessionMiddleware uses -- rather than going through the
normal HTTP dependency chain. That makes it a bespoke auth boundary,
re-implemented from scratch, and the layer with the least existing test
coverage on this branch.

This file does NOT re-litigate ground already pinned elsewhere:

- tests/web/services/test_socketio_handshake_auth.py drives real
  itsdangerous signature verification (tampered/garbage/wrong-key/expired
  cookies), the connect()/on_subscribe() branch logic, and a real Engine.IO
  polling handshake for missing/garbage cookies.
- tests/web/services/test_socketio_connect_gate.py pins connect()'s
  lazy-DB-open branches with the cookie decode patched out.
- tests/web/services/test_socketio_asgi_user_scoping.py pins
  emit_to_user()'s sid-selection logic against _sid_users with a stubbed
  AsyncServer.
- tests/web/routers/test_fastapi_migration.py::test_socketio_mount_path
  black-box-probes that /ws/socket.io responds and /socket.io does not.

What's new here:

1. A cross-user delivery proof driven through the REAL mounted ASGI app,
   the REAL (unmocked) socketio.AsyncServer room targeting, and the REAL
   Engine.IO polling wire protocol -- not a stubbed AsyncServer. Two
   independently authenticated users are connected for real and an event
   emitted to one is proven, by reading back the actual queued packet, to
   never reach the other's socket.
2. A parity check that _decode_session_cookie can decode a cookie MINTED
   BY THE REAL SessionMiddleware after a real register+login -- not a
   cookie hand-built to this test's own understanding of the format (the
   existing hand-rolled-cookie tests would not catch a shared assumption
   bug between the two independent reimplementations).
3. emit_to_subscribers() / remove_subscriptions_for_research() invariants,
   which have no existing coverage at all: the "no subscribers -> drop,
   never broadcast" branch that source comments flag as the mechanism
   preventing one user's research progress from leaking to every
   connected client, and isolation between two different research_ids'
   subscriber sets.
4. A structural mount-table assertion (Mount object identity + the actual
   socketio_path string, cross-checked against the frontend's own
   hardcoded client config) rather than a black-box HTTP probe.
5. sid-recycling identity-swap safety: a disconnected sid reused by a
   different user's connection must carry the NEW user's identity, never
   a residue of the old one.
"""

import asyncio
import base64
import json
import re
import threading
import time
from importlib import resources as importlib_resources
from pathlib import Path
from unittest.mock import AsyncMock, Mock, patch

import itsdangerous
import pytest
from fastapi.testclient import TestClient
from starlette.routing import Mount

from local_deep_research.security import get_security_default
from local_deep_research.web.services import socketio_asgi
from local_deep_research.web.services.socketio_asgi import (
    connect,
    disconnect,
    emit_to_subscribers,
    emit_to_user,
    remove_subscriptions_for_research,
    socket_app,
)


def _make_session_cookie(
    session_data: dict,
    secret_key: str,
    timestamp: int | None = None,
    real_session: bool = True,
) -> str:
    """Build a session cookie value the way Starlette's SessionMiddleware
    does: base64(json(session)) signed with an itsdangerous TimestampSigner
    over the app's secret key. See starlette/middleware/sessions.py."""
    # The WebSocket handshake now validates session_id against the
    # server-side store (the revocation gate main's #5535 added and this
    # branch was missing). A fabricated session_id no longer authenticates
    # -- correctly -- so mint a REAL session for the username, letting these
    # tests exercise the gate rather than depend on its absence.
    if real_session and session_data.get("username"):
        from local_deep_research.web.auth.session_manager import (
            session_manager,
        )

        session_data = dict(session_data)
        session_data["session_id"] = session_manager.create_session(
            session_data["username"]
        )
    payload = base64.b64encode(json.dumps(session_data).encode("utf-8"))
    signer = itsdangerous.TimestampSigner(secret_key)
    if timestamp is not None:
        signer.get_timestamp = lambda: timestamp  # type: ignore[method-assign]
    return signer.sign(payload).decode("utf-8")


def _connected_db_manager() -> Mock:
    """A stub for the one true boundary these tests mock: the encrypted
    per-user DB manager. Reports the user's DB as already open so
    connect() doesn't need real SQLCipher I/O."""
    dbm = Mock()
    dbm.is_user_connected.return_value = True
    return dbm


def _open_and_connect(
    client: TestClient, cookie_value: str | None
) -> tuple[str, str]:
    """Drive one real Engine.IO polling handshake through the mounted ASGI
    app: open a transport session, then send the Socket.IO CONNECT packet
    ("40"). Returns (engine.io sid, the raw ack/refusal packet text)."""
    if cookie_value is not None:
        client.cookies.set("session", cookie_value)
    r_open = client.get("/ws/socket.io/?EIO=4&transport=polling")
    assert r_open.status_code == 200
    eio_sid = json.loads(r_open.text[1:])["sid"]
    r_connect = client.post(
        f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}",
        content="40",
        headers={"Content-Type": "text/plain"},
    )
    assert r_connect.status_code == 200
    r_ack = client.get(f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_sid}")
    return eio_sid, r_ack.text


@pytest.fixture
def secret_key(app) -> str:
    """The real app SECRET_KEY. Depends on `app` so fastapi_app's
    module-level import happens only after the `app` fixture has pointed
    LDR_DATA_DIR at an isolated temp dir -- never a real data directory."""
    from local_deep_research.web.fastapi_app import SECRET_KEY

    return SECRET_KEY


@pytest.fixture(autouse=True)
def _isolated_socketio_state():
    """Snapshot/restore module state so tests never see another test's
    (or another file's, under xdist) leftover sids/subscriptions, and so
    _lock is fresh (unbound to any closed event loop) for each test."""
    saved_users = dict(socketio_asgi._sid_users)
    saved_subs = {k: set(v) for k, v in socketio_asgi._subscriptions.items()}
    saved_lock = socketio_asgi._lock
    socketio_asgi._sid_users.clear()
    socketio_asgi._subscriptions.clear()
    socketio_asgi._lock = None
    yield
    socketio_asgi._sid_users.clear()
    socketio_asgi._sid_users.update(saved_users)
    socketio_asgi._subscriptions.clear()
    socketio_asgi._subscriptions.update(saved_subs)
    socketio_asgi._lock = saved_lock


@pytest.fixture
def background_loop():
    """A real running event loop on a background thread, installed as the
    module's captured main loop -- mirrors uvicorn's loop capture
    (set_main_loop) without a real server, for exercising the sync
    emit_to_* wrappers exactly as background research threads do."""
    loop = asyncio.new_event_loop()
    thread = threading.Thread(target=loop.run_forever, daemon=True)
    thread.start()
    socketio_asgi._lock = asyncio.Lock()
    with patch.object(socketio_asgi, "_get_main_loop", return_value=loop):
        yield loop
    loop.call_soon_threadsafe(loop.stop)
    thread.join(timeout=5)
    loop.close()


def _run_on(loop: asyncio.AbstractEventLoop, coro) -> None:
    """Block until a coroutine scheduled on `loop` from this thread has
    actually run -- a deterministic barrier, not a sleep-based race."""
    asyncio.run_coroutine_threadsafe(coro, loop).result(timeout=5)


# ---------------------------------------------------------------------------
# 1. _decode_session_cookie can decode a cookie the REAL SessionMiddleware
#    minted, not just one hand-built to mimic it.
# ---------------------------------------------------------------------------


class TestRealSessionMiddlewareCookieParity:
    """The existing tests (test_socketio_handshake_auth.py) hand-build a
    cookie to this test suite's own understanding of Starlette's format.
    If that understanding ever drifted from the real SessionMiddleware
    (different salt, different session-cookie name, different max_age
    default), those tests would still pass -- both sides share the same
    (possibly wrong) assumption. Driving a cookie the app's REAL
    SessionMiddleware actually issued closes that gap."""

    def test_decodes_a_cookie_actually_issued_by_sessionmiddleware(
        self, authenticated_client
    ):
        from local_deep_research.web.services.socketio_asgi import (
            _decode_session_cookie,
        )

        raw = authenticated_client.cookies.get("session")
        assert raw, "authenticated_client did not receive a 'session' cookie"

        decoded = _decode_session_cookie(f"session={raw}")

        assert decoded is not None, (
            "socketio_asgi._decode_session_cookie rejected a cookie signed "
            "by the app's real SessionMiddleware -- the WS handshake's "
            "signing scheme has drifted from the HTTP session scheme"
        )
        assert isinstance(decoded.get("username"), str)
        # generate_unique_test_username()'s default prefix (tests/conftest.py) --
        # a real, not fabricated, value round-tripped through the real cookie.
        assert decoded["username"].startswith("pytest_user_")
        assert (
            isinstance(decoded.get("session_id"), str) and decoded["session_id"]
        )


# ---------------------------------------------------------------------------
# 2. Cross-user delivery through the REAL mounted ASGI app + REAL AsyncServer
# ---------------------------------------------------------------------------


class TestRealCrossUserDeliveryThroughMountedApp:
    """emit_to_user's per-user isolation, proven end-to-end: real signed
    cookies, connect() run through the actual mounted ASGI transport, the
    real (unmocked) socketio.AsyncServer room targeting, and delivery
    verified by reading back the real queued Engine.IO packet -- not by
    mocking sio.emit and asserting on its call args."""

    def _authenticated_polling_connection(
        self, client: TestClient, username: str, secret_key: str
    ) -> str:
        cookie = _make_session_cookie(
            {"username": username, "session_id": f"s-{username}"}, secret_key
        )
        eio_sid, ack = _open_and_connect(client, cookie)
        assert ack.startswith("40"), f"{username}'s handshake refused: {ack!r}"
        return eio_sid

    def test_emit_to_user_reaches_only_the_targeted_users_real_socket(
        self, app, secret_key
    ):
        socketio_asgi.init_lock()
        dbm = _connected_db_manager()

        with patch("local_deep_research.database.encrypted_db.db_manager", dbm):
            client_alice = TestClient(app, raise_server_exceptions=False)
            client_bob = TestClient(app, raise_server_exceptions=False)
            eio_alice = self._authenticated_polling_connection(
                client_alice, "alice", secret_key
            )
            eio_bob = self._authenticated_polling_connection(
                client_bob, "bob", secret_key
            )

            assert set(socketio_asgi._sid_users.values()) == {"alice", "bob"}

            loop = asyncio.new_event_loop()
            thread = threading.Thread(target=loop.run_forever, daemon=True)
            thread.start()
            try:
                with patch.object(
                    socketio_asgi, "_get_main_loop", return_value=loop
                ):
                    assert (
                        emit_to_user(
                            "secret_settings", "alice", {"only": "alice"}
                        )
                        is True
                    )
                    # bob's own event, emitted right after, doubles as a
                    # fence: if bob's poll below returns it, we know the
                    # earlier alice-only emit had already been (or hadn't
                    # been) delivered to him by then.
                    assert (
                        emit_to_user("bob_marker", "bob", {"only": "bob"})
                        is True
                    )
                    _run_on(loop, asyncio.sleep(0))
            finally:
                loop.call_soon_threadsafe(loop.stop)
                thread.join(timeout=5)
                loop.close()

            r_alice = client_alice.get(
                f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_alice}"
            )
            r_bob = client_bob.get(
                f"/ws/socket.io/?EIO=4&transport=polling&sid={eio_bob}"
            )

        assert r_alice.status_code == 200
        assert "secret_settings" in r_alice.text
        assert '"only":"alice"' in r_alice.text.replace(" ", "")

        assert r_bob.status_code == 200
        assert "bob_marker" in r_bob.text
        # The core assertion: bob's queued packets never contain alice's
        # event -- this is the WS analogue of the cross-user leak this
        # branch is chasing on the HTTP side.
        assert "secret_settings" not in r_bob.text, (
            "CROSS-USER WS LEAK: bob's socket received an event emitted "
            f"only to alice. bob's poll body: {r_bob.text!r}"
        )

    def test_expired_but_validly_signed_cookie_rejected_through_real_wire(
        self, app, secret_key
    ):
        """Fills a mechanism gap in the existing wire-level coverage:
        test_socketio_handshake_auth.py's TestEndToEndPollingHandshake
        drives garbage and missing cookies through the real ASGI
        transport, but not a cookie that is validly SIGNED yet older than
        the remember-me horizon -- exactly the scenario the WS max_age
        mirroring fix (_decode_session_cookie's max_age= parameter)
        targets, driven here through the real wire, not a direct call."""
        socketio_asgi.init_lock()
        max_age = (
            get_security_default("security.session_remember_me_days", 30)
            * 24
            * 3600
        )
        stale_ts = int(time.time()) - max_age - 3600
        cookie = _make_session_cookie(
            {"username": "alice", "session_id": "s1"},
            secret_key,
            timestamp=stale_ts,
        )

        with patch(
            "local_deep_research.database.encrypted_db.db_manager",
            _connected_db_manager(),
        ):
            client = TestClient(app, raise_server_exceptions=False)
            _eio_sid, ack = _open_and_connect(client, cookie)

        assert ack.startswith("44"), (
            f"expired-but-validly-signed cookie was ACCEPTED at the real "
            f"WS handshake (should be refused): {ack!r}"
        )
        assert socketio_asgi._sid_users == {}


# ---------------------------------------------------------------------------
# 3. emit_to_subscribers / remove_subscriptions_for_research -- untested
#    elsewhere. The no-subscribers branch is explicitly flagged in the
#    source as the mechanism preventing a research-progress broadcast leak.
# ---------------------------------------------------------------------------


class TestEmitToSubscribersInvariants:
    def test_no_subscribers_drops_the_event_without_broadcasting(
        self, background_loop
    ):
        """socketio_asgi.py's _async_emit_to_subscribers docstring/comment:
        'No subscribers: drop the event. We must NOT broadcast -- that
        would leak one user's research progress to every connected
        client.' Pin that branch: zero sio.emit calls, not a broadcast."""
        rid = "rid-nobody-subscribed"
        assert ("owner-user", rid) not in socketio_asgi._subscriptions
        mock_sio = Mock()
        mock_sio.emit = AsyncMock()

        with patch.object(socketio_asgi, "sio", mock_sio):
            assert (
                emit_to_subscribers(
                    "research_progress", rid, {"p": 1}, owner="owner-user"
                )
                is True
            )
            _run_on(background_loop, asyncio.sleep(0))

        mock_sio.emit.assert_not_awaited()

    def test_only_subscribers_of_this_research_id_receive_the_event(
        self, background_loop
    ):
        """Two different research_ids' subscriber sets must never bleed
        into each other -- the subscription-scoped analogue of
        emit_to_user's cross-user isolation."""
        rid_a, rid_b = "rid-a", "rid-b"
        socketio_asgi._subscriptions[("owner-user", rid_a)] = {
            "sid-a1",
            "sid-a2",
        }
        socketio_asgi._subscriptions[("owner-user", rid_b)] = {"sid-b1"}
        mock_sio = Mock()
        mock_sio.emit = AsyncMock()

        with patch.object(socketio_asgi, "sio", mock_sio):
            assert (
                emit_to_subscribers(
                    "research_progress", rid_a, {"p": 42}, owner="owner-user"
                )
                is True
            )
            _run_on(background_loop, asyncio.sleep(0))

        rooms = {c.kwargs["room"] for c in mock_sio.emit.await_args_list}
        assert rooms == {"sid-a1", "sid-a2"}, (
            "emit_to_subscribers leaked to sid-b1, a subscriber of a "
            f"DIFFERENT research_id: rooms notified were {rooms!r}"
        )
        for call in mock_sio.emit.await_args_list:
            assert call.args[0] == f"research_progress_{rid_a}"
            assert call.args[1] == {"p": 42}

    def test_one_failing_subscriber_does_not_block_delivery_to_the_rest(
        self, background_loop
    ):
        rid = "rid-partial-fail"
        socketio_asgi._subscriptions[("owner-user", rid)] = {
            "sid-good",
            "sid-bad",
        }
        mock_sio = Mock()
        mock_sio.emit = AsyncMock(side_effect=[RuntimeError("gone"), None])

        with patch.object(socketio_asgi, "sio", mock_sio):
            assert (
                emit_to_subscribers(
                    "research_progress", rid, {}, owner="owner-user"
                )
                is True
            )
            _run_on(background_loop, asyncio.sleep(0))

        assert mock_sio.emit.await_count == 2

    def test_remove_subscriptions_for_research_stops_future_delivery(
        self, background_loop
    ):
        rid = "rid-to-remove"
        socketio_asgi._subscriptions[("owner-user", rid)] = {"sid-x"}

        remove_subscriptions_for_research(rid, "owner-user")
        _run_on(background_loop, asyncio.sleep(0))
        assert ("owner-user", rid) not in socketio_asgi._subscriptions

        mock_sio = Mock()
        mock_sio.emit = AsyncMock()
        with patch.object(socketio_asgi, "sio", mock_sio):
            assert (
                emit_to_subscribers(
                    "research_progress", rid, {}, owner="owner-user"
                )
                is True
            )
            _run_on(background_loop, asyncio.sleep(0))

        mock_sio.emit.assert_not_awaited()


# ---------------------------------------------------------------------------
# 4. Mount table: structural assertion, not a black-box HTTP probe.
# ---------------------------------------------------------------------------


class TestMountTable:
    """A silent path change here breaks every realtime update with no
    server-side error -- the only symptom is a frozen progress UI. Assert
    against the actual live route table and the frontend's own config,
    not just "some URL returns 200"."""

    def test_socket_app_is_mounted_at_ws_in_the_live_route_table(self, app):
        mounts = [
            r
            for r in app.routes
            if isinstance(r, Mount) and r.app is socket_app
        ]
        assert len(mounts) == 1, (
            "socket_app is not mounted exactly once on the live FastAPI "
            f"app's route table -- found {len(mounts)} Mount route(s)"
        )
        assert mounts[0].path == "/ws", (
            f"Socket.IO ASGI app is mounted at {mounts[0].path!r}, not "
            "'/ws' -- the frontend client will silently fail to connect"
        )

    def test_backend_socketio_path_matches_frontend_hardcoded_client_config(
        self,
    ):
        """Cross-check the backend's actual socketio_path against the
        frontend's own hardcoded `io(..., {path: ...})` config (read live
        from services/socket.js, the same importlib.resources lookup
        fastapi_app.py uses for STATIC_DIR) -- catches drift in either
        direction with no shared magic string between the two tests."""
        pkg_web = importlib_resources.files("local_deep_research") / "web"
        js_path = (
            Path(str(pkg_web)) / "static" / "js" / "services" / "socket.js"
        )
        source = js_path.read_text(encoding="utf-8")
        match = re.search(r"path:\s*'([^']+)'", source)
        assert match, (
            f"could not find the Socket.IO client 'path:' config in "
            f"{js_path} -- frontend config may have moved/renamed"
        )
        frontend_path = match.group(1)

        assert socket_app.engineio_path.rstrip("/") == frontend_path, (
            f"backend socket_app.engineio_path is "
            f"{socket_app.engineio_path!r} but the frontend is hardcoded "
            f"to connect at {frontend_path!r} -- realtime updates will "
            "silently stop working with no server-side error"
        )


# ---------------------------------------------------------------------------
# 5. sid lifecycle: a recycled sid must never inherit a prior user's identity.
# ---------------------------------------------------------------------------


class TestSidRecyclingIdentitySwap:
    def test_recycled_sid_gets_new_users_identity_not_the_old_ones(
        self, secret_key
    ):
        """Engine.IO sids are short-lived and can, in principle, be reused
        across unrelated sessions. disconnect() removing the sid from
        _sid_users (pinned elsewhere) is necessary but not sufficient --
        this proves a SUBSEQUENT connect() reusing the exact same sid
        string for a DIFFERENT user records that new user, with no trace
        of the old one left to inherit."""
        recycled_sid = "sid-recycled-by-engineio"
        alice_cookie = _make_session_cookie(
            {"username": "alice", "session_id": "s-alice"}, secret_key
        )
        bob_cookie = _make_session_cookie(
            {"username": "bob", "session_id": "s-bob"}, secret_key
        )
        dbm = _connected_db_manager()

        async def _run():
            socketio_asgi._lock = None
            socketio_asgi.init_lock()

            with patch(
                "local_deep_research.database.encrypted_db.db_manager", dbm
            ):
                accepted = await connect(
                    recycled_sid, {"HTTP_COOKIE": f"session={alice_cookie}"}
                )
            assert accepted is True
            assert socketio_asgi._sid_users[recycled_sid] == "alice"

            await disconnect(recycled_sid)
            assert recycled_sid not in socketio_asgi._sid_users

            with patch(
                "local_deep_research.database.encrypted_db.db_manager", dbm
            ):
                accepted = await connect(
                    recycled_sid, {"HTTP_COOKIE": f"session={bob_cookie}"}
                )
            assert accepted is True
            assert socketio_asgi._sid_users[recycled_sid] == "bob", (
                "sid reuse inherited the PREVIOUS occupant's identity -- "
                f"expected 'bob', got {socketio_asgi._sid_users.get(recycled_sid)!r}"
            )

        asyncio.run(_run())