iii-sdk 0.20.0.dev1__tar.gz → 0.21.0.dev1__tar.gz

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.20.0.dev1
+Version: 0.21.0.dev1
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/iii
 Project-URL: Repository, https://github.com/iii-hq/iii
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: iii-helpers==0.20.0.dev1
+Requires-Dist: iii-helpers==0.21.0.dev1
 Requires-Dist: opentelemetry-api>=1.25
 Requires-Dist: pydantic>=2.0
 Requires-Dist: websockets>=12.0

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.20.0.dev1"
+version = "0.21.0.dev1"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }
@@ -23,7 +23,7 @@ dependencies = [
     "websockets>=12.0",
     "pydantic>=2.0",
     "opentelemetry-api>=1.25",
-    "iii-helpers==0.20.0.dev1",
+    "iii-helpers==0.21.0.dev1",
 ]
 
 [project.urls]

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/src/iii/iii.py

@@ -1,6 +1,7 @@
 """III SDK implementation for WebSocket communication with the III Engine."""
 
 import asyncio
+import inspect
 import json
 import logging
 import os
@@ -64,6 +65,45 @@ TResult = TypeVar("TResult")
 log = logging.getLogger("iii.iii")
 
 
+def _metadata_passing_mode(handler: Callable[..., Any]) -> str:
+    """Decide how (if at all) to forward per-invocation metadata to a handler.
+
+    Only handlers that explicitly declare a parameter named ``metadata``
+    receive the sidecar; every other signature keeps its exact pre-metadata
+    call shape (``handler(data)``), so existing handlers -- including ones
+    with unrelated optional parameters, ``*args``, or ``**kwargs`` -- keep
+    working unchanged. Returns one of:
+
+    - ``"positional"``: ``metadata`` is the second positional parameter
+      (e.g. ``def handler(data, metadata=None)``).
+    - ``"keyword"``: ``metadata`` is keyword-only
+      (e.g. ``def handler(data, *, metadata=None)``).
+    - ``"none"``: no ``metadata`` parameter -- omit metadata.
+
+    If the signature cannot be introspected (some builtins/C callables),
+    falls back to ``"none"`` to preserve back-compat.
+    """
+    try:
+        sig = inspect.signature(handler)
+    except (ValueError, TypeError):
+        return "none"
+
+    meta_param = sig.parameters.get("metadata")
+    if meta_param is None:
+        return "none"
+    if meta_param.kind == inspect.Parameter.KEYWORD_ONLY:
+        return "keyword"
+
+    positional = [
+        p
+        for p in sig.parameters.values()
+        if p.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(positional) >= 2 and positional[1].name == "metadata":
+        return "positional"
+    return "none"
+
+
 def _resolve_format(fmt: Any) -> Any | None:
     """Resolve a format value: if it's a type (e.g. Pydantic model), convert to JSON Schema."""
     if fmt is None:
@@ -434,6 +474,7 @@ class III:
                     data.get("data"),
                     data.get("traceparent"),
                     data.get("baggage"),
+                    data.get("metadata"),
                 )
             )
         elif msg_type == MessageType.REGISTER_TRIGGER.value:
@@ -483,10 +524,11 @@ class III:
     async def _invoke_with_otel_context(
         self,
         function_id: str,
-        handler: Callable[[Any], Awaitable[Any]],
+        handler: Callable[..., Awaitable[Any]],
         data: Any,
         traceparent: str | None,
         baggage: str | None,
+        metadata: dict[str, Any] | None = None,
     ) -> tuple[Any, str | None]:
         from opentelemetry import context as otel_context
         from opentelemetry import propagate, trace
@@ -531,7 +573,7 @@ class III:
                     },
                 )
             try:
-                result = await handler(data)
+                result = await handler(data, metadata)
                 if trace_payloads and span.is_recording():
                     out_json, out_truncated = redact_and_truncate(result, payload_max_bytes)
                     span.add_event(
@@ -586,6 +628,7 @@ class III:
         data: Any,
         traceparent: str | None = None,
         baggage: str | None = None,
+        metadata: dict[str, Any] | None = None,
     ) -> None:
         func = self._functions.get(path)
 
@@ -627,7 +670,7 @@ class III:
         if not invocation_id:
             task = asyncio.create_task(
                 self._invoke_with_otel_context(
-                    path, func.handler, resolved_data, traceparent, baggage
+                    path, func.handler, resolved_data, traceparent, baggage, metadata
                 )
             )
             task.add_done_callback(self._log_task_exception)
