tigrbl-kernel 0.1.0__py3-none-any.whl

tigrbl_kernel/atoms.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+import logging
+import pkgutil
+from types import SimpleNamespace
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    cast,
+)
+
+from tigrbl_typing.phases import HOOK_PHASES as HOOK_PHASES
+
+from tigrbl_atoms import StepFn
+from . import events as _ev, ordering as _ordering
+
+logger = logging.getLogger(__name__)
+
+_AtomRun = Callable[[Optional[object], Any], Any]
+_DiscoveredAtom = tuple[str, _AtomRun]
+
+
+def _discover_atoms() -> list[_DiscoveredAtom]:
+    out: list[_DiscoveredAtom] = []
+    try:
+        import tigrbl_atoms.atoms as atoms_pkg  # type: ignore
+    except Exception:
+        return out
+
+    for info in pkgutil.walk_packages(atoms_pkg.__path__, atoms_pkg.__name__ + "."):  # type: ignore[attr-defined]
+        if info.ispkg:
+            continue
+        try:
+            mod = importlib.import_module(info.name)
+            instance = getattr(mod, "INSTANCE", None)
+            if instance is not None and callable(instance):
+                anchor = getattr(instance, "anchor", None) or getattr(
+                    mod, "ANCHOR", None
+                )
+                if isinstance(anchor, str):
+                    out.append((anchor, cast(_AtomRun, instance)))
+                    continue
+            anchor = getattr(mod, "ANCHOR", None)
+            run = getattr(mod, "run", None)
+            if isinstance(anchor, str) and callable(run):
+                out.append((anchor, cast(_AtomRun, run)))
+        except Exception:
+            continue
+    logger.debug("kernel: discovered %d atoms", len(out))
+    return out
+
+
+def _infer_domain_subject(run: _AtomRun) -> tuple[Optional[str], Optional[str]]:
+    mod = getattr(run, "__module__", "") or ""
+    parts = mod.split(".")
+    try:
+        i = parts.index("atoms")
+        return (
+            parts[i + 1] if i + 1 < len(parts) else None,
+            parts[i + 2] if i + 2 < len(parts) else None,
+        )
+    except ValueError:
+        return None, None
+
+
+def _make_label(anchor: str, run: _AtomRun) -> Optional[str]:
+    domain, subject = _infer_domain_subject(run)
+    return f"atom:{domain}:{subject}@{anchor}" if (domain and subject) else None
+
+
+def _wrap_atom(run: _AtomRun, *, anchor: str) -> StepFn:
+    use_two_args = True
+    try:
+        params = tuple(inspect.signature(run).parameters.values())
+        positional = [
+            p
+            for p in params
+            if p.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ]
+        use_two_args = len(positional) != 1
+    except (TypeError, ValueError):
+        use_two_args = True
+
+    async def _step(ctx: Any) -> Any:
+        rv = run(None, ctx) if use_two_args else run(ctx)  # type: ignore[misc]
+        if inspect.isawaitable(rv):
+            return await cast(Any, rv)
+        return rv
+
+    label = getattr(run, "__tigrbl_label", None)
+    if not isinstance(label, str):
+        label = _make_label(anchor, run)
+    if label:
+        setattr(_step, "__tigrbl_label", label)
+    return _step
+
+
+def _hook_phase_chains(model: type, alias: str) -> Dict[str, List[StepFn]]:
+    hooks_root = getattr(model, "hooks", None) or SimpleNamespace()
+    alias_ns = getattr(hooks_root, alias, None)
+    out: Dict[str, List[StepFn]] = {ph: [] for ph in HOOK_PHASES}
+    if alias_ns is None:
+        return out
+    for phase in HOOK_PHASES:
+        out[phase] = list(getattr(alias_ns, phase, []) or [])
+    return out
+
+
+def _is_persistent(chains: Mapping[str, Sequence[StepFn]]) -> bool:
+    for fn in chains.get("START_TX", ()) or ():
+        if getattr(fn, "__name__", "") == "start_tx":
+            return True
+    for fn in chains.get("PRE_TX_BEGIN", ()) or ():
+        if getattr(fn, "__name__", "") == "mark_skip_persist":
+            return False
+    return False
+
+
+def _label_dep_atom(*, kind: str, index: int, anchor: str) -> str:
+    return f"hook:dep:{kind}:{index}@{anchor}"
+
+
+def _make_dep_atom_step(run_fn: _AtomRun, dep: Any, *, label: str) -> StepFn:
+    async def _step(ctx: Any) -> Any:
+        rv = run_fn(dep, ctx)
+        if hasattr(rv, "__await__"):
+            return await cast(Any, rv)
+        return rv
+
+    setattr(_step, "__tigrbl_label", label)
+    return _step
+
+
+def _inject_pre_tx_dep_atoms(chains: Dict[str, List[StepFn]], sp: Any | None) -> None:
+    if sp is None:
+        return
+    try:
+        from tigrbl_atoms.atoms.dep.security import INSTANCE as sec_run  # type: ignore
+        from tigrbl_atoms.atoms.dep.extra import INSTANCE as dep_run  # type: ignore
+    except Exception:
+        try:
+            from tigrbl_atoms.atoms.dep.security import run as sec_run  # type: ignore
+            from tigrbl_atoms.atoms.dep.extra import run as dep_run  # type: ignore
+        except Exception:
+            return
+
+    pre_tx = chains.setdefault("PRE_TX_BEGIN", [])
+    for idx, dep in enumerate(getattr(sp, "secdeps", ()) or ()):
+        pre_tx.append(
+            _make_dep_atom_step(
+                sec_run,
+                dep,
+                label=_label_dep_atom(
+                    kind="security", index=idx, anchor=_ev.DEP_SECURITY
+                ),
+            )
+        )
+    for idx, dep in enumerate(getattr(sp, "deps", ()) or ()):
+        pre_tx.append(
+            _make_dep_atom_step(
+                dep_run,
+                dep,
+                label=_label_dep_atom(kind="extra", index=idx, anchor=_ev.DEP_EXTRA),
+            )
+        )
+
+
+def _inject_atoms(
+    chains: Dict[str, List[StepFn]],
+    atoms: Iterable[_DiscoveredAtom],
+    *,
+    persistent: bool,
+    target: str | None = None,
+) -> None:
+    order = {name: i for i, name in enumerate(_ev.all_events_ordered())}
+
+    def _sort_key(item: _DiscoveredAtom) -> tuple[int, int]:
+        anchor, run = item
+        anchor_idx = order.get(anchor, 10_000)
+        domain, subject = _infer_domain_subject(run)
+        token = f"{domain}:{subject}" if domain and subject else ""
+        pref = _ordering._PREF.get(anchor, ())
+        token_idx = pref.index(token) if token in pref else 10_000
+        return anchor_idx, token_idx
+
+    for anchor, run in sorted(atoms, key=_sort_key):
+        if _ev.is_valid_event(anchor):
+            info = _ev.get_anchor_info(anchor)
+            phase = info.phase
+            persist_tied = info.persist_tied
+        elif anchor == "INGRESS_ROUTE":
+            # Back-compat phase alias retained for route-stage atom injection.
+            phase = "INGRESS_ROUTE"
+            persist_tied = False
+        elif anchor in _ev.PHASES:
+            phase = anchor
+            persist_tied = False
+        elif anchor == "INGRESS_ROUTE":
+            # Compatibility alias retained for tests and legacy direct callers.
+            # Canonical runtime ingress routing phase is INGRESS_DISPATCH.
+            phase = anchor
+            persist_tied = False
+        else:
+            continue
+
+        domain, _subject = _infer_domain_subject(run)
+        if not persistent and persist_tied:
+            if not (
+                domain == "sys"
+                and isinstance(_subject, str)
+                and _subject.startswith("handler_")
+            ):
+                continue
+        if (
+            domain == "sys"
+            and isinstance(_subject, str)
+            and _subject.startswith("handler_")
+        ):
+            handler_target = _subject.removeprefix("handler_")
+            if handler_target != "persistence" and target and handler_target != target:
+                continue
+        if domain == "dep":
+            continue
+
+        chains.setdefault(phase, []).append(_wrap_atom(run, anchor=anchor))

