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

tigrbl/orm/tables/client.py

@@ -0,0 +1,25 @@
+# peagen/orm/api_key.py
+from __future__ import annotations
+
+
+from ...specs import acol, IO, S, F
+from ...types import LargeBinary, Mapped, String
+
+from ._base import Base
+from ..mixins import ActiveToggle, GUIDPk, Timestamped, TenantBound
+
+
+class Client(Base, GUIDPk, Timestamped, TenantBound, ActiveToggle):
+    __tablename__ = "clients"
+    __abstract__ = True
+    # ---------------------------------------------------------------- columns --
+    client_secret_hash: Mapped[bytes] = acol(
+        storage=S(LargeBinary(60), nullable=False),
+        field=F(),
+        io=IO(in_verbs=("create",)),
+    )
+    redirect_uris: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(constraints={"max_length": 1000}),
+        io=IO(),
+    )

tigrbl/orm/tables/group.py

@@ -0,0 +1,29 @@
+"""Group model."""
+
+from ._base import Base
+from ..mixins import GUIDPk, Timestamped, TenantBound, Principal
+from ...specs import IO, F, acol, S
+from ...types import Mapped, String
+
+
+class Group(Base, GUIDPk, Timestamped, TenantBound, Principal):
+    __tablename__ = "groups"
+    name: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(),
+    )
+
+
+__all__ = ["Group"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/orm/tables/org.py

@@ -0,0 +1,30 @@
+"""Org model."""
+
+from ._base import Base
+from ..mixins import GUIDPk, Timestamped, TenantBound, Principal
+from ...specs import IO, F, acol, S
+from ...types import Mapped, String
+
+
+class Org(Base, GUIDPk, Timestamped, TenantBound, Principal):
+    __tablename__ = "orgs"
+    __abstract__ = True
+    name: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(),
+    )
+
+
+__all__ = ["Org"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/orm/tables/rbac.py

@@ -0,0 +1,76 @@
+from uuid import UUID
+
+
+from ...specs import IO, F, acol, S
+from ...specs.storage_spec import ForeignKeySpec
+from ...types import Integer, String, PgUUID, Mapped
+
+from . import Base
+from ..mixins import (
+    GUIDPk,
+    TenantBound,
+    RelationEdge,
+    Timestamped,
+    MaskableEdge,
+)
+
+
+# ───────── RBAC core ──────────────────────────────────────────────────
+class Role(Base, GUIDPk, Timestamped, TenantBound):
+    __tablename__ = "roles"
+    slug: Mapped[str] = acol(
+        storage=S(String, unique=True),
+        field=F(),
+        io=IO(),
+    )
+    global_mask: Mapped[int] = acol(
+        storage=S(Integer, default=0),
+        field=F(),
+        io=IO(),
+    )
+
+
+class RolePerm(Base, GUIDPk, Timestamped, TenantBound, RelationEdge, MaskableEdge):
+    __tablename__ = "role_perms"
+    role_id: Mapped[UUID] = acol(
+        storage=S(PgUUID, fk=ForeignKeySpec("roles.id")),
+        field=F(),
+        io=IO(),
+    )
+    target_table: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(),
+    )
+    target_id: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(),
+    )  # row or sentinel
+
+
+class RoleGrant(Base, GUIDPk, Timestamped, TenantBound, RelationEdge):
+    __tablename__ = "role_grants"
+    principal_id: Mapped[UUID] = acol(
+        storage=S(PgUUID),
+        field=F(),
+        io=IO(),
+    )  # FK to principal row
+    role_id: Mapped[UUID] = acol(
+        storage=S(PgUUID, fk=ForeignKeySpec("roles.id")),
+        field=F(),
+        io=IO(),
+    )
+
+
+__all__ = ["Role", "RolePerm", "RoleGrant"]
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/orm/tables/status.py

