Serialize index access between the watcher and request threads

The watcher thread crashed in production with "database is locked", and
under load the damage is worse than a stalled rescan:

    sqlite3.InterfaceError: bad parameter or other API misuse
    TypeError: 'NoneType' object is not subscriptable

Radicale serializes its request threads with Storage.acquire_lock, but the
watcher calls index.rescan() outside it. Both share one sqlite3 connection,
and rescan is a multi-statement read-modify-write — bump the generation,
reparse, reconcile identities, prune, commit. Interleaving two of those
corrupts the reconcile pass and misuses the connection.

Give Index an RLock and take it in every public method. Writer holds it
across validate → write → reindex, since a rescan landing between _load
and the splice would invalidate the byte spans about to be written.

Two supporting fixes:

  - _rebuild_memory assigned an empty dict before refilling it, so a reader
    could observe a half-populated task list. Build, then swap.
  - Open the database in WAL with a 30s busy_timeout, so `mdcaldav doctor`
    run against a live server waits instead of failing.

This is also a second, independent cause of the ETag churn fixed in
2552545: a corrupted reconcile pass reassigns last_modified on tasks that
never changed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/mdcaldav/index.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import hashlib
 import json
 import sqlite3
+import threading
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -74,10 +75,21 @@ class Index:
         self.tasks: dict[str, Task] = {}  # uid → current task (in-memory truth)
         self._parsed: dict[str, list[Task]] = {}  # rel_path → tasks
 
+        # Every public method takes this. A rescan is a multi-statement
+        # read-modify-write over a connection shared by Radicale's request
+        # threads and the watcher thread; interleaving them corrupts the
+        # reconcile pass and raises sqlite3 API-misuse errors.
+        self.lock = threading.RLock()
+
         db_path = Path(cfg.index.db).expanduser()
         db_path.parent.mkdir(parents=True, exist_ok=True)
-        self.db = sqlite3.connect(db_path, check_same_thread=False)
+        self.db = sqlite3.connect(db_path, check_same_thread=False, timeout=30.0)
         self.db.row_factory = sqlite3.Row
