~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
"""Unit tests for queue-dispatch registration (FastAPI re-homing).
Under Flask, a before_request hook (notify_queue_processor) registered the
active user with the queue processor on every authenticated request — the
ONLY feeder of QueueProcessorV2._users_to_check, which the processing loop
reads to dispatch QUEUED researches. The FastAPI migration deleted that
hook without a replacement, so queued researches never started. The fix
registers the user (a) in notify_research_queued's queue fallback, at the
moment the research is actually queued, and (b) at login (post-login step
7) so QUEUED rows survive a server restart. These tests pin both paths.
"""
from unittest.mock import MagicMock, Mock, patch
MOD = "local_deep_research.web.queue.processor_v2"
def _ctx_session(db_session=None):
"""A context-manager mock for get_user_db_session."""
session = db_session or MagicMock()
cm = MagicMock()
cm.__enter__ = Mock(return_value=session)
cm.__exit__ = Mock(return_value=False)
return cm, session
class TestNotifyResearchQueuedRegistersDispatch:
def _processor(self):
from local_deep_research.web.queue.processor_v2 import (
QueueProcessorV2,
)
return QueueProcessorV2()
def test_queue_fallback_registers_user_for_dispatch(self):
"""When the research lands in the queue (here: no session password,
so the direct-start branch is skipped), the user MUST be added to
_users_to_check or the processing loop never dispatches it."""
processor = self._processor()
cm, _ = _ctx_session()
with (
patch(f"{MOD}.session_password_store") as store,
patch(f"{MOD}.get_user_db_session", return_value=cm),
patch(f"{MOD}.UserQueueService") as service_cls,
):
store.get_session_password.return_value = None
processor.notify_research_queued(
"alice", "rid-1", session_id="sess-1", query="q", mode="quick"
)
service_cls.return_value.add_task_metadata.assert_called_once()
assert ("alice", "sess-1") in processor._users_to_check
def test_no_session_id_does_not_register(self):
"""Without a session_id the loop could not resolve a password
anyway — no registration, but the queue metadata is still written
(the user's next login re-registers them)."""
processor = self._processor()
cm, _ = _ctx_session()
with (
patch(f"{MOD}.get_user_db_session", return_value=cm),
patch(f"{MOD}.UserQueueService"),
):
processor.notify_research_queued("alice", "rid-1")
assert processor._users_to_check == set()
def test_direct_start_does_not_register(self):
"""A research started directly never enters the queue, so the user
is not registered for queue checks."""
processor = self._processor()
db_session = MagicMock()
db_session.query.return_value.filter_by.return_value.count.return_value = 0
cm, _ = _ctx_session(db_session)
sm = Mock()
sm.get_setting.side_effect = lambda key, default=None: {
"app.queue_mode": "direct",
"app.max_concurrent_researches": 3,
}.get(key, default)
with (
patch(f"{MOD}.session_password_store") as store,
patch(f"{MOD}.db_manager") as dbm,
patch(f"{MOD}.get_user_db_session", return_value=cm),
patch(
"local_deep_research.settings.manager.SettingsManager",
return_value=sm,
),
patch.object(processor, "_start_research_directly") as start,
):
store.get_session_password.return_value = "pw"
dbm.open_user_database.return_value = Mock()
processor.notify_research_queued(
"alice", "rid-1", session_id="sess-1", query="q", mode="quick"
)
start.assert_called_once()
assert processor._users_to_check == set()
def test_direct_admission_takes_gate_before_database_open(self):
"""Direct handoff must follow the global gate -> database order."""
processor = self._processor()
gate = processor._get_user_critical_lock("alice")
gate_observations = []
fallback_cm, _ = _ctx_session()
def observe_open(*_args, **_kwargs):
gate_observations.append(gate.locked())
with (
patch(f"{MOD}.session_password_store") as store,
patch(
f"{MOD}.db_manager.open_user_database",
side_effect=observe_open,
),
patch(f"{MOD}.get_user_db_session", return_value=fallback_cm),
patch(f"{MOD}.UserQueueService"),
):
store.get_session_password.return_value = "pw"
processor.notify_research_queued(
"alice", "rid-order", session_id="sess-1", query="q"
)
assert gate_observations == [True]
assert gate.locked() is False
def test_direct_setup_failure_uses_queue_fallback_and_registers(self):
"""A failed direct-start setup must not strand the persisted queue row.
The helper used to swallow the failure and return ``None``; its caller
interpreted every return as "started" and skipped both TaskMetadata and
the only dispatch registration available under FastAPI.
"""
from local_deep_research.constants import ResearchStatus
from local_deep_research.database.models import (
ResearchHistory,
UserActiveResearch,
)
processor = self._processor()
settings_session = MagicMock()
settings_session.query.return_value.filter_by.return_value.count.return_value = 0
setup_session = MagicMock()
cleanup_session = MagicMock()
fallback_session = MagicMock()
settings_cm, _ = _ctx_session(settings_session)
setup_cm, _ = _ctx_session(setup_session)
cleanup_cm, _ = _ctx_session(cleanup_session)
fallback_cm, _ = _ctx_session(fallback_session)
active_record = Mock()
research_row = Mock()
def cleanup_query(model):
query = MagicMock()
query.filter_by.return_value = query
if model is UserActiveResearch:
query.first.return_value = active_record
elif model is ResearchHistory:
query.first.return_value = research_row
return query
cleanup_session.query.side_effect = cleanup_query
settings = Mock()
settings.get_setting.side_effect = lambda key, default=None: {
"app.queue_mode": "direct",
"app.max_concurrent_researches": 3,
}.get(key, default)
active_service = Mock()
active_service.update_task_status.side_effect = RuntimeError(
"TaskMetadata transition failed"
)
fallback_service = Mock()
with (
patch(f"{MOD}.session_password_store") as store,
patch(f"{MOD}.db_manager") as dbm,
patch(
f"{MOD}.get_user_db_session",
side_effect=[
settings_cm,
setup_cm,
cleanup_cm,
fallback_cm,
],
),
patch(
"local_deep_research.settings.manager.SettingsManager",
return_value=settings,
),
patch(
f"{MOD}.UserQueueService",
side_effect=[active_service, fallback_service],
),
patch(f"{MOD}.start_research_process") as start,
):
store.get_session_password.return_value = "pw"
dbm.open_user_database.return_value = Mock()
processor.notify_research_queued(
"alice", "rid-setup", session_id="sess-1", query="q"
)
start.assert_not_called()
cleanup_session.delete.assert_called_once_with(active_record)
assert research_row.status == ResearchStatus.QUEUED
cleanup_session.commit.assert_called_once()
fallback_service.add_task_metadata.assert_called_once_with(
task_id="rid-setup", task_type="research", priority=0
)
assert ("alice", "sess-1") in processor._users_to_check
def test_global_capacity_reject_cleans_up_then_registers_dispatch(self):
"""The global semaphore can reject after the per-user count allowed
direct mode. That later race must converge on the same queue fallback,
including cleanup, one metadata write, and dispatch registration.
"""
from local_deep_research.constants import ResearchStatus
from local_deep_research.database.models import (
ResearchHistory,
UserActiveResearch,
)
from local_deep_research.exceptions import SystemAtCapacityError
processor = self._processor()
settings_session = MagicMock()
settings_session.query.return_value.filter_by.return_value.count.return_value = 0
setup_session = MagicMock()
cleanup_session = MagicMock()
fallback_session = MagicMock()
active_record = Mock()
research_row = Mock()
def cleanup_query(model):
query = MagicMock()
query.filter_by.return_value = query
if model is UserActiveResearch:
query.first.return_value = active_record
elif model is ResearchHistory:
query.first.return_value = research_row
return query
cleanup_session.query.side_effect = cleanup_query
session_contexts = [
_ctx_session(session)[0]
for session in (
settings_session,
setup_session,
cleanup_session,
fallback_session,
)
]
settings = Mock()
settings.get_setting.side_effect = lambda key, default=None: {
"app.queue_mode": "direct",
"app.max_concurrent_researches": 3,
}.get(key, default)
active_service = Mock()
fallback_service = Mock()
with (
patch(f"{MOD}.session_password_store") as store,
patch(f"{MOD}.db_manager") as dbm,
patch(f"{MOD}.get_user_db_session", side_effect=session_contexts),
patch(
"local_deep_research.settings.manager.SettingsManager",
return_value=settings,
),
patch(
f"{MOD}.UserQueueService",
side_effect=[active_service, fallback_service],
),
patch(
f"{MOD}.start_research_process",
side_effect=SystemAtCapacityError("global slots full"),
),
):
store.get_session_password.return_value = "pw"
dbm.open_user_database.return_value = Mock()
processor.notify_research_queued(
"alice", "rid-capacity", session_id="sess-1", query="q"
)
active_service.update_task_status.assert_called_once_with(
"rid-capacity", "processing"
)
cleanup_session.delete.assert_called_once_with(active_record)
assert research_row.status == ResearchStatus.QUEUED
cleanup_session.commit.assert_called_once()
fallback_service.add_task_metadata.assert_called_once_with(
task_id="rid-capacity", task_type="research", priority=0
)
assert ("alice", "sess-1") in processor._users_to_check
def test_at_capacity_direct_mode_registers_for_later_dispatch(self):
"""Direct mode at max_concurrent falls through to the queue — the
user must be registered so the loop dispatches the queued research
when a running one completes and frees a slot."""
processor = self._processor()
db_session = MagicMock()
db_session.query.return_value.filter_by.return_value.count.return_value = 3
cm, _ = _ctx_session(db_session)
sm = Mock()
sm.get_setting.side_effect = lambda key, default=None: {
"app.queue_mode": "direct",
"app.max_concurrent_researches": 3,
}.get(key, default)
with (
patch(f"{MOD}.session_password_store") as store,
patch(f"{MOD}.db_manager") as dbm,
patch(f"{MOD}.get_user_db_session", return_value=cm),
patch(
"local_deep_research.settings.manager.SettingsManager",
return_value=sm,
),
patch(f"{MOD}.UserQueueService") as service_cls,
patch.object(processor, "_start_research_directly") as start,
):
store.get_session_password.return_value = "pw"
dbm.open_user_database.return_value = Mock()
processor.notify_research_queued(
"alice", "rid-1", session_id="sess-1", query="q", mode="quick"
)
start.assert_not_called()
service_cls.return_value.add_task_metadata.assert_called_once()
assert ("alice", "sess-1") in processor._users_to_check
class TestPostLoginQueueResume:
def test_post_login_step7_registers_user_with_processor(self):
"""Login is the restart-recovery anchor: _perform_post_login_tasks_body
must register (username, session_id) with the queue processor so
QUEUED rows from before a server restart get dispatched again."""
from local_deep_research.web.routers import auth as auth_module
with (
# Steps 1/4/6 die fast on the DB session seam (each step's
# try/except absorbs it) — step 7 must still run.
patch(
"local_deep_research.database.session_context.get_user_db_session",
side_effect=RuntimeError("db unavailable"),
),
patch(
"local_deep_research.database.library_init.initialize_library_for_user",
return_value={"success": True},
),
patch.object(
auth_module,
"auth_db_session",
side_effect=RuntimeError("auth db unavailable"),
),
patch(f"{MOD}.queue_processor") as qp,
):
auth_module._perform_post_login_tasks_body("alice", "pw", "sess-1")
qp.notify_user_activity.assert_called_once_with("alice", "sess-1")