~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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"
)