@@ -640,6 +683,7 @@ class III:
                 resolved_data,
                 traceparent,
                 baggage,
+                metadata,
             )
             await self._send(
                 InvocationResultMessage(
@@ -927,8 +971,14 @@ class III:
 
         Handlers can be synchronous or asynchronous.  Sync handlers are
         automatically wrapped with ``run_in_executor`` so they do not
-        block the event loop.  Each handler receives a single ``data``
-        argument containing the trigger payload.
+        block the event loop.  Each handler receives a ``data`` argument
+        containing the trigger payload, and may optionally accept a second
+        ``metadata`` argument carrying per-invocation metadata (e.g.
+        ``def handler(data, metadata=None)`` or ``def handler(data, *,
+        metadata=None)``).  Metadata is only forwarded to handlers that
+        declare a parameter literally named ``metadata``, so existing
+        handlers -- including ones with unrelated extra parameters,
+        ``*args``, or ``**kwargs`` -- keep working unchanged.
 
         ``request_format`` and ``response_format`` are auto-extracted
         from the handler's type hints when omitted or passed as ``None``
@@ -940,9 +990,10 @@ class III:
         Args:
             function_id: Unique string identifier for the function.
             handler_or_invocation: A callable handler or
-                ``HttpInvocationConfig``.  Callable handlers receive one
-                positional argument (``data`` -- the trigger payload) and
-                may return a value.
+                ``HttpInvocationConfig``.  Callable handlers receive
+                ``data`` (the trigger payload) as the first argument and
+                may optionally accept ``metadata`` (per-invocation
+                metadata) as a second argument; they may return a value.
             description: Human-readable description.
             metadata: Arbitrary metadata.
             request_format: Schema describing expected input.  When
@@ -1020,7 +1071,7 @@ class III:
                 raise TypeError(
                     f"handler_or_invocation must be callable or HttpInvocationConfig, got {actual_type}"
                 )
-            handler = handler_or_invocation
+            handler = cast("Callable[..., Any]", handler_or_invocation)
             msg = RegisterFunctionMessage(
                 id=func.id,
                 description=func.description,
@@ -1030,20 +1081,31 @@ class III:
             )
             self._send_if_connected(msg)
 
+            # Decide once, at registration time, whether this handler accepts
+            # per-invocation metadata. 1-arg handlers keep working unchanged.
+            metadata_mode = _metadata_passing_mode(handler)
+
+            def _call_handler(input_data: Any, metadata: dict[str, Any] | None) -> Any:
+                if metadata_mode == "positional":
+                    return handler(input_data, metadata)
+                if metadata_mode == "keyword":
+                    return handler(input_data, metadata=metadata)
+                return handler(input_data)
+
             if asyncio.iscoroutinefunction(handler):
 
-                async def wrapped(input_data: Any) -> Any:
-                    return await handler(input_data)
+                async def wrapped(input_data: Any, metadata: dict[str, Any] | None = None) -> Any:
+                    return await _call_handler(input_data, metadata)
 
             else:
 
-                async def wrapped(input_data: Any) -> Any:
+                async def wrapped(input_data: Any, metadata: dict[str, Any] | None = None) -> Any:
                     loop = asyncio.get_running_loop()
                     future: asyncio.Future[Any] = loop.create_future()
 
                     def _run() -> None:
                         try:
-                            result = handler(input_data)
+                            result = _call_handler(input_data, metadata)
                             loop.call_soon_threadsafe(future.set_result, result)
                         except BaseException as exc:
                             loop.call_soon_threadsafe(future.set_exception, exc)
@@ -1120,6 +1182,7 @@ class III:
         function_id = req["function_id"]
         payload = req.get("payload")
         action = req.get("action")
+        metadata = req.get("metadata")
 
         timeout_ms = req.get("timeout_ms") or self._options.invocation_timeout_ms
 
@@ -1137,6 +1200,7 @@ class III:
                 InvokeFunctionMessage(
                     function_id=function_id,
                     data=payload,
+                    metadata=metadata,
                     traceparent=self._inject_traceparent(),
                     baggage=self._inject_baggage(),
                     action=action,
@@ -1160,6 +1224,7 @@ class III:
             InvokeFunctionMessage(
                 function_id=function_id,
                 data=payload,
+                metadata=metadata,
                 invocation_id=invocation_id,
                 traceparent=self._inject_traceparent(),
                 baggage=self._inject_baggage(),

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/src/iii/iii_types.py

@@ -92,7 +92,7 @@ class RegisterTriggerInput(BaseModel):
     type: str = Field(description="Trigger type identifier.")
     function_id: str = Field(description="ID of the function this trigger invokes.")
     config: Any = Field(default=None, description="Trigger-type-specific configuration.")
-    metadata: dict[str, Any] | None = Field(
+    metadata: Any | None = Field(
         default=None, description="Arbitrary metadata attached to the trigger."
     )
 
@@ -104,7 +104,7 @@ class RegisterTriggerMessage(BaseModel):
     trigger_type: str = Field(alias="trigger_type")
     function_id: str = Field()
     config: Any
-    metadata: dict[str, Any] | None = Field(default=None)
+    metadata: Any | None = Field(default=None)
     message_type: MessageType = Field(default=MessageType.REGISTER_TRIGGER, alias="type")
 
 
@@ -148,7 +148,7 @@ class RegisterFunctionInput(BaseModel):
     response_format: RegisterFunctionFormat | dict[str, Any] | None = Field(
         default=None, description="Schema describing expected output."
     )
-    metadata: dict[str, Any] | None = Field(default=None, description="Arbitrary metadata attached to the function.")
+    metadata: Any | None = Field(default=None, description="Arbitrary metadata attached to the function.")
     invocation: HttpInvocationConfig | None = Field(
         default=None,
         description="HTTP invocation config for externally hosted functions.",
@@ -162,7 +162,7 @@ class RegisterFunctionMessage(BaseModel):
     description: str | None = None
     request_format: RegisterFunctionFormat | dict[str, Any] | None = Field(default=None)
     response_format: RegisterFunctionFormat | dict[str, Any] | None = Field(default=None)
-    metadata: dict[str, Any] | None = None
+    metadata: Any | None = None
     invocation: HttpInvocationConfig | None = None
     message_type: MessageType = Field(default=MessageType.REGISTER_FUNCTION, alias="type")
 
@@ -223,6 +223,8 @@ class TriggerRequest(BaseModel):
         action: Routing action, ``None`` for sync, ``TriggerAction.Enqueue(...)``
             for queue, ``TriggerAction.Void()`` for fire-and-forget.
         timeout_ms: Override the default invocation timeout.
+        metadata: Arbitrary per-invocation metadata delivered to the handler
+            as a separate channel (not folded into ``payload``).
     """
 
     function_id: str = Field(description="ID of the function to invoke.")
@@ -236,6 +238,10 @@ class TriggerRequest(BaseModel):
         ),
     )
     timeout_ms: int | None = Field(default=None, description="Override the default invocation timeout.")
+    metadata: Any | None = Field(
+        default=None,
+        description="Arbitrary per-invocation metadata delivered to the handler.",
+    )
 
 
 class InvokeFunctionMessage(BaseModel):
@@ -243,6 +249,7 @@ class InvokeFunctionMessage(BaseModel):
 
     function_id: str = Field()
     data: Any
+    metadata: Any | None = Field(default=None)
     invocation_id: str | None = Field(default=None)
     traceparent: str | None = Field(default=None)
     baggage: str | None = Field(default=None)

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/tests/test_invocation_exception.py

@@ -30,7 +30,7 @@ async def test_invoke_with_otel_context_records_exception_with_stacktrace():
         client._queue = []
         client._running = False
 
-        async def failing_handler(data):
+        async def failing_handler(data, metadata=None):
             raise ValueError("test invocation error")
 
         with pytest.raises(_TraceContextError) as exc_info:
@@ -78,7 +78,7 @@ async def test_invoke_with_otel_context_success_no_exception():
         client._queue = []
         client._running = False
 
-        async def success_handler(data):
+        async def success_handler(data, metadata=None):
             return {"result": "ok"}
 
         result, traceparent = await client._invoke_with_otel_context("test.fn", success_handler, {"key": "value"}, None, None)

iii_sdk-0.21.0.dev1/tests/test_invocation_metadata.py

@@ -0,0 +1,298 @@
+"""Tests for per-invocation metadata support.
+
+Covers the wire mirror (``InvokeFunctionMessage.metadata``), the handler
+signature convention (metadata is forwarded only when the handler accepts
+it -- 1-arg handlers keep working), and the outbound ``trigger`` API.
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import iii.iii as iii_module
+from iii.iii import III, _metadata_passing_mode
+from iii.iii_constants import InitOptions
+from iii.iii_types import InvokeFunctionMessage, TriggerActionVoid, TriggerRequest
+
+
+@pytest.fixture
+def client(monkeypatch):
+    """A client whose background loop runs but never connects to an engine.
+
+    Constructing an ``III`` runs ``connect_async`` -> ``init_otel``, which
+    installs global OTel providers. We reset those singletons on teardown so
+    this test does not leak provider state into later tests (mirrors the
+    cleanup in ``test_context_propagation.py``).
+    """
+
+    async def fake_do_connect(self):
+        return None
+
+    monkeypatch.setattr(iii_module.III, "_do_connect", fake_do_connect)
+    c = III(address="ws://localhost:9999", options=InitOptions(worker_name="test"))
+    yield c
+    c.shutdown()
+    _reset_otel_singletons()
+
+
+def _reset_otel_singletons():
+    """Reset OTel global provider singletons so tests stay isolated."""
+    try:
+        import opentelemetry._logs._internal as _li
+
+        _li._LOGGER_PROVIDER = None
+        _li._LOGGER_PROVIDER_SET_ONCE._done = False
+    except Exception:
+        pass
+    try:
+        import opentelemetry.trace._internal as _ti
+
+        _ti._TRACER_PROVIDER = None
+        _ti._TRACER_PROVIDER_SET_ONCE._done = False
+    except Exception:
+        pass
+    try:
+        import opentelemetry.metrics._internal as _mi
+
+        _mi._METER_PROVIDER = None
+        _mi._METER_PROVIDER_SET_ONCE._done = False
+    except Exception:
+        pass
+
+
+# --- _metadata_passing_mode: handler-arity detection -----------------------
+
+
+def test_mode_positional_for_two_arg_handler():
+    def handler(data, metadata=None):
+        return None
+
+    assert _metadata_passing_mode(handler) == "positional"
+
+
+def test_mode_positional_for_required_metadata_param():
+    def handler(data, metadata):
+        return None
+
+    assert _metadata_passing_mode(handler) == "positional"
+
+
+def test_mode_keyword_for_keyword_only_metadata():
+    def handler(data, *, metadata=None):
+        return None
+
+    assert _metadata_passing_mode(handler) == "keyword"
+
+
+def test_mode_none_for_single_arg_handler():
+    def handler(data):
+        return None
+
+    assert _metadata_passing_mode(handler) == "none"
+
+
+def test_mode_none_for_unrelated_second_positional_param():
+    # A pre-existing handler with an unrelated optional second parameter must
+    # keep its exact old call shape: handler(data), so `retries` stays 3.
+    def handler(data, retries=3):
+        return None
+
+    assert _metadata_passing_mode(handler) == "none"
+
+
+def test_mode_none_for_var_keyword_handler():
+    # **kwargs handlers previously received no keyword arguments; injecting
+    # metadata into kwargs would change their observable input.
+    def handler(data, **kwargs):
+        return None
+
+    assert _metadata_passing_mode(handler) == "none"
+
+
+def test_mode_none_for_var_positional_handler():
+    # *args handlers previously received exactly one argument; appending
+    # metadata would change len(args).
+    def handler(*args):
+        return None
+
+    assert _metadata_passing_mode(handler) == "none"
+
+
+# --- handler receives invocation metadata when it accepts it ---------------
+
+
+def test_sync_handler_receives_invocation_metadata(client):
+    received = {}
+
+    def handler(data, metadata=None):
+        received["data"] = data
+        received["metadata"] = metadata
+        return {"ok": True}
+
+    client.register_function("fn::meta", handler)
+
+    with patch.object(client, "_send", new_callable=AsyncMock):
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="inv-1",
+                path="fn::meta",
+                data={"x": 1},
+                metadata={"tenant": "acme"},
+            )
+        )
+
+    assert received["data"] == {"x": 1}
+    assert received["metadata"] == {"tenant": "acme"}
+
+
+def test_async_handler_receives_invocation_metadata(client):
+    received = {}
+
+    async def handler(data, metadata=None):
+        received["metadata"] = metadata
+        return {"ok": True}
+
+    client.register_function("fn::async-meta", handler)
+
+    with patch.object(client, "_send", new_callable=AsyncMock):
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="inv-2",
+                path="fn::async-meta",
+                data={},
+                metadata={"region": "us"},
+            )
+        )
+
+    assert received["metadata"] == {"region": "us"}
+
+
+def test_keyword_only_handler_receives_invocation_metadata(client):
+    received = {}
+
+    def handler(data, *, metadata=None):
+        received["metadata"] = metadata
+        return {"ok": True}
+
+    client.register_function("fn::kw-meta", handler)
+
+    with patch.object(client, "_send", new_callable=AsyncMock):
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="inv-3",
+                path="fn::kw-meta",
+                data={},
+                metadata={"k": "v"},
+            )
+        )
+
+    assert received["metadata"] == {"k": "v"}
+
+
+# --- back-compat: 1-arg handler keeps working when metadata is present -----
+
+
+def test_one_arg_handler_still_works_with_metadata_present(client):
+    received = {}
+
+    def handler(data):
+        received["data"] = data
+        return {"ok": True}
+
+    client.register_function("fn::legacy", handler)
+
+    with patch.object(client, "_send", new_callable=AsyncMock) as send_mock:
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="inv-4",
+                path="fn::legacy",
+                data={"x": 2},
+                metadata={"present": True},
+            )
+        )
+
+    # Handler ran with just `data` and did not crash.
+    assert received["data"] == {"x": 2}
+    # The invocation completed successfully (a result, not an error, was sent).
+    result_msg = send_mock.call_args.args[0]
+    assert result_msg.error is None
+    assert result_msg.result == {"ok": True}
+
+
+# --- outbound trigger() populates the wire metadata field ------------------
+
+
+def test_trigger_async_dict_populates_outbound_metadata(client):
+    with patch.object(client, "_send", new_callable=AsyncMock) as send_mock:
+        client._run_on_loop(
+            client.trigger_async(
+                {
+                    "function_id": "remote::fn",
+                    "payload": {"a": 1},
+                    "action": TriggerActionVoid(),
+                    "metadata": {"caller": "svc-a"},
+                }
+            )
+        )
+
+    msg = send_mock.call_args.args[0]
+    assert isinstance(msg, InvokeFunctionMessage)
+    assert msg.data == {"a": 1}
+    assert msg.metadata == {"caller": "svc-a"}
+
+
+def test_trigger_async_request_object_populates_outbound_metadata(client):
+    with patch.object(client, "_send", new_callable=AsyncMock) as send_mock:
+        client._run_on_loop(
+            client.trigger_async(
+                TriggerRequest(
+                    function_id="remote::fn",
+                    payload={"a": 1},
+                    action=TriggerActionVoid(),
+                    metadata={"caller": "svc-b"},
+                )
+            )
+        )
+
+    msg = send_mock.call_args.args[0]
+    assert msg.metadata == {"caller": "svc-b"}
+
+
+def test_trigger_async_without_metadata_leaves_field_none(client):
+    with patch.object(client, "_send", new_callable=AsyncMock) as send_mock:
+        client._run_on_loop(
+            client.trigger_async(
+                {
+                    "function_id": "remote::fn",
+                    "payload": {},
+                    "action": TriggerActionVoid(),
+                }
+            )
+        )
+
+    msg = send_mock.call_args.args[0]
+    assert msg.metadata is None
+
+
+# --- InvokeFunctionMessage round-trip / omission ---------------------------
+
+
+def test_invoke_function_message_roundtrips_metadata():
+    msg = InvokeFunctionMessage(function_id="fn", data={"x": 1}, metadata={"trace": "abc"})
+    dumped = msg.model_dump(by_alias=True, exclude_none=True)
+    assert dumped["metadata"] == {"trace": "abc"}
+
+    parsed = InvokeFunctionMessage.model_validate(dumped)
+    assert parsed.metadata == {"trace": "abc"}
+
+
+def test_invoke_function_message_omits_metadata_when_none():
+    msg = InvokeFunctionMessage(function_id="fn", data={"x": 1})
+    dumped = msg.model_dump(by_alias=True, exclude_none=True)
+    assert "metadata" not in dumped
+
+
+def test_invoke_function_message_absent_metadata_parses_to_none():
+    # Backward compatible: an inbound message with no `metadata` key.
+    parsed = InvokeFunctionMessage.model_validate({"function_id": "fn", "data": {}})
+    assert parsed.metadata is None

{iii_sdk-0.20.0.dev1 → iii_sdk-0.21.0.dev1}/uv.lock

@@ -546,7 +546,7 @@ wheels = [
 
 [[package]]
 name = "iii-helpers"
-version = "0.19.6"
+version = "0.20.0"
 source = { editable = "../helpers" }
 dependencies = [
     { name = "httpx" },
@@ -574,7 +574,7 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "iii-sdk"
-version = "0.19.7"
+version = "0.20.0"
 source = { editable = "." }
 dependencies = [
     { name = "iii-helpers" },