tigrbl-core 0.4.2.dev4__py3-none-any.whl → 0.4.3.dev4__py3-none-any.whl

tigrbl_core/_spec/__init__.py

@@ -29,6 +29,8 @@ _EXPORTS = {
     "HttpStreamBindingSpec": "binding_spec",
     "SseBindingSpec": "binding_spec",
     "WebTransportBindingSpec": "binding_spec",
+    "WELL_KNOWN_PREFIX": "well_known_spec",
+    "WellKnownResourceSpec": "well_known_spec",
     "WsBindingSpec": "binding_spec",
     "resolve_rest_nested_prefix": "binding_spec",
     "ColumnSpec": "column_spec",
@@ -80,6 +82,8 @@ _EXPORTS = {
     "validate_app_framing_for_binding": "binding_spec",
     "validate_binding_profile_exchange": "binding_spec",
     "validate_path_binding": "path_spec",
+    "normalize_well_known_name": "well_known_spec",
+    "well_known_path": "well_known_spec",
     "PHASE": "op_spec",
     "PHASES": "op_spec",
     "HookPhase": "hook_spec",
@@ -106,7 +110,39 @@ _EXPORTS = {
     "TypeAdapter": "datatypes",
     "TypeRegistry": "datatypes",
     "TableSpec": "table_spec",
+    "BindingToken": "table_profile_bindings",
+    "LoweredBinding": "table_profile_bindings",
+    "lower_binding_tokens_for_ops": "table_profile_bindings",
+    "lower_default_bindings_for_op": "table_profile_bindings",
+    "lower_table_profile_bindings": "table_profile_bindings",
+    "TableProfileSpec": "table_profile_spec",
+    "BuiltinTableProfile": "table_profile_spec",
+    "BUILTIN_TABLE_PROFILE_DEFINITIONS": "table_profile_spec",
+    "BUILTIN_TABLE_PROFILE_KINDS": "table_profile_spec",
+    "TableProfileError": "table_profile_spec",
+    "TableProfileBindingFamily": "table_profile_spec",
+    "TableProfileRole": "table_profile_spec",
+    "PLAIN_TABLE_PROFILE": "table_profile_spec",
+    "CRUD_TABLE_PROFILE": "table_profile_spec",
+    "REALTIME_TABLE_PROFILE": "table_profile_spec",
+    "coerce_table_profile": "table_profile_spec",
+    "get_builtin_table_profile_definition": "table_profile_spec",
+    "get_table_profile": "table_profile_spec",
+    "iter_builtin_table_profile_definitions": "table_profile_spec",
+    "make_builtin_table_profile": "table_profile_spec",
+    "register_table_profile": "table_profile_spec",
     "TableRegistrySpec": "table_registry_spec",
+    "BINDING_STACK_PROJECTIONS": "transport_stack",
+    "BindingStackError": "transport_stack",
+    "BindingStackProjection": "transport_stack",
+    "binding_stack_maturity": "transport_stack",
+    "classify_binding_stack": "transport_stack",
+    "compose_h3_binding_projections": "transport_stack",
+    "require_binding_stack": "transport_stack",
+    "ExposureDecision": "exposure_policy",
+    "ExposurePolicyError": "exposure_policy",
+    "exposed_surfaces": "exposure_policy",
+    "resolve_exposure_policy": "exposure_policy",
 }
 
 __all__ = list(_EXPORTS)

tigrbl_core/_spec/app_spec.py

@@ -2,10 +2,12 @@
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Callable, Optional, Sequence
+import warnings
 
 from .._spec.engine_spec import EngineCfg, EngineSpec
 from .._spec.monotone import as_tuple, merge_mro_sequence_attr
 from .._spec.response_spec import ResponseSpec
+from .._spec.well_known_spec import WellKnownResourceSpec
 from .serde import SerdeMixin
 
 
@@ -45,12 +47,15 @@ def normalize_app_spec(spec: "AppSpec") -> "AppSpec":
         title=str(spec.title or "Tigrbl"),
         description=spec.description,
         version=str(spec.version or "0.1.0"),
-        execution_backend=str(getattr(spec, "execution_backend", None) or "auto"),
+        execution_backend=normalize_execution_backend(
+            getattr(spec, "execution_backend", None),
+        ),
         engine=spec.engine,
         engine_name=spec.engine_name,
         engines=_seqify(spec.engines),
         routers=routers,
         ops=ops,
+        well_known=_seqify(spec.well_known),
         tables=tables,
         schemas=_seqify(spec.schemas),
         hooks=_seqify(spec.hooks),
@@ -64,6 +69,23 @@ def normalize_app_spec(spec: "AppSpec") -> "AppSpec":
     )
 
 
+def normalize_execution_backend(value: Any) -> str:
+    lowered = str(value or "auto").strip().lower()
+    if not lowered:
+        return "auto"
+    if lowered == "rust":
+        warnings.warn(
+            "AppSpec.execution_backend='rust' is deprecated; "
+            "Tigrbl runtime execution is Python-only.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return "python"
+    if lowered in {"auto", "python"}:
+        return lowered
+    raise ValueError(f"unsupported execution backend: {value!r}")
+
+
 @dataclass(eq=False)
 class AppSpec(SerdeMixin):
     """
@@ -83,6 +105,7 @@ class AppSpec(SerdeMixin):
 
     # NEW: orchestration/topology knobs
     ops: Sequence[Any] = field(default_factory=tuple)  # op descriptors or specs
+    well_known: Sequence[WellKnownResourceSpec] = field(default_factory=tuple)
     tables: Sequence[Any] = field(default_factory=tuple)  # table refs owned by app
     schemas: Sequence[Any] = field(default_factory=tuple)  # schema classes/defs
     hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
@@ -103,9 +126,11 @@ class AppSpec(SerdeMixin):
     lifespan: Optional[Callable[..., Any]] = None
 
     def __post_init__(self) -> None:
+        self.execution_backend = normalize_execution_backend(self.execution_backend)
         self.engines = _seqify(self.engines)
         self.routers = _seqify(self.routers)
         self.ops = _seqify(self.ops)
+        self.well_known = _seqify(self.well_known)
         self.tables = _seqify(self.tables)
         self.schemas = _seqify(self.schemas)
         self.hooks = _seqify(self.hooks)
@@ -113,6 +138,14 @@ class AppSpec(SerdeMixin):
         self.deps = _seqify(self.deps)
         self.middlewares = _seqify(self.middlewares)
 
+        for resource in self.well_known:
+            if isinstance(resource, str):
+                raise TypeError("AppSpec.well_known entries must be nested specs, not strings.")
+            if not isinstance(resource, WellKnownResourceSpec):
+                raise TypeError(
+                    "AppSpec.well_known entries must be WellKnownResourceSpec; "
+                    f"got {type(resource).__name__}."
+                )
         validate_engine_inventory(self.engines)
         validate_engine_name_binding(
             self.engine_name,
@@ -172,6 +205,8 @@ class AppSpec(SerdeMixin):
 
     @classmethod
     def from_dict(cls, payload: dict[str, Any]) -> "AppSpec":
+        if "routes" in payload:
+            raise ValueError("AppSpec does not accept 'routes'; use path-owned specs.")
         return super().from_dict(payload)
 
     @classmethod
@@ -255,6 +290,7 @@ class AppSpec(SerdeMixin):
                 or ()
             ),
             ops=tuple(merge_seq_attr(app, "OPS") or ()),
+            well_known=tuple(merge_seq_attr(app, "WELL_KNOWN") or ()),
             tables=tuple(merge_seq_attr(app, "TABLES") or ()),
             schemas=tuple(merge_seq_attr(app, "SCHEMAS") or ()),
             hooks=tuple(merge_seq_attr(app, "HOOKS") or ()),
@@ -277,6 +313,7 @@ class AppSpec(SerdeMixin):
                 engines=tuple(spec.engines or ()),
                 routers=tuple(spec.routers or ()),
                 ops=tuple(spec.ops or ()),
+                well_known=tuple(spec.well_known or ()),
                 tables=tuple(spec.tables or ()),
                 schemas=tuple(spec.schemas or ()),
                 hooks=tuple(spec.hooks or ()),

tigrbl_core/_spec/binding_spec.py

@@ -28,6 +28,7 @@ Framing = Literal[
     "binary",
     "bytes",
     "webtransport",
+    "multipart/form-data",
 ]
 BindingProfile = Literal[
     "rest",
@@ -52,16 +53,16 @@ WebTransportLane = Literal[
 ]
 
 APP_LEVEL_FRAMING_SUPPORT: dict[str, tuple[str, ...]] = {
-    "http.rest": ("json",),
-    "https.rest": ("json",),
+    "http.rest": ("json", "multipart/form-data"),
+    "https.rest": ("json", "multipart/form-data"),
     "http.jsonrpc": ("jsonrpc",),
     "https.jsonrpc": ("jsonrpc",),
     "http.stream": ("stream", "bytes", "binary", "text", "json", "ndjson"),
     "https.stream": ("stream", "bytes", "binary", "text", "json", "ndjson"),
     "http.sse": ("sse",),
     "https.sse": ("sse",),
-    "ws": ("text", "bytes", "binary", "json", "jsonrpc"),
-    "wss": ("text", "bytes", "binary", "json", "jsonrpc"),
+    "ws": ("text", "bytes", "binary", "json", "jsonrpc", "ndjson"),
+    "wss": ("text", "bytes", "binary", "json", "jsonrpc", "ndjson"),
     "webtransport": ("webtransport",),
 }
 
@@ -70,8 +71,8 @@ BINDING_PROFILE_EXCHANGE_SUPPORT: dict[str, tuple[str, ...]] = {
     "https.rest": ("request_response",),
     "http.jsonrpc": ("request_response",),
     "https.jsonrpc": ("request_response",),
-    "http.stream": ("server_stream",),
-    "https.stream": ("server_stream",),
+    "http.stream": ("server_stream", "client_stream"),
+    "https.stream": ("server_stream", "client_stream"),
     "http.sse": ("server_stream",),
     "https.sse": ("server_stream",),
     "ws": ("bidirectional_stream",),
@@ -154,17 +155,16 @@ def validate_app_framing_for_binding(
     allowed = APP_LEVEL_FRAMING_SUPPORT.get(binding_kind)
     if allowed is None:
         raise ValueError(f"unsupported binding kind {binding_kind!r}")
-    if selected == "ndjson" and binding_kind in {"ws", "wss"}:
-        raise ValueError("WebSocket ndjson framing is unsupported and must fail closed")
     if selected not in allowed:
         raise ValueError(
             f"unsupported app-level framing {selected!r} for binding {binding_kind!r}"
         )
-    if selected == "jsonrpc" and binding_kind in {"ws", "wss"}:
+    if selected in {"jsonrpc", "ndjson"} and binding_kind in {"ws", "wss"}:
         lowered = tuple(str(item).lower() for item in subprotocols)
-        if "jsonrpc" not in lowered:
+        if selected not in lowered:
             raise ValueError(
-                "WebSocket jsonrpc framing requires subprotocols to include 'jsonrpc'."
+                f"WebSocket {selected} framing requires subprotocols to include "
+                f"'{selected}'."
             )
     if selected == "ndjson" and "jsonrpc" in binding_kind:
         raise ValueError("ndjson is not a JSON-RPC framing substitute")
@@ -583,6 +583,23 @@ def project_binding_runtime_metadata(binding: TransportBindingSpec) -> dict[str,
     if isinstance(binding, WebTransportBindingSpec):
         metadata["lane"] = binding.lane or webtransport_lane_for_profile(binding.profile)
         metadata["inner_framing"] = inner_framing
+        if metadata["lane"] == "bidi_stream":
+            metadata["direction"] = "bidirectional"
+        elif metadata["lane"] == "unidi_client_stream":
+            metadata["stream_initiator"] = "client"
+            metadata["direction"] = "client_to_server"
+        elif metadata["lane"] == "unidi_server_stream":
+            metadata["stream_initiator"] = "server"
+            metadata["direction"] = "server_to_client"
+    elif family == "stream" and proto in {"http.stream", "https.stream"}:
+        if exchange == "client_stream":
+            metadata["carrier_kind"] = "http_request_body"
+            metadata["stream_initiator"] = "client"
+            metadata["direction"] = "client_to_server"
+        elif exchange == "server_stream":
+            metadata["carrier_kind"] = "http_response_body"
+            metadata["stream_initiator"] = "server"
+            metadata["direction"] = "server_to_client"
     return metadata
 
 

tigrbl_core/_spec/exceptions.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+class InvalidHookPhaseError(ValueError):
+    """Raised when a hook phase is not one of the supported declarative phases."""
+
+    def __init__(self, *, phase: str, allowed_phases: Iterable[str]):
+        self.phase = phase
+        self.allowed_phases = tuple(allowed_phases)
+        options = ", ".join(self.allowed_phases)
+        super().__init__(f"Invalid hook phase '{phase}'. Valid phases are: {options}.")
+
+
+__all__ = ["InvalidHookPhaseError"]

tigrbl_core/_spec/exposure_policy.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .binding_spec import canonical_binding_kind
+
+
+DOCS_SURFACES = frozenset({"openapi", "openrpc"})
+RUNTIME_SURFACES = frozenset({"http", "jsonrpc", "stream", "sse", "websocket", "webtransport"})
+SUPPORTED_BINDING_KINDS = frozenset(
+    {
+        "http.rest",
+        "http.jsonrpc",
+        "http.stream",
+        "http.sse",
+        "ws",
+        "webtransport",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ExposureDecision:
+    docs: bool
+    runtime: bool
+    docs_source: str
+    runtime_source: str
+
+
+class ExposurePolicyError(ValueError):
+    pass
+
+
+def resolve_exposure_policy(
+    *,
+    docs_exposure: str = "default",
+    runtime_exposure: str = "none",
+    binding: Any | None = None,
+) -> ExposureDecision:
+    docs = _enabled(docs_exposure, default=True)
+    runtime = _enabled(runtime_exposure, default=False)
+    if runtime:
+        if binding is None:
+            raise ExposurePolicyError("runtime exposure requires declared transport binding")
+        _require_supported_binding(binding)
+    if docs and binding is not None:
+        _require_supported_binding(binding)
+    return ExposureDecision(
+        docs=docs,
+        runtime=runtime,
+        docs_source=str(docs_exposure),
+        runtime_source=str(runtime_exposure),
+    )
+
+
+def exposed_surfaces(decision: ExposureDecision, binding: Any | None = None) -> tuple[str, ...]:
+    surfaces: list[str] = []
+    if decision.docs:
+        surfaces.extend(("openapi", "openrpc"))
+    if decision.runtime:
+        if binding is None:
+            raise ExposurePolicyError("runtime exposure requires declared transport binding")
+        surfaces.append(_runtime_surface(binding))
+    return tuple(surfaces)
+
+
+def _enabled(value: str, *, default: bool) -> bool:
+    token = str(value or "default").strip().lower()
+    if token == "default":
+        return default
+    if token in {"enabled", "on", "true"}:
+        return True
+    if token in {"disabled", "none", "off", "false"}:
+        return False
+    raise ExposurePolicyError(f"unsupported exposure value: {value!r}")
+
+
+def _require_supported_binding(binding: Any) -> str:
+    kind = _binding_kind(binding)
+    if kind not in SUPPORTED_BINDING_KINDS:
+        raise ExposurePolicyError(f"unsupported transport binding: {kind}")
+    return kind
+
+
+def _runtime_surface(binding: Any) -> str:
+    kind = _require_supported_binding(binding)
+    return {
+        "http.rest": "http",
+        "http.jsonrpc": "jsonrpc",
+        "http.stream": "stream",
+        "http.sse": "sse",
+        "ws": "websocket",
+        "webtransport": "webtransport",
+    }[kind]
+
+
+def _binding_kind(binding: Any) -> str:
+    if isinstance(binding, Mapping):
+        return str(binding.get("kind") or binding.get("proto") or "")
+    return canonical_binding_kind(binding)
+
+
+__all__ = [
+    "DOCS_SURFACES",
+    "RUNTIME_SURFACES",
+    "ExposureDecision",
+    "ExposurePolicyError",
+    "exposed_surfaces",
+    "resolve_exposure_policy",
+]

tigrbl_core/_spec/hook_types.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any, Awaitable, Callable, Tuple
 
-from tigrbl_typing.phases import normalize_phase
+from tigrbl_typing.phases import canonicalize_phase_input
 
 
 class HookPhase(str, Enum):
@@ -30,7 +30,7 @@ class HookPhase(str, Enum):
 
     @classmethod
     def _missing_(cls, value: object):
-        normalized = normalize_phase(str(value)) if value is not None else None
+        normalized = canonicalize_phase_input(str(value)) if value is not None else None
         if normalized != value:
             return cls(normalized)
         return None

tigrbl_core/_spec/op_spec.py

@@ -206,6 +206,15 @@ def _as_specs(value: Any, table: type) -> List["OpSpec"]:
 
 
 def _generate_canonical(table: type) -> List["OpSpec"]:
+    profile = getattr(table, "TABLE_PROFILE", None)
+    if profile is not None:
+        try:
+            from tigrbl_core._spec.table_profile_spec import coerce_table_profile
+
+            return list(coerce_table_profile(profile).bind_table(table).ops)
+        except Exception:
+            raise
+
     from tigrbl_core.op.canonical import should_wire_canonical
 
     specs: List[OpSpec] = []

tigrbl_core/_spec/path_spec.py

@@ -15,6 +15,7 @@ from .binding_spec import (
 from .op_spec import OpSpec
 from .serde import SerdeMixin
 from .table_spec import TableSpec
+from .well_known_spec import WellKnownResourceSpec
 
 PathKind = Literal[
     "resource",
@@ -31,6 +32,7 @@ PathKind = Literal[
     "docs-uix",
     "static",
     "mount",
+    "well-known",
 ]
 
 
@@ -48,6 +50,7 @@ class PathSpec(SerdeMixin):
     docs_uix: Any | None = None
     static: Any | None = None
     mount: Any | None = None
+    well_known: WellKnownResourceSpec | None = None
 
     def __post_init__(self) -> None:
         if not isinstance(self.path, str) or not self.path.startswith("/"):
@@ -67,7 +70,13 @@ class PathSpec(SerdeMixin):
         if "routes" in payload:
             raise ValueError("PathSpec does not accept 'routes'; use path-owned specs.")
         if "engine" in payload or "engine_name" in payload:
-            raise ValueError("PathSpec does not own engines; bind engines at app, router, table, or op scope.")
+            rejected = ", ".join(
+                field for field in ("engine", "engine_name") if field in payload
+            )
+            raise ValueError(
+                "PathSpec does not own engines; rejected "
+                f"{rejected}; bind engines at app, router, table, or op scope."
+            )
         return super().from_dict(payload)
 
     def binding_path(self, binding: TransportBindingSpec) -> str:
@@ -134,6 +143,7 @@ class PathSpec(SerdeMixin):
             "docs-uix",
             "static",
             "mount",
+            "well-known",
         }
         if self.kind not in valid:
             raise ValueError(f"PathSpec.kind must be a canonical path kind; got {self.kind!r}.")
@@ -144,6 +154,7 @@ class PathSpec(SerdeMixin):
             "docs-uix": ("docs_uix", self.docs_uix),
             "static": ("static", self.static),
             "mount": ("mount", self.mount),
+            "well-known": ("well_known", self.well_known),
         }
         if self.kind in payload_fields:
             field_name, value = payload_fields[self.kind]
@@ -155,11 +166,16 @@ class PathSpec(SerdeMixin):
                 ("docs_uix", self.docs_uix),
                 ("static", self.static),
                 ("mount", self.mount),
+                ("well_known", self.well_known),
             ):
                 if value is not None:
                     raise ValueError(
                         f"PathSpec.{field_name} is only valid on its matching canonical path kind."
                     )
+        if self.well_known is not None and not isinstance(
+            self.well_known, WellKnownResourceSpec
+        ):
+            raise TypeError("PathSpec.well_known must be WellKnownResourceSpec.")
 
     def _validate_tables(self) -> None:
         for table in self.tables:

tigrbl_core/_spec/router_spec.py

@@ -10,6 +10,7 @@ from .._spec.path_spec import PathSpec
 from .._spec.response_spec import ResponseSpec
 from .._spec.schema_spec import SchemaSpec
 from .._spec.table_spec import TableSpec
+from .._spec.well_known_spec import WellKnownResourceSpec
 from .serde import SerdeMixin
 
 
@@ -29,10 +30,13 @@ class RouterSpec(SerdeMixin):
     deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
     middlewares: Sequence[Any] = field(default_factory=tuple)
     response: Optional[ResponseSpec] = None
+    well_known: Sequence[WellKnownResourceSpec] = field(default_factory=tuple)
     paths: Sequence[PathSpec] = field(default_factory=tuple)
     tables: Sequence[Any] = field(default_factory=tuple)
 
     def __post_init__(self) -> None:
+        self.well_known = tuple(self.well_known or ())
+        self._validate_nested_specs("well_known", self.well_known, (WellKnownResourceSpec,))
         self._validate_nested_specs("paths", self.paths, (PathSpec,))
         self._validate_nested_specs("tables", self.tables, (TableSpec,))
         self._validate_nested_specs("ops", self.ops, (OpSpec,))
@@ -44,6 +48,8 @@ class RouterSpec(SerdeMixin):
             raise ValueError(
                 "RouterSpec does not accept 'models'; use 'tables' with nested TableSpec values."
             )
+        if "routes" in payload:
+            raise ValueError("RouterSpec does not accept 'routes'; use path-owned specs.")
         return super().from_dict(payload)
 
     @staticmethod
@@ -102,6 +108,7 @@ class RouterSpec(SerdeMixin):
             engine_name=engine_name,
             tags=merge_seq_attr(router, "TAGS", include_inherited=True),
             ops=merge_seq_attr(router, "OPS", include_inherited=True),
+            well_known=merge_seq_attr(router, "WELL_KNOWN", include_inherited=True),
             paths=merge_seq_attr(router, "PATHS", include_inherited=True),
             tables=merge_seq_attr(router, "TABLES", include_inherited=True),
             schemas=merge_seq_attr(router, "SCHEMAS", include_inherited=True),