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

tigrbl/runtime/context.py

@@ -0,0 +1,206 @@
+# tigrbl/v3/runtime/context.py
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+
+def _canon_op(op: Optional[str]) -> str:
+    return (op or "").strip().lower() or "unknown"
+
+
+@dataclass
+class Context:
+    """
+    Canonical runtime context shared by the kernel and atoms.
+
+    Minimal contract (consumed by atoms we’ve written so far):
+      - op:        operation name (e.g., 'create' | 'update' | 'read' | 'list' | custom)
+      - persist:   write vs. read (affects pruning of persist-tied anchors)
+      - specs:     mapping of field -> ColumnSpec (frozen at bind time)
+      - cfg:       read-only config view (see config.resolver.CfgView)
+      - temp:      dict scratchpad used by atoms to exchange data
+
+    Optional adapter slots:
+      - model:     owning model type / class
+      - obj:       hydrated ORM instance (if any)
+      - session:   DB session / unit-of-work handle
+      - user, tenant, now: identity/time hints
+      - row/values/current_values: mapping fallbacks (for read paths)
+      - in_data / payload / data / body: inbound payload staging (for build_in)
+    """
+
+    # core
+    op: str
+    persist: bool
+    specs: Mapping[str, Any]
+    cfg: Any
+
+    # shared scratchpad
+    temp: Dict[str, Any] = field(default_factory=dict)
+
+    # optional context
+    model: Any | None = None
+    obj: Any | None = None
+    session: Any | None = None
+
+    # identity/time
+    user: Any | None = None
+    tenant: Any | None = None
+    now: _dt.datetime | None = None
+
+    # read-path fallbacks
+    row: Mapping[str, Any] | None = None
+    values: Mapping[str, Any] | None = None
+    current_values: Mapping[str, Any] | None = None
+
+    # inbound staging (router/adapters may set any one of these)
+    in_data: Any | None = None
+    payload: Any | None = None
+    data: Any | None = None
+    body: Any | None = None
+
+    def __post_init__(self) -> None:
+        self.op = _canon_op(self.op)
+        # Normalize now to a timezone-aware UTC timestamp when not provided
+        if self.now is None:
+            try:
+                self.now = _dt.datetime.now(_dt.timezone.utc)
+            except Exception:  # pragma: no cover
+                self.now = _dt.datetime.utcnow().replace(tzinfo=None)
+
+        # Ensure temp is a dict (atoms rely on it)
+        if not isinstance(self.temp, dict):
+            self.temp = dict(self.temp)
+
+    # ── convenience flags ─────────────────────────────────────────────────────
+
+    @property
+    def is_write(self) -> bool:
+        """Alias for persist; reads better in some call sites."""
+        return bool(self.persist)
+
+    # ── safe read-only view for user callables (generators, default_factory) ──
+
+    def safe_view(
+        self,
+        *,
+        include_temp: bool = False,
+        temp_keys: Optional[Sequence[str]] = None,
+    ) -> Mapping[str, Any]:
+        """
+        Return a small, read-only mapping exposing only safe, frequently useful keys.
+
+        By default, temp is NOT included (to avoid leaking internals like paired raw values).
+        If include_temp=True, only exposes the keys listed in 'temp_keys' (if provided),
+        otherwise exposes a conservative subset.
+
+        This method is intended to be passed into author callables such as
+        default_factory(ctx_view) or paired token generators.
+        """
+        base = {
+            "op": self.op,
+            "persist": self.persist,
+            "model": self.model,
+            "specs": self.specs,
+            "user": self.user,
+            "tenant": self.tenant,
+            "now": self.now,
+        }
+        if include_temp:
+            allowed = set(temp_keys or ("assembled_values", "virtual_in"))
+            exposed: Dict[str, Any] = {}
+            for k in allowed:
+                if k in self.temp:
+                    exposed[k] = self.temp[k]
+            base = {**base, "temp": MappingProxy(exposed)}
+        return MappingProxy(base)
+
+    # ── tiny helpers used by atoms / kernel ───────────────────────────────────
+
+    def mark_used_returning(self, value: bool = True) -> None:
+        """Flag that DB RETURNING already hydrated values."""
+        self.temp["used_returning"] = bool(value)
+
+    def merge_hydrated_values(
+        self, mapping: Mapping[str, Any], *, replace: bool = False
+    ) -> None:
+        """
+        Save values hydrated from DB (RETURNING/refresh). If replace=False (default),
+        performs a shallow merge into any existing 'hydrated_values'.
+        """
+        if not isinstance(mapping, Mapping):
+            return
+        hv = self.temp.get("hydrated_values")
+        if replace or not isinstance(hv, dict):
+            self.temp["hydrated_values"] = dict(mapping)
+        else:
+            hv.update(mapping)
+
+    def add_response_extras(
+        self, extras: Mapping[str, Any], *, overwrite: Optional[bool] = None
+    ) -> Sequence[str]:
+        """
+        Merge alias extras into temp['response_extras'].
+        Returns a tuple of conflicting keys that were skipped when overwrite=False.
+        """
+        if not isinstance(extras, Mapping) or not extras:
+            return ()
+        buf = self.temp.get("response_extras")
+        if not isinstance(buf, dict):
+            buf = {}
+            self.temp["response_extras"] = buf
+        if overwrite is None:
+            # fall back to cfg; atoms call wire:dump to honor final overwrite policy
+            overwrite = bool(getattr(self.cfg, "response_extras_overwrite", False))
+        conflicts: list[str] = []
+        for k, v in extras.items():
+            if (k in buf) and not overwrite:
+                conflicts.append(k)
+                continue
+            buf[k] = v
+        return tuple(conflicts)
+
+    def get_response_payload(self) -> Any:
+        """Return the payload assembled by wire:dump (or None if not yet available)."""
+        return self.temp.get("response_payload")
+
+    # ── representation (avoid leaking large/sensitive temp contents) ──────────
+
+    def __repr__(self) -> str:  # pragma: no cover
+        model_name = getattr(self.model, "__name__", None) or str(self.model)
+        return (
+            f"Context(op={self.op!r}, persist={self.persist}, model={model_name!r}, "
+            f"user={(getattr(self.user, 'id', None) or None)!r}, temp_keys={sorted(self.temp.keys())})"
+        )
+
+
+# ── tiny immutable mapping proxy (local; no external deps) ────────────────────
+
+
+class MappingProxy(Mapping[str, Any]):
+    """A lightweight, read-only mapping wrapper."""
+
+    __slots__ = ("_d",)
+
+    def __init__(self, data: Mapping[str, Any]):
+        self._d = dict(data)
+
+    def __getitem__(self, k: str) -> Any:
+        return self._d[k]
+
+    def __iter__(self):
+        return iter(self._d)
+
+    def __len__(self) -> int:
+        return len(self._d)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._d.get(key, default)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"MappingProxy({self._d!r})"
+
+
+__all__ = ["Context", "MappingProxy"]

