sg-event-daemon 0.1.0__py3-none-any.whl

sg_event_daemon/__init__.py

@@ -0,0 +1,9 @@
+"""Package the sg-event-daemon service and its supported import paths.
+
+Run the foreground service and operator commands through the `sg-event-daemon`
+console script or `python -m sg_event_daemon`. Use `sg_event_daemon.testing` to
+load and drive trusted plugins with synthetic events offline. The package root
+exports no public names.
+"""
+
+__all__: list[str] = []

sg_event_daemon/__main__.py

@@ -0,0 +1,8 @@
+"""Run the shared command shell with `python -m sg_event_daemon`."""
+
+import sys
+
+from sg_event_daemon._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

sg_event_daemon/_checkpoint.py

@@ -0,0 +1,236 @@
+"""Classify passive WAL checkpoints and enforce their runtime bounds."""
+
+from __future__ import annotations
+
+import math
+import random
+import sqlite3
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, TypeAlias, TypedDict, Unpack
+
+from sg_event_daemon._sqlite import DatabaseError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+CheckpointOutcome: TypeAlias = Literal[
+    'complete',
+    'reset-observed',
+    'contended',
+    'partial-no-progress',
+    'partial-progress',
+]
+CheckpointResult: TypeAlias = tuple[int, int, int]
+CheckpointState: TypeAlias = Literal['idle', 'complete', 'incomplete']
+
+_WAL_IN_USE_LIMIT_BYTES = 256 * 1024 * 1024
+_CHECKPOINT_FAILURE_INTERVALS = 5
+_CLEARING_OUTCOMES: frozenset[CheckpointOutcome] = frozenset({'complete', 'reset-observed'})
+_RECENT_ATTEMPTS = 8
+_WAL_FRAME_HEADER_BYTES = 24
+
+
+@dataclass(frozen=True)
+class CheckpointAttempt:
+    """Record one classified passive checkpoint attempt.
+
+    Attributes:
+        outcome: Classification under the checkpoint policy.
+        result: The `(busy, log, checkpointed)` row of the final try, which is
+            the retry's row when the first try was contended.
+        retried: Whether the first try was contended and retried.
+        finished_at: Monotonic time when the attempt was classified.
+    """
+
+    outcome: CheckpointOutcome
+    result: CheckpointResult
+    retried: bool
+    finished_at: float
+
+
+class CheckpointBoundError(DatabaseError):
+    """Report a runtime bound violation with its classified checkpoint attempt.
+
+    Attributes:
+        attempt: The observed attempt that triggered the bound.
+    """
+
+    def __init__(self, message: str, attempt: CheckpointAttempt) -> None:
+        """Retain the classified attempt alongside the diagnostic message."""
+        super().__init__(message)
+        self.attempt = attempt
+
+
+class _CheckpointerSeams(TypedDict, total=False):
+    """Type optional clock, randomness, result, sleep, and bound replacements for tests."""
+
+    clock: Callable[[], float]
+    random_value: Callable[[], float]
+    run_checkpoint: Callable[[], CheckpointResult]
+    sleep: Callable[[float], None]
+    wal_limit_bytes: int
+
+
+class Checkpointer:
+    """Run one process's passive checkpoints on one database file.
+
+    Each `run_once()` call makes one attempt; a contended first try is retried
+    once after a random delay of up to half an interval. Attempts are
+    classified as complete, reset observed, contended, or partial with or
+    without progress.
+    The checkpointer halts by raising `DatabaseError` when no complete or
+    reset-observed attempt has occurred for five intervals, measured from the
+    last such attempt or from construction, or when a non-contended attempt
+    reports more committed WAL frames than `_WAL_IN_USE_LIMIT_BYTES` occupy.
+    That limit is a tripwire on observed committed frames, not a ceiling on the
+    WAL file's size. Use it only from the thread that opened its connection.
+    """
+
+    def __init__(
+        self,
+        connection: sqlite3.Connection,
+        path: Path,
+        *,
+        interval_secs: float,
+        **seams: Unpack[_CheckpointerSeams],
+    ) -> None:
+        """Prepare a checkpointer for an open WAL connection.
+
+        Args:
+            connection: Connection dedicated to checkpoints on this file.
+            path: Database path named in halt messages.
+            interval_secs: Scheduled time between attempts; the duration bound
+                and the retry delay derive from it.
+            **seams: Optional replacements for tests.
+
+        Raises:
+            ValueError: `interval_secs` is not finite and positive, or
+                `wal_limit_bytes` is not positive.
+            DatabaseError: SQLite cannot report the page size.
+        """
+        if not math.isfinite(interval_secs) or interval_secs <= 0:
+            raise ValueError('checkpoint interval must be finite and positive')
+        wal_limit_bytes = seams.get('wal_limit_bytes', _WAL_IN_USE_LIMIT_BYTES)
+        if wal_limit_bytes <= 0:
+            raise ValueError('WAL limit must be positive')
+        self._connection = connection
+        self._path = path
+        self._interval_secs = interval_secs
+        self._clock = seams.get('clock', time.monotonic)
+        self._random_value = seams.get('random_value', random.random)
+        self._sleep = seams.get('sleep', time.sleep)
+        self._run_checkpoint = seams.get('run_checkpoint', self._passive_checkpoint)
+        self._wal_limit_bytes = wal_limit_bytes
+        self._frame_bytes = _page_size(connection) + _WAL_FRAME_HEADER_BYTES
+        self._cleared_at = self._clock()
+        self._previous_log: int | None = None
+        self._previous_checkpointed: int | None = None
+        self._recent: deque[CheckpointAttempt] = deque(maxlen=_RECENT_ATTEMPTS)
+        self._state: CheckpointState = 'idle'
+
+    def _classify(self, result: CheckpointResult) -> CheckpointOutcome:
+        """Classify one final try against this checkpointer's previous sample."""
+        busy, log_frames, checkpointed = result
+        if busy != 0:
+            return 'contended'
+        if checkpointed >= log_frames:
+            return 'complete'
+        if self._previous_log is not None and log_frames < self._previous_log:
+            return 'reset-observed'
+        if self._previous_checkpointed is not None and checkpointed == self._previous_checkpointed:
+            return 'partial-no-progress'
+        return 'partial-progress'
+
+    def _halt(self, bound: str, detail: str) -> CheckpointBoundError:
+        """Build the halt error naming the file, the bound, and the recent attempts."""
+        elapsed = self._clock() - self._cleared_at
+        recent = ', '.join(f'{attempt.outcome} {attempt.result}' for attempt in self._recent)
+        return CheckpointBoundError(
+            f'checkpoint {bound} bound exceeded for {self._path}: {detail}; '
+            f'{elapsed:.3f}s since the last complete or reset-observed attempt; '
+            f'recent attempts: {recent}',
+            self._recent[-1],
+        )
+
+    def _passive_checkpoint(self) -> CheckpointResult:
+        """Run one passive checkpoint on the owned connection."""
+        try:
+            row = self._connection.execute('PRAGMA wal_checkpoint(PASSIVE)').fetchone()
+        except sqlite3.Error as exc:
+            raise DatabaseError(str(exc)) from exc
+        if row is None:
+            raise DatabaseError('SQLite returned no passive checkpoint result')
+        busy, log_frames, checkpointed = (int(value) for value in row)
+        return busy, log_frames, checkpointed
+
+    def _record(self, attempt: CheckpointAttempt) -> None:
+        """Update this checkpointer's history and raise when a bound is exceeded."""
+        self._recent.append(attempt)
+        cleared = attempt.outcome in _CLEARING_OUTCOMES
+        self._state = 'complete' if cleared else 'incomplete'
+        if cleared:
+            self._cleared_at = attempt.finished_at
+        _busy, log_frames, checkpointed = attempt.result
+        if attempt.outcome != 'contended':
+            self._previous_log = log_frames
+            self._previous_checkpointed = checkpointed
+            if log_frames * self._frame_bytes > self._wal_limit_bytes:
+                raise self._halt(
+                    'WAL growth',
+                    f'{log_frames} committed frames exceed {self._wal_limit_bytes} bytes',
+                )
+        incomplete_secs = attempt.finished_at - self._cleared_at
+        if incomplete_secs >= _CHECKPOINT_FAILURE_INTERVALS * self._interval_secs:
+            raise self._halt(
+                'incomplete duration',
+                f'{_CHECKPOINT_FAILURE_INTERVALS} intervals of {self._interval_secs}s elapsed',
+            )
+
+    @property
+    def frame_bytes(self) -> int:
+        """Return the bytes one WAL frame occupies: the page size plus its header."""
+        return self._frame_bytes
+
+    def run_once(self) -> CheckpointAttempt:
+        """Make one checkpoint attempt and enforce both bounds.
+
+        Returns:
+            The classified attempt.
+
+        Raises:
+            CheckpointBoundError: The classified attempt exceeded the
+                incomplete-duration bound or the WAL growth tripwire.
+            DatabaseError: SQLite failed before an attempt could be classified.
+        """
+        result = self._run_checkpoint()
+        retried = result[0] != 0
+        if retried:
+            self._sleep(self._random_value() * self._interval_secs / 2)
+            result = self._run_checkpoint()
+        attempt = CheckpointAttempt(
+            outcome=self._classify(result),
+            result=result,
+            retried=retried,
+            finished_at=self._clock(),
+        )
+        self._record(attempt)
+        return attempt
+
+    @property
+    def state(self) -> CheckpointState:
+        """Return `idle` before the first attempt, then `complete` or `incomplete`."""
+        return self._state
+
+
+def _page_size(connection: sqlite3.Connection) -> int:
+    """Return the database page size that sizes each WAL frame."""
+    try:
+        row = connection.execute('PRAGMA page_size').fetchone()
+    except sqlite3.Error as exc:
+        raise DatabaseError(str(exc)) from exc
+    if row is None:
+        raise DatabaseError('SQLite returned no page size')
+    return int(row[0])

