paskia 0.8.1__py3-none-any.whl → 0.9.1__py3-none-any.whl

paskia/db/jsonl.py

@@ -1,19 +1,24 @@
 """
 JSONL persistence layer for the database.
-
-Handles file I/O, JSON diffs, and persistence. Works with plain JSON/dict data.
-Uses aiofiles for async I/O operations.
 """
 
+import copy
 import logging
 from collections import deque
-from datetime import datetime, timezone
+from contextlib import contextmanager
+from datetime import UTC, datetime
 from pathlib import Path
+from typing import Any
+from uuid import UUID
 
 import aiofiles
 import jsondiff
 import msgspec
 
+from paskia.db.logging import log_change
+from paskia.db.migrations import DBVER, apply_all_migrations
+from paskia.db.structs import DB, SessionContext
+
 _logger = logging.getLogger(__name__)
 
 # Default database path
@@ -25,6 +30,7 @@ class _ChangeRecord(msgspec.Struct, omit_defaults=True):
 
     ts: datetime
     a: str  # action - describes the operation (e.g., "migrate", "login", "create_user")
+    v: int  # schema version after this change
     u: str | None = None  # user UUID who performed the action (None for system)
     diff: dict = {}
 
@@ -33,43 +39,6 @@ class _ChangeRecord(msgspec.Struct, omit_defaults=True):
 _change_encoder = msgspec.json.Encoder()
 
 
