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

tigrbl/response/shortcuts.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+from typing import Any, AsyncIterable, Iterable, Mapping, Optional, Union
+from datetime import datetime, timezone
+from pathlib import Path
+import json
+import os
+import mimetypes
+import base64
+
+from ..deps.starlette import (
+    JSONResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    StreamingResponse,
+    FileResponse as StarletteFileResponse,
+    RedirectResponse,
+    Response,
+)
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return base64.b64encode(bytes(value)).decode("ascii")
+    if isinstance(value, Path):
+        return str(value)
+    return str(value)
+
+
+try:
+    import orjson as _orjson
+
+    _ORJSON_OPTIONS = (
+        getattr(_orjson, "OPT_NON_STR_KEYS", 0)
+        | getattr(_orjson, "OPT_SERIALIZE_NUMPY", 0)
+        | getattr(_orjson, "OPT_SERIALIZE_BYTES", 0)
+    )
+
+    def _dumps(obj: Any) -> bytes:
+        try:
+            return _orjson.dumps(
+                obj,
+                option=_ORJSON_OPTIONS,
+                default=_json_default,
+            )
+        except TypeError:
+            # Fallback for older orjson builds missing optional flags
+            return json.dumps(
+                obj,
+                separators=(",", ":"),
+                ensure_ascii=False,
+                default=_json_default,
+            ).encode("utf-8")
+except Exception:  # pragma: no cover - fallback
+
+    def _dumps(obj: Any) -> bytes:
+        return json.dumps(
+            obj,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            default=_json_default,
+        ).encode("utf-8")
+
+
+def _maybe_envelope(data: Any) -> Any:
+    if isinstance(data, Mapping) and ("data" in data or "error" in data):
+        return data
+    return {"data": data, "ok": True}
+
+
+JSON = Mapping[str, Any]
+Headers = Mapping[str, str]
+
+
+def as_json(
+    data: Any,
+    *,
+    status: int = 200,
+    headers: Optional[Headers] = None,
+    envelope: bool = True,
+    dumps=_dumps,
+) -> Response:
+    payload = _maybe_envelope(data) if envelope else data
+    try:
+        return JSONResponse(
+            payload,
+            status_code=status,
+            headers=dict(headers or {}),
+            dumps=lambda o: dumps(o).decode(),
+        )
+    except TypeError:  # pragma: no cover - starlette >= 0.44
+        return Response(
+            dumps(payload),
+            status_code=status,
+            headers=dict(headers or {}),
+            media_type="application/json",
+        )
+
+
+def as_html(
+    html: str, *, status: int = 200, headers: Optional[Headers] = None
+) -> Response:
+    return HTMLResponse(html, status_code=status, headers=dict(headers or {}))
+
+
+def as_text(
+    text: str, *, status: int = 200, headers: Optional[Headers] = None
+) -> Response:
+    return PlainTextResponse(text, status_code=status, headers=dict(headers or {}))
+
+
+def as_redirect(
+    url: str, *, status: int = 307, headers: Optional[Headers] = None
+) -> Response:
+    return RedirectResponse(url, status_code=status, headers=dict(headers or {}))
+
+
+def as_stream(
+    chunks: Union[Iterable[bytes], AsyncIterable[bytes]],
+    *,
+    media_type: str = "application/octet-stream",
+    status: int = 200,
+    headers: Optional[Headers] = None,
+) -> Response:
+    return StreamingResponse(
+        chunks, media_type=media_type, status_code=status, headers=dict(headers or {})
+    )
+
+
+def as_file(
+    path: Union[str, Path],
+    *,
+    filename: Optional[str] = None,
+    download: bool = False,
+    status: int = 200,
+    headers: Optional[Headers] = None,
+    stat_result: Optional[os.stat_result] = None,
+    etag: Optional[str] = None,
+    last_modified: Optional[datetime] = None,
+) -> Response:
+    p = Path(path)
+    if not p.exists() or not p.is_file():
+        return PlainTextResponse("Not Found", status_code=404)
+    media_type, _ = mimetypes.guess_type(str(p))
+    media_type = media_type or "application/octet-stream"
+    hdrs = dict(headers or {})
+    st = stat_result or os.stat(p)
+    if etag is None:
+        etag = f'W/"{st.st_mtime_ns}-{st.st_size}"'
+    lm = last_modified or datetime.fromtimestamp(st.st_mtime, tz=timezone.utc)
+    hdrs.setdefault("ETag", etag)
+    hdrs.setdefault("Last-Modified", lm.strftime("%a, %d %b %Y %H:%M:%S GMT"))
+    if download or filename:
+        fname = filename or p.name
+        hdrs.setdefault("Content-Disposition", f'attachment; filename="{fname}"')
+    return StarletteFileResponse(
+        str(p),
+        status_code=status,
+        media_type=media_type,
+        filename=filename,
+        headers=hdrs,
+    )
+
+
+__all__ = [
+    "as_json",
+    "as_html",
+    "as_text",
+    "as_redirect",
+    "as_stream",
+    "as_file",
+]