tigrbl/runtime/errors/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from .utils import HTTPException, status
+from .mappings import (
+    HTTP_ERROR_MESSAGES,
+    ERROR_MESSAGES,
+    _HTTP_TO_RPC,
+    _RPC_TO_HTTP,
+)
+from .converters import (
+    http_exc_to_rpc,
+    rpc_error_to_http,
+    _http_exc_to_rpc,
+    _rpc_error_to_http,
+    create_standardized_error,
+    create_standardized_error_from_status,
+    to_rpc_error_payload,
+)
+from .exceptions import (
+    TigrblError,
+    PlanningError,
+    LabelError,
+    ConfigError,
+    SystemStepError,
+    ValidationError,
+    TransformError,
+    DeriveError,
+    KernelAbort,
+    coerce_runtime_error,
+    raise_for_in_errors,
+)
+
+__all__ = [
+    "HTTPException",
+    "status",
+    # maps & messages
+    "HTTP_ERROR_MESSAGES",
+    "ERROR_MESSAGES",
+    "_HTTP_TO_RPC",
+    "_RPC_TO_HTTP",
+    # conversions
+    "http_exc_to_rpc",
+    "rpc_error_to_http",
+    "_http_exc_to_rpc",
+    "_rpc_error_to_http",
+    "create_standardized_error",
+    "create_standardized_error_from_status",
+    "to_rpc_error_payload",
+    # typed errors + helpers
+    "TigrblError",
+    "PlanningError",
+    "LabelError",
+    "ConfigError",
+    "SystemStepError",
+    "ValidationError",
+    "TransformError",
+    "DeriveError",
+    "KernelAbort",
+    "coerce_runtime_error",
+    "raise_for_in_errors",
+]

