Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
fix(doc-search): stop a single failed probe from disabling FTS5 for the process
Pouzor3d679c9a2d68
diff --git a/backend/app/services/doc_search.py b/backend/app/services/doc_search.pyindex 24ec397..ed2698a 100644--- a/backend/app/services/doc_search.py+++ b/backend/app/services/doc_search.py@@ -12,6 +12,7 @@ in sync through `_try_migrate` forever."""import logging+import timefrom typing import Anyfrom sqlalchemy import text@@ -24,25 +25,55 @@ logger = logging.getLogger(__name__)_BODY_COLUMN = 3_available: bool | None = None+_checked_at: float = 0.0++# How long an "unavailable" answer stands before the probe is worth repeating.+# A build without FTS5 never gains it, so the retry is pure waste there and the+# interval keeps that waste to one failed SELECT a minute; a lock that closed the+# index for one request clears in milliseconds, so a minute of LIKE is the cost+# of not hammering a database that is already busy.+_RECHECK_SECONDS = 60.0def reset_availability_cache() -> None:"""Forget the probed FTS5 state. Tests swap databases between cases."""- global _available+ global _available, _checked_at_available = None+ _checked_at = 0.0+++def _mark_unavailable(reason: str) -> None:+ """Record that the index is not usable, logging only on the way down."""+ global _available, _checked_at+ if _available is not False:+ logger.info("FTS5 unavailable — document search falls back to LIKE (%s)", reason)+ _available = False+ _checked_at = time.monotonic()async def fts_available(db: AsyncSession) -> bool:- """Whether this SQLite build has FTS5 and the index table exists."""- global _available- if _available is None:- try:- await db.execute(text("SELECT doc_id FROM documents_fts LIMIT 1"))- _available = True- except OperationalError:- _available = False- logger.info("FTS5 unavailable — document search falls back to LIKE")- return _available+ """Whether this SQLite build has FTS5 and the index table exists.++ The answer is cached, but a negative one only for `_RECHECK_SECONDS`. The+ probe is one statement against a local file, and the errors it can raise are+ not all permanent: `database is locked` while the boot reindex or the scanner+ thread holds a write is transient, and caching it forever cost the process+ every ranked search it would ever run. So a failure is a "not right now",+ re-asked on the first call after the interval; only success is final.+ """+ global _available, _checked_at+ if _available is True:+ return True+ if _available is False and time.monotonic() - _checked_at < _RECHECK_SECONDS:+ return False+ try:+ await db.execute(text("SELECT doc_id FROM documents_fts LIMIT 1"))+ except OperationalError as exc:+ _mark_unavailable(str(exc))+ return False+ _available = True+ _checked_at = time.monotonic()+ return Truedef tags_text(tags: Any) -> str:@@ -56,16 +87,34 @@ async def index_document(db: AsyncSession, doc: Any) -> None:"""Re-index one document. Safe to call when FTS5 is missing."""if not await fts_available(db):return- await unindex_document(db, doc.id)- await db.execute(- text("INSERT INTO documents_fts (doc_id, title, tags, body) VALUES (:i, :t, :g, :b)"),- {"i": doc.id, "t": doc.title or "", "g": tags_text(doc.tags), "b": doc.body or ""},- )+ # A savepoint, so a write against an index that vanished under us rolls back+ # to here instead of poisoning the document write this is part of. Saving a+ # document must not fail because its search index did.+ try:+ async with db.begin_nested():+ await _delete_indexed(db, doc.id)+ await db.execute(+ text(+ "INSERT INTO documents_fts (doc_id, title, tags, body) "+ "VALUES (:i, :t, :g, :b)"+ ),+ {"i": doc.id, "t": doc.title or "", "g": tags_text(doc.tags), "b": doc.body or ""},+ )+ except OperationalError as exc:+ _mark_unavailable(str(exc))async def unindex_document(db: AsyncSession, doc_id: str) -> None:if not await fts_available(db):return+ try:+ async with db.begin_nested():+ await _delete_indexed(db, doc_id)+ except OperationalError as exc:+ _mark_unavailable(str(exc))+++async def _delete_indexed(db: AsyncSession, doc_id: str) -> None:await db.execute(text("DELETE FROM documents_fts WHERE doc_id = :i"), {"i": doc_id})diff --git a/backend/tests/test_doc_search.py b/backend/tests/test_doc_search.pyindex 24006db..eebba62 100644--- a/backend/tests/test_doc_search.py+++ b/backend/tests/test_doc_search.py@@ -5,6 +5,9 @@ the LIKE fallback is a supported path, not a safety net — it gets the samecoverage as the index."""+import logging++import pytestfrom sqlalchemy import textfrom sqlalchemy.ext.asyncio import AsyncSession@@ -161,6 +164,112 @@ async def test_like_fallback_is_case_insensitive(db_session: AsyncSession):assert len(hits) == 1+# ── the availability probe ──────────────────────────────────────────────────++[email protected](autouse=True)+def _forget_probe():+ """Every case in this file decides for itself whether the index exists."""+ doc_search.reset_availability_cache()+ yield+ doc_search.reset_availability_cache()+++async def test_a_failed_probe_is_retried_once_the_interval_passes(db_session: AsyncSession):+ """Regression for #448: a transient failure must not disable FTS5 for good.++ `database is locked` while the boot reindex or the scanner thread holds a+ write used to be cached as "this build has no FTS5", costing the process+ every ranked search it would ever run.+ """+ await _seed(db_session)+ await db_session.execute(text("DROP TABLE documents_fts"))+ doc_search.reset_availability_cache()+ assert await doc_search.fts_available(db_session) is False++ await db_session.execute(text(+ "CREATE VIRTUAL TABLE documents_fts USING fts5(doc_id UNINDEXED, title, tags, body)"+ ))+ doc_search._checked_at -= doc_search._RECHECK_SECONDS++ assert await doc_search.fts_available(db_session) is True+++async def test_a_failed_probe_is_not_repeated_within_the_interval(db_session: AsyncSession):+ """The retry is bounded: a build genuinely without FTS5 must not re-probe+ on every document write for the life of the process."""+ await db_session.execute(text("DROP TABLE documents_fts"))+ doc_search.reset_availability_cache()+ assert await doc_search.fts_available(db_session) is False++ # The index is back, but the negative answer is still fresh, so nothing+ # probes and the caller keeps getting LIKE until the interval is up.+ await db_session.execute(text(+ "CREATE VIRTUAL TABLE documents_fts USING fts5(doc_id UNINDEXED, title, tags, body)"+ ))+ assert await doc_search.fts_available(db_session) is False+++async def test_an_available_index_is_not_re_probed(db_session: AsyncSession):+ """Success is final — the hot path stays one dict lookup."""+ assert await doc_search.fts_available(db_session) is True+ await db_session.execute(text("DROP TABLE documents_fts"))++ assert await doc_search.fts_available(db_session) is True+++async def test_unavailability_is_logged_once_not_on_every_probe(+ db_session: AsyncSession, caplog+):+ """The fallback is a supported mode, not an incident to report per request."""+ await db_session.execute(text("DROP TABLE documents_fts"))+ doc_search.reset_availability_cache()++ with caplog.at_level(logging.INFO, logger="app.services.doc_search"):+ await doc_search.fts_available(db_session)+ doc_search._checked_at -= doc_search._RECHECK_SECONDS+ await doc_search.fts_available(db_session)++ assert sum("FTS5 unavailable" in r.message for r in caplog.records) == 1+++async def test_an_index_that_vanishes_degrades_the_write_instead_of_failing_it(+ db_session: AsyncSession,+):+ """Regression for #448, the other direction.++ A cached "available" plus an index dropped underneath used to raise straight+ out of `index_document` and 500 the document save. The index is best-effort:+ the document write survives it, and search drops to LIKE.+ """+ await _seed(db_session)+ assert await doc_search.fts_available(db_session) is True+ await db_session.execute(text("DROP TABLE documents_fts"))++ doc = _doc(title="Switch", slug="switch", body="A stack of two.")+ db_session.add(doc)+ await db_session.flush()+ await doc_search.index_document(db_session, doc)++ assert doc_search._available is False+ # The savepoint rolled back the index write alone — the document is intact.+ await db_session.flush()+ stored = (await db_session.execute(+ text("SELECT title FROM documents WHERE slug = 'switch'")+ )).scalar_one()+ assert stored == "Switch"+++async def test_unindexing_against_a_vanished_index_does_not_raise(db_session: AsyncSession):+ docs = await _seed(db_session)+ assert await doc_search.fts_available(db_session) is True+ await db_session.execute(text("DROP TABLE documents_fts"))++ await doc_search.unindex_document(db_session, docs[0].id)++ assert doc_search._available is False++def test_excerpt_centres_on_the_match():body = "x" * 200 + "needle" + "y" * 200excerpt = doc_search._excerpt(body, "needle")