iii-sdk 0.11.3.dev1__tar.gz → 0.11.3.dev2__tar.gz

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.3.dev1
+Version: 0.11.3.dev2
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/sdk
 Project-URL: Repository, https://github.com/iii-hq/sdk

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.11.3.dev1"
+version = "0.11.3.dev2"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/src/iii/__init__.py

@@ -1,6 +1,7 @@
 """III SDK for Python."""
 
 from .channels import ChannelReader, ChannelWriter
+from .errors import IIIForbiddenError, IIIInvocationError, IIITimeoutError
 from .format_utils import extract_request_format, extract_response_format, python_type_to_format
 from .iii import TriggerAction, register_worker
 from .iii_constants import FunctionRef, InitOptions, ReconnectionConfig, TelemetryOptions
@@ -62,6 +63,10 @@ __all__ = [
     # Channels
     "ChannelReader",
     "ChannelWriter",
+    # Errors
+    "IIIForbiddenError",
+    "IIIInvocationError",
+    "IIITimeoutError",
     # Core
     "FunctionRef",
     "InitOptions",

iii_sdk-0.11.3.dev2/src/iii/errors.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class IIIInvocationError(Exception):
+    """Raised when an invocation dispatched by the SDK fails.
+
+    Subclass by code:
+      - ``IIIForbiddenError``  (``code == 'FORBIDDEN'``)
+      - ``IIITimeoutError``    (``code == 'TIMEOUT'``)
+
+    Catch the base to handle every rejection; catch a subclass to react to
+    a specific category. ``except Exception`` continues to work because
+    ``IIIInvocationError`` inherits from ``Exception``.
+
+    Attributes are read-only after construction. ``stacktrace`` is the
+    engine-side trace when the remote handler raised; it may include
+    internal file paths and should not be surfaced to end users. ``str(err)``
+    intentionally never includes the stacktrace.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        function_id: str | None = None,
+        stacktrace: str | None = None,
+        invocation_id: str | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.function_id = function_id
+        self.stacktrace = stacktrace
+        self.invocation_id = invocation_id
+
+
+class IIIForbiddenError(IIIInvocationError):
+    """Raised when RBAC denies an invocation. ``code == 'FORBIDDEN'``."""
+
+
+class IIITimeoutError(IIIInvocationError):
+    """Raised when an invocation exceeds its timeout. ``code == 'TIMEOUT'``."""
+
+
+def _wrap_wire_error(
+    error: Any,
+    *,
+    function_id: str | None,
+    invocation_id: str | None,
+) -> IIIInvocationError:
+    """Convert a wire ``ErrorBody``-shaped dict into a typed exception.
+
+    Dispatches to ``IIIForbiddenError`` / ``IIITimeoutError`` based on
+    ``error['code']``. Malformed shapes (non-dict, missing fields, non-string
+    values) fall back to ``IIIInvocationError(code='UNKNOWN', ...)`` so no
+    rejection path prints as a raw dict repr.
+    """
+    if isinstance(error, dict):
+        raw_code = error.get("code")
+        code = raw_code if isinstance(raw_code, str) else "UNKNOWN"
+
+        raw_message = error.get("message")
+        message = raw_message if isinstance(raw_message, str) else "<no message>"
+
+        raw_stacktrace = error.get("stacktrace")
+        stacktrace = raw_stacktrace if isinstance(raw_stacktrace, str) else None
+
+        cls: type[IIIInvocationError] = {
+            "FORBIDDEN": IIIForbiddenError,
+            "TIMEOUT": IIITimeoutError,
+        }.get(code, IIIInvocationError)
+
+        return cls(
+            code=code,
+            message=message,
+            function_id=function_id,
+            stacktrace=stacktrace,
+            invocation_id=invocation_id,
+        )
+
+    return IIIInvocationError(
+        code="UNKNOWN",
+        message=str(error),
+        function_id=function_id,
+        invocation_id=invocation_id,
+    )

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/src/iii/iii.py

@@ -9,6 +9,7 @@ import random
 import threading
 import traceback
 import uuid
+from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Any, Awaitable, Callable, Coroutine, TypeVar, cast
 
@@ -16,6 +17,7 @@ import websockets
 from websockets.asyncio.client import ClientConnection
 
 from .channels import ChannelReader, ChannelWriter
+from .errors import IIIInvocationError, IIITimeoutError, _wrap_wire_error
 from .format_utils import extract_request_format, extract_response_format
 from .iii_constants import (
     DEFAULT_RECONNECTION_CONFIG,
@@ -86,6 +88,18 @@ class _TraceContextError(Exception):
         self.traceparent = traceparent
 
 
+@dataclass(frozen=True)
+class _PendingInvocation:
+    """Pending invocation record kept on the SDK until the engine responds.
+
+    ``function_id`` is preserved so the timeout and error-wrapping paths
+    can name the target without plumbing it through every call site.
+    """
+
+    future: asyncio.Future[Any]
+    function_id: str
+
+
 class III:
     """WebSocket client for communication with the III Engine.
 
@@ -107,7 +121,7 @@ class III:
         self._ws: ClientConnection | None = None
         self._functions: dict[str, RemoteFunctionData] = {}
         self._services: dict[str, RegisterServiceMessage] = {}
-        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._pending: dict[str, _PendingInvocation] = {}
         self._triggers: dict[str, RegisterTriggerMessage] = {}
         self._trigger_types: dict[str, RemoteTriggerTypeData] = {}
         self._queue: list[dict[str, Any]] = []
@@ -224,9 +238,16 @@ class III:
                     pass
 
         # Reject all pending invocations
-        for invocation_id, future in list(self._pending.items()):
-            if not future.done():
-                future.set_exception(Exception("iii is shutting down"))
+        for invocation_id, pending in list(self._pending.items()):
+            if not pending.future.done():
+                pending.future.set_exception(
+                    IIIInvocationError(
+                        code="SHUTDOWN",
+                        message="iii is shutting down",
+                        function_id=pending.function_id,
+                        invocation_id=invocation_id,
+                    )
+                )
         self._pending.clear()
 
         if self._ws:
@@ -401,15 +422,21 @@ class III:
             log.debug(f"Worker registered with ID: {worker_id}")
 
     def _handle_result(self, invocation_id: str, result: Any, error: Any) -> None:
-        future = self._pending.pop(invocation_id, None)
-        if not future:
+        pending = self._pending.pop(invocation_id, None)
+        if not pending:
             log.debug(f"No pending invocation: {invocation_id}")
             return
 
         if error:
-            future.set_exception(Exception(str(error)))
+            pending.future.set_exception(
+                _wrap_wire_error(
+                    error,
+                    function_id=pending.function_id,
+                    invocation_id=invocation_id,
+                )
+            )
         else:
-            future.set_result(result)
+            pending.future.set_result(result)
 
     def _inject_traceparent(self) -> str | None:
         from opentelemetry import context as otel_context
@@ -972,7 +999,9 @@ class III:
             actions.
 
         Raises:
-            TimeoutError: If the invocation times out.
+            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
+            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
+            IIIInvocationError: For any other engine rejection.
 
         Examples:
             >>> result = iii.trigger({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -997,7 +1026,9 @@ class III:
             The result of the function invocation, or ``None`` for void calls.
 
         Raises:
-            TimeoutError: If the invocation times out.
+            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
+            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
+            IIIInvocationError: For any other engine rejection.
 
         Examples:
             >>> result = await iii.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -1035,7 +1066,9 @@ class III:
         invocation_id = str(uuid.uuid4())
         future: asyncio.Future[Any] = self._loop.create_future()
 
-        self._pending[invocation_id] = future
+        self._pending[invocation_id] = _PendingInvocation(
+            future=future, function_id=function_id
+        )
 
         enqueue_action: TriggerActionEnqueue | None = (
             action if isinstance(action, TriggerActionEnqueue) else None
@@ -1056,8 +1089,11 @@ class III:
             return await asyncio.wait_for(future, timeout=timeout_secs)
         except asyncio.TimeoutError:
             self._pending.pop(invocation_id, None)
-            raise TimeoutError(
-                f"Invocation of '{function_id}' timed out after {timeout_ms}ms"
+            raise IIITimeoutError(
+                code="TIMEOUT",
+                message=f"invocation timed out after {timeout_ms}ms",
+                function_id=function_id,
+                invocation_id=invocation_id,
             )
 
     def list_functions(self) -> list[FunctionInfo]:

iii_sdk-0.11.3.dev2/tests/test_errors.py

@@ -0,0 +1,168 @@
+"""Unit tests for the typed invocation error hierarchy. No engine required."""
+
+from __future__ import annotations
+
+import pytest
+
+from iii import IIIForbiddenError, IIIInvocationError, IIITimeoutError
+from iii.errors import _wrap_wire_error
+
+
+class TestIIIInvocationError:
+    def test_exposes_all_fields(self) -> None:
+        err = IIIInvocationError(
+            code="FORBIDDEN",
+            message="function 'engine::functions::list' not allowed",
+            function_id="engine::functions::list",
+            stacktrace="trace here",
+            invocation_id="inv-123",
+        )
+        assert isinstance(err, Exception)
+        assert isinstance(err, IIIInvocationError)
+        assert err.code == "FORBIDDEN"
+        assert err.message == "function 'engine::functions::list' not allowed"
+        assert err.function_id == "engine::functions::list"
+        assert err.stacktrace == "trace here"
+        assert err.invocation_id == "inv-123"
+
+    def test_str_is_code_colon_message(self) -> None:
+        err = IIIInvocationError(
+            code="FORBIDDEN",
+            message="function 'X' not allowed (add to rbac.expose_functions)",
+            function_id="X",
+        )
+        assert str(err) == "FORBIDDEN: function 'X' not allowed (add to rbac.expose_functions)"
+
+    def test_str_never_looks_like_raw_dict_repr(self) -> None:
+        """Guards against the original Node [object Object] equivalent."""
+        err = IIIInvocationError(code="FORBIDDEN", message="nope")
+        assert str(err) != "{'code': 'FORBIDDEN', 'message': 'nope'}"
+        assert str(err) != repr({"code": "FORBIDDEN", "message": "nope"})
+
+    def test_str_does_not_leak_stacktrace(self) -> None:
+        """Stacktrace is opt-in via .stacktrace attribute; str/repr must not include it."""
+        err = IIIInvocationError(
+            code="HANDLER",
+            message="boom",
+            stacktrace="/internal/path/secrets.py:line 42",
+        )
+        assert "/internal/path/secrets.py" not in str(err)
+        assert "/internal/path/secrets.py" not in repr(err)
+
+    def test_supports_optional_fields(self) -> None:
+        err = IIIInvocationError(code="TIMEOUT", message="gone")
+        assert err.function_id is None
+        assert err.stacktrace is None
+        assert err.invocation_id is None
+        assert str(err) == "TIMEOUT: gone"
+
+
+class TestSubclassHierarchy:
+    def test_forbidden_is_invocation_error(self) -> None:
+        err = IIIForbiddenError(code="FORBIDDEN", message="x")
+        assert isinstance(err, IIIInvocationError)
+        assert isinstance(err, IIIForbiddenError)
+        assert isinstance(err, Exception)
+
+    def test_timeout_is_invocation_error(self) -> None:
+        err = IIITimeoutError(code="TIMEOUT", message="x")
+        assert isinstance(err, IIIInvocationError)
+        assert isinstance(err, IIITimeoutError)
+        assert isinstance(err, Exception)
+
+    def test_except_ordering_catches_subclass_first(self) -> None:
+        """`except IIIForbiddenError` fires before `except IIIInvocationError`."""
+        caught: str | None = None
+        try:
+            raise IIIForbiddenError(code="FORBIDDEN", message="x")
+        except IIIForbiddenError:
+            caught = "forbidden"
+        except IIIInvocationError:
+            caught = "base"
+        assert caught == "forbidden"
+
+    def test_base_catches_every_subclass(self) -> None:
+        for err in (
+            IIIForbiddenError(code="FORBIDDEN", message="x"),
+            IIITimeoutError(code="TIMEOUT", message="x"),
+            IIIInvocationError(code="UNKNOWN", message="x"),
+        ):
+            try:
+                raise err
+            except IIIInvocationError as got:
+                assert got.code in {"FORBIDDEN", "TIMEOUT", "UNKNOWN"}
+
+    def test_except_exception_still_works(self) -> None:
+        """Migration guarantee: existing `except Exception:` handlers still catch."""
+        try:
+            raise IIIForbiddenError(code="FORBIDDEN", message="x")
+        except Exception as got:
+            assert isinstance(got, IIIInvocationError)
+
+
+class TestWrapWireError:
+    def test_forbidden_dict_dispatches_to_forbidden_error(self) -> None:
+        err = _wrap_wire_error(
+            {"code": "FORBIDDEN", "message": "not allowed"},
+            function_id="engine::functions::list",
+            invocation_id="inv-1",
+        )
+        assert isinstance(err, IIIForbiddenError)
+        assert err.code == "FORBIDDEN"
+        assert err.function_id == "engine::functions::list"
+        assert err.invocation_id == "inv-1"
+
+    def test_timeout_dict_dispatches_to_timeout_error(self) -> None:
+        err = _wrap_wire_error(
+            {"code": "TIMEOUT", "message": "gone"},
+            function_id="api::slow",
+            invocation_id=None,
+        )
+        assert isinstance(err, IIITimeoutError)
+        assert err.code == "TIMEOUT"
+
+    def test_unknown_code_falls_back_to_base(self) -> None:
+        err = _wrap_wire_error(
+            {"code": "BUSINESS_RULE", "message": "nope"},
+            function_id=None,
+            invocation_id=None,
+        )
+        assert type(err) is IIIInvocationError
+        assert err.code == "BUSINESS_RULE"
+
+    def test_stacktrace_propagated_when_string(self) -> None:
+        err = _wrap_wire_error(
+            {"code": "HANDLER", "message": "boom", "stacktrace": "trace"},
+            function_id=None,
+            invocation_id=None,
+        )
+        assert err.stacktrace == "trace"
+
+    @pytest.mark.parametrize(
+        "bad_error",
+        [
+            None,
+            "a plain string",
+            42,
+            {},
+            {"code": 123, "message": "x"},
+            {"code": "X"},
+            {"message": "no code"},
+            {"code": "X", "message": None},
+        ],
+    )
+    def test_malformed_wire_errors_never_produce_raw_repr(self, bad_error: object) -> None:
+        """Guards against stringified-dict regression for every pathological shape."""
+        err = _wrap_wire_error(bad_error, function_id="fn", invocation_id=None)
+        assert isinstance(err, IIIInvocationError)
+        assert str(err).startswith(("UNKNOWN:", "X:", "123:"))
+        assert "{'" not in str(err), f"dict repr leaked into message: {err!s}"
+        assert "': " not in str(err), f"dict repr leaked into message: {err!s}"
+
+    def test_non_string_stacktrace_ignored(self) -> None:
+        err = _wrap_wire_error(
+            {"code": "X", "message": "m", "stacktrace": 42},
+            function_id=None,
+            invocation_id=None,
+        )
+        assert err.stacktrace is None

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/tests/test_rbac_workers.py

@@ -8,6 +8,8 @@ import pytest
 from iii import (
     AuthInput,
     AuthResult,
+    IIIForbiddenError,
+    IIIInvocationError,
     InitOptions,
     MiddlewareFunctionInput,
     OnFunctionRegistrationInput,
@@ -339,3 +341,130 @@ class TestRbacWorkers:
             assert result["echoed"]["msg"] == "prefix-test"
         finally:
             iii_client.shutdown()
+
+    def test_forbidden_wrapped_as_typed_error(self, iii_server):
+        """FORBIDDEN rejections surface as IIIForbiddenError with function_id set
+        and the engine's remediation phrase in the message."""
+        iii_client = register_worker(
+            EW_URL,
+            InitOptions(otel={"enabled": False}, headers={"x-test-token": "valid-token"}),
+        )
+
+        try:
+            with pytest.raises(IIIForbiddenError) as excinfo:
+                iii_client.trigger({
+                    "function_id": "test::ew::private",
+                    "payload": {},
+                })
+
+            err = excinfo.value
+            assert isinstance(err, IIIInvocationError)  # base class
+            assert err.code == "FORBIDDEN"
+            assert err.function_id == "test::ew::private"
+            assert "FORBIDDEN" in str(err)
+            assert "test::ew::private" in str(err)
+            # Remediation phrase from engine/src/engine/mod.rs:806
+            assert "rbac.expose_functions" in str(err)
+            # Guards against raw-dict regression (the Python equivalent of
+            # Node's `[object Object]`).
+            assert str(err) != repr({"code": "FORBIDDEN"})
+        finally:
+            iii_client.shutdown()
+
+    def test_restricted_handler_happy_path_under_infra_carveout(self, iii_server):
+        """Regression guard for the engine-side infrastructure carve-out.
+
+        A worker whose `expose_functions` only lists `test::ew::*` must still
+        be able to complete registration (engine::workers::register) and run
+        SDK-transparent engine calls (engine::log::*, engine::baggage::*).
+        If the carve-out ever regresses, connection setup FORBIDDENs here.
+        """
+        iii_client = register_worker(
+            EW_URL,
+            InitOptions(otel={"enabled": False}, headers={"x-test-token": "valid-token"}),
+        )
+
+        try:
+            # Successful invocation proves handshake completed without tripping
+            # FORBIDDEN on engine::workers::register (the transparent startup
+            # trigger) — otherwise the worker would not be reachable.
+            result = iii_client.trigger({
+                "function_id": "test::ew::valid-token-echo",
+                "payload": {"msg": "carveout-regression"},
+            })
+            assert result["valid_token"] is True
+            assert result["echoed"]["msg"] == "carveout-regression"
+        finally:
+            iii_client.shutdown()
+
+    # --- Infrastructure carve-out regression guards ---
+    #
+    # Lock in the engine-side INFRASTRUCTURE_FUNCTIONS carve-out end-to-end over
+    # a real WebSocket. Previously a worker whose allowed_functions /
+    # expose_functions did not cover `engine::*` IDs tripped FORBIDDEN the
+    # moment a handler used the SDK logger — the reporter's original bug.
+    # Paired with identical scenarios in
+    # sdk/packages/node/iii/tests/rbac-workers.test.ts and
+    # sdk/packages/rust/iii/tests/rbac_workers.rs.
+
+    def test_infrastructure_logger_callable_from_user_handler(self, iii_server):
+        """Real usage case: restricted worker's user handler calls the SDK
+        logger during invocation.
+
+        Handler runs under `allowed_functions: ['test::ew::valid-token-echo']`
+        and internally hits `engine::log::info` — allowed only via the
+        carve-out, not the allow-list. If the carve-out regresses, the nested
+        invocation FORBIDDENs and the handler raises instead of returning
+        ``{"logged": True}``.
+        """
+        iii_client = register_worker(
+            EW_URL,
+            InitOptions(otel={"enabled": False}, headers={"x-test-token": "valid-token"}),
+        )
+
+        try:
+            def handler(data: dict) -> dict:
+                # If the carve-out regresses, this nested trigger surfaces
+                # IIIForbiddenError and the handler propagates it as a failure.
+                iii_client.trigger({
+                    "function_id": "engine::log::info",
+                    "payload": {
+                        "message": "carve-out regression guard: handler reached logger",
+                        "data": {"input": data},
+                    },
+                })
+                return {"logged": True, "echoed": data}
+
+            iii_client.register_function("test::ew::valid-token-echo", handler)
+            time.sleep(0.5)
+
+            result = iii_server.trigger({
+                "function_id": "test::ew::valid-token-echo",
+                "payload": {"msg": "real-usage-case"},
+            })
+            assert result["logged"] is True
+        finally:
+            iii_client.shutdown()
+
+    def test_infrastructure_logger_directly_callable(self, iii_server):
+        """Direct variant: restricted worker invokes ``engine::log::info``
+        straight from its client — mirrors a bootstrap script / CLI.
+
+        ``engine::log::info`` is NOT in valid-token's allowed_functions, so
+        a successful trigger here proves the carve-out path is reachable from
+        the worker client's own ``trigger()`` method.
+        """
+        iii_client = register_worker(
+            EW_URL,
+            InitOptions(otel={"enabled": False}, headers={"x-test-token": "valid-token"}),
+        )
+
+        try:
+            # No exception == carve-out is working. If this raises
+            # IIIForbiddenError, the carve-out regressed.
+            iii_client.trigger({
+                "function_id": "engine::log::info",
+                "payload": {"message": "carve-out direct invocation"},
+            })
+        finally:
+            iii_client.shutdown()

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.3.dev2}/uv.lock

@@ -500,7 +500,7 @@ wheels = [
 
 [[package]]
 name = "iii-sdk"
-version = "0.11.0.dev9"
+version = "0.11.2"
 source = { editable = "." }
 dependencies = [
     { name = "opentelemetry-api" },