tigrbl/runtime/errors/converters.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from .utils import (
+    HTTPException,
+    status,
+    PydanticValidationError,
+    RequestValidationError,
+    IntegrityError,
+    DBAPIError,
+    OperationalError,
+    NoResultFound,
+    _is_asyncpg_constraint_error,
+    _stringify_exc,
+    _format_validation,
+)
+from .exceptions import TigrblError
+from .mappings import (
+    _HTTP_TO_RPC,
+    _RPC_TO_HTTP,
+    ERROR_MESSAGES,
+    HTTP_ERROR_MESSAGES,
+)
+
+
+def http_exc_to_rpc(exc: HTTPException) -> tuple[int, str, Any | None]:
+    """Convert HTTPException → (rpc_code, message, data)."""
+    code = _HTTP_TO_RPC.get(exc.status_code, -32603)
+    detail = exc.detail
+    if isinstance(detail, (dict, list)):
+        return code, ERROR_MESSAGES.get(code, "Unknown error"), detail
+    msg = getattr(exc, "rpc_message", None) or (
+        detail if isinstance(detail, str) else None
+    )
+    if not msg:
+        msg = ERROR_MESSAGES.get(
+            code, HTTP_ERROR_MESSAGES.get(exc.status_code, "Unknown error")
+        )
+    data = getattr(exc, "rpc_data", None)
+    return code, msg, data
+
+
+def rpc_error_to_http(
+    rpc_code: int, message: str | None = None, data: Any | None = None
+) -> HTTPException:
+    """Convert JSON-RPC error code (and optional message/data) → HTTPException."""
+    http_status = _RPC_TO_HTTP.get(rpc_code, 500)
+    msg = (
+        message
+        or HTTP_ERROR_MESSAGES.get(http_status)
+        or ERROR_MESSAGES.get(rpc_code, "Unknown error")
+    )
+    http_exc = HTTPException(status_code=http_status, detail=msg)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", msg)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc
+
+
+def _http_exc_to_rpc(exc: HTTPException) -> tuple[int, str, Any | None]:
+    """Alias for :func:`http_exc_to_rpc` to preserve older import paths."""
+    return http_exc_to_rpc(exc)
+
+
+def _rpc_error_to_http(
+    rpc_code: int, message: str | None = None, data: Any | None = None
+) -> HTTPException:
+    """Alias for :func:`rpc_error_to_http` to preserve older import paths."""
+    return rpc_error_to_http(rpc_code, message, data)
+
+
+def _classify_exception(
+    exc: BaseException,
+) -> Tuple[int, str | dict | list, Any | None]:
+    """
+    Return (http_status, detail_or_message, data) suitable for HTTPException and JSON-RPC mapping.
+    `detail_or_message` may be a string OR a structured dict/list (validation).
+    """
+    # 0) Typed Tigrbl errors
+    if isinstance(exc, TigrblError):
+        status_code = getattr(exc, "status", 400) or 400
+        details = getattr(exc, "details", None)
+        if isinstance(details, (dict, list)):
+            return status_code, details, details
+        return status_code, str(exc) or exc.code, None
+
+    # 1) Pass-through HTTPException preserving detail
+    if isinstance(exc, HTTPException):
+        return exc.status_code, exc.detail, getattr(exc, "rpc_data", None)
+
+    # 2) Validation errors → 422 with structured data
+    if (PydanticValidationError is not None) and isinstance(
+        exc, PydanticValidationError
+    ):
+        return (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            HTTP_ERROR_MESSAGES.get(422, "Validation failed"),
+            _format_validation(exc),
+        )
+    if (RequestValidationError is not None) and isinstance(exc, RequestValidationError):
+        return (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            HTTP_ERROR_MESSAGES.get(422, "Validation failed"),
+            _format_validation(exc),
+        )
+
+    # 3) Common client errors
+    if isinstance(exc, (ValueError, TypeError, KeyError)):
+        return status.HTTP_400_BAD_REQUEST, _stringify_exc(exc), None
+    if isinstance(exc, PermissionError):
+        return status.HTTP_403_FORBIDDEN, _stringify_exc(exc), None
+    if isinstance(exc, NotImplementedError):
+        return status.HTTP_501_NOT_IMPLEMENTED, _stringify_exc(exc), None
+    if isinstance(exc, TimeoutError):
+        return status.HTTP_504_GATEWAY_TIMEOUT, _stringify_exc(exc), None
+
+    # 4) ORM/DB mapping
+    if (NoResultFound is not None) and isinstance(exc, NoResultFound):
+        return status.HTTP_404_NOT_FOUND, "Resource not found", None
+
+    if _is_asyncpg_constraint_error(exc):
+        return status.HTTP_409_CONFLICT, _stringify_exc(exc), None
+
+    if (IntegrityError is not None) and isinstance(exc, IntegrityError):
+        msg = _stringify_exc(exc)
+        lower_msg = msg.lower()
+        if "not null constraint" in lower_msg or "check constraint" in lower_msg:
+            return status.HTTP_422_UNPROCESSABLE_ENTITY, msg, None
+        return status.HTTP_409_CONFLICT, msg, None
+
+    if (OperationalError is not None) and isinstance(exc, OperationalError):
+        return status.HTTP_503_SERVICE_UNAVAILABLE, _stringify_exc(exc), None
+
+    if (DBAPIError is not None) and isinstance(exc, DBAPIError):
+        return status.HTTP_500_INTERNAL_SERVER_ERROR, _stringify_exc(exc), None
+
+    # 5) Fallback
+    return status.HTTP_500_INTERNAL_SERVER_ERROR, _stringify_exc(exc), None
+
+
+def create_standardized_error(exc: BaseException) -> HTTPException:
+    """
+    Normalize any exception → HTTPException with attached RPC context:
+      • .rpc_code
+      • .rpc_message
+      • .rpc_data
+    """
+    http_status, detail_or_message, data = _classify_exception(exc)
+    rpc_code = _HTTP_TO_RPC.get(http_status, -32603)
+    if isinstance(detail_or_message, (dict, list)):
+        http_detail = detail_or_message
+        rpc_message = ERROR_MESSAGES.get(
+            rpc_code, HTTP_ERROR_MESSAGES.get(http_status, "Unknown error")
+        )
+    else:
+        http_detail = detail_or_message
+        rpc_message = detail_or_message or ERROR_MESSAGES.get(
+            rpc_code, HTTP_ERROR_MESSAGES.get(http_status, "Unknown error")
+        )
+    http_exc = HTTPException(status_code=http_status, detail=http_detail)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", rpc_message)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc
+
+
+def create_standardized_error_from_status(
+    http_status: int,
+    message: str | None = None,
+    *,
+    rpc_code: int | None = None,
+    data: Any | None = None,
+) -> tuple[HTTPException, int, str]:
+    """Explicit constructor used by code paths that already decided on an HTTP status."""
+    if rpc_code is None:
+        rpc_code = _HTTP_TO_RPC.get(http_status, -32603)
+    if message is None:
+        http_message = HTTP_ERROR_MESSAGES.get(http_status) or ERROR_MESSAGES.get(
+            rpc_code, "Unknown error"
+        )
+        rpc_message = ERROR_MESSAGES.get(rpc_code) or HTTP_ERROR_MESSAGES.get(
+            http_status, "Unknown error"
+        )
+    else:
+        http_message = rpc_message = message
+    http_exc = HTTPException(status_code=http_status, detail=http_message)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", rpc_message)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc, rpc_code, rpc_message
+
+
+def to_rpc_error_payload(exc: HTTPException) -> dict:
+    """Produce a JSON-RPC error object from an HTTPException (with or without rpc_* attrs)."""
+    code, msg, data = http_exc_to_rpc(exc)
+    payload = {"code": code, "message": msg}
+    if data is not None:
+        payload["data"] = data
+    else:
+        if isinstance(exc.detail, (dict, list)):
+            payload["data"] = exc.detail
+    return payload
+
+
+__all__ = [
+    "http_exc_to_rpc",
+    "rpc_error_to_http",
+    "_http_exc_to_rpc",
+    "_rpc_error_to_http",
+    "create_standardized_error",
+    "create_standardized_error_from_status",
+    "to_rpc_error_payload",
+]

