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

tigrbl/runtime/system.py

@@ -0,0 +1,279 @@
+# tigrbl/v3/runtime/system.py
+from __future__ import annotations
+
+import logging
+import inspect
+from typing import Any, Callable, Dict, Mapping, MutableMapping, Optional, Tuple
+
+from . import errors as _err
+from .executor.helpers import _in_tx, _is_async_db
+
+log = logging.getLogger(__name__)
+
+# Canonical anchors for system steps (ordering uses these symbolic anchors)
+START_TX = "START_TX"
+HANDLER = "HANDLER"
+END_TX = "END_TX"
+
+# Runner signature (matches atoms): (obj|None, ctx) -> None
+SysRunFn = Callable[[Optional[object], Any], None]
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Pluggable runners (adapters install real implementations at app startup)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+class _Installed:
+    begin: Optional[Callable[[Any], None]] = None  # (ctx) -> None
+    handler: Optional[Callable[[Optional[object], Any], None]] = (
+        None  # (obj, ctx) -> None
+    )
+    commit: Optional[Callable[[Any], None]] = None  # (ctx) -> None
+    rollback: Optional[Callable[[Any, BaseException | None], None]] = (
+        None  # (ctx, err) -> None
+    )
+
+
+INSTALLED = _Installed()  # singleton container
+
+
+def install(
+    *,
+    begin: Optional[Callable[[Any], None]] = None,
+    handler: Optional[Callable[[Optional[object], Any], None]] = None,
+    commit: Optional[Callable[[Any], None]] = None,
+    rollback: Optional[Callable[[Any, BaseException | None], None]] = None,
+) -> None:
+    """
+    Adapter entrypoint to install concrete system step functions.
+
+    Example (SQLAlchemy-ish pseudocode):
+        from tigrbl.runtime import system as sys
+        sys.install(
+            begin=lambda ctx: ctx.session.begin(),
+            handler=lambda obj, ctx: ctx.route_handler(obj, ctx),
+            commit=lambda ctx: ctx.session.commit(),
+            rollback=lambda ctx, err: ctx.session.rollback(),
+        )
+    """
+    if begin is not None:
+        INSTALLED.begin = begin
+    if handler is not None:
+        INSTALLED.handler = handler
+    if commit is not None:
+        INSTALLED.commit = commit
+    if rollback is not None:
+        INSTALLED.rollback = rollback
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Default implementations (safe no-ops except handler, which errs if missing)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _sys_tx_begin(_obj: Optional[object], ctx: Any) -> None:
+    """
+    sys:txn:begin — open a transaction/savepoint if the adapter installed a runner.
+    Defaults to no-op; sets a small flag for diagnostics.
+    """
+    log.debug("system: begin_tx enter")
+    _ensure_temp(ctx)
+    has_open = any(
+        callable(fn) for fn in (INSTALLED.begin, INSTALLED.commit, INSTALLED.rollback)
+    )
+    ctx.temp["__sys_tx_open__"] = has_open
+    try:
+        if callable(INSTALLED.begin):
+            INSTALLED.begin(ctx)
+            log.debug("system: begin_tx executed.")
+        else:
+            log.debug("system: begin_tx no-op (no adapter installed).")
+    except Exception as e:  # escalate as typed error
+        ctx.temp["__sys_tx_open__"] = False
+        raise _err.SystemStepError("Failed to begin transaction.", cause=e)
+    finally:
+        log.debug("system: begin_tx exit")
+
+
+def _sys_handler_crud(obj: Optional[object], ctx: Any) -> None:
+    """
+    sys:handler:crud — invoke the model/router handler.
+    Resolution order:
+      1) Installed adapter runner (INSTALLED.handler)
+      2) ctx.temp['handler'] if callable
+      3) getattr(ctx, 'handler')
+      4) getattr(ctx.model, 'runtime').handler or ctx.model.handler
+    On total miss, raises SystemStepError.
+    """
+    try:
+        # 1) Adapter-installed
+        if callable(INSTALLED.handler):
+            return INSTALLED.handler(obj, ctx)
+
+        # 2) From ctx.temp (explicitly staged by adapter)
+        h = _get_temp(ctx).get("handler")
+        if callable(h):
+            return h(obj, ctx)
+
+        # 3) Directly on ctx (adapters may set this)
+        h = getattr(ctx, "handler", None)
+        if callable(h):
+            return h(obj, ctx)
+
+        # 4) On the model (common pattern: Model.runtime.handler / Model.handler)
+        mdl = getattr(ctx, "model", None)
+        if mdl is not None:
+            r = getattr(getattr(mdl, "runtime", None), "handler", None)
+            if callable(r):
+                return r(obj, ctx)
+            r = getattr(mdl, "handler", None)
+            if callable(r):
+                return r(obj, ctx)
+
+        # No handler found
+        raise _err.SystemStepError(
+            "No handler is installed or discoverable for this operation."
+        )
+
+    except _err.TigrblError:
+        # Pass through typed errors intact
+        raise
+    except Exception as e:
+        raise _err.SystemStepError("Handler execution failed.", cause=e)
+
+
+async def _sys_tx_commit(_obj: Optional[object], ctx: Any) -> None:
+    """
+    sys:txn:commit — commit the transaction if begin ran and adapter installed commit.
+    Defaults to no-op; clears the 'open' flag.
+    """
+    log.debug("system: commit_tx enter")
+    _ensure_temp(ctx)
+    db = getattr(ctx, "db", None)
+    open_flag = bool(ctx.temp.get("__sys_tx_open__")) or (db is not None and _in_tx(db))
+    try:
+        if open_flag:
+            if callable(INSTALLED.commit):
+                rv = INSTALLED.commit(ctx)
+                if inspect.isawaitable(rv):
+                    await rv  # type: ignore[func-returns-value]
+                log.debug("system: commit_tx executed.")
+            else:
+                log.debug("system: commit_tx no-op (no adapter commit).")
+
+            if db is not None and _in_tx(db):
+                log.debug("system: commit_tx fallback commit executing.")
+                commit = getattr(db, "commit", None)
+                if callable(commit):
+                    try:
+                        if _is_async_db(db):
+                            await commit()  # type: ignore[misc]
+                        else:
+                            commit()
+                        log.debug("system: commit_tx fallback commit succeeded.")
+                    except Exception as e:  # pragma: no cover - defensive safeguard
+                        log.exception("system: commit_tx fallback commit failed: %s", e)
+                else:
+                    log.debug(
+                        "system: commit_tx fallback commit not possible (no commit attr)."
+                    )
+        else:
+            log.debug("system: commit_tx no-op (open=%s).", open_flag)
+    except Exception as e:
+        raise _err.SystemStepError("Failed to commit transaction.", cause=e)
+    finally:
+        ctx.temp["__sys_tx_open__"] = False
+        log.debug("system: commit_tx exit")
+
+
+def run_rollback(ctx: Any, err: BaseException | None = None) -> None:
+    """
+    Execute rollback logic when the kernel catches an exception.
+    Always safe to call (even if no begin was executed).
+    """
+    try:
+        if callable(INSTALLED.rollback):
+            INSTALLED.rollback(ctx, err)
+            log.debug("system: rollback executed.")
+        else:
+            # Best-effort fallback: try common session attribute
+            sess = getattr(ctx, "session", None)
+            rb = getattr(sess, "rollback", None)
+            if callable(rb):
+                rb()
+                log.debug("system: rollback via ctx.session.rollback().")
+    except Exception as e:  # Never mask the original error; log only.
+        log.exception("system: rollback failed: %s", e)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Registry & dispatch (mirrors atoms registry shape for consistency)
+# ──────────────────────────────────────────────────────────────────────────────
+
+REGISTRY: Dict[Tuple[str, str], Tuple[str, SysRunFn]] = {
+    ("txn", "begin"): (START_TX, _sys_tx_begin),
+    ("handler", "crud"): (HANDLER, _sys_handler_crud),
+    ("txn", "commit"): (END_TX, _sys_tx_commit),
+}
+
+
+def get(domain: str, subject: str) -> Tuple[str, SysRunFn]:
+    """
+    Return (anchor, runner) for a given system step, e.g., get('txn','begin').
+    """
+    key = (domain, subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown system step: {domain}:{subject}")
+    return REGISTRY[key]
+
+
+def subjects(domain: str | None = None) -> Tuple[Tuple[str, str], ...]:
+    """
+    Return the available (domain, subject) tuples, optionally filtered by domain.
+    """
+    items = tuple(sorted(REGISTRY.keys()))
+    if domain is None:
+        return items
+    return tuple(k for k in items if k[0] == domain)
+
+
+def all_items() -> Tuple[Tuple[Tuple[str, str], Tuple[str, SysRunFn]], ...]:
+    """Return the registry items as a sorted tuple (deterministic iteration)."""
+    return tuple(sorted(REGISTRY.items(), key=lambda kv: (kv[0][0], kv[0][1])))
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# 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 _get_temp(ctx: Any) -> Mapping[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    return tmp if isinstance(tmp, Mapping) else {}
+
+
+__all__ = [
+    # anchors
+    "START_TX",
+    "HANDLER",
+    "END_TX",
+    # install surface
+    "install",
+    "INSTALLED",
+    # rollback
+    "run_rollback",
+    # registry facade
+    "REGISTRY",
+    "get",
+    "subjects",
+    "all_items",
+]

tigrbl/runtime/trace.py

@@ -0,0 +1,330 @@
+# tigrbl/v3/runtime/trace.py
+from __future__ import annotations
+
+import datetime as _dt
+import random
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Sequence, Tuple
+
+# Public status constants
+OK = "ok"
+ERROR = "error"
+SKIPPED = "skipped"
+
+# Soft caps to avoid unbounded growth
+_MAX_STEPS = 5000
+_MAX_EVENTS = 2000
+_MAX_KV_KEYS = 16
+_MAX_SCALAR_LEN = 256
+
+
+@dataclass
+class _TraceState:
+    enabled: bool = True
+    sampled: bool = True
+    started_at: _dt.datetime = field(
+        default_factory=lambda: _dt.datetime.now(_dt.timezone.utc)
+    )
+    t0: float = field(default_factory=time.perf_counter)
+    seq: int = 0
+    steps: list[Dict[str, Any]] = field(default_factory=list)  # closed steps
+    events: list[Dict[str, Any]] = field(default_factory=list)  # loose events
+    open: Dict[int, Tuple[str, float, Dict[str, Any]]] = field(
+        default_factory=dict
+    )  # seq -> (label, t_start, base_kv)
+    plan_labels: Tuple[
+        str, ...
+    ] = ()  # optional: the full ordered plan (for diagnostics)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Public API
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def init(ctx: Any, *, plan_labels: Optional[Sequence[str]] = None) -> None:
+    """
+    Initialize tracing for this context. Called once by the kernel before executing the plan.
+    Respects cfg.trace.enabled and cfg.trace.sample_rate (0..1).
+    """
+    st = _get_state(ctx, create=True)
+
+    # Read config (tolerant to missing cfg/attrs)
+    cfg = getattr(ctx, "cfg", None)
+    enabled = True
+    sample_rate = 1.0
+    tr = getattr(cfg, "trace", None)
+    if tr is not None:
+        en = getattr(tr, "enabled", None)
+        if isinstance(en, bool):
+            enabled = en
+        sr = getattr(tr, "sample_rate", None)
+        if isinstance(sr, (int, float)):
+            sample_rate = max(0.0, min(1.0, float(sr)))
+
+    st.enabled = bool(enabled)
+    st.sampled = (random.random() < sample_rate) if st.enabled else False
+
+    if plan_labels:
+        st.plan_labels = tuple(str(x) for x in plan_labels[:_MAX_STEPS])
+
+
+def set_enabled(ctx: Any, enabled: bool) -> None:
+    """Force tracing on/off for this context."""
+    st = _get_state(ctx, create=True)
+    st.enabled = bool(enabled)
+    if not st.enabled:
+        st.sampled = False
+
+
+def start(ctx: Any, label: str, **kv: Any) -> int | None:
+    """
+    Start a trace span for a plan label. Returns a step id (seq) you should pass to end().
+    If tracing is disabled or not sampled, returns None.
+    """
+    st = _get_state(ctx)
+    if not _active(st):
+        return None
+    if len(st.steps) + len(st.open) >= _MAX_STEPS:
+        return None  # soft drop
+
+    seq = st.seq = st.seq + 1
+    base = _base_entry(label)
+    base["seq"] = seq
+    base.update(_safe_kv(kv))
+
+    t_start = time.perf_counter()
+    st.open[seq] = (label, t_start, base)
+    return seq
+
+
+def end(
+    ctx: Any, seq: int | None, status: str = OK, **kv: Any
+) -> Optional[Dict[str, Any]]:
+    """
+    End a previously started span by its seq id. Returns the finalized step dict.
+    If seq is None or tracing is inactive, this is a no-op.
+    """
+    st = _get_state(ctx)
+    if not _active(st) or seq is None:
+        return None
+
+    opened = st.open.pop(seq, None)
+    if opened is None:
+        return None  # already closed or never started
+
+    _label, t_start, base = opened
+    dur_ms = max(0.0, (time.perf_counter() - t_start) * 1000.0)
+
+    entry = dict(base)
+    entry["status"] = str(status or OK)
+    entry["dur_ms"] = round(dur_ms, 3)
+    # merge extra kv (sanitized), without clobbering base keys unintentionally
+    entry.update(_safe_kv(kv))
+
+    if len(st.steps) < _MAX_STEPS:
+        st.steps.append(entry)
+    return entry
+
+
+def event(ctx: Any, name: str, **kv: Any) -> None:
+    """Record an ad-hoc event (not tied to a plan label)."""
+    st = _get_state(ctx)
+    if not _active(st) or len(st.events) >= _MAX_EVENTS:
+        return
+    st.events.append(
+        {
+            "ts": _iso_now(),
+            "name": str(name),
+            **_safe_kv(kv),
+        }
+    )
+
+
+def attach_error(ctx: Any, seq: int | None, exc: BaseException) -> None:
+    """
+    Attach a compact, non-sensitive error summary to an open/closed step.
+    If `seq` is None or cannot be found, emits a free-standing 'error' event instead.
+    """
+    info = {
+        "err_type": exc.__class__.__name__,
+        "err_msg": _safe_scalar(getattr(exc, "detail", None)) or _safe_scalar(str(exc)),
+    }
+
+    st = _get_state(ctx)
+    if not _active(st):
+        return
+
+    # Try to update an open step first
+    if seq is not None and seq in st.open:
+        label, t_start, base = st.open[seq]
+        base.setdefault("error", info)
+        return
+
+    # Try to update the last closed step with matching seq
+    found = None
+    if seq is not None:
+        for step in reversed(st.steps):
+            if step.get("seq") == seq:
+                found = step
+                break
+    if found is not None:
+        found.setdefault("error", info)
+        return
+
+    # Fallback: emit an event
+    event(ctx, "error", **info)
+
+
+def snapshot(ctx: Any) -> Dict[str, Any]:
+    """
+    Return a structured snapshot of the trace suitable for diagnostics endpoints.
+    """
+    st = _get_state(ctx)
+    total_ms = max(0.0, (time.perf_counter() - st.t0) * 1000.0)
+    return {
+        "enabled": st.enabled,
+        "sampled": st.sampled,
+        "started_at": st.started_at.isoformat(),
+        "duration_ms": round(total_ms, 3),
+        "counts": {
+            "steps": len(st.steps),
+            "open": len(st.open),
+            "events": len(st.events),
+        },
+        "plan": st.plan_labels,
+        "steps": tuple(st.steps),  # immutable copy for consumers
+        "events": tuple(st.events),
+    }
+
+
+def clear(ctx: Any) -> None:
+    """Erase all trace data for this context."""
+    tmp = _ensure_temp(ctx)
+    tmp.pop("__trace__", None)
+
+
+@contextmanager
+def span(ctx: Any, label: str, **kv: Any):
+    """
+    Context-manager convenience for start()/end(). On exception, marks status=error
+    and attaches a compact error summary; then re-raises.
+    """
+    seq = start(ctx, label, **kv)
+    try:
+        yield seq
+        end(ctx, seq, status=OK)
+    except Exception as e:  # pragma: no cover (kernel normally handles)
+        attach_error(ctx, seq, e)
+        end(ctx, seq, status=ERROR)
+        raise
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# 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 _get_state(ctx: Any, *, create: bool = False) -> _TraceState:
+    tmp = _ensure_temp(ctx)
+    st = tmp.get("__trace__")
+    if isinstance(st, _TraceState):
+        return st
+    if create or st is None:
+        st = _TraceState()
+        tmp["__trace__"] = st
+        return st
+    # If someone stuffed a dict there, replace with a fresh state.
+    st = _TraceState()
+    tmp["__trace__"] = st
+    return st
+
+
+def _active(st: _TraceState) -> bool:
+    return bool(st.enabled and st.sampled)
+
+
+def _iso_now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).isoformat()
+
+
+def _parse_label(label: str) -> Dict[str, Any]:
+    """
+    Parse step_kind:domain:subject@anchor#field into parts.
+    Tolerant: any segment may be missing.
+    """
+    out = {"label": str(label)}
+    left, anchor = (label.split("@", 1) + [""])[:2]
+    field = None
+    if "#" in anchor:
+        anchor, field = anchor.split("#", 1)
+    parts = left.split(":")
+    if parts:
+        out["step_kind"] = parts[0] or None
+    if len(parts) > 1:
+        out["domain"] = parts[1] or None
+    if len(parts) > 2:
+        out["subject"] = ":".join(parts[2:]) or None  # tolerate extra colons
+    out["anchor"] = anchor or None
+    out["field"] = field or None
+    return out
+
+
+def _base_entry(label: str) -> Dict[str, Any]:
+    entry = _parse_label(label)
+    entry["ts"] = _iso_now()
+    return entry
+
+
+def _safe_kv(kv: Mapping[str, Any]) -> Dict[str, Any]:
+    """
+    Sanitize and cap key/values:
+      - keep at most _MAX_KV_KEYS keys
+      - value → scalar (bool/int/float/str<=N) or a short type tag
+    """
+    out: Dict[str, Any] = {}
+    for i, (k, v) in enumerate(kv.items()):
+        if i >= _MAX_KV_KEYS:
+            out["_kv_truncated"] = True
+            break
+        out[str(k)] = _safe_scalar(v)
+    return out
+
+
+def _safe_scalar(v: Any) -> Any:
+    if v is None:
+        return None
+    if isinstance(v, (bool, int, float)):
+        return v
+    if isinstance(v, (bytes, bytearray, memoryview)):
+        return f"<{type(v).__name__}:{len(v)}B>"
+    s = str(v)
+    if len(s) > _MAX_SCALAR_LEN:
+        s = s[: _MAX_SCALAR_LEN - 1] + "…"
+    return s
+
+
+__all__ = [
+    "OK",
+    "ERROR",
+    "SKIPPED",
+    "init",
+    "set_enabled",
+    "start",
+    "end",
+    "event",
+    "attach_error",
+    "snapshot",
+    "clear",
+    "span",
+]

