paskia 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

paskia/db/jsonl.py

@@ -1,19 +1,27 @@
 """
 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.
 """
 
+from __future__ import annotations
+
+import copy
+import json
 import logging
+import sys
 from collections import deque
+from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
+from uuid import UUID
 
 import aiofiles
 import jsondiff
 import msgspec
 
+from paskia.db.migrations import apply_migrations
+from paskia.db.structs import DB, SessionContext
+
 _logger = logging.getLogger(__name__)
 
 # Default database path
@@ -96,6 +104,10 @@ def create_change_record(
     )
 
 
+# Actions that are allowed to create a new database file
+_BOOTSTRAP_ACTIONS = frozenset({"bootstrap", "migrate"})
+
+
 async def flush_changes(
     db_path: Path,
     pending_changes: deque[_ChangeRecord],
@@ -112,15 +124,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 +152,143 @@ 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
+
+    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)
+        try:
+            data_dict = await load_jsonl(self.db_path)
+            if data_dict:
+                # Preserve original state before migrations (deep copy for nested dicts)
+                original_dict = copy.deepcopy(data_dict)
+
+                # Apply schema migrations (modifies data_dict in place)
+                migrated = apply_migrations(data_dict)
+
+                decoder = msgspec.json.Decoder(DB)
+                self.db = decoder.decode(msgspec.json.encode(data_dict))
+                self.db._store = self
+
+                # Update previous state to migrated data FIRST (to avoid transaction hardening reset)
+                self._previous_builtins = data_dict
+
+                # Persist migration by manually computing and queueing the diff
+                if migrated:
+                    diff = compute_diff(original_dict, data_dict)
+                    if diff:
+                        self._pending_changes.append(
+                            create_change_record("migrate", diff, user=None)
+                        )
+                        _logger.info("Queued migration changes for persistence")
+                    await self.flush()
+        except ValueError:
+            if self.db_path.exists():
+                raise
+
+    def _queue_change(self) -> None:
+        current = msgspec.to_builtins(self.db)
+        diff = compute_diff(self._previous_builtins, current)
+        if diff:
+            self._pending_changes.append(
+                create_change_record(self._current_action, diff, self._current_user)
+            )
+            self._previous_builtins = current
+            # Log the change with user display name if available
+            user_display = None
+            if self._current_user:
+                try:
+                    user_uuid = UUID(self._current_user)
+                    if user_uuid in self.db.users:
+                        user_display = self.db.users[user_uuid].display_name
+                except (ValueError, KeyError):
+                    user_display = self._current_user
+
+            diff_json = json.dumps(diff, default=str)
+            if user_display:
+                print(
+                    f"{self._current_action} by {user_display}: {diff_json}",
+                    file=sys.stderr,
+                )
+            else:
+                print(f"{self._current_action}: {diff_json}", file=sys.stderr)
+
+    @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:
+            diff = compute_diff(self._previous_builtins, current_state)
+            diff_json = json.dumps(diff, default=str, indent=2)
+            _logger.error(
+                "Database state modified outside of transaction! "
+                "This indicates a bug where DB changes occurred without a transaction wrapper. "
+                "Resetting to last known state from JSONL file.\n"
+                f"Changes detected:\n{diff_json}"
+            )
+            # Hard reset to last known good state
+            decoder = msgspec.json.Decoder(DB)
+            self.db = decoder.decode(msgspec.json.encode(self._previous_builtins))
+            self.db._store = self
+            current_state = self._previous_builtins.copy()
+
+        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
+            self._queue_change()
+        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/migrations.py

@@ -0,0 +1,34 @@
+"""
+Database schema migrations.
+
+Migrations are applied during database load based on the version field.
+Each migration should be idempotent and only run when needed.
+"""
+
+import logging
+
+_logger = logging.getLogger(__name__)
+
+
+def apply_migrations(data_dict: dict) -> bool:
+    """Apply any pending schema migrations to the database dictionary.
+
+    Args:
+        data_dict: The raw database dictionary loaded from JSONL
+
+    Returns:
+        True if any migrations were applied, False otherwise
+    """
+    db_version = data_dict.get("v", 0)
+    migrated = False
+
+    if db_version == 0:
+        # Migration v0 -> v1: Remove created_at from orgs (field removed from schema)
+        if "orgs" in data_dict:
+            for org_data in data_dict["orgs"].values():
+                org_data.pop("created_at", None)
+        data_dict["v"] = 1
+        migrated = True
+        _logger.info("Applied schema migration: v0 -> v1 (removed org.created_at)")
+
+    return migrated