tigrbl/runtime/errors/exceptions.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .utils import _read_in_errors, _has_in_errors
+
+
+class TigrblError(Exception):
+    """Base class for runtime errors in Tigrbl v3."""
+
+    code: str = "tigrbl_error"
+    status: int = 400
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        details: Any = None,
+        cause: Optional[BaseException] = None,
+    ):
+        super().__init__(message)
+        if cause is not None:
+            self.__cause__ = cause
+        if code is not None:
+            self.code = code
+        if status is not None:
+            self.status = status
+        self.details = details
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "type": self.__class__.__name__,
+            "code": self.code,
+            "status": self.status,
+            "message": str(self),
+        }
+        if self.details is not None:
+            d["details"] = self.details
+        return d
+
+
+class PlanningError(TigrblError):
+    code = "planning_error"
+    status = 500
+
+
+class LabelError(TigrblError):
+    code = "label_error"
+    status = 400
+
+
+class ConfigError(TigrblError):
+    code = "config_error"
+    status = 400
+
+
+class SystemStepError(TigrblError):
+    code = "system_step_error"
+    status = 500
+
+
+class ValidationError(TigrblError):
+    code = "validation_error"
+    status = 422
+
+    @staticmethod
+    def from_ctx(
+        ctx: Any, message: str = "Input validation failed."
+    ) -> "ValidationError":
+        return ValidationError(message, status=422, details=_read_in_errors(ctx))
+
+
+class TransformError(TigrblError):
+    code = "transform_error"
+    status = 400
+
+
+class DeriveError(TigrblError):
+    code = "derive_error"
+    status = 400
+
+
+class KernelAbort(TigrblError):
+    code = "kernel_abort"
+    status = 403
+
+
+def coerce_runtime_error(exc: BaseException, ctx: Any | None = None) -> TigrblError:
+    """
+    Map arbitrary exceptions to a typed TigrblError for consistent kernel handling.
+    - Already TigrblError → return as-is
+    - ValueError + ctx.temp['in_errors'] → ValidationError
+    - Otherwise → generic TigrblError
+    """
+    if isinstance(exc, TigrblError):
+        return exc
+    if isinstance(exc, ValueError) and ctx is not None and _has_in_errors(ctx):
+        return ValidationError.from_ctx(
+            ctx, message=str(exc) or "Input validation failed."
+        )
+    return TigrblError(str(exc) or exc.__class__.__name__)
+
+
+def raise_for_in_errors(ctx: Any) -> None:
+    """Raise a typed ValidationError if ctx.temp['in_errors'] indicates invalid input."""
+    if _has_in_errors(ctx):
+        raise ValidationError.from_ctx(ctx)
+
+
+__all__ = [
+    "TigrblError",
+    "PlanningError",
+    "LabelError",
+    "ConfigError",
+    "SystemStepError",
+    "ValidationError",
+    "TransformError",
+    "DeriveError",
+    "KernelAbort",
+    "coerce_runtime_error",
+    "raise_for_in_errors",
+]

