kanta 0.1.0__py3-none-any.whl

kanta/__init__.py

@@ -0,0 +1,26 @@
+from .diff import compute_diff
+from .diff import replay_jsonl as replay
+from .exceptions import DatabaseError, DataIntegrityError, FileLockError, ReplayError
+from .filelock import LockedFile
+from .kanta import Kanta
+from .logging import configure_logging, format_diff, log_change
+from .serialization import JsonSerializer, MsgPackSerializer
+from .structs import ChangeRecord, Snapshot
+
+__all__ = [
+    "ChangeRecord",
+    "compute_diff",
+    "configure_logging",
+    "DataIntegrityError",
+    "DatabaseError",
+    "FileLockError",
+    "format_diff",
+    "JsonSerializer",
+    "Kanta",
+    "LockedFile",
+    "log_change",
+    "MsgPackSerializer",
+    "ReplayError",
+    "replay",
+    "Snapshot",
+]

kanta/diff.py

@@ -0,0 +1,81 @@
+"""Diff computation and replay utilities."""
+
+import jsondiff
+
+from kanta.kanta.structs import ChangeRecord
+from kanta.serialization.base import ReplayResult, replay
+from kanta.serialization.framing import LineFramer
+from kanta.serialization.json import JsonSerializer
+
+
+def compute_diff(previous: dict, current: dict) -> dict | None:
+    """Compute a jsondiff patch between two dicts.
+
+    Returns None if there is no difference.
+    """
+    return jsondiff.diff(previous, current, marshal=True) or None
+
+
+def _apply_diff(state: dict, diff: dict) -> dict:
+    """Apply a jsondiff patch manually, handling ``$replace`` and ``$delete``.
+
+    jsondiff.patch does not handle nested ``$replace`` commands when the
+    parent key is missing from the state.  This function recursively applies
+    diffs, treating ``$replace`` as full replacement and ``$delete`` as
+    key removal.
+    """
+    if not isinstance(diff, dict):
+        return diff
+
+    result = dict(state) if isinstance(state, dict) else state
+    if not isinstance(result, dict):
+        result = {}
+
+    for key, value in diff.items():
+        if key == "$replace":
+            return value
+        elif key == "$delete":
+            if isinstance(value, list):
+                for k in value:
+                    result.pop(k, None)
+            else:
+                result.pop(value, None)
+        elif isinstance(value, dict):
+            old = result.get(key, {})
+            if not isinstance(old, dict):
+                old = {}
+            result[key] = _apply_diff(old, value)
+        else:
+            result[key] = value
+
+    return result
+
+
+def patch_state(state: dict, diff: dict) -> dict:
+    """Apply a jsondiff patch to a state dict.
+
+    The diff was produced with ``marshal=True`` (string keys like
+    ``"$replace"`` and ``"$delete"``) and decoded from JSON.
+    """
+    return _apply_diff(state, diff)
+
+
+# Backward-compatible JSONL replay using the default serializer.
+_default_serializer = JsonSerializer()
+_default_framer = LineFramer()
+
+
+def replay_jsonl(
+    data: bytes,
+    *,
+    type: type[ChangeRecord] = ChangeRecord,
+) -> ReplayResult:
+    """Replay database state from JSONL file data.
+
+    This is the legacy public API that hard-codes JSON/JSONL handling.
+    """
+    return replay(
+        data,
+        framer=_default_framer,
+        decode=_default_serializer.decode,
+    )

kanta/exceptions.py

