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

tigrbl/runtime/atoms/storage/to_stored.py

@@ -0,0 +1,167 @@
+# tigrbl/v3/runtime/atoms/storage/to_stored.py
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in, _ensure_temp
+
+# Runs right before the handler flushes to the DB.
+ANCHOR = _ev.PRE_FLUSH  # "pre:flush"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    storage:to_stored@pre:flush
+
+    Transform inbound values into their persisted representation.
+
+    - For *paired/secret-once* columns, derive the stored value from the prepared raw
+      and assign it to BOTH ctx.temp["assembled_values"][field] AND the ORM object.
+      Also handles a fallback when 'persist_from_paired' wasn't queued but a paired raw
+      exists (planner tolerance).
+    - Otherwise, apply an optional per-column inbound→stored transform and mirror the
+      transformed value onto the ORM instance.
+
+    On failure to derive for paired, raise ValueError (mapped by higher layers) to
+    avoid leaking DB IntegrityErrors.
+    """
+    logger.debug("Running storage:to_stored")
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping storage:to_stored; ctx.persist is False")
+        return
+
+    ov = opview_from_ctx(ctx)
+    schema_in = ensure_schema_in(ctx, ov)
+    temp = _ensure_temp(ctx)
+    assembled = _ensure_dict(temp, "assembled_values")
+    paired_values = _ensure_dict(temp, "paired_values")
+    pf_paired = _ensure_dict(temp, "persist_from_paired")
+    slog = _ensure_list(temp, "storage_log")
+    serr = _ensure_list(temp, "storage_errors")
+
+    # Prefer explicit obj (hydrated instance), else ctx.model if adapter provided it
+    target_obj = obj or getattr(ctx, "model", None)
+
+    # Ensure paired fields are considered even when absent from inbound schema.
+    # schema_in["fields"] may omit columns like "digest" that generate their
+    # values server-side via IO(...).paired. To derive their stored values, merge
+    # the explicit schema fields with the paired index keys.
+    all_fields = set(schema_in["fields"]) | set(ov.paired_index.keys())
+
+    for field in sorted(all_fields):
+        if field in ov.paired_index:
+            if field in pf_paired or field in paired_values:
+                raw = None
+                if field in pf_paired:
+                    raw = _resolve_from_pointer(
+                        pf_paired[field].get("source"), paired_values, field
+                    )
+                if raw is None:
+                    raw = paired_values.get(field, {}).get("raw")
+                if raw is None:
+                    serr.append({"field": field, "error": "missing_paired_raw"})
+                    logger.debug("Missing paired raw for field %s", field)
+                    raise RuntimeError(f"paired_raw_missing:{field}")
+                deriver = ov.paired_index[field].get("store")
+                try:
+                    stored = deriver(raw, ctx) if callable(deriver) else raw
+                except Exception as e:
+                    serr.append(
+                        {"field": field, "error": f"deriver_failed:{type(e).__name__}"}
+                    )
+                    logger.debug("Deriver failed for field %s: %s", field, e)
+                    raise
+                assembled[field] = stored
+                _assign_to_model(target_obj, field, stored)
+                slog.append({"field": field, "action": "derived_from_paired"})
+                logger.debug("Derived stored value for paired field %s", field)
+                continue
+
+            nullable = schema_in["by_field"].get(field, {}).get("nullable", True)
+            if (
+                not nullable
+                and field not in assembled
+                and not _has_attr_with_value(target_obj, field)
+            ):
+                serr.append({"field": field, "error": "paired_missing_before_flush"})
+                logger.debug("Paired field %s missing before flush", field)
+                raise RuntimeError(f"paired_missing_before_flush:{field}")
+            continue
+
+        if field in assembled:
+            transform = ov.to_stored_transforms.get(field)
+            if transform is None:
+                logger.debug("No transform for field %s; using assembled value", field)
+                _assign_to_model(target_obj, field, assembled[field])
+                continue
+            try:
+                stored_val = transform(assembled[field], ctx)
+                assembled[field] = stored_val
+                _assign_to_model(target_obj, field, stored_val)
+                slog.append({"field": field, "action": "transformed"})
+                logger.debug("Transformed field %s", field)
+            except Exception as e:
+                serr.append(
+                    {"field": field, "error": f"transform_failed:{type(e).__name__}"}
+                )
+                logger.debug("Transform failed for field %s: %s", field, e)
+                raise
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals (tolerant to spec shapes)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _assign_to_model(target: Optional[object], field: str, value: Any) -> None:
+    """Safely assign value onto the hydrated ORM object so SQLAlchemy flushes it."""
+    if target is None:
+        return
+    try:
+        setattr(target, field, value)
+    except Exception:
+        # Non-fatal: some adapters may not expose an assignable object here.
+        pass
+
+
+def _has_attr_with_value(target: Optional[object], field: str) -> bool:
+    if target is None or not hasattr(target, field):
+        return False
+    try:
+        return getattr(target, field) is not None
+    except Exception:
+        return False
+
+
+def _ensure_dict(temp: MutableMapping[str, Any], key: str) -> Dict[str, Any]:
+    d = temp.get(key)
+    if not isinstance(d, dict):
+        d = {}
+        temp[key] = d
+    return d  # type: ignore[return-value]
+
+
+def _ensure_list(temp: MutableMapping[str, Any], key: str) -> list:
+    lst = temp.get(key)
+    if not isinstance(lst, list):
+        lst = []
+        temp[key] = lst
+    return lst  # type: ignore[return-value]
+
+
+def _resolve_from_pointer(
+    source: Any, pv: Mapping[str, Dict[str, Any]], field: str
+) -> Optional[Any]:
+    """Resolve ('paired_values', field, 'raw') pointer, with fallback to pv[field]['raw']."""
+    if isinstance(source, (tuple, list)) and len(source) == 3:
+        base, fld, key = source
+        if base == "paired_values" and isinstance(fld, str) and key == "raw":
+            return pv.get(fld, {}).get("raw")
+    return pv.get(field, {}).get("raw")
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/wire/__init__.py

@@ -0,0 +1,45 @@
+# tigrbl/v3/runtime/atoms/wire/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (per-field)
+from . import build_in as _build_in
+from . import validate_in as _validate_in
+from . import build_out as _build_out
+from . import dump as _dump
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+#: Canonical subjects mirror filenames; we keep "validate_in" (not "validate") to avoid duplicates.
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("wire", "build_in"): (_build_in.ANCHOR, _build_in.run),
+    ("wire", "validate_in"): (_validate_in.ANCHOR, _validate_in.run),
+    ("wire", "build_out"): (_build_out.ANCHOR, _build_out.run),
+    ("wire", "dump"): (_dump.ANCHOR, _dump.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'wire' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'wire' domain."""
+    key = ("wire", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown wire atom subject: {subject!r}")
+    logger.debug("Retrieving 'wire' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/wire/build_in.py

@@ -0,0 +1,166 @@
+# tigrbl/v3/runtime/atoms/wire/build_in.py
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+import logging
+
+from ... import events as _ev
+
+# Runs in PRE_HANDLER just before validation.
+ANCHOR = _ev.IN_VALIDATE  # "in:validate"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    wire:build_in@in:validate
+
+    Purpose
+    -------
+    Normalize the inbound request payload into canonical field names based on
+    the schema collected by schema:collect_in. This prepares a dict that
+    downstream atoms (resolve:assemble, validate_in, etc.) can use.
+
+    What it does
+    ------------
+    - Reads ctx.temp["schema_in"] (built by schema:collect_in).
+    - Extracts a dict-like payload from ctx (ctx.in_data/payload/data/body or Pydantic model).
+    - Maps known *aliases* (alias_in) → canonical field names.
+    - Keeps only fields enabled for inbound IO; unknown keys captured to diagnostics.
+    - Distinguishes **ABSENT** (missing) from present(None) by *not* inserting missing keys.
+    - Stores results in ctx.temp["in_values"] and supporting diagnostics.
+
+    Notes
+    -----
+    - This atom does *not* perform validation—that belongs to wire:validate_in.
+    - For bulk inputs, adapters may pre-split and invoke the executor per-item.
+    """
+    schema_in = _schema_in(ctx)
+    if not schema_in:
+        logger.debug("No schema_in available; skipping wire:build_in")
+        return  # nothing to do
+
+    logger.debug("Running wire:build_in")
+    temp = _ensure_temp(ctx)
+
+    payload = _coerce_payload(ctx)
+    if not isinstance(payload, Mapping):
+        logger.debug("Payload is not a mapping; skipping normalization")
+        # Non-mapping payloads are ignored here; adapters can pre-normalize.
+        return
+
+    by_field: Mapping[str, Mapping[str, Any]] = schema_in.get("by_field", {})  # type: ignore[assignment]
+    # Build alias→field and ingress whitelist (field and alias forms)
+    alias_to_field: Dict[str, str] = {}
+    ingress_keys: set[str] = set()
+
+    for fname, entry in by_field.items():
+        alias = _safe_str(entry.get("alias_in"))
+        ingress_keys.add(fname)
+        if alias:
+            alias_to_field[alias] = fname
+            ingress_keys.add(alias)
+
+    # Normalize
+    in_values: Dict[str, Any] = {}
+    present_fields: set[str] = set()
+    unknown_keys: Dict[str, Any] = {}
+
+    # First pass: direct field-name matches win
+    for key, val in payload.items():
+        if key in by_field:
+            in_values[key] = val
+            present_fields.add(key)
+        else:
+            # Track unknowns for now; we may reclassify as alias below
+            unknown_keys[key] = val
+
+    # Second pass: alias matches for anything not already set
+    for key, val in list(unknown_keys.items()):
+        target = alias_to_field.get(key)
+        if target and target not in in_values:
+            logger.debug("Resolved alias %s -> %s", key, target)
+            in_values[target] = val
+            present_fields.add(target)
+            unknown_keys.pop(key, None)
+
+    # Keep minimal diagnostics
+    temp["in_values"] = in_values
+    temp["in_present"] = tuple(sorted(present_fields))
+    if unknown_keys:
+        temp["in_unknown"] = tuple(sorted(unknown_keys.keys()))
+        logger.debug("Unknown inbound keys: %s", list(unknown_keys.keys()))
+        # optionally stash raw unknowns for tooling (avoid huge payloads)
+        if len(unknown_keys) <= 16:  # small guard
+            temp["in_unknown_samples"] = {
+                k: unknown_keys[k] for k in list(unknown_keys)[:16]
+            }
+    logger.debug("Normalized inbound values: %s", in_values)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_temp(ctx: Any) -> MutableMapping[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    if not isinstance(tmp, dict):
+        tmp = {}
+        setattr(ctx, "temp", tmp)
+    return tmp
+
+
+def _schema_in(ctx: Any) -> Mapping[str, Any]:
+    tmp = getattr(ctx, "temp", {})
+    sch = getattr(tmp, "get", lambda *_a, **_k: None)("schema_in")  # type: ignore
+    if isinstance(sch, Mapping):
+        return sch
+    # allow adapters to stuff schema_in directly on ctx
+    sch2 = getattr(ctx, "schema_in", None)
+    return sch2 if isinstance(sch2, Mapping) else {}
+
+
+def _coerce_payload(ctx: Any) -> Mapping[str, Any] | Any:
+    """
+    Try to obtain a dict-like payload from common places on the context.
+    Accepts Pydantic v1/v2 models and simple dataclasses.
+    """
+    # Preferred explicit staging from router/adapters
+    for name in ("in_data", "payload", "data", "body"):
+        val = getattr(ctx, name, None)
+        if val is None:
+            continue
+        # Mapping already?
+        if isinstance(val, Mapping):
+            return val
+        # Pydantic v2
+        if hasattr(val, "model_dump") and callable(getattr(val, "model_dump")):
+            try:
+                return dict(val.model_dump())
+            except Exception:
+                pass
+        # Pydantic v1
+        if hasattr(val, "dict") and callable(getattr(val, "dict")):
+            try:
+                return dict(val.dict())
+            except Exception:
+                pass
+        # Dataclass?
+        try:
+            import dataclasses as _dc  # local import; safe if missing
+
+            if _dc.is_dataclass(val):
+                return _dc.asdict(val)
+        except Exception:
+            pass
+        return val  # give back as-is; validator can complain later
+    return {}
+
+
+def _safe_str(v: Any) -> Optional[str]:
+    return v if isinstance(v, str) and v else None
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/wire/build_out.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out, _ensure_temp
+
+# POST_HANDLER, runs before readtime aliases and dump.
+ANCHOR = _ev.OUT_BUILD  # "out:build"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Build canonical outbound values keyed by field name."""
+    logger.debug("Running wire:build_out")
+    ov = opview_from_ctx(ctx)
+    schema_out = ensure_schema_out(ctx, ov)
+    by_field = schema_out["by_field"]
+    expose = schema_out["expose"]
+
+    temp = _ensure_temp(ctx)
+    out_values: Dict[str, Any] = {}
+    produced_virtuals: list[str] = []
+    missing: list[str] = []
+
+    for field in expose:
+        desc = by_field.get(field, {})
+        if desc.get("virtual"):
+            producer = ov.virtual_producers.get(field)
+            if callable(producer):
+                try:
+                    out_values[field] = producer(obj, ctx)
+                    produced_virtuals.append(field)
+                    logger.debug("Produced virtual field %s", field)
+                except Exception:
+                    missing.append(field)
+                    logger.debug("Virtual producer failed for field %s", field)
+            else:
+                missing.append(field)
+                logger.debug("No producer for virtual field %s", field)
+            continue
+
+        value = _read_current_value(obj, ctx, field)
+        if value is None:
+            missing.append(field)
+            logger.debug("No value available for field %s", field)
+        out_values[field] = value
+
+    temp["out_values"] = out_values
+    if produced_virtuals:
+        temp["out_virtual_produced"] = tuple(produced_virtuals)
+    if missing:
+        temp["out_missing"] = tuple(missing)
+    logger.debug(
+        "Built outbound values: %s (virtuals=%s, missing=%s)",
+        out_values,
+        produced_virtuals,
+        missing,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _read_current_value(obj: Optional[object], ctx: Any, field: str) -> Optional[Any]:
+    if obj is not None and hasattr(obj, field):
+        try:
+            return getattr(obj, field)
+        except Exception:
+            pass
+    for name in ("row", "values", "current_values"):
+        src = getattr(ctx, name, None)
+        if isinstance(src, Mapping) and field in src:
+            return src.get(field)
+    hv = getattr(getattr(ctx, "temp", {}), "get", lambda *a, **k: None)(
+        "hydrated_values"
+    )  # type: ignore
+    if isinstance(hv, Mapping):
+        return hv.get(field)
+    return None
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/wire/dump.py

@@ -0,0 +1,206 @@
+# tigrbl/v3/runtime/atoms/wire/dump.py
+from __future__ import annotations
+
+import base64
+import datetime as _dt
+import decimal as _dc
+import uuid as _uuid
+import logging
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+
+from ... import events as _ev
+
+# Runs at the very end of model shaping; out:masking follows at the same anchor.
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    wire:dump@out:dump
+
+    Purpose
+    -------
+    Build the final wire payload (dict or list[dict]) from:
+      - ctx.temp["out_values"] (field -> value) produced by wire:build_out
+      - ctx.temp["schema_out"] (for alias mapping)
+      - ctx.temp["response_extras"] (alias extras from emit atoms)
+
+    What it does
+    ------------
+    - Maps canonical field names → wire keys using alias_out (when provided).
+    - Optionally omits null values (cfg.exclude_none / cfg.omit_nulls).
+    - Applies minimal JSON-friendly scalar conversions (date/time/uuid/decimal/bytes).
+    - Merges response_extras (without overwriting unless configured) for single-object payloads.
+    - Stores the result in ctx.temp["response_payload"] for downstream masking/transport.
+
+    Notes
+    -----
+    - This step does NOT perform masking/redaction; that is handled by out:masking.
+    - For collection/list responses, extras are not merged (they are usually per-item).
+    """
+    logger.debug("Running wire:dump")
+    temp = _ensure_temp(ctx)
+    out_values = temp.get("out_values")
+
+    if not out_values:
+        logger.debug("No out_values available; skipping dump")
+        return  # nothing to dump
+
+    schema_out = _schema_out(ctx)
+    aliases: Mapping[str, str] = (
+        schema_out.get("aliases", {}) if isinstance(schema_out, Mapping) else {}
+    )
+
+    omit_nulls = _omit_nulls(ctx)
+    allow_overwrite = _allow_extras_overwrite(ctx)
+
+    # Single object
+    if isinstance(out_values, Mapping):
+        logger.debug("Dumping single-object payload")
+        payload = _dump_one(out_values, aliases, omit_nulls)
+        # Merge extras (single-object only)
+        extras = temp.get("response_extras")
+        if isinstance(extras, Mapping) and extras:
+            conflicts = []
+            for k, v in extras.items():
+                if (k in payload) and not allow_overwrite:
+                    conflicts.append(k)
+                    logger.debug("Conflict on extra key %s", k)
+                    continue
+                payload[k] = _dump_scalar(v)
+            if conflicts:
+                temp["dump_conflicts"] = tuple(sorted(set(conflicts)))
+        temp["response_payload"] = payload
+        logger.debug("Response payload built: %s", payload)
+        return None
+
+    # List/tuple of objects (already expanded by executor)
+    if isinstance(out_values, (list, tuple)) and all(
+        isinstance(x, Mapping) for x in out_values
+    ):
+        logger.debug("Dumping list payload with %d items", len(out_values))
+        payload_list = [
+            _dump_one(item, aliases, omit_nulls)
+            for item in out_values  # type: ignore[arg-type]
+        ]
+        temp["response_payload"] = payload_list
+        return None
+
+    # Unknown shape — stash as-is to avoid surprises (transport may serialize).
+    temp["response_payload"] = out_values
+    logger.debug("Stored opaque response payload: %s", type(out_values).__name__)
+    return None
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_temp(ctx: Any) -> MutableMapping[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    if not isinstance(tmp, dict):
+        tmp = {}
+        setattr(ctx, "temp", tmp)
+    return tmp
+
+
+def _schema_out(ctx: Any) -> Mapping[str, Any]:
+    tmp = getattr(ctx, "temp", {})
+    sch = getattr(tmp, "get", lambda *_a, **_k: None)("schema_out")  # type: ignore
+    if isinstance(sch, Mapping):
+        return sch
+    sch2 = getattr(ctx, "schema_out", None)
+    return sch2 if isinstance(sch2, Mapping) else {}
+
+
+def _omit_nulls(ctx: Any) -> bool:
+    """
+    Config flags to drop null-valued keys:
+      - cfg.exclude_none (preferred)
+      - cfg.omit_nulls
+    Default False.
+    """
+    cfg = getattr(ctx, "cfg", None)
+    for name in ("exclude_none", "omit_nulls"):
+        val = getattr(cfg, name, None)
+        if isinstance(val, bool):
+            return val
+    return False
+
+
+def _allow_extras_overwrite(ctx: Any) -> bool:
+    """
+    If True, extras can overwrite existing keys; default False.
+    cfg.extras_overwrite or cfg.response_extras_overwrite.
+    """
+    cfg = getattr(ctx, "cfg", None)
+    for name in ("response_extras_overwrite", "extras_overwrite"):
+        val = getattr(cfg, name, None)
+        if isinstance(val, bool):
+            return val
+    return False
+
+
+def _dump_one(
+    values: Mapping[str, Any], aliases: Mapping[str, str], omit_nulls: bool
+) -> Dict[str, Any]:
+    """
+    Convert a single out_values mapping to a wire payload dict with alias mapping and scalar dumps.
+    """
+    out: Dict[str, Any] = {}
+    used_aliases: list[str] = []
+    omitted: list[str] = []
+
+    for field, val in values.items():
+        if omit_nulls and val is None:
+            omitted.append(field)
+            continue
+        key = aliases.get(field) or field
+        if key != field:
+            used_aliases.append(key)
+        out[key] = _dump_scalar(val)
+
+    if used_aliases:
+        # diagnostics hook
+        # note: this goes on the payload's temp, not user-visible
+        pass
+    return out
+
+
+def _dump_scalar(v: Any) -> Any:
+    """
+    Minimal JSON-friendly conversion for common scalars.
+    Leave complex types as-is; transport may have its own encoder.
+    """
+    if v is None:
+        return None
+    if isinstance(v, (_dt.datetime, _dt.date, _dt.time)):
+        # ISO 8601
+        try:
+            return v.isoformat()
+        except Exception:
+            return str(v)
+    if isinstance(v, _uuid.UUID):
+        return str(v)
+    if isinstance(v, _dc.Decimal):
+        # Preserve precision via string
+        return str(v)
+    if isinstance(v, (bytes, bytearray, memoryview)):
+        try:
+            return base64.b64encode(bytes(v)).decode("ascii")
+        except Exception:
+            return None
+    # Plain containers → recurse shallowly
+    if isinstance(v, Mapping):
+        return {k: _dump_scalar(v[k]) for k in v}
+    if isinstance(v, list):
+        return [_dump_scalar(x) for x in v]
+    if isinstance(v, tuple):
+        return tuple(_dump_scalar(x) for x in v)
+    return v
+
+
+__all__ = ["ANCHOR", "run"]