tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0__py3-none-any.whl

tigrbl/runtime/errors/utils.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Prefer FastAPI HTTPException/status; fall back to Starlette; finally a tiny shim.
+try:  # FastAPI present
+    from fastapi import HTTPException, status
+except Exception:  # pragma: no cover
+    try:  # Starlette present
+        from starlette.exceptions import HTTPException  # type: ignore
+        from starlette import status  # type: ignore
+    except Exception:  # pragma: no cover
+
+        class HTTPException(Exception):  # minimal shim
+            def __init__(
+                self,
+                status_code: int,
+                detail: Any = None,
+                headers: Optional[dict] = None,
+            ) -> None:
+                super().__init__(detail)
+                self.status_code = status_code
+                self.detail = detail
+                self.headers = headers
+
+        class _Status:
+            HTTP_400_BAD_REQUEST = 400
+            HTTP_401_UNAUTHORIZED = 401
+            HTTP_403_FORBIDDEN = 403
+            HTTP_404_NOT_FOUND = 404
+            HTTP_409_CONFLICT = 409
+            HTTP_422_UNPROCESSABLE_ENTITY = 422
+            HTTP_500_INTERNAL_SERVER_ERROR = 500
+            HTTP_501_NOT_IMPLEMENTED = 501
+            HTTP_503_SERVICE_UNAVAILABLE = 503
+            HTTP_504_GATEWAY_TIMEOUT = 504
+
+        status = _Status()  # type: ignore
+
+# Optional imports – code must run even if these packages aren’t installed.
+try:
+    from pydantic import ValidationError as PydanticValidationError  # v2
+except Exception:  # pragma: no cover
+    PydanticValidationError = None  # type: ignore
+
+try:
+    from fastapi.exceptions import (
+        RequestValidationError,
+    )  # emitted by FastAPI input validation
+except Exception:  # pragma: no cover
+    RequestValidationError = None  # type: ignore
+
+try:
+    # SQLAlchemy v1/v2 exception sets
+    from sqlalchemy.exc import IntegrityError, DBAPIError, OperationalError
+    from sqlalchemy.orm.exc import NoResultFound  # type: ignore
+except Exception:  # pragma: no cover
+    IntegrityError = DBAPIError = OperationalError = NoResultFound = None  # type: ignore
+
+
+# Detect asyncpg constraint errors without importing asyncpg (optional dep).
+_ASYNCPG_CONSTRAINT_NAMES = {
+    "UniqueViolationError",
+    "ForeignKeyViolationError",
+    "NotNullViolationError",
+    "CheckViolationError",
+    "ExclusionViolationError",
+}
+
+
+def _is_asyncpg_constraint_error(exc: BaseException) -> bool:
+    cls = type(exc)
+    return (cls.__module__ or "").startswith("asyncpg") and (
+        cls.__name__ in _ASYNCPG_CONSTRAINT_NAMES
+    )
+
+
+def _limit(s: str, n: int = 4000) -> str:
+    return s if len(s) <= n else s[: n - 3] + "..."
+
+
+def _stringify_exc(exc: BaseException) -> str:
+    detail = getattr(exc, "detail", None)
+    if detail:
+        return _limit(str(detail))
+    return _limit(f"{exc.__class__!r}: {str(exc) or repr(exc)}")
+
+
+def _format_validation(err: Any) -> Any:
+    try:
+        items = err.errors()  # pydantic / fastapi RequestValidationError
+        if isinstance(items, Iterable):
+            return list(items)
+    except Exception:  # pragma: no cover
+        pass
+    return _limit(str(err))
+
+
+def _get_temp(ctx: Any) -> Mapping[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    return tmp if isinstance(tmp, Mapping) else {}
+
+
+def _has_in_errors(ctx: Any) -> bool:
+    tmp = _get_temp(ctx)
+    if tmp.get("in_invalid") is True:
+        return True
+    errs = tmp.get("in_errors")
+    return isinstance(errs, (list, tuple)) and len(errs) > 0
+
+
+def _read_in_errors(ctx: Any) -> List[Dict[str, Any]]:
+    tmp = _get_temp(ctx)
+    errs = tmp.get("in_errors")
+    if isinstance(errs, list):
+        norm: List[Dict[str, Any]] = []
+        for e in errs:
+            if isinstance(e, Mapping):
+                field = e.get("field")
+                code = e.get("code") or "invalid"
+                msg = e.get("message") or "Invalid value."
+                entry = {"field": field, "code": code, "message": msg}
+                for k, v in e.items():
+                    if k not in entry:
+                        entry[k] = v
+                norm.append(entry)
+        return norm
+    return []
+
+
+__all__ = [
+    "HTTPException",
+    "status",
+    "PydanticValidationError",
+    "RequestValidationError",
+    "IntegrityError",
+    "DBAPIError",
+    "OperationalError",
+    "NoResultFound",
+    "_is_asyncpg_constraint_error",
+    "_limit",
+    "_stringify_exc",
+    "_format_validation",
+    "_get_temp",
+    "_has_in_errors",
+    "_read_in_errors",
+]

tigrbl/runtime/events.py

@@ -0,0 +1,209 @@
+# tigrbl/v3/runtime/events.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Literal, Tuple
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Phases
+#   - PRE_TX is a synthetic phase for security/dependency checks.
+#   - START_TX / END_TX are reserved for system steps (no atom anchors there).
+#   - Atoms bind only to the event anchors below.
+# ──────────────────────────────────────────────────────────────────────────────
+
+Phase = Literal[
+    "PRE_TX",
+    "START_TX",
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "END_TX",
+    "POST_RESPONSE",
+]
+
+PHASES: Tuple[Phase, ...] = (
+    "PRE_TX",
+    "START_TX",  # system-only
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "END_TX",  # system-only
+    "POST_RESPONSE",
+)
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Canonical anchors (events) — the only moments atoms can bind to
+# Keep these names stable; labels use them directly: step_kind:domain:subject@ANCHOR
+# ──────────────────────────────────────────────────────────────────────────────
+
+# PRE_HANDLER
+SCHEMA_COLLECT_IN = "schema:collect_in"
+IN_VALIDATE = "in:validate"
+
+# HANDLER
+RESOLVE_VALUES = "resolve:values"
+PRE_FLUSH = "pre:flush"
+EMIT_ALIASES_PRE = "emit:aliases:pre_flush"
+
+# POST_HANDLER
+POST_FLUSH = "post:flush"
+EMIT_ALIASES_POST = "emit:aliases:post_refresh"
+SCHEMA_COLLECT_OUT = "schema:collect_out"
+OUT_BUILD = "out:build"
+
+# POST_RESPONSE
+EMIT_ALIASES_READ = "emit:aliases:readtime"
+OUT_DUMP = "out:dump"
+
+# Canonical order of event anchors within the request lifecycle.
+# This ordering is global and stable; use it to produce deterministic plans/traces.
+_EVENT_ORDER: Tuple[str, ...] = (
+    # PRE_HANDLER
+    SCHEMA_COLLECT_IN,
+    IN_VALIDATE,
+    # HANDLER
+    RESOLVE_VALUES,
+    PRE_FLUSH,
+    EMIT_ALIASES_PRE,
+    # POST_HANDLER
+    POST_FLUSH,
+    EMIT_ALIASES_POST,
+    SCHEMA_COLLECT_OUT,
+    OUT_BUILD,
+    # POST_RESPONSE
+    EMIT_ALIASES_READ,
+    OUT_DUMP,
+)
+
+
+# Map each anchor to its phase and persistence tie.
+# "persist_tied=True" means the anchor is pruned for non-persisting ops
+# (e.g., read/list) and whenever an op is executed with persist=False.
+@dataclass(frozen=True)
+class AnchorInfo:
+    name: str
+    phase: Phase
+    ordinal: int
+    persist_tied: bool
+
+
+_ANCHORS: Dict[str, AnchorInfo] = {
+    # PRE_HANDLER (not persist-tied)
+    SCHEMA_COLLECT_IN: AnchorInfo(SCHEMA_COLLECT_IN, "PRE_HANDLER", 0, False),
+    IN_VALIDATE: AnchorInfo(IN_VALIDATE, "PRE_HANDLER", 1, False),
+    RESOLVE_VALUES: AnchorInfo(RESOLVE_VALUES, "PRE_HANDLER", 2, True),
+    PRE_FLUSH: AnchorInfo(PRE_FLUSH, "PRE_HANDLER", 3, True),
+    EMIT_ALIASES_PRE: AnchorInfo(EMIT_ALIASES_PRE, "PRE_HANDLER", 4, True),
+    # POST_HANDLER (mixed)
+    POST_FLUSH: AnchorInfo(POST_FLUSH, "POST_HANDLER", 5, True),
+    EMIT_ALIASES_POST: AnchorInfo(EMIT_ALIASES_POST, "POST_HANDLER", 6, True),
+    SCHEMA_COLLECT_OUT: AnchorInfo(SCHEMA_COLLECT_OUT, "POST_HANDLER", 7, False),
+    OUT_BUILD: AnchorInfo(OUT_BUILD, "POST_HANDLER", 8, False),
+    # POST_RESPONSE (not persist-tied)
+    EMIT_ALIASES_READ: AnchorInfo(EMIT_ALIASES_READ, "POST_RESPONSE", 9, False),
+    OUT_DUMP: AnchorInfo(OUT_DUMP, "POST_RESPONSE", 10, False),
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Public helpers
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def is_valid_event(anchor: str) -> bool:
+    """True if the given anchor is one of the canonical events."""
+    return anchor in _ANCHORS
+
+
+def phase_for_event(anchor: str) -> Phase:
+    """Return the Phase for a canonical event; raises on unknown anchors."""
+    try:
+        return _ANCHORS[anchor].phase
+    except KeyError as e:
+        raise ValueError(f"Unknown event anchor: {anchor!r}") from e
+
+
+def is_persist_tied(anchor: str) -> bool:
+    """Return True if this event is pruned for non-persisting ops."""
+    try:
+        return _ANCHORS[anchor].persist_tied
+    except KeyError as e:
+        raise ValueError(f"Unknown event anchor: {anchor!r}") from e
+
+
+def get_anchor_info(anchor: str) -> AnchorInfo:
+    """Return the full :class:`AnchorInfo` for a canonical event."""
+    try:
+        return _ANCHORS[anchor]
+    except KeyError as e:
+        raise ValueError(f"Unknown event anchor: {anchor!r}") from e
+
+
+def all_events_ordered() -> List[str]:
+    """Return all canonical events in deterministic, lifecycle order."""
+    return list(_EVENT_ORDER)
+
+
+def events_for_phase(phase: Phase) -> List[str]:
+    """Return the subset of events that belong to the given phase."""
+    if phase not in PHASES:
+        raise ValueError(f"Unknown phase: {phase!r}")
+    return [a for a, info in _ANCHORS.items() if info.phase == phase]
+
+
+def prune_events_for_persist(anchors: Iterable[str], *, persist: bool) -> List[str]:
+    """
+    Given a sequence of anchors, return a new list with persistence-tied events
+    removed when persist=False. Unknown anchors raise ValueError.
+    """
+    out: List[str] = []
+    for a in anchors:
+        if not is_valid_event(a):
+            raise ValueError(f"Unknown event anchor: {a!r}")
+        if not persist and _ANCHORS[a].persist_tied:
+            continue
+        out.append(a)
+    # keep canonical order irrespective of input order
+    out.sort(key=lambda x: _ANCHORS[x].ordinal)
+    return out
+
+
+def order_events(anchors: Iterable[str]) -> List[str]:
+    """
+    Sort a set/list of anchors into canonical lifecycle order.
+    Raises on unknown anchors.
+    """
+    anchors = list(anchors)
+    for a in anchors:
+        if a not in _ANCHORS:
+            raise ValueError(f"Unknown event anchor: {a!r}")
+    anchors.sort(key=lambda x: _ANCHORS[x].ordinal)
+    return anchors
+
+
+__all__ = [
+    # Phases
+    "Phase",
+    "PHASES",
+    # Anchors (constants)
+    "SCHEMA_COLLECT_IN",
+    "IN_VALIDATE",
+    "RESOLVE_VALUES",
+    "PRE_FLUSH",
+    "EMIT_ALIASES_PRE",
+    "POST_FLUSH",
+    "EMIT_ALIASES_POST",
+    "SCHEMA_COLLECT_OUT",
+    "OUT_BUILD",
+    "EMIT_ALIASES_READ",
+    "OUT_DUMP",
+    # Types / helpers
+    "AnchorInfo",
+    "is_valid_event",
+    "phase_for_event",
+    "is_persist_tied",
+    "get_anchor_info",
+    "all_events_ordered",
+    "events_for_phase",
+    "prune_events_for_persist",
+    "order_events",
+]

tigrbl/runtime/executor/__init__.py

@@ -0,0 +1,6 @@
+# tigrbl/v3/runtime/executor/__init__.py
+from .types import _Ctx, HandlerStep, PhaseChains
+from .helpers import _in_tx
+from .invoke import _invoke
+
+__all__ = ["_Ctx", "_invoke", "_in_tx", "HandlerStep", "PhaseChains"]

tigrbl/runtime/executor/guards.py

@@ -0,0 +1,132 @@
+"""Database session guard utilities for the runtime executor.
+
+This module temporarily replaces ``commit`` and ``flush`` on SQLAlchemy
+sessions to enforce phase-specific policies. Each guard returns a handle that
+restores the original methods once the phase completes and provides helpers to
+rollback when the runtime owns the transaction.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional, Union
+
+try:
+    from sqlalchemy.orm import Session  # type: ignore
+    from sqlalchemy.ext.asyncio import AsyncSession  # type: ignore
+except Exception:  # pragma: no cover
+    Session = Any  # type: ignore
+    AsyncSession = Any  # type: ignore
+
+from .types import _Ctx, PhaseChains
+from .helpers import _is_async_db, _run_chain, _g
+
+logger = logging.getLogger(__name__)
+
+
+class _GuardHandle:
+    """Stores original ``commit``/``flush`` methods for later restoration."""
+
+    __slots__ = ("db", "orig_commit", "orig_flush")
+
+    def __init__(self, db: Any, orig_commit: Any, orig_flush: Any) -> None:
+        self.db = db
+        self.orig_commit = orig_commit
+        self.orig_flush = orig_flush
+
+    def restore(self) -> None:
+        if self.orig_commit is not None:
+            try:
+                setattr(self.db, "commit", self.orig_commit)
+            except Exception:
+                pass  # pragma: no cover
+        if self.orig_flush is not None:
+            try:
+                setattr(self.db, "flush", self.orig_flush)
+            except Exception:
+                pass  # pragma: no cover
+
+
+def _install_db_guards(
+    db: Union[Session, AsyncSession, None],
+    *,
+    phase: str,
+    allow_flush: bool,
+    allow_commit: bool,
+    require_owned_tx_for_commit: bool,
+    owns_tx: bool,
+) -> _GuardHandle:
+    """Install guards that restrict ``commit``/``flush`` during a phase.
+
+    Parameters:
+        db: SQLAlchemy ``Session``/``AsyncSession`` to guard.
+        phase: Name of the executing phase for error messages.
+        allow_flush: Whether ``flush`` should be permitted.
+        allow_commit: Whether ``commit`` should be permitted.
+        require_owned_tx_for_commit: Block commits if the executor did not
+            open the transaction.
+        owns_tx: Whether the runtime opened the transaction.
+
+    Returns:
+        A ``_GuardHandle`` for restoring original methods.
+    """
+    if db is None:
+        return _GuardHandle(None, None, None)
+    orig_commit = getattr(db, "commit", None)
+    orig_flush = getattr(db, "flush", None)
+
+    def _raise(op: str) -> None:
+        raise RuntimeError(f"db.{op}() is not allowed during {phase} phase")
+
+    if not allow_commit or (require_owned_tx_for_commit and not owns_tx):
+        if _is_async_db(db):
+
+            async def _blocked_commit() -> None:  # type: ignore[func-returns-value]
+                _raise("commit")
+        else:
+
+            def _blocked_commit() -> None:  # type: ignore[func-returns-value]
+                _raise("commit")
+
+        setattr(db, "commit", _blocked_commit)  # type: ignore[assignment]
+
+    if not allow_flush:
+        if _is_async_db(db):
+
+            async def _blocked_flush() -> None:  # type: ignore[func-returns-value]
+                _raise("flush")
+        else:
+
+            def _blocked_flush() -> None:  # type: ignore[func-returns-value]
+                _raise("flush")
+
+        setattr(db, "flush", _blocked_flush)  # type: ignore[assignment]
+
+    return _GuardHandle(db, orig_commit, orig_flush)
+
+
+async def _rollback_if_owned(
+    db: Union[Session, AsyncSession, None],
+    owns_tx: bool,
+    *,
+    phases: Optional[PhaseChains],
+    ctx: _Ctx,
+) -> None:
+    """Rollback the session if this runtime owns the transaction."""
+
+    if not owns_tx or db is None:
+        return
+    try:
+        if _is_async_db(db):
+            await db.rollback()  # type: ignore[func-returns-value]
+        else:
+            db.rollback()
+    except Exception as rb_exc:  # pragma: no cover
+        logger.exception("Rollback failed: %s", rb_exc)
+    try:
+        await _run_chain(ctx, _g(phases, "ON_ROLLBACK"), phase="ON_ROLLBACK")
+    except Exception:  # pragma: no cover
+        pass
+
+
+__all__ = ["_GuardHandle", "_install_db_guards", "_rollback_if_owned"]

tigrbl/runtime/executor/helpers.py

@@ -0,0 +1,88 @@
+# tigrbl/v3/runtime/executor/helpers.py
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import Any, Iterable, Optional, Sequence
+
+try:
+    from sqlalchemy.ext.asyncio import AsyncSession  # type: ignore
+except Exception:  # pragma: no cover
+    AsyncSession = Any  # type: ignore
+
+try:
+    from .. import trace as _trace  # type: ignore
+except Exception:  # pragma: no cover
+    _trace = None  # type: ignore
+
+from .types import _Ctx, HandlerStep, PhaseChains
+
+logger = logging.getLogger(__name__)
+
+
+def _is_async_db(db: Any) -> bool:
+    """Detect DB interfaces that require `await` for transactional methods."""
+    if isinstance(db, AsyncSession) or hasattr(db, "run_sync"):
+        return True
+    for attr in ("commit", "begin", "rollback", "flush"):
+        if inspect.iscoroutinefunction(getattr(db, attr, None)):
+            return True
+    return False
+
+
+def _bool_call(meth: Any) -> bool:
+    try:
+        return bool(meth())
+    except Exception:  # pragma: no cover
+        return False
+
+
+def _in_tx(db: Any) -> bool:
+    for name in ("in_transaction", "in_nested_transaction"):
+        attr = getattr(db, name, None)
+        if callable(attr):
+            if _bool_call(attr):
+                return True
+        elif attr:
+            return True
+    return False
+
+
+async def _maybe_await(v: Any) -> Any:
+    if inspect.isawaitable(v):
+        return await v  # type: ignore[func-returns-value]
+    return v
+
+
+async def _run_chain(
+    ctx: _Ctx, chain: Optional[Iterable[HandlerStep]], *, phase: str
+) -> None:
+    if not chain:
+        return
+    if _trace is not None:
+        with _trace.span(ctx, f"phase:{phase}"):
+            for step in chain:
+                rv = step(ctx)
+                rv = await _maybe_await(rv)
+                if rv is not None:
+                    ctx.result = rv
+        return
+    for step in chain:
+        rv = step(ctx)
+        rv = await _maybe_await(rv)
+        if rv is not None:
+            ctx.result = rv
+
+
+def _g(phases: Optional[PhaseChains], key: str) -> Sequence[HandlerStep]:
+    return () if not phases else phases.get(key, ())
+
+
+__all__ = [
+    "_is_async_db",
+    "_bool_call",
+    "_in_tx",
+    "_maybe_await",
+    "_run_chain",
+    "_g",
+]