Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

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.py
index 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 time
from typing import Any
from 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.0
def 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 True
def 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.py
index 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 same
coverage as the index.
"""
+import logging
+
+import pytest
from sqlalchemy import text
from 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" * 200
excerpt = doc_search._excerpt(body, "needle")