Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

13.5 KB
Raw Blame
from __future__ import annotations

import logging
import os
import threading
import time
from pathlib import Path
from types import TracebackType
from typing import Callable, IO, Literal, Optional, Type


logger = logging.getLogger(__name__)

#: How long a blocked acquire waits before it starts saying so. A migration that
#: takes minutes is legitimate, and the process waiting behind it looks hung from
#: the outside; naming the holder is what turns that into a diagnosable wait.
_WAIT_LOG_INTERVAL_SECONDS = 15.0


class MigrationLockTimeout(TimeoutError):
    pass


def migration_lock_path_for(db_path: Path) -> Path:
    """The lock guarding migrations of one SQLite state database.

    Derived from the database rather than from the state directory, and stated
    once here, because the thing being protected is that file: two callers that
    disagree about which directory is "the" state directory would otherwise
    take two different locks over one database and both proceed.
    """

    return db_path.expanduser().resolve().with_name("migration.lock")


class _PathLockState:
    """The one in-process owner of a lock path.

    The OS lock alone cannot express re-entrance. ``fcntl.flock`` attaches to an
    open file description, so a second ``open`` of the same path -- which is what
    a nested acquire does -- is a *different* description and blocks against the
    first, in the very thread that holds it. That is a self-deadlock, and it is
    reachable from ordinary nesting: ``ensure_sqlite_state`` holds the migration
    lock across the call to ``run_migrations``, which takes it too.

    Holding the depth here rather than on the lock object is what makes
    re-entrance a property of the path instead of one caller's instance. Nested
    callers do not share objects; they only share the file they are protecting.
    """

    def __init__(self) -> None:
        self.gate = threading.RLock()
        self.depth = 0
        self.handle = None
        self.users = 0


_registry_lock = threading.Lock()
_states: dict[str, _PathLockState] = {}


def _state_key(lock_path: Path) -> str:
    return os.path.normcase(os.path.realpath(os.fspath(lock_path)))


def _checkout_state(key: str) -> _PathLockState:
    with _registry_lock:
        state = _states.get(key)
        if state is None:
            state = _PathLockState()
            _states[key] = state
        state.users += 1
        return state


def _return_state(key: str) -> None:
    with _registry_lock:
        state = _states.get(key)
        if state is None:
            return
        state.users -= 1
        if state.users <= 0:
            _states.pop(key, None)