tigrbl/response/types.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Literal, Optional
+
+ResponseKind = Literal["auto", "json", "html", "text", "file", "stream", "redirect"]
+
+
+@dataclass(slots=True)
+class TemplateSpec:
+    name: str
+    search_paths: List[str] = field(default_factory=list)
+    package: Optional[str] = None
+    auto_reload: Optional[bool] = None
+    filters: Dict[str, object] = field(default_factory=dict)
+    globals: Dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ResponseSpec:
+    kind: ResponseKind = "auto"
+    media_type: Optional[str] = None
+    status_code: Optional[int] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+    envelope: Optional[bool] = None
+    template: Optional[TemplateSpec] = None
+    filename: Optional[str] = None
+    download: Optional[bool] = None
+    etag: Optional[str] = None
+    cache_control: Optional[str] = None
+    redirect_to: Optional[str] = None
+
+
+@dataclass(slots=True)
+class Template(TemplateSpec):
+    """Concrete template configuration used at runtime."""
+
+
+@dataclass(slots=True)
+class Response(ResponseSpec):
+    """Concrete response configuration used at runtime."""
+
+
+__all__ = [
+    "TemplateSpec",
+    "ResponseSpec",
+    "ResponseKind",
+    "Template",
+    "Response",
+]

tigrbl/rest/__init__.py

@@ -0,0 +1,27 @@
+"""tigrbl_routes.py
+Helpers that build path prefixes for nested REST endpoints.
+The logic is intentionally minimal; extend or override as needed.
+"""
+
+from __future__ import annotations
+from typing import Optional, Type
+
+from ..config.constants import TIGRBL_NESTED_PATHS_ATTR
+
+
+def _nested_prefix(model: Type) -> Optional[str]:
+    """Return the user-supplied hierarchical prefix or *None*.
+
+    • If the SQLAlchemy model defines `__tigrbl_nested_paths__`
+      → call it and return the result.
+    • Else, fall back to legacy `_nested_path` string if present.
+    • Otherwise → signal ``no nested route wanted`` with ``None``.
+    """
+
+    cb = getattr(model, TIGRBL_NESTED_PATHS_ATTR, None)
+    if callable(cb):
+        return cb()
+    return getattr(model, "_nested_path", None)
+
+
+__all__ = ["_nested_prefix"]

tigrbl/runtime/README.md

