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

tigrbl/runtime/atoms/resolve/paired_gen.py

@@ -0,0 +1,147 @@
+# tigrbl/v3/runtime/atoms/resolve/paired_gen.py
+from __future__ import annotations
+
+import secrets
+import logging
+from typing import Any, Dict, MutableMapping, Optional
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, _ensure_temp
+
+# Runs in HANDLER phase, before pre:flush (and before storage transforms).
+ANCHOR = _ev.RESOLVE_VALUES  # "resolve:values"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    resolve:paired_gen@resolve:values
+
+    Purpose
+    -------
+    Prepare *paired* raw values for columns marked as secret-once/paired.
+    The raw value is:
+      - taken from inbound virtual input (if provided), or
+      - generated securely (e.g., URL-safe token) when inbound is ABSENT.
+
+    Contracts / Conventions
+    -----------------------
+    - ctx.temp:
+        - "virtual_in"         : dict of inbound virtual values (from resolve:assemble)
+        - "paired_values"      : dict[field -> {"raw": <str>, "alias": <str>, "meta": {...}}]
+        - "persist_from_paired": dict[field -> {"source": ("paired_values", field, "raw")}]
+        - "assembled_values"   : dict used for persistence (we DO NOT put raw into it)
+        - "generated_paired"   : tuple of fields generated here (diagnostics)
+    - Secret-once guarantee is enforced later by emit atoms (post-refresh + readtime).
+
+    Policy
+    ------
+    - We treat a column as "paired" if any of these flags exist (ColumnSpec or FieldSpec):
+        secret_once=True | paired=True | paired_input=True | generate_on_absent=True
+      OR if a generator callable is present on the spec (generator/paired_generator/secret_generator).
+    - If inbound virtual value for the alias exists, we adopt it as the raw.
+    - Otherwise we call the generator if provided, else generate a token.
+    - We place a *pointer* into ctx.temp["persist_from_paired"] for storage:to_stored
+      to derive the persisted representation right before flush.
+    """
+    # Non-persisting ops should have pruned this anchor; keep guard for safety.
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping resolve:paired_gen; ctx.persist is False")
+        return
+
+    logger.debug("Running resolve:paired_gen")
+    ov = opview_from_ctx(ctx)
+    temp = _ensure_temp(ctx)
+    assembled = _ensure_dict(temp, "assembled_values")
+    virtual_in = _ensure_dict(temp, "virtual_in")
+    paired_values = _ensure_dict(temp, "paired_values")
+    persist_from_paired = _ensure_dict(temp, "persist_from_paired")
+
+    generated: list[str] = []
+
+    for field, desc in ov.paired_index.items():
+        if field in assembled:
+            logger.debug(
+                "Field %s already has assembled value; skipping generation", field
+            )
+            continue
+
+        alias_name = desc.get("alias") or field
+        raw = None
+        if alias_name in virtual_in:
+            raw = virtual_in.get(alias_name)
+            logger.debug(
+                "Using client-provided raw for field %s via alias %s", field, alias_name
+            )
+
+        if raw is None:
+            logger.debug("Generating raw value for field %s", field)
+            gen = desc.get("gen")
+            if callable(gen):
+                try:
+                    raw = gen(_ctx_view(ctx))
+                except Exception:
+                    logger.debug("Generator failed for field %s", field)
+                    raw = None
+            if raw is None:
+                raw = _secure_token(desc.get("max_length", 0) or 0)
+
+        if raw is None:
+            raise RuntimeError(f"paired_raw_missing:{field}")
+
+        meta = {}
+        if "mask_last" in desc:
+            meta["mask_last"] = desc["mask_last"]
+
+        paired_values[field] = {"raw": raw, "alias": alias_name, "meta": meta}
+        logger.debug("Recorded paired raw for field %s", field)
+
+        persist_from_paired[field] = {"source": ("paired_values", field, "raw")}
+
+        generated.append(field)
+
+    if generated:
+        temp["generated_paired"] = tuple(generated)
+        logger.debug("Generated paired fields: %s", generated)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+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 _ctx_view(ctx: Any) -> Dict[str, Any]:
+    """Small read-only view for generator callables."""
+    return {
+        "op": getattr(ctx, "op", None),
+        "persist": getattr(ctx, "persist", True),
+        "temp": getattr(ctx, "temp", None),
+        "tenant": getattr(ctx, "tenant", None),
+        "user": getattr(ctx, "user", None),
+        "now": getattr(ctx, "now", None),
+    }
+
+
+def _secure_token(max_len: int) -> str:
+    """
+    Generate a URL-safe token. If max_len > 0, keep within that bound.
+    We aim for ~32 bytes entropy by default.
+    """
+    # 32 bytes → ~43 chars base64-url
+    token = secrets.token_urlsafe(32)
+    if max_len and max_len > 0 and len(token) > max_len:
+        # Trim conservatively; if extremely small, ensure we still return something.
+        token = token[: max(8, max_len)]
+    return token
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/response/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from ... import events as _ev
+from .template import run as _template
+from .negotiate import run as _negotiate
+from .render import run as _render
+
+RunFn = Callable[[Optional[object], Any], Any]
+
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("response", "template"): (_ev.OUT_DUMP, _template),
+    ("response", "negotiate"): (_ev.OUT_DUMP, _negotiate),
+    ("response", "render"): (_ev.OUT_DUMP, _render),
+}
+
+__all__ = ["REGISTRY", "RunFn"]

tigrbl/runtime/atoms/response/negotiate.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from ... import events as _ev
+from .negotiation import negotiate_media_type
+from .renderer import ResponseHints
+
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """response:negotiate@out:dump
+
+    Determine the response media type if not already set.
+    """
+    resp_ns = getattr(ctx, "response", None)
+    req = getattr(ctx, "request", None)
+    if resp_ns is None or req is None:
+        return
+    hints = getattr(resp_ns, "hints", None)
+    if hints is None:
+        hints = ResponseHints()
+        resp_ns.hints = hints
+    if not hints.media_type:
+        accept = getattr(req, "headers", {}).get("accept", "*/*")
+        default_media = getattr(resp_ns, "default_media", "application/json")
+        hints.media_type = negotiate_media_type(accept, default_media)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/response/negotiation.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from typing import List
+import logging
+
+
+def _parse(accept: str) -> List[str]:
+    parts = [p.strip() for p in accept.split(",") if p.strip()]
+
+    def q(p: str) -> float:
+        for seg in p.split(";"):
+            seg = seg.strip()
+            if seg.startswith("q="):
+                try:
+                    return float(seg[2:])
+                except Exception:
+                    return 1.0
+        return 1.0
+
+    return sorted(parts, key=q, reverse=True)
+
+
+logger = logging.getLogger("uvicorn")
+
+
+def negotiate_media_type(accept: str, default_media: str) -> str:
+    logger.debug("Negotiating media type from Accept header %s", accept)
+    if not accept or accept == "*/*":
+        return default_media
+    for cand in _parse(accept):
+        mt = cand.split(";")[0].strip()
+        if mt in (
+            "application/json",
+            "text/html",
+            "text/plain",
+            "application/octet-stream",
+        ):
+            return mt
+        if mt.startswith("text/"):
+            return "text/plain"
+    return default_media
+
+
+__all__ = ["negotiate_media_type"]

tigrbl/runtime/atoms/response/render.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from ... import events as _ev
+from .renderer import render
+
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+
+def run(obj: Optional[object], ctx: Any) -> Any:
+    """response:render@out:dump
+
+    Render ``ctx.response.result`` into a concrete Response object.
+    """
+    resp_ns = getattr(ctx, "response", None)
+    req = getattr(ctx, "request", None)
+    if resp_ns is None or req is None:
+        return None
+    result = getattr(resp_ns, "result", None)
+    if result is None:
+        return None
+    hints = getattr(resp_ns, "hints", None)
+    default_media = getattr(resp_ns, "default_media", "application/json")
+    envelope_default = getattr(resp_ns, "envelope_default", False)
+    resp = render(
+        req,
+        result,
+        hints=hints,
+        default_media=default_media,
+        envelope_default=envelope_default,
+    )
+    resp_ns.result = resp
+    return resp
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/response/renderer.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, AsyncIterable, Iterable, Mapping, Optional, Union, cast
+import logging
+
+from ....deps.starlette import BackgroundTask, Response
+
+from ....response.shortcuts import (
+    as_file,
+    as_html,
+    as_json,
+    as_stream,
+    as_text,
+)
+
+JSON = Mapping[str, Any]
+
+logger = logging.getLogger("uvicorn")
+
+
+@dataclass
+class ResponseHints:
+    media_type: Optional[str] = None
+    status_code: int = 200
+    headers: dict[str, str] = field(default_factory=dict)
+    filename: Optional[str] = None
+    download: bool = False
+    etag: Optional[str] = None
+    last_modified: Optional[Any] = None
+    background: Optional[BackgroundTask] = None
+
+
+class ResponseKind:
+    JSON = "application/json"
+    HTML = "text/html"
+    TEXT = "text/plain"
+    FILE = "application/file"
+    STREAM = "application/stream"
+    REDIRECT = "application/redirect"
+
+
+ResponseLike = Union[
+    Response,
+    bytes,
+    bytearray,
+    memoryview,
+    str,
+    Path,
+    JSON,
+    Iterable[bytes],
+    AsyncIterable[bytes],
+]
+
+
+def render(
+    request: Any,
+    payload: ResponseLike,
+    *,
+    hints: Optional[ResponseHints] = None,
+    default_media: str = "application/json",
+    envelope_default: bool = False,
+) -> Response:
+    logger.debug("Rendering response with payload type %s", type(payload))
+    if isinstance(payload, Response):
+        return payload
+
+    hints = hints or ResponseHints()
+    chosen = hints.media_type or default_media
+
+    if isinstance(payload, Path):
+        return as_file(
+            payload,
+            filename=hints.filename,
+            download=hints.download,
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if isinstance(payload, (bytes, bytearray, memoryview)):
+        return as_stream(
+            iter((bytes(payload),)),
+            media_type="application/octet-stream",
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if hasattr(payload, "__aiter__") or (
+        hasattr(payload, "__iter__") and not isinstance(payload, (str, dict, list))
+    ):
+        return as_stream(
+            cast(Union[Iterable[bytes], AsyncIterable[bytes]], payload),
+            media_type="application/octet-stream",
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if isinstance(payload, str):
+        if payload.lstrip().startswith("<") or chosen == "text/html":
+            return as_html(payload, status=hints.status_code, headers=hints.headers)
+        return as_text(payload, status=hints.status_code, headers=hints.headers)
+
+    return as_json(
+        payload,
+        status=hints.status_code,
+        headers=hints.headers,
+        envelope=envelope_default,
+    )
+
+
+__all__ = [
+    "ResponseHints",
+    "ResponseKind",
+    "ResponseLike",
+    "render",
+]

tigrbl/runtime/atoms/response/template.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from ... import events as _ev
+from .templates import render_template
+from .renderer import ResponseHints
+
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+
+async def run(obj: Optional[object], ctx: Any) -> None:
+    """response:template@out:dump
+
+    Render a template if configured on ``ctx.response``.
+    """
+    resp_ns = getattr(ctx, "response", None)
+    req = getattr(ctx, "request", None)
+    if resp_ns is None or req is None:
+        return
+    tmpl = getattr(resp_ns, "template", None)
+    if not tmpl:
+        return
+    result = getattr(resp_ns, "result", None)
+    context = result if isinstance(result, dict) else {"data": result}
+    html = await render_template(
+        name=tmpl.name,
+        context=context,
+        search_paths=tmpl.search_paths,
+        package=tmpl.package,
+        auto_reload=bool(tmpl.auto_reload),
+        filters=tmpl.filters,
+        globals_=tmpl.globals,
+        request=req,
+    )
+    resp_ns.result = html
+    hints = getattr(resp_ns, "hints", None)
+    if hints is None:
+        hints = ResponseHints()
+        resp_ns.hints = hints
+    if not hints.media_type:
+        hints.media_type = "text/html"
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/response/templates.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+from functools import lru_cache
+import logging
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from ....deps.starlette import Request
+from ....deps.jinja import (
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    ChoiceLoader,
+    select_autoescape,
+    TemplateNotFound,
+)
+
+logger = logging.getLogger("uvicorn")
+if Environment is None:  # pragma: no cover - jinja2 not installed
+
+    async def render_template(
+        *,
+        name: str,
+        context: Dict[str, Any],
+        search_paths: Iterable[str] = (),
+        package: Optional[str] = None,
+        auto_reload: bool = False,
+        filters: Optional[Dict[str, Any]] = None,
+        globals_: Optional[Dict[str, Any]] = None,
+        request: Optional[Request] = None,
+    ) -> str:
+        logger.debug("Rendering template %s", name)
+        raise RuntimeError("jinja2 is required for template rendering")
+
+else:
+
+    def _mk_loader(search_paths: Iterable[str], package: Optional[str]) -> ChoiceLoader:
+        loaders = []
+        if search_paths:
+            loaders.append(FileSystemLoader(list(search_paths)))
+        if package:
+            loaders.append(PackageLoader(package_name=package))
+        if not loaders:
+            loaders.append(FileSystemLoader(["."]))
+        return ChoiceLoader(loaders)
+
+    @lru_cache(maxsize=64)
+    def _get_env(
+        search_paths_key: Tuple[str, ...],
+        package: Optional[str],
+        auto_reload: bool,
+    ) -> Environment:
+        env = Environment(
+            loader=_mk_loader(search_paths_key, package),
+            autoescape=select_autoescape(["html", "xml"]),
+            auto_reload=auto_reload,
+            enable_async=True,
+        )
+        return env
+
+    async def render_template(
+        *,
+        name: str,
+        context: Dict[str, Any],
+        search_paths: Iterable[str] = (),
+        package: Optional[str] = None,
+        auto_reload: bool = False,
+        filters: Optional[Dict[str, Any]] = None,
+        globals_: Optional[Dict[str, Any]] = None,
+        request: Optional[Request] = None,
+    ) -> str:
+        logger.debug("Rendering template %s", name)
+        env = _get_env(tuple(search_paths), package, auto_reload)
+        if filters:
+            env.filters.update(filters)
+        if globals_:
+            env.globals.update(globals_)
+        if request is not None:
+            env.globals.setdefault("url_for", request.url_for)
+            env.globals.setdefault("request", request)
+
+        try:
+            tmpl = env.get_template(name)
+        except TemplateNotFound as e:  # pragma: no cover - passthrough
+            raise FileNotFoundError(f"Template not found: {name}") from e
+
+        return await tmpl.render_async(**context)
+
+
+__all__ = ["render_template"]

tigrbl/runtime/atoms/schema/__init__.py

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

tigrbl/runtime/atoms/schema/collect_in.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in
+
+# Runs at the very beginning of the lifecycle, before in-model build/validation.
+ANCHOR = _ev.SCHEMA_COLLECT_IN  # "schema:collect_in"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Load precompiled inbound schema into ctx.temp."""
+    ov = opview_from_ctx(ctx)
+    ensure_schema_in(ctx, ov)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/schema/collect_out.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out
+
+# Runs late in POST_HANDLER, before out model build and dumping.
+ANCHOR = _ev.SCHEMA_COLLECT_OUT  # "schema:collect_out"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Load precompiled outbound schema into ctx.temp."""
+    ov = opview_from_ctx(ctx)
+    ensure_schema_out(ctx, ov)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/storage/__init__.py

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