tigrbl/schema/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/schema/__init__.py
+from .builder import _build_schema, _build_list_params
+from .utils import (
+    namely_model,
+    _make_bulk_rows_model,
+    _make_bulk_rows_response_model,
+    _make_bulk_ids_model,
+    _make_deleted_response_model,
+    _make_pk_model,
+)
+from .get_schema import get_schema
+from .decorators import schema_ctx
+from .collect import collect_decorated_schemas
+from ._schema import Schema
+from .schema_spec import SchemaSpec
+from .shortcuts import schema, schema_spec
+from .types import SchemaRef, SchemaArg, SchemaKind
+
+__all__ = [
+    "_build_schema",
+    "_build_list_params",
+    "namely_model",
+    "_make_bulk_rows_model",
+    "_make_bulk_rows_response_model",
+    "_make_bulk_ids_model",
+    "_make_deleted_response_model",
+    "_make_pk_model",
+    "get_schema",
+    "schema_ctx",
+    "collect_decorated_schemas",
+    "Schema",
+    "SchemaSpec",
+    "schema",
+    "schema_spec",
+    "SchemaRef",
+    "SchemaArg",
+    "SchemaKind",
+]

tigrbl/schema/_schema.py

@@ -0,0 +1,27 @@
+# tigrbl/v3/schema/_schema.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Type
+
+try:  # pragma: no cover
+    from pydantic import BaseModel  # type: ignore
+except Exception:  # pragma: no cover
+
+    class BaseModel:  # minimal stub for typing only
+        pass
+
+
+from .types import SchemaKind
+
+
+@dataclass(frozen=True, slots=True)
+class Schema:
+    """Concrete schema paired with its alias and kind."""
+
+    model: Type[BaseModel]
+    kind: SchemaKind = "out"
+    alias: str | None = None
+
+
+__all__ = ["Schema"]

tigrbl/schema/builder/__init__.py

@@ -0,0 +1,17 @@
+"""Schema builder package for Tigrbl v3."""
+
+from .cache import _SchemaCache, _SchemaVerb
+from .extras import _merge_request_extras, _merge_response_extras
+from .build_schema import _build_schema
+from .list_params import _build_list_params
+from .strip_parent_fields import _strip_parent_fields
+
+__all__ = [
+    "_build_schema",
+    "_build_list_params",
+    "_strip_parent_fields",
+    "_merge_request_extras",
+    "_merge_response_extras",
+    "_SchemaCache",
+    "_SchemaVerb",
+]