From 96e1dfe395a440f9e2dddf4589c4f6988f4ee4cd Mon Sep 17 00:00:00 2001 From: Rod Boev Date: Wed, 1 Jul 2026 21:25:14 -0400 Subject: [PATCH] fix(ccr): honor workspace dir for sqlite store (#1564) ## Description CCR's default SQLite backend ignores `HEADROOM_WORKSPACE_DIR`. When users relocate Headroom's read-write state with the canonical workspace env var, the CCR store still wrote `ccr_store.db` under `~/.headroom` unless they also set `HEADROOM_CCR_SQLITE_PATH`. This change keeps `HEADROOM_CCR_SQLITE_PATH` as the strongest per-store override, then resolves the default SQLite database as `workspace_dir() / "ccr_store.db"` from `headroom.paths.workspace_dir()`. With no env vars set, `workspace_dir()` still falls back to `~/.headroom`, so the effective default remains unchanged. The default backend stays SQLite, preserving restart survival and multi-worker sharing. Closes #1558 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Route `headroom.cache.backends.sqlite.default_db_path()` through `headroom.paths.workspace_dir()` when `HEADROOM_CCR_SQLITE_PATH` is unset. - Preserve `HEADROOM_CCR_SQLITE_PATH` as the strongest override. - Keep the no-env effective fallback at `~/.headroom/ccr_store.db` through `workspace_dir()` resolution. - Update default-path wording in SQLite/compression-store/backends docs to remove unconditional fallback claims. - Add focused regression and preservation tests in `tests/test_ccr_sqlite_backend.py` for: - workspace override when `HEADROOM_WORKSPACE_DIR` is set and `HEADROOM_CCR_SQLITE_PATH` is unset. - env path override still winning. - no-env fallback to `~/.headroom`. - explicit `SQLiteBackend(db_path=...)` authority. - existing restart and two-connection behavior. ## Testing - [x] Unit tests pass (`uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir or sqlite_path_env_wins or home_fallback or explicit_db_path or default_backend_is_sqlite or survives_reopen or two_connections_share_data" -v`) - [x] Linting passes (`uv run ruff check headroom/cache/backends/sqlite.py headroom/cache/compression_store.py headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py`) - [ ] Type checking not run (`uv run mypy headroom`) - [x] New tests added for new functionality when applicable - [x] Manual testing performed ### Test Output ```text Base proof before the production fix: uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir" -v FAILED tests/test_ccr_sqlite_backend.py::TestDefaults::test_workspace_dir - AssertionError: assert 'C:\Users\Rod\AppData\Local\Temp\pytest-of-Rod\pytest-484\test_workspace_dir0\fake_home\.headroom\ccr_store.db' == 'C:\Users\Rod\AppData\Local\Temp\pytest-of-Rod\pytest-484\test_workspace_dir0\workspace\ccr_store.db' 1 failed, 20 deselected Focused validation after the fix: uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir or sqlite_path_env_wins or home_fallback or explicit_db_path or default_backend_is_sqlite or survives_reopen or two_connections_share_data" -v 7 passed, 14 deselected, 1 warning in 0.20s uv run ruff check headroom/cache/backends/sqlite.py headroom/cache/compression_store.py headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py All checks passed! ``` ## Real Behavior Proof - Environment: local pytest filesystem-path regression tests with temporary home and workspace directories. - Exact command / steps: run `uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir" -v` on base with the new regression test present, then run `uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir or sqlite_path_env_wins or home_fallback or explicit_db_path or default_backend_is_sqlite or survives_reopen or two_connections_share_data" -v` and `uv run ruff check headroom/cache/backends/sqlite.py headroom/cache/compression_store.py headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py` on the patched branch. - Observed result: the base proof fails because the default backend path resolves to `fake_home\\.headroom\\ccr_store.db` instead of `workspace\\ccr_store.db`; after the fix, the focused pytest selection passes, `HEADROOM_CCR_SQLITE_PATH` still wins, the no-env fallback still resolves through `~/.headroom`, explicit `db_path` remains authoritative, and `ruff check` passes. - Not tested: live proxy traffic with real CCR compression/retrieve requests, because the changed surface is the deterministic default path resolver and default backend construction. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Additional Notes `CHANGELOG.md` should remain unchanged because the repo's release automation derives changelog entries from conventional commits. --- headroom/cache/backends/__init__.py | 2 +- headroom/cache/backends/sqlite.py | 8 +++-- headroom/cache/compression_store.py | 6 ++-- tests/test_ccr_sqlite_backend.py | 50 +++++++++++++++++++++++++++++ 4 files changed, 59 insertions(+), 7 deletions(-) diff --git a/headroom/cache/backends/__init__.py b/headroom/cache/backends/__init__.py index 8dd19ac3d..85adeff08 100644 --- a/headroom/cache/backends/__init__.py +++ b/headroom/cache/backends/__init__.py @@ -13,7 +13,7 @@ Usage: from headroom.cache.backends import SQLiteBackend, CompressionStoreBackend from headroom.cache.compression_store import CompressionStore, get_compression_store - # Env-driven default (SQLite at ~/.headroom/ccr_store.db) + # Env-driven default (SQLite at workspace_dir()/ccr_store.db) store = get_compression_store() # Direct construction defaults to in-memory; pass a backend for persistence diff --git a/headroom/cache/backends/sqlite.py b/headroom/cache/backends/sqlite.py index 641ae369b..35d9cacb5 100644 --- a/headroom/cache/backends/sqlite.py +++ b/headroom/cache/backends/sqlite.py @@ -13,7 +13,7 @@ cannot provide, both load-bearing for the no-accuracy-loss guarantee: Set ``HEADROOM_CCR_BACKEND=memory`` to opt back into the in-memory backend, or ``HEADROOM_CCR_SQLITE_PATH`` to relocate the database file -(default ``~/.headroom/ccr_store.db``). +(default ``workspace_dir()/ccr_store.db``). """ from __future__ import annotations @@ -49,11 +49,13 @@ _PURGE_INTERVAL = 60.0 def default_db_path() -> Path: - """Resolve the database path (env override or ~/.headroom/).""" + """Resolve the database path (env override, else workspace root).""" env = os.environ.get("HEADROOM_CCR_SQLITE_PATH", "").strip() if env: return Path(env).expanduser() - return Path.home() / ".headroom" / "ccr_store.db" + from ...paths import workspace_dir + + return workspace_dir() / "ccr_store.db" class SQLiteBackend: diff --git a/headroom/cache/compression_store.py b/headroom/cache/compression_store.py index 69f3610cf..84d3e2cf6 100644 --- a/headroom/cache/compression_store.py +++ b/headroom/cache/compression_store.py @@ -946,9 +946,9 @@ def clear_request_compression_store() -> None: def _create_default_ccr_backend() -> CompressionStoreBackend | None: """Create a CCR backend from env (e.g. HEADROOM_CCR_BACKEND=redis). - Default (env unset or "sqlite"): SQLiteBackend at - ~/.headroom/ccr_store.db — restart-safe and shared across worker - processes, which the session-scale 30-minute TTL assumes. + Default (env unset or "sqlite"): SQLiteBackend at workspace_dir()/ccr_store.db + — restart-safe and shared across worker processes, which the + session-scale 30-minute TTL assumes. "memory" opts back into the in-process dict. Other values load adapters via setuptools entry point 'headroom.ccr_backend'. Returns None to use InMemoryBackend. diff --git a/tests/test_ccr_sqlite_backend.py b/tests/test_ccr_sqlite_backend.py index 3c6a88550..fbdd87ef7 100644 --- a/tests/test_ccr_sqlite_backend.py +++ b/tests/test_ccr_sqlite_backend.py @@ -212,6 +212,56 @@ class TestDefaults: assert backend is not None assert backend.get_stats()["backend_type"] == "sqlite" + def test_workspace_dir(self, monkeypatch, tmp_path): + from headroom.cache.compression_store import _create_default_ccr_backend + + workspace = tmp_path / "workspace" + fake_home = tmp_path / "fake_home" + + monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False) + monkeypatch.delenv("HEADROOM_CCR_SQLITE_PATH", raising=False) + monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace)) + monkeypatch.setenv("HOME", str(fake_home)) + monkeypatch.setenv("USERPROFILE", str(fake_home)) + + backend = _create_default_ccr_backend() + assert backend is not None + assert str(backend._path) == str(workspace / "ccr_store.db") + + def test_sqlite_path_env_wins(self, monkeypatch, tmp_path): + from headroom.cache.compression_store import _create_default_ccr_backend + + workspace = tmp_path / "workspace" + sqlite_path = tmp_path / "sqlite_override.db" + + monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False) + monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace)) + monkeypatch.setenv("HEADROOM_CCR_SQLITE_PATH", str(sqlite_path)) + backend = _create_default_ccr_backend() + + assert backend is not None + assert str(backend._path) == str(sqlite_path) + + def test_home_fallback(self, monkeypatch, tmp_path): + from headroom.cache.compression_store import _create_default_ccr_backend + + fake_home = tmp_path / "fake_home" + + monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False) + monkeypatch.delenv("HEADROOM_CCR_SQLITE_PATH", raising=False) + monkeypatch.delenv("HEADROOM_WORKSPACE_DIR", raising=False) + monkeypatch.setenv("HOME", str(fake_home)) + monkeypatch.setenv("USERPROFILE", str(fake_home)) + + backend = _create_default_ccr_backend() + assert backend is not None + assert str(backend._path) == str(fake_home / ".headroom" / "ccr_store.db") + + def test_explicit_db_path(self, tmp_path): + explicit = tmp_path / "explicit.db" + backend = SQLiteBackend(explicit) + assert backend._path == explicit + def test_memory_opt_out(self, monkeypatch): from headroom.cache.compression_store import _create_default_ccr_backend