class MigrationFileLock:
    """A cross-process lock for one path, re-entrant within a thread.

    Two guarantees, needed together by the same callers: at most one process on
    the machine holds the path, and at most one thread inside each process holds
    it -- while a thread that already holds it may take it again.

    The second guarantee makes this thread-owned, so the thread that acquires is
    the thread that releases. Re-entrance is what forces that: a lock that any
    thread may hand to any other has no holder to compare a nested acquire
    against. A caller that waits on one thread and works on another must keep
    the whole acquire-release pair on the waiting thread.

    ``timeout_seconds`` bounds the whole acquire, gate and file lock together.
    ``0`` makes it a try-lock that never blocks. ``None`` waits indefinitely,
    which is the right answer whenever the work behind the lock has no upper
    bound: the OS drops a file lock when its holder dies, so the only way to
    wait forever is for a live process to still be working.

    Security-sensitive callers may supply the private opener and validator so
    the same no-follow descriptor is checked before and after acquisition.
    Default callers retain the ordinary append-open behavior.
    """

    def __init__(
        self,
        lock_path: Path,
        *,
        timeout_seconds: float | None = 30.0,
        _handle_opener: Callable[[Path], IO[str]] | None = None,
        _handle_validator: Callable[[IO[str]], bool] | None = None,
    ):
        self.lock_path = lock_path
        self.timeout_seconds = timeout_seconds
        self._handle_opener = _handle_opener
        self._handle_validator = _handle_validator
        self._key = _state_key(self.lock_path)
        self._state: _PathLockState | None = None
        self._entries = 0
        # A small number of security-sensitive callers open and validate the
        # descriptor themselves before taking the advisory lock. They still
        # need MigrationFileLock to own the unlock/close lifecycle afterward.
        self._adopted_handle: IO[str] | None = None

    def adopt_locked_handle(self, handle: IO[str]) -> None:
        """Transfer an already-locked descriptor into this lock's ownership.

        The caller remains responsible for acquiring and validating the OS
        lock. Once adopted, ``release()`` performs the matching unlock and
        closes the descriptor, just like a normal ``acquire()`` path.
        """
        if self._state is not None or self._entries:
            raise RuntimeError("cannot adopt a handle while the lock is acquired")
        if self._adopted_handle is not None:
            raise RuntimeError("a locked handle is already adopted")
        self._adopted_handle = handle

    def acquire(self) -> None:
        deadline = None if self.timeout_seconds is None else time.monotonic() + self.timeout_seconds
        state = _checkout_state(self._key)
        if not _acquire_gate(state.gate, deadline):
            _return_state(self._key)
            raise MigrationLockTimeout(f"Timed out waiting for migration lock: {self.lock_path}")
        try:
            if state.depth == 0:
                state.handle = _acquire_file_lock(
                    self.lock_path,
                    deadline,
                    handle_opener=self._handle_opener,
                    handle_validator=self._handle_validator,
                )
            elif self._handle_validator is not None and (
                state.handle is None or not self._handle_validator(state.handle)
            ):
                raise OSError(f"Lock path failed identity validation: {self.lock_path}")
        except BaseException:
            state.gate.release()
            _return_state(self._key)
            raise
        state.depth += 1
        self._state = state
        self._entries += 1

    def release(self) -> None:
        state = self._state
        if state is None or self._entries == 0:
            handle = self._adopted_handle
            if handle is not None:
                self._adopted_handle = None
                _release_file_lock(handle)
            return
        self._entries -= 1
        if self._entries == 0:
            self._state = None
        state.depth -= 1
        try:
            if state.depth == 0 and state.handle is not None:
                handle, state.handle = state.handle, None
                _release_file_lock(handle)
        finally:
            state.gate.release()
            _return_state(self._key)

    def __enter__(self) -> "MigrationFileLock":
        self.acquire()
        return self

    def __exit__(
        self,
        _exc_type: Optional[Type[BaseException]],
        _exc: Optional[BaseException],
        _tb: Optional[TracebackType],
    ) -> None:
        self.release()


def _acquire_gate(gate, deadline: float | None) -> bool:
    if deadline is None:
        gate.acquire()
        return True
    remaining = deadline - time.monotonic()
    if remaining <= 0:
        # Still one real attempt: a zero timeout is a try-lock, not a refusal,
        # and a thread already holding the gate re-enters it here.
        return gate.acquire(blocking=False)
    return gate.acquire(timeout=remaining)


def _acquire_file_lock(
    lock_path: Path,
    deadline: float | None,
    *,
    handle_opener: Callable[[Path], IO[str]] | None = None,
    handle_validator: Callable[[IO[str]], bool] | None = None,
):
    lock_path.parent.mkdir(parents=True, exist_ok=True)
    handle = handle_opener(lock_path) if handle_opener is not None else open(lock_path, "a+", encoding="utf-8")
    next_log = time.monotonic() + _WAIT_LOG_INTERVAL_SECONDS
    locked = False
    try:
        if handle_validator is not None and not handle_validator(handle):
            raise OSError(f"Lock path failed identity validation: {lock_path}")
        while True:
            # Every attempt locks the same byte. Windows locks a range starting at
            # the current position, and both the append-mode open and the read below
            # leave it at the end of the file, so seeking is what keeps two waiters
            # contending for one byte instead of two disjoint ones.
            handle.seek(0)
            if _try_lock(handle):
                locked = True
                if handle_validator is not None and not handle_validator(handle):
                    raise OSError(f"Lock path failed identity validation after acquisition: {lock_path}")
                handle.seek(0)
                handle.truncate()
                handle.write(str(os.getpid()))
                handle.flush()
                return handle
            now = time.monotonic()
            if deadline is not None and now >= deadline:
                raise MigrationLockTimeout(f"Timed out waiting for migration lock: {lock_path}")
            if now >= next_log:
                next_log = now + _WAIT_LOG_INTERVAL_SECONDS
                logger.info(
                    "Waiting for the migration lock at %s, held by pid %s",
                    lock_path,
                    _recorded_holder(handle),
                )
            time.sleep(0.1)
    except BaseException:
        if locked:
            _release_file_lock(handle)
        else:
            handle.close()
        raise


