tigrbl 0.3.0.dev3__py3-none-any.whl → 0.3.1__py3-none-any.whl

tigrbl/api/_api.py

@@ -6,7 +6,9 @@ from types import SimpleNamespace
 from ..deps.fastapi import APIRouter as ApiRouter
 from ..engine.engine_spec import EngineCfg
 from ..engine import install_from_objects
+from ..ddl import initialize as _ddl_initialize
 from ..engine import resolver as _resolver
+from ..app._model_registry import initialize_model_registry
 from .api_spec import APISpec
 
 
@@ -41,7 +43,7 @@ class Api(APISpec, ApiRouter):
         self.deps = tuple(getattr(self, "DEPS", ()))
         self.response = getattr(self, "RESPONSE", None)
         # ``models`` is expected to be a dict at runtime for registry lookups.
-        self.models: dict[str, type] = {}
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
 
         ApiRouter.__init__(
             self,
@@ -70,3 +72,26 @@ class Api(APISpec, ApiRouter):
                 install_from_objects(app=self, api=a, models=models)
         else:
             install_from_objects(app=self, api=None, models=models)
+
+    def _collect_tables(self) -> list[Any]:
+        seen = set()
+        tables = []
+        for model in self.models.values():
+            if not hasattr(model, "__table__"):
+                try:  # pragma: no cover - defensive remap
+                    from ..table import Base
+                    from ..table._base import _materialize_colspecs_to_sqla
+
+                    _materialize_colspecs_to_sqla(model)
+                    Base.registry.map_declaratively(model)
+                except Exception:
+                    pass
+            table = getattr(model, "__table__", None)
+            if table is not None and not table.columns:
+                continue
+            if table is not None and table not in seen:
+                seen.add(table)
+                tables.append(table)
+        return tables
+
+    initialize = _ddl_initialize

tigrbl/api/tigrbl_api.py

@@ -32,6 +32,7 @@ from ..bindings.rest import build_router_and_attach as _build_router_and_attach
 from ..transport import mount_jsonrpc as _mount_jsonrpc
 from ..system import mount_diagnostics as _mount_diagnostics
 from ..op import get_registry, OpSpec
+from ..app._model_registry import initialize_model_registry
 
 
 class TigrblApi(_Api):
@@ -73,7 +74,7 @@ class TigrblApi(_Api):
         self.system_prefix = system_prefix
 
         # public containers (mirrors used by bindings.api)
-        self.models: Dict[str, type] = {}
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
         self.schemas = SimpleNamespace()
         self.handlers = SimpleNamespace()
         self.hooks = SimpleNamespace()
@@ -231,6 +232,8 @@ class TigrblApi(_Api):
     ) -> None:
         if authn is not None:
             self._authn = authn
+            if allow_anon is None:
+                allow_anon = False
         if allow_anon is not None:
             self._allow_anon = bool(allow_anon)
         if authorize is not None:
@@ -270,6 +273,8 @@ class TigrblApi(_Api):
         tables = []
         for m in self.models.values():
             t = getattr(m, "__table__", None)
+            if t is not None and not t.columns:
+                continue
             if t is not None and t not in seen:
                 seen.add(t)
                 tables.append(t)

tigrbl/app/_app.py

@@ -6,6 +6,8 @@ from ..deps.fastapi import FastAPI
 from ..engine.engine_spec import EngineCfg
 from ..engine import resolver as _resolver
 from ..engine import install_from_objects
+from ..ddl import initialize as _ddl_initialize
+from ._model_registry import initialize_model_registry
 from .app_spec import AppSpec
 
 
@@ -23,7 +25,7 @@ class App(AppSpec, FastAPI):
         self.ops = tuple(getattr(self, "OPS", ()))
         # Runtime registries use mutable containers (dict/namespace), but the
         # dataclass fields expect sequences. Storing a dict here satisfies both.
-        self.models = {}
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
         self.schemas = tuple(getattr(self, "SCHEMAS", ()))
         self.hooks = tuple(getattr(self, "HOOKS", ()))
         self.security_deps = tuple(getattr(self, "SECURITY_DEPS", ()))
@@ -59,3 +61,26 @@ class App(AppSpec, FastAPI):
                 install_from_objects(app=self, api=a, models=models)
         else:
             install_from_objects(app=self, api=None, models=models)
