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

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",
+]

tigrbl/runtime/executor/invoke.py

@@ -0,0 +1,150 @@
+# tigrbl/v3/runtime/executor/invoke.py
+from __future__ import annotations
+
+import logging
+from typing import Any, MutableMapping, Optional, Union
+
+from .types import _Ctx, PhaseChains, Request, Session, AsyncSession
+from .helpers import _in_tx, _run_chain, _g
+from .guards import _install_db_guards, _rollback_if_owned
+from ..errors import create_standardized_error
+from ...config.constants import CTX_SKIP_PERSIST_FLAG
+
+logger = logging.getLogger(__name__)
+
+
+async def _invoke(
+    *,
+    request: Optional[Request],
+    db: Union[Session, AsyncSession, None],
+    phases: Optional[PhaseChains],
+    ctx: Optional[MutableMapping[str, Any]] = None,
+) -> Any:
+    """Execute an operation through explicit phases with strict write policies."""
+
+    ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+    if getattr(ctx, "app", None) is None and getattr(ctx, "api", None) is not None:
+        ctx.app = ctx.api
+    if getattr(ctx, "op", None) is None and getattr(ctx, "method", None) is not None:
+        ctx.op = ctx.method
+    if getattr(ctx, "model", None) is None:
+        obj = getattr(ctx, "obj", None)
+        if obj is not None:
+            ctx.model = type(obj)
+    skip_persist: bool = bool(ctx.get(CTX_SKIP_PERSIST_FLAG) or ctx.get("skip_persist"))
+
+    existed_tx_before = _in_tx(db) if db is not None else False
+
+    async def _run_phase(
+        name: str,
+        *,
+        allow_flush: bool,
+        allow_commit: bool,
+        in_tx: bool,
+        require_owned_for_commit: bool = True,
+        nonfatal: bool = False,
+        owns_tx_for_phase: Optional[bool] = None,
+    ) -> None:
+        chain = _g(phases, name)
+        if not chain:
+            return
+
+        eff_allow_flush = allow_flush and (not skip_persist)
+        eff_allow_commit = allow_commit and (not skip_persist)
+
+        owns_tx_now = bool(owns_tx_for_phase)
+        if owns_tx_for_phase is None:
+            owns_tx_now = not existed_tx_before
+
+        guard = _install_db_guards(
+            db,
+            phase=name,
+            allow_flush=eff_allow_flush,
+            allow_commit=eff_allow_commit,
+            require_owned_tx_for_commit=require_owned_for_commit,
+            owns_tx=owns_tx_now,
+        )
+
+        try:
+            await _run_chain(ctx, chain, phase=name)
+        except Exception as exc:
+            ctx.error = exc
+            if in_tx:
+                await _rollback_if_owned(db, owns_tx_now, phases=phases, ctx=ctx)
+            err_name = f"ON_{name}_ERROR"
+            try:
+                await _run_chain(
+                    ctx, _g(phases, err_name) or _g(phases, "ON_ERROR"), phase=err_name
+                )
+            except Exception:  # pragma: no cover
+                pass
+            if nonfatal:
+                logger.exception("%s failed (nonfatal): %s", name, exc)
+                return
+            raise create_standardized_error(exc)
+        finally:
+            guard.restore()
+
+    await _run_phase("PRE_TX_BEGIN", allow_flush=False, allow_commit=False, in_tx=False)
+
+    if not skip_persist:
+        await _run_phase(
+            "START_TX",
+            allow_flush=False,
+            allow_commit=False,
+            in_tx=False,
+            require_owned_for_commit=True,
+        )
+
+    await _run_phase(
+        "PRE_HANDLER", allow_flush=True, allow_commit=False, in_tx=not skip_persist
+    )
+
+    await _run_phase(
+        "HANDLER", allow_flush=True, allow_commit=False, in_tx=not skip_persist
+    )
+
+    await _run_phase(
+        "POST_HANDLER", allow_flush=True, allow_commit=False, in_tx=not skip_persist
+    )
+
+    await _run_phase(
+        "PRE_COMMIT", allow_flush=False, allow_commit=False, in_tx=not skip_persist
+    )
+
+    if not skip_persist:
+        owns_tx_for_commit = (not existed_tx_before) and (db is not None and _in_tx(db))
+        await _run_phase(
+            "END_TX",
+            allow_flush=True,
+            allow_commit=True,
+            in_tx=True,
+            require_owned_for_commit=True,
+            owns_tx_for_phase=owns_tx_for_commit,
+        )
+
+    from types import SimpleNamespace as _NS
+
+    serializer = ctx.get("response_serializer")
+    if callable(serializer):
+        try:
+            ctx["result"] = serializer(ctx.get("result"))
+        except Exception:
+            logger.exception("response serialization failed", exc_info=True)
+    ctx.response = _NS(result=ctx.get("result"))
+
+    await _run_phase("POST_COMMIT", allow_flush=True, allow_commit=False, in_tx=False)
+
+    await _run_phase(
+        "POST_RESPONSE",
+        allow_flush=False,
+        allow_commit=False,
+        in_tx=False,
+        nonfatal=True,
+    )
+    if ctx.get("result") is not None:
+        ctx.response.result = ctx.get("result")
+    return ctx.response.result
+
+
+__all__ = ["_invoke"]

tigrbl/runtime/executor/types.py

@@ -0,0 +1,84 @@
+# tigrbl/v3/runtime/executor/types.py
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Sequence,
+    Union,
+    Protocol,
+    runtime_checkable,
+)
+
+try:
+    from fastapi import Request  # type: ignore
+except Exception:  # pragma: no cover
+    Request = Any  # type: ignore
+
+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
+
+
+@runtime_checkable
+class _Step(Protocol):
+    def __call__(self, ctx: "_Ctx") -> Union[Any, Awaitable[Any]]: ...
+
+
+HandlerStep = Union[
+    _Step,
+    Callable[["_Ctx"], Any],
+    Callable[["_Ctx"], Awaitable[Any]],
+]
+PhaseChains = Mapping[str, Sequence[HandlerStep]]
+
+
+class _Ctx(dict):
+    """Dict-like context with attribute access.
+
+    Common keys:
+      • request: FastAPI Request (optional)
+      • db: Session | AsyncSession
+      • api/model/op: optional metadata
+      • result: last non-None step result
+      • error: last exception caught (on failure paths)
+      • response: SimpleNamespace(result=...) for POST_RESPONSE shaping
+      • temp: scratch dict used by atoms/hook steps
+    """
+
+    __slots__ = ()
+    __getattr__ = dict.get  # type: ignore[assignment]
+    __setattr__ = dict.__setitem__  # type: ignore[assignment]
+
+    @classmethod
+    def ensure(
+        cls,
+        *,
+        request: Optional[Request],
+        db: Union[Session, AsyncSession, None],
+        seed: Optional[MutableMapping[str, Any]] = None,
+    ) -> "_Ctx":
+        ctx = cls() if seed is None else (seed if isinstance(seed, _Ctx) else cls(seed))
+        if request is not None:
+            ctx.request = request
+            state = getattr(request, "state", None)
+            if state is not None and getattr(state, "ctx", None) is None:
+                try:
+                    state.ctx = ctx  # make ctx available to deps
+                except Exception:  # pragma: no cover
+                    pass
+        if db is not None:
+            ctx.db = db
+        if "temp" not in ctx or not isinstance(ctx.get("temp"), dict):
+            ctx.temp = {}
+        return ctx
+
+
+__all__ = ["_Ctx", "HandlerStep", "PhaseChains", "Request", "Session", "AsyncSession"]