volcano-sdk-python 0.13.3__tar.gz → 0.13.4__tar.gz

volcano_sdk_python-0.13.4/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.13.4"
+}

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.13.4](https://github.com/Kong/volcano-sdk-python/compare/v0.13.3...v0.13.4) (2026-09-24)
+
+
+### Bug Fixes
+
+* **durable:** validate execution snapshots and exact mutation scope ([5652b49](https://github.com/Kong/volcano-sdk-python/commit/5652b49c5d6533cfd1c35dec7e2751234aedeae5))
+
 ## [0.13.3](https://github.com/Kong/volcano-sdk-python/compare/v0.13.2...v0.13.3) (2026-09-24)
 
 

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.13.3
+Version: 0.13.4
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/maintainers/quality-policy.lock.json

@@ -16,10 +16,21 @@
         },
         {
           "reportAny": "error",
+          "reportExplicitAny": "error",
           "reportUnannotatedClassAttribute": "error",
           "reportUnusedCallResult": "error",
           "root": "src/volcano_sdk/realtime.py"
         },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "root": "src/volcano_sdk/auth.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "root": "src/volcano_sdk/functions.py"
+        },
         {
           "reportAny": "error",
           "reportUnannotatedClassAttribute": "error",
@@ -43,6 +54,16 @@
           "reportUnusedCallResult": "error",
           "root": "tests/unit/test_realtime.py"
         },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "root": "tests/unit/test_functions.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "root": "tests/unit/test_logs.py"
+        },
         {
           "reportAny": "error",
           "reportExplicitAny": "error",

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "volcano-sdk-python"
-version = "0.13.3"
+version = "0.13.4"
 description = "Official Python SDK for Volcano"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -180,6 +180,17 @@ root = "src/volcano_sdk/realtime.py"
 reportUnannotatedClassAttribute = "error"
 reportUnusedCallResult = "error"
 reportAny = "error"
+reportExplicitAny = "error"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src/volcano_sdk/auth.py"
+reportAny = "error"
+reportExplicitAny = "error"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src/volcano_sdk/functions.py"
+reportAny = "error"
+reportExplicitAny = "error"
 
 [[tool.basedpyright.executionEnvironments]]
 root = "src/volcano_sdk/_transport.py"
@@ -204,6 +215,16 @@ reportImplicitStringConcatenation = "error"
 reportUnannotatedClassAttribute = "error"
 reportUnusedCallResult = "error"
 
+[[tool.basedpyright.executionEnvironments]]
+root = "tests/unit/test_functions.py"
+reportAny = "error"
+reportExplicitAny = "error"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests/unit/test_logs.py"
+reportAny = "error"
+reportExplicitAny = "error"
+
 [[tool.basedpyright.executionEnvironments]]
 root = "tests/unit/test_auth_facade_recovery.py"
 reportAny = "error"

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/scripts/check_quality_policy.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterable
 
 GENERATED = "src/volcano_sdk/_generated"
-LOCK_SHA256 = "87fb82c238174cf5427086d5296306d63d47e297c0be90b1ae6c15d99168e148"
+LOCK_SHA256 = "5da168f90e02c72a3ee45f4f7b8899149a80c408574c2b693c3d83db7b5d7c1b"
 TYPE_FIXTURES = {
     "tests/typing/contract_steps.py",
     "tests/typing/durable_callbacks.py",

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/scripts/mutation.sh

@@ -64,7 +64,7 @@ else
   for path in "${modules[@]}"; do
     module=${path#src/}
     module=${module%.py}
-    patterns+=("${module//\//.}*")
+    patterns+=("${module//\//.}.x*")
   done
   if ! mutmut run --max-children 1 "${patterns[@]}"; then
     printf '%s\0' "scoped mutation run" >> "$failed"

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/src/volcano_sdk/auth.py

@@ -459,12 +459,22 @@ def _oauth_provider_token_status_from_payload(
     )
 
 
+class _OAuthAPIData(Protocol):
+    @property
+    def data(self) -> object: ...
+
+
+def _oauth_api_data(payload: _OAuthAPIData) -> object:
+    return payload.data
+
+
 def _oauth_api_data_from_payload(payload: object) -> JSONValue:
     if not isinstance(payload, CallOAuthProviderAPIResponse200):
         raise VolcanoError(_INVALID_OAUTH_API_RESPONSE)
-    if not _is_json_value(payload.data):
+    data = _oauth_api_data(payload)
+    if not _is_json_value(data):
         raise VolcanoError(_INVALID_OAUTH_API_RESPONSE)
-    return _freeze_json(payload.data)
+    return _freeze_json(data)
 
 
 class _SetSession(Protocol):

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/src/volcano_sdk/durable.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping, Sequence
+import math
+from collections.abc import Mapping
 from datetime import datetime
-from typing import Protocol, cast, runtime_checkable
+from typing import Protocol, TypeGuard, runtime_checkable
 from uuid import UUID
 
 from ._transport import (
@@ -46,6 +47,15 @@ _UUID_IDENTIFIERS = {
 }
 _HTTP_ACCEPTED = 202
 _HTTP_OK = 200
+_EXECUTION_STATUSES: tuple[DurableExecutionStatus, ...] = (
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "stopped",
+    "unknown",
+)
 
 
 class DurableClientContext(Protocol):
@@ -318,13 +328,105 @@ def _identifier(value: object, field: str) -> str:
 
 
 def _execution_fields(payload: object) -> Mapping[str, object]:
-    if not isinstance(payload, Mapping):
+    if not _is_object_mapping(payload):
         raise TypeError(_INVALID_EXECUTION_PAYLOAD)
-    values = cast("Mapping[str, object]", payload)
     for required in ("id", "function_id", "name", "status", "region", "created_at"):
-        if not isinstance(values.get(required), str) or not values[required]:
+        if not isinstance(payload.get(required), str) or not payload[required]:
             raise TypeError(_INVALID_EXECUTION_PAYLOAD)
-    return values
+    return payload
+
+
+def _is_object_mapping(value: object) -> TypeGuard[Mapping[str, object]]:
+    return _is_mapping(value) and all(isinstance(key, str) for key in value)
+
+
+def _is_mapping(value: object) -> TypeGuard[Mapping[object, object]]:
+    return isinstance(value, Mapping)
+
+
+def _is_sequence(value: object) -> TypeGuard[list[object] | tuple[object, ...]]:
+    return isinstance(value, (list, tuple))
+
+
+def _execution_status(value: object) -> DurableExecutionStatus:
+    for status in _EXECUTION_STATUSES:
+        if value == status:
+            return status
+    raise TypeError(_INVALID_EXECUTION_PAYLOAD)
+
+
+def _json_result(value: object) -> JSONValue:
+    try:
+        if _is_json_value(value, set()):
+            return value
+    except RecursionError as error:
+        raise TypeError(_INVALID_EXECUTION_PAYLOAD) from error
+    raise TypeError(_INVALID_EXECUTION_PAYLOAD)
+
+
+def _is_json_value(value: object, active: set[int]) -> TypeGuard[JSONValue]:
+    if _is_json_scalar(value):
+        return True
+    if _is_mapping(value):
+        return _is_json_mapping(value, active)
+    if _is_sequence(value):
+        return _is_json_sequence(value, active)
+    return False
+
+
+def _is_json_scalar(value: object) -> TypeGuard[str | int | float | bool | None]:
+    if value is None or isinstance(value, bool):
+        return True
+    if isinstance(value, str):
+        return _is_utf8(value)
+    if isinstance(value, int):
+        return _is_json_int(value)
+    if isinstance(value, float):
+        return math.isfinite(value)
+    return False
+
+
+def _is_utf8(value: str) -> bool:
+    try:
+        _ = value.encode()
+    except UnicodeEncodeError:
+        return False
+    return True
+
+
+def _is_json_int(value: int) -> bool:
+    try:
+        _ = int.__str__(value)
+    except ValueError:
+        return False
+    return True
+
+
+def _is_json_mapping(value: Mapping[object, object], active: set[int]) -> bool:
+    marker = id(value)
+    if marker in active:
+        return False
+    active.add(marker)
+    try:
+        return all(
+            isinstance(key, str) and _is_utf8(key) and _is_json_value(item, active)
+            for key, item in value.items()
+        )
+    finally:
+        active.remove(marker)
+
+
+def _is_json_sequence(
+    value: list[object] | tuple[object, ...], active: set[int]
+) -> bool:
+    marker = id(value)
+    if marker in active:
+        return False
+    active.add(marker)
+    try:
+        return all(_is_json_value(item, active) for item in value)
+    finally:
+        active.remove(marker)
 
 
 def _durable_execution(payload: object) -> DurableExecution:
@@ -337,10 +439,10 @@ def _durable_execution(payload: object) -> DurableExecution:
         id=str(values["id"]),
         function_id=str(values["function_id"]),
         name=str(values["name"]),
-        status=cast("DurableExecutionStatus", str(values["status"])),
+        status=_execution_status(values["status"]),
         region=str(values["region"]),
         created_at=created_at,
-        result=cast("JSONValue", values.get("result")),
+        result=_json_result(values.get("result")),
         result_expired=result_expired,
         error=_durable_error(values.get("error")),
         completed_at=_datetime(values.get("completed_at")),
@@ -350,11 +452,10 @@ def _durable_execution(payload: object) -> DurableExecution:
 def _durable_error(payload: object) -> DurableExecutionFailure | None:
     if payload is None:
         return None
-    if not isinstance(payload, Mapping):
+    if not _is_object_mapping(payload):
         raise TypeError(_INVALID_EXECUTION_PAYLOAD)
-    values = cast("Mapping[str, object]", payload)
-    error_type = values.get("type")
-    message = values.get("message")
+    error_type = payload.get("type")
+    message = payload.get("message")
     return DurableExecutionFailure(
         type=None if error_type is None else str(error_type),
         message=None if message is None else str(message),
@@ -362,23 +463,22 @@ def _durable_error(payload: object) -> DurableExecutionFailure | None:
 
 
 def _durable_execution_page(payload: object) -> DurableExecutionPage:
-    if not isinstance(payload, Mapping):
+    if not _is_object_mapping(payload):
         raise TypeError(_INVALID_EXECUTION_PAGE)
-    values = cast("Mapping[str, object]", payload)
-    raw_data = values.get("data")
+    raw_data: object = payload.get("data")
     if raw_data is None:
-        raw_data = []
-    if not isinstance(raw_data, (list, tuple)):
+        raw_data = list[object]()
+    if not _is_sequence(raw_data):
         raise TypeError(_INVALID_EXECUTION_PAGE)
-    data = tuple(cast("Sequence[object]", raw_data))
-    has_more = values.get("has_more", False)
+    data = tuple(raw_data)
+    has_more = payload.get("has_more", False)
     if not isinstance(has_more, bool):
         raise TypeError(_INVALID_EXECUTION_PAGE)
     return DurableExecutionPage(
         executions=tuple(_durable_execution(entry) for entry in data),
-        page=_count(values.get("page")),
-        limit=_count(values.get("limit")),
-        total=_count(values.get("total")),
+        page=_count(payload.get("page")),
+        limit=_count(payload.get("limit")),
+        total=_count(payload.get("total")),
         has_more=has_more,
     )
 
@@ -402,8 +502,7 @@ def _datetime(value: object) -> datetime | None:
 def _parse_datetime(value: object) -> datetime:
     if not isinstance(value, str) or not value:
         raise TypeError(_INVALID_EXECUTION_PAYLOAD)
-    text = value.replace("Z", "+00:00") if value.endswith("Z") else value
     try:
-        return datetime.fromisoformat(text)
+        return datetime.fromisoformat(value)
     except ValueError as error:
         raise TypeError(_INVALID_EXECUTION_PAYLOAD) from error

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/src/volcano_sdk/functions.py

@@ -359,6 +359,13 @@ def _stale_mapping(response: TransportResponse) -> bool:
     )
 
 
+class _JSONLoader(Protocol):
+    def loads(self, s: str, /, *, parse_constant: Callable[[str], None]) -> object: ...
+
+
+_JSON_LOADER: _JSONLoader = json
+
+
 def _function_data(response: TransportResponse) -> JSONValue:
     if not response.content:
         return _json_value(response.payload)
@@ -369,7 +376,7 @@ def _function_data(response: TransportResponse) -> JSONValue:
     is_json = content_type is not None and "application/json" in content_type.lower()
     if is_json or text.startswith(("{", "[")):
         try:
-            decoded: object = json.loads(text, parse_constant=_reject_json_constant)
+            decoded = _JSON_LOADER.loads(text, parse_constant=_reject_json_constant)
             return _json_value(decoded)
         except ValueError:
             pass

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/src/volcano_sdk/realtime.py

@@ -10,7 +10,6 @@ from itertools import count
 from types import MappingProxyType
 from typing import (
     TYPE_CHECKING,
-    Any,
     Literal,
     Protocol,
     TypeAlias,
@@ -47,9 +46,11 @@ if TYPE_CHECKING:
 _PostgresFetchRequest: TypeAlias = PostgresFetchRequest
 _SubscriptionT = TypeVar("_SubscriptionT")
 _DefaultT = TypeVar("_DefaultT")
+_MessageT = TypeVar("_MessageT")
 
-MessageCallback = Callable[[Any], object]
-RealtimeCallback = Callable[[Any], object]
+MessageCallback: TypeAlias = Callable[[_MessageT], object]
+RealtimeCallback: TypeAlias = Callable[[_MessageT], object]
+_StoredCallback = Callable[..., object]
 UnsubscribeCallback = Callable[[], None]
 ChannelType: TypeAlias = Literal["broadcast", "presence", "postgres"]
 PostgresEvent: TypeAlias = Literal["INSERT", "UPDATE", "DELETE"]
@@ -703,7 +704,7 @@ def _presence_info(info: object) -> RealtimePresenceInfo:
 
 
 async def _run_connection_callback(
-    callback: RealtimeCallback,
+    callback: _StoredCallback,
     context: object,
 ) -> None:
     result = callback(context)
@@ -738,7 +739,7 @@ class Channel:
         self._name: str = name
         self._type: ChannelType = channel_type
         self._fetch_config: _PostgresFetchConfig = fetch_config
-        self._callbacks: dict[str, list[MessageCallback]] = {}
+        self._callbacks: dict[str, list[_StoredCallback]] = {}
         self._presence_state: dict[str, RealtimePresenceInfo] = {}
         self._presence_events: list[tuple[str, RealtimePresenceInfo]] = []
         self._presence_syncing: bool = False
@@ -787,7 +788,7 @@ class Channel:
         """Canonical channel name sent to realtime."""
         return self._name
 
-    def on(self, event: str, callback: MessageCallback) -> Channel:
+    def on(self, event: str, callback: Callable[[_MessageT], object]) -> Channel:
         """Register a callback for messages or presence events.
 
         Returns
@@ -852,7 +853,9 @@ class Channel:
 
         return unsubscribe
 
-    def on_presence_sync(self, callback: MessageCallback) -> UnsubscribeCallback:
+    def on_presence_sync(
+        self, callback: Callable[[Mapping[str, RealtimePresenceInfo]], object]
+    ) -> UnsubscribeCallback:
         """Observe immutable snapshots of a presence channel's current state.
 
         Requires a presence channel.
@@ -1204,7 +1207,7 @@ class Channel:
 
     async def _run_callback(
         self,
-        callback: MessageCallback,
+        callback: _StoredCallback,
         delivery: _CallbackDelivery,
     ) -> None:
         if not self._callback_delivery_is_current(delivery):
@@ -1406,7 +1409,7 @@ class Realtime:
         self._channels: dict[str, Channel] = {}
         self._callback_tasks: set[asyncio.Task[None]] = set()
         self._removing_channels: set[str] = set()
-        self._connection_callbacks: dict[str, dict[int, RealtimeCallback]] = {
+        self._connection_callbacks: dict[str, dict[int, _StoredCallback]] = {
             "connect": {},
             "disconnect": {},
             "error": {},
@@ -1458,7 +1461,9 @@ class Realtime:
             for request in requests
         )
 
-    def on_connect(self, callback: RealtimeCallback) -> UnsubscribeCallback:
+    def on_connect(
+        self, callback: Callable[[RealtimeConnectContext], object]
+    ) -> UnsubscribeCallback:
         """Register a connection callback.
 
         Returns
@@ -1469,7 +1474,9 @@ class Realtime:
         """
         return self._register_connection_callback("connect", callback)
 
-    def on_disconnect(self, callback: RealtimeCallback) -> UnsubscribeCallback:
+    def on_disconnect(
+        self, callback: Callable[[RealtimeDisconnectContext], object]
+    ) -> UnsubscribeCallback:
         """Register a disconnection callback.
 
         Returns
@@ -1480,7 +1487,9 @@ class Realtime:
         """
         return self._register_connection_callback("disconnect", callback)
 
-    def on_error(self, callback: RealtimeCallback) -> UnsubscribeCallback:
+    def on_error(
+        self, callback: Callable[[RealtimeErrorContext], object]
+    ) -> UnsubscribeCallback:
         """Register a transport-error callback.
 
         Returns
@@ -1494,7 +1503,7 @@ class Realtime:
     def _register_connection_callback(
         self,
         event: str,
-        callback: RealtimeCallback,
+        callback: _StoredCallback,
     ) -> UnsubscribeCallback:
         require_callable(callback, CALLBACK_NOT_CALLABLE)
         callback_id = next(self._callback_ids)

volcano_sdk_python-0.13.4/tests/unit/fixtures/invalid_realtime_callback.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from volcano_sdk.realtime import (
+        Channel,
+        MessageCallback,
+        Realtime,
+        RealtimeCallback,
+        RealtimeConnectContext,
+    )
+
+
+def register_non_callable(realtime: Realtime) -> None:
+    # Native mypy must report arg-type; unused-ignore rejects a missing diagnostic.
+    _ = realtime.on_connect(None)  # type: ignore[arg-type]
+
+
+def register_callback_without_message(channel: Channel) -> None:
+    def receive_nothing() -> None:
+        return None
+
+    _ = channel.on("message", receive_nothing)  # type: ignore[arg-type]
+
+
+def assign_callback_without_message() -> None:
+    def receive_nothing() -> None:
+        return None
+
+    message_callback: MessageCallback[str] = receive_nothing  # type: ignore[assignment]
+    realtime_callback: RealtimeCallback[RealtimeConnectContext] = receive_nothing  # type: ignore[assignment]
+    del message_callback, realtime_callback
+
+
+def assign_narrow_callbacks() -> None:
+    def receive_message(message: str) -> None:
+        del message
+
+    def connected(context: RealtimeConnectContext) -> None:
+        del context
+
+    message_callback: MessageCallback[str] = receive_message
+    realtime_callback: RealtimeCallback[RealtimeConnectContext] = connected
+    del message_callback, realtime_callback

{volcano_sdk_python-0.13.3 → volcano_sdk_python-0.13.4}/tests/unit/test_durable.py

@@ -129,6 +129,8 @@ def test_start_returns_the_accepted_execution_handle() -> None:
     )
 
     assert execution.id == EXECUTION_ID
+    assert execution.function_id == "00000000-0000-4000-8000-000000000040"
+    assert execution.name == "order-42"
     assert execution.status == "running"
     assert execution.region == "aws-us-east-1"
     assert execution.created_at == datetime(2026, 9, 2, 12, 0, tzinfo=UTC)
@@ -229,6 +231,32 @@ def test_get_reports_a_failed_execution_error() -> None:
     assert execution.error.message == "card was declined"
 
 
+@pytest.mark.parametrize(
+    ("error", "expected_type", "expected_message"),
+    [
+        ({}, None, None),
+        ({"type": None, "message": None}, None, None),
+        ({"type": "CardDeclined"}, "CardDeclined", None),
+        ({"message": "card was declined"}, None, "card was declined"),
+    ],
+)
+def test_get_preserves_optional_failure_fields(
+    error: dict[str, object], expected_type: str | None, expected_message: str | None
+) -> None:
+    transport = FakeDurableTransport()
+    transport.get_response = FakeResponse(
+        200, running_execution(status="failed", error=error), {}
+    )
+
+    execution = durable_client(transport).durable.get(
+        PROJECT_ID, "order-pipeline", EXECUTION_ID
+    )
+
+    assert execution.error is not None
+    assert execution.error.type == expected_type
+    assert execution.error.message == expected_message
+
+
 def test_get_distinguishes_an_expired_result_from_an_empty_one() -> None:
     transport = FakeDurableTransport()
     transport.get_response = FakeResponse(
@@ -409,6 +437,16 @@ def test_start_refuses_an_execution_name_over_the_platform_limit() -> None:
     assert transport.calls == []
 
 
+def test_start_accepts_an_execution_name_at_the_platform_limit() -> None:
+    transport = FakeDurableTransport()
+
+    _ = durable_client(transport).durable.start(
+        "order-pipeline", {}, execution_name="x" * 255
+    )
+
+    assert transport.calls[0][1]["execution_name"] == "x" * 255
+
+
 def test_owner_scoped_reads_send_the_session_token() -> None:
     """The routes take a user token, so that is the only credential to send.
 
@@ -507,6 +545,24 @@ def test_owner_scoped_reads_reject_identifiers_that_are_not_uuids() -> None:
     assert transport.calls == []
 
 
+@pytest.mark.parametrize(
+    ("project_id", "function_name", "expected"),
+    [
+        ("not-a-uuid", "order-pipeline", "project_id must be a UUID"),
+        (PROJECT_ID, "", "function_name must be a non-empty string"),
+    ],
+)
+def test_list_rejects_invalid_identifiers_before_transport(
+    project_id: str, function_name: str, expected: str
+) -> None:
+    transport = FakeDurableTransport()
+
+    with pytest.raises(ValueError, match=expected):
+        _ = durable_client(transport).durable.list(project_id, function_name)
+
+    assert transport.calls == []
+
+
 def test_an_execution_has_a_stable_hash() -> None:
     execution = durable_client(FakeDurableTransport()).durable.get(
         PROJECT_ID, "order-pipeline", EXECUTION_ID