+
+    def _collect_tables(self) -> list[Any]:
+        seen = set()
+        tables = []
+        for model in self.models.values():
+            if not hasattr(model, "__table__"):
+                try:  # pragma: no cover - defensive remap
+                    from ..table import Base
+                    from ..table._base import _materialize_colspecs_to_sqla
+
+                    _materialize_colspecs_to_sqla(model)
+                    Base.registry.map_declaratively(model)
+                except Exception:
+                    pass
+            table = getattr(model, "__table__", None)
+            if table is not None and not table.columns:
+                continue
+            if table is not None and table not in seen:
+                seen.add(table)
+                tables.append(table)
+        return tables
+
+    initialize = _ddl_initialize

tigrbl/app/_model_registry.py

@@ -0,0 +1,41 @@
+"""Utilities for initializing model registries on App and API facades."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def initialize_model_registry(models: Iterable[Any]) -> dict[str, Any]:
+    """Build the default ``models`` mapping for an App or Api instance.
+
+    ``defineAppSpec``/``defineApiSpec`` allow authors to declare default models
+    using bare model classes or ``("alias", Model)`` tuples.  Runtime facades,
+    however, expect ``self.models`` to be a dictionary keyed by model name so
+    that lookups like ``app.models["Widget"]`` Just Work.
+
+    This helper normalizes the declared sequence into that dictionary shape and
+    preserves declaration order.  When an alias is provided we register both the
+    alias and the model's ``__name__`` so either lookup style succeeds.
+    """
+
+    registry: dict[str, Any] = {}
+
+    for entry in models or ():
+        # Support ``("Alias", Model)`` declarations in addition to bare models.
+        if isinstance(entry, tuple) and len(entry) == 2 and isinstance(entry[0], str):
+            alias, model = entry
+            registry[alias] = model
+            model_name = getattr(model, "__name__", alias)
+            registry.setdefault(model_name, model)
+            continue
+
+        model = entry
+        model_name = getattr(model, "__name__", None)
+        if model_name is None:
+            model_name = str(model)
+        registry[model_name] = model
+
+    return registry
+
+
+__all__ = ["initialize_model_registry"]

tigrbl/app/tigrbl_app.py

@@ -32,6 +32,7 @@ from ..bindings.rest import build_router_and_attach as _build_router_and_attach
 from ..transport import mount_jsonrpc as _mount_jsonrpc
 from ..system import mount_diagnostics as _mount_diagnostics
 from ..op import get_registry, OpSpec
+from ._model_registry import initialize_model_registry
 
 
 # optional compat: legacy transactional decorator
@@ -93,7 +94,7 @@ class TigrblApp(_App):
         self.system_prefix = system_prefix
 
         # public containers (mirrors used by bindings.api)
-        self.models: Dict[str, type] = {}
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
         self.schemas = SimpleNamespace()
         self.handlers = SimpleNamespace()
         self.hooks = SimpleNamespace()
@@ -262,6 +263,8 @@ class TigrblApp(_App):
     ) -> None:
         if authn is not None:
             self._authn = authn
+            if allow_anon is None:
+                allow_anon = False
         if allow_anon is not None:
             self._allow_anon = bool(allow_anon)
         if authorize is not None:
@@ -301,6 +304,8 @@ class TigrblApp(_App):
         tables = []
         for m in self.models.values():
             t = getattr(m, "__table__", None)
+            if t is not None and not t.columns:
+                continue
             if t is not None and t not in seen:
                 seen.add(t)
                 tables.append(t)

tigrbl/bindings/rest/collection.py

@@ -35,6 +35,8 @@ from .common import (
     _status_for,
 )
 
+from .io_headers import _make_header_dep
+
 from ...runtime.executor.types import _Ctx
 
 
@@ -103,6 +105,7 @@ def _make_collection_endpoint(
 ) -> Callable[..., Awaitable[Any]]:
     alias, target, nested_vars = sp.alias, sp.target, list(nested_vars or [])
     status_code = _status_for(sp)
+    hdr_dep = _make_header_dep(model, alias)
 
     if target in {"list", "clear"}:
         list_dep = _make_list_query_dep(model, alias) if target == "list" else None
@@ -110,6 +113,7 @@ def _make_collection_endpoint(
         async def _endpoint(
             request: Request,
             db: Any = Depends(db_dep),
+            h: Mapping[str, Any] = Depends(hdr_dep),
             q: Mapping[str, Any] | None = None,
             **kw: Any,
         ):
@@ -120,6 +124,8 @@ def _make_collection_endpoint(
                 payload = _validate_query(model, alias, target, query)
             else:
                 payload = dict(parent_kw)
+            if isinstance(h, Mapping):
+                payload = {**payload, **dict(h)}
             ctx = _ctx(model, alias, target, request, db, payload, parent_kw, api)
             ctx["response_serializer"] = lambda r: _serialize_output(
                 model, alias, target, sp, r
@@ -154,16 +160,20 @@ def _make_collection_endpoint(
                     inspect.Parameter.POSITIONAL_OR_KEYWORD,
                     annotation=Annotated[Any, Depends(db_dep)],
                 ),
+                inspect.Parameter(
+                    "h",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+                ),
             ]
         )
         if target == "list":
-            params.insert(
-                len(nested_vars) + 1,
+            params.append(
                 inspect.Parameter(
                     "q",
                     inspect.Parameter.POSITIONAL_OR_KEYWORD,
                     annotation=Annotated[Mapping[str, Any], Depends(list_dep)],
-                ),
+                )
             )
         _endpoint.__signature__ = inspect.Signature(params)
     else:
@@ -192,12 +202,18 @@ def _make_collection_endpoint(
         async def _endpoint(
             request: Request,
             db: Any = Depends(db_dep),
+            h: Mapping[str, Any] = Depends(hdr_dep),
             body=Body(...),
             **kw: Any,
         ):
             parent_kw = {k: kw[k] for k in nested_vars if k in kw}
             _coerce_parent_kw(model, parent_kw)
             payload = _validate_body(model, alias, target, body)
+            if isinstance(h, Mapping):
+                if isinstance(payload, Mapping):
+                    payload = {**payload, **dict(h)}
+                else:
+                    payload = [{**dict(item), **dict(h)} for item in payload]
             is_seq = (
                 target in {"create", "update", "replace", "merge"}
                 and isinstance(payload, Sequence)
@@ -248,6 +264,11 @@ def _make_collection_endpoint(
                     inspect.Parameter.POSITIONAL_OR_KEYWORD,
                     annotation=Annotated[Any, Depends(db_dep)],
                 ),
+                inspect.Parameter(
+                    "h",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+                ),
                 inspect.Parameter(
                     "body",
                     inspect.Parameter.POSITIONAL_OR_KEYWORD,

tigrbl/bindings/rest/common.py

@@ -45,6 +45,8 @@ from .routing import (
     _default_path_suffix,
     _normalize_deps,
     _normalize_secdeps,
+    _require_auth_header,
+    _requires_auth_header,
     _path_for_spec,
     _request_model_for,
     _response_model_for,
@@ -106,6 +108,8 @@ __all__ = [
     "_optionalize_list_in_model",
     "_normalize_deps",
     "_normalize_secdeps",
+    "_require_auth_header",
+    "_requires_auth_header",
     "_status_for",
     "_RESPONSES_META",
     "_DEFAULT_METHODS",

tigrbl/bindings/rest/io_headers.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import inspect
+from typing import Mapping, Any
+
+from fastapi import Header
+
+
+def _build_signature_with_header_params(
+    hdr_fields: list[tuple[str, str, bool]],
+) -> inspect.Signature:
+    params: list[inspect.Parameter] = []
+    for _field, header, required in hdr_fields:
+        param = header.lower().replace("-", "_")
+        default = Header(... if required else None, alias=header)
+        params.append(
+            inspect.Parameter(
+                name=param,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                default=default,
+                annotation=str | None,
+            )
+        )
+    return inspect.Signature(parameters=params, return_annotation=Mapping[str, object])
+
+
+def _make_header_dep(model: type, alias: str):
+    hdr_fields: list[tuple[str, str, bool]] = []
+    for name, spec in getattr(model, "__tigrbl_cols__", {}).items():
+        io = getattr(spec, "io", None)
+        if not io or not getattr(io, "header_in", None):
+            continue
+        if alias not in set(getattr(io, "in_verbs", ()) or ()):  # honor IO.in_verbs
+            continue
+        hdr_fields.append(
+            (name, io.header_in, bool(getattr(io, "header_required_in", False)))
+        )
+
+    async def _dep(**kw: Any) -> Mapping[str, object]:
+        out: dict[str, object] = {}
+        for field, header, _req in hdr_fields:
+            param = header.lower().replace("-", "_")
+            v = kw.get(param)
+            if v is not None:
+                out[field] = v
+        return out
+
+    _dep.__signature__ = _build_signature_with_header_params(hdr_fields)
+    return _dep

tigrbl/bindings/rest/member.py

@@ -35,6 +35,8 @@ from .common import (
     _status_for,
 )
 
+from .io_headers import _make_header_dep
+
 from ...runtime.executor.types import _Ctx
 
 
@@ -58,6 +60,7 @@ def _make_member_endpoint(
     real_pk = _pk_name(model)
     pk_names = _pk_names(model)
     nested_vars = list(nested_vars or [])
+    hdr_dep = _make_header_dep(model, alias)
 
     # --- No body on GET read / DELETE delete ---
     if target in {"read", "delete"}:
@@ -66,11 +69,14 @@ def _make_member_endpoint(
             item_id: Any,
             request: Request,
             db: Any = Depends(db_dep),
+            h: Mapping[str, Any] = Depends(hdr_dep),
             **kw: Any,
         ):
             parent_kw = {k: kw[k] for k in nested_vars if k in kw}
             _coerce_parent_kw(model, parent_kw)
             payload: Mapping[str, Any] = dict(parent_kw)
+            if isinstance(h, Mapping):
+                payload = {**payload, **dict(h)}
             path_params = {real_pk: item_id, pk_param: item_id, **parent_kw}
             ctx: Dict[str, Any] = {
                 "request": request,
@@ -142,6 +148,11 @@ def _make_member_endpoint(
                     inspect.Parameter.POSITIONAL_OR_KEYWORD,
                     annotation=Annotated[Any, Depends(db_dep)],
                 ),
+                inspect.Parameter(
+                    "h",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+                ),
             ]
         )
         _endpoint.__signature__ = inspect.Signature(params)
@@ -257,12 +268,15 @@ def _make_member_endpoint(
         item_id: Any,
         request: Request,
         db: Any = Depends(db_dep),
+        h: Mapping[str, Any] = Depends(hdr_dep),
         body=body_default,
         **kw: Any,
     ):
         parent_kw = {k: kw[k] for k in nested_vars if k in kw}
         _coerce_parent_kw(model, parent_kw)
         payload = _validate_body(model, alias, target, body)
+        if isinstance(h, Mapping):
+            payload = {**payload, **dict(h)}
 
         # Enforce path-PK canonicality. If body echoes PK: drop if equal, 409 if mismatch.
         for k in pk_names:
@@ -350,6 +364,11 @@ def _make_member_endpoint(
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
                 annotation=Annotated[Any, Depends(db_dep)],
             ),
+            inspect.Parameter(
+                "h",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+            ),
             inspect.Parameter(
                 "body",
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,

tigrbl/bindings/rest/router.py

@@ -25,6 +25,8 @@ from .common import (
     _normalize_secdeps,
     _optionalize_list_in_model,
     _path_for_spec,
+    _require_auth_header,
+    _requires_auth_header,
     _req_state_db,
     _resource_name,
     _status,
@@ -265,6 +267,8 @@ def _build_router(
 
         secdeps: list[Any] = []
         if auth_dep and sp.alias not in allow_anon and sp.target not in allow_anon:
+            if _requires_auth_header(auth_dep):
+                secdeps.append(_require_auth_header)
             secdeps.append(auth_dep)
         secdeps.extend(getattr(sp, "secdeps", ()))
         route_secdeps = _normalize_secdeps(secdeps)

tigrbl/bindings/rest/routing.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
+import inspect
 import logging
 
 from types import SimpleNamespace
 from typing import Any, Dict, Optional, Sequence, Tuple
 
 
-from .fastapi import Depends, Security, _status
+from fastapi.security import HTTPBearer
+from .fastapi import Depends, HTTPException, Request, Security, _status
 from ...op import OpSpec
 from ...op.types import CANON
 
@@ -35,6 +37,24 @@ def _normalize_secdeps(secdeps: Optional[Sequence[Any]]) -> list[Any]:
     return out
 
 
+def _requires_auth_header(auth_dep: Any) -> bool:
+    try:
+        sig = inspect.signature(auth_dep)
+    except (TypeError, ValueError):
+        return False
+    for param in sig.parameters.values():
+        default = param.default
+        dep = getattr(default, "dependency", None)
+        if isinstance(dep, HTTPBearer) and getattr(dep, "auto_error", True):
+            return True
+    return False
+
+
+def _require_auth_header(request: Request) -> None:
+    if not request.headers.get("Authorization"):
+        raise HTTPException(status_code=_status.HTTP_403_FORBIDDEN, detail="Forbidden")
+
+
 def _status_for(sp: OpSpec) -> int:
     if sp.status_code is not None:
         return sp.status_code

tigrbl/column/io_spec.py

@@ -57,6 +57,9 @@ class IOSpec:
     mutable_verbs: Tuple[str, ...] = ()
     alias_in: str | None = None
     alias_out: str | None = None
+    header_in: str | None = None  # e.g., "X-Worker-Key"
+    header_out: str | None = None  # e.g., "ETag"
+    header_required_in: bool = False
     sensitive: bool = False
     redact_last: int | None = None
     filter_ops: Tuple[str, ...] = ()

tigrbl/engine/__init__.py

@@ -24,3 +24,22 @@ __all__ = [
     "Engine",
     "engine",
 ]
+
+
+# Optional engine plugin support
+from .plugins import load_engine_plugins
+from .registry import register_engine, known_engine_kinds, get_engine_registration
+
+# Load external engines automatically on import (idempotent)
+try:
+    load_engine_plugins()
+except Exception:
+    # Import-time plugin load should never fail the package import
+    pass
+
+__all__ += [
+    "load_engine_plugins",
+    "register_engine",
+    "known_engine_kinds",
+    "get_engine_registration",
+]

tigrbl/engine/_engine.py

@@ -27,6 +27,13 @@ if TYPE_CHECKING:  # pragma: no cover - for type checkers only
 
 @dataclass(frozen=True)
 class Provider:
+    # supports() exposes engine capabilities for compatibility checks
+    def supports(self) -> dict:
+        try:
+            return self.spec.supports()
+        except Exception:
+            return {"engine": self.spec.kind or "unknown"}
+
     """Lazily builds an engine + sessionmaker from an :class:`EngineSpec`."""
 
     spec: "EngineSpec"
@@ -87,6 +94,13 @@ class Provider:
 
 @dataclass
 class Engine:
+    # Delegate to provider/spec for capability reporting
+    def supports(self) -> dict:
+        try:
+            return self.provider.supports()
+        except Exception:
+            return {"engine": self.spec.kind or "unknown"}
+
     """Thin façade over an :class:`EngineSpec` with convenient (a)context managers."""
 
     spec: "EngineSpec"

tigrbl/engine/capabilities.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Any, Dict
+
+
+def sqlite_capabilities(*, async_: bool, memory: bool) -> Dict[str, Any]:
+    # SQLite supports transactional semantics; isolation semantics differ from server DBs.
+    # We expose a conservative set that higher layers can reason about.
+    return {
+        "transactional": True,
+        "async_native": async_,  # async layer is provided by aiosqlite/SQLAlchemy AsyncEngine
+        "isolation_levels": {"read_committed", "serializable"},
+        "read_only_enforced": False,  # app layer should enforce; file-open RO may be used externally
+        "supports_timeouts": True,
+        "supports_ddl": True,
+        "engine": "sqlite",
+        "memory": bool(memory),
+    }
+
+
+def postgres_capabilities(*, async_: bool) -> Dict[str, Any]:
+    return {
+        "transactional": True,
+        "async_native": async_,
+        "isolation_levels": {"read_committed", "repeatable_read", "serializable"},
+        "read_only_enforced": True,
+        "supports_timeouts": True,
+        "supports_ddl": True,
+        "engine": "postgres",
+    }

tigrbl/engine/decorators.py

@@ -56,7 +56,9 @@ def _normalize(ctx: Optional[EngineCfg] = None, **kw: Any) -> EngineCfg:
             if k in kw:
                 m[k] = kw[k]
     else:
-        raise ValueError("kind must be 'sqlite' or 'postgres'")
+        # Allow external engine kinds; pass mapping through unchanged.
+        # Keep provided keys as-is so external builders can interpret them.
+        m.update({k: v for k, v in kw.items() if k not in m})
 
     return m
 

tigrbl/engine/docs/PLUGINS.md

@@ -0,0 +1,49 @@
+
+# Tigrbl Engine Plugins
+
+Tigrbl supports external engine kinds via an entry-point group: `tigrbl.engine`.
+
+An external package registers itself by exposing a `register()` function and
+declaring an entry point:
+
+```toml
+[project.entry-points."tigrbl.engine"]
+duckdb = "tigrbl_engine_duckdb.plugin:register"
+```
+
+Inside `register()` call:
+
+```python
+from tigrbl.engine.registry import register_engine
+from .builder import duckdb_engine, duckdb_capabilities
+
+def register():
+    register_engine("duckdb", duckdb_engine, duckdb_capabilities)
+```
+
+At runtime, `EngineSpec(kind="duckdb")` will look up the registration and use
+the external builder or raise a helpful `RuntimeError` if the plugin is not
+installed.
+
+
+## Capabilities / supports()
+
+External engines should expose a capabilities callable when registering:
+
+```python
+from tigrbl.engine.registry import register_engine
+
+def my_engine_builder(...): ...
+def my_engine_capabilities(**kw):
+    # Return a dict describing what the engine supports
+    return {
+        "transactional": True,
+        "isolation_levels": {"read_committed","serializable"},
+        "read_only_enforced": True,
+        "async_native": False,
+        "engine": "myengine",
+    }
+
+def register():
+    register_engine("myengine", my_engine_builder, capabilities=my_engine_capabilities)
+```