sg_event_daemon/_checkpoint_host.py

@@ -0,0 +1,226 @@
+"""Own independently timed checkpoint connections for each process-local file."""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from typing import TYPE_CHECKING, TypedDict, Unpack
+
+from ._checkpoint import Checkpointer, CheckpointState
+from ._resources import close_resources
+from ._sqlite import Schema, open_database
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+    from types import TracebackType
+    from typing import Self
+
+
+class _CheckpointFailure:
+    """Report ordinary failures at the checkpoint thread ownership boundary."""
+
+    def __init__(self, identity: str, on_failure: Callable[[str], None]) -> None:
+        """Bind one file identity to the owning worker's fatal callback."""
+        self._identity = identity
+        self._on_failure = on_failure
+
+    def __enter__(self) -> Self:
+        """Enter the checkpoint thread's failure boundary."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        """Report ordinary errors once while propagating process-control errors."""
+        if not isinstance(exc_value, Exception):
+            return False
+        self._on_failure(
+            f'checkpoint:{self._identity} thread failed: {type(exc_value).__name__}: {exc_value}'
+        )
+        return True
+
+
+class _CheckpointStatus(TypedDict):
+    """Share a lock and the latest state between the owner and its views."""
+
+    lock: threading.Lock
+    state: CheckpointState
+
+
+class CheckpointHostStoppedError(RuntimeError):
+    """Report registration interrupted by the host's shutdown request."""
+
+
+class CheckpointView:
+    """Provide a thread-safe read-only view of one file's checkpoint state."""
+
+    def __init__(self, status: _CheckpointStatus | None = None) -> None:
+        """Share a host-owned state cell, or represent an unregistered idle file."""
+        self._status: _CheckpointStatus = (
+            status if status is not None else {'lock': threading.Lock(), 'state': 'idle'}
+        )
+
+    def state(self) -> CheckpointState:
+        """Return idle before the first attempt, then complete or incomplete."""
+        with self._status['lock']:
+            return self._status['state']
+
+
+class _CheckpointHostSeams(TypedDict, total=False):
+    """Type the optional monotonic clock and checkpointer factory replacements."""
+
+    clock: Callable[[], float]
+    checkpointer_factory: Callable[..., Checkpointer]
+
+
+class _CheckpointFile(TypedDict):
+    """Hold one file's thread inputs and synchronized health output."""
+
+    path: Path
+    identity: str
+    schema: Schema
+    first_due: float
+    status: _CheckpointStatus
+
+
+class CheckpointHost:
+    """Own one daemon checkpoint thread per resolved database path.
+
+    Register files after their owner initializes them. Each checkpoint thread
+    opens and closes its own existing-only connection. `close()` interrupts
+    timer waits and joins all threads; registration after close is rejected.
+    """
+
+    def __init__(
+        self,
+        *,
+        interval_secs: float,
+        synchronous: str,
+        on_failure: Callable[[str], None],
+        **seams: Unpack[_CheckpointHostSeams],
+    ) -> None:
+        """Configure independent file timers and the fatal-failure callback.
+
+        Args:
+            interval_secs: Finite positive time between checkpoint attempts.
+            synchronous: SQLite synchronous policy for each owned connection.
+            on_failure: Called once when a file's checkpoint thread fails.
+            **seams: Optional monotonic clock and checkpointer factory.
+
+        Raises:
+            ValueError: `interval_secs` is not finite and positive.
+        """
+        if not math.isfinite(interval_secs) or interval_secs <= 0:
+            raise ValueError('checkpoint interval must be finite and positive')
+        self._interval_secs = interval_secs
+        self._synchronous = synchronous
+        self._on_failure = on_failure
+        self._clock = seams.get('clock', time.monotonic)
+        self._checkpointer_factory = seams.get('checkpointer_factory', Checkpointer)
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._files: dict[Path, tuple[CheckpointView, threading.Thread]] = {}
+
+    def _run(self, file: _CheckpointFile) -> None:
+        """Open, checkpoint, and close one file entirely on its owning thread."""
+        with _CheckpointFailure(file['identity'], self._on_failure):
+            database = open_database(
+                file['path'],
+                file['identity'],
+                file['schema'],
+                synchronous=self._synchronous,
+                create=False,
+            )
+            try:
+                checkpointer = self._checkpointer_factory(
+                    database.connection,
+                    file['path'],
+                    interval_secs=self._interval_secs,
+                )
+                due = file['first_due']
+                while not self._stop.wait(max(0.0, due - self._clock())):
+                    try:
+                        checkpointer.run_once()
+                    finally:
+                        with file['status']['lock']:
+                            file['status']['state'] = checkpointer.state
+                    elapsed = max(0.0, self._clock() - due)
+                    due += (int(elapsed // self._interval_secs) + 1) * self._interval_secs
+            except BaseException as error:
+                close_resources((database,), primary_error=error)
+                raise
+            else:
+                database.close()
+
+    def register(self, path: Path, identity: str, schema: Schema) -> CheckpointView:
+        """Start one timer for an initialized file, reusing resolved-path views.
+
+        The first attempt waits one interval plus this registration's
+        `interval * index / count` offset. Later registrations do not change
+        existing timers.
+
+        Args:
+            path: Initialized database path; registration uses its resolved
+                path.
+            identity: Stable identity matching the database's stored identity.
+                A mismatch fails asynchronously through `on_failure`.
+            schema: Database schema used when the checkpoint thread opens it.
+
+        Returns:
+            The checkpoint view for the resolved path. Re-registration returns
+            the existing view and ignores the new `identity` and `schema`.
+
+        Raises:
+            CheckpointHostStoppedError: This host is stopping or closed.
+        """
+        path = path.resolve()
+        with self._lock:
+            if self._stop.is_set():
+                raise CheckpointHostStoppedError('checkpoint host is stopping or closed')
+            existing = self._files.get(path)
+            if existing is not None:
+                return existing[0]
+            index = len(self._files)
+            first_due = self._clock() + self._interval_secs * (1 + index / (index + 1))
+            file = _CheckpointFile(
+                path=path,
+                identity=identity,
+                schema=schema,
+                first_due=first_due,
+                status={'lock': threading.Lock(), 'state': 'idle'},
+            )
+            view = CheckpointView(file['status'])
+            thread = threading.Thread(
+                target=self._run,
+                args=(file,),
+                daemon=True,
+                name=f'sg-event-daemon:checkpoint:{identity}',
+            )
+            thread.start()
+            self._files[path] = view, thread
+            return view
+
+    def request_stop(self) -> None:
+        """Interrupt schedule waits and reject new registrations without joining."""
+        self._stop.set()
+
+    def threads(self) -> tuple[threading.Thread, ...]:
+        """Return a stable snapshot of started owners for monitored, bounded joins.
+
+        Each thread owns its database connection through final cleanup. A
+        stopped thread therefore has no remaining connection work.
+        """
+        with self._lock:
+            return tuple(thread for _view, thread in self._files.values())
+
+    def close(self) -> None:
+        """Interrupt timer waits and join threads after their connections close."""
+        self.request_stop()
+        for thread in self.threads():
+            if thread is not threading.current_thread():
+                thread.join()