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

tigrbl/runtime/atoms/emit/paired_post.py

@@ -0,0 +1,158 @@
+# tigrbl/v3/runtime/atoms/emit/paired_post.py
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+import logging
+
+from ... import events as _ev
+
+# Runs after DB flush + refresh, before out model construction.
+ANCHOR = _ev.EMIT_ALIASES_POST  # "emit:aliases:post_refresh"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    emit:paired_post@emit:aliases:post_refresh
+
+    Purpose
+    -------
+    Resolve *deferred* alias emissions prepared by emit:paired_pre. For each pending
+    descriptor, look up the generated raw value (typically created by resolve:paired_gen),
+    copy it into a response-extras buffer, and scrub the raw from temp to enforce
+    the secret-once rule.
+
+    Inputs / Conventions
+    --------------------
+    - ctx.temp["emit_aliases"]["pre"] : list of descriptors from paired_pre
+        { "field": str, "alias": str, "source": ("paired_values", field, "raw"), "meta": {...} }
+    - ctx.temp["paired_values"]      : { field: {"raw": <value>, "meta"?: {...}, ...}, ... }
+    - ctx.persist                    : bool (this anchor should be pruned when False)
+    - ctx.temp["response_extras"]    : dict aggregated here for out-building
+
+    Effects
+    -------
+    - Appends alias/value into ctx.temp["response_extras"][alias] = value
+    - Appends a redacted audit descriptor to ctx.temp["emit_aliases"]["post"]
+    - Scrubs ctx.temp["paired_values"][field]["raw"] after emission (secret-once)
+    - Clears "pre" queue after processing
+    """
+    # Non-persisting ops should have pruned this anchor via the planner,
+    # but guard anyway for robustness.
+    logger.debug("Running emit:paired_post")
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping emit:paired_post; ctx.persist is False")
+        return
+
+    temp = _ensure_temp(ctx)
+    emit_buf = _ensure_emit_buf(temp)
+    pre_queue = list(emit_buf.get("pre") or ())
+    if not pre_queue:
+        logger.debug("No deferred aliases to emit")
+        return
+
+    pv = _get_paired_values(temp)
+    extras = _ensure_response_extras(temp)
+
+    for desc in pre_queue:
+        if not isinstance(desc, dict):
+            logger.debug("Skipping non-dict descriptor: %s", desc)
+            continue
+        field = desc.get("field")
+        alias = desc.get("alias")
+        if not isinstance(field, str) or not isinstance(alias, str) or not field:
+            logger.debug("Descriptor missing valid field/alias: %s", desc)
+            continue
+
+        value = _resolve_value_from_source(desc.get("source"), pv, field)
+        if value is None:
+            logger.debug("No value resolved for field %s; skipping", field)
+            continue
+
+        logger.debug("Emitting alias '%s' for field '%s'", alias, field)
+        # 1) Emit into response extras (to be merged by wire/out stages)
+        extras[alias] = value
+
+        # 2) Record a minimal (redacted) audit entry; do NOT keep raw value here
+        emit_buf["post"].append(
+            {
+                "field": field,
+                "alias": alias,
+                "emitted": True,
+                "meta": (desc.get("meta") or {}),
+            }
+        )
+
+        # 3) Enforce secret-once: scrub raw so later steps cannot re-emit accidentally
+        _scrub_paired_raw(pv, field)
+        logger.debug("Scrubbed paired raw for field '%s'", field)
+
+    # All pre-emit descriptors consumed
+    emit_buf["pre"].clear()
+    logger.debug("Cleared pre-emit queue")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_temp(ctx: Any) -> MutableMapping[str, Any]:
+    temp = getattr(ctx, "temp", None)
+    if not isinstance(temp, dict):
+        temp = {}
+        setattr(ctx, "temp", temp)
+    return temp
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _ensure_response_extras(temp: MutableMapping[str, Any]) -> Dict[str, Any]:
+    extras = temp.get("response_extras")
+    if not isinstance(extras, dict):
+        extras = {}
+        temp["response_extras"] = extras
+    return extras  # type: ignore[return-value]
+
+
+def _get_paired_values(temp: Mapping[str, Any]) -> Dict[str, Dict[str, Any]]:
+    pv = temp.get("paired_values")
+    return pv if isinstance(pv, dict) else {}
+
+
+def _resolve_value_from_source(
+    source: Any, pv: Mapping[str, Dict[str, Any]], field: str
+) -> Optional[Any]:
+    """
+    Resolve the value indicated by a ('paired_values', field, 'raw')-style pointer.
+    Falls back to pv[field]['raw'] when source is missing/malformed.
+    """
+    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")
+    # Fallback
+    return pv.get(field, {}).get("raw")
+
+
+def _scrub_paired_raw(pv: MutableMapping[str, Dict[str, Any]], field: str) -> None:
+    entry = pv.get(field)
+    if not isinstance(entry, dict):
+        return
+    # Remove raw, mark emitted
+    entry.pop("raw", None)
+    entry["emitted"] = True
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/emit/paired_pre.py

@@ -0,0 +1,106 @@
+# tigrbl/v3/runtime/atoms/emit/paired_pre.py
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, _ensure_temp
+
+# This atom runs before the flush, after values have been assembled/generated.
+ANCHOR = _ev.EMIT_ALIASES_PRE  # "emit:aliases:pre_flush"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    emit:paired_pre@emit:aliases:pre_flush
+
+    Purpose
+    -------
+    Prepare *deferred* alias emissions for "paired" values (e.g., secret-once raw tokens)
+    that were generated earlier (typically by resolve:paired_gen) and stored on
+    ctx.temp["paired_values"] = { <field>: {"raw": <value>, "alias"?: <str>, "meta"?: {...}} }.
+
+    This atom:
+      - Ensures ctx.temp["emit_aliases"] = {"pre": [], "post": [], "read": []}
+      - Scans paired_values and pushes *deferred* emit specs into "pre"
+        so that emit:paired_post can resolve them after flush/refresh and
+        attach to the outbound payload/extras safely.
+
+    Contracts / Conventions
+    -----------------------
+    - ctx.temp is a dict-like scratch space shared across atoms.
+    - paired_values entries may provide an explicit "alias"; otherwise we infer one
+      using OpView metadata; if nothing is available, we default to the field name.
+    - This atom is a no-op when there are no paired values.
+
+    It is safe to call multiple times; it only appends idempotent descriptors.
+    """
+    # Non-persisting ops should have pruned this anchor via the planner,
+    # but guard anyway for robustness.
+    logger.debug("Running emit:paired_pre")
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping emit:paired_pre; ctx.persist is False")
+        return
+
+    temp = _ensure_temp(ctx)
+    emit_buf = _ensure_emit_buf(temp)
+    paired = _get_paired_values(temp)
+
+    if not paired:
+        logger.debug("No paired values found; nothing to schedule")
+        return
+
+    ov = opview_from_ctx(ctx)
+
+    for field, entry in paired.items():
+        if not isinstance(entry, dict):
+            logger.debug(
+                "Skipping non-dict paired entry for field %s: %s", field, entry
+            )
+            continue
+        if "raw" not in entry:
+            logger.debug("Paired entry for field %s lacks raw value", field)
+            # nothing to emit
+            continue
+
+        desc = ov.paired_index.get(field, {})
+        alias = entry.get("alias") or desc.get("alias") or field
+
+        # Record a *deferred* emission descriptor; emit:paired_post will resolve it.
+        emit_buf["pre"].append(
+            {
+                "field": field,
+                "alias": alias,
+                "source": ("paired_values", field, "raw"),
+                "meta": entry.get("meta") or {},
+            }
+        )
+        logger.debug("Queued deferred alias '%s' for field '%s'", alias, field)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _get_paired_values(temp: Mapping[str, Any]) -> Mapping[str, Dict[str, Any]]:
+    pv = temp.get("paired_values")
+    return pv if isinstance(pv, dict) else {}
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/emit/readtime_alias.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out, _ensure_temp
+
+# Runs near the end of the lifecycle, before wire:dump/out:masking.
+ANCHOR = _ev.EMIT_ALIASES_READ  # "emit:aliases:readtime"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Emit safe read-time aliases into response extras."""
+    logger.debug("Running emit:readtime_alias")
+    temp = _ensure_temp(ctx)
+    emit_buf = _ensure_emit_buf(temp)
+    extras = _ensure_response_extras(temp)
+
+    ov = opview_from_ctx(ctx)
+    schema_out = ensure_schema_out(ctx, ov)
+    for field, desc in schema_out["by_field"].items():
+        out_alias = desc.get("alias_out")
+        if not out_alias:
+            continue
+        if out_alias in extras:
+            logger.debug("Alias %s already present in extras; skipping", out_alias)
+            continue
+
+        value = _read_current_value(obj, ctx, field)
+        if value is None:
+            logger.debug("No current value available for field %s", field)
+            continue
+
+        safe_val = _safe_readtime_value(value, desc)
+        extras[out_alias] = safe_val
+        logger.debug("Emitted read-time alias '%s' for field '%s'", out_alias, field)
+
+        emit_buf["read"].append(
+            {
+                "field": field,
+                "alias": out_alias,
+                "emitted": True,
+                "meta": _alias_meta(desc),
+            }
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _ensure_response_extras(temp: MutableMapping[str, Any]) -> Dict[str, Any]:
+    extras = temp.get("response_extras")
+    if not isinstance(extras, dict):
+        extras = {}
+        temp["response_extras"] = extras
+    return extras  # type: ignore[return-value]
+
+
+def _alias_meta(desc: Mapping[str, Any]) -> Dict[str, Any]:
+    meta: Dict[str, Any] = {}
+    for attr in ("sensitive", "mask_last"):
+        if attr in desc:
+            meta[attr] = desc[attr]
+    return meta
+
+
+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
+
+
+def _mask_value(value: Any, keep_last: Optional[int]) -> str:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return "••••"
+    s = str(value) if value is not None else ""
+    if not s:
+        return ""
+    n = keep_last if (isinstance(keep_last, int) and keep_last >= 0) else 4
+    n = min(n, len(s))
+    return "•" * (len(s) - n) + s[-n:]
+
+
+def _safe_readtime_value(value: Any, desc: Mapping[str, Any]) -> Any:
+    if desc.get("sensitive"):
+        keep_last = desc.get("mask_last")
+        return _mask_value(value, keep_last)
+    return value
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/out/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/runtime/atoms/out/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import masking as _masking
+
+# 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).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("out", "masking"): (_masking.ANCHOR, _masking.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 'out' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'out' domain."""
+    key = ("out", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown out atom subject: {subject!r}")
+    logger.debug("Retrieving 'out' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/out/masking.py

@@ -0,0 +1,135 @@
+# tigrbl/v3/runtime/atoms/out/masking.py
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Sequence
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out, _ensure_temp
+
+# Runs at the very end of the lifecycle (after wire:dump).
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    out:masking@out:dump
+
+    Purpose
+    -------
+    Mask sensitive top-level fields in the already-built response payload.
+    This runs AFTER wire:dump so the payload exists and after emit:readtime_alias
+    so alias extras are already present. It does NOT redact explicitly emitted
+    alias extras (e.g., secret-once raw tokens) — those are intentional.
+
+    Inputs / Conventions
+    --------------------
+    - ctx.temp["response_payload"] : dict or list[dict] (produced by wire:dump)
+    - ctx.temp["emit_aliases"]["post"] / ["read"] : lists of descriptors that
+      include {"alias": "..."}; these alias keys are skipped (not masked).
+
+    Effects
+    -------
+    - For each payload item (dict), if a key equals a ColumnSpec field name and
+      that column is marked sensitive (via `sensitive`/`redact`/`redact_last`),
+      replace the value with a masked hint.
+    - Leaves alias extras untouched (based on the alias sets captured from
+      emit_aliases.post/read).
+    """
+    logger.debug("Running out:masking")
+    ov = opview_from_ctx(ctx)
+    schema_out = ensure_schema_out(ctx, ov)
+
+    temp = _ensure_temp(ctx)
+    payload = temp.get("response_payload")
+    if payload is None:
+        logger.debug("No response payload found; skipping masking")
+        return
+    logger.debug("Original payload before masking: %s", payload)
+
+    emit_buf = _ensure_emit_buf(temp)
+    skip_aliases = _collect_emitted_aliases(emit_buf)
+
+    if isinstance(payload, dict):
+        logger.debug("Masking single-object payload")
+        _mask_one(payload, schema_out["by_field"], skip_aliases)
+    elif isinstance(payload, (list, tuple)):
+        logger.debug("Masking list payload with %d items", len(payload))
+        for item in payload:
+            if isinstance(item, dict):
+                _mask_one(item, schema_out["by_field"], skip_aliases)
+            else:
+                logger.debug("Skipping non-dict item in payload: %s", item)
+    else:
+        logger.debug(
+            "Unsupported payload type %s; leaving as-is", type(payload).__name__
+        )
+
+    logger.debug("Payload after masking: %s", payload)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _collect_emitted_aliases(
+    emit_buf: Mapping[str, Sequence[Mapping[str, Any]]],
+) -> set[str]:
+    aliases: set[str] = set()
+    for bucket in ("post", "read"):
+        for d in emit_buf.get(bucket, ()) or ():
+            a = d.get("alias")
+            if isinstance(a, str) and a:
+                aliases.add(a)
+    return aliases
+
+
+def _mask_one(
+    item: Dict[str, Any],
+    by_field: Mapping[str, Mapping[str, Any]],
+    skip_aliases: set[str],
+) -> None:
+    for field, desc in by_field.items():
+        if field not in item or field in skip_aliases:
+            continue
+        val = item.get(field, None)
+        if val is None:
+            continue
+        if not (desc.get("sensitive") or desc.get("mask_last") is not None):
+            continue
+        masked = _mask_value(val, desc.get("mask_last"))
+        logger.debug("Masking field '%s': %r -> %r", field, val, masked)
+        item[field] = masked
+    logger.debug("Item after masking: %s", item)
+
+
+def _mask_value(value: Any, keep_last: Optional[int]) -> str:
+    """
+    Generic masking for strings/bytes; falls back to a fixed token when unknown.
+    """
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return "••••"
+    s = str(value) if value is not None else ""
+    if not s:
+        return ""
+    n = keep_last if (isinstance(keep_last, int) and keep_last >= 0) else 4
+    n = min(n, len(s))
+    return "•" * (len(s) - n) + s[-n:]
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/refresh/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/runtime/atoms/refresh/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import demand as _demand
+
+# 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).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("refresh", "demand"): (_demand.ANCHOR, _demand.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 'refresh' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'refresh' domain."""
+    key = ("refresh", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown refresh atom subject: {subject!r}")
+    logger.debug("Retrieving 'refresh' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]