tigrbl/runtime/errors/mappings.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+# HTTP → JSON-RPC code map
+_HTTP_TO_RPC: dict[int, int] = {
+    400: -32602,
+    401: -32001,
+    403: -32002,
+    404: -32003,
+    409: -32004,
+    422: -32602,
+    500: -32603,
+    501: -32603,
+    503: -32603,
+    504: -32603,
+}
+
+# JSON-RPC → HTTP status map
+_RPC_TO_HTTP: dict[int, int] = {
+    -32700: 400,
+    -32600: 400,
+    -32601: 404,
+    -32602: 400,
+    -32603: 500,
+    -32001: 401,
+    -32002: 403,
+    -32003: 404,
+    -32004: 409,
+}
+
+# Standardized error messages
+ERROR_MESSAGES: dict[int, str] = {
+    -32700: "Parse error",
+    -32600: "Invalid Request",
+    -32601: "Method not found",
+    -32602: "Invalid params",
+    -32603: "Internal error",
+    -32001: "Authentication required",
+    -32002: "Insufficient permissions",
+    -32003: "Resource not found",
+    -32004: "Resource conflict",
+    -32000: "Server error",
+    -32099: "Duplicate key constraint violation",
+    -32098: "Data constraint violation",
+    -32097: "Foreign key constraint violation",
+    -32096: "Authentication required",
+    -32095: "Authorization failed",
+    -32094: "Resource not found",
+    -32093: "Validation error",
+    -32092: "Transaction failed",
+}
+
+# HTTP status code → standardized message
+HTTP_ERROR_MESSAGES: dict[int, str] = {
+    400: "Bad Request: malformed input",
+    401: "Unauthorized: authentication required",
+    403: "Forbidden: insufficient permissions",
+    404: "Not Found: resource does not exist",
+    409: "Conflict: duplicate key or constraint violation",
+    422: "Unprocessable Entity: validation failed",
+    500: "Internal Server Error: unexpected server error",
+    501: "Not Implemented",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+}
+
+__all__ = [
+    "_HTTP_TO_RPC",
+    "_RPC_TO_HTTP",
+    "ERROR_MESSAGES",
+    "HTTP_ERROR_MESSAGES",
+]