@@ -0,0 +1,129 @@
+# Runtime Execution Module (v3)
+
+> **Maintainer-only:** This module is internal to the SDK. Downstream users **must not** modify or rely on it directly.
+
+The runtime executor coordinates Tigrbl operations through a fixed set of **phase chains**. Each phase has a list of steps built by the kernel and is executed under strict database guards.
+
+## Phase Chains
+
+Phase chains map phase names to ordered handler lists. The executor runs the phases in the sequence below:
+
+1. `PRE_TX_BEGIN` – pre-transaction checks.
+2. `START_TX` – open a new transaction (system-only).
+3. `PRE_HANDLER` – request validation and setup.
+4. `HANDLER` – core operation logic.
+5. `POST_HANDLER` – post-processing while still in the transaction.
+6. `PRE_COMMIT` – final checks before committing.
+7. `END_TX` – commit and close the transaction.
+8. `POST_COMMIT` – steps after commit.
+9. `POST_RESPONSE` – fire-and-forget side effects.
+
+## Step Kinds
+
+The kernel labels every piece of work so it can be ordered predictably:
+
+- **secdeps** – security dependencies that run before any other steps. Downstream
+  applications configure these to enforce authentication or authorization.
+- **deps** – general dependencies resolved ahead of handlers. These are also
+  provided downstream.
+- **sys** – system steps shipped with Tigrbl to coordinate core behavior. They
+  are maintained by project maintainers.
+- **atoms** – built-in runtime units such as schema collectors or wire
+  serializers. Maintainers own these components.
+- **hooks** – user-supplied handlers that attach to anchors within phases.
+
+Downstream consumers configure `secdeps`, `deps`, and `hooks`, while `sys` and
+`atom` steps are maintained by the Tigrbl maintainers.
+
+
+## Step Precedence
+
+When the kernel assembles an operation it flattens several step kinds into a
+single execution plan. They run in the following precedence:
+
+1. Security dependencies (`secdeps`)
+2. General dependencies (`deps`)
+3. System steps (`sys`) such as transaction begin, handler dispatch, and commit
+4. Runtime atoms (`atoms`)
+5. Hooks (`hooks`)
+
+System steps appear only on the `START_TX`, `HANDLER`, and `END_TX` anchors. Within
+each anchor, atoms execute before hooks and any remaining ties are resolved by
+anchor-specific preferences.
+
+## Atom Domains
+
+Atoms are grouped into domain-specific registries so the kernel can inject them
+at the correct stage of the lifecycle. Each domain focuses on a different slice
+of request or response processing:
+
+- **wire** – builds inbound data, validates it, and prepares outbound payloads at
+  the field level.
+- **schema** – collects request and response schema definitions for models.
+- **resolve** – assembles derived values or generates paired inputs before they
+  are flushed.
+- **storage** – converts field specifications into storage-layer instructions.
+- **emit** – surfaces runtime metadata such as aliases or extras for downstream
+  consumers.
+- **out** – mutates data after handlers run, for example masking fields before
+  serialization.
+- **response** – negotiates content types and renders the final HTTP response or
+  template.
+- **refresh** – triggers post-commit refreshes like demand-driven reloads.
+
+Domains differ by the moment they run and the guarantees they provide. A `wire`
+atom transforms raw request values before validation, whereas a `response` atom
+operates after the transaction is committed to shape the returned payload. The
+kernel uses the pair `(domain, subject)` to register and inject atoms into phase
+chains.
+
+## DB Guards
+
+For every phase the executor installs database guards that monkey‑patch
+`commit` and `flush` on the session. Guards enforce which operations are
+allowed and ensure only the owning transaction may commit.
+
+The guard installer swaps these methods with stubs that raise
+`RuntimeError` when a disallowed operation is attempted. Each phase passes
+flags describing its policy:
+
+- `allow_flush` – permit calls to `session.flush`.
+- `allow_commit` – permit calls to `session.commit`.
+- `require_owned_tx_for_commit` – when `True`, block commits if the
+  executor did not open the transaction.
+
+The installer returns a handle that restores the original methods once the
+phase finishes so restrictions do not leak across phases. A companion
+helper triggers a rollback if the runtime owns the transaction and a phase
+raises an error.
+
+| Phase | Flush | Commit | Notes |
+|-------|-------|--------|-------|
+| PRE_TX_BEGIN | ❌ | ❌ | no database writes |
+| START_TX | ❌ | ❌ | transaction opening |
+| PRE_HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| POST_HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| PRE_COMMIT | ❌ | ❌ | freeze writes before commit |
+| END_TX | ✅ | ✅ | commit allowed only if runtime owns the transaction |
+| POST_COMMIT | ✅ | ❌ | post-commit writes without commit |
+| POST_RESPONSE | ❌ | ❌ | background work, no writes |
+
+### Transaction Boundaries
+
+`start_tx` is a system step that opens a new database transaction when
+no transaction is active and marks the runtime as its owner. While this
+phase runs, both `session.flush` and `session.commit` are blocked. After a
+transaction is started, phases such as `PRE_HANDLER`, `HANDLER`, and
+`POST_HANDLER` allow flushes so SQL statements can be issued while the
+commit remains deferred. The `end_tx` step executes during the `END_TX`
+phase, performing a final flush and committing the transaction if the
+runtime owns it. Once this phase completes, guards restore the original
+session methods.
+
+If a phase fails, the guard restores the original methods and the executor rolls back when it owns the transaction. Optional `ON_<PHASE>_ERROR` chains can handle cleanup.
+
+---
+
+This runtime layer is maintained by the core team. Downstream packages should treat it as read‑only and interact only through the public Tigrbl interfaces.
+

tigrbl/runtime/__init__.py