+        # WAL keeps a second process (`mdcaldav doctor` against a running
+        # server) reading while we write; busy_timeout makes it wait rather
+        # than fail with "database is locked".
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA busy_timeout=30000")
         self.db.executescript(SCHEMA)
         if self.db.execute("SELECT COUNT(*) FROM meta").fetchone()[0] == 0:
             self.db.execute(
@@ -102,6 +114,7 @@ class Index:
 
     @property
     def generation(self) -> int:
+        with self.lock:
             return self.db.execute("SELECT generation FROM meta").fetchone()[0]
 
     def _bump(self) -> int:
@@ -131,6 +144,7 @@ class Index:
 
     def rescan(self, only: list[str] | None = None) -> int:
         """Reparse the vault (or `only` these files) and reconcile identities."""
+        with self.lock:
             gen = self._bump()
             targets = (
                 [rel for rel in only if self.included(rel)]
@@ -171,6 +185,7 @@ class Index:
         Called on every read path so an edit made in vim is visible even when no
         watcher is running; the watcher (SPEC 8) only improves latency.
         """
+        with self.lock:
             known = {
                 row["rel_path"]: (row["mtime"], row["size"])
                 for row in self.db.execute("SELECT rel_path, mtime, size FROM files")
@@ -190,14 +205,24 @@ class Index:
             self.rescan(stale)
             return True
 
+    def file_hash_of(self, rel: str) -> str | None:
+        """The hash the index last recorded for a file, or None if unknown."""
+        with self.lock:
+            row = self.db.execute(
+                "SELECT hash FROM files WHERE rel_path = ?", (rel,)
+            ).fetchone()
+            return row["hash"] if row else None
+
     def reassign_uid(self, old_uid: str, new_uid: str) -> None:
         """Adopt a client-chosen UID for a task we just created."""
         if old_uid == new_uid:
             return
+        with self.lock:
             self.db.execute("DELETE FROM tasks WHERE uid = ?", (new_uid,))
             self.db.execute("UPDATE tasks SET uid = ? WHERE uid = ?", (new_uid, old_uid))
             self.db.execute(
-            "UPDATE tasks SET parent_uid = ? WHERE parent_uid = ?", (new_uid, old_uid)
+                "UPDATE tasks SET parent_uid = ? WHERE parent_uid = ?",
+                (new_uid, old_uid),
             )
             self.db.commit()
             for tasks in self._parsed.values():
@@ -206,7 +231,9 @@ class Index:
                         task.uid = new_uid
                     if task.parent_uid == old_uid:
                         task.parent_uid = new_uid
-                task.children = [new_uid if c == old_uid else c for c in task.children]
+                    task.children = [
+                        new_uid if c == old_uid else c for c in task.children
+                    ]
             self._rebuild_memory()
 
     def _retire_file(self, rel: str, gen: int) -> None:
@@ -402,12 +429,16 @@ class Index:
     # ---- serving ---------------------------------------------------------
 
     def _rebuild_memory(self) -> None:
-        self.tasks = {}
+        # Build then swap: assigning an empty dict first would let a reader
-        for tasks in self._parsed.values():
+        # holding no lock observe a half-populated task list.
-            for task in tasks:
+        tasks: dict[str, Task] = {}
-                self.tasks[task.uid] = task
+        for parsed in self._parsed.values():
+            for task in parsed:
+                tasks[task.uid] = task
+        self.tasks = tasks
 
     def completed_at(self, uid: str) -> datetime | None:
+        with self.lock:
             row = self.db.execute(
                 "SELECT completed_at FROM tasks WHERE uid = ?", (uid,)
             ).fetchone()
@@ -417,6 +448,7 @@ class Index:
 
     def last_modified(self, uid: str) -> datetime:
         """When this task last actually changed — the basis of its ETag."""
+        with self.lock:
             row = self.db.execute(
                 "SELECT last_modified FROM tasks WHERE uid = ?", (uid,)
             ).fetchone()
@@ -431,12 +463,14 @@ class Index:
         if collection is not None:
             sql += " AND collection = ?"
             params = (collection,)
+        with self.lock:
             row = self.db.execute(sql, params).fetchone()
         if row and row["m"]:
             return datetime.fromisoformat(row["m"])
         return datetime.now(timezone.utc)
 
     def collections(self) -> list[str]:
+        with self.lock:
             rows = self.db.execute(
                 "SELECT DISTINCT collection FROM tasks WHERE deleted_gen IS NULL"
             ).fetchall()
@@ -446,6 +480,7 @@ class Index:
         return [t for t in self.tasks.values() if t.collection == collection]
 
     def rel_path_of(self, uid: str) -> str | None:
+        with self.lock:
             row = self.db.execute(
                 "SELECT rel_path FROM tasks WHERE uid = ?", (uid,)
             ).fetchone()
@@ -453,6 +488,7 @@ class Index:
 
     def sync(self, collection: str, old_token: str = "") -> tuple[str, list[str]]:
         """Radicale sync-token contract (SPEC 8.1)."""
+        with self.lock:
             gen = self.generation
             token = f"http://mdcaldav.local/ns/sync/{gen}"
             if not old_token:
@@ -473,4 +509,5 @@ class Index:
         return token, [f"{r['uid']}.ics" for r in rows]
 
     def close(self) -> None:
+        with self.lock:
             self.db.close()

src/mdcaldav/writer.py

@@ -66,11 +66,9 @@ class Writer:
         rel = task.source.rel_path
         path = self.vault / rel
 
-        row = self.index.db.execute(
+        known = self.index.file_hash_of(rel)
-            "SELECT hash FROM files WHERE rel_path = ?", (rel,)
-        ).fetchone()
         data = path.read_bytes()
-        if row is None or row["hash"] != file_hash(data):
+        if known is None or known != file_hash(data):
             # Changed behind our back — reindex before trusting any span.
             self.index.rescan([rel])
             task = self.index.tasks.get(uid)
@@ -96,6 +94,9 @@ class Writer:
     def apply(self, uid: str, changes: dict) -> None:
         if not changes:
             return
+        # Held across validate → write → reindex: a watcher rescan slipping in
+        # between would invalidate the byte spans we are about to splice.
+        with self.index.lock:
             task, path, data = self._load(uid)
             edits: list[tuple[int, int, bytes]] = []
 
@@ -168,6 +169,7 @@ class Writer:
         if not self.cfg.write.allow_create:
             raise NotAllowedError("task creation is disabled")
 
+        with self.index.lock:
             rel = self.inbox_for(collection)
             path = self.vault / rel
             heading = self.cfg.write.inbox_heading
@@ -213,6 +215,7 @@ class Writer:
     def delete(self, uid: str) -> None:
         if not self.cfg.write.allow_delete:
             raise NotAllowedError("task deletion is disabled")
+        with self.index.lock:
             task, path, data = self._load(uid)
 
             policy = self.cfg.write.delete_children

tests/test_concurrency.py

@@ -0,0 +1,147 @@
+"""The watcher thread and Radicale's request threads share one Index.
+
+Radicale serializes request threads with `Storage.acquire_lock`, but the watcher
+rescans outside it. Unsynchronized, the two interleave inside `rescan`'s
+multi-statement read-modify-write and raise `sqlite3.OperationalError: database
+is locked`, `sqlite3.InterfaceError: bad parameter or other API misuse`, or a
+`TypeError` from a row that vanished mid-pass.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+from mdcaldav.config import Config
+from mdcaldav.index import Index
+from mdcaldav.writer import Writer
+from mdcaldav.model import Status
+
+DURATION = 3.0
+
+
+def _index(vault: Path, tmp_path: Path) -> Index:
+    cfg = Config()
+    cfg.vault.path = vault
+    cfg.index.db = tmp_path / "index.db"
+    index = Index(cfg)
+    index.rescan()
+    return index
+
+
+def _run(workers: list[threading.Thread], stop: threading.Event) -> None:
+    for worker in workers:
+        worker.start()
+    time.sleep(DURATION)
+    stop.set()
+    for worker in workers:
+        worker.join(timeout=10)
+        assert not worker.is_alive(), "worker did not stop"
+
+
+def test_concurrent_rescans_do_not_corrupt_the_index(vault: Path, tmp_path: Path):
+    index = _index(vault, tmp_path)
+    note = vault / "daily" / "2026-01-05.md"
+    errors: list[BaseException] = []
+    stop = threading.Event()
+
+    def churn() -> None:
+        n = 0
+        while not stop.is_set():
+            note.write_bytes(note.read_bytes() + f"\n- [ ] churn {n}\n".encode())
+            n += 1
+            time.sleep(0.005)
+
+    def rescanner() -> None:
+        while not stop.is_set():
+            try:
+                index.rescan(["daily/2026-01-05.md"])
+                index.refresh_if_stale()
+                index.collections()
+            except BaseException as exc:  # noqa: BLE001 - the assertion is "none"
+                errors.append(exc)
+                return
+
+    workers = [threading.Thread(target=churn, daemon=True)]
+    workers += [threading.Thread(target=rescanner, daemon=True) for _ in range(4)]
+    _run(workers, stop)
+
+    assert not errors, f"{len(errors)} failures, first: {errors[0]!r}"
+
+
+def test_writes_survive_a_concurrent_watcher(vault: Path, tmp_path: Path):
+    """Completing tasks while the watcher rescans must not lose or garble edits."""
+    index = _index(vault, tmp_path)
+    writer = Writer(index.cfg, index)
+    other = vault / "daily" / "2026-01-06.md"
+    errors: list[BaseException] = []
+    completed: list[str] = []
+    stop = threading.Event()
+
+    def watcher() -> None:
+        # Stands in for the watchdog thread: touch a file, then reindex it.
+        while not stop.is_set():
+            try:
+                other.write_bytes(other.read_bytes())
+                index.rescan(["daily/2026-01-06.md"])
+            except BaseException as exc:  # noqa: BLE001
+                errors.append(exc)
+                return
+            time.sleep(0.01)
+
+    def completer() -> None:
+        while not stop.is_set():
+            pending = [
+                t
+                for t in index.tasks.values()
+                if t.status is Status.NEEDS_ACTION
+                and t.source.rel_path == "daily/2026-01-07.md"
+            ]
+            if not pending:
+                return
+            task = pending[0]
+            try:
+                writer.apply(task.uid, {"status": Status.COMPLETED})
+                completed.append(task.title)
+            except BaseException as exc:  # noqa: BLE001
+                errors.append(exc)
+                return
+            time.sleep(0.01)
+
+    _run([threading.Thread(target=f, daemon=True) for f in (watcher, completer)], stop)
+
+    assert not errors, f"{len(errors)} failures, first: {errors[0]!r}"
+    assert completed, "no task was completed"
+
+    text = (vault / "daily/2026-01-07.md").read_text()
+    for title in completed:
+        assert f"] {title}" in text  # the line still parses as a task
+    assert text.count("- [x]") >= len(completed)
+
+
+def test_etag_input_is_stable_under_a_concurrent_watcher(vault: Path, tmp_path: Path):
+    """An idle rescan loop must not change any task's last_modified.
+
+    This is what the ETag hashes; churn here is what made clients revert their
+    own edits.
+    """
+    index = _index(vault, tmp_path)
+    uids = list(index.tasks)
+    before = {uid: index.last_modified(uid) for uid in uids}
+    errors: list[BaseException] = []
+    stop = threading.Event()
+
+    def rescanner() -> None:
+        while not stop.is_set():
+            try:
+                index.rescan()
+            except BaseException as exc:  # noqa: BLE001
+                errors.append(exc)
+                return
+            time.sleep(0.01)
+
+    _run([threading.Thread(target=rescanner, daemon=True) for _ in range(3)], stop)
+
+    assert not errors, f"{len(errors)} failures, first: {errors[0]!r}"
+    assert {uid: index.last_modified(uid) for uid in uids} == before