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

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

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