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

tigrbl/runtime/atoms/wire/validate_in.py

@@ -0,0 +1,227 @@
+# tigrbl/v3/runtime/atoms/wire/validate_in.py
+from __future__ import annotations
+
+import datetime as _dt
+import decimal as _dc
+import uuid as _uuid
+import logging
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+from fastapi import HTTPException, status as _status
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in, _ensure_temp
+
+# PRE_HANDLER, runs after wire:build_in
+ANCHOR = _ev.IN_VALIDATE  # "in:validate"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    wire:validate_in@in:validate
+
+    Validates the normalized inbound payload (ctx.temp["in_values"]) using the
+    schema collected by schema:collect_in plus tolerant signals from ColumnSpec.
+
+    What it checks
+    --------------
+    - Required fields are present (ABSENT → error; present(None) is a separate check)
+    - Nullability (value is None while column is non-nullable → error)
+    - Lightweight type conformance (optional coercion if enabled)
+    - String max_length (when available)
+    - Author validators (validate_in / in_validator / validator_in on ColumnSpec/FieldSpec/IOSpec)
+
+    Effects
+    -------
+    - Mutates ctx.temp["in_values"] with any successful coercions/validator returns
+    - Writes diagnostics to:
+        ctx.temp["in_errors"] : list of {field, code, message}
+        ctx.temp["in_invalid"] : bool
+        ctx.temp["in_coerced"] : tuple of coerced field names (if any)
+    - Raises HTTPException(422) if any validation errors are found
+    """
+    logger.debug("Running wire:validate_in")
+    temp = _ensure_temp(ctx)
+    ov = opview_from_ctx(ctx)
+    schema_in = ensure_schema_in(ctx, ov)
+
+    in_values: Dict[str, Any] = dict(temp.get("in_values") or {})
+    by_field: Mapping[str, Mapping[str, Any]] = schema_in.get("by_field", {})  # type: ignore[assignment]
+    required: Tuple[str, ...] = tuple(schema_in.get("required", ()))  # type: ignore[assignment]
+
+    errors: list[Dict[str, Any]] = []
+    coerced: list[str] = []
+
+    # 1) Required presence (ABSENT → error)
+    for name in required:
+        if name not in in_values:
+            logger.debug("Required field %s missing", name)
+            errors.append(
+                _err(name, "required", "Field is required but was not provided.")
+            )
+
+    # 2) Per-field validation
+    for name, value in list(in_values.items()):
+        entry = by_field.get(name) or {}
+
+        # Nullability
+        nullable = entry.get("nullable", None)
+        if value is None and nullable is False:
+            logger.debug("Field %s is null but not nullable", name)
+            errors.append(
+                _err(name, "null_not_allowed", "Null is not allowed for this field.")
+            )
+            continue  # skip further checks for this field
+
+        # Type (optionally coerce)
+        target_type = entry.get("py_type")
+        if value is not None and isinstance(target_type, type):
+            allow_coerce = bool(entry.get("coerce", True))
+            ok, new_val, msg = _coerce_if_needed(value, target_type, allow=allow_coerce)
+            if not ok:
+                logger.debug("Type mismatch for field %s", name)
+                errors.append(
+                    _err(
+                        name,
+                        "type_mismatch",
+                        msg or f"Expected {_type_name(target_type)}.",
+                    )
+                )
+                continue
+            if new_val is not value:
+                in_values[name] = new_val
+                coerced.append(name)
+
+        # Max length (strings)
+        max_len = entry.get("max_length", None)
+        if (
+            isinstance(max_len, int)
+            and max_len > 0
+            and isinstance(in_values.get(name), str)
+        ):
+            if len(in_values[name]) > max_len:
+                logger.debug("Field %s exceeds max_length %d", name, max_len)
+                errors.append(
+                    _err(name, "max_length", f"String exceeds max_length={max_len}.")
+                )
+                continue
+
+        # Author-supplied validator(s)
+        vfn = entry.get("validator")
+        if callable(vfn) and in_values.get(name) is not None:
+            try:
+                out = vfn(in_values[name], ctx)
+                if out is not None:
+                    in_values[name] = out
+            except Exception as e:
+                logger.debug("Validator failed for field %s: %s", name, e)
+                errors.append(
+                    _err(name, "validator_failed", f"{type(e).__name__}: {e}")
+                )
+                continue
+
+    # 3) Unknown keys policy (handled after build_in captured samples)
+    unknown = tuple(temp.get("in_unknown") or ())
+    if unknown and _reject_unknown(ctx):
+        logger.debug("Rejecting unknown fields: %s", unknown)
+        for k in unknown:
+            errors.append(_err(k, "unknown_field", "Unknown input key."))
+
+    # Persist results + diagnostics
+    temp["in_values"] = in_values
+    if coerced:
+        temp["in_coerced"] = tuple(coerced)
+
+    if errors:
+        temp["in_errors"] = errors
+        temp["in_invalid"] = True
+        logger.debug("Validation errors found: %s", errors)
+        raise HTTPException(
+            status_code=_status.HTTP_422_UNPROCESSABLE_ENTITY, detail=errors
+        )
+    else:
+        temp["in_invalid"] = False
+        logger.debug("Inbound payload validated successfully")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _reject_unknown(ctx: Any) -> bool:
+    """
+    Check cfg for a 'reject_unknown_fields' (bool); default False.
+    """
+    cfg = getattr(ctx, "cfg", None)
+    val = getattr(cfg, "reject_unknown_fields", None)
+    return bool(val) if isinstance(val, bool) else False
+
+
+def _err(field: str, code: str, msg: str) -> Dict[str, Any]:
+    return {"field": field, "code": code, "message": msg}
+
+
+def _type_name(t: type) -> str:
+    return getattr(t, "__name__", str(t))
+
+
+# ── coercion helpers ──────────────────────────────────────────────────────────
+
+
+def _coerce_if_needed(
+    value: Any, target: type, *, allow: bool
+) -> Tuple[bool, Any, Optional[str]]:
+    """Return (ok, new_value, error_message). Only coerces when allow=True."""
+    if isinstance(value, target):
+        return True, value, None
+    if not allow:
+        return False, value, f"Expected {_type_name(target)}."
+    try:
+        coerced = _coerce(value, target)
+        return True, coerced, None
+    except Exception:
+        return False, value, f"Could not convert to {_type_name(target)}."
+
+
+def _coerce(value: Any, target: type) -> Any:
+    if target is str:
+        return str(value)
+    if target is int:
+        if isinstance(value, bool):
+            return int(value)
+        return int(str(value).strip())
+    if target is float:
+        return float(str(value).strip())
+    if target is bool:
+        if isinstance(value, bool):
+            return value
+        s = str(value).strip().lower()
+        if s in {"true", "1", "yes", "y", "on"}:
+            return True
+        if s in {"false", "0", "no", "n", "off"}:
+            return False
+        raise ValueError("not a boolean")
+    if target is _dc.Decimal:
+        return _dc.Decimal(str(value).strip())
+    if target is _uuid.UUID:
+        return _uuid.UUID(str(value))
+    if target is _dt.datetime:
+        # allow both date-time and date-only (promote to midnight)
+        s = str(value).strip()
+        try:
+            return _dt.datetime.fromisoformat(s)
+        except Exception:
+            d = _dt.date.fromisoformat(s)
+            return _dt.datetime.combine(d, _dt.time())
+    if target is _dt.date:
+        return _dt.date.fromisoformat(str(value).strip())
+    if target is _dt.time:
+        return _dt.time.fromisoformat(str(value).strip())
+    # Fallback: try direct construction
+    return target(value)
+
+
+__all__ = ["ANCHOR", "run"]

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