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

tigrbl/orm/mixins/principals.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from ...specs import ColumnSpec, F, S, acol
+from ...specs.storage_spec import ForeignKeySpec
+from ...types import PgUUID, UUID, declarative_mixin, declared_attr, uuid4, Mapped
+
+from .utils import _infer_schema, uuid_example, CRUD_IO, RO_IO
+
+
+@declarative_mixin
+class GUIDPk:
+    """Universal surrogate primary key."""
+
+    id: Mapped[UUID] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                primary_key=True,
+                default=uuid4,
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=RO_IO,
+        )
+    )
+
+
+@declarative_mixin
+class TenantColumn:
+    """Adds ``tenant_id`` with a schema-qualified FK to ``<schema>.tenants.id``."""
+
+    @declared_attr
+    def tenant_id(cls) -> Mapped[UUID]:
+        schema = getattr(cls, "__tenant_table_schema__", None) or _infer_schema(cls)
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{schema}.tenants.id"),
+                nullable=False,
+                index=True,
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=CRUD_IO,
+        )
+        return acol(spec=spec)
+
+
+@declarative_mixin
+class UserColumn:
+    """Adds ``user_id`` with a schema-qualified FK to ``<schema>.users.id``."""
+
+    @declared_attr
+    def user_id(cls) -> Mapped[UUID]:
+        schema = getattr(cls, "__user_table_schema__", None) or _infer_schema(cls)
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{schema}.users.id"),
+                nullable=False,
+                index=True,
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=CRUD_IO,
+        )
+        return acol(spec=spec)
+
+
+@declarative_mixin
+class OrgColumn:
+    """Adds ``org_id`` with a schema-qualified FK to ``<schema>.orgs.id``."""
+
+    @declared_attr
+    def org_id(cls) -> Mapped[UUID]:
+        schema = getattr(cls, "__org_table_schema__", None) or _infer_schema(cls)
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{schema}.orgs.id"),
+                nullable=False,
+                index=True,
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=CRUD_IO,
+        )
+        return acol(spec=spec)
+
+
+@declarative_mixin
+class Principal:
+    __abstract__ = True
+
+
+__all__ = [
+    "GUIDPk",
+    "TenantColumn",
+    "UserColumn",
+    "OrgColumn",
+    "Principal",
+]

tigrbl/orm/mixins/tenant_bound.py

