~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
from __future__ import annotations
import errno
import multiprocessing
import os
import stat
import sys
import threading
import time
import tracemalloc
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from multiprocessing.synchronize import Event
from pathlib import Path
from types import ModuleType
from typing import ClassVar, final
from uuid import UUID
import pytest
from local_deep_research.database import rekey_lock as rekey_lock_module
from local_deep_research.database.rekey_lock import (
RekeyEpochState,
RekeyLockContentionError,
RekeyRecoveryRequiredError,
_acquire_windows_lock,
_release_windows_lock,
acquire_rekey_lock,
begin_rekey_epoch,
clear_pending_rekey_epoch,
commit_rekey_epoch,
read_rekey_epoch_state,
)
def _hold_rekey_lock(
db_path: str,
acquired: Event,
release: Event,
) -> None:
with acquire_rekey_lock(Path(db_path)):
acquired.set()
if not release.wait(timeout=10):
raise RuntimeError("parent did not release rekey-lock worker")
def _assert_sidecar_io_error(
error: rekey_lock_module.RekeySidecarIOError,
db_path: Path,
operation: rekey_lock_module.RekeySidecarOperation,
) -> None:
assert error.db_path == db_path
assert error.operation is operation
assert error.errno == errno.EIO
assert error.__context__ is None
assert str(db_path) not in str(error)
assert "sensitive raw OS text" not in str(error)
class _ProtectedBodyError(Exception):
pass
def test_rekey_lock_contends_across_processes(tmp_path: Path) -> None:
# Given a separate process holding this database's sidecar lock
db_path = tmp_path / "user.db"
context = multiprocessing.get_context("spawn")
acquired = context.Event()
release = context.Event()
process = context.Process(
target=_hold_rekey_lock,
args=(str(db_path), acquired, release),
)
process.start()
try:
assert acquired.wait(timeout=10), "child did not acquire the rekey lock"
# When this process attempts the same nonblocking lock
with pytest.raises(RekeyLockContentionError):
with acquire_rekey_lock(db_path):
pytest.fail("contended rekey lock was acquired")
finally:
release.set()
process.join(timeout=10)
if process.is_alive():
process.terminate()
process.join(timeout=5)
# Then only the child acquired it and exited cleanly
assert process.exitcode == 0
def _os_lock_attempt_name() -> str:
return "_acquire_windows_lock" if os.name == "nt" else "_acquire_posix_lock"
def test_contention_retry_rides_out_a_holder_that_releases_in_the_window(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given another process holding the sidecar lock, which it releases only
# once this process has already been refused at least once
db_path = tmp_path / "user.db"
context = multiprocessing.get_context("spawn")
acquired = context.Event()
release = context.Event()
process = context.Process(
target=_hold_rekey_lock,
args=(str(db_path), acquired, release),
)
process.start()
attempt_name = _os_lock_attempt_name()
real_attempt = getattr(rekey_lock_module, attempt_name)
refusals = 0
def attempt_then_release_holder(*args: object, **kwargs: object) -> None:
nonlocal refusals
try:
real_attempt(*args, **kwargs)
except RekeyLockContentionError:
refusals += 1
release.set()
raise
monkeypatch.setattr(
rekey_lock_module, attempt_name, attempt_then_release_holder
)
try:
assert acquired.wait(timeout=10), "child did not acquire the rekey lock"
# When this process takes the lock with a generous retry window
with acquire_rekey_lock(db_path, contention_retry=30.0):
held_here = True
finally:
release.set()
process.join(timeout=10)
if process.is_alive():
process.terminate()
process.join(timeout=5)
# Then it was refused while the holder lived and acquired once released
assert held_here
assert refusals >= 1
assert process.exitcode == 0
def test_contention_retry_gives_up_on_a_holder_beyond_the_window(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given another process holding the sidecar lock for longer than the window
db_path = tmp_path / "user.db"
context = multiprocessing.get_context("spawn")
acquired = context.Event()
release = context.Event()
process = context.Process(
target=_hold_rekey_lock,
args=(str(db_path), acquired, release),
)
process.start()
attempt_name = _os_lock_attempt_name()
real_attempt = getattr(rekey_lock_module, attempt_name)
attempts = 0
def counting_attempt(*args: object, **kwargs: object) -> None:
nonlocal attempts
attempts += 1
real_attempt(*args, **kwargs)
monkeypatch.setattr(rekey_lock_module, attempt_name, counting_attempt)
window = 0.5
try:
assert acquired.wait(timeout=10), "child did not acquire the rekey lock"
# When this process retries the nonblocking lock for the window
started = time.monotonic()
with pytest.raises(RekeyLockContentionError):
with acquire_rekey_lock(db_path, contention_retry=window):
pytest.fail("lock held by another process was acquired")
elapsed = time.monotonic() - started
finally:
release.set()
process.join(timeout=10)
if process.is_alive():
process.terminate()
process.join(timeout=5)
# Then it kept retrying for the whole window and then failed as contention
assert elapsed >= window
assert elapsed < window + 5
assert attempts > 1
assert process.exitcode == 0
@contextmanager
def _flock_held_by_another_descriptor(db_path: Path) -> Iterator[None]:
# A second open file description of the sidecar: flock makes it contend
# with this process's own descriptor exactly as another process's
# would, and it never takes this process's gate, like a foreign holder.
import fcntl
fd = os.open(
db_path.with_name(f"{db_path.name}.rekey.lock"),
os.O_RDWR | os.O_CREAT,
0o600,
)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
yield
finally:
os.close(fd)
@pytest.mark.skipif(os.name == "nt", reason="POSIX flock required")
def test_timeout_gives_up_on_a_flock_holder_after_the_bound(
tmp_path: Path,
) -> None:
# Given a holder that does not release on its own (another process's
# rekey of a large database, a stopped process, a hung mount)
db_path = tmp_path / "user.db"
bound = 0.3
with _flock_held_by_another_descriptor(db_path):
# When a request-path caller takes the sidecar with a timeout
started = time.monotonic()
with pytest.raises(RekeyLockContentionError):
with acquire_rekey_lock(db_path, timeout=bound):
pytest.fail("a flock held elsewhere was acquired")
elapsed = time.monotonic() - started
# Then it retried for the whole bound and gave up as typed contention
assert bound <= elapsed < bound + 5
# and the same bounded acquisition succeeds once the holder is gone
with acquire_rekey_lock(db_path, timeout=bound):
pass
def test_timeout_bounds_the_wait_for_an_in_process_holder(
tmp_path: Path,
) -> None:
# Given another thread of this process holding the sidecar, so the
# in-process gate as well, until the test lets it go
db_path = tmp_path / "user.db"
bound = 0.3
acquired = threading.Event()
release = threading.Event()
def hold() -> None:
with acquire_rekey_lock(db_path):
acquired.set()
release.wait(timeout=30)
holder = threading.Thread(target=hold, daemon=True)
holder.start()
try:
assert acquired.wait(timeout=10), "holder never took the sidecar"
# When a request-path caller takes the sidecar with a timeout
started = time.monotonic()
with pytest.raises(RekeyLockContentionError):
with acquire_rekey_lock(db_path, timeout=bound):
pytest.fail("the gate held by another thread was acquired")
elapsed = time.monotonic() - started
finally:
release.set()
holder.join(timeout=10)
# Then the gate wait was bounded the same way
assert not holder.is_alive()
assert bound <= elapsed < bound + 5
def test_rekey_lock_sidecar_is_persistent_and_owner_only(
tmp_path: Path,
) -> None:
# Given a database path without a sidecar
db_path = tmp_path / "user.db"
lock_path = tmp_path / "user.db.rekey.lock"
# When the rekey lock is acquired and released
with acquire_rekey_lock(db_path):
assert lock_path.exists()
original_inode = lock_path.stat().st_ino
with acquire_rekey_lock(db_path):
rekey_lock_module.advance_rekey_epoch(db_path)
# Then the owner-only sidecar remains for future lock acquisitions
assert lock_path.exists()
assert lock_path.stat().st_ino == original_inode
if os.name != "nt":
assert stat.S_IMODE(lock_path.stat().st_mode) == 0o600
def test_rekey_lock_chmod_failure_is_best_effort(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a filesystem that rejects permission changes
db_path = tmp_path / "user.db"
def fail_chmod(_path_or_fd: str | Path | int, _mode: int) -> None:
raise OSError(errno.EPERM, "chmod unsupported")
monkeypatch.setattr(os, "chmod", fail_chmod)
# The sidecar mode is tightened through its fd (never by path).
monkeypatch.setattr(os, "fchmod", fail_chmod, raising=False)
# When the stable lock is acquired, then chmod cannot abort locking
with acquire_rekey_lock(db_path):
assert db_path.with_name("user.db.rekey.lock").exists()
@pytest.mark.skipif(
not hasattr(os, "O_NOFOLLOW"), reason="O_NOFOLLOW unavailable"
)
def test_symlinked_rekey_lock_sidecar_is_refused(tmp_path: Path) -> None:
# Given a symlink planted at the sidecar name, pointing at another file
db_path = tmp_path / "user.db"
target = tmp_path / "unrelated.txt"
target.write_text("unrelated\n", encoding="utf-8")
os.chmod(target, 0o644)
db_path.with_name("user.db.rekey.lock").symlink_to(target)
# When the stable lock is acquired, then the link is refused, typed
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar lock acquired through a symlink")
# And neither the open nor the permission tightening reached the target
assert (
raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
)
assert raised.value.errno == errno.ELOOP
assert "symlink" in str(raised.value)
assert stat.S_IMODE(target.stat().st_mode) == 0o644
assert target.read_text(encoding="utf-8") == "unrelated\n"
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "link"),
reason="POSIX hard links required",
)
def test_hard_linked_sidecar_is_locked_without_touching_its_mode(
tmp_path: Path,
) -> None:
# Given a hard link at the sidecar name whose other name is outside the
# sidecar's directory (a backup or snapshot tool that hard-links the
# data directory into another one)
data_dir = tmp_path / "encrypted_databases"
data_dir.mkdir()
snapshot_dir = tmp_path / "snapshot"
snapshot_dir.mkdir()
db_path = data_dir / "user.db"
target = snapshot_dir / "unrelated.txt"
target.write_text("unrelated\n", encoding="utf-8")
os.chmod(target, 0o644)
os.link(target, db_path.with_name("user.db.rekey.lock"))
# When the sidecar is opened for the rekey lock
entered = False
with acquire_rekey_lock(db_path):
entered = True
# Then the lock is taken (no lockout), and the linked file keeps its
# mode and content
assert entered
assert stat.S_IMODE(target.stat().st_mode) == 0o644
assert target.read_text(encoding="utf-8") == "unrelated\n"
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "link"),
reason="POSIX hard links required",
)
def test_hard_linked_sidecar_is_refused_unopened_when_directory_scan_fails(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given an external hard link distinct from the real DB, WAL and shm,
# so classification must reach the directory scan to rule out aliases.
data_dir = tmp_path / "encrypted_databases"
data_dir.mkdir()
snapshot_dir = tmp_path / "snapshot"
snapshot_dir.mkdir()
db_path = data_dir / "user.db"
database_identities = set()
for suffix in ("", "-wal", "-shm"):
path = db_path.with_name(f"user.db{suffix}")
path.write_bytes(f"database{suffix}".encode())
status = path.stat()
database_identities.add((status.st_dev, status.st_ino))
assert len(database_identities) == 3
target = snapshot_dir / "unrelated.txt"
original_bytes = b"unrelated\n"
target.write_bytes(original_bytes)
target.chmod(0o644)
sidecar = db_path.with_name("user.db.rekey.lock")
os.link(target, sidecar)
original = target.stat()
identity = (original.st_dev, original.st_ino)
original_mode = stat.S_IMODE(original.st_mode)
assert original.st_nlink >= 2
assert identity not in database_identities
linked = sidecar.stat()
assert (linked.st_dev, linked.st_ino) == identity
assert linked.st_nlink == original.st_nlink
real_scandir = os.scandir
real_open = os.open
scan_attempts: list[object] = []
open_attempts: list[str] = []
def denied_scandir(path):
scan_attempts.append(path)
if path == data_dir:
raise PermissionError(
errno.EACCES, "synthetic unlistable directory"
)
return real_scandir(path)
def recording_open(path, *args, **kwargs):
open_attempts.append(os.fspath(path))
return real_open(path, *args, **kwargs)
# The authorization-lease sidecar main also covered here was removed
# with its unused API (#6750); the rekey lock is the only sidecar.
acquire = acquire_rekey_lock(db_path)
entered = False
refusal = None
# Only the exact lock parent is unlistable; all opens remain real.
with monkeypatch.context() as scoped:
scoped.setattr(os, "scandir", denied_scandir)
scoped.setattr(os, "open", recording_open)
try:
with acquire:
entered = True
except rekey_lock_module.RekeySidecarIOError as error:
refusal = error
# Cleanup and assertions run after restoring filesystem operations.
assert data_dir in scan_attempts
assert not entered, "protected body entered despite an unlistable directory"
assert os.fspath(sidecar) not in open_attempts
assert os.fspath(target) not in open_attempts
assert isinstance(refusal, rekey_lock_module.RekeySidecarIOError)
assert refusal.operation is rekey_lock_module.RekeySidecarOperation.OPEN
assert refusal.errno == errno.EMLINK
assert refusal.db_path == db_path
for path in (sidecar, target):
status = path.stat()
assert (status.st_dev, status.st_ino) == identity
assert status.st_nlink == original.st_nlink
assert stat.S_IMODE(status.st_mode) == original_mode
assert path.read_bytes() == original_bytes
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "link"),
reason="POSIX hard links required",
)
@pytest.mark.parametrize("victim_suffix", ["", "-wal", "-shm"])
def test_sidecar_hard_linked_to_another_users_database_is_refused_unopened(
tmp_path: Path, victim_suffix: str, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given this user's lock file hard-linked to ANOTHER user's database
# file in the same directory
db_path = tmp_path / "ldr_user_attacker.db"
db_path.write_bytes(b"attacker")
victim = tmp_path / f"ldr_user_victim.db{victim_suffix}"
victim.write_bytes(b"victim database")
lock_path = db_path.with_name(f"{db_path.name}.rekey.lock")
os.link(victim, lock_path)
real_open = os.open
opened: list[str] = []
def spy_open(path, *args, **kwargs):
opened.append(os.fspath(path))
return real_open(path, *args, **kwargs)
monkeypatch.setattr(rekey_lock_module.os, "open", spy_open)
# When the rekey lock is taken
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar lock acquired through another user's file")
# Then it is refused, typed, and the victim's inode is never opened
assert raised.value.errno == errno.EMLINK
assert (
raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
)
assert os.fspath(lock_path) not in opened
assert os.fspath(victim) not in opened
assert victim.read_bytes() == b"victim database"
def test_plain_sidecar_is_locked(tmp_path: Path) -> None:
# Given an ordinary database directory with no links
db_path = tmp_path / "user.db"
db_path.write_bytes(b"database")
(tmp_path / "other.db").write_bytes(b"other")
# When the rekey lock is taken twice (created, then reused)
for _ in range(2):
with acquire_rekey_lock(db_path):
pass
# Then it is a single-link regular file owned by the sidecar name
status = db_path.with_name("user.db.rekey.lock").stat()
assert status.st_nlink == 1
assert stat.S_ISREG(status.st_mode)
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "link"),
reason="POSIX hard links required",
)
@pytest.mark.parametrize("database_suffix", ["", "-wal", "-shm"])
def test_sidecar_hard_linked_to_the_database_is_refused_unopened(
tmp_path: Path, database_suffix: str, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given the lock file hard-linked to the database, its WAL or its shm
db_path = tmp_path / "user.db"
db_path.write_bytes(b"database")
target = db_path.with_name(f"user.db{database_suffix}")
if database_suffix:
target.write_bytes(b"sidecar")
lock_path = db_path.with_name("user.db.rekey.lock")
os.link(target, lock_path)
real_open = os.open
opened: list[str] = []
def spy_open(path, *args, **kwargs):
opened.append(os.fspath(path))
return real_open(path, *args, **kwargs)
monkeypatch.setattr(rekey_lock_module.os, "open", spy_open)
# When the rekey lock is taken
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar lock acquired through a link to the database")
# Then it is refused, typed, without ever opening (and so closing) a
# descriptor to the database file
assert raised.value.errno == errno.EMLINK
assert (
raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
)
assert os.fspath(lock_path) not in opened
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "mkfifo"),
reason="POSIX FIFOs required",
)
def test_non_regular_sidecar_is_refused_and_its_fd_closed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a FIFO planted at the sidecar name
db_path = tmp_path / "user.db"
sidecar = db_path.with_name("user.db.rekey.lock")
os.mkfifo(sidecar, 0o600)
opened_fds: list[int] = []
real_open = os.open
def recording_open(path, flags, mode=0o777, *args, **kwargs):
fd = real_open(path, flags, mode, *args, **kwargs)
if Path(path) == sidecar:
opened_fds.append(fd)
return fd
monkeypatch.setattr(rekey_lock_module.os, "open", recording_open)
# When the sidecar is opened for the rekey lock
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar lock acquired on a FIFO")
monkeypatch.undo()
# Then the open is refused, typed, and the fd it opened is closed
assert (
raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
)
assert raised.value.errno == errno.EINVAL
assert "non-regular" in str(raised.value)
assert len(opened_fds) == 1
with pytest.raises(OSError) as closed:
os.fstat(opened_fds[0])
assert closed.value.errno == errno.EBADF
assert stat.S_ISFIFO(sidecar.lstat().st_mode)
def test_missing_epoch_is_invalid_until_repaired_under_lock(
tmp_path: Path,
) -> None:
# Given no durable epoch for an existing database path
db_path = tmp_path / "user.db"
assert rekey_lock_module.read_rekey_epoch(db_path) is None
# When the caller repairs it while holding the stable sidecar lock
with acquire_rekey_lock(db_path):
epoch = rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
# Then the persisted token is a canonical lowercase UUID
assert str(UUID(epoch)) == epoch
assert rekey_lock_module.read_rekey_epoch(db_path) == epoch
def test_rekey_epoch_pending_commit_and_cleanup_are_explicit(
tmp_path: Path,
) -> None:
# Given a stable committed epoch
db_path = tmp_path / "user.db"
with acquire_rekey_lock(db_path):
committed_epoch = rekey_lock_module.read_or_initialize_rekey_epoch(
db_path
)
# When a candidate is begun but not yet committed
pending_epoch = begin_rekey_epoch(db_path)
assert str(UUID(pending_epoch)) == pending_epoch
if os.name != "nt":
pending_path = db_path.with_name("user.db.rekey.pending")
assert stat.S_IMODE(pending_path.stat().st_mode) == 0o600
# Then cache projection fails closed while full state remains recoverable
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
committed_epoch=committed_epoch,
pending_epoch=pending_epoch,
)
assert rekey_lock_module.read_rekey_epoch(db_path) is None
# When the candidate is committed, pending metadata remains explicit
commit_rekey_epoch(db_path, pending_epoch)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
committed_epoch=pending_epoch,
pending_epoch=pending_epoch,
)
assert rekey_lock_module.read_rekey_epoch(db_path) is None
# When cleanup succeeds, the committed epoch becomes cache-visible
clear_pending_rekey_epoch(db_path, pending_epoch)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
committed_epoch=pending_epoch,
pending_epoch=None,
)
assert rekey_lock_module.read_rekey_epoch(db_path) == pending_epoch
if os.name != "nt":
pending_path = db_path.with_name("user.db.rekey.pending")
epoch_path = db_path.with_name("user.db.rekey.epoch")
assert not pending_path.exists()
assert stat.S_IMODE(epoch_path.stat().st_mode) == 0o600
def test_malformed_epoch_fails_closed_under_lock(
tmp_path: Path,
) -> None:
# Given a malformed durable epoch
db_path = tmp_path / "user.db"
epoch_path = db_path.with_name("user.db.rekey.epoch")
epoch_path.write_text("NOT-A-CANONICAL-UUID", encoding="ascii")
# When the caller attempts to read or repair it under the lock
with acquire_rekey_lock(db_path):
with pytest.raises(RekeyRecoveryRequiredError):
read_rekey_epoch_state(db_path)
with pytest.raises(RekeyRecoveryRequiredError):
rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
# Then malformed content is preserved for explicit operator recovery
assert rekey_lock_module.read_rekey_epoch(db_path) is None
assert epoch_path.read_text(encoding="ascii") == "NOT-A-CANONICAL-UUID"
def _commit_first_epoch(db_path: Path) -> str:
with acquire_rekey_lock(db_path):
return rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
def _run_bounded(
call: Callable[[], object], timeout: float = 5.0
) -> tuple[threading.Thread, dict[str, object]]:
# Runs ``call`` on a daemon thread and waits at most ``timeout``, so a
# read that hangs fails the test instead of the CI job.
outcome: dict[str, object] = {}
def target() -> None:
try:
outcome["value"] = call()
except BaseException as error: # noqa: BLE001 - handed to the test
outcome["error"] = error
worker = threading.Thread(target=target, daemon=True)
worker.start()
worker.join(timeout)
return worker, outcome
def _release_fifo_reader(fifo: Path) -> None:
# A reader blocked opening the FIFO is released by a writer that opens
# and closes it; with no reader waiting the open fails (ENXIO) and
# there is nothing to release.
try:
fd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK)
except OSError:
return
os.close(fd)
@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="POSIX FIFOs required")
@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
@pytest.mark.parametrize("planted_kind", ["fifo", "directory"])
def test_a_non_regular_epoch_file_is_refused_without_reading_it(
tmp_path: Path, suffix: str, planted_kind: str
) -> None:
# Given a FIFO or a directory planted at an epoch file name
db_path = tmp_path / "user.db"
_commit_first_epoch(db_path)
planted = db_path.with_name(f"user.db{suffix}")
planted.unlink(missing_ok=True)
if planted_kind == "fifo":
os.mkfifo(planted, 0o600)
else:
planted.mkdir()
# When the durable state is read under the sidecar, as every probe does
def read_under_the_sidecar() -> RekeyEpochState:
with acquire_rekey_lock(db_path):
return read_rekey_epoch_state(db_path)
worker, outcome = _run_bounded(read_under_the_sidecar)
finished = not worker.is_alive()
if planted_kind == "fifo":
_release_fifo_reader(planted)
worker.join(timeout=10)
# Then it fails at once as "nothing was read", leaves the file alone
# and releases the sidecar
assert finished, "the epoch read waited on a planted FIFO under the flock"
error = outcome.get("error")
assert isinstance(error, rekey_lock_module.RekeyEpochUnreadableError), (
outcome
)
assert error.errno == errno.EINVAL
if planted_kind == "fifo":
assert stat.S_ISFIFO(planted.lstat().st_mode)
else:
assert planted.is_dir()
with acquire_rekey_lock(db_path):
pass
@pytest.mark.skipif(os.name == "nt", reason="POSIX symlinks required")
@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
def test_a_symlinked_epoch_file_is_refused_not_followed(
tmp_path: Path, suffix: str
) -> None:
# Given a link at an epoch file name to a file elsewhere holding the
# committed token itself, so following the link would vouch for it
db_path = tmp_path / "user.db"
committed = _commit_first_epoch(db_path)
target = tmp_path / "elsewhere" / "token"
target.parent.mkdir()
target.write_text(committed, encoding="ascii")
link = db_path.with_name(f"user.db{suffix}")
link.unlink(missing_ok=True)
link.symlink_to(target)
# When the durable state is read
with pytest.raises(rekey_lock_module.RekeyEpochUnreadableError) as raised:
read_rekey_epoch_state(db_path)
# Then the link is refused (O_NOFOLLOW), and both files are left as found
assert raised.value.errno == errno.ELOOP
assert link.is_symlink()
assert target.read_text(encoding="ascii") == committed
@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
def test_an_oversized_epoch_file_is_refused_without_being_read(
tmp_path: Path, suffix: str
) -> None:
# Given a regular file far larger than a token at an epoch file name
db_path = tmp_path / "user.db"
_commit_first_epoch(db_path)
size = 8 * 1024 * 1024
db_path.with_name(f"user.db{suffix}").write_bytes(b"0" * size)
# When the durable state is read
was_tracing = tracemalloc.is_tracing()
if not was_tracing:
tracemalloc.start()
try:
tracemalloc.reset_peak()
baseline, _ = tracemalloc.get_traced_memory()
with pytest.raises(RekeyRecoveryRequiredError) as raised:
read_rekey_epoch_state(db_path)
_, peak = tracemalloc.get_traced_memory()
finally:
if not was_tracing:
tracemalloc.stop()
# Then it does not vouch, like any malformed token (it is not an
# unreadable file), and was refused without being read into memory
assert not isinstance(
raised.value, rekey_lock_module.RekeyEpochUnreadableError
)
assert peak - baseline < size // 8
@pytest.mark.parametrize(
("error_number", "tolerated"),
[
pytest.param(errno.EIO, False, id="EIO-real-failure"),
pytest.param(errno.EINVAL, True, id="EINVAL-unsupported"),
],
)
def test_pending_transition_directory_fsync_failure_fails_closed(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
error_number: int,
tolerated: bool,
) -> None:
"""A directory-fsync error during pending publication is classified.
``_sync_parent_directory`` treats the errnos a filesystem uses to say
"directory fsync is not supported here" (EINVAL, ENOTSUP/EOPNOTSUPP,
ENOSYS) as "as durable as this filesystem allows", because treating
them as fatal made every epoch publication fail on such mounts. A real
failure (EIO) still propagates. This test originally asserted that
EINVAL raised; that predates the tolerance and contradicted the
documented behaviour (and
``test_unsupported_directory_fsync_does_not_fail_epoch_publication``),
so it now pins both sides on the pending transition: the real failure
fails closed with the visible pending file still fencing caches, and
the unsupported errno publishes the pending epoch normally.
"""
if os.name == "nt":
pytest.skip("directory fsync is skipped entirely on Windows")
# Given a stable epoch and a filesystem whose directory fsync errors
db_path = tmp_path / "user.db"
with acquire_rekey_lock(db_path):
committed_epoch = rekey_lock_module.read_or_initialize_rekey_epoch(
db_path
)
real_fsync = os.fsync
def fail_directory_fsync(fd: int) -> None:
if stat.S_ISDIR(os.fstat(fd).st_mode):
raise OSError(error_number, "directory fsync error")
real_fsync(fd)
monkeypatch.setattr(os, "fsync", fail_directory_fsync)
# When pending publication cannot synchronize its parent directory
with acquire_rekey_lock(db_path):
if tolerated:
pending_epoch = begin_rekey_epoch(db_path)
else:
with pytest.raises(OSError) as raised:
begin_rekey_epoch(db_path)
assert raised.value.errno == error_number
# Then E1 is preserved and the pending file fences caches either way
state = read_rekey_epoch_state(db_path)
assert state.committed_epoch == committed_epoch
assert state.pending_epoch is not None
if tolerated:
assert state.pending_epoch == pending_epoch
assert rekey_lock_module.read_rekey_epoch(db_path) is None
def test_epoch_replace_failure_aborts_without_accepting_partial_state(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given an epoch replacement that the filesystem refuses
db_path = tmp_path / "user.db"
epoch_path = db_path.with_name("user.db.rekey.epoch")
def fail_replace(source: str | Path, _target: str | Path) -> None:
if os.name != "nt":
assert stat.S_IMODE(Path(source).stat().st_mode) == 0o600
raise OSError(errno.EIO, "replace failed")
monkeypatch.setattr(os, "replace", fail_replace)
# When repair attempts the atomic replace, then the write failure propagates
with acquire_rekey_lock(db_path):
with pytest.raises(OSError, match="replace failed"):
rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
assert not epoch_path.exists()
def test_pending_without_committed_epoch_fails_closed(tmp_path: Path) -> None:
# Given a canonical pending epoch without committed metadata
db_path = tmp_path / "user.db"
pending_path = db_path.with_name("user.db.rekey.pending")
pending_path.write_text(str(UUID(int=1)), encoding="ascii")
# When state is read, then the contradictory transition requires recovery
with pytest.raises(RekeyRecoveryRequiredError):
read_rekey_epoch_state(db_path)
assert rekey_lock_module.read_rekey_epoch(db_path) is None
def test_posix_noncontention_error_is_typed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
if os.name == "nt":
pytest.skip("POSIX backend test")
# Given flock reports an unrelated I/O error
import fcntl
def fail_flock(_fd: int, _operation: int) -> None:
raise OSError(errno.EIO, "simulated I/O failure")
monkeypatch.setattr(fcntl, "flock", fail_flock)
# When the sidecar lock is acquired, then the I/O failure is normalized
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(tmp_path / "user.db"):
pytest.fail("lock unexpectedly acquired")
_assert_sidecar_io_error(
raised.value,
tmp_path / "user.db",
rekey_lock_module.RekeySidecarOperation.ACQUIRE,
)
assert not isinstance(raised.value, RekeyLockContentionError)
def test_sidecar_open_failure_is_typed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given sidecar creation fails with raw operating-system text
db_path = tmp_path / "user.db"
def fail_open(_path: Path, _flags: int, _mode: int) -> int:
raise OSError(errno.EIO, "sensitive raw OS text")
# When the existing rekey lock opens its persistent sidecar
with monkeypatch.context() as scoped:
scoped.setattr(os, "open", fail_open)
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar unexpectedly opened")
# Then the failure carries only typed safe diagnostics
_assert_sidecar_io_error(
raised.value,
db_path,
rekey_lock_module.RekeySidecarOperation.OPEN,
)
def test_sidecar_acquire_failure_is_typed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given the platform backend reports a non-contention acquisition failure
db_path = tmp_path / "user.db"
acquire_name = (
"_acquire_windows_lock" if os.name == "nt" else "_acquire_posix_lock"
)
def fail_acquire(
_fd: int,
_lock_path: Path,
*,
blocking: bool = False,
) -> None:
raise OSError(errno.EIO, "sensitive raw OS text")
# When the existing rekey lock acquires its sidecar
with monkeypatch.context() as scoped:
scoped.setattr(rekey_lock_module, acquire_name, fail_acquire)
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pytest.fail("sidecar lock unexpectedly acquired")
# Then acquisition exposes only the typed sidecar failure
_assert_sidecar_io_error(
raised.value,
db_path,
rekey_lock_module.RekeySidecarOperation.ACQUIRE,
)
def test_sidecar_unlock_failure_is_typed_and_closes_once(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given unlock fails and close calls are observable
db_path = tmp_path / "user.db"
release_name = (
"_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
)
real_close = os.close
close_calls: list[int] = []
def fail_release(_fd: int) -> None:
raise OSError(errno.EIO, "sensitive raw OS text")
def close_once(fd: int) -> None:
close_calls.append(fd)
real_close(fd)
# When the protected body succeeds but unlock fails
with monkeypatch.context() as scoped:
scoped.setattr(rekey_lock_module, release_name, fail_release)
scoped.setattr(os, "close", close_once)
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pass
# Then unlock is typed and close was attempted exactly once
_assert_sidecar_io_error(
raised.value,
db_path,
rekey_lock_module.RekeySidecarOperation.UNLOCK,
)
assert len(close_calls) == 1
def test_sidecar_close_failure_is_typed_without_retry(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given close fails after actually closing the descriptor
db_path = tmp_path / "user.db"
real_close = os.close
close_calls: list[int] = []
def fail_close(fd: int) -> None:
close_calls.append(fd)
real_close(fd)
raise OSError(errno.EIO, "sensitive raw OS text")
# When cleanup closes the existing rekey sidecar
with monkeypatch.context() as scoped:
scoped.setattr(os, "close", fail_close)
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pass
# Then close is typed and never retried
_assert_sidecar_io_error(
raised.value,
db_path,
rekey_lock_module.RekeySidecarOperation.CLOSE,
)
assert len(close_calls) == 1
def test_protected_body_error_survives_unlock_and_close_failures(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given both cleanup stages fail with unsafe operating-system text
db_path = tmp_path / "user.db"
release_name = (
"_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
)
real_close = os.close
close_calls: list[int] = []
def fail_release(_fd: int) -> None:
raise OSError(errno.EIO, "sensitive raw OS text")
def fail_close(fd: int) -> None:
close_calls.append(fd)
real_close(fd)
raise OSError(errno.EIO, "sensitive raw OS text")
# When the protected body raises before cleanup runs
with monkeypatch.context() as scoped:
scoped.setattr(rekey_lock_module, release_name, fail_release)
scoped.setattr(os, "close", fail_close)
with pytest.raises(_ProtectedBodyError) as raised:
with acquire_rekey_lock(db_path):
raise _ProtectedBodyError
# Then the body error wins and cleanup emits only safe typed notes
assert len(close_calls) == 1
assert len(raised.value.__notes__) == 2
assert all(str(db_path) not in note for note in raised.value.__notes__)
assert all(
"sensitive raw OS text" not in note for note in raised.value.__notes__
)
assert any("unlock" in note for note in raised.value.__notes__)
assert any("close" in note for note in raised.value.__notes__)
class _CallerHandledError(Exception):
"""An unrelated exception the caller is handling when it takes the lock."""
def _fail_one_release_stage(
scoped: pytest.MonkeyPatch, stage: rekey_lock_module.RekeySidecarOperation
) -> list[int]:
release_name = (
"_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
)
real_close = os.close
close_calls: list[int] = []
def fail_release(_fd: int) -> None:
raise OSError(errno.EIO, "sensitive raw OS text")
def fail_close(fd: int) -> None:
close_calls.append(fd)
real_close(fd)
raise OSError(errno.EIO, "sensitive raw OS text")
match stage:
case rekey_lock_module.RekeySidecarOperation.UNLOCK:
scoped.setattr(rekey_lock_module, release_name, fail_release)
case rekey_lock_module.RekeySidecarOperation.CLOSE:
scoped.setattr(os, "close", fail_close)
case _:
raise AssertionError(f"not a release stage: {stage}")
return close_calls
@pytest.mark.parametrize(
"stage",
[
rekey_lock_module.RekeySidecarOperation.UNLOCK,
rekey_lock_module.RekeySidecarOperation.CLOSE,
],
ids=["unlock", "close"],
)
def test_release_failure_after_a_clean_body_raises_inside_a_callers_except_block(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
stage: rekey_lock_module.RekeySidecarOperation,
) -> None:
# Given a caller that takes the lock while it handles an unrelated
# exception (a probe made from an error handler), and a release stage
# that fails
db_path = tmp_path / "user.db"
handled = _CallerHandledError("the caller's own error")
# When the protected body finishes cleanly
with monkeypatch.context() as scoped:
close_calls = _fail_one_release_stage(scoped, stage)
try:
raise handled
except _CallerHandledError:
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
with acquire_rekey_lock(db_path):
pass
# Then the release failure is raised, typed and scrubbed, as it is
# outside an except block. It used to be added as a note to the
# caller's unrelated exception (the one sys.exception() returned in the
# lock's cleanup) and never raised, so the caller saw a clean release.
assert raised.value.operation is stage
assert raised.value.errno == errno.EIO
assert str(db_path) not in str(raised.value)
assert "sensitive raw OS text" not in str(raised.value)
assert not getattr(handled, "__notes__", None)
if stage is rekey_lock_module.RekeySidecarOperation.CLOSE:
assert len(close_calls) == 1
def test_body_error_inside_a_callers_except_block_carries_the_release_note(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a caller handling an unrelated exception and a failing unlock
db_path = tmp_path / "user.db"
handled = _CallerHandledError("the caller's own error")
# When the protected body itself raises
with monkeypatch.context() as scoped:
_fail_one_release_stage(
scoped, rekey_lock_module.RekeySidecarOperation.UNLOCK
)
try:
raise handled
except _CallerHandledError:
with pytest.raises(_ProtectedBodyError) as raised:
with acquire_rekey_lock(db_path):
raise _ProtectedBodyError
# Then the body's error wins and carries the release failure as a
# note; the caller's exception is left alone
assert len(raised.value.__notes__) == 1
assert "unlock" in raised.value.__notes__[0]
assert not getattr(handled, "__notes__", None)
@final
class _FakeMsvcrt(ModuleType):
LK_LOCK: ClassVar[int] = 0
LK_NBLCK: ClassVar[int] = 1
LK_UNLCK: ClassVar[int] = 4
def __init__(self, acquire_error: OSError | None = None) -> None:
super().__init__("msvcrt")
self.acquire_error = acquire_error
self.calls: list[tuple[int, int, int]] = []
def locking(self, fd: int, mode: int, size: int) -> None:
self.calls.append((os.lseek(fd, 0, os.SEEK_CUR), mode, size))
if mode == self.LK_NBLCK and self.acquire_error is not None:
raise self.acquire_error
def test_windows_backend_locks_one_byte_from_start(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given an empty persistent sidecar and a Windows locking backend
lock_path = tmp_path / "user.db.rekey.lock"
fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
backend = _FakeMsvcrt()
monkeypatch.setitem(sys.modules, "msvcrt", backend)
try:
# When the Windows lock is acquired and released
_acquire_windows_lock(fd, lock_path)
_release_windows_lock(fd)
finally:
os.close(fd)
# Then a persistent byte backs both operations at offset zero
assert lock_path.read_bytes() == b"\0"
assert backend.calls == [
(0, backend.LK_NBLCK, 1),
(0, backend.LK_UNLCK, 1),
]
def test_windows_backend_selects_blocking_and_nonblocking_modes(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a persistent sidecar and a Windows locking backend
lock_path = tmp_path / "user.db.rekey.lock"
fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
backend = _FakeMsvcrt()
monkeypatch.setitem(sys.modules, "msvcrt", backend)
try:
# When nonblocking and blocking exclusive locks are acquired
_acquire_windows_lock(fd, lock_path)
_release_windows_lock(fd)
_acquire_windows_lock(fd, lock_path, blocking=True)
_release_windows_lock(fd)
finally:
os.close(fd)
# Then Windows uses the non-blocking and blocking write-lock modes
assert [call[1] for call in backend.calls] == [
backend.LK_NBLCK,
backend.LK_UNLCK,
backend.LK_LOCK,
backend.LK_UNLCK,
]
def test_windows_backend_translates_only_contention(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given the Windows backend reports lock contention
lock_path = tmp_path / "user.db.rekey.lock"
fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
backend = _FakeMsvcrt(OSError(errno.EACCES, "region already locked"))
monkeypatch.setitem(sys.modules, "msvcrt", backend)
try:
# When the one-byte lock is attempted, then contention is typed
with pytest.raises(RekeyLockContentionError) as raised:
_acquire_windows_lock(fd, lock_path)
finally:
os.close(fd)
assert raised.value.lock_path == lock_path
def test_windows_backend_preserves_unrelated_io_errors(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given the Windows backend reports an unrelated I/O error
lock_path = tmp_path / "user.db.rekey.lock"
fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
backend = _FakeMsvcrt(OSError(errno.EIO, "simulated I/O failure"))
monkeypatch.setitem(sys.modules, "msvcrt", backend)
try:
# When the one-byte lock is attempted, then the original error propagates
with pytest.raises(OSError) as raised:
_acquire_windows_lock(fd, lock_path)
finally:
os.close(fd)
assert raised.value.errno == errno.EIO
assert not isinstance(raised.value, RekeyLockContentionError)
def test_epoch_token_is_fsynced_before_it_replaces_the_epoch_file(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Given a spy on fsync and replace in the epoch writer
db_path = tmp_path / "user.db"
events: list[tuple[str, str]] = []
real_fsync = os.fsync
real_replace = os.replace
def spy_fsync(fd: int) -> None:
status = os.fstat(fd)
if stat.S_ISREG(status.st_mode):
events.append(("fsync", os.readlink(f"/proc/self/fd/{fd}")))
real_fsync(fd)
def spy_replace(source, target) -> None:
events.append(("replace", os.fspath(source)))
real_replace(source, target)
if not Path("/proc/self/fd").is_dir():
pytest.skip("needs /proc/self/fd to name the synced file")
monkeypatch.setattr(rekey_lock_module.os, "fsync", spy_fsync)
monkeypatch.setattr(rekey_lock_module.os, "replace", spy_replace)
# When an epoch is published
with acquire_rekey_lock(db_path):
rekey_lock_module.read_or_initialize_rekey_epoch(db_path)
# Then the temporary token file was fsynced before it was renamed over
# the epoch file
replaced = [path for kind, path in events if kind == "replace"]
assert len(replaced) == 1
synced_before = events[: events.index(("replace", replaced[0]))]
assert ("fsync", replaced[0]) in synced_before
class TestEpochTransitionGuards:
"""Each epoch transition refuses a state it was not written for."""
_ONE = str(UUID(int=1))
_TWO = str(UUID(int=2))
_THREE = str(UUID(int=3))
def _state(self, db_path: Path, committed, pending) -> None:
for suffix, token in (
(".rekey.epoch", committed),
(".rekey.pending", pending),
):
path = db_path.with_name(f"{db_path.name}{suffix}")
if token is None:
path.unlink(missing_ok=True)
else:
path.write_text(token, encoding="ascii")
def test_begin_refuses_without_a_committed_epoch(self, tmp_path: Path):
db_path = tmp_path / "user.db"
with pytest.raises(RekeyRecoveryRequiredError):
begin_rekey_epoch(db_path)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(None, None)
def test_begin_refuses_while_a_generation_is_pending(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._ONE, self._TWO)
with pytest.raises(RekeyRecoveryRequiredError):
begin_rekey_epoch(db_path)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._ONE, self._TWO
)
def test_commit_refuses_a_candidate_that_is_not_pending(
self, tmp_path: Path
):
db_path = tmp_path / "user.db"
self._state(db_path, self._ONE, self._TWO)
with pytest.raises(RekeyRecoveryRequiredError):
commit_rekey_epoch(db_path, self._THREE)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._ONE, self._TWO
)
def test_commit_refuses_without_a_pending_generation(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._ONE, None)
with pytest.raises(RekeyRecoveryRequiredError):
commit_rekey_epoch(db_path, self._TWO)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._ONE, None
)
def test_commit_refuses_a_non_canonical_candidate(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._ONE, self._TWO)
with pytest.raises(RekeyRecoveryRequiredError):
commit_rekey_epoch(db_path, self._TWO.replace("-", ""))
def test_clear_refuses_before_the_pending_generation_is_committed(
self, tmp_path: Path
):
db_path = tmp_path / "user.db"
self._state(db_path, self._ONE, self._TWO)
with pytest.raises(RekeyRecoveryRequiredError):
clear_pending_rekey_epoch(db_path, self._TWO)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._ONE, self._TWO
)
def test_clear_refuses_a_different_pending_generation(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._TWO, self._THREE)
with pytest.raises(RekeyRecoveryRequiredError):
clear_pending_rekey_epoch(db_path, self._TWO)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._TWO, self._THREE
)
def test_clear_is_idempotent_once_cleared(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._TWO, None)
clear_pending_rekey_epoch(db_path, self._TWO)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._TWO, None
)
def test_clear_removes_a_committed_pending_generation(self, tmp_path: Path):
db_path = tmp_path / "user.db"
self._state(db_path, self._TWO, self._TWO)
clear_pending_rekey_epoch(db_path, self._TWO)
assert read_rekey_epoch_state(db_path) == RekeyEpochState(
self._TWO, None
)
@pytest.mark.skipif(
os.name == "nt" or not hasattr(os, "link"),
reason="POSIX hard links required",
)
def test_hard_link_guard_cannot_identify_an_inode_after_its_other_name_is_removed(
tmp_path: Path,
) -> None:
"""Document the trusted-directory boundary: current names, not history."""
db_path = tmp_path / "user.db"
other_path = tmp_path / "other-user.db"
other_path.write_bytes(b"file whose original name will be removed")
lock_path = db_path.with_name(f"{db_path.name}.rekey.lock")
os.link(other_path, lock_path)
# Control: while the original name is present, the guard refuses it.
with pytest.raises(rekey_lock_module.RekeySidecarIOError) as refused:
with acquire_rekey_lock(db_path):
pytest.fail("a same-directory hard link was accepted")
assert refused.value.errno == errno.EMLINK
# Removing that name erases the evidence available to the guard. This
# is a documented limit, not protection against writers of the data dir.
other_path.unlink()
assert lock_path.stat().st_nlink == 1
with acquire_rekey_lock(db_path):
assert (
lock_path.read_bytes()
== b"file whose original name will be removed"
)