@@ -0,0 +1,20 @@
+# tigrbl/v3/runtime/__init__.py
+from .executor import _invoke, _Ctx
+from .kernel import Kernel, build_phase_chains, run, get_cached_specs, _default_kernel
+from . import events, errors, context
+from .labels import STEP_KINDS, DOMAINS
+
+__all__ = [
+    "_invoke",
+    "_Ctx",
+    "Kernel",
+    "build_phase_chains",
+    "run",
+    "get_cached_specs",
+    "_default_kernel",
+    "events",
+    "errors",
+    "context",
+    "STEP_KINDS",
+    "DOMAINS",
+]

tigrbl/runtime/atoms/__init__.py

@@ -0,0 +1,102 @@
+# tigrbl/v3/runtime/atoms/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+from .. import events as _ev
+
+# Domain registries
+from .emit import REGISTRY as _EMIT
+from .out import REGISTRY as _OUT
+from .refresh import REGISTRY as _REFRESH
+from .resolve import REGISTRY as _RESOLVE
+from .schema import REGISTRY as _SCHEMA
+from .storage import REGISTRY as _STORAGE
+from .wire import REGISTRY as _WIRE
+from .response import REGISTRY as _RESPONSE
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Global registry consumed by the kernel plan:
+#:   { (domain, subject): (anchor, runner) }
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {}
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+def _add_bulk(source: Dict[Tuple[str, str], Tuple[str, RunFn]]) -> None:
+    for key, val in source.items():
+        if key in REGISTRY:
+            logger.error("Duplicate atom registration attempted: %s", key)
+            raise RuntimeError(f"Duplicate atom registration: {key!r}")
+        anchor, fn = val
+        if not _ev.is_valid_event(anchor):
+            logger.error("Atom %s declares unknown anchor %s", key, anchor)
+            raise ValueError(f"Atom {key!r} declares unknown anchor {anchor!r}")
+        REGISTRY[key] = (anchor, fn)
+        logger.debug("Registered atom %s -> %s", key, anchor)
+
+
+# Aggregate all domains
+_add_bulk(_EMIT)
+_add_bulk(_OUT)
+_add_bulk(_REFRESH)
+_add_bulk(_RESOLVE)
+_add_bulk(_SCHEMA)
+_add_bulk(_STORAGE)
+_add_bulk(_WIRE)
+_add_bulk(_RESPONSE)
+
+logger.info("Loaded %d runtime atoms", len(REGISTRY))
+
+# ── Back-compat subject aliases (optional) ────────────────────────────────────
+# Allow "wire:validate" as an alias of "wire:validate_in".
+if ("wire", "validate_in") in REGISTRY and ("wire", "validate") not in REGISTRY:
+    REGISTRY[("wire", "validate")] = REGISTRY[("wire", "validate_in")]
+
+# ── Public helpers ────────────────────────────────────────────────────────────
+
+
+def domains() -> Tuple[str, ...]:
+    """Return all domains present in the registry."""
+    out = tuple(sorted({d for (d, _) in REGISTRY.keys()}))
+    logger.debug("Listing domains: %s", out)
+    return out
+
+
+def subjects(domain: str) -> Tuple[str, ...]:
+    """Return subjects available for a given domain."""
+    out = tuple(sorted(s for (d, s) in REGISTRY.keys() if d == domain))
+    logger.debug("Listing subjects for %s: %s", domain, out)
+    return out
+
+
+def get(domain: str, subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a given (domain, subject)."""
+    key = (domain, subject)
+    if key not in REGISTRY:
+        logger.error("Unknown atom requested: %s:%s", domain, subject)
+        raise KeyError(f"Unknown atom: {domain}:{subject}")
+    val = REGISTRY[key]
+    logger.debug("Retrieved atom %s:%s -> %s", domain, subject, val[0])
+    return val
+
+
+def all_items() -> Tuple[Tuple[Tuple[str, str], Tuple[str, RunFn]], ...]:
+    """Return the registry items as a sorted tuple for deterministic iteration."""
+    items = tuple(sorted(REGISTRY.items(), key=lambda kv: (kv[0][0], kv[0][1])))
+    logger.debug("Listing all registry items (%d)", len(items))
+    return items
+
+
+__all__ = [
+    "RunFn",
+    "REGISTRY",
+    "domains",
+    "subjects",
+    "get",
+    "all_items",
+]

tigrbl/runtime/atoms/emit/__init__.py

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