~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
"""Contracts for the v1.10.7 rollback guidance after the FastAPI release.
Three facts about the rollback are easy to lose in an edit, and each one
costs operators data when it is wrong:
1. v1.10.7 must never be started against the upgraded databases. Its
``encrypted_db`` calls ``needs_migration()``, which is true for any
revision it does not know, and then takes a forced backup with
``BackupService``'s default ``max_backups=1``. Every sign-in attempt
therefore replaces the user's automatic pre-migration backup with a copy
of the upgraded database before the login fails. The guide, the README
and the changelog fragment must all say so, and must tell operators to
copy that backup out of the data directory first.
2. The new release does not keep the pre-migration backup either. The
post-login backup (``auth.py`` -> ``submit_backup`` ->
``create_backup(force=False)``) uses ``backup.max_count``, default 1, so
the user's first sign-in on a later UTC day replaces it with a copy of
the upgraded database, and a password change deletes it
(``purge_and_refresh``). The docs must say to copy it out immediately
after each user's first sign-in, not merely before a downgrade.
3. The release can ship more than one revision after ``0030``, so the docs
must not pin the rollback to one revision number. The guide tells
operators to read the newest revision from ``get_head_revision()`` or
from the highest-numbered migration file; both must agree.
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
GUIDE = REPO_ROOT / "docs" / "deployment" / "upgrading.md"
README = REPO_ROOT / "README.md"
CHANGELOG = REPO_ROOT / "changelog.d" / "3299.breaking.md"
VERSIONS_DIR = (
REPO_ROOT
/ "src"
/ "local_deep_research"
/ "database"
/ "migrations"
/ "versions"
)
ROLLBACK_DOCS = {
"upgrading.md": GUIDE,
"README.md": README,
"3299.breaking.md": CHANGELOG,
}
def _prose(path: Path) -> str:
return re.sub(r"\s+", " ", path.read_text(encoding="utf-8"))
@pytest.mark.parametrize("name", sorted(ROLLBACK_DOCS))
def test_rollback_docs_warn_about_the_pre_migration_backup(name):
if name == "3299.breaking.md" and not CHANGELOG.exists():
pytest.skip("fragment consumed by towncrier at release prep")
text = _prose(ROLLBACK_DOCS[name])
lowered = text.lower()
assert "never start v1.10.7 against the upgraded" in lowered, (
f"{name} must forbid starting v1.10.7 against upgraded data: each "
"sign-in attempt there overwrites the pre-migration backup"
)
assert "before any downgrade attempt" in lowered, name
assert "encrypted_databases/backups/" in text, (
f"{name} must say where the pre-migration backup lives"
)
assert "outside the data directory" in lowered, name
@pytest.mark.parametrize("name", sorted(ROLLBACK_DOCS))
def test_rollback_docs_say_the_new_release_replaces_the_backup(name):
if name == "3299.breaking.md" and not CHANGELOG.exists():
pytest.skip("fragment consumed by towncrier at release prep")
lowered = _prose(ROLLBACK_DOCS[name]).lower()
for phrase in (
"immediately after that user's first sign-in",
"later utc day",
"password change",
):
assert phrase in lowered, (
f"{name} must say that the new release's own daily login backup "
"and password changes replace the pre-migration backup, so it "
f"must be copied out at once; missing {phrase!r}"
)
def test_guide_explains_how_to_keep_the_pre_migration_backup():
text = _prose(GUIDE)
lowered = text.lower()
assert "soon after the upgrade" not in lowered, (
"'soon after the upgrade' is too late: each user's backup is made "
"at their first sign-in and replaced at a later-day sign-in"
)
# _cleanup_old_backups deletes by count (index >= max_backups) as well
# as by age, so a raised max_count is never age-only protection.
assert "does not protect them from a password change" not in text, (
"a raised backup.max_count is not 'safe except for a password "
"change': the Nth later-day login backup evicts it by count"
)
for phrase in (
"Copy the pre-migration backups out immediately",
"restores the upgraded database, not the pre-migration one",
"`backup.max_count`",
"`backup.max_age_days`",
"`LDR_BACKUP_MAX_COUNT`",
"`LDR_BACKUP_MAX_AGE_DAYS`",
"only widens that window",
"the Nth login backup made after it",
"however young the backup is",
"until the user's first sign-in on the `backup.max_count`-th later "
"UTC day on which they sign in",
"only the first sign-in on each later UTC day adds one",
"a password change still deletes it at any time",
"It is not a substitute for copying the backups out",
"Check each file's timestamp first",
):
assert phrase in text, f"upgrading.md lost {phrase!r}"
# create_backup(force=False) skips while a backup dated the current UTC
# day exists, so later sign-ins on the same day add no login backup.
for wrong in (
"each sign-in on a later UTC day still adds",
"Nth sign-in on a later UTC day",
):
assert wrong not in text, (
f"upgrading.md says {wrong!r}: only the first sign-in on each "
"UTC day adds a login backup"
)
def test_guide_says_the_pre_migration_backup_applies_the_users_retention():
"""Writing the pre-migration backup prunes by the user's own settings.
``encrypted_db`` reads ``backup.max_count`` and ``backup.max_age_days``
with ``_read_backup_retention`` before the migration and builds
``BackupService`` with them. If they cannot be read, or are not whole
numbers within the settings' ranges, it writes the backup with
``prune=False``. So the guide must not say that writing it always
removes the user's older automatic backups: with a raised
``backup.max_count`` it keeps those inside the user's limits.
``tests/database/backup/test_premigration_backup_retention.py`` pins
the code side; the ranges below come from the same constants.
"""
from local_deep_research.database import encrypted_db
text = _prose(GUIDE)
stale = "Writing it removes the user's older automatic backups"
assert stale not in text, (
"writing the pre-migration backup prunes by the user's own "
"backup.max_count and backup.max_age_days, not unconditionally"
)
for phrase in (
"Writing it applies the user's `backup.max_count` and "
"`backup.max_age_days` to their older automatic backups",
"with the default `backup.max_count` of `1` it removes all of them",
"if those settings cannot be read before the migration, or are not "
"whole numbers within the settings' ranges "
f"(1 to {encrypted_db._BACKUP_MAX_COUNT_LIMIT} backups, 1 to "
f"{encrypted_db._BACKUP_MAX_AGE_DAYS_LIMIT} days), it removes none",
):
assert phrase in text, f"upgrading.md lost {phrase!r}"
def test_guide_warns_that_a_first_sign_in_past_midnight_loses_the_backup():
"""The pre-migration backup's file name is stamped before its export.
``_create_backup_impl`` takes the timestamp before ``sqlcipher_export``
runs, and the migration plus the login's own backup follow. If the first
sign-in crosses midnight UTC, that login backup finds no file for the
new day and, with ``max_count`` 1, deletes the pre-migration backup
before anyone can copy it.
"""
text = _prose(GUIDE)
for phrase in (
"the first sign-in itself does this if it runs past midnight UTC",
"named for the time its export started",
"the file named in that user's `Pre-migration backup created` log "
"line still exists",
):
assert phrase in text, f"upgrading.md lost {phrase!r}"
def test_guide_says_a_failed_pre_migration_backup_does_not_stop_migration():
"""The pre-migration backup is best-effort, not a precondition.
``encrypted_db`` logs ``Pre-migration backup failed`` when
``create_backup(force=True)`` fails or raises, and then runs
``initialize_database`` anyway. The guide must not promise that the
copy is always written, and must tell operators how to spot a user who
has none.
"""
text = _prose(GUIDE)
assert "it first writes an encrypted copy" not in text, (
"the pre-migration backup can fail and the migration still runs; "
"the guide must not say the copy is always written"
)
for phrase in (
"it first tries to write an encrypted copy",
"A failed pre-migration backup does not stop the migration",
"less than twice the database's size",
"logs a `Pre-migration backup failed` line and migrates the database "
"anyway",
"Treat a user with no `Pre-migration backup created` line for that "
"sign-in as having no pre-migration backup",
"first sign-in logged `Pre-migration backup failed`, or no "
"`Pre-migration backup created` line, has no pre-migration backup to "
"restore from",
):
assert phrase in text, f"upgrading.md lost {phrase!r}"
backup_doc = _prose(REPO_ROOT / "docs" / "security" / "database-backup.md")
assert "a backup is always created regardless" not in backup_doc
assert "the migration runs anyway" in backup_doc
def test_guide_backup_references_do_not_pin_one_backup_doc_layout():
"""Keep the guide valid across backup-format changes.
Backup names may gain a suffix after the timestamp (for example a
unique suffix and a ``.db.salt`` sidecar), and the backup guide's
restore section may be restructured. The rollback guide must describe
the name by its timestamp prefix and link to the backup page itself.
"""
text = _prose(GUIDE)
assert "(`ldr_backup_YYYYMMDD_HHMMSS`)" in text
assert "`ldr_backup_YYYYMMDD_HHMMSS.db`" not in text
assert "database-backup.md#" not in text
def test_pre_migration_backup_fails_when_disk_space_is_short(
tmp_path, monkeypatch
):
"""Pin the failure the guide names: under 2x the database size free."""
import shutil
from collections import namedtuple
from local_deep_research.database.backup.backup_service import (
BackupService,
)
db = tmp_path / "ldr_user_test.db"
db.write_bytes(b"x" * 100)
usage = namedtuple("usage", "total used free")
monkeypatch.setattr(shutil, "disk_usage", lambda *_: usage(1000, 801, 199))
svc = object.__new__(BackupService)
svc.username = "rollback-doc-user"
svc.db_path = db
svc.backup_dir = tmp_path / "backups"
svc.backup_dir.mkdir()
result = svc.create_backup(force=True)
assert not result.success
assert "Insufficient disk space" in (result.error or "")
assert list(svc.backup_dir.iterdir()) == []
def test_guide_says_to_protect_and_destroy_copied_out_backups():
"""Copies taken outside the data directory escape the password-change purge.
``purge_and_refresh`` deletes every backup on a password change because
old-password backups are a risk. Copies the guide tells operators to
take keep opening with the old password, so the guide must say to
protect and destroy them, and must not ask operators to hold users'
passwords.
"""
text = _prose(GUIDE)
for phrase in (
"keeps doing so after the user changes that password",
"cannot reach copies made outside the data directory",
"destroy them once a rollback to v1.10.7 is no longer needed",
"destroy a user's copies at once",
"do not collect users' passwords yourself",
):
assert phrase in text, f"upgrading.md lost {phrase!r}"
assert "Retain the users' database passwords" not in text, (
"LDR does not store user passwords; the guide must not tell "
"operators to collect them"
)
def test_guide_covers_accounts_created_after_the_upgrade():
"""New accounts' databases are created at the head revision.
``create_user_database`` runs ``initialize_database``, so v1.10.7
refuses those databases, and no pre-upgrade copy of them exists.
"""
text = _prose(GUIDE)
assert (
"Accounts created on the new release have no pre-upgrade copy" in text
)
assert "Export anything those users need before rolling back" in text
def test_login_backup_is_skipped_while_a_backup_dated_today_exists(
tmp_path, monkeypatch
):
"""Pin the day gate the guide's counting rests on.
The guide counts login backups per later UTC day, not per sign-in. That
holds only while ``create_backup(force=False)`` skips when a file dated
the current UTC day exists, and runs when the newest file is from an
earlier day (the midnight case). The guide's "replaces it" also needs
that login backup to prune older backups, so the fake records the
``prune`` flag ``create_backup`` passes to ``_create_backup_impl``.
"""
from datetime import UTC, datetime, timedelta
from local_deep_research.database.backup.backup_service import (
BackupResult,
BackupService,
)
calls = []
def fake_impl(self, prune=True):
calls.append((self.username, prune))
return BackupResult(success=True)
from local_deep_research.database.backup import backup_service
# Freeze the clock create_backup reads, so a run crossing midnight UTC
# cannot disagree with the dates written below.
frozen = datetime(2026, 10, 3, 12, 0, tzinfo=UTC)
class _FrozenDatetime(datetime):
@classmethod
def now(cls, tz=None):
return frozen if tz is not None else frozen.replace(tzinfo=None)
monkeypatch.setattr(backup_service, "datetime", _FrozenDatetime)
monkeypatch.setattr(BackupService, "_create_backup_impl", fake_impl)
# This test is about the calendar-day gate, not backup integrity. A later
# backup-service hardening may verify today's file before using it as a gate.
monkeypatch.setattr(BackupService, "_verify_backup", lambda *_: True)
svc = object.__new__(BackupService)
svc.username = "rollback-doc-user"
svc.backup_dir = tmp_path
yesterday = (frozen - timedelta(days=1)).strftime("%Y%m%d")
(tmp_path / f"ldr_backup_{yesterday}_235959.db").write_bytes(b"x")
svc.create_backup(force=False)
assert calls == [("rollback-doc-user", True)], (
"a login backup must run when the newest file is from an earlier "
"UTC day, and must prune older backups (prune=True); otherwise it "
"never replaces the pre-migration backup the guide warns about"
)
today = frozen.strftime("%Y%m%d")
(tmp_path / f"ldr_backup_{today}_000001.db").write_bytes(b"x")
svc.create_backup(force=False)
assert calls == [("rollback-doc-user", True)], (
"a second sign-in on the same UTC day made another login backup; "
"the guide's per-day counting is then wrong"
)
def test_changelog_says_a_raised_max_count_only_delays_eviction():
if not CHANGELOG.exists():
pytest.skip("fragment consumed by towncrier at release prep")
text = _prose(CHANGELOG)
for phrase in (
"only delays the replacement",
"the user's first sign-in on the `backup.max_count`-th later UTC "
"day on which they sign in still deletes it",
"a password change deletes it at any time",
):
assert phrase in text, f"3299.breaking.md lost {phrase!r}"
assert "user's sign-in on the `backup.max_count`-th later UTC day" not in (
text
), "only the first sign-in on each UTC day adds a login backup"
assert "(a password change still deletes it)" not in text, (
"the fragment must not present a raised max_count as protection "
"that only a password change defeats"
)
@pytest.mark.parametrize("name", sorted(ROLLBACK_DOCS))
def test_rollback_docs_do_not_pin_one_new_revision(name):
if name == "3299.breaking.md" and not CHANGELOG.exists():
pytest.skip("fragment consumed by towncrier at release prep")
text = _prose(ROLLBACK_DOCS[name])
pinned = re.findall(
r"(?:includes|ships alongside|stamped|the new) database revision "
r"`?\d{4}`?|identified by '\d{4}'|stamped `\d{4}`",
text,
)
assert not pinned, (
f"{name} names a single post-0030 revision as the release's "
f"revision: {pinned}. The release may ship several; describe them "
"as the revisions newer than 0030."
)
def test_documented_head_lookup_matches_highest_numbered_file():
from local_deep_research.database.alembic_runner import get_head_revision
numbered = sorted(
p.name.split("_", 1)[0]
for p in VERSIONS_DIR.glob("[0-9][0-9][0-9][0-9]_*.py")
)
assert numbered, "no migration files found"
assert get_head_revision() == numbered[-1], (
"the guide says the newest revision is the highest-numbered "
"migration file; that no longer matches get_head_revision()"
)
guide = _prose(GUIDE)
assert "get_head_revision()" in guide
assert "database/migrations/versions/" in guide
def test_raised_max_count_evicts_the_pre_migration_backup_by_count(tmp_path):
"""Pin the code fact the guide's max_count warning rests on.
The guide says a raised ``backup.max_count`` of N still deletes the
pre-migration backup at the user's first sign-in on the Nth later UTC
day on which they sign in, however young
it is. That holds only while ``_cleanup_old_backups`` evicts by count
as well as by age.
"""
import os
import time
from local_deep_research.database.backup.backup_service import (
BackupService,
)
svc = object.__new__(BackupService)
svc.backup_dir = tmp_path
svc.max_backups = 3
svc.max_age_days = 90
now = time.time()
pre_migration = tmp_path / "ldr_backup_20260101_000000.db"
names = [pre_migration.name] + [
f"ldr_backup_2026010{day}_000000.db" for day in (2, 3, 4)
]
for age_hours, name in zip((72, 48, 24, 0), names):
path = tmp_path / name
path.write_bytes(b"x")
os.utime(path, (now - age_hours * 3600, now - age_hours * 3600))
svc._cleanup_old_backups()
assert not pre_migration.exists(), (
"a three-day-old backup survived max_count=3 with max_age_days=90; "
"if cleanup no longer evicts by count, update the guide's warning"
)
assert sorted(p.name for p in tmp_path.iterdir()) == names[1:]