tigrbl_kernel/cache.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import threading
+import weakref
+from typing import Any, Dict, Generic, Mapping, Optional, Sequence, TypeVar
+
+from tigrbl_core._spec.column_spec import mro_collect_columns
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class _WeakMaybeDict(Generic[K, V]):
+    """Dictionary that uses weak references when possible.
+
+    Falls back to strong references when ``key`` cannot be weakly referenced.
+    """
+
+    def __init__(self) -> None:
+        self._weak: "weakref.WeakKeyDictionary[Any, V]" = weakref.WeakKeyDictionary()
+        self._strong: Dict[int, tuple[Any, V]] = {}
+
+    def _use_weak(self, key: Any) -> bool:
+        try:
+            weakref.ref(key)
+            return True
+        except TypeError:
+            return False
+
+    def __setitem__(self, key: K, value: V) -> None:
+        if self._use_weak(key):
+            self._weak[key] = value
+        else:
+            self._strong[id(key)] = (key, value)
+
+    def __getitem__(self, key: K) -> V:
+        if self._use_weak(key):
+            return self._weak[key]
+        return self._strong[id(key)][1]
+
+    def get(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        if self._use_weak(key):
+            return self._weak.get(key, default)
+        return self._strong.get(id(key), (None, default))[1]
+
+    def setdefault(self, key: K, default: V) -> V:
+        if self._use_weak(key):
+            return self._weak.setdefault(key, default)
+        return self._strong.setdefault(id(key), (key, default))[1]
+
+    def pop(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        if self._use_weak(key):
+            return self._weak.pop(key, default)
+        return self._strong.pop(id(key), (None, default))[1]
+
+
+class _SpecsOnceCache:
+    """Thread-safe, compute-once cache of per-model column specs."""
+
+    def __init__(self) -> None:
+        self._d: Dict[type, Mapping[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, model: type) -> Mapping[str, Any]:
+        try:
+            return self._d[model]
+        except KeyError:
+            pass
+        with self._lock:
+            rv = self._d.get(model)
+            if rv is None:
+                rv = mro_collect_columns(model)
+                self._d[model] = rv
+        return rv
+
+    def prime(self, models: Sequence[type]) -> None:
+        for model in models:
+            self.get(model)
+
+    def invalidate(self, model: Optional[type] = None) -> None:
+        with self._lock:
+            if model is None:
+                self._d.clear()
+            else:
+                self._d.pop(model, None)

tigrbl_kernel/core.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import logging
+import threading
+from types import SimpleNamespace
+from typing import Any, ClassVar, Mapping, Optional, Sequence
+
+
+from . import events as _ev
+from ._build import (
+    _build_route_matrix,
+    _pack_kernel_plan,
+    _segment_label,
+    _build,
+    _build_egress,
+    _build_ingress,
+    _build_op,
+    _compile_bootstrap_plan,
+    _plan_labels,
+)
+from ._compile import _compile_opview_from_specs, _compile_plan
+from .atoms import _DiscoveredAtom, _discover_atoms
+from .cache import _SpecsOnceCache, _WeakMaybeDict
+from .models import KernelPlan, OpView
+from .opview_compiler import compile_opview_from_specs
+from .types import DEFAULT_PHASE_ORDER as _DEFAULT_PHASE_ORDER
+from .utils import (
+    _opspecs,
+    _table_iter,
+)
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_PHASE_ORDER = tuple(getattr(_ev, "PHASES", ())) or _DEFAULT_PHASE_ORDER
+
+
+class Kernel:
+    _instance: ClassVar["Kernel | None"] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Kernel":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None):
+        if atoms is None and getattr(self, "_singleton_initialized", False):
+            self._reset(atoms)
+            return
+        self._reset(atoms)
+        if atoms is None:
+            self._singleton_initialized = True
+
+    def _reset(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None) -> None:
+        self._atoms_cache = list(atoms) if atoms else None
+        self._specs_cache = _SpecsOnceCache()
+        self._opviews = _WeakMaybeDict()
+        self._phase_chains = _WeakMaybeDict()
+        self._phase_chains_by_id: dict[int, dict[str, tuple[Any, Any]]] = {}
+        self._kernel_plans = _WeakMaybeDict()
+        self._kernelz_payload = _WeakMaybeDict()
+        self._primed = _WeakMaybeDict()
+        self._lock = threading.Lock()
+
+    def _atoms(self) -> list[_DiscoveredAtom]:
+        if self._atoms_cache is None:
+            self._atoms_cache = _discover_atoms()
+        return self._atoms_cache
+
+    def get_specs(self, model: type) -> Mapping[str, Any]:
+        return self._specs_cache.get(model)
+
+    def plan_labels(self, model: type, alias: str) -> list[str]:
+        return self._plan_labels(model, alias)
+
+    def prime_specs(self, models: Sequence[type]) -> None:
+        self._specs_cache.prime(models)
+
+    def invalidate_specs(self, model: Optional[type] = None) -> None:
+        self._specs_cache.invalidate(model)
+
+    def ensure_primed(self, app: Any) -> None:
+        if self._primed.get(app):
+            return
+        with self._lock:
+            if self._primed.get(app):
+                return
+            self.prime_specs(_table_iter(app))
+            self._kernel_plans.pop(app, None)
+            self._kernelz_payload.pop(app, None)
+            self._opviews.pop(app, None)
+            self._phase_chains.pop(app, None)
+            self._phase_chains_by_id.clear()
+            self._primed[app] = True
+
+    def get_opview(self, app: Any, model: type, alias: str) -> OpView:
+        ov_map = self._opviews.get(app)
+        if isinstance(ov_map, dict):
+            opview = ov_map.get((model, alias))
+            if opview is not None:
+                return opview
+
+        self.ensure_primed(app)
+
+        ov_map = self._opviews.setdefault(app, {})
+        opview = ov_map.get((model, alias))
+        if opview is not None:
+            return opview
+
+        try:
+            specs = self._specs_cache.get(model)
+            found = False
+            for sp in _opspecs(model):
+                ov_map.setdefault(
+                    (model, sp.alias), compile_opview_from_specs(specs, sp)
+                )
+                if sp.alias == alias:
+                    found = True
+
+            if not found:
+                temp_sp = SimpleNamespace(alias=alias)
+                ov_map[(model, alias)] = compile_opview_from_specs(specs, temp_sp)
+
+            return ov_map[(model, alias)]
+        except Exception as exc:
+            raise RuntimeError(
+                f"opview_missing: app={app!r} model={getattr(model, '__name__', model)!r} alias={alias!r}"
+            ) from exc
+
+    def kernel_plan(self, app: Any) -> KernelPlan:
+        self.ensure_primed(app)
+        plan = self._kernel_plans.get(app)
+        if isinstance(plan, KernelPlan):
+            return plan
+
+        compiled = self.compile_plan(app)
+        self._kernel_plans[app] = compiled
+
+        payload: dict[str, dict[str, list[str]]] = {}
+        for model in _table_iter(app):
+            model_name = getattr(model, "__name__", str(model))
+            payload[model_name] = {}
+            for sp in _opspecs(model):
+                payload[model_name][sp.alias] = self._plan_labels(model, sp.alias)
+        self._kernelz_payload[app] = payload
+
+        return compiled
+
+    def kernelz_payload(self, app: Any) -> dict[str, dict[str, list[str]]]:
+        self.kernel_plan(app)
+        payload = self._kernelz_payload.get(app)
+        if isinstance(payload, dict):
+            return payload
+        return {}
+
+    def invalidate_kernelz_payload(self, app: Optional[Any] = None) -> None:
+        with self._lock:
+            if app is None:
+                self._kernel_plans = _WeakMaybeDict()
+                self._kernelz_payload = _WeakMaybeDict()
+                self._opviews = _WeakMaybeDict()
+                self._phase_chains = _WeakMaybeDict()
+                self._phase_chains_by_id = {}
+                self._primed = _WeakMaybeDict()
+            else:
+                self._kernel_plans.pop(app, None)
+                self._kernelz_payload.pop(app, None)
+                self._opviews.pop(app, None)
+                self._phase_chains.pop(app, None)
+                self._phase_chains_by_id.clear()
+                self._primed.pop(app, None)
+
+
+Kernel._build_op = _build_op
+Kernel._build = _build
+Kernel._build_ingress = _build_ingress
+Kernel._build_egress = _build_egress
+Kernel._plan_labels = _plan_labels
+Kernel._compile_bootstrap_plan = _compile_bootstrap_plan
+Kernel._segment_label = _segment_label
+Kernel._build_route_matrix = _build_route_matrix
+Kernel._pack_kernel_plan = _pack_kernel_plan
+
+Kernel.compile_plan = _compile_plan
+Kernel.compile_bootstrap_plan = _compile_bootstrap_plan
+Kernel._compile_opview_from_specs = _compile_opview_from_specs

tigrbl_kernel/events.py

@@ -0,0 +1,6 @@
+"""Compatibility wrapper for canonical runtime event anchors.
+
+Canonical event anchors and ordering now live in ``tigrbl_atoms.events``.
+"""
+
+from tigrbl_atoms.events import *  # noqa: F403

tigrbl_kernel/helpers.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import Any, Iterable, Mapping, Optional, Sequence
+
+try:
+    from tigrbl_kernel import trace as _trace  # type: ignore
+except Exception:  # pragma: no cover
+    _trace = None  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_payload(payload: Any) -> Any:
+    if isinstance(payload, (str, int, float, bool)) or payload is None:
+        return payload
+    if isinstance(payload, dict):
+        return {str(k): _normalize_payload(v) for k, v in payload.items()}
+    if isinstance(payload, (list, tuple, set)):
+        return [_normalize_payload(v) for v in payload]
+
+    model_dump = getattr(payload, "model_dump", None)
+    if callable(model_dump):
+        try:
+            return _normalize_payload(model_dump())
+        except Exception:
+            pass
+
+    obj_dict = getattr(payload, "__dict__", None)
+    if isinstance(obj_dict, dict):
+        data = {
+            k: v
+            for k, v in obj_dict.items()
+            if not k.startswith("_") and not callable(v)
+        }
+        if data:
+            return _normalize_payload(data)
+
+    return str(payload)
+
+
+async def _maybe_await(v: Any) -> Any:
+    if inspect.isawaitable(v):
+        return await v  # type: ignore[func-returns-value]
+    return v
+
+
+def _trace_ready(ctx: Any) -> bool:
+    if _trace is None:
+        return False
+    temp = getattr(ctx, "temp", None)
+    return isinstance(temp, dict) and "__trace__" in temp
+
+
+async def _run_chain(ctx: Any, chain: Optional[Iterable[Any]], *, phase: str) -> None:
+    temp = getattr(ctx, "temp", None)
+    if isinstance(temp, dict) and temp.get("rpc_short_circuit"):
+        if phase not in {"EGRESS_SHAPE", "EGRESS_FINALIZE", "POST_RESPONSE"}:
+            return
+
+    if not chain:
+        return
+
+    isawaitable = inspect.isawaitable
+    trace_active = _trace_ready(ctx)
+
+    for idx, step in enumerate(chain):
+        label = getattr(step, "__tigrbl_label", None)
+        if not isinstance(label, str) or not label:
+            label = f"phase:{phase}:step:{idx}"
+
+        seq = _trace.start(ctx, label) if trace_active else None
+        before_post_response = None
+        if phase == "POST_RESPONSE":
+            response = getattr(ctx, "response", None)
+            before_value = getattr(response, "result", None)
+            if before_value is None:
+                before_value = ctx.get("result")
+            before_post_response = _normalize_payload(before_value)
+
+        try:
+            rv = step(ctx)
+            if isawaitable(rv):
+                rv = await rv  # type: ignore[func-returns-value]
+            if rv is not None and rv is not ctx:
+                ctx.result = rv
+            if trace_active:
+                _trace.end(ctx, seq, status=_trace.OK)
+
+            if (
+                phase == "POST_RESPONSE"
+                and getattr(step, "__tigrbl_label", None) is None
+            ):
+                temp_ns = getattr(ctx, "temp", None)
+                if not isinstance(temp_ns, dict):
+                    continue
+
+                egress = temp_ns.get("egress")
+                if not isinstance(egress, dict):
+                    continue
+
+                response = getattr(ctx, "response", None)
+                result = getattr(response, "result", None)
+                if result is None:
+                    result = ctx.get("result")
+                else:
+                    ctx.result = result
+
+                if result is None:
+                    continue
+                if hasattr(result, "status_code") and hasattr(result, "body"):
+                    continue
+                if isinstance(result, dict) and any(
+                    key in result for key in ("status_code", "headers", "body")
+                ):
+                    continue
+
+                safe_result = _normalize_payload(result)
+                if safe_result == before_post_response:
+                    continue
+
+                egress["wire_payload"] = safe_result
+                enveloped = egress.get("enveloped")
+                if isinstance(enveloped, dict) and "result" in enveloped:
+                    enveloped["result"] = safe_result
+                elif enveloped is not None and not isinstance(enveloped, dict):
+                    egress["enveloped"] = safe_result
+
+                transport_response = egress.get("transport_response")
+                if isinstance(transport_response, dict):
+                    transport_response["body"] = egress.get("enveloped", safe_result)
+        except Exception as exc:
+            temp = getattr(ctx, "temp", None)
+            route = temp.get("route") if isinstance(temp, dict) else None
+            rpc_env = route.get("rpc_envelope") if isinstance(route, dict) else None
+            if isinstance(rpc_env, Mapping):
+                ctx.status_code = 200
+                ctx.result = None
+                if isinstance(temp, dict):
+                    temp["rpc_short_circuit"] = True
+                    if not isinstance(temp.get("rpc_error"), dict):
+                        builder = ctx.get("rpc_error_builder")
+                        if callable(builder):
+                            try:
+                                temp["rpc_error"] = builder(exc)
+                            except Exception:
+                                temp["rpc_error"] = {"message": str(exc)}
+                        else:
+                            temp["rpc_error"] = {"message": str(exc)}
+                if trace_active:
+                    _trace.attach_error(ctx, seq, exc)
+                    _trace.end(ctx, seq, status=_trace.ERROR)
+                return
+            if trace_active:
+                _trace.attach_error(ctx, seq, exc)
+                _trace.end(ctx, seq, status=_trace.ERROR)
+            raise
+
+
+def _g(phases: Optional[Mapping[str, Sequence[Any]]], key: str) -> Sequence[Any]:
+    return () if not phases else phases.get(key, ())
+
+
+__all__ = ["_maybe_await", "_run_chain", "_g"]

tigrbl_kernel/hook_types.py

@@ -0,0 +1,10 @@
+"""Kernel-owned hook type definitions.
+
+The kernel compiles plans and phase chains, but does not execute them.
+"""
+
+from __future__ import annotations
+
+from tigrbl_atoms import HookPhase, HookPhases, StepFn
+
+__all__ = ["HookPhase", "HookPhases", "StepFn"]