-async def load_jsonl(db_path: Path) -> dict:
-    """Load data from disk by applying change log.
-
-    Replays all changes from JSONL file using plain dicts (to handle
-    schema evolution).
-
-    Args:
-        db_path: Path to the JSONL database file
-
-    Returns:
-        The final state after applying all changes
-
-    Raises:
-        ValueError: If file doesn't exist or cannot be loaded
-    """
-    if not db_path.exists():
-        raise ValueError(f"Database file not found: {db_path}")
-    data_dict: dict = {}
-    try:
-        # Read entire file at once and split into lines
-        async with aiofiles.open(db_path, "rb") as f:
-            content = await f.read()
-        for line_num, line in enumerate(content.split(b"\n"), 1):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                change = msgspec.json.decode(line)
-                # Apply the diff to current state (marshal=True for $-prefixed keys)
-                data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
-            except Exception as e:
-                raise ValueError(f"Error parsing line {line_num}: {e}")
-    except (OSError, ValueError, msgspec.DecodeError) as e:
-        raise ValueError(f"Failed to load database: {e}")
-    return data_dict
-
-
 def compute_diff(previous: dict, current: dict) -> dict | None:
     """Compute JSON diff between two states.
 
@@ -85,17 +54,22 @@ def compute_diff(previous: dict, current: dict) -> dict | None:
 
 
 def create_change_record(
-    action: str, diff: dict, user: str | None = None
+    action: str, version: int, diff: dict, user: str | None = None
 ) -> _ChangeRecord:
     """Create a change record for persistence."""
     return _ChangeRecord(
-        ts=datetime.now(timezone.utc),
+        ts=datetime.now(UTC),
         a=action,
+        v=version,
         u=user,
         diff=diff,
     )
 
 
+# Actions that are allowed to create a new database file
+_BOOTSTRAP_ACTIONS = frozenset({"bootstrap", "migrate:sql"})
+
+
 async def flush_changes(
     db_path: Path,
     pending_changes: deque[_ChangeRecord],
@@ -112,15 +86,25 @@ async def flush_changes(
     if not pending_changes:
         return True
 
-    # Collect all pending changes
+    if not db_path.exists():
+        first_action = pending_changes[0].a
+        if first_action not in _BOOTSTRAP_ACTIONS:
+            _logger.error(
+                "Refusing to create database file with action '%s' - "
+                "only bootstrap or migrate can create a new database",
+                first_action,
+            )
+            pending_changes.clear()
+            return False
+
     changes_to_write = list(pending_changes)
     pending_changes.clear()
 
     try:
-        # Build lines to append (keep as bytes, join with \n)
         lines = [_change_encoder.encode(change) for change in changes_to_write]
+        if not lines:
+            return True
 
-        # Append all lines in a single write (binary mode for Windows compatibility)
         async with aiofiles.open(db_path, "ab") as f:
             await f.write(b"\n".join(lines) + b"\n")
         return True
@@ -130,3 +114,169 @@ async def flush_changes(
         for change in reversed(changes_to_write):
             pending_changes.appendleft(change)
         return False
+
+
+class JsonlStore:
+    """JSONL persistence layer for a DB instance."""
+
+    def __init__(self, db: DB, db_path: str = DB_PATH_DEFAULT):
+        self.db: DB = db
+        self.db_path = Path(db_path)
+        self._previous_builtins: dict[str, Any] = {}
+        self._pending_changes: deque[_ChangeRecord] = deque()
+        self._current_action: str = "system"
+        self._current_user: str | None = None
+        self._in_transaction: bool = False
+        self._transaction_snapshot: dict[str, Any] | None = None
+        self._current_version: int = DBVER  # Schema version for new databases
+
+    async def load(self, db_path: str | None = None) -> None:
+        """Load data from JSONL change log."""
+        if db_path is not None:
+            self.db_path = Path(db_path)
+        if not self.db_path.exists():
+            return
+
+        # Replay change log to reconstruct state
+        data_dict: dict = {}
+        try:
+            async with aiofiles.open(self.db_path, "rb") as f:
+                content = await f.read()
+            for line_num, line in enumerate(content.split(b"\n"), 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    change = msgspec.json.decode(line)
+                    data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
+                    self._current_version = change.get("v", 0)
+                except Exception as e:
+                    raise ValueError(f"Error parsing line {line_num}: {e}")
+        except (OSError, ValueError, msgspec.DecodeError) as e:
+            raise ValueError(f"Failed to load database: {e}")
+
+        if not data_dict:
+            return
+
+        # Set previous state for diffing (will be updated by _queue_change)
+        self._previous_builtins = copy.deepcopy(data_dict)
+
+        # Callback to persist each migration
+        async def persist_migration(
+            action: str, new_version: int, current: dict
+        ) -> None:
+            self._current_version = new_version
+            self._queue_change(action, new_version, current)
+
+        # Apply schema migrations one at a time
+        await apply_all_migrations(data_dict, self._current_version, persist_migration)
+
+        # Decode to msgspec struct
+        decoder = msgspec.json.Decoder(DB)
+        self.db = decoder.decode(msgspec.json.encode(data_dict))
+        self.db._store = self
+
+        # Normalize via msgspec round-trip (handles omit_defaults etc.)
+        # This ensures _previous_builtins matches what msgspec would produce
+        normalized_dict = msgspec.to_builtins(self.db)
+        await persist_migration(
+            "migrate:msgspec", self._current_version, normalized_dict
+        )
+
+    def _queue_change(
+        self, action: str, version: int, current: dict, user: str | None = None
+    ) -> None:
+        """Queue a change record and log it.
+
+        Args:
+            action: The action name for the change record
+            version: The schema version for the change record
+            current: The current state as a plain dict
+            user: Optional user UUID who performed the action
+        """
+        diff = compute_diff(self._previous_builtins, current)
+        if not diff:
+            return
+        self._pending_changes.append(create_change_record(action, version, diff, user))
+        self._previous_builtins = copy.deepcopy(current)
+
+        # Log the change with user display name if available
+        user_display = None
+        if user:
+            try:
+                user_uuid = UUID(user)
+                if user_uuid in self.db.users:
+                    user_display = self.db.users[user_uuid].display_name
+            except (ValueError, KeyError):
+                user_display = user
+
+        log_change(action, diff, user_display)
+
+    @contextmanager
+    def transaction(
+        self,
+        action: str,
+        ctx: SessionContext | None = None,
+        *,
+        user: str | None = None,
+    ):
+        """Wrap writes in transaction. Queues change on successful exit.
+
+        Args:
+            action: Describes the operation (e.g., "Created user", "Login")
+            ctx: Session context of user performing the action (None for system operations)
+            user: User UUID string (alternative to ctx when full context unavailable)
+        """
+        if self._in_transaction:
+            raise RuntimeError("Nested transactions are not supported")
+
+        # Check for out-of-transaction modifications
+        current_state = msgspec.to_builtins(self.db)
+        if current_state != self._previous_builtins:
+            # Allow bootstrap/migrate to create a new database from empty state
+            is_bootstrap = action in _BOOTSTRAP_ACTIONS or action.startswith("migrate:")
+            if is_bootstrap and not self._previous_builtins:
+                pass  # Expected: creating database from scratch
+            else:
+                diff = compute_diff(self._previous_builtins, current_state)
+                diff_json = msgspec.json.encode(diff).decode()
+                _logger.critical(
+                    "Database state modified outside of transaction! "
+                    "This indicates a bug where DB changes occurred without a transaction wrapper.\n"
+                    f"Changes detected:\n{diff_json}"
+                )
+                raise SystemExit(1)
+
+        old_action = self._current_action
+        old_user = self._current_user
+        self._current_action = action
+        # Prefer ctx.user.uuid if ctx provided, otherwise use user param
+        self._current_user = str(ctx.user.uuid) if ctx else user
+        self._in_transaction = True
+        self._transaction_snapshot = current_state
+
+        try:
+            yield
+            current = msgspec.to_builtins(self.db)
+            self._queue_change(
+                self._current_action, self._current_version, current, self._current_user
+            )
+        except Exception:
+            # Rollback on error: restore from snapshot
+            _logger.warning("Transaction '%s' failed, rolling back changes", action)
+            if self._transaction_snapshot is not None:
+                decoder = msgspec.json.Decoder(DB)
+                self.db = decoder.decode(
+                    msgspec.json.encode(self._transaction_snapshot)
+                )
+                self.db._store = self
+            raise
+        finally:
+            self._current_action = old_action
+            self._current_user = old_user
+            self._in_transaction = False
+            self._transaction_snapshot = None
+
+    async def flush(self) -> bool:
+        """Write all pending changes to disk."""
+        return await flush_changes(self.db_path, self._pending_changes)

paskia/db/logging.py

@@ -0,0 +1,233 @@
+"""
+Database change logging with pretty-printed diffs.
+
+Provides a logger for JSONL database changes that formats diffs
+in a human-readable path.notation style with color coding.
+"""
+
+import logging
+import re
+import sys
+from typing import Any
+
+logger = logging.getLogger("paskia.db")
+
+# Pattern to match control characters and bidirectional overrides
+_UNSAFE_CHARS = re.compile(
+    r"[\x00-\x1f\x7f-\x9f"  # C0 and C1 control characters
+    r"\u200e\u200f"  # LRM, RLM
+    r"\u202a-\u202e"  # LRE, RLE, PDF, LRO, RLO
+    r"\u2066-\u2069"  # LRI, RLI, FSI, PDI
+    r"]"
+)
+
+# ANSI color codes (matching FastAPI logging style)
+_RESET = "\033[0m"
+_DIM = "\033[2m"
+_PATH_PREFIX = "\033[1;30m"  # Dark grey for path prefix (like host in access log)
+_PATH_FINAL = "\033[0m"  # Default for final element (like path in access log)
+_REPLACE = "\033[0;33m"  # Yellow for replacements
+_DELETE = "\033[0;31m"  # Red for deletions
+_ADD = "\033[0;32m"  # Green for additions
+_ACTION = "\033[1;34m"  # Bold blue for action name
+_USER = "\033[0;34m"  # Blue for user display
+
+
+def _use_color() -> bool:
+    """Check if we should use color output."""
+    return sys.stderr.isatty()
+
+
+def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
+    """Format a value for display, truncating if needed."""
+    if value is None:
+        return "null"
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    if isinstance(value, (int, float)):
+        return str(value)
+
+    if isinstance(value, str):
+        # Filter out control characters and bidirectional overrides
+        value = _UNSAFE_CHARS.sub("", value)
+        # Truncate long strings
+        if len(value) > max_len:
+            return value[: max_len - 3] + "..."
+        return value
+
+    if isinstance(value, dict):
+        if not value:
+            return "{}"
+        # For small dicts, show inline
+        if len(value) == 1:
+            k, v = next(iter(value.items()))
+            return "{" + f"{k}: {_format_value(v, use_color, max_len=30)}" + "}"
+        return f"{{...{len(value)} keys}}"
+
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        if len(value) == 1:
+            return "[" + _format_value(value[0], use_color, max_len=30) + "]"
+        return f"[...{len(value)} items]"
+
+    # Fallback for other types
+    text = str(value)
+    if len(text) > max_len:
+        text = text[: max_len - 3] + "..."
+    return text
+
+
+def _format_path(path: list[str], use_color: bool) -> str:
+    """Format a path as dot notation with prefix in dark grey, final in default."""
+    if not path:
+        return ""
+    if not use_color:
+        return ".".join(path)
+    if len(path) == 1:
+        return f"{_PATH_FINAL}{path[0]}{_RESET}"
+    prefix = ".".join(path[:-1])
+    final = path[-1]
+    return f"{_PATH_PREFIX}{prefix}.{_RESET}{_PATH_FINAL}{final}{_RESET}"
+
+
+def _collect_changes(
+    diff: dict, path: list[str], changes: list[tuple[str, list[str], Any, Any | None]]
+) -> None:
+    """
+    Recursively collect changes from a diff into a flat list.
+
+    Each change is a tuple of (change_type, path, new_value, old_value).
+    change_type is one of: 'set', 'replace', 'delete'
+    """
+    if not isinstance(diff, dict):
+        # Leaf value - this is a set operation
+        changes.append(("set", path, diff, None))
+        return
+
+    for key, value in diff.items():
+        if key == "$delete":
+            # $delete contains a list of keys to delete
+            if isinstance(value, list):
+                for deleted_key in value:
+                    changes.append(("delete", path + [str(deleted_key)], None, None))
+            else:
+                changes.append(("delete", path + [str(value)], None, None))
+
+        elif key == "$replace":
+            # $replace contains the new value for this path
+            if isinstance(value, dict):
+                # Replacing with a dict - show each key as a replacement
+                for rkey, rval in value.items():
+                    changes.append(("replace", path + [str(rkey)], rval, None))
+                if not value:
+                    # Empty replacement - clearing the collection
+                    changes.append(("replace", path, {}, None))
+            else:
+                changes.append(("replace", path, value, None))
+
+        elif key.startswith("$"):
+            # Other special operations (future-proofing)
+            changes.append(("set", path, {key: value}, None))
+
+        else:
+            # Regular nested key
+            _collect_changes(value, path + [str(key)], changes)
+
+
+def _format_change_line(
+    change_type: str, path: list[str], value: Any, use_color: bool
+) -> str:
+    """Format a single change as a one-line string."""
+    path_str = _format_path(path, use_color)
+    value_str = _format_value(value, use_color)
+
+    if change_type == "delete":
+        if use_color:
+            return f"  ❌  {path_str}"
+        return f"  - {path_str}"
+
+    if change_type == "replace":
+        if use_color:
+            return f"  {_REPLACE}⟳{_RESET} {path_str} {_DIM}={_RESET} {value_str}"
+        return f"  ~ {path_str} = {value_str}"
+
+    # Default: set/add
+    if use_color:
+        return f"  {_ADD}+{_RESET} {path_str} {_DIM}={_RESET} {value_str}"
+    return f"  + {path_str} = {value_str}"
+
+
+def format_diff(diff: dict) -> list[str]:
+    """
+    Format a JSON diff as human-readable lines.
+
+    Returns a list of formatted lines (without newlines).
+    Single changes return one line, multiple changes return multiple lines.
+    """
+    use_color = _use_color()
+    changes: list[tuple[str, list[str], Any, Any | None]] = []
+    _collect_changes(diff, [], changes)
+
+    if not changes:
+        return []
+
+    # Format each change
+    lines = []
+    for change_type, path, value, _ in changes:
+        lines.append(_format_change_line(change_type, path, value, use_color))
+
+    return lines
+
+
+def format_action_header(action: str, user_display: str | None = None) -> str:
+    """Format the action header line."""
+    use_color = _use_color()
+
+    if use_color:
+        action_str = f"{_ACTION}{action}{_RESET}"
+        if user_display:
+            user_str = f"{_USER}{user_display}{_RESET}"
+            return f"{action_str} by {user_str}"
+        return action_str
+    else:
+        if user_display:
+            return f"{action} by {user_display}"
+        return action
+
+
+def log_change(action: str, diff: dict, user_display: str | None = None) -> None:
+    """
+    Log a database change with pretty-printed diff.
+
+    Args:
+        action: The action name (e.g., "login", "admin:delete_user")
+        diff: The JSON diff dict
+        user_display: Optional display name of the user who performed the action
+    """
+    header = format_action_header(action, user_display)
+    diff_lines = format_diff(diff)
+
+    if not diff_lines:
+        logger.info(header)
+        return
+
+    if len(diff_lines) == 1:
+        # Single change - combine on one line
+        logger.info(f"{header}{diff_lines[0]}")
+    else:
+        # Multiple changes - header on its own line, then changes
+        logger.info(header)
+        for line in diff_lines:
+            logger.info(line)
+
+
+def configure_db_logging() -> None:
+    """Configure the database logger to output to stderr without prefix."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False

paskia/db/migrations.py

@@ -0,0 +1,33 @@
+"""
+Database schema migrations.
+
+Migrations are applied during database load based on the version field.
+Each migration should be idempotent and only run when needed.
+"""
+
+from collections.abc import Awaitable, Callable
+
+
+def migrate_v1(d: dict) -> None:
+    """Remove Org.created_at fields."""
+    for org_data in d["orgs"].values():
+        org_data.pop("created_at", None)
+
+
+migrations = sorted(
+    [f for n, f in globals().items() if n.startswith("migrate_v")],
+    key=lambda f: int(f.__name__.removeprefix("migrate_v")),
+)
+
+DBVER = len(migrations)  # Used by bootstrap and migrate:sql to set initial version
+
+
+async def apply_all_migrations(
+    data_dict: dict,
+    current_version: int,
+    persist: Callable[[str, int, dict], Awaitable[None]],
+) -> None:
+    while current_version < DBVER:
+        migrations[current_version](data_dict)
+        current_version += 1
+        await persist(f"migrate:v{current_version}", current_version, data_dict)