tigrbl-runtime 0.4.2.dev4__tar.gz → 0.4.3.dev4__tar.gz

{tigrbl_runtime-0.4.2.dev4 → tigrbl_runtime-0.4.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-runtime
-Version: 0.4.2.dev4
+Version: 0.4.3.dev4
 Summary: Runtime pipeline helpers and execution bridge surfaces for Tigrbl ASGI applications, transports, and operation dispatch.
 License: Apache License
                                     Version 2.0, January 2004
@@ -311,12 +311,21 @@ pip install tigrbl-runtime
 `tigrbl-runtime` owns the `foundational framework package` boundary. It should be installed when you need this package's focused responsibility without assuming every other Tigrbl workspace package is present.
 
 Implementation orientation:
-- `tigrbl_runtime`: callbacks, channel/, config/, executors/, handle, protocol/, runtime/, rust/, transactions, webhooks
+- `tigrbl_runtime`: callbacks, channel/, config/, executors/, handle, protocol/, runtime/, transactions, webhooks
+- `tigrbl_runtime/rust/`: deprecated compatibility shims only; Rust execution is unavailable.
+
+Runtime authoring BCP:
+- Do use this package for runtime-owned routing, request execution, transport-unit execution, framing atoms, transport channels, transaction helpers, and kernel integration.
+- Do keep handler invocation, transaction progression, error handling, and transport emission aligned with compiled plans.
+- Do not make application route handlers, FastAPI/Starlette objects, direct SQLAlchemy session calls, or ad-hoc engine construction the runtime contract.
+- Do not bypass kernel plans or lifecycle phases when adding REST, JSON-RPC, stream, SSE, WebSocket, or WebTransport behavior.
+- Avoid hiding behavior in transport wrappers that diagnostics and compiled plans cannot inspect.
 
 ## Public API and Import Surface
 
 - Import roots: `tigrbl_runtime`.
-- Public symbols: `ExecutionBackend`, `RustBackendConfig`, `RustBindingsUnavailableError`.
+- Public symbols: `Runtime`, `RuntimeBase`.
+- Rust-named symbols live only under `tigrbl_runtime.rust` as deprecated compatibility shims and must not be used for execution.
 - Workspace dependencies: [`tigrbl-typing`](https://pypi.org/project/tigrbl-typing/), [`tigrbl-kernel`](https://pypi.org/project/tigrbl-kernel/), [`tigrbl-atoms`](https://pypi.org/project/tigrbl-atoms/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), [`tigrbl-core`](https://pypi.org/project/tigrbl-core/).
 - External runtime dependencies: `numba>=0.61.2`.
 
@@ -344,9 +353,9 @@ print(module.__name__)
 ### Import a public symbol
 
 ```python
-from tigrbl_runtime import ExecutionBackend
+from tigrbl_runtime import Runtime
 
-print(ExecutionBackend)
+print(Runtime)
 ```
 
 ### Use with the facade when building applications

{tigrbl_runtime-0.4.2.dev4 → tigrbl_runtime-0.4.3.dev4}/README.md

@@ -71,12 +71,21 @@ pip install tigrbl-runtime
 `tigrbl-runtime` owns the `foundational framework package` boundary. It should be installed when you need this package's focused responsibility without assuming every other Tigrbl workspace package is present.
 
 Implementation orientation:
-- `tigrbl_runtime`: callbacks, channel/, config/, executors/, handle, protocol/, runtime/, rust/, transactions, webhooks
+- `tigrbl_runtime`: callbacks, channel/, config/, executors/, handle, protocol/, runtime/, transactions, webhooks
+- `tigrbl_runtime/rust/`: deprecated compatibility shims only; Rust execution is unavailable.
+
+Runtime authoring BCP:
+- Do use this package for runtime-owned routing, request execution, transport-unit execution, framing atoms, transport channels, transaction helpers, and kernel integration.
+- Do keep handler invocation, transaction progression, error handling, and transport emission aligned with compiled plans.
+- Do not make application route handlers, FastAPI/Starlette objects, direct SQLAlchemy session calls, or ad-hoc engine construction the runtime contract.
+- Do not bypass kernel plans or lifecycle phases when adding REST, JSON-RPC, stream, SSE, WebSocket, or WebTransport behavior.
+- Avoid hiding behavior in transport wrappers that diagnostics and compiled plans cannot inspect.
 
 ## Public API and Import Surface
 
 - Import roots: `tigrbl_runtime`.
-- Public symbols: `ExecutionBackend`, `RustBackendConfig`, `RustBindingsUnavailableError`.
+- Public symbols: `Runtime`, `RuntimeBase`.
+- Rust-named symbols live only under `tigrbl_runtime.rust` as deprecated compatibility shims and must not be used for execution.
 - Workspace dependencies: [`tigrbl-typing`](https://pypi.org/project/tigrbl-typing/), [`tigrbl-kernel`](https://pypi.org/project/tigrbl-kernel/), [`tigrbl-atoms`](https://pypi.org/project/tigrbl-atoms/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), [`tigrbl-core`](https://pypi.org/project/tigrbl-core/).
 - External runtime dependencies: `numba>=0.61.2`.
 
@@ -104,9 +113,9 @@ print(module.__name__)
 ### Import a public symbol
 
 ```python
-from tigrbl_runtime import ExecutionBackend
+from tigrbl_runtime import Runtime
 
-print(ExecutionBackend)
+print(Runtime)
 ```
 
 ### Use with the facade when building applications

{tigrbl_runtime-0.4.2.dev4 → tigrbl_runtime-0.4.3.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-runtime"
-version = "0.4.2.dev4"
+version = "0.4.3.dev4"
 description = "Runtime pipeline helpers and execution bridge surfaces for Tigrbl ASGI applications, transports, and operation dispatch."
 readme = "README.md"
 license = { file = "LICENSE" }

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/__init__.py

@@ -0,0 +1,25 @@
+"""Public exports for ``tigrbl_runtime`` with lazy loading."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_LAZY_EXPORTS = {
+    "Runtime": "runtime",
+    "RuntimeBase": "runtime",
+}
+
+__all__ = [
+    *_LAZY_EXPORTS,
+]
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(name)
+    module = import_module(f"{__name__}.{module_name}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

tigrbl_runtime-0.4.2.dev4/tigrbl_runtime/webhooks.py → tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/callbacks.py

@@ -7,7 +7,7 @@ from collections.abc import Callable, Mapping
 from typing import Any
 
 
-def compile_webhook_delivery_plan(
+def compile_callback_delivery_plan(
     *,
     event: str,
     endpoint: str,
@@ -19,11 +19,11 @@ def compile_webhook_delivery_plan(
         "endpoint": endpoint,
         "signing": {"algorithm": "hmac-sha256", "secret_ref": signing_secret_ref},
         "retry": dict(retry or {"max_attempts": 1}),
-        "completion_subevent": "webhook.delivery.emit_complete",
+        "completion_subevent": "callback.delivery.emit_complete",
     }
 
 
-def build_webhook_payload(
+def build_callback_payload(
     *, event: str, data: Mapping[str, Any], idempotency_key: str
 ) -> dict[str, object]:
     return {
@@ -33,13 +33,13 @@ def build_webhook_payload(
     }
 
 
-def sign_webhook_payload(payload: Mapping[str, Any], *, secret: str) -> dict[str, object]:
+def sign_callback_payload(payload: Mapping[str, Any], *, secret: str) -> dict[str, object]:
     canonical = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
     digest = hmac.new(secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
     return {"payload": dict(payload), "signature": f"sha256={digest}"}
 
 
-def deliver_webhook(
+def deliver_callback(
     payload: Mapping[str, Any],
     *,
     send: Callable[[Mapping[str, Any]], Mapping[str, Any]],
@@ -54,7 +54,7 @@ def deliver_webhook(
     for attempt in range(1, max_attempts + 1):
         attempts = attempt
         if trace and attempt == 1:
-            trace("webhook.delivery.emit")
+            trace("callback.delivery.emit")
         try:
             response = send(payload)
         except Exception as exc:
@@ -65,7 +65,7 @@ def deliver_webhook(
                 "attempts": attempts,
                 "completed": False,
                 "error_ctx": {
-                    "subevent": "webhook.delivery.emit",
+                    "subevent": "callback.delivery.emit",
                     "message": str(exc),
                 },
             }
@@ -73,7 +73,7 @@ def deliver_webhook(
         status_code = int(response.get("status_code", 0))
         if 200 <= status_code < 300:
             if trace:
-                trace("webhook.delivery.emit_complete")
+                trace("callback.delivery.emit_complete")
             return {
                 "status": "delivered",
                 "attempts": attempts,
@@ -109,8 +109,8 @@ def _is_transient(status_code: int) -> bool:
 
 
 __all__ = [
-    "build_webhook_payload",
-    "compile_webhook_delivery_plan",
-    "deliver_webhook",
-    "sign_webhook_payload",
+    "build_callback_payload",
+    "compile_callback_delivery_plan",
+    "deliver_callback",
+    "sign_callback_payload",
 ]

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/channel/_asgi_completion.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tigrbl_atoms.atoms.transport.asgi_channel import (
+    complete_channel_state as _complete_channel_state,
+)
+from tigrbl_typing.channel import OpChannel
+
+from ._asgi_scope import build_asgi_channel
+from ._asgi_send import send_transport_via_channel
+from .websocket import RuntimeWebSocket
+
+
+def channel_senders():
+    from tigrbl_atoms.atoms.egress.asgi_send import _send_json
+
+    return _send_json, send_transport_via_channel
+
+
+async def complete_channel(env: Any, ctx: Any) -> None:
+    channel = ctx.get("channel")
+    if channel is None:
+        channel = build_asgi_channel(env)
+        ctx["channel"] = channel
+    if isinstance(getattr(channel, "state", None), dict):
+        _complete_channel_state(channel.state)
+    ctx["transport_completed"] = True
+    ctx["current_phase"] = "POST_EMIT"
+
+
+def websocket_adapter(channel: OpChannel) -> RuntimeWebSocket:
+    return RuntimeWebSocket(channel)

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/channel/_asgi_context.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+from tigrbl_kernel.channel_taxonomy import normalize_exchange
+from tigrbl_typing.channel import OpChannel
+
+from ._asgi_jsonrpc import _resolve_jsonrpc_endpoint
+from ._asgi_receive import _receive_session_message
+from ._asgi_scope import _scheme, build_asgi_channel
+from ._asgi_webtransport import (
+    _receive_webtransport_session_messages,
+    _webtransport_scope_state,
+)
+
+
+async def prepare_channel_context(env: Any, ctx: Any) -> OpChannel:
+    temp = ctx.get("temp")
+    if not isinstance(temp, dict):
+        ctx["temp"] = {}
+        temp = ctx["temp"]
+
+    route = temp.setdefault("route", {})
+    exchange = str(
+        route.get("exchange")
+        or getattr(ctx, "tigrbl_exchange", None)
+        or "request_response"
+    )
+    exchange = normalize_exchange(exchange)
+    protocol = str(route.get("protocol") or _scheme(getattr(env, "scope", {}) or {}))
+    framing = route.get("framing")
+    channel = build_asgi_channel(
+        env,
+        exchange=exchange,
+        protocol=protocol or None,
+        framing=str(framing) if isinstance(framing, str) else None,
+    )
+    ctx["channel"] = channel
+    ctx["path"] = channel.path
+    ctx["method"] = channel.method or channel.protocol.upper()
+
+    dispatch = temp.setdefault("dispatch", {})
+    if isinstance(dispatch, dict):
+        dispatch.setdefault("channel_protocol", channel.protocol)
+        dispatch.setdefault("channel_selector", channel.selector)
+        dispatch.setdefault("path_params", dict(channel.path_params))
+        endpoint = _resolve_jsonrpc_endpoint(ctx, channel)
+        if endpoint:
+            dispatch.setdefault("endpoint", endpoint)
+
+    scope = getattr(env, "scope", {}) or {}
+    scope_type = str(scope.get("type") or "http")
+    if scope_type == "webtransport":
+        await _receive_webtransport_session_messages(env, channel, ctx)
+        wt_state = _webtransport_scope_state(env)
+        trace = wt_state.get("trace")
+        if isinstance(trace, list):
+            ctx["webtransport_trace"] = trace
+            channel.state["webtransport_trace"] = trace
+        hook_trace = wt_state.get("hook_trace")
+        if isinstance(hook_trace, list):
+            ctx["webtransport_hook_trace"] = hook_trace
+            channel.state["webtransport_hook_trace"] = hook_trace
+        route.setdefault("protocol", dispatch.get("binding_protocol"))
+        route.setdefault("selector", channel.path)
+        route.setdefault("path_params", dict(channel.path_params))
+        route.setdefault("endpoint", dispatch.get("endpoint"))
+    elif scope_type == "websocket":
+        await _receive_session_message(
+            env,
+            channel,
+            ctx,
+            connect_type="websocket.connect",
+            receive_type="websocket.receive",
+            disconnect_type="websocket.disconnect",
+            eager_payload_after_connect=False,
+        )
+        message = ctx.get("channel_message")
+        if isinstance(message, Mapping) and message.get("text") is not None:
+            try:
+                parsed = json.loads(str(message.get("text")))
+            except Exception:
+                parsed = None
+            if isinstance(parsed, Mapping) and parsed.get("jsonrpc") == "2.0":
+                dispatch["binding_protocol"] = (
+                    "wss.jsonrpc" if channel.protocol == "wss" else "ws.jsonrpc"
+                )
+                dispatch["rpc"] = dict(parsed)
+                dispatch["rpc_method"] = parsed.get("method")
+        route.setdefault("protocol", dispatch.get("binding_protocol"))
+        route.setdefault("selector", channel.path)
+        route.setdefault("path_params", dict(channel.path_params))
+        route.setdefault("endpoint", dispatch.get("endpoint"))
+
+    return channel

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/channel/_asgi_jsonrpc.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from tigrbl_core.config.constants import __JSONRPC_DEFAULT_ENDPOINT_MAPPINGS__
+from tigrbl_typing.channel import OpChannel
+
+
+def _normalize_path(path: str) -> str:
+    return path.rstrip("/") or "/"
+
+
+def _resolve_jsonrpc_endpoint(ctx: Any, channel: OpChannel) -> str | None:
+    if channel.kind != "http" or str(channel.method or "").upper() != "POST":
+        return None
+
+    path = _normalize_path(channel.path)
+    route = {}
+    temp = ctx.get("temp")
+    if isinstance(temp, dict):
+        route = temp.setdefault("route", {})
+    if isinstance(route, Mapping):
+        endpoint = route.get("endpoint")
+        if isinstance(endpoint, str) and endpoint:
+            return endpoint
+
+    for owner_key in ("router", "app"):
+        owner = ctx.get(owner_key)
+        mounts = getattr(owner, "_jsonrpc_endpoint_mounts", None)
+        if isinstance(mounts, Mapping):
+            endpoint = mounts.get(path) or mounts.get(channel.path)
+            if isinstance(endpoint, str) and endpoint:
+                return endpoint
+
+    for endpoint, mapped_path in __JSONRPC_DEFAULT_ENDPOINT_MAPPINGS__.items():
+        if path == _normalize_path(mapped_path):
+            return endpoint
+    return None

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/channel/_asgi_receive.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+from tigrbl_typing.channel import OpChannel
+
+
+async def _receive_session_message(
+    env: Any,
+    channel: OpChannel,
+    ctx: Any,
+    *,
+    connect_type: str,
+    receive_type: str | tuple[str, ...],
+    disconnect_type: str,
+    eager_payload_after_connect: bool = True,
+) -> None:
+    receive = getattr(env, "receive", None)
+    if not callable(receive):
+        return
+    message = await receive()
+    state = channel.state
+    state["last_event"] = message
+    if message.get("type") == connect_type:
+        state["connected"] = True
+        if message.get("session_id") is not None:
+            state["session_id"] = message.get("session_id")
+        if not eager_payload_after_connect:
+            ctx["channel_message"] = message
+            return
+        message = await receive()
+        state["last_event"] = message
+    receive_types = (receive_type,) if isinstance(receive_type, str) else receive_type
+    if message.get("type") in receive_types:
+        queue = state.get("receive_queue")
+        if isinstance(queue, deque):
+            queue.append(message)
+        else:
+            next_queue = deque()
+            if isinstance(queue, list):
+                next_queue.extend(queue)
+            next_queue.append(message)
+            state["receive_queue"] = next_queue
+        payload = message.get("bytes")
+        if payload is None:
+            payload = message.get("data")
+        if payload is None and message.get("text") is not None:
+            payload = str(message.get("text")).encode("utf-8")
+        ctx["body"] = payload
+        ctx["channel_message"] = message
+        for key in (
+            "session_id",
+            "stream_id",
+            "stream_direction",
+            "datagram_id",
+            "framing",
+        ):
+            if message.get(key) is not None:
+                state[key] = message.get(key)
+    elif message.get("type") == disconnect_type:
+        state["disconnected"] = True
+        ctx["channel_message"] = message

tigrbl_runtime-0.4.3.dev4/tigrbl_runtime/channel/_asgi_scope.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+from urllib.parse import parse_qs
+
+from tigrbl_kernel.channel_taxonomy import (
+    channel_family as _channel_family,
+    channel_kind as _channel_kind,
+    channel_subevents as _subevents,
+    normalize_exchange,
+)
+from tigrbl_typing.channel import OpChannel
+
+
+def _headers(scope: Mapping[str, Any]) -> dict[str, str]:
+    pairs = scope.get("headers", ())
+    out: dict[str, str] = {}
+    for key, value in pairs or ():
+        try:
+            out[bytes(key).decode("latin-1").lower()] = bytes(value).decode("latin-1")
+        except Exception:
+            continue
+    return out
+
+
+def _query(scope: Mapping[str, Any]) -> dict[str, list[str]]:
+    raw = scope.get("query_string", b"")
+    if isinstance(raw, str):
+        raw = raw.encode("utf-8")
+    if not isinstance(raw, (bytes, bytearray)):
+        return {}
+    return {
+        key: [str(item) for item in values]
+        for key, values in parse_qs(
+            bytes(raw).decode("utf-8"), keep_blank_values=True
+        ).items()
+    }
+
+
+def _scheme(scope: Mapping[str, Any]) -> str:
+    return str(scope.get("scheme") or "").lower()
+
+
+def build_asgi_channel(
+    env: Any,
+    *,
+    exchange: str = "request_response",
+    protocol: str | None = None,
+    framing: str | None = None,
+) -> OpChannel:
+    exchange = normalize_exchange(exchange)
+    scope = getattr(env, "scope", {}) or {}
+    scope_type = str(scope.get("type") or "http")
+    path = str(scope.get("path") or "/")
+    method = scope.get("method")
+    protocol_name = protocol or _scheme(scope) or scope_type
+    selector = path
+    if scope_type == "http" and isinstance(method, str):
+        selector = f"{method.upper()} {path}"
+    return OpChannel(
+        kind=_channel_kind(scope_type, exchange),
+        family=_channel_family(scope_type, exchange),
+        exchange=exchange,
+        protocol=protocol_name,
+        path=path,
+        method=str(method).upper() if isinstance(method, str) else None,
+        selector=selector,
+        framing=framing,
+        subevents=_subevents(scope_type, exchange),
+        headers=_headers(scope),
+        query=_query(scope),
+        path_params=scope.get("path_params", {}) or {},
+        send=getattr(env, "send", None),
+        receive=getattr(env, "receive", None),
+    )