vention-storage 0.1.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

storage/accessor.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    List,
+    Optional,
+    Sequence,
+    Type,
+    TypeVar,
+    cast,
+    Iterator,
+)
+
+from sqlmodel import SQLModel, Session, select
+
+from storage.auditor import audit_operation
+from storage import database
+from storage.hooks import HookFn, HookRegistry, HookEvent
+from storage.utils import ModelType, utcnow, Operation
+
+
+WriteResult = TypeVar("WriteResult")
+
+
+class ModelAccessor(Generic[ModelType]):
+    """
+    Accessor for a single SQLModel type with:
+      - strongly-typed lifecycle hooks (before/after insert/update/delete)
+      - atomic writes with auditing
+      - optional soft delete (if model defines `deleted_at`)
+      - batch helpers
+      - implicit session reuse inside hooks (no .bind() needed)
+    """
+
+    def __init__(self, model: Type[ModelType], component_name: str) -> None:
+        self.model = model
+        self.component = component_name
+        self._hooks: HookRegistry[ModelType] = HookRegistry()
+        self._has_soft_delete = hasattr(model, "deleted_at")
+
+    # ---------- Hook decorators ----------
+    def before_insert(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("before_insert")
+
+    def after_insert(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("after_insert")
+
+    def before_update(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("before_update")
+
+    def after_update(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("after_update")
+
+    def before_delete(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("before_delete")
+
+    def after_delete(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
+        return self._hooks.decorator("after_delete")
+
+    # ---------- Internal helpers ----------
+    def _emit(self, event: HookEvent, *, session: Session, instance: ModelType) -> None:
+        """Make this session visible to any accessor calls done inside hooks."""
+        with database.use_session(session):
+            self._hooks.emit(event, session=session, instance=instance)
+
+    def _audit_create_operation(
+        self, *, session: Session, instance: ModelType, actor: str
+    ) -> None:
+        """Audit a create operation."""
+        audit_operation(
+            session=session,
+            component=self.component,
+            operation="create",
+            record_id=int(getattr(instance, "id")),
+            actor=actor,
+            before=None,
+            after=instance.model_dump(),
+        )
+
+    def _run_write(self, fn: Callable[[Session], WriteResult]) -> WriteResult:
+        """Run a write op using the current session if present, else open a transaction."""
+        existing = database.CURRENT_SESSION.get()
+        if existing is not None:
+            return fn(existing)
+        with database.transaction() as session:
+            return fn(session)
+
+    @contextmanager
+    def _read_session(self) -> Iterator[Session]:
+        """Reuse current session if present; otherwise open a short-lived one."""
+        existing = database.CURRENT_SESSION.get()
+        if existing is not None:
+            yield existing
+        else:
+            with Session(database.get_engine(), expire_on_commit=False) as session:
+                yield session
+
+    # ---------- Reads ----------
+    def get(self, id: int, *, include_deleted: bool = False) -> Optional[ModelType]:
+        """Get a single model by id."""
+        with self._read_session() as session:
+            obj = session.get(self.model, id)
+            if obj is None:
+                return None
+            if self._has_soft_delete and not include_deleted:
+                if getattr(obj, "deleted_at") is not None:
+                    return None
+            return cast(ModelType, obj)
+
+    def all(self, *, include_deleted: bool = False) -> List[ModelType]:
+        """Get all models."""
+        with self._read_session() as session:
+            statement = select(self.model)
+            if self._has_soft_delete and not include_deleted:
+                statement = statement.where(getattr(self.model, "deleted_at").is_(None))
+            return cast(List[ModelType], session.exec(statement).all())
+
+    # ---------- Writes ----------
+    def insert(self, obj: ModelType, *, actor: str = "internal") -> ModelType:
+        """Insert a new model."""
+
+        def write_operation(session: Session) -> ModelType:
+            self._emit("before_insert", session=session, instance=obj)
+            session.add(obj)
+            session.flush()
+            session.refresh(obj)
+            self._audit_create_operation(session=session, instance=obj, actor=actor)
+            self._emit("after_insert", session=session, instance=obj)
+            return obj
+
+        return self._run_write(write_operation)
+
+    def save(self, obj: ModelType, *, actor: str = "internal") -> ModelType:
+        """Save a model, creating it if it doesn't exist."""
+
+        def write_operation(session: Session) -> ModelType:
+            obj_id = cast(Optional[int], getattr(obj, "id", None))
+            if obj_id is None:
+                return self.insert(obj, actor=actor)
+
+            current = session.get(self.model, obj_id)
+            if current is None:
+                return self.insert(obj, actor=actor)
+
+            before = current.model_dump()
+            merged = session.merge(obj)
+            self._emit("before_update", session=session, instance=merged)
+            session.flush()
+            session.refresh(merged)
+            audit_operation(
+                session=session,
+                component=self.component,
+                operation="update",
+                record_id=int(getattr(merged, "id")),
+                actor=actor,
+                before=before,
+                after=merged.model_dump(),
+            )
+            self._emit("after_update", session=session, instance=merged)
+            return cast(ModelType, merged)
+
+        return self._run_write(write_operation)
+
+    def delete(self, id: int, *, actor: str = "internal") -> bool:
+        """Delete a model."""
+
+        def write_operation(session: Session) -> bool:
+            obj = session.get(self.model, id)
+            if obj is None:
+                return False
+            self._emit("before_delete", session=session, instance=obj)
+            op_name, before_payload, after_payload = _soft_or_hard_delete(session, obj)
+            audit_operation(
+                session=session,
+                component=self.component,
+                operation=op_name,
+                record_id=id,
+                actor=actor,
+                before=before_payload,
+                after=after_payload,
+            )
+            self._emit("after_delete", session=session, instance=obj)
+            return True
+
+        return self._run_write(write_operation)
+
+    def restore(self, id: int, *, actor: str = "internal") -> bool:
+        """Restore a soft-deleted model."""
+
+        def write_operation(session: Session) -> bool:
+            obj = session.get(self.model, id)
+            if obj is None or not self._has_soft_delete:
+                return False
+            if getattr(obj, "deleted_at") is None:
+                return True
+            before = obj.model_dump()
+            setattr(obj, "deleted_at", None)
+            session.add(obj)
+            session.flush()
+            session.refresh(obj)
+            audit_operation(
+                session=session,
+                component=self.component,
+                operation="restore",
+                record_id=id,
+                actor=actor,
+                before=before,
+                after=obj.model_dump(),
+            )
+            return True
+
+        return self._run_write(write_operation)
+
+    # ---------- Batch helpers ----------
+    def insert_many(
+        self, objs: Sequence[ModelType], *, actor: str = "internal"
+    ) -> List[ModelType]:
+        """Insert multiple models."""
+
+        def write_operation(session: Session) -> List[ModelType]:
+            out: List[ModelType] = []
+            for obj in objs:
+                self._emit("before_insert", session=session, instance=obj)
+                session.add(obj)
+            session.flush()
+            for obj in objs:
+                session.refresh(obj)
+                self._audit_create_operation(session=session, instance=obj, actor=actor)
+                self._emit("after_insert", session=session, instance=obj)
+                out.append(obj)
+            return out
+
+        return self._run_write(write_operation)
+
+    def delete_many(self, ids: Sequence[int], *, actor: str = "internal") -> int:
+        """Delete multiple models."""
+
+        def write_operation(session: Session) -> int:
+            count = 0
+            for id_ in ids:
+                obj = session.get(self.model, id_)
+                if obj is None:
+                    continue
+                self._emit("before_delete", session=session, instance=obj)
+                op_name, before_payload, after_payload = _soft_or_hard_delete(
+                    session, obj
+                )
+                audit_operation(
+                    session=session,
+                    component=self.component,
+                    operation=op_name,
+                    record_id=id_,
+                    actor=actor,
+                    before=before_payload,
+                    after=after_payload,
+                )
+                self._emit("after_delete", session=session, instance=obj)
+                count += 1
+            return count
+
+        return self._run_write(write_operation)
+
+
+def _soft_or_hard_delete(
+    session: Session, instance: SQLModel
+) -> tuple[Operation, dict[str, Any], dict[str, Any] | None]:
+    """Soft delete if model defines `deleted_at`, else hard delete."""
+    before_payload = instance.model_dump()
+    if hasattr(instance, "deleted_at"):
+        setattr(instance, "deleted_at", utcnow())
+        session.add(instance)
+        session.flush()
+        after_payload = instance.model_dump()
+        return "soft_delete", before_payload, after_payload
+    else:
+        session.delete(instance)
+        return "delete", before_payload, None

storage/auditor.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from datetime import datetime, date
+from typing import Any, Dict, Optional, cast
+
+from sqlalchemy import Column, String
+from sqlalchemy.dialects.sqlite import JSON
+from sqlmodel import Field, SQLModel, Session
+from storage.utils import utcnow, Operation
+import json
+
+__all__ = ["AuditLog", "audit_operation"]
+
+
+class AuditLog(SQLModel, table=True):  # type: ignore[misc, call-arg]
+    id: Optional[int] = Field(default=None, primary_key=True)
+
+    # Queryable identifiers
+    timestamp: datetime = Field(index=True)
+    component: str = Field(index=True)
+    record_id: int = Field(index=True)
+
+    # What happened and by whom
+    operation: Operation = Field(sa_column=Column(String, nullable=False))
+    actor: str
+
+    # Snapshot of state change
+    before: Optional[Dict[str, Any]] = Field(default=None, sa_column=Column(JSON))
+    after: Optional[Dict[str, Any]] = Field(default=None, sa_column=Column(JSON))
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, (datetime, date)):
+        return obj.isoformat()
+    # add more cases as needed
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def _jsonify(value: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    if value is None:
+        return None
+    # round-trip through json to coerce unsupported types (e.g., datetime) into strings
+    return cast(Dict[str, Any], json.loads(json.dumps(value, default=_json_default)))
+
+
+def audit_operation(
+    *,
+    session: Session,
+    component: str,
+    operation: Operation,
+    record_id: int,
+    actor: str,
+    before: Optional[Dict[str, Any]] = None,
+    after: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    Record a single audit event. Call this INSIDE the same transaction as the data change.
+    """
+    session.add(
+        AuditLog(
+            timestamp=utcnow(),
+            component=component,
+            record_id=record_id,
+            operation=operation,
+            actor=actor,
+            before=_jsonify(before),
+            after=_jsonify(after),
+        )
+    )

storage/bootstrap.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from fastapi import FastAPI
+from sqlmodel import SQLModel
+
+from storage.database import get_engine, set_database_url
+from storage.accessor import ModelAccessor
+from storage.router_model import build_crud_router
+from storage.router_database import build_db_router
+
+
+def bootstrap(
+    app: FastAPI,
+    *,
+    accessors: Iterable[ModelAccessor[Any]],
+    database_url: Optional[str] = None,
+    create_tables: bool = True,
+    max_records_per_model: Optional[int] = 5,
+    enable_db_router: bool = True,
+) -> None:
+    """
+    Bootstrap the storage system for a FastAPI app.
+
+    This helper wires up:
+      - Database engine initialization (optionally overriding the URL).
+      - Optional table creation via `SQLModel.metadata.create_all`.
+      - One CRUD router per registered `ModelAccessor`.
+      - The global /db router (health, audit, diagram, backup/restore) if enabled.
+    """
+    if database_url is not None:
+        set_database_url(database_url)
+
+    engine = get_engine()
+    if create_tables:
+        SQLModel.metadata.create_all(engine)
+
+    # Per-model CRUD routers
+    for accessor in accessors:
+        app.include_router(
+            build_crud_router(accessor, max_records=max_records_per_model)
+        )
+
+    # Global DB router (health, audit, diagram, backup/restore)
+    if enable_db_router:
+        app.include_router(build_db_router())

storage/database.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Iterator, Optional
+
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+from sqlmodel import Session, create_engine
+
+__all__ = [
+    "set_database_url",
+    "get_engine",
+    "transaction",
+    "use_session",
+    "CURRENT_SESSION",
+]
+
+_DATABASE_URL = os.getenv("VENTION_STORAGE_DATABASE_URL", "sqlite:///./storage.db")
+_ENGINE: Optional[Engine] = None
+CURRENT_SESSION: ContextVar[Optional[Session]] = ContextVar(
+    "VENTION_STORAGE_CURRENT_SESSION", default=None
+)
+
+
+def set_database_url(url: str) -> None:
+    """
+    Configure the database URL before the engine is created.
+    Raise if the engine was already initialized.
+    """
+    global _DATABASE_URL, _ENGINE
+    if _ENGINE is not None:
+        raise RuntimeError(
+            "Database engine already initialized. Call set_database_url() before first use."
+        )
+    _DATABASE_URL = url
+
+
+def _attach_sqlite_pragmas(engine: Engine) -> None:
+    """
+    In SQLite foreign key enforcement is disabled by default.
+    Without it, insertions of invalid foreign keys will succeed.
+    """
+
+    def _set_sqlite_pragmas(dbapi_connection: Any, _record: Any) -> None:
+        cursor = dbapi_connection.cursor()
+        try:
+            cursor.execute("PRAGMA foreign_keys=ON")
+        finally:
+            cursor.close()
+
+    event.listen(engine, "connect", _set_sqlite_pragmas)
+
+
+def get_engine() -> Engine:
+    """Return a singleton SQLAlchemy engine (created on first use)."""
+    global _ENGINE
+    if _ENGINE is None:
+        connect_args = (
+            {"check_same_thread": False} if _DATABASE_URL.startswith("sqlite") else {}
+        )
+        _ENGINE = create_engine(_DATABASE_URL, echo=False, connect_args=connect_args)
+        _attach_sqlite_pragmas(_ENGINE)
+    return _ENGINE
+
+
+@contextmanager
+def transaction() -> Iterator[Session]:
+    """
+    Yield a Session wrapped in a single atomic transaction.
+    Commits on success; rolls back on error.
+    Use this when you have multiple all-or-nothing operations.
+
+    Also sets CURRENT_SESSION for the duration, so accessors/hooks can reuse it.
+    """
+    engine = get_engine()
+    with Session(engine, expire_on_commit=False) as session:
+        token = CURRENT_SESSION.set(session)
+        try:
+            with session.begin():
+                yield session
+        finally:
+            CURRENT_SESSION.reset(token)
+
+
+@contextmanager
+def use_session(session: Optional[Session] = None) -> Iterator[Session]:
+    """
+    This helper lets accessors and hooks run DB work without duplicating
+    session-management code. It does not open a transaction by itself;
+    for atomic multi-write operations prefer `transaction()`.
+    """
+    if session is not None:
+        token = CURRENT_SESSION.set(session)
+        try:
+            yield session
+        finally:
+            CURRENT_SESSION.reset(token)
+        return
+
+    with Session(get_engine(), expire_on_commit=False) as s:
+        token = CURRENT_SESSION.set(s)
+        try:
+            yield s
+        finally:
+            CURRENT_SESSION.reset(token)

storage/hooks.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Callable, DefaultDict, Generic, List, TypeVar
+from collections import defaultdict
+
+from sqlmodel import Session, SQLModel
+from typing_extensions import Literal
+
+ModelRecord = TypeVar("ModelRecord", bound=SQLModel)
+
+HookEvent = Literal[
+    "before_insert",
+    "after_insert",
+    "before_update",
+    "after_update",
+    "before_delete",
+    "after_delete",
+]
+
+HookFn = Callable[[Session, ModelRecord], None]
+
+
+class HookRegistry(Generic[ModelRecord]):
+    """Lightweight per-accessor registry for lifecycle hooks."""
+
+    def __init__(self) -> None:
+        self._hooks: DefaultDict[HookEvent, List[HookFn[ModelRecord]]] = defaultdict(
+            list
+        )
+
+    def decorator(
+        self, event: HookEvent
+    ) -> Callable[[HookFn[ModelRecord]], HookFn[ModelRecord]]:
+        """Return a decorator that registers a function for `event`."""
+
+        def deco(fn: HookFn[ModelRecord]) -> HookFn[ModelRecord]:
+            self._hooks[event].append(fn)
+            return fn
+
+        return deco
+
+    def emit(
+        self, event: HookEvent, *, session: Session, instance: ModelRecord
+    ) -> None:
+        """Invoke all hooks registered for `event`."""
+        for fn in self._hooks.get(event, []):
+            fn(session, instance)