~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
"""Error-path pins for ``web.dependencies.auth::get_db_session_dep``.
This dependency is deliberately NOT wired to any route (the thread-affinity
hazard on its ``with get_user_db_session(...)`` block is documented at
length in its own docstring, and pinned against
``fastapi.concurrency.contextmanager_in_threadpool`` in
``tests/web/dependencies/test_dependency_contracts.py``). But "not wired
today" is not "dead code": its single consumer
(``get_settings_manager_dep``) is one ``Depends()`` away from any future
route, and the error paths below are the ones that decide whether a broken
credential state produces a clean re-login prompt or a stuck client.
These paths are already pinned end-to-end at route level in
``tests/web/dependencies/test_dependency_resolution_contracts.py``
(real generator wired into FastAPI: open-time ``DatabaseSessionError``
-> clear/401, ``None`` -> 500 without clear, handler-time
``DatabaseSessionError`` -> forced logout, unrelated handler error ->
500 with session retained). What this file adds is the same real
generator driven DIRECTLY — no app/route/TestClient wiring — with the
throw point under explicit fixture control:
1. ``DatabaseSessionError`` -> ``request.session.clear()`` -> 401
"Session expired". This is the revocation behavior that makes a
dead password store self-heal: without the clear, the browser keeps
presenting a cookie that can never work again and every request 401s
forever (the exact "stale session" failure mode
``clear_session_if_unrecoverable`` exists to prevent on the auth path).
2. A ``None`` session from the context manager -> 500, not a silent
success that hands the handler ``None`` where a ``Session`` was typed.
3. ONLY ``DatabaseSessionError`` maps to 401. A generic exception must
propagate untouched — if the ``except`` ever widens to ``Exception``
(a favourite "robustness" refactor), bug signals would disappear into
401s and login loops, so that widening must fail this pin.
4. Its ``DatabaseSessionUnavailableError`` subclass (a rekey operational
fault, not a credential problem) maps to a retryable 503 with
``Retry-After`` and leaves the session alone.
Both entry routes into the ``except`` are covered: the error raised while
*opening* the session (``__enter__``), and the error thrown *back into the
yield* (handler-time), since FastAPI delivers handler exceptions into
generator dependencies exactly that way.
"""
import pytest
from fastapi import HTTPException
from starlette.requests import Request
from local_deep_research.database.session_context import DatabaseSessionError
from local_deep_research.web.dependencies.auth import get_db_session_dep
class _FakeSessionContext:
"""Stand-in for the ``get_user_db_session(...)`` context manager.
``enter_exc`` raises from ``__enter__`` (credential resolution /
open failure); ``yield_exc`` is thrown into the generator at yield
time (handler-time failure). ``__exit__`` never swallows.
"""
def __init__(self, session=None, enter_exc=None, yield_exc=None):
self._session = session
self._enter_exc = enter_exc
self._yield_exc = yield_exc
self.exited = False
def __enter__(self):
if self._enter_exc is not None:
raise self._enter_exc
return self._session
def __exit__(self, exc_type, exc, tb):
self.exited = True
return False
def _request_with_session(session_dict):
scope = {
"type": "http",
"method": "GET",
"path": "/",
"headers": [],
"session": session_dict,
}
return Request(scope)
def _patch_ctx(monkeypatch, ctx):
monkeypatch.setattr(
"local_deep_research.web.dependencies.auth.get_user_db_session",
lambda username, session_id=None: ctx,
)
return ctx
class TestHappyPath:
def test_yields_the_resolved_session(self, monkeypatch):
sentinel = object()
_patch_ctx(monkeypatch, _FakeSessionContext(session=sentinel))
request = _request_with_session(
{"username": "alice", "session_id": "sid-1"}
)
gen = get_db_session_dep(request, "alice")
assert next(gen) is sentinel
gen.close()
class TestDatabaseSessionErrorPaths:
def test_open_failure_clears_session_and_raises_401(self, monkeypatch):
_patch_ctx(
monkeypatch,
_FakeSessionContext(enter_exc=DatabaseSessionError("gone")),
)
session_dict = {"username": "alice", "session_id": "sid-1"}
request = _request_with_session(session_dict)
with pytest.raises(HTTPException) as excinfo:
next(get_db_session_dep(request, "alice"))
assert excinfo.value.status_code == 401
assert excinfo.value.detail == "Session expired — please log in again"
# The revocation half of the contract: the cookie payload is wiped
# so the client stops presenting a credential that can never
# resolve again.
assert session_dict == {}
def test_handler_time_failure_clears_session_and_raises_401(
self, monkeypatch
):
# FastAPI delivers a handler exception into a yield-dependency via
# gen.throw(); a DatabaseSessionError taking that route must land
# in the same 401+clear bucket as an open-time failure.
ctx = _patch_ctx(monkeypatch, _FakeSessionContext(session=object()))
session_dict = {"username": "alice", "session_id": "sid-2"}
request = _request_with_session(session_dict)
gen = get_db_session_dep(request, "alice")
next(gen)
with pytest.raises(HTTPException) as excinfo:
gen.throw(DatabaseSessionError("revoked mid-request"))
assert excinfo.value.status_code == 401
assert session_dict == {}
assert ctx.exited
class TestNonCredentialFailures:
def test_none_session_raises_500_not_silent_success(self, monkeypatch):
_patch_ctx(monkeypatch, _FakeSessionContext(session=None))
request = _request_with_session({"username": "alice"})
with pytest.raises(HTTPException) as excinfo:
next(get_db_session_dep(request, "alice"))
assert excinfo.value.status_code == 500
def test_generic_exception_is_not_masked_as_401(self, monkeypatch):
# Only DatabaseSessionError may map to the "log in again" bucket.
# A bare/broadened except here would convert real bugs (driver
# errors, programming errors) into login loops and hide them from
# logs and monitors alike.
_patch_ctx(
monkeypatch, _FakeSessionContext(enter_exc=RuntimeError("boom"))
)
request = _request_with_session({"username": "alice"})
with pytest.raises(RuntimeError, match="boom"):
next(get_db_session_dep(request, "alice"))
def _session_unavailable():
# Imported here so this module still collects against a tree that
# predates the subclass (the fail-on-old run).
from local_deep_research.database.session_context import (
DatabaseSessionUnavailableError,
)
return DatabaseSessionUnavailableError("RekeySidecarIOError")
class TestOperationalFaultKeepsTheSession:
"""A rekey sidecar fault is not a reason to log the user out.
``get_user_db_session`` raises ``DatabaseSessionUnavailableError`` (a
``DatabaseSessionError`` subclass) when the database could not be
opened or claimed because of a rekey operational fault, e.g. an
fd-exhaustion spike that began after ``require_auth``'s probe passed.
Caught by the base-class clause, it cleared the cookie and answered
401. It must get ``require_auth``'s retryable 503 and leave the session
as it was, from either entry route into the ``except``.
"""
@staticmethod
def _assert_retryable_503(excinfo, session_dict, expected):
assert excinfo.value.status_code == 503
assert excinfo.value.headers == {"Retry-After": "5"}
assert session_dict == expected, (
"a transient sidecar fault cleared a recoverable session"
)
def test_open_failure_answers_503_and_keeps_the_session(self, monkeypatch):
_patch_ctx(
monkeypatch,
_FakeSessionContext(enter_exc=_session_unavailable()),
)
session_dict = {"username": "alice", "session_id": "sid-3"}
request = _request_with_session(session_dict)
with pytest.raises(HTTPException) as excinfo:
next(get_db_session_dep(request, "alice"))
self._assert_retryable_503(
excinfo, session_dict, {"username": "alice", "session_id": "sid-3"}
)
def test_handler_time_failure_answers_503_and_keeps_the_session(
self, monkeypatch
):
ctx = _patch_ctx(monkeypatch, _FakeSessionContext(session=object()))
session_dict = {"username": "alice", "session_id": "sid-4"}
request = _request_with_session(session_dict)
gen = get_db_session_dep(request, "alice")
next(gen)
with pytest.raises(HTTPException) as excinfo:
gen.throw(_session_unavailable())
self._assert_retryable_503(
excinfo, session_dict, {"username": "alice", "session_id": "sid-4"}
)
assert ctx.exited