~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
from __future__ import annotations
import errno
import importlib
import importlib.util
import subprocess
import sys
import os
from pathlib import Path
from uuid import UUID
import pytest
from local_deep_research.config.paths import get_user_database_filename
from local_deep_research.database.rekey_epoch import (
read_authorization_epoch,
read_user_authorization_epoch,
)
from local_deep_research.database.rekey_lock import (
RekeyEpochUnreadableError,
RekeyRecoveryRequiredError,
acquire_rekey_lock,
read_rekey_epoch,
)
_EPOCH_ONE = str(UUID(int=1))
_EPOCH_TWO = str(UUID(int=2))
def _write_epoch_state(
db_path: Path,
*,
committed: str | None,
pending: str | None,
) -> None:
if committed is not None:
db_path.with_name(f"{db_path.name}.rekey.epoch").write_text(
committed, encoding="ascii"
)
if pending is not None:
db_path.with_name(f"{db_path.name}.rekey.pending").write_text(
pending, encoding="ascii"
)
def test_stable_committed_epoch_authorizes(tmp_path: Path) -> None:
# Given a stable committed identity
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
# When authorization projects the durable identity
epoch = read_authorization_epoch(db_path)
# Then the committed identity authorizes sessions
assert epoch == _EPOCH_ONE
def test_matching_committed_and_pending_epoch_authorizes(
tmp_path: Path,
) -> None:
# Given verified E2 remains marked pending only for cleanup
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_TWO, pending=_EPOCH_TWO)
# When authorization projects the durable identity
epoch = read_authorization_epoch(db_path)
# Then verified committed E2 authorizes while cache projection stays closed
assert epoch == _EPOCH_TWO
assert read_rekey_epoch(db_path) is None
def test_old_committed_with_candidate_pending_requires_recovery(
tmp_path: Path,
) -> None:
# Given physical-key outcome may disagree with E1+pending-E2 metadata
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=_EPOCH_TWO)
# When authorization projects the ambiguous identity
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
# Then no metadata is repaired or discarded
assert read_rekey_epoch(db_path) is None
def test_missing_committed_epoch_requires_recovery(tmp_path: Path) -> None:
# Given authorization metadata has not been initialized
db_path = tmp_path / "alice.db"
# When authorization projects the missing identity
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
def test_malformed_epoch_requires_recovery_without_repair(
tmp_path: Path,
) -> None:
# Given committed metadata is malformed
db_path = tmp_path / "alice.db"
epoch_path = db_path.with_name(f"{db_path.name}.rekey.epoch")
epoch_path.write_text("not-a-canonical-epoch", encoding="ascii")
# When authorization projects the malformed identity
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
# Then the malformed evidence is preserved for recovery
assert epoch_path.read_text(encoding="ascii") == "not-a-canonical-epoch"
def test_pending_without_committed_epoch_requires_recovery(
tmp_path: Path,
) -> None:
# Given pending metadata contradicts the missing committed identity
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=None, pending=_EPOCH_TWO)
# When authorization projects the contradictory identity
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
def test_unreadable_epoch_requires_recovery(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a stable committed identity whose files cannot be read: the
# epoch reader's own open fails (EIO), so the identity it would
# otherwise authorize is never seen
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
real_open = os.open
def unreadable(path, flags, *args, **kwargs):
if os.fspath(path).endswith((".rekey.epoch", ".rekey.pending")):
raise OSError(errno.EIO, "unreadable")
return real_open(path, flags, *args, **kwargs)
monkeypatch.setattr(os, "open", unreadable)
# When authorization projects the unreadable identity
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
def test_authorization_projection_does_not_acquire_sidecar(
tmp_path: Path,
) -> None:
# Given another operation already holds the stable sidecar
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
# When authorization reads while that sidecar remains held
with acquire_rekey_lock(db_path):
epoch = read_authorization_epoch(db_path)
# Then projection succeeds without lock recursion or contention
assert epoch == _EPOCH_ONE
def test_user_authorization_epoch_resolves_hashed_database_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given Alice's metadata exists beneath the manager's data directory
# (pinned explicitly: another module in this worker may have pinned
# the singleton elsewhere, and the projection resolves through it)
from local_deep_research.database.encrypted_db import db_manager
monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path))
database_dir = tmp_path / "encrypted_databases"
database_dir.mkdir()
monkeypatch.setattr(db_manager, "_data_dir_override", database_dir)
db_path = database_dir / get_user_database_filename("alice")
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
# When authorization resolves Alice through db_manager
epoch = read_user_authorization_epoch("alice")
# Then it projects the identity from Alice's hashed database path
assert epoch == _EPOCH_ONE
def test_projection_cannot_tear_into_the_superseded_epoch(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a rekey in flight: committed E1, pending E2
from local_deep_research.database import rekey_lock as rekey_lock_module
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=_EPOCH_TWO)
real_read = rekey_lock_module._read_epoch_token
writer_ran = False
def read_then_let_the_writer_finish(path: Path, db: Path) -> str | None:
# The lock-free reader is descheduled right after its FIRST file
# read, and the rekey commits E2 and clears pending in between.
nonlocal writer_ran
token = real_read(path, db)
if not writer_ran:
writer_ran = True
monkeypatch.setattr(
rekey_lock_module, "_read_epoch_token", real_read
)
rekey_lock_module.commit_rekey_epoch(db_path, _EPOCH_TWO)
rekey_lock_module.clear_pending_rekey_epoch(db_path, _EPOCH_TWO)
monkeypatch.setattr(
rekey_lock_module,
"_read_epoch_token",
read_then_let_the_writer_finish,
)
return token
monkeypatch.setattr(
rekey_lock_module, "_read_epoch_token", read_then_let_the_writer_finish
)
# When authorization projects across that commit
epoch = read_authorization_epoch(db_path)
# Then it never reports the superseded E1 as a stable identity (reading
# .epoch first saw E1, then no pending file, and authorized E1)
assert writer_ran
assert epoch == _EPOCH_TWO
@pytest.mark.parametrize("error_number", [errno.EMFILE, errno.EIO])
def test_epoch_read_os_error_is_typed_unreadable(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, error_number: int
) -> None:
# An I/O failure on the read is distinguishable (for session
# validation) but still a RekeyRecoveryRequiredError, so every
# existing handler keeps failing closed.
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
real_open = os.open
def failing_open(path, *args, **kwargs):
if Path(path).name.endswith(".rekey.epoch"):
raise OSError(error_number, "injected")
return real_open(path, *args, **kwargs)
monkeypatch.setattr(os, "open", failing_open)
with pytest.raises(RekeyEpochUnreadableError) as raised:
read_authorization_epoch(db_path)
assert isinstance(raised.value, RekeyRecoveryRequiredError)
assert raised.value.errno == error_number
assert read_rekey_epoch(db_path) is None
def test_undecodable_epoch_is_not_typed_unreadable(tmp_path: Path) -> None:
# Content that was read but cannot be decoded is durable state, not a
# transient read fault.
db_path = tmp_path / "user.db"
db_path.with_name(f"{db_path.name}.rekey.epoch").write_bytes(b"\xff\xfe")
with pytest.raises(RekeyRecoveryRequiredError) as raised:
read_authorization_epoch(db_path)
assert not isinstance(raised.value, RekeyEpochUnreadableError)
# --- Windows sharing violations between lock-free readers and writers ----
#
# CPython opens files on Windows without FILE_SHARE_DELETE. Session
# validation reads ``.rekey.epoch``/``.rekey.pending`` WITHOUT the sidecar
# lock on every authenticated request, so a reader can hold the file open
# while ``change_password`` replaces/unlinks it (the writer then fails with
# PermissionError, after the physical rekey), and a reader can open a file
# whose replace/unlink is in flight (the reader gets PermissionError). The
# window is microseconds; both sides retry a PermissionError a bounded
# number of times. A Linux CI runner cannot produce the violation, so it is
# injected at the real call sites.
def _sharing_violations(
monkeypatch: pytest.MonkeyPatch, target, name: str, failures: int
) -> list[object]:
"""Make ``target.name`` raise PermissionError ``failures`` times."""
import local_deep_research.database.rekey_lock as rekey_lock_module
monkeypatch.setattr(
rekey_lock_module, "_SHARING_VIOLATION_DELAY", 0, raising=False
)
real = getattr(target, name)
calls: list[object] = []
def flaky(*args, **kwargs):
calls.append(args[0] if args else None)
if len(calls) <= failures:
raise PermissionError(errno.EACCES, "sharing violation")
return real(*args, **kwargs)
monkeypatch.setattr(target, name, flaky)
return calls
def test_transient_read_sharing_violation_is_retried(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
failures = 2
calls = _sharing_violations(monkeypatch, os, "open", failures)
# pending (missing) read: `failures` violations then FileNotFoundError;
# the epoch read then succeeds on its first attempt.
assert read_authorization_epoch(db_path) == _EPOCH_ONE
assert len(calls) == failures + 2
def test_persistent_read_sharing_violation_fails_closed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
import local_deep_research.database.rekey_lock as rekey_lock_module
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
attempts = rekey_lock_module._SHARING_VIOLATION_ATTEMPTS
calls = _sharing_violations(monkeypatch, os, "open", 10**6)
# Bounded: the reader gives up after `attempts` tries and NEVER yields
# an epoch -- the typed unreadable error makes session validation
# answer 503 for that request (record kept), and cache validation
# treat the epoch as unknown.
with pytest.raises(RekeyEpochUnreadableError) as raised:
read_authorization_epoch(db_path)
assert raised.value.errno == errno.EACCES
assert len(calls) == attempts
assert read_rekey_epoch(db_path) is None
def test_transient_replace_sharing_violation_still_commits(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
import os
import local_deep_research.database.rekey_lock as rekey_lock_module
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
with acquire_rekey_lock(db_path):
pending = rekey_lock_module.begin_rekey_epoch(db_path)
calls = _sharing_violations(monkeypatch, os, "replace", 2)
rekey_lock_module.commit_rekey_epoch(db_path, pending)
assert len(calls) == 3
assert rekey_lock_module.read_rekey_epoch_state(
db_path
).committed_epoch == (pending)
# No temporary token file is left behind by the failed attempts.
assert sorted(p.name for p in tmp_path.iterdir()) == [
"user.db.rekey.epoch",
"user.db.rekey.lock",
"user.db.rekey.pending",
]
def test_transient_unlink_sharing_violation_still_clears_pending(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
import local_deep_research.database.rekey_lock as rekey_lock_module
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
with acquire_rekey_lock(db_path):
pending = rekey_lock_module.begin_rekey_epoch(db_path)
rekey_lock_module.commit_rekey_epoch(db_path, pending)
calls = _sharing_violations(monkeypatch, Path, "unlink", 2)
rekey_lock_module.clear_pending_rekey_epoch(db_path, pending)
assert len(calls) == 3
assert read_authorization_epoch(db_path) == pending
assert not db_path.with_name("user.db.rekey.pending").exists()
def test_transient_unlink_sharing_violation_still_publishes_a_new_epoch(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# publish_new_database_epoch removes a stale pending token left beside
# a just-created database; a reader holding it open on Windows must
# not fail the creation (#7830). Only the pending token's unlink is
# made flaky: the epoch writer's own temp-file cleanup is untouched.
import local_deep_research.database.rekey_lock as rekey_lock_module
monkeypatch.setattr(rekey_lock_module, "_SHARING_VIOLATION_DELAY", 0)
db_path = tmp_path / "user.db"
pending_path = db_path.with_name("user.db.rekey.pending")
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=_EPOCH_TWO)
real_unlink = Path.unlink
pending_calls: list[Path] = []
def flaky_unlink(self: Path, *args, **kwargs):
if self == pending_path:
pending_calls.append(self)
if len(pending_calls) <= 2:
raise PermissionError(errno.EACCES, "sharing violation")
return real_unlink(self, *args, **kwargs)
monkeypatch.setattr(Path, "unlink", flaky_unlink)
with acquire_rekey_lock(db_path):
epoch = rekey_lock_module.publish_new_database_epoch(db_path)
assert len(pending_calls) == 3
assert not pending_path.exists()
assert epoch not in (_EPOCH_ONE, _EPOCH_TWO)
assert read_authorization_epoch(db_path) == epoch
def test_persistent_replace_permission_error_still_propagates(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
import os
import local_deep_research.database.rekey_lock as rekey_lock_module
db_path = tmp_path / "user.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=None)
with acquire_rekey_lock(db_path):
calls = _sharing_violations(monkeypatch, os, "replace", 10**6)
with pytest.raises(PermissionError):
rekey_lock_module.begin_rekey_epoch(db_path)
assert len(calls) == rekey_lock_module._SHARING_VIOLATION_ATTEMPTS
assert not db_path.with_name("user.db.rekey.pending").exists()
def test_authorization_epoch_import_contract() -> None:
name = "local_deep_research.database.authorization_epoch"
assert importlib.util.find_spec(name) is not None
canonical = importlib.import_module(name)
legacy = importlib.import_module("local_deep_research.database.rekey_epoch")
assert canonical.read_authorization_epoch is legacy.read_authorization_epoch
assert (
canonical.read_user_authorization_epoch
is legacy.read_user_authorization_epoch
)
assert canonical.RekeyRecoveryRequiredError is RekeyRecoveryRequiredError
assert legacy.RekeyRecoveryRequiredError is RekeyRecoveryRequiredError
@pytest.fixture(params=["authorization_epoch", "rekey_epoch"], autouse=True)
def projection_import_path(request, monkeypatch):
module = importlib.import_module(
f"local_deep_research.database.{request.param}"
)
monkeypatch.setattr(
sys.modules[__name__],
"read_authorization_epoch",
module.read_authorization_epoch,
)
monkeypatch.setattr(
sys.modules[__name__],
"read_user_authorization_epoch",
module.read_user_authorization_epoch,
)
def test_projection_import_stays_shallow() -> None:
result = subprocess.run(
[
sys.executable,
"-B",
"-c",
"import sys; import local_deep_research.database.authorization_epoch; import local_deep_research.database.rekey_epoch; assert 'local_deep_research.database.encrypted_db' not in sys.modules",
],
capture_output=True,
text=True,
check=False,
)
assert result.returncode == 0, result.stderr
def test_user_projection_uses_pinned_manager_directory(tmp_path, monkeypatch):
from local_deep_research.database.encrypted_db import db_manager
pinned = tmp_path / "pinned"
environment = tmp_path / "environment"
monkeypatch.setenv("LDR_DATA_DIR", str(environment))
monkeypatch.setattr(db_manager, "_data_dir_override", pinned)
db_path = db_manager._get_user_db_path("alice")
assert db_path == pinned / get_user_database_filename("alice")
db_path.parent.mkdir(parents=True, exist_ok=True)
_write_epoch_state(db_path, committed=_EPOCH_TWO, pending=None)
assert read_user_authorization_epoch("alice") == _EPOCH_TWO
def test_pending_first_projection_preserves_metadata(tmp_path, monkeypatch):
db_path = tmp_path / "alice.db"
_write_epoch_state(db_path, committed=_EPOCH_ONE, pending=_EPOCH_TWO)
before = {path.name: path.read_bytes() for path in tmp_path.iterdir()}
real_open = os.open
reads = []
def record_open(path, flags, *args, **kwargs):
if os.fspath(path).endswith((".rekey.pending", ".rekey.epoch")):
reads.append(Path(path).name)
return real_open(path, flags, *args, **kwargs)
monkeypatch.setattr(os, "open", record_open)
with pytest.raises(RekeyRecoveryRequiredError):
read_authorization_epoch(db_path)
assert reads == ["alice.db.rekey.pending", "alice.db.rekey.epoch"]
assert {
path.name: path.read_bytes() for path in tmp_path.iterdir()
} == before