~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 settings manager layer *beneath* the HTTP router:
``ISettingsManager`` and its two production implementations,
``SettingsManager`` (database-backed) and ``InMemorySettingsManager``
(the programmatic API's store), plus the caching that sits under them.
WHY THIS FILE EXISTS
``tests/web/routers/test_settings_persistence_contracts.py`` and
``tests/web/routers/test_settings_lock_enforcement.py`` pin the *router*:
route-level lock guards, coercion at the HTTP boundary, and which routes
call ``invalidate_settings_caches``. ``tests/settings/test_settings_manager
.py`` pins individual manager methods against a mocked session. Neither
asks the three questions this file asks, all of which are about the layer
as a whole rather than one method:
1. IS ANY USER VALUE CACHED, AND IF SO IS THE CACHE INVALIDATED ON WRITE?
``SettingsManager`` deliberately re-queries the database on every
``get_setting`` -- there is no value cache to go stale, and that is a
property worth pinning rather than assuming, because it is the only
reason two managers built for two different users cannot cross-serve.
But the class *does* memoize exactly one thing:
``settings_locked``. Nothing invalidates it -- not ``set_setting``, not
``import_settings``, and not even the public ``clear_cache()``, which
clears the immutable defaults metadata instead. A manager that read the
lock as "off" keeps writing after the lock is turned on underneath it.
``TestTheOnlyMemoizedValueIsTheLockDecision`` pins both halves.
2. DO THE TWO IMPLEMENTATIONS ACTUALLY AGREE? Every test that substitutes
``InMemorySettingsManager`` for ``SettingsManager`` is only worth
something to the extent the two behave alike.
``TestBothImplementationsAnswerTheSameQuestion`` drives them through
ONE parametrised body -- same scenario, same call, results compared to
each other rather than to a hand-written expectation -- so a divergence
cannot hide in a test that only ever exercised one of them. Scenarios
known to diverge today are marked ``xfail(strict=True)`` with a reason,
so the day somebody closes one the census fails and has to be updated.
``TestTheAbcDescribesBothImplementations`` does the static half over
every abstract method's signature and every extra public method.
3. DOES ``LDR_*`` WIN CONSISTENTLY IN EVERY ACCESSOR? A setting can be
read four ways (``get_setting``, ``get_bool_setting``,
``get_all_settings``, ``get_settings_snapshot``). An env override that
wins in one and loses in another is an operator-policy hole.
``TestEveryAccessorAgreesOnEnvironmentPrecedence`` runs all four, for
both implementations, across the ui_element types whose coercion
differs.
DELIBERATELY NOT COVERED -- filed upstream, do not duplicate: #5737
(``import_settings``
lock refusal is a silent no-op / ``load_from_defaults_file`` logs a false
success), #5739 (``settings_locked`` fails open, latent
infinite recursion), #5740 (inconsistent lock-vs-env ordering). #5738
(``override_locked`` missing from the ABC and from the in-memory
implementation) is now fixed -- both ``delete_setting`` and
``import_settings`` declare ``override_locked`` on the ABC and accept it
(as a no-op) on ``InMemorySettingsManager``; ``locked_*`` scenarios below
are still about the in-memory implementation having no lock *enforcement*
at all, which is what makes an in-memory-based lock test prove nothing.
The 5-minute TTL cache in ``scheduler/background.py`` already has its
session-lifetime contract pinned by ``tests/web/test_scheduler_job_
contracts.py::test_settings_cache_does_not_outlive_the_session`` and its
router-side invalidation by ``tests/web/routers/test_settings_cache_
invalidation.py``. What neither covers is the scheduler writing a setting
that it itself caches, and never invalidating its own entry --
``TestSchedulerWritesInvalidateTheirOwnCache``.
HOW THESE TESTS DRIVE THE CODE. Real ``SettingsManager`` instances over
real (in-memory-seeded, then file-copied) SQLite databases and real
``InMemorySettingsManager`` instances -- no mocked sessions, so a
"refused" result is read back out of the store rather than inferred from a
call assertion. Environment variables are set with ``monkeypatch`` only.
Every "the write did not happen" claim is paired with a positive control
running the same call without the lock/env var, so an unchanged-shaped
result can never come from a broken call.
"""
import ast
import copy
import functools
import inspect
import shutil
import traceback
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Callable, Dict, Optional
import pytest
from sqlalchemy import create_engine
from sqlalchemy.exc import SQLAlchemyError
from sqlalchemy.orm import Session, sessionmaker
import local_deep_research
from local_deep_research.api.settings_utils import InMemorySettingsManager
from local_deep_research.database.models import Base, Setting
from local_deep_research.settings.base import ISettingsManager
from local_deep_research.settings.manager import SettingsManager
from local_deep_research.settings.exceptions import SettingsValueError
_PKG = Path(local_deep_research.__file__).parent
_BACKGROUND_PY = _PKG / "scheduler" / "background.py"
# Every LDR_* variable this module reads or writes. Cleared before each
# test so a value inherited from the developer's shell cannot silently
# turn a negative assertion into a false pass.
_ENV_VARS_USED = (
"LDR_APP_HOST",
"LDR_APP_THEME",
"LDR_APP_PORT",
"LDR_APP_ENABLE_NOTIFICATIONS",
"LDR_APP_LOCK_SETTINGS",
"LDR_APP_DEBUG",
"LDR_LLM_TEMPERATURE",
"LDR_LLM_GOOGLE_API_KEY",
"LDR_REPORT_EXPORT_FORMATS",
"LDR_TESTING_TEST_MODE",
"LDR_ZZZ_NOT_A_SETTING",
"LDR_BRAND_NEW_KEY",
"LDR_CUSTOM_READ_VALUE",
)
@pytest.fixture(autouse=True)
def _clean_ldr_env(monkeypatch):
"""Remove the LDR_* variables this module manipulates."""
for name in _ENV_VARS_USED:
monkeypatch.delenv(name, raising=False)
# ---------------------------------------------------------------------------
# Manager factories
# ---------------------------------------------------------------------------
#
# Seeding a fresh SettingsManager writes ~1000 default rows and costs most
# of a second. The template database is seeded once per module and copied
# per test, so each test still gets a private, fully isolated store.
@pytest.fixture(scope="module")
def seeded_template(tmp_path_factory) -> Path:
"""A SQLite file with the shipped defaults already imported."""
path = tmp_path_factory.mktemp("settings_contracts") / "template.sqlite"
engine = create_engine(f"sqlite:///{path}")
Base.metadata.create_all(engine)
session = sessionmaker(bind=engine)()
try:
# Construction seeds the defaults when the table is empty.
SettingsManager(db_session=session)
assert session.query(Setting).count() > 0, (
"the template database came out empty -- SettingsManager's "
"auto-seeding did not run, so every test below would be "
"measuring an empty store"
)
finally:
session.close()
engine.dispose()
return path
@pytest.fixture
def make_db_manager(
seeded_template, tmp_path
) -> Callable[..., SettingsManager]:
"""Build an isolated database-backed manager over a copy of the seed."""
made: list[Session] = []
counter = {"n": 0}
def _make(locked: bool = False) -> SettingsManager:
counter["n"] += 1
path = tmp_path / f"user_{counter['n']}.sqlite"
shutil.copyfile(seeded_template, path)
engine = create_engine(f"sqlite:///{path}")
session = sessionmaker(bind=engine)()
made.append(session)
if locked:
# app.lock_settings ships editable=False, so no manager API can
# set it; its own description says it must be changed in the
# database. Written BEFORE the manager is built, because the
# manager memoizes the answer (see the lock-cache tests).
session.query(Setting).filter(
Setting.key == "app.lock_settings"
).update({"value": True})
session.commit()
return SettingsManager(db_session=session)
yield _make
for session in made:
session.close()
def _make_memory_manager(locked: bool = False) -> InMemorySettingsManager:
"""Build an isolated in-memory manager.
The lock is engaged through ``set_setting`` because that is the most
direct means this store offers -- it has no database row to write and
no editable/lock enforcement of its own. That asymmetry is itself one
of the divergences recorded below.
"""
manager = InMemorySettingsManager()
if locked:
manager.set_setting("app.lock_settings", True)
return manager
# ---------------------------------------------------------------------------
class TestTypedReadsAndSnapshots:
@staticmethod
def _manager(storage, make_db_manager):
return (
make_db_manager()
if storage == "database"
else InMemorySettingsManager()
)
@pytest.mark.parametrize("storage", ["database", "memory"])
@pytest.mark.parametrize(
"key,env_name,stored",
[
("app.port", "LDR_APP_PORT", 6123),
("llm.temperature", "LDR_LLM_TEMPERATURE", 0.35),
],
)
def test_invalid_numeric_env_raises_in_every_effective_read(
self, storage, key, env_name, stored, make_db_manager, monkeypatch
):
manager = self._manager(storage, make_db_manager)
assert manager.set_setting(key, stored)
baseline = manager.get_all_settings(include_environment_overrides=False)
monkeypatch.setenv(env_name, "not-a-number")
for read in (
lambda: manager.get_setting(key, default=991),
manager.get_all_settings,
manager.get_settings_snapshot,
lambda: manager.get_setting(key.rsplit(".", 1)[0], default=991),
):
_assert_settings_error(read, key, "not-a-number")
assert manager.get_setting(key, check_env=False) == stored
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_numeric_environment_changes_do_not_replace_the_stored_value(
self, storage, make_db_manager, monkeypatch
):
manager = self._manager(storage, make_db_manager)
key = "llm.temperature"
assert manager.set_setting(key, 0.35)
monkeypatch.setenv("LDR_LLM_TEMPERATURE", "invalid")
_assert_settings_error(manager.get_settings_snapshot, key)
for raw, expected in [("0.5", 0.5), ("", 0.35)]:
monkeypatch.setenv("LDR_LLM_TEMPERATURE", raw)
assert manager.get_setting(key) == expected
assert manager.get_all_settings()[key]["value"] == expected
assert manager.get_settings_snapshot()[key] == expected
assert manager.get_setting(key, check_env=False) == 0.35
monkeypatch.delenv("LDR_LLM_TEMPERATURE")
assert manager.get_settings_snapshot()[key] == 0.35
@pytest.mark.parametrize(
"key,env_name",
[
("app.port", "LDR_APP_PORT"),
("llm.temperature", "LDR_LLM_TEMPERATURE"),
],
)
def test_defaults_only_database_snapshot_rejects_invalid_env(
self, key, env_name, monkeypatch
):
manager = SettingsManager(db_session=None)
baseline = manager.get_all_settings(include_environment_overrides=False)
expected = baseline[key]["value"]
assert isinstance(expected, (int, float))
monkeypatch.setenv(env_name, "not-a-number")
for read in (
lambda: manager.get_setting(key, default=991),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(read, key, "not-a-number")
assert manager.get_setting(key, check_env=False) == expected
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_absent_known_key_uses_default_schema_for_environment_value(
self, storage, make_db_manager, monkeypatch
):
manager = self._manager(storage, make_db_manager)
assert manager.delete_setting("app.port")
monkeypatch.setenv("LDR_APP_PORT", "8123")
assert manager.get_setting("app.port", default=42) == 8123
assert (
manager.get_setting("app.port", default=42, check_env=False) == 42
)
monkeypatch.setenv("LDR_APP_PORT", "invalid")
_assert_settings_error(
lambda: manager.get_setting("app.port", default=42), "app.port"
)
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_unknown_environment_key_is_returned_unconverted(
self, storage, make_db_manager, monkeypatch
):
"""With no declared type there is nothing to validate against.
Both stores return the raw override, as SettingsManager did on
main: untyped keys such as app.api_rate_limit are read on every
/api/v1 request and their consumers parse the string.
"""
manager = self._manager(storage, make_db_manager)
key = "zzz.not_a_setting"
assert manager.get_setting(key, default="fallback") == "fallback"
monkeypatch.setenv("LDR_ZZZ_NOT_A_SETTING", "from-env")
assert manager.get_setting(key, default="fallback") == "from-env"
assert (
manager.get_setting(key, default="fallback", check_env=False)
== "fallback"
)
assert key not in manager.get_all_settings()
monkeypatch.setenv("LDR_ZZZ_NOT_A_SETTING", "")
assert manager.get_setting(key, default="fallback") == "fallback"
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_env_only_keys_keep_registry_typing_and_are_not_store_reads(
self, storage, make_db_manager, monkeypatch
):
manager = self._manager(storage, make_db_manager)
key = "testing.test_mode"
monkeypatch.setenv("LDR_TESTING_TEST_MODE", "true")
assert manager.get_setting(key, default=False) is True
# Disabling environment reads uses the registry's declared default.
assert manager.get_setting(key, default=True, check_env=False) is False
assert manager.get_bool_setting(key) is True
monkeypatch.setenv("LDR_TESTING_TEST_MODE", "false")
assert manager.get_setting(key, default=True) is False
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_null_read_uses_caller_default_without_rewriting_the_snapshot(
self, storage, make_db_manager
):
manager = self._manager(storage, make_db_manager)
key = "llm.google.api_key"
fallback = object()
assert manager.get_setting(key, default=fallback) is fallback
assert manager.get_setting(key) is None
assert manager.get_settings_snapshot()[key] is None
def test_memory_namespace_uses_full_child_keys_for_environment_reads(
self, monkeypatch
):
manager = InMemorySettingsManager()
monkeypatch.setenv("LDR_LLM_GOOGLE_API_KEY", "namespaced-value")
monkeypatch.setenv("LDR_API_KEY", "unrelated-value")
assert manager.get_setting("llm.google") == {
"api_key": "namespaced-value"
}
assert manager.get_setting(
"llm.google", default="missing", check_env=False
) == {"api_key": "missing"}
def test_memory_namespace_ignores_malformed_children_and_nearby_prefixes(
self,
):
manager = InMemorySettingsManager()
for key in (
"read_probe.",
"read_probe..value",
"read_probe. bad",
"read_probe2.value",
):
manager._settings[key] = {"value": "ignored", "ui_element": "text"}
assert (
manager.get_setting(
"read_probe", default="missing", check_env=False
)
== "missing"
)
manager._settings["read_probe.value"] = {
"value": "7",
"ui_element": "number",
}
assert manager.get_setting("read_probe", check_env=False) == {
"value": 7
}
manager._settings["read_probe"] = {
"value": "exact",
"ui_element": "text",
}
assert manager.get_setting("read_probe", check_env=False) == "exact"
def test_memory_operator_path_does_not_become_a_child_namespace(
self, monkeypatch
):
manager = InMemorySettingsManager()
key = "research_library.storage_path"
monkeypatch.delenv("LDR_RESEARCH_LIBRARY_STORAGE_PATH", raising=False)
manager._settings.pop(key, None)
manager._settings[key + ".child"] = {
"value": "child",
"ui_element": "text",
}
assert manager.get_setting(key, default="fallback") == "fallback"
def test_programmatic_snapshot_rejects_invalid_env(self, monkeypatch):
from local_deep_research.api.settings_utils import (
create_settings_snapshot,
extract_setting_value,
)
baseline = create_settings_snapshot()
expected = extract_setting_value(baseline, "llm.temperature")
assert isinstance(expected, (int, float))
monkeypatch.setenv("LDR_LLM_TEMPERATURE", "not-a-number")
_assert_settings_error(create_settings_snapshot, "llm.temperature")
_assert_settings_error(
lambda: create_settings_snapshot(temperature=0.6),
"llm.temperature",
)
assert extract_setting_value(baseline, "llm.temperature") == expected
monkeypatch.delenv("LDR_LLM_TEMPERATURE")
assert (
extract_setting_value(
create_settings_snapshot(temperature=0.6), "llm.temperature"
)
== 0.6
)
def _assert_settings_error(read, key, secret=None):
with pytest.raises(SettingsValueError) as raised:
read()
error = raised.value
assert key in str(error)
assert error.__cause__ is None
assert error.__context__ is None
if secret is not None:
rendered = (
str(error)
+ repr(error)
+ repr(error.args)
+ repr(vars(error))
+ "".join(traceback.format_exception(error))
)
assert secret not in rendered
return error
def _replace_stored(manager, key, **fields):
"""Model legacy stored state without passing through new write validation."""
if isinstance(manager, InMemorySettingsManager):
manager._settings[key].update(copy.deepcopy(fields))
else:
row = manager.db_session.query(Setting).filter(Setting.key == key).one()
for name, value in fields.items():
setattr(row, name, copy.deepcopy(value))
manager.db_session.commit()
class TestInvalidStoredReads:
@pytest.mark.parametrize("storage", ["database", "memory"])
@pytest.mark.parametrize(
"value", ["bad-number", "", [1], {"bad": "number"}]
)
def test_invalid_selected_value_never_uses_default_or_raw_snapshot(
self, storage, value, make_db_manager
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
key = "llm.temperature"
_replace_stored(manager, key, value=value)
baseline = manager.get_all_settings(include_environment_overrides=False)
for read in (
lambda: manager.get_setting(key, default=0.8),
lambda: manager.get_setting("llm", default=0.8),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(read, key)
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_valid_environment_wins_over_invalid_lower_priority_store(
self, storage, make_db_manager, monkeypatch
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
key = "llm.temperature"
_replace_stored(manager, key, value="bad-number")
baseline = manager.get_all_settings(include_environment_overrides=False)
monkeypatch.setenv("LDR_LLM_TEMPERATURE", "0.25")
assert manager.get_setting(key, default=0.8) == 0.25
assert manager.get_all_settings()[key]["value"] == 0.25
assert manager.get_settings_snapshot()[key] == 0.25
_assert_settings_error(
lambda: manager.get_setting(key, check_env=False), key
)
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
@pytest.mark.parametrize("storage", ["database", "memory"])
@pytest.mark.parametrize(
"key,ui_element,value",
[
("llm.temperature", "number", 0),
("app.enable_notifications", "checkbox", False),
("app.host", "text", ""),
("app.host", "json", []),
("app.host", "json", {}),
("app.host", "json", "hello"),
("app.host", "json", ""),
("app.host", "multiselect", []),
],
)
def test_supported_values_are_not_missing(
self, storage, key, ui_element, value, make_db_manager
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
_replace_stored(manager, key, ui_element=ui_element, value=value)
for observed in (
manager.get_setting(key, default="not-missing"),
manager.get_all_settings()[key]["value"],
manager.get_settings_snapshot()[key],
):
assert type(observed) is type(value)
assert observed == value
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_json_environment_requires_encoding_without_changing_stored_json(
self, storage, make_db_manager, monkeypatch
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
key = "app.host"
_replace_stored(manager, key, ui_element="json", value={"stored": 1})
baseline = manager.get_all_settings(include_environment_overrides=False)
bad_json = "{private-json-sentinel-723"
monkeypatch.setenv("LDR_APP_HOST", bad_json)
for read in (
lambda: manager.get_setting(key, default={"fallback": True}),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(read, key, bad_json)
assert manager.get_setting(key, check_env=False) == {"stored": 1}
for encoded, expected in [
('"hello"', "hello"),
('{"valid": 2}', {"valid": 2}),
]:
monkeypatch.setenv("LDR_APP_HOST", encoded)
assert manager.get_setting(key) == expected
assert manager.get_all_settings()[key]["value"] == expected
assert manager.get_settings_snapshot()[key] == expected
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
@pytest.mark.parametrize("storage", ["database", "memory"])
@pytest.mark.parametrize(
"ui_element,stored",
[
("json", "true"),
("json", "42"),
("json", "[1,2]"),
("json", "hello"),
("number", "42"),
("checkbox", "false"),
("multiselect", "a,b"),
],
)
def test_validation_preserves_existing_snapshot_representation(
self, storage, ui_element, stored, make_db_manager
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
key = "app.host"
_replace_stored(manager, key, ui_element=ui_element, value=stored)
original = manager.get_all_settings(
include_environment_overrides=False
)[key]
effective = manager.get_all_settings()[key]
assert effective == original
assert manager.get_settings_snapshot()[key] == stored
assert type(manager.get_settings_snapshot()[key]) is str
@pytest.mark.parametrize("storage", ["database", "memory"])
def test_invalid_lock_allows_raw_export_but_stops_effective_reads(
self, storage, make_db_manager, monkeypatch
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
baseline = manager.get_all_settings(include_environment_overrides=False)
monkeypatch.setenv("LDR_APP_LOCK_SETTINGS", "invalid-lock-marker")
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
for read in (
lambda: manager.get_setting("app.lock_settings", default=False),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(
read, "app.lock_settings", "invalid-lock-marker"
)
@pytest.mark.parametrize("storage", ["database", "memory"])
@pytest.mark.parametrize(
"raw", ["NaN", "Infinity", "-Infinity", '{"nested": NaN}']
)
def test_json_environment_rejects_nonfinite_constants(
self, storage, raw, make_db_manager, monkeypatch
):
manager = TestTypedReadsAndSnapshots._manager(storage, make_db_manager)
key = "app.host"
_replace_stored(manager, key, ui_element="json", value={"stored": 1})
monkeypatch.setenv("LDR_APP_HOST", raw)
for read in (
lambda: manager.get_setting(key, default={"fallback": 2}),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(read, key, raw)
assert manager.get_setting(key, check_env=False) == {"stored": 1}
class TestMemoryInvalidTypeReads:
@pytest.mark.parametrize("ui_element", ["custom_widget", None])
@pytest.mark.parametrize("stored", ["chosen-value", 0, False, None, [], {}])
def test_invalid_schema_is_rejected_before_writing(
self, ui_element, stored
):
manager = InMemorySettingsManager()
key = "custom_read.value"
baseline = manager.get_all_settings(include_environment_overrides=False)
_assert_settings_error(
lambda: manager.create_or_update_setting(
{"key": key, "value": stored, "ui_element": ui_element}
),
key,
)
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
def test_invalid_schema_without_value_is_still_rejected(self):
manager = InMemorySettingsManager()
key = "custom_read.value"
_assert_settings_error(
lambda: manager.create_or_update_setting(
{"key": key, "ui_element": "custom_widget"}
),
key,
)
assert key not in manager.get_all_settings(
include_environment_overrides=False
)
@pytest.mark.parametrize("ui_element", ["custom_widget", None])
@pytest.mark.parametrize("override", [None, "", "environment-value"])
def test_legacy_invalid_schema_fails_all_reads(
self, ui_element, override, monkeypatch
):
manager = InMemorySettingsManager()
key = "custom_read.value"
manager._settings[key] = {
"value": "stored-value",
"ui_element": ui_element,
"editable": True,
}
baseline = manager.get_all_settings(include_environment_overrides=False)
if override is not None:
monkeypatch.setenv("LDR_CUSTOM_READ_VALUE", override)
for read in (
lambda: manager.get_setting(key, default="fallback"),
lambda: manager.get_setting(key, check_env=False),
lambda: manager.get_setting("custom_read", default="fallback"),
manager.get_all_settings,
manager.get_settings_snapshot,
):
_assert_settings_error(read, key)
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
def test_exact_entry_does_not_validate_unused_namespace_children(self):
manager = InMemorySettingsManager()
manager.create_or_update_setting(
{"key": "custom_read", "value": "exact", "ui_element": "text"}
)
manager._settings["custom_read.child"] = {
"value": "bad-number",
"ui_element": "number",
}
assert manager.get_setting("custom_read") == "exact"
@pytest.mark.parametrize(
"encoded,expected", [('"hello"', "hello"), ('""', "")]
)
def test_decoded_json_string_remains_readable_after_write(
self, encoded, expected
):
manager = InMemorySettingsManager()
key = "custom_read.value"
manager.create_or_update_setting(
{"key": key, "value": encoded, "ui_element": "json"}
)
assert manager._settings[key]["value"] == expected
assert manager.get_setting(key) == expected
assert manager.get_all_settings()[key]["value"] == expected
assert manager.get_settings_snapshot()[key] == expected
def test_failed_write_does_not_mutate_stored_value(self, monkeypatch):
manager = InMemorySettingsManager()
baseline = manager.get_all_settings(include_environment_overrides=False)
monkeypatch.setenv("LDR_LLM_TEMPERATURE", "0.25")
_assert_settings_error(
lambda: manager.set_setting("llm.temperature", "bad-number"),
"llm.temperature",
)
assert (
manager.get_all_settings(include_environment_overrides=False)
== baseline
)
# ---------------------------------------------------------------------------
# 1. The one memoized value, and the caches that do not exist
# ---------------------------------------------------------------------------
class TestTheOnlyMemoizedValueIsTheLockDecision:
"""``settings_locked`` is memoized per instance and no write path,
nor ``clear_cache()``, ever invalidates it.
``app.lock_settings`` is a security control: while it is on, the
manager is the last line refusing every write for the routes that
carry no guard of their own (see the router audit). A manager holding
a stale "unlocked" answer keeps writing.
"""
_LOCK_ROW = {
"app.lock_settings": {
"value": True,
"ui_element": "checkbox",
"name": "Lock Settings",
"description": "Locked by this import.",
"category": "app_interface",
"type": "APP",
"editable": False,
"visible": False,
}
}
def _stored(self, manager: SettingsManager, key: str) -> Any:
row = (
manager.db_session.query(Setting).filter(Setting.key == key).first()
)
return None if row is None else row.value
def test_engaging_the_lock_does_not_lock_the_manager_that_wrote_it(
self, make_db_manager
):
manager = make_db_manager()
assert manager.settings_locked is False # memoizes "unlocked"
manager.import_settings(self._LOCK_ROW, commit=True)
assert self._stored(manager, "app.lock_settings") is True, (
"the lock row was not written, so this test is not measuring "
"what it claims to"
)
assert manager.get_setting("app.lock_settings") is True, (
"an uncached read cannot see the lock either -- the defect "
"would be in the read path, not the memoization"
)
assert manager.settings_locked is False, (
"settings_locked stopped being stale; if the memoization now "
"refreshes, delete this test and its siblings"
)
assert manager.set_setting("app.theme", "dark") is True
assert self._stored(manager, "app.theme") == "dark", (
"a manager that engaged the settings lock a moment ago still "
"committed a settings write"
)
def test_a_manager_built_after_the_lock_refuses_the_same_write(
self, make_db_manager
):
"""Positive control for the test above: the refusal machinery
works, so the write that landed there landed because of the
memoized decision and nothing else."""
manager = make_db_manager(locked=True)
assert manager.settings_locked is True
assert manager.set_setting("app.theme", "dark") is False
assert self._stored(manager, "app.theme") != "dark"
def test_clear_cache_does_not_clear_the_lock_decision(
self, make_db_manager
):
"""``clear_cache()`` is the only cache-clearing API on the class.
It drops the immutable defaults metadata and leaves the one
mutable, security-relevant memo in place."""
manager = make_db_manager()
assert manager.settings_locked is False
manager.import_settings(self._LOCK_ROW, commit=True)
manager.clear_cache()
assert "default_settings" not in manager.__dict__, (
"clear_cache() no longer clears the defaults metadata; this "
"test's premise about what it does clear is out of date"
)
assert manager.settings_locked is False, (
"clear_cache() left the stale lock decision in place"
)
assert manager.set_setting("app.theme", "dark") is True, (
"clear_cache() is the documented way to drop cached state and "
"it still does not restore lock enforcement"
)
def test_an_unlock_is_equally_invisible_to_the_manager(
self, make_db_manager
):
"""The staleness cuts both ways: a manager that read the lock as
on keeps refusing after an administrator turns it off, which
locks a user out of their own settings for the manager's
lifetime."""
manager = make_db_manager(locked=True)
assert manager.settings_locked is True
manager.db_session.query(Setting).filter(
Setting.key == "app.lock_settings"
).update({"value": False})
manager.db_session.commit()
assert manager.get_setting("app.lock_settings") is False, (
"the unlock did not reach the database"
)
assert manager.settings_locked is True, (
"the memoized lock decision now refreshes on unlock"
)
assert manager.set_setting("app.theme", "dark") is False
fresh = SettingsManager(db_session=manager.db_session)
assert fresh.set_setting("app.theme", "dark") is True, (
"positive control: a manager built after the unlock must "
"accept the write"
)
@pytest.mark.parametrize("failure", [RuntimeError, SQLAlchemyError])
def test_failed_lock_read_cannot_turn_a_locked_account_writable(
self, make_db_manager, monkeypatch, failure
):
"""A transient read failure must not let a later healthy write through."""
manager = make_db_manager(locked=True)
key = "search.max_results"
before = self._stored(manager, key)
original_check = manager._check_thread_safety
checks = 0
def fail_first_check():
nonlocal checks
checks += 1
if checks == 1:
raise failure("transient lock-read failure")
original_check()
monkeypatch.setattr(manager, "_check_thread_safety", fail_first_check)
assert manager.set_setting(key, 17) is False
assert self._stored(manager, key) == before
assert manager.settings_locked is True
assert checks == 1, "the write reached a second database check"
# The database lock was actually on; the refusal is not due to an
# empty or unreadable fixture.
assert manager.get_setting("app.lock_settings") is True
class TestNoUserValueSurvivesBetweenReadsOrBetweenUsers:
"""The database manager keeps no value cache, which is the only
reason two users' managers cannot cross-serve. Both properties are
asserted with BOTH users' values seeded, so an assertion that a
manager returned "the right value" has a wrong value available to
return instead."""
KEY = "app.host"
def test_two_managers_never_serve_each_others_values(self, make_db_manager):
alice = make_db_manager()
bob = make_db_manager()
assert alice.set_setting(self.KEY, "alice.internal") is True
assert bob.set_setting(self.KEY, "bob.internal") is True
for name, manager, expected in (
("alice", alice, "alice.internal"),
("bob", bob, "bob.internal"),
):
assert manager.get_setting(self.KEY) == expected, (
f"{name}'s get_setting returned another user's value"
)
assert manager.get_all_settings()[self.KEY]["value"] == expected, (
f"{name}'s get_all_settings returned another user's value"
)
assert manager.get_settings_snapshot()[self.KEY] == expected, (
f"{name}'s snapshot returned another user's value"
)
def test_a_write_by_one_manager_is_invisible_to_the_other(
self, make_db_manager
):
alice = make_db_manager()
bob = make_db_manager()
alice.set_setting(self.KEY, "alice.internal")
bob.set_setting(self.KEY, "bob.internal")
assert alice.set_setting(self.KEY, "alice.rotated") is True
assert alice.get_setting(self.KEY) == "alice.rotated", (
"a manager's own write was not visible to its next read -- "
"there is a value cache and it is not invalidated on write"
)
assert bob.get_setting(self.KEY) == "bob.internal", (
"one user's write changed what another user's manager reads"
)
def test_the_defaults_metadata_memo_is_per_instance(self, make_db_manager):
"""``default_settings`` is the manager's other cache. It holds
immutable shipped metadata, but it is a ``functools.cached_property``
living in ``self.__dict__`` -- proving it is not shared is what
rules out one instance's metadata reaching another user's."""
alice = make_db_manager()
bob = make_db_manager()
assert alice.default_settings is not bob.default_settings
alice.default_settings["app.host"]["value"] = "poisoned"
assert bob.default_settings["app.host"]["value"] != "poisoned", (
"the defaults metadata memo is shared between manager instances"
)
def test_a_deleted_row_is_gone_on_the_very_next_read(self, make_db_manager):
alice = make_db_manager()
bob = make_db_manager()
alice.set_setting(self.KEY, "alice.internal")
bob.set_setting(self.KEY, "bob.internal")
assert alice.delete_setting(self.KEY) is True
assert alice.get_setting(self.KEY, default="ABSENT") == "ABSENT", (
"a deleted setting was still served from a cache"
)
assert bob.get_setting(self.KEY) == "bob.internal", (
"positive control: the other user's row must survive"
)
# ---------------------------------------------------------------------------
# 2. The two implementations, driven through one body
# ---------------------------------------------------------------------------
def _canonical(value: Any) -> Any:
"""Reduce a result to something comparable across implementations.
A created/updated setting comes back as a ``Setting`` ORM row from one
implementation and as a plain dict from the other. Reducing both to
``("row", key, value)`` keeps *that* difference from masking the
substantive question a scenario asks (did the write happen, with what
value); the shape difference itself is asserted by its own scenario.
"""
if isinstance(value, Setting):
return ("row", str(value.key), value.value)
if isinstance(value, dict) and "key" in value and "value" in value:
return ("row", str(value["key"]), value["value"])
if isinstance(value, dict):
return ("mapping", sorted(value))
return value
def _observe(action: Callable[[Any], Any], manager: Any) -> Any:
"""Run *action* and reduce its outcome -- return or raise -- to a
comparable token, so "one raises, the other returns" is a visible
divergence rather than an error in one leg of the test."""
try:
result = action(manager)
except Exception as exc: # noqa: BLE001 - the exception IS the result
return ("raised", type(exc).__name__)
return ("returned", _canonical(result))
_FULL_SETTING = {
"ui_element": "text",
"name": "Contract Probe",
"description": "Written by the manager contract census.",
"category": "app_interface",
}
def _setting_payload(key: str, value: Any, **overrides: Any) -> Dict[str, Any]:
payload = dict(_FULL_SETTING)
payload.update({"key": key, "value": value})
payload.update(overrides)
return payload
@dataclass(frozen=True)
class Scenario:
"""One question asked identically of both implementations."""
name: str
action: Callable[[Any], Any]
env: Dict[str, str] = field(default_factory=dict)
locked: bool = False
diverges: Optional[str] = None
def _read_after_write(key: str, value: Any, default: Any = None):
def action(manager):
accepted = manager.set_setting(key, value)
return (accepted, manager.get_setting(key, default=default))
return action
SCENARIOS: tuple[Scenario, ...] = (
# ---- agreeing: the positive controls for the census harness -------
Scenario(
"plain_write_then_read",
_read_after_write("app.host", "10.0.0.9"),
),
Scenario(
"env_var_beats_the_stored_value",
lambda m: m.get_setting("app.host"),
env={"LDR_APP_HOST": "operator.example"},
),
Scenario(
"check_env_false_reads_the_store",
lambda m: m.get_setting("app.host", check_env=False),
env={"LDR_APP_HOST": "operator.example"},
),
Scenario(
"snapshot_carries_the_env_value",
lambda m: m.get_settings_snapshot()["app.host"],
env={"LDR_APP_HOST": "operator.example"},
),
Scenario(
"env_override_marks_the_row_non_editable",
lambda m: m.get_all_settings()["app.host"]["editable"],
env={"LDR_APP_HOST": "operator.example"},
),
Scenario(
"bool_accessor_reads_the_env_var",
lambda m: m.get_bool_setting("app.enable_notifications"),
env={"LDR_APP_ENABLE_NOTIFICATIONS": "false"},
),
Scenario(
"multiselect_env_var_is_split",
lambda m: m.get_setting("report.export_formats"),
env={"LDR_REPORT_EXPORT_FORMATS": "markdown,ris"},
),
Scenario(
"delete_then_read_falls_back_to_the_default_argument",
lambda m: (
m.delete_setting("app.host"),
m.get_setting("app.host", default="ABSENT"),
),
),
Scenario(
"malformed_key_is_refused_by_set_setting",
lambda m: m.set_setting("foo.", "x"),
),
# ---- diverging: the census proper ---------------------------------
Scenario(
"namespace_read_returns_a_mapping",
lambda m: m.get_setting("llm.google"),
),
Scenario(
"env_var_for_a_key_absent_from_the_store",
lambda m: m.get_setting("zzz.not_a_setting", default="DEFAULT"),
env={"LDR_ZZZ_NOT_A_SETTING": "from-env"},
),
Scenario(
"env_only_setting",
lambda m: m.get_setting("testing.test_mode", default="DEFAULT"),
env={"LDR_TESTING_TEST_MODE": "true"},
),
Scenario(
"stored_null_falls_back_to_the_default_argument",
lambda m: m.get_setting("llm.google.api_key", default="FALLBACK"),
),
Scenario(
"unparseable_env_value_on_a_numeric_setting",
lambda m: m.get_setting("llm.temperature", default=0.7),
env={"LDR_LLM_TEMPERATURE": "not-a-number"},
),
Scenario(
"write_to_an_environment_locked_key",
_read_after_write("app.host", "attacker.example"),
env={"LDR_APP_HOST": "operator.example"},
diverges=(
"SettingsManager refuses the write (operator policy); "
"InMemorySettingsManager accepts it and stores the new value."
),
),
Scenario(
"write_to_a_non_editable_row",
_read_after_write("app.debug", True),
diverges=(
"SettingsManager honours the row's editable flag; "
"InMemorySettingsManager ignores it."
),
),
Scenario(
"write_to_a_key_the_store_does_not_have",
_read_after_write("brand.new_key", "v"),
diverges=(
"SettingsManager mints a new row and returns True; "
"InMemorySettingsManager returns False and stores nothing, so "
"the same call is a create in one store and a no-op in the "
"other."
),
),
Scenario(
"create_or_update_returns",
lambda m: (
type(
m.create_or_update_setting(_setting_payload("app.host", "h"))
).__name__
),
diverges=(
"SettingsManager returns a Setting ORM row, "
"InMemorySettingsManager returns the dict it was handed. The "
"ABC promises 'the created or updated Setting model'."
),
),
Scenario(
"create_or_update_with_an_incomplete_dict",
lambda m: m.create_or_update_setting({"key": "app.host", "value": "h"}),
diverges=(
"SettingsManager raises pydantic ValidationError for a dict "
"missing name/description; InMemorySettingsManager stores it. "
"A caller that works against the API store crashes the web "
"one."
),
),
Scenario(
"create_or_update_with_a_malformed_key",
lambda m: m.create_or_update_setting(_setting_payload("bar.", "y")),
diverges=(
"SettingsManager refuses to mint a trailing-dot key (#4840); "
"InMemorySettingsManager creates it."
),
),
Scenario(
"locked_store_refuses_set_setting",
_read_after_write("app.theme", "dark"),
locked=True,
diverges=(
"app.lock_settings has no effect on "
"InMemorySettingsManager -- it carries no lock enforcement at "
"all, so a lock test written against it proves nothing about "
"production. (Related to but distinct from #5738, which was "
"about the override_locked parameter missing from the ABC; "
"set_setting never declared that parameter at all.)"
),
),
Scenario(
"locked_store_refuses_delete_setting",
lambda m: m.delete_setting("app.host"),
locked=True,
diverges="InMemorySettingsManager has no lock enforcement.",
),
Scenario(
"locked_store_refuses_create_or_update",
lambda m: m.create_or_update_setting(_setting_payload("app.host", "h")),
locked=True,
diverges="InMemorySettingsManager has no lock enforcement.",
),
Scenario(
"locked_store_refuses_import_settings",
lambda m: (
m.import_settings(
{
"app.host": _setting_payload(
"app.host", "imported.example", type="APP"
)
}
),
m.get_setting("app.host"),
),
locked=True,
diverges="InMemorySettingsManager has no lock enforcement.",
),
Scenario(
"locked_store_reports_rows_as_non_editable",
lambda m: m.get_all_settings()["app.host"]["editable"],
locked=True,
diverges=(
"SettingsManager forces editable=False on every row while "
"locked, so a UI reading the in-memory store would render an "
"editable form for a locked configuration."
),
),
)
def _scenario_params():
for scenario in SCENARIOS:
marks = ()
if scenario.diverges:
marks = (pytest.mark.xfail(strict=True, reason=scenario.diverges),)
yield pytest.param(scenario, marks=marks, id=scenario.name)
class TestBothImplementationsAnswerTheSameQuestion:
"""One body, both implementations, results compared to each other.
Nothing here asserts against a hand-written expectation of what a
manager *should* return -- the assertion is that the two production
implementations of the same interface agree. A scenario marked
``xfail(strict=True)`` is a recorded divergence: if it starts passing,
the census fails and the reason string has to be retired.
"""
def test_the_two_stores_agree(self, scenario, make_db_manager, monkeypatch):
for name, value in scenario.env.items():
monkeypatch.setenv(name, value)
database = _observe(
scenario.action, make_db_manager(locked=scenario.locked)
)
in_memory = _observe(
scenario.action, _make_memory_manager(locked=scenario.locked)
)
assert database == in_memory, (
f"{scenario.name}: SettingsManager answered {database!r} and "
f"InMemorySettingsManager answered {in_memory!r}. Every test "
"that substitutes one for the other is only meaningful where "
"they agree."
)
def test_the_census_covers_both_outcomes(self):
"""A census made only of known failures would pass vacuously with
a broken harness."""
agreeing = [s for s in SCENARIOS if not s.diverges]
diverging = [s for s in SCENARIOS if s.diverges]
assert len(agreeing) >= 5, (
"too few agreeing scenarios to show the comparison harness "
"can produce a pass"
)
assert diverging, "the divergence census is empty"
assert all(len(s.diverges) > 40 for s in diverging), (
"every recorded divergence needs a reason a reader can act on"
)
def pytest_generate_tests(metafunc):
if "scenario" in metafunc.fixturenames:
metafunc.parametrize("scenario", list(_scenario_params()))
# ---------------------------------------------------------------------------
# 3. Static conformance: the ABC against both implementations
# ---------------------------------------------------------------------------
# Parameters each implementation accepts BEYOND what ISettingsManager
# declares. Every entry is a place where code written against the ABC
# cannot reach a behaviour production depends on. #5738 -- the two
# SettingsManager entries this inventory used to carry -- is fixed:
# override_locked is now declared on the ABC itself, so it is no longer
# an "extra" parameter for either implementation. The inventory stays
# empty (not deleted) so the NEXT undeclared parameter fails this test
# instead of shipping unnoticed.
_KNOWN_EXTRA_PARAMETERS = {}
# Public methods reachable on the database manager that the ABC does not
# declare and the in-memory manager does not provide. Substituting the
# in-memory manager turns each of these into an AttributeError.
_KNOWN_DB_ONLY_MEMBERS = {
"clear_cache",
"close",
"db_version_matches_package",
"default_settings",
"emit_settings_changed_after_commit",
"get_bootstrap_env_vars",
"get_env_var_for_setting",
"get_setting_key_for_env_var",
"is_bootstrap_env_var",
"is_env_only_setting",
"settings_locked",
"update_db_version",
}
_ABC_METHODS = tuple(sorted(ISettingsManager.__abstractmethods__))
def _parameters(cls: type, name: str) -> Dict[str, Any]:
signature = inspect.signature(getattr(cls, name))
return {
param_name: param.default
for param_name, param in signature.parameters.items()
if param_name != "self"
}
class TestTheAbcDescribesBothImplementations:
"""The static half of the conformance question. Needs no database and
no app, so it still runs when the rest of the suite cannot."""
def test_the_abc_declares_the_methods_this_file_assumes(self):
assert set(_ABC_METHODS) == {
"create_or_update_setting",
"delete_setting",
"get_all_settings",
"get_bool_setting",
"get_setting",
"get_settings_snapshot",
"import_settings",
"load_from_defaults_file",
"set_setting",
}, (
"ISettingsManager's abstract surface changed; the census "
"below and the scenario list above both need revisiting"
)
@pytest.mark.parametrize("method", _ABC_METHODS)
@pytest.mark.parametrize(
"implementation", (SettingsManager, InMemorySettingsManager)
)
def test_every_abc_parameter_is_accepted_with_its_declared_default(
self, implementation, method
):
declared = _parameters(ISettingsManager, method)
actual = _parameters(implementation, method)
missing = {
name: default
for name, default in declared.items()
if name not in actual
}
assert not missing, (
f"{implementation.__name__}.{method} does not accept "
f"{sorted(missing)}, which ISettingsManager declares -- a "
"caller written against the interface would fail on it"
)
wrong_default = {
name: (declared[name], actual[name])
for name in declared
if name in actual and declared[name] != actual[name]
}
assert not wrong_default, (
f"{implementation.__name__}.{method} changes the default of "
f"{sorted(wrong_default)}: {wrong_default}. The same call "
"means different things depending on which store answers it."
)
@pytest.mark.parametrize("method", _ABC_METHODS)
def test_extra_parameters_match_the_written_inventory(self, method):
declared = set(_parameters(ISettingsManager, method))
found = {}
for implementation in (SettingsManager, InMemorySettingsManager):
extra = set(_parameters(implementation, method)) - declared
extra.discard("kwargs")
if extra:
found[(implementation.__name__, method)] = extra
expected = {
key: value
for key, value in _KNOWN_EXTRA_PARAMETERS.items()
if key[1] == method
}
assert found == expected, (
"an implementation grew or lost a parameter the interface "
f"does not declare. found={found} inventory={expected}. A "
"parameter only one implementation accepts is a behaviour "
"the ABC cannot express and the other store cannot honour."
)
def test_the_two_implementations_expose_the_same_public_surface(self):
def public(cls: type) -> set:
names = set()
for name in dir(cls):
if name.startswith("_"):
continue
static = inspect.getattr_static(cls, name, None)
if isinstance(
static, (property, functools.cached_property)
) or callable(getattr(cls, name, None)):
names.add(name)
return names
db_only = public(SettingsManager) - public(InMemorySettingsManager)
memory_only = public(InMemorySettingsManager) - public(SettingsManager)
assert db_only == _KNOWN_DB_ONLY_MEMBERS, (
"the database manager's extra public surface changed: "
f"{sorted(db_only)}. Anything here raises AttributeError when "
"InMemorySettingsManager is substituted."
)
assert not memory_only, (
"the in-memory manager grew public members the database one "
f"lacks: {sorted(memory_only)}"
)
def test_settings_lock_enforcement_is_absent_from_the_interface(self):
"""The lock is the manager layer's last line of defence for the
router paths that carry no guard, yet neither the ABC nor the
in-memory implementation knows it exists."""
assert not hasattr(InMemorySettingsManager, "settings_locked")
assert not hasattr(ISettingsManager, "settings_locked")
assert hasattr(SettingsManager, "settings_locked"), (
"positive control: the database manager does carry the lock"
)
# ---------------------------------------------------------------------------
# 4. Environment precedence, in every accessor, in both stores
# ---------------------------------------------------------------------------
# key, LDR_ name, env string, coerced value, a distinct stored value.
_ENV_CASES = (
(
"app.host",
"LDR_APP_HOST",
"operator.example",
"operator.example",
"stored.example",
),
("app.port", "LDR_APP_PORT", "9999", 9999, 5000),
("llm.temperature", "LDR_LLM_TEMPERATURE", "0.25", 0.25, 0.9),
(
"app.enable_notifications",
"LDR_APP_ENABLE_NOTIFICATIONS",
"false",
False,
True,
),
(
"report.export_formats",
"LDR_REPORT_EXPORT_FORMATS",
"markdown,ris",
["markdown", "ris"],
["latex"],
),
)
@pytest.mark.parametrize(
"key,env_name,env_value,coerced,stored",
_ENV_CASES,
ids=[case[0] for case in _ENV_CASES],
)
@pytest.mark.parametrize("flavour", ("database", "in_memory"))
class TestEveryAccessorAgreesOnEnvironmentPrecedence:
"""Four accessors, one answer. A setting whose env override wins in
``get_setting`` but loses in ``get_settings_snapshot`` is an operator
policy that a background thread quietly ignores -- snapshots are how
settings reach research threads."""
def _manager(self, flavour, make_db_manager):
if flavour == "database":
return make_db_manager()
return _make_memory_manager()
def test_all_four_accessors_return_the_env_value(
self,
flavour,
make_db_manager,
monkeypatch,
key,
env_name,
env_value,
coerced,
stored,
):
manager = self._manager(flavour, make_db_manager)
# Seed a DIFFERENT stored value first, so "returned the env value"
# has something concrete to fail against.
manager.set_setting(key, stored)
monkeypatch.setenv(env_name, env_value)
assert manager.get_setting(key) == coerced, "get_setting"
assert manager.get_all_settings()[key]["value"] == coerced, (
"get_all_settings"
)
assert manager.get_settings_snapshot()[key] == coerced, (
"get_settings_snapshot"
)
assert manager.get_all_settings()[key]["editable"] is False, (
"an env-pinned row must be reported as non-editable, or the "
"UI invites a write that silently has no effect"
)
if isinstance(coerced, bool):
assert manager.get_bool_setting(key) == coerced
def test_without_the_env_var_all_four_return_the_stored_value(
self,
flavour,
make_db_manager,
monkeypatch,
key,
env_name,
env_value,
coerced,
stored,
):
"""Positive control: the accessors do read the store, so the test
above is measuring precedence rather than a stuck value."""
manager = self._manager(flavour, make_db_manager)
manager.set_setting(key, stored)
assert manager.get_setting(key) == stored
assert manager.get_all_settings()[key]["value"] == stored
assert manager.get_settings_snapshot()[key] == stored
def test_the_documented_opt_outs_reach_the_store(
self,
flavour,
make_db_manager,
monkeypatch,
key,
env_name,
env_value,
coerced,
stored,
):
manager = self._manager(flavour, make_db_manager)
manager.set_setting(key, stored)
monkeypatch.setenv(env_name, env_value)
assert manager.get_setting(key, check_env=False) == stored, (
"check_env=False must bypass the environment -- "
"db_version_matches_package relies on it to avoid masking a "
"stale schema behind LDR_APP_VERSION"
)
assert (
manager.get_all_settings(include_environment_overrides=False)[key][
"value"
]
== stored
)
# ---------------------------------------------------------------------------
# 5. The scheduler writes a setting it caches, and never invalidates it
# ---------------------------------------------------------------------------
# Functions in scheduler/background.py that call set_setting, mapped to
# whether the same function also invalidates the scheduler's own per-user
# TTL cache. The document scheduler caches document_scheduler.last_run
# (DocumentSchedulerSettings.last_run, read back to build the
# "completed_at > last_run" filter) and writes it at the end of every
# run without dropping its cache entry. document_scheduler.interval_seconds
# has min_value 60, well under the cache's 300s TTL, so consecutive ticks
# can and do read a last_run older than the one just committed.
_SCHEDULER_WRITE_SITES = {"_process_user_documents": False}
_INVALIDATION_NAMES = (
"invalidate_user_settings_cache",
"invalidate_all_settings_cache",
"invalidate_settings_caches",
"_settings_cache",
)
def _scan_setting_writers(source: str) -> Dict[str, bool]:
"""Map each function that calls ``.set_setting(...)`` to whether it
also drops the scheduler's cached settings for the same user."""
found: Dict[str, bool] = {}
for node in ast.walk(ast.parse(source)):
if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
continue
writes = any(
isinstance(inner, ast.Call)
and isinstance(inner.func, ast.Attribute)
and inner.func.attr == "set_setting"
for inner in ast.walk(node)
)
if not writes:
continue
body = ast.unparse(node)
found[node.name] = any(name in body for name in _INVALIDATION_NAMES)
return found
class TestSchedulerWritesInvalidateTheirOwnCache:
"""Static census -- no scheduler is instantiated, so this runs with
no APScheduler thread and no singleton left behind for other tests."""
def test_the_write_sites_match_the_written_inventory(self):
found = _scan_setting_writers(
_BACKGROUND_PY.read_text(encoding="utf-8")
)
assert found == _SCHEDULER_WRITE_SITES, (
"scheduler/background.py's settings-write sites changed: "
f"{found} vs inventory {_SCHEDULER_WRITE_SITES}. A function "
"here that writes a setting the scheduler also caches must "
"invalidate its own TTL entry, or the next tick inside the "
"300s window reads the value it just replaced."
)
def test_the_cached_field_and_the_written_key_are_the_same_setting(
self,
):
"""The census above only matters because the key written is one
of the keys cached. Pinning that link stops the inventory from
being quietly correct-but-irrelevant."""
from local_deep_research.scheduler.background import (
DocumentSchedulerSettings,
)
source = _BACKGROUND_PY.read_text(encoding="utf-8")
assert "document_scheduler.last_run" in source
assert "last_run" in DocumentSchedulerSettings.__dataclass_fields__, (
"last_run is no longer a cached field; the staleness this "
"census records may no longer exist"
)
def test_the_scanner_tells_a_guarded_writer_from_an_unguarded_one(
self,
):
"""Negative control for the scanner: without it, a scanner that
never finds an invalidation would report the same inventory for
code that is perfectly correct."""
unguarded = (
"class S:\n"
" def write(self, u):\n"
" self.sm.set_setting('a.b', 1)\n"
)
guarded = (
"class S:\n"
" def write(self, u):\n"
" self.sm.set_setting('a.b', 1)\n"
" self.invalidate_user_settings_cache(u)\n"
)
assert _scan_setting_writers(unguarded) == {"write": False}
assert _scan_setting_writers(guarded) == {"write": True}
assert _scan_setting_writers("def f():\n pass\n") == {}