def _release_file_lock(handle) -> None:
    try:
        _unlock(handle)
    finally:
        handle.close()


def _recorded_holder(handle) -> str:
    """Whoever last wrote the lock file, for the waiting message only.

    Advisory: a holder writes its pid just after taking the lock, so a reader
    can catch the previous holder's pid for an instant. Nothing decides anything
    on this value.
    """

    try:
        handle.seek(0)
        return handle.read().strip() or "unknown"
    except OSError:
        return "unknown"


def _try_lock(handle) -> bool:
    if os.name == "nt":
        import msvcrt

        try:
            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
            return True
        except OSError:
            return False

    import fcntl

    try:
        fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
        return True
    except BlockingIOError:
        return False


def _unlock(handle) -> None:
    if os.name == "nt":
        import msvcrt

        handle.seek(0)
        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
        return

    import fcntl

    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)


#: What a look at another process's lock established, without creating or keeping
#: it: a live handle holds it, nothing does, there is no file, or the look failed.
LockHolderState = Literal["held", "free", "missing", "unknown"]


def probe_lock_holder(lock_path: Path) -> LockHolderState:
    """Whether a live handle holds the lock at ``lock_path``, leaving the path as found.

    The OS drops a lock when its holding process ends, however it ends, so ``free``
    is evidence that the holder is gone. The path is never created: a lock that is
    not there names no holder either way, so ``missing`` and ``unknown`` are
    reported rather than guessed. Windows answers a failed attempt the same way as
    a held lock, so there an inspection error reads as ``held``, never ``free``.
    """

    try:
        handle = open(lock_path, "r+", encoding="utf-8")
    except FileNotFoundError:
        return "missing"
    except OSError:
        return "unknown"
    try:
        handle.seek(0)
        if not _try_lock(handle):
            return "held"
        _unlock(handle)
        return "free"
    except OSError:
        return "unknown"
    finally:
        handle.close()


def remove_unheld_lock(lock_path: Path) -> bool:
    """Delete ``lock_path`` while holding its lock, when no live handle holds it.

    Only for a lock that no later claimant will take again. Unlinking under our own
    lock then cannot split two claimants across an old and a new inode. Best effort:
    Windows refuses to delete an open file, which leaves the file in place.
    """

    try:
        handle = open(lock_path, "r+", encoding="utf-8")
    except OSError:
        return False
    try:
        handle.seek(0)
        if not _try_lock(handle):
            return False
        try:
            lock_path.unlink()
            return True
        except OSError:
            return False
        finally:
            _unlock(handle)
    except OSError:
        return False
    finally:
        handle.close()


def fcntl_available() -> bool:
    try:
        import fcntl  # noqa: F401
    except ImportError:
        return False
    return True


def try_windows_exclusive_lock(fd: int) -> bool:
    """Non-blocking exclusive probe on an already-open Windows lock fd."""
    try:
        import msvcrt
    except ImportError:
        return False
    try:
        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
    except OSError:
        return False
    return True


def unlock_windows_exclusive_lock(fd: int) -> None:
    try:
        import msvcrt
    except ImportError:
        return
    try:
        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
    except OSError:
        pass