@@ -0,0 +1,61 @@
+"""Custom exception types for Kanta."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+class DatabaseError(ValueError):
+    """Exception raised for database loading errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        db_path: Path | None = None,
+        line_number: int | None = None,
+        byte_pos: int | None = None,
+        cause_type: str | None = None,
+    ):
+        self.db_path = db_path
+        self.line_number = line_number
+        self.byte_pos = byte_pos
+        self.cause_type = cause_type
+        super().__init__(message)
+
+
+class ReplayError(DatabaseError):
+    """Structured replay error with source location metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        line_number: int | None = None,
+        byte_pos: int | None = None,
+        record_type: str | None = None,
+    ):
+        self.record_type = record_type
+        super().__init__(message, line_number=line_number, byte_pos=byte_pos)
+
+
+class FileLockError(DatabaseError):
+    """Raised when database file open/lock operations fail."""
+
+
+class DataIntegrityError(RuntimeError):
+    """Raised when in-memory data integrity invariants are violated."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        db_path: Path | None = None,
+        action: str | None = None,
+        diff: dict[str, Any] | None = None,
+    ):
+        self.db_path = db_path
+        self.action = action
+        self.diff = diff
+        super().__init__(message)

kanta/filelock.py

@@ -0,0 +1,274 @@
+"""Cross-platform locked file for the database (no separate .lock files).
+
+Unix:    open() + fcntl.flock (advisory, cooperative among processes that flock).
+Windows: CreateFileW with FILE_SHARE_READ (OS-enforced, allows readers, blocks writers).
+
+A single file descriptor is opened once for both reading and writing.
+The lock is acquired atomically (on Windows) or immediately after open (on Unix),
+and the same descriptor is used for the lifetime of the process: first to read
+the existing content, then to append new writes.
+"""
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from kanta.exceptions import FileLockError
+
+_logger = logging.getLogger(__name__)
+
+
+def _fatal(msg: str, *, db_path: Path | None = None) -> None:
+    """Log a fatal error and raise a typed exception."""
+    _logger.critical(msg)
+    raise FileLockError(msg, db_path=db_path)
+
+
+if sys.platform == "win32":
+    import ctypes
+    from ctypes import wintypes
+
+    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+
+    _GENERIC_READ = 0x80000000
+    _GENERIC_WRITE = 0x40000000
+    _FILE_SHARE_READ = 0x00000001
+    _OPEN_EXISTING = 3
+    _OPEN_ALWAYS = 4
+    _FILE_ATTRIBUTE_NORMAL = 0x80
+    _FILE_BEGIN = 0
+    _FILE_END = 2
+    _ERROR_SHARING_VIOLATION = 32
+    _INVALID_FILE_SIZE = 0xFFFFFFFF
+
+    _kernel32.CreateFileW.restype = wintypes.HANDLE
+    _kernel32.CreateFileW.argtypes = [
+        wintypes.LPCWSTR,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.HANDLE,
+    ]
+    _kernel32.ReadFile.restype = wintypes.BOOL
+    _kernel32.ReadFile.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    ]
+    _kernel32.WriteFile.restype = wintypes.BOOL
+    _kernel32.WriteFile.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    ]
+    _kernel32.GetFileSize.restype = wintypes.DWORD
+    _kernel32.GetFileSize.argtypes = [
+        wintypes.HANDLE,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    _kernel32.SetFilePointer.restype = wintypes.DWORD
+    _kernel32.SetFilePointer.argtypes = [
+        wintypes.HANDLE,
+        wintypes.LONG,
+        ctypes.POINTER(wintypes.LONG),
+        wintypes.DWORD,
+    ]
+    _kernel32.CloseHandle.restype = wintypes.BOOL
+    _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+
+    def _is_invalid_handle(handle) -> bool:
+        return ctypes.c_void_p(handle).value == ctypes.c_void_p(-1).value
+
+else:
+    import fcntl
+
+
+class LockedFile:
+    """A file opened with an exclusive write lock.
+
+    Usage::
+
+        f = LockedFile()
+        f.open(path)          # open + lock (read+write)
+        content = f.read()    # read entire content
+        f.write(data)         # append data (seeks to end first)
+        f.close()             # release lock + close fd
+
+    Unix:    fcntl.flock (advisory) — read-only callers that don't flock are unaffected.
+    Windows: CreateFileW with FILE_SHARE_READ — OS blocks other writers.
+    """
+
+    def __init__(self) -> None:
+        self._fd: int | None = None  # Unix fd or Windows HANDLE
+
+    def open(self, path: Path, *, create: bool = False) -> None:
+        """Open *path* for read+write with an exclusive lock.
+
+        Args:
+            path:   File to open and lock.
+            create: If True, create the file if it doesn't exist (bootstrap).
+
+        Raises:
+            FileLockError: If the file is locked by another process or not found.
+        """
+        if self._fd is not None:
+            return  # Already open (idempotent)
+
+        if sys.platform == "win32":
+            self._open_win32(path, create)
+        else:
+            self._open_unix(path, create)
+
+    def open_and_read(self, path: Path, create: bool = False) -> bytes:
+        """Open *path* with exclusive lock and read all content.
+
+        Combined operation for efficient use with asyncio.to_thread().
+        """
+        self.open(path, create=create)
+        return self.read()
+
+    def read(self) -> bytes:
+        """Read the entire file content from the beginning."""
+        if self._fd is None:
+            raise RuntimeError("LockedFile.read() called on a closed file")
+
+        if sys.platform == "win32":
+            return self._read_win32()
+        else:
+            return self._read_unix()
+
+    def write(self, data: bytes) -> None:
+        """Append *data* to the end of the file."""
+        if self._fd is None:
+            raise RuntimeError("LockedFile.write() called on a closed file")
+
+        if sys.platform == "win32":
+            self._write_win32(data)
+        else:
+            self._write_unix(data)
+
+    def size(self) -> int:
+        """Return current file size in bytes."""
+        if self._fd is None:
+            raise RuntimeError("LockedFile.size() called on a closed file")
+
+        if sys.platform == "win32":
+            size = _kernel32.GetFileSize(self._fd, None)
+            if size == _INVALID_FILE_SIZE:
+                raise OSError(
+                    f"GetFileSize failed: Windows error {ctypes.get_last_error()}"
+                )
+            return int(size)
+
+        current = os.lseek(self._fd, 0, os.SEEK_CUR)
+        end = os.lseek(self._fd, 0, os.SEEK_END)
+        os.lseek(self._fd, current, os.SEEK_SET)
+        return end
+
+    def close(self) -> None:
+        """Release the lock and close the file."""
+        if self._fd is None:
+            return
+        if sys.platform == "win32":
+            _kernel32.CloseHandle(self._fd)
+        else:
+            os.close(self._fd)
+        self._fd = None
+
+    @property
+    def is_open(self) -> bool:
+        return self._fd is not None
+
+    # -- Unix ----------------------------------------------------------------
+
+    def _open_unix(self, path: Path, create: bool) -> None:
+        flags = os.O_RDWR | (os.O_CREAT if create else 0)
+        try:
+            fd = os.open(path, flags, 0o666)
+        except FileNotFoundError:
+            _fatal(f"Database file not found: {path.resolve()}", db_path=path)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            os.close(fd)
+            _fatal(
+                f"{path.resolve()}: database already locked by another instance",
+                db_path=path,
+            )
+        self._fd = fd
+
+    def _read_unix(self) -> bytes:
+        os.lseek(self._fd, 0, os.SEEK_SET)
+        chunks = []
+        while True:
+            chunk = os.read(self._fd, 1 << 20)  # 1 MiB
+            if not chunk:
+                break
+            chunks.append(chunk)
+        return b"".join(chunks)
+
+    def _write_unix(self, data: bytes) -> None:
+        os.lseek(self._fd, 0, os.SEEK_END)
+        os.write(self._fd, data)
+
+    # -- Windows -------------------------------------------------------------
+
+    def _open_win32(self, path: Path, create: bool) -> None:
+        disposition = _OPEN_ALWAYS if create else _OPEN_EXISTING
+        handle = _kernel32.CreateFileW(
+            str(path),
+            _GENERIC_READ | _GENERIC_WRITE,
+            _FILE_SHARE_READ,
+            None,
+            disposition,
+            _FILE_ATTRIBUTE_NORMAL,
+            None,
+        )
+        if _is_invalid_handle(handle):
+            err = ctypes.get_last_error()
+            if err == _ERROR_SHARING_VIOLATION:
+                _fatal(
+                    f"{path.resolve()}: database already locked by another instance",
+                    db_path=path,
+                )
+            _fatal(
+                f"Failed to open database {path.resolve()}: Windows error {err}",
+                db_path=path,
+            )
+        self._fd = handle
+
+    def _read_win32(self) -> bytes:
+        _kernel32.SetFilePointer(self._fd, 0, None, _FILE_BEGIN)
+        size = _kernel32.GetFileSize(self._fd, None)
+        if size == _INVALID_FILE_SIZE:
+            raise OSError(
+                f"GetFileSize failed: Windows error {ctypes.get_last_error()}"
+            )
+        if size == 0:
+            return b""
+        buf = ctypes.create_string_buffer(size)
+        bytes_read = wintypes.DWORD()
+        ok = _kernel32.ReadFile(self._fd, buf, size, ctypes.byref(bytes_read), None)
+        if not ok:
+            raise OSError(f"ReadFile failed: Windows error {ctypes.get_last_error()}")
+        return buf.raw[: bytes_read.value]
+
+    def _write_win32(self, data: bytes) -> None:
+        _kernel32.SetFilePointer(self._fd, 0, None, _FILE_END)
+        written = wintypes.DWORD()
+        ok = _kernel32.WriteFile(
+            self._fd,
+            data,
+            len(data),
+            ctypes.byref(written),
+            None,
+        )
+        if not ok:
+            raise OSError(f"WriteFile failed: Windows error {ctypes.get_last_error()}")

kanta/kanta.py

@@ -0,0 +1,206 @@
+"""JSONL persistence layer with background flush task."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Generic, TypeVar
+
+from kanta.exceptions import DatabaseError
+from kanta.kanta.kantaimpl import KantaImpl
+from kanta.serialization import JsonSerializer, Serializer
+from kanta.transaction import transaction as _transaction
+
+T = TypeVar("T")
+
+
+class Kanta(Generic[T]):
+    """JSONL persistence layer for a msgspec.Struct database state.
+
+    The application defines its schema as a msgspec.Struct (e.g. ``Data``,
+    ``Project``).  The Kanta instance holds the live state as that struct type.
+    Internally it round-trips through plain dicts for diffing, replay,
+    and serialization.
+
+    A background task periodically flushes pending changes to disk.
+    Call `await kanta.open()` to start the background task,
+    and `await kanta.close()` to stop it.
+
+    All transactions are synchronous — they immediately affect the
+    in-memory ``kanta.data``. Persistence happens asynchronously in
+    the background (or via explicit ``await kanta.flush()``).
+
+    Usage::
+
+        class Data(msgspec.Struct):
+            users: dict[str, User] = {}
+
+        kanta = Kanta("data.db", Data())
+        await kanta.open()
+
+        with kanta.transaction(action="create_user") as data:
+            data.users["alice"] = User(name="Alice")
+
+        await kanta.close()
+    """
+
+    def __init__(
+        self,
+        filename: Path | str,
+        data: T,
+        *,
+        type: type[T] | None = None,
+        migrations: ModuleType | str | None = None,
+        migration_ctx: Any | None = None,
+        serializer: Serializer | None = None,
+        fatal_error: Callable[[DatabaseError], None] | None = None,
+        flush_interval: float = 0.1,
+    ):
+        """Initialize a Kanta persistence instance.
+
+        Args:
+            filename: Path to the database file.
+            data: Caller-owned root msgspec.Struct state instance.
+            type: Optional explicit root type. Defaults to ``type(data)``.
+            migrations: Optional migrations module object or import path.
+            migration_ctx: Optional context object passed to migration functions.
+            flush_interval: Background flush interval in seconds.
+            serializer: Optional serializer implementation.
+            fatal_error: Optional callback invoked immediately when the
+                background writer encounters a DatabaseError.
+
+        Raises:
+            ImportError: If ``migrations`` is a string path that cannot be imported.
+            ValueError: If migration definitions are invalid.
+        """
+        active_serializer = serializer if serializer is not None else JsonSerializer()
+        data_type = type if type is not None else data.__class__
+
+        self._impl = KantaImpl(
+            serializer=active_serializer,
+            fatal_error=fatal_error,
+            filename=filename,
+            data=data,
+            type=data_type,
+            migrations=migrations,
+            migration_ctx=migration_ctx,
+            flush_interval=flush_interval,
+        )
+
+    @property
+    def data(self) -> T:
+        """Current in-memory state object.
+
+        Returns:
+            The live state instance of the configured ``type``.
+
+        Notes:
+            Mutations should only be performed via :meth:`transaction`
+            to ensure proper diffing and persistence.
+        """
+        return self._impl.data
+
+    @data.setter
+    def data(self, value: T) -> None:
+        """Replace the in-memory state object.
+
+        Notes:
+            Mutations should only be performed via :meth:`transaction`
+            to ensure proper diffing and persistence.
+
+        Args:
+            value: New state object instance.
+        """
+        self._impl.data = value
+
+    @property
+    def version(self) -> int:
+        """Current schema/database version.
+
+        Returns:
+            Integer version derived from migrations/replay state.
+        """
+        return self._impl.version
+
+    @property
+    def filename(self) -> Path:
+        """Database file path.
+
+        Returns:
+            Filesystem path used for persistence.
+        """
+        return self._impl.filename
+
+    async def open(self) -> None:
+        """Open the database file and start background persistence.
+
+        This loads existing records, applies configured migrations, and starts
+        the background flush task.
+
+        Calling ``open`` more than once on the same instance is not allowed.
+
+        Raises:
+            kanta.exceptions.DatabaseError: If replay or decoding fails.
+            kanta.exceptions.DataIntegrityError: If the instance is already open.
+        """
+        await self._impl.open()
+
+    async def __aenter__(self) -> Kanta[T]:
+        """Enter async context manager and open the database.
+
+        Returns:
+            The current ``Kanta`` instance itself.
+        """
+        await self.open()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        """Exit async context manager and close the database.
+
+        Args:
+            exc_type: Exception type raised inside the context, if any.
+            exc: Exception instance raised inside the context, if any.
+            tb: Traceback for the exception, if any.
+        """
+        await self.close()
+
+    async def flush(self) -> None:
+        """Asynchronously flush pending change records to disk."""
+        await self._impl.flush()
+
+    def request_snapshot(self) -> None:
+        """Request a snapshot to be written on the next background iteration."""
+        self._impl.snapshot.request_force()
+
+    async def close(self) -> None:
+        """Stop background task, flush pending changes, and close file lock."""
+        await self._impl.close()
+
+    def transaction(
+        self,
+        action: str,
+        *,
+        user: str | None = None,
+        user_display: str | None = None,
+        resolver: Any = None,
+    ):
+        """Create a transactional mutation context manager.
+
+        Args:
+            action: Action label stored in the change record.
+            user: Optional user identifier stored in metadata.
+            user_display: Optional display name used for logging/resolution.
+            resolver: Optional callable for resolving identifiers in logs.
+
+        Returns:
+            A context manager yielding the live state object for mutation.
+
+        Notes:
+            On successful exit, a diff is queued for persistence.
+            If an exception is raised inside the context, in-memory changes are
+            rolled back.
+        """
+        return _transaction(
+            self._impl, action, user=user, user_display=user_display, resolver=resolver
+        )