@@ -0,0 +1,301 @@
+"""Tenant scoping mixin for Tigrbl v3."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Any, Mapping
+from uuid import UUID
+
+from ._RowBound import _RowBound
+from ...specs import acol
+from ...config.constants import (
+    TIGRBL_TENANT_POLICY_ATTR,
+    CTX_AUTH_KEY,
+    CTX_TENANT_ID_KEY,
+)
+from ...runtime.errors import create_standardized_error
+from ...specs import ColumnSpec, F, IO, S
+from ...specs.storage_spec import ForeignKeySpec
+from ...types import Mapped, PgUUID, declared_attr
+
+
+log = logging.getLogger(__name__)
+
+
+class TenantPolicy(str, Enum):
+    CLIENT_SET = "client"  # client may supply tenant_id on create/update
+    DEFAULT_TO_CTX = "default"  # server fills tenant_id on create; immutable
+    STRICT_SERVER = "strict"  # server forces tenant_id and forbids changes
+
+
+def _infer_schema(cls, default: str = "public") -> str:
+    args = getattr(cls, "__table_args__", None)
+    if not args:
+        return default
+    if isinstance(args, dict):
+        return args.get("schema", default)
+    if isinstance(args, (tuple, list)):
+        for elem in args:
+            if isinstance(elem, dict) and "schema" in elem:
+                return elem["schema"]
+    return default
+
+
+def _is_missing(value) -> bool:
+    """Treat None or empty strings as 'not provided'."""
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def _normalize_uuid(val):
+    if isinstance(val, UUID):
+        return val
+    if isinstance(val, str):
+        try:
+            return UUID(val)
+        except ValueError:
+            return val  # let model validation surface the error
+    return val
+
+
+class TenantBound(_RowBound):
+    """
+    Plug-and-play tenant isolation.
+
+    • tenant_id column is defined per subclass (declared_attr) so the schema
+      builder sees the right flags before caching.
+    • _RowBound’s read/list filters work because we implement `is_visible`.
+    """
+
+    __tigrbl_tenant_policy__: TenantPolicy = TenantPolicy.CLIENT_SET
+
+    # ────────────────────────────────────────────────────────────────────
+    # tenant_id column (Schema-Aware; PgUUID(as_uuid=True))
+    # -------------------------------------------------------------------
+    @declared_attr
+    def tenant_id(cls) -> Mapped[UUID]:
+        pol = getattr(cls, TIGRBL_TENANT_POLICY_ATTR, TenantPolicy.CLIENT_SET)
+        schema = _infer_schema(cls, default="public")
+
+        in_verbs = (
+            ("create", "update", "replace")
+            if pol == TenantPolicy.CLIENT_SET
+            else ("create",)
+        )
+        io = IO(
+            in_verbs=in_verbs,
+            out_verbs=("read", "list"),
+            mutable_verbs=in_verbs,
+        )
+
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{schema}.tenants.id"),
+                nullable=False,
+                index=True,
+            ),
+            field=F(py_type=UUID),
+            io=io,
+        )
+        return acol(spec=spec)
+
+    @declared_attr
+    def __tablename__(cls):
+        return cls.__name__.lower()
+
+    # -------------------------------------------------------------------
+    # Row-level visibility for _RowBound
+    # -------------------------------------------------------------------
+    @staticmethod
+    def is_visible(obj, ctx) -> bool:
+        return getattr(obj, "tenant_id", None) == _ctx_tenant_id(ctx)
+
+    # -------------------------------------------------------------------
+    # Runtime hooks
+    # -------------------------------------------------------------------
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        cls._install_tenant_bound_hooks()
+
+    @classmethod
+    def _install_tenant_bound_hooks(cls) -> None:
+        pol = getattr(cls, "__tigrbl_tenant_policy__", TenantPolicy.CLIENT_SET)
+
+        def _err(code: int, msg: str) -> None:
+            http_exc, _, _ = create_standardized_error(code, message=msg)
+            raise http_exc
+
+        def _before_create(ctx: dict[str, Any]) -> None:
+            env = (
+                ctx.get("env") if isinstance(ctx, dict) else getattr(ctx, "env", None)
+            ) or {}
+            params = (
+                (
+                    env.get("params")
+                    if isinstance(env, dict)
+                    else getattr(env, "params", None)
+                )
+                or (
+                    ctx.get("payload")
+                    if isinstance(ctx, dict)
+                    else getattr(ctx, "payload", None)
+                )
+                or {}
+            )
+            if hasattr(params, "model_dump"):
+                params = params.model_dump()
+
+            tenant_id = _ctx_tenant_id(ctx)
+            provided = params.get("tenant_id")
+            missing = _is_missing(provided)
+
+            if pol == TenantPolicy.STRICT_SERVER:
+                if tenant_id is None:
+                    _err(400, "tenant_id is required.")
+                if not missing:
+                    if _normalize_uuid(provided) != _normalize_uuid(tenant_id):
+                        _err(400, "tenant_id mismatch.")
+                    _err(400, "tenant_id is server-assigned.")
+                params["tenant_id"] = tenant_id
+            elif pol == TenantPolicy.DEFAULT_TO_CTX:
+                if missing and tenant_id is not None:
+                    params["tenant_id"] = tenant_id
+                elif not missing:
+                    params["tenant_id"] = _normalize_uuid(provided)
+            else:  # CLIENT_SET
+                if not missing:
+                    params["tenant_id"] = _normalize_uuid(provided)
+
+            env_attr = (
+                ctx.get("env") if isinstance(ctx, dict) else getattr(ctx, "env", None)
+            )
+            if env_attr is not None:
+                if isinstance(env_attr, dict):
+                    env_attr["params"] = params
+                else:
+                    env_attr.params = params
+            if isinstance(ctx, dict):
+                ctx["payload"] = params
+            else:
+                setattr(ctx, "payload", params)
+
+        def _before_update(ctx: dict[str, Any]) -> None:
+            env = (
+                ctx.get("env") if isinstance(ctx, dict) else getattr(ctx, "env", None)
+            ) or {}
+            params = (
+                (
+                    env.get("params")
+                    if isinstance(env, dict)
+                    else getattr(env, "params", None)
+                )
+                or (
+                    ctx.get("payload")
+                    if isinstance(ctx, dict)
+                    else getattr(ctx, "payload", None)
+                )
+                or {}
+            )
+            if hasattr(params, "model_dump"):
+                params = params.model_dump()
+
+            if "tenant_id" not in params:
+                return
+
+            if _is_missing(params.get("tenant_id")):
+                params.pop("tenant_id", None)
+                env_attr = (
+                    ctx.get("env")
+                    if isinstance(ctx, dict)
+                    else getattr(ctx, "env", None)
+                )
+                if env_attr is not None:
+                    if isinstance(env_attr, dict):
+                        env_attr["params"] = params
+                    else:
+                        env_attr.params = params
+                if isinstance(ctx, dict):
+                    ctx["payload"] = params
+                else:
+                    setattr(ctx, "payload", params)
+                return
+
+            if pol != TenantPolicy.CLIENT_SET:
+                _err(400, "tenant_id is immutable.")
+
+            new_val = _normalize_uuid(params["tenant_id"])
+            tenant_id = _ctx_tenant_id(ctx)
+            is_admin = bool(ctx.get("is_admin"))
+
+            if not is_admin and tenant_id is not None and new_val != tenant_id:
+                _err(403, "Cannot switch tenant context.")
+
+            params["tenant_id"] = new_val
+            env_attr = (
+                ctx.get("env") if isinstance(ctx, dict) else getattr(ctx, "env", None)
+            )
+            if env_attr is not None:
+                if isinstance(env_attr, dict):
+                    env_attr["params"] = params
+                else:
+                    env_attr.params = params
+            if isinstance(ctx, dict):
+                ctx["payload"] = params
+            else:
+                setattr(ctx, "payload", params)
+
+        hooks = {**getattr(cls, "__tigrbl_hooks__", {})}
+
+        def _append(alias: str, phase: str, fn) -> None:
+            phase_map = hooks.get(alias) or {}
+            lst = list(phase_map.get(phase) or [])
+            if fn not in lst:
+                lst.append(fn)
+            phase_map[phase] = tuple(lst)
+            hooks[alias] = phase_map
+
+        _append("create", "PRE_TX_BEGIN", _before_create)
+        _append("update", "PRE_TX_BEGIN", _before_update)
+
+        setattr(cls, "__tigrbl_hooks__", hooks)
+
+
+def _ctx_tenant_id(ctx: Mapping[str, Any]) -> Any | None:
+    """Best-effort extraction of tenant_id from ctx."""
+    t = (
+        ctx.get(CTX_TENANT_ID_KEY)
+        if isinstance(ctx, dict)
+        else getattr(ctx, CTX_TENANT_ID_KEY, None)
+    )
+    if t:
+        return _normalize_uuid(t)
+
+    auth = (
+        ctx.get(CTX_AUTH_KEY)
+        if isinstance(ctx, dict)
+        else getattr(ctx, CTX_AUTH_KEY, None)
+    ) or {}
+    t = auth.get(CTX_TENANT_ID_KEY)
+    if t:
+        return _normalize_uuid(t)
+
+    inj = (
+        ctx.get("injected_fields")
+        if isinstance(ctx, dict)
+        else getattr(ctx, "injected_fields", None)
+    ) or {}
+    t = inj.get(CTX_TENANT_ID_KEY)
+    if t:
+        return _normalize_uuid(t)
+
+    ac = (
+        ctx.get("auth_context")
+        if isinstance(ctx, dict)
+        else getattr(ctx, "auth_context", None)
+    ) or {}
+    t = ac.get(CTX_TENANT_ID_KEY)
+    if t:
+        return _normalize_uuid(t)
+
+    return None

tigrbl/orm/mixins/upsertable.py

@@ -0,0 +1,111 @@
+# tigrbl/v3/mixins/upsertable.py
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence, Optional, Tuple
+from sqlalchemy import and_, inspect as sa_inspect
+from tigrbl.types import Session
+
+
+class Upsertable:
+    """
+    Hybrid upsert:
+      • If __upsert_keys__ is set and fully present -> decide by those keys
+      • Else if all PK parts are present            -> decide by PK
+      • Else                                        -> no rewrite
+    """
+
+    __upsert_keys__: Sequence[str] | None = None  # optional natural key list
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        cls._install_upsertable_hooks()
+
+    @classmethod
+    def _install_upsertable_hooks(cls) -> None:
+        hooks = {**getattr(cls, "__tigrbl_hooks__", {})}
+
+        def _append(alias: str, phase: str, fn) -> None:
+            phase_map = hooks.get(alias) or {}
+            lst = list(phase_map.get(phase) or [])
+            if fn not in lst:
+                lst.append(fn)
+            phase_map[phase] = tuple(lst)
+            hooks[alias] = phase_map
+
+        for op in ("create", "update", "replace"):
+            _append(op, "PRE_TX_BEGIN", cls._make_upsert_rewrite_hook(op))
+
+        setattr(cls, "__tigrbl_hooks__", hooks)
+
+    @classmethod
+    def _make_upsert_rewrite_hook(cls, verb: str):
+        tab = "".join(w.title() for w in cls.__tablename__.split("_"))
+
+        async def _rewrite(ctx: Mapping[str, Any]) -> None:
+            params = ctx["env"].params if ctx.get("env") else {}
+            if hasattr(params, "model_dump"):
+                params = params.model_dump()
+            if not isinstance(params, Mapping):
+                return
+
+            db: Session = ctx["db"]
+            mapper = sa_inspect(cls)
+
+            # 1) Try natural keys if declared
+            key_names: Sequence[str] | None = cls.__upsert_keys__
+            if key_names:
+                kv = _extract_values(params, key_names)
+                if kv is not None:
+                    exists = _exists_by_names(cls, db, key_names, kv)
+                    _rewrite_by_existence(ctx, tab, verb, exists)
+                    return  # done
+
+            # 2) Fall back to PKs if fully present
+            pk_cols = tuple(mapper.primary_key)
+            pk_names = tuple(c.key for c in pk_cols)
+            kv = _extract_values(params, pk_names)
+            if kv is None:
+                return  # not enough info → no rewrite
+
+            exists = _exists_by_pk(cls, db, pk_cols, kv)
+            _rewrite_by_existence(ctx, tab, verb, exists)
+
+        return _rewrite
+
+
+def _extract_values(
+    p: Mapping[str, Any], names: Sequence[str]
+) -> Optional[Tuple[Any, ...]]:
+    vals = []
+    for n in names:
+        v = p.get(n)
+        if v is None:
+            return None
+        vals.append(v)
+    return tuple(vals)
+
+
+def _exists_by_names(
+    model, db: Session, names: Sequence[str], vals: Tuple[Any, ...]
+) -> bool:
+    q = db.query(model)
+    for n, v in zip(names, vals):
+        q = q.filter(getattr(model, n) == v)
+    return db.query(q.exists()).scalar() is True
+
+
+def _exists_by_pk(model, db: Session, pk_cols, pk_vals: Tuple[Any, ...]) -> bool:
+    if len(pk_cols) == 1:
+        # fast path
+        return db.get(model, pk_vals[0]) is not None
+    conds = [getattr(model, c.key) == v for c, v in zip(pk_cols, pk_vals)]
+    return db.query(db.query(model).filter(and_(*conds)).exists()).scalar() is True
+
+
+def _rewrite_by_existence(ctx, tab: str, verb: str, exists: bool) -> None:
+    if verb == "create" and exists:
+        ctx["env"].method = f"{tab}.update"
+    elif verb == "update" and not exists:
+        ctx["env"].method = f"{tab}.create"
+    elif verb == "replace":
+        ctx["env"].method = f"{tab}.update" if exists else f"{tab}.create"

tigrbl/orm/mixins/utils.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import datetime as dt
+
+from ...specs import IO
+from ...types import UUID
+
+
+def tzutcnow() -> dt.datetime:
+    """Return an aware UTC ``datetime``."""
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def tzutcnow_plus_day() -> dt.datetime:
+    """Return an aware UTC ``datetime`` one day in the future."""
+    return tzutcnow() + dt.timedelta(days=1)
+
+
+def _infer_schema(cls, default: str = "public") -> str:
+    """Extract schema from ``__table_args__`` in dict or tuple/list form."""
+    args = getattr(cls, "__table_args__", None)
+    if not args:
+        return default
+    if isinstance(args, dict):
+        return args.get("schema", default)
+    if isinstance(args, (tuple, list)):
+        for elem in args:
+            if isinstance(elem, dict) and "schema" in elem:
+                return elem["schema"]
+    return default
+
+
+uuid_example = UUID("00000000-dead-beef-cafe-000000000000")
+
+CRUD_IN = ("create", "update", "replace")
+CRUD_OUT = ("read", "list")
+CRUD_IO = IO(in_verbs=CRUD_IN, out_verbs=CRUD_OUT, mutable_verbs=CRUD_IN)
+RO_IO = IO(out_verbs=CRUD_OUT)
+
+__all__ = [
+    "tzutcnow",
+    "tzutcnow_plus_day",
+    "_infer_schema",
+    "uuid_example",
+    "CRUD_IN",
+    "CRUD_OUT",
+    "CRUD_IO",
+    "RO_IO",
+]

tigrbl/orm/tables/__init__.py

@@ -0,0 +1,72 @@
+"""Public façade for all table classes.
+
+Usage
+-----
+    from tigrbl.orm.tables import (
+        Tenant,
+        User,
+        Group,
+        Role,
+    )
+"""
+
+import importlib
+from typing import TYPE_CHECKING, Any
+from ._base import Base
+
+__all__ = [
+    "Tenant",
+    "Client",
+    "User",
+    "Group",
+    "Org",
+    "Role",
+    "RolePerm",
+    "RoleGrant",
+    "Status",
+    "StatusEnum",
+    "Change",
+    "Base",
+]
+
+# ------------------------------------------------------------------ #
+# Lazy attribute loader (PEP 562). Keeps import graphs light-weight.
+# ------------------------------------------------------------------ #
+_module_map = {
+    "Tenant": f"{__name__}.tenant",
+    "Client": f"{__name__}.client",
+    "User": f"{__name__}.user",
+    "Group": f"{__name__}.group",
+    "Org": f"{__name__}.org",
+    "Role": f"{__name__}.rbac",
+    "RolePerm": f"{__name__}.rbac",
+    "RoleGrant": f"{__name__}.rbac",
+    "Status": f"{__name__}.status",
+    "StatusEnum": f"{__name__}.status",
+    "Change": f"{__name__}.audit",
+}
+
+
+def __getattr__(name: str) -> Any:  # noqa: D401
+    """Dynamically import `tenant`, `user`, or `group` on first use."""
+    if name not in _module_map:
+        raise AttributeError(name)
+    module = importlib.import_module(_module_map[name])
+    obj = getattr(module, name)
+    globals()[name] = obj  # cache for future look-ups
+    return obj
+
+
+# ------------------------------------------------------------------ #
+# Static typing support – imported eagerly only during type checking.
+# ------------------------------------------------------------------ #
+if TYPE_CHECKING:  # pragma: no cover
+    from ._base import Base
+    from .tenant import Tenant
+    from .client import Client
+    from .user import User
+    from .group import Group
+    from .org import Org
+    from .rbac import Role, RoleGrant, RolePerm
+    from .status import Status, StatusEnum
+    from .audit import Change

tigrbl/orm/tables/_base.py

@@ -0,0 +1,8 @@
+"""Compatibility layer for Base moved to tigrbl.table."""
+
+from __future__ import annotations
+
+from ...table import Base
+from ...table._base import _materialize_colspecs_to_sqla
+
+__all__ = ["Base", "_materialize_colspecs_to_sqla"]

tigrbl/orm/tables/audit.py

@@ -0,0 +1,56 @@
+# tigrbl/tables/audit.py
+import datetime as dt
+from uuid import UUID
+
+from . import Base
+from ..mixins import GUIDPk, Timestamped
+from ...specs import IO, F, acol, S
+from ...types import DateTime, Integer, String, PgUUID, Mapped
+
+
+class Change(Base, GUIDPk, Timestamped):
+    __tablename__ = "changes"
+
+    seq: Mapped[int] = acol(
+        storage=S(Integer, primary_key=True),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    at: Mapped[dt.datetime] = acol(
+        storage=S(DateTime, default=dt.datetime.utcnow),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    actor_id: Mapped[UUID | None] = acol(
+        storage=S(PgUUID, nullable=True),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    table_name: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    row_id: Mapped[UUID | None] = acol(
+        storage=S(PgUUID, nullable=True),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+    action: Mapped[str] = acol(
+        storage=S(String),
+        field=F(),
+        io=IO(out_verbs=("read", "list")),
+    )
+
+
+__all__ = ["Change"]
+
+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__)