@@ -0,0 +1,106 @@
+"""
+StatusEnum table
+----------------
+Canonical store of workflow / lifecycle states.
+
+• The `Status` enum below should always be the **only** source of truth for
+  allowed values.  Every place in the codebase ‒ mix-ins, business logic,
+  RPC schemas, etc. ‒ should import it instead of hard-coding strings.
+• Domain tables that need a status field should `ForeignKey` to
+  `status_enums.code` **or** just declare a `Column(SAEnum(Status, …))`
+  if the FK is unnecessary.
+
+If you add/remove a state later, just edit the `Status` enum – the rest
+keeps working.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from ...specs import acol, F, IO, S
+from ...types import Integer, Mapped, SAEnum, String
+
+from ._base import Base
+from ..mixins import Timestamped  # created_at / updated_at
+
+
+# ────────────────────────────────────────────────────────────────────────
+# 1. In-memory application enum  (single source of truth)
+# ────────────────────────────────────────────────────────────────────────
+class Status(StrEnum):
+    # queued / dispatching
+    QUEUED = "queued"
+    WAITING = "waiting"
+    INPUT_REQUIRED = "input_required"
+    AUTH_REQUIRED = "auth_required"
+
+    # approvals
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+    # execution lifecycle
+    DISPATCHED = "dispatched"
+    RUNNING = "running"
+    PAUSED = "paused"
+
+    # final states
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    # (legacy / generic)
+    PENDING = "pending"  # optional catch-all
+    ACTIVE = "active"
+    SUSPENDED = "suspended"
+    DISABLED = "disabled"
+    DELETED = "deleted"
+
+
+# ────────────────────────────────────────────────────────────────────────
+# 2. Persistent lookup table
+# ────────────────────────────────────────────────────────────────────────
+class StatusEnum(Base, Timestamped):
+    """
+    id       – surrogate PK (easy FK if needed elsewhere)
+    code     – canonical string value from the Status enum
+    label    – human-readable label (“Paused”, “Failed”, …)
+    """
+
+    __tablename__ = "status_enums"
+
+    id: Mapped[int] = acol(
+        storage=S(Integer, primary_key=True, autoincrement=True),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    code: Mapped[Status] = acol(
+        storage=S(
+            SAEnum(Status, name="status_code_enum"),
+            nullable=False,
+            unique=True,
+        ),
+        field=F(py_type=Status),
+        io=IO(out_verbs=("read", "list")),
+    )
+    label: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+
+    def __repr__(self) -> str:  # noqa: D401
+        return f"<StatusEnum {self.code}>"
+
+
+__all__ = ["Status", "StatusEnum"]
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/orm/tables/tenant.py

@@ -0,0 +1,22 @@
+"""Tenant model."""
+
+from ._base import Base
+from ..mixins import GUIDPk, Slugged, Timestamped
+
+
+class Tenant(Base, GUIDPk, Slugged, Timestamped):
+    __tablename__ = "tenants"
+    __abstract__ = True
+
+
+__all__ = ["Tenant"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+    return sorted(__all__)

tigrbl/orm/tables/user.py

@@ -0,0 +1,39 @@
+"""User model."""
+
+from ._base import Base
+from ..mixins import (
+    GUIDPk,
+    Timestamped,
+    TenantBound,
+    Principal,
+    AsyncCapable,
+    ActiveToggle,
+)
+from ...specs import IO, acol, F, S
+from ...types import Mapped, String
+
+
+class User(
+    Base, GUIDPk, Timestamped, TenantBound, Principal, AsyncCapable, ActiveToggle
+):
+    __tablename__ = "users"
+    __abstract__ = True
+    username: Mapped[str] = acol(
+        storage=S(String(32), nullable=False),
+        field=F(constraints={"max_length": 32}),
+        io=IO(),
+    )
+
+
+__all__ = ["User"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/response/README.md

@@ -0,0 +1,34 @@
+# Response and Template Specs
+
+Tigrbl exposes flexible response configuration through the `ResponseSpec` and `TemplateSpec` dataclasses in `tigrbl.response.types`.
+
+## `ResponseSpec`
+
+`ResponseSpec` controls how an operation returns data:
+
+- **`kind`** – response mode: `"auto"`, `"json"`, `"html"`, `"text"`, `"file"`, `"stream"`, or `"redirect"`.
+- **`media_type`** – explicit `Content-Type` header.
+- **`status_code`** – HTTP status override.
+- **`headers`** – mapping of additional headers.
+- **`envelope`** – wrap payloads in a standard envelope when `True`.
+- **`template`** – optional [`TemplateSpec`](#templatespec) to render an HTML response.
+- **`filename`** – file name for `file` responses.
+- **`download`** – force browser downloads when `True`.
+- **`etag`** – ETag header value.
+- **`cache_control`** – `Cache-Control` header value.
+- **`redirect_to`** – target location for `redirect` responses.
+
+## `TemplateSpec`
+
+`TemplateSpec` defines how templates are resolved and rendered:
+
+- **`name`** – template identifier passed to the renderer.
+- **`search_paths`** – directories to search for template files.
+- **`package`** – Python package providing templates via `importlib.resources`.
+- **`auto_reload`** – when `True`, reload templates on each request (useful in development).
+- **`filters`** – custom Jinja2 filters.
+- **`globals`** – additional template globals.
+
+A `TemplateSpec` may be nested inside a `ResponseSpec`'s `template` field to render HTML output. When provided, the runtime invokes `render_template` and populates the response body with the rendered HTML.
+
+These specs offer a declarative way to tailor outbound responses and integrate server-side templates without manual response handling.

tigrbl/response/__init__.py

@@ -0,0 +1,33 @@
+from .decorators import response_ctx, get_attached_response_spec
+from .types import (
+    Response,
+    ResponseKind,
+    ResponseSpec,
+    Template,
+    TemplateSpec,
+)
+from .resolver import resolve_response_spec, infer_hints
+from .shortcuts import as_json, as_html, as_text, as_redirect, as_stream, as_file
+from ..runtime.atoms.response.renderer import ResponseHints, render
+from ..runtime.atoms.response.templates import render_template
+
+__all__ = [
+    "response_ctx",
+    "get_attached_response_spec",
+    "ResponseSpec",
+    "ResponseKind",
+    "TemplateSpec",
+    "Response",
+    "Template",
+    "resolve_response_spec",
+    "infer_hints",
+    "as_json",
+    "as_html",
+    "as_text",
+    "as_redirect",
+    "as_stream",
+    "as_file",
+    "ResponseHints",
+    "render",
+    "render_template",
+]

tigrbl/response/bind.py

@@ -0,0 +1,12 @@
+"""Response binding helpers (placeholder)."""
+
+from __future__ import annotations
+from typing import Any, Dict
+
+
+def bind(collected: Dict[str, Any]) -> None:  # pragma: no cover - trivial
+    """Bind collected response configuration. Currently a no-op."""
+    return None
+
+
+__all__ = ["bind"]

tigrbl/response/decorators.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+from typing import Any, Callable, Optional, TypeVar, overload
+
+from .types import ResponseSpec
+
+T = TypeVar("T")
+_ATTR = "__tigrbl_response_spec__"
+
+
+def _to_spec(spec: Optional[ResponseSpec] = None, **kwargs: Any) -> ResponseSpec:
+    if spec is not None and kwargs:
+        raise TypeError("response_ctx: provide either a ResponseSpec or keyword args")
+    if spec is not None:
+        return spec
+    return ResponseSpec(**kwargs)
+
+
+@overload
+def response_ctx(spec: ResponseSpec) -> Callable[[T], T]: ...
+
+
+@overload
+def response_ctx(**kwargs: Any) -> Callable[[T], T]: ...
+
+
+def response_ctx(*args: Any, **kwargs: Any) -> Callable[[T], T]:
+    spec = _to_spec(*args, **kwargs)
+
+    def decorator(target: T) -> T:
+        setattr(target, _ATTR, spec)
+        return target
+
+    return decorator
+
+
+def get_attached_response_spec(obj: Any) -> Optional[ResponseSpec]:
+    return getattr(obj, _ATTR, None)

tigrbl/response/resolver.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+from typing import Dict, Optional
+
+from dataclasses import fields
+from .types import ResponseSpec, TemplateSpec
+from ..runtime.atoms.response.renderer import ResponseHints
+
+
+def _merge_template(
+    base: Optional[TemplateSpec], over: Optional[TemplateSpec]
+) -> Optional[TemplateSpec]:
+    if over is None:
+        return base
+    if base is None:
+        return over
+    paths = list(base.search_paths)
+    for p in over.search_paths:
+        if p not in paths:
+            paths.append(p)
+    return TemplateSpec(
+        name=over.name or base.name,
+        search_paths=paths,
+        package=over.package or base.package,
+        auto_reload=over.auto_reload
+        if over.auto_reload is not None
+        else base.auto_reload,
+        filters={**base.filters, **over.filters},
+        globals={**base.globals, **over.globals},
+    )
+
+
+def _merge(
+    base: Optional[ResponseSpec], over: Optional[ResponseSpec]
+) -> Optional[ResponseSpec]:
+    if over is None:
+        return base
+    if base is None:
+        return over
+    data = {f.name: getattr(base, f.name) for f in fields(base)}
+    for f in fields(over):
+        v = getattr(over, f.name)
+        if v is not None:
+            if f.name == "template":
+                data[f.name] = _merge_template(getattr(base, f.name), v)
+            elif isinstance(v, dict) and isinstance(data.get(f.name), dict):
+                d = dict(data.get(f.name))
+                d.update(v)
+                data[f.name] = d
+            else:
+                data[f.name] = v
+    return ResponseSpec(**data)
+
+
+def resolve_response_spec(
+    *candidates: Optional[ResponseSpec],
+) -> Optional[ResponseSpec]:
+    spec: Optional[ResponseSpec] = None
+    for c in candidates:
+        spec = _merge(spec, c)
+    return spec
+
+
+def infer_hints(
+    spec: Optional[ResponseSpec],
+) -> tuple[ResponseHints, Optional[bool], Optional[str]]:
+    if spec is None:
+        return ResponseHints(), None, None
+    headers: Dict[str, str] = dict(spec.headers or {})
+    if spec.cache_control:
+        headers.setdefault("Cache-Control", spec.cache_control)
+    hints = ResponseHints(
+        media_type=spec.media_type,
+        status_code=spec.status_code or 200,
+        headers=headers,
+        filename=spec.filename,
+        download=bool(spec.download) if spec.download is not None else False,
+        etag=spec.etag,
+    )
+    default_media = spec.media_type
+    return hints, spec.envelope, default_media
+
+
+__all__ = ["resolve_response_spec", "infer_hints"]

tigrbl/response/shortcuts.py

@@ -0,0 +1,144 @@
+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
+
+from ..deps.starlette import (
+    JSONResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    StreamingResponse,
+    FileResponse as StarletteFileResponse,
+    RedirectResponse,
+    Response,
+)
+
+try:
+    import orjson as _orjson
+
+    def _dumps(obj: Any) -> bytes:
+        return _orjson.dumps(
+            obj, option=_orjson.OPT_NON_STR_KEYS | _orjson.OPT_SERIALIZE_NUMPY
+        )
+except Exception:  # pragma: no cover - fallback
+
+    def _dumps(obj: Any) -> bytes:
+        return json.dumps(
+            obj,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            default=str,
+        ).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",
+]