volcano-sdk-python 0.13.0__tar.gz → 0.13.2__tar.gz

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

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

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.13.2](https://github.com/Kong/volcano-sdk-python/compare/v0.13.1...v0.13.2) (2026-09-24)
+
+
+### Bug Fixes
+
+* **python:** guard function resolution and lock expiry boundaries ([#361](https://github.com/Kong/volcano-sdk-python/issues/361)) ([505b7e2](https://github.com/Kong/volcano-sdk-python/commit/505b7e2e8c79be9a086430cc462a04191994be84))
+* validate log JSON boundaries and close mutation gaps ([#356](https://github.com/Kong/volcano-sdk-python/issues/356)) ([d1e76da](https://github.com/Kong/volcano-sdk-python/commit/d1e76da9a7c164a69b87f570bd2216ebe20afe82))
+
+## [0.13.1](https://github.com/Kong/volcano-sdk-python/compare/v0.13.0...v0.13.1) (2026-09-24)
+
+
+### Bug Fixes
+
+* **realtime:** validate wire events and bound callback lifecycle ([#350](https://github.com/Kong/volcano-sdk-python/issues/350)) ([9a4deb1](https://github.com/Kong/volcano-sdk-python/commit/9a4deb13477150c6b26e7fed61fc56ce7c7aa1e6))
+
 ## [0.13.0](https://github.com/Kong/volcano-sdk-python/compare/v0.12.0...v0.13.0) (2026-09-23)
 
 

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.13.0
+Version: 0.13.2
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -94,17 +94,22 @@ execution = client.durable.start(
 )
 print(execution.id, execution.status)
 
-execution = client.durable.get(
+owner_client = VolcanoClient(
+    api_url="https://api.volcano.dev",
+    anon_key="your-anon-key",
+    access_token="your-platform-user-token",
+)
+execution = owner_client.durable.get(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
 )
 print(execution.is_terminal, execution.result)
 
-executions = client.durable.list(
+executions = owner_client.durable.list(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", status="running"
 )
 print(executions.total, executions.has_more)
 
-client.durable.stop(
+owner_client.durable.stop(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
 )
 
@@ -264,18 +269,18 @@ A function's own response, HTTP 403, or a network failure never triggers this re
 Anonymous and service keys do not refresh.
 
 `durable.start()` begins an execution of a deployed durable function and returns
-a handle rather than a result: an execution can run for hours, so its result is
-read back with `durable.get()`. It takes the credential `functions.invoke()`
+a handle rather than a result: an execution can run for up to 366 days, so its
+result is read back with `durable.get()`. It takes the credential `functions.invoke()`
 takes, and is the only durable operation an application credential may perform.
 An `execution_name` makes the start idempotent — starting again under the same
 name returns the execution that already exists rather than beginning a second
 one, and is charged once.
 
 `durable.get()`, `durable.list()` and `durable.stop()` are owner-scoped and need
-the project's own platform token, because an execution is addressed by its id
-alone and an anonymous key is held by everyone who loads the page. Neither an
-auth-user session from `sign_in()` nor a service key is accepted -- the routes
-take a user token, and anything else is answered 401. Poll them from a backend.
+the project owner's platform user token, because an execution is addressed by
+its id alone and an anonymous key is held by everyone who loads the page.
+Auth-user sessions from `sign_in()`, anonymous keys, service keys, and project
+access tokens are not accepted. Poll them from a trusted backend.
 `get()` carries `result` once the execution has succeeded and `error` when it
 failed; `result_expired` separates a result the platform has discarded from a
 function that returned nothing. `is_terminal` reports whether the execution has
@@ -315,6 +320,31 @@ def handler(event, ctx):
     return {"charged": charge["id"], "packed": packed.results}
 ```
 
+Use the function name for its source directory and manifest entry:
+
+```text
+volcano/functions/order-pipeline/
+├── main.py
+└── requirements.txt
+```
+
+```text
+# volcano/functions/order-pipeline/requirements.txt
+volcano-sdk-python
+```
+
+```yaml
+# volcano-config.yaml
+version: 1
+project:
+  name: my-app
+functions:
+  - name: order-pipeline
+    kind: durable
+```
+
+The decorator defines handler behavior. The manifest declaration makes the function discoverable by `volcano durable deploy`.
+
 Every context operation is checkpointed: what finished is recorded, and a
 resumed execution replays that recorded outcome instead of doing the work again.
 That is the one rule the handler has to respect — the code between operations
@@ -356,6 +386,20 @@ nothing while it waits. Running the handler anywhere durable execution does not
 exist raises `DurableRuntimeMissingError` rather than an import error from an
 unfamiliar package.
 
+Run the same handler through the local durable engine:
+
+```bash
+volcano start
+volcano durable deploy --all
+volcano durable start order-pipeline --input '{"order_id":"order-9"}'
+```
+
+Local waits resolve immediately by default while preserving checkpoint and replay
+behavior. Set `LOCAL_DURABLE_REAL_TIME=true` before `volcano start` when wait
+timing must match the deployed function. Local executions persist across
+`volcano stop` and `volcano start`. Volcano does not expose externally completed
+callbacks; use `ctx.wait_until` to poll application state instead.
+
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/README.md

@@ -69,17 +69,22 @@ execution = client.durable.start(
 )
 print(execution.id, execution.status)
 
-execution = client.durable.get(
+owner_client = VolcanoClient(
+    api_url="https://api.volcano.dev",
+    anon_key="your-anon-key",
+    access_token="your-platform-user-token",
+)
+execution = owner_client.durable.get(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
 )
 print(execution.is_terminal, execution.result)
 
-executions = client.durable.list(
+executions = owner_client.durable.list(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", status="running"
 )
 print(executions.total, executions.has_more)
 
-client.durable.stop(
+owner_client.durable.stop(
     "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
 )
 
@@ -239,18 +244,18 @@ A function's own response, HTTP 403, or a network failure never triggers this re
 Anonymous and service keys do not refresh.
 
 `durable.start()` begins an execution of a deployed durable function and returns
-a handle rather than a result: an execution can run for hours, so its result is
-read back with `durable.get()`. It takes the credential `functions.invoke()`
+a handle rather than a result: an execution can run for up to 366 days, so its
+result is read back with `durable.get()`. It takes the credential `functions.invoke()`
 takes, and is the only durable operation an application credential may perform.
 An `execution_name` makes the start idempotent — starting again under the same
 name returns the execution that already exists rather than beginning a second
 one, and is charged once.
 
 `durable.get()`, `durable.list()` and `durable.stop()` are owner-scoped and need
-the project's own platform token, because an execution is addressed by its id
-alone and an anonymous key is held by everyone who loads the page. Neither an
-auth-user session from `sign_in()` nor a service key is accepted -- the routes
-take a user token, and anything else is answered 401. Poll them from a backend.
+the project owner's platform user token, because an execution is addressed by
+its id alone and an anonymous key is held by everyone who loads the page.
+Auth-user sessions from `sign_in()`, anonymous keys, service keys, and project
+access tokens are not accepted. Poll them from a trusted backend.
 `get()` carries `result` once the execution has succeeded and `error` when it
 failed; `result_expired` separates a result the platform has discarded from a
 function that returned nothing. `is_terminal` reports whether the execution has
@@ -290,6 +295,31 @@ def handler(event, ctx):
     return {"charged": charge["id"], "packed": packed.results}
 ```
 
+Use the function name for its source directory and manifest entry:
+
+```text
+volcano/functions/order-pipeline/
+├── main.py
+└── requirements.txt
+```
+
+```text
+# volcano/functions/order-pipeline/requirements.txt
+volcano-sdk-python
+```
+
+```yaml
+# volcano-config.yaml
+version: 1
+project:
+  name: my-app
+functions:
+  - name: order-pipeline
+    kind: durable
+```
+
+The decorator defines handler behavior. The manifest declaration makes the function discoverable by `volcano durable deploy`.
+
 Every context operation is checkpointed: what finished is recorded, and a
 resumed execution replays that recorded outcome instead of doing the work again.
 That is the one rule the handler has to respect — the code between operations
@@ -331,6 +361,20 @@ nothing while it waits. Running the handler anywhere durable execution does not
 exist raises `DurableRuntimeMissingError` rather than an import error from an
 unfamiliar package.
 
+Run the same handler through the local durable engine:
+
+```bash
+volcano start
+volcano durable deploy --all
+volcano durable start order-pipeline --input '{"order_id":"order-9"}'
+```
+
+Local waits resolve immediately by default while preserving checkpoint and replay
+behavior. Set `LOCAL_DURABLE_REAL_TIME=true` before `volcano start` when wait
+timing must match the deployed function. Local executions persist across
+`volcano stop` and `volcano start`. Volcano does not expose externally completed
+callbacks; use `ctx.wait_until` to poll application state instead.
+
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/docs/README.md

@@ -130,6 +130,6 @@ See [Realtime](./realtime.md) for broadcasts, presence, database changes, and sh
 
 See [Authentication](./authentication.md) for account, session, email, and OAuth workflows.
 
-See [Functions](./functions.md) for invocation identity, response values, and error handling.
+See [Functions](./functions.md) for standard invocation, durable execution, local durable development, and error handling.
 
 See [Versions and compatibility](./versions.md) for runtime support, upgrades, and restoring a tested dependency set.

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/docs/functions.md

@@ -63,3 +63,83 @@ A function's own HTTP 404 does not trigger another invocation.
 Network failures do not establish whether a function ran; do not blindly retry operations with side effects.
 
 Invalid invocation arguments and malformed successful resolution responses can raise `ValueError` or `TypeError`.
+
+## Start and follow a durable execution
+
+A durable execution can run for up to 366 days. Starting one returns a handle instead of waiting for its result:
+
+```python
+handle = client.durable.start(
+    "charge-order",
+    {"order_id": "order-9"},
+    execution_name="order-9",
+)
+
+owner_client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+    access_token=os.environ["VOLCANO_PLATFORM_TOKEN"],
+)
+execution = owner_client.durable.get(project_id, "charge-order", handle.id)
+page = owner_client.durable.list(project_id, "charge-order", status="running")
+owner_client.durable.stop(project_id, "charge-order", handle.id)
+```
+
+`start()` accepts the same active session, service key, or anonymous key as `functions.invoke()`. It is the only durable operation available to application credentials. An execution name makes a start idempotent.
+
+`get()`, `list()`, and `stop()` are owner-scoped. Call them from a trusted backend with the project owner's platform user token. Auth-user sessions, anonymous keys, service keys, and project access tokens are not accepted. `stop()` returns after the stop request is accepted, so poll `get()` until `is_terminal` is true.
+
+## Write a durable function
+
+Use `volcano_sdk.durable_authoring` in a durable function running on `python3.13` or `python3.14`:
+
+```python
+from volcano_sdk.durable_authoring import durable
+
+
+@durable
+def handler(event, ctx):
+    charge = ctx.step("charge", lambda scope: charge_card(event["order_id"]))
+    ctx.wait("settle", "30s")
+    return {"charge_id": charge["id"]}
+```
+
+Place the handler and its dependency file under the function name:
+
+```text
+volcano/functions/charge-order/
+├── main.py
+└── requirements.txt
+```
+
+```text
+# volcano/functions/charge-order/requirements.txt
+volcano-sdk-python
+```
+
+Declare the same name as durable in `volcano-config.yaml`; the decorator does not register the function with the CLI:
+
+```yaml
+version: 1
+project:
+  name: my-app
+functions:
+  - name: charge-order
+    kind: durable
+```
+
+Volcano records each context operation. Resumed executions replay recorded results instead of repeating completed work. Keep changing decisions inside `ctx.step()`. Use `ctx.wait_until()` to poll application state. Volcano does not expose externally completed callbacks.
+
+## Run durable functions locally
+
+Deploy and start the same handler through the local durable engine:
+
+```bash
+volcano start
+volcano durable deploy --all
+volcano durable start charge-order --input '{"order_id":"order-9"}'
+```
+
+Local waits resolve immediately by default while preserving checkpoint and replay behavior. Set `LOCAL_DURABLE_REAL_TIME=true` before `volcano start` when wait timing must match the deployed function. Local executions persist across `volcano stop` and `volcano start`.
+
+Running a decorated handler directly in a Python process still needs the optional test runtime: `python -m pip install 'volcano-sdk-python[durable]'`.

volcano_sdk_python-0.13.2/maintainers/mutation-testing.md

@@ -0,0 +1,45 @@
+# Mutation testing
+
+`uv run --locked poe quality` runs all native checks and mutates every changed
+handwritten runtime module plus the lock acquisition, guard, renewal, and worker
+modules. CI uses the same `checks` and `mutation` tasks in separate jobs, then
+requires both through `Quality Gate`. The weekly `poe mutation-full` task audits
+every handwritten runtime module without a debt baseline.
+
+Mutmut's [native configuration](https://mutmut.readthedocs.io/en/latest/) lives
+in `pyproject.toml`; it excludes only the generated OpenAPI client. Mutmut can
+select modules by name but has no Git-changed-module option and returns success
+when mutants survive. `scripts/mutation.sh` selects module names from Git and
+`scripts/mutation_results.py` reads only those modules' native metadata. The
+report at `reports/mutation.json` distinguishes killed, statically invalid,
+surviving, uncovered, timed-out, crashed, interrupted, and missing results.
+A pytest internal error is a harness crash, not a killed mutant.
+The pinned Pyrefly check rejects type-invalid realtime and auth mutants before pytest;
+the report counts these as `type_checked`, separately from test-killed mutants.
+Surviving, uncovered, timed-out, crashed, and incomplete mutants still fail.
+Mutmut passes pytest `-x` so a selected test's first assertion failure kills the
+mutant before a later selected test can hang on the same defect. Mutants that
+hang before any failure remain timeouts and fail separately.
+The runner rebuilds mutmut's native test-selection cache for each gate so newly
+added tests are included. Direct mutmut runs also watch Python test files for
+cache invalidation.
+The runner uses one mutmut child at a time because competing async mutant
+processes can time out tests that kill the same mutant when run alone.
+Mutmut uses its native forkserver isolation because forking from a process that
+has already run asyncio tests can crash a worker before its tests report a result.
+The mutation runner sets `NO_PROXY=*` for its hermetic transport tests because
+macOS system-proxy discovery can abort after a fork with active threads.
+The pinned pytest-order plugin runs bounded callback and presence assertions
+first when mutmut's unordered test selection could otherwise reach a blocked test.
+
+The full audit runs mutmut once across the entire source tree. It reports any
+surviving mutants without treating them as an approved baseline. Equivalent
+mutants require a reviewed, exact exception before a gate can accept them.
+
+Ruff, Mypy, Basedpyright, pytest, and Tox tasks pass `pyproject.toml`
+explicitly. Their documented config-file precedence can otherwise select a
+new local config before the checked-in policy:
+[Ruff](https://docs.astral.sh/ruff/configuration/),
+[Mypy](https://mypy.readthedocs.io/en/stable/command_line.html),
+[pytest](https://docs.pytest.org/en/stable/reference/customize.html),
+[Tox](https://tox.wiki/en/latest/man/tox.1.html).

volcano_sdk_python-0.13.2/maintainers/quality-exceptions.json

@@ -0,0 +1,20 @@
+[
+  {
+    "rule": "S603",
+    "scope": "scripts/generate_openapi.py:generate",
+    "rationale": "The command invokes the current Python interpreter with an argument list and no shell. The output path is passed as data.",
+    "evidence": "scripts/generate_openapi.py:52-70; the executable is sys.executable and all command switches are literals.",
+    "approved_by": "swkeever",
+    "approved_at": "2026-08-27",
+    "approval_evidence": "Original suppression introduced in commit 95ea362b and merged by swkeever in PR #1 on 2026-08-27."
+  },
+  {
+    "rule": "pytest.filterwarnings",
+    "scope": "tests/unit/test_durable_authoring.py:pytestmark",
+    "rationale": "The AWS durable local test runner calls asyncio.iscoroutinefunction, deprecated in Python 3.14. This exact upstream warning does not originate in SDK code; all other warnings remain errors.",
+    "evidence": "The module-scoped marker was introduced in commit f97aeee6 (PR #133) with its upstream-runner rationale at tests/unit/test_durable_authoring.py:48-56.",
+    "approved_by": "subnetmarco",
+    "approved_at": "2026-09-19",
+    "approval_evidence": "Existing filter shipped in PR #133, merged by subnetmarco on 2026-09-19."
+  }
+]

{volcano_sdk_python-0.13.0 → volcano_sdk_python-0.13.2}/maintainers/quality-policy.lock.json

@@ -34,6 +34,15 @@
           "reportUnusedCallResult": "error",
           "root": "tests/unit/test_state.py"
         },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportImplicitStringConcatenation": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "reportUnusedCallResult": "error",
+          "root": "tests/unit/test_realtime.py"
+        },
         {
           "reportAny": "error",
           "reportExplicitAny": "error",
@@ -90,6 +99,54 @@
           "reportUnusedCallResult": "error",
           "root": "tests/package"
         },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_realtime_callback_boundaries.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_realtime_cleanup_boundaries.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_realtime_connection_boundaries.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_realtime_delivery_boundaries.py"
+        },
+        {
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_realtime_input_boundaries.py"
+        },
+        {
+          "extraPaths": [
+            ".",
+            "src",
+            "tests/unit",
+            "features"
+          ],
+          "reportAny": "error",
+          "reportExplicitAny": "error",
+          "reportInvalidCast": "error",
+          "reportUnannotatedClassAttribute": "error",
+          "root": "tests/unit/test_mutation_results.py"
+        },
         {
           "extraPaths": [
             ".",
@@ -140,6 +197,7 @@
       "reportUnnecessaryTypeIgnoreComment": "error",
       "reportUnreachable": "error",
       "reportUnsafeMultipleInheritance": "error",
+      "reportUnusedCallResult": "error",
       "reportUnusedParameter": "error",
       "stubPath": "typings",
       "typeCheckingMode": "strict",
@@ -188,19 +246,35 @@
         "openapi-python-client.yaml",
         "README.md"
       ],
+      "cache_invalidation_files": [
+        "tests/**/*.py"
+      ],
       "do_not_mutate": [
         "src/volcano_sdk/_generated/*"
       ],
       "on_dependency_change": "rerun",
+      "process_isolation": "forkserver",
       "pytest_add_cli_args": [
         "-c",
-        "pyproject.toml"
+        "pyproject.toml",
+        "-x"
       ],
       "pytest_add_cli_args_test_selection": [
         "tests/unit"
       ],
       "source_paths": [
         "src/volcano_sdk"
+      ],
+      "type_check_command": [
+        "pyrefly",
+        "check",
+        "--output-format=json",
+        "src/volcano_sdk/realtime.py",
+        "src/volcano_sdk/auth.py",
+        "src/volcano_sdk/storage.py",
+        "src/volcano_sdk/functions.py",
+        "src/volcano_sdk/database.py",
+        "src/volcano_sdk/_function_resolution.py"
       ]
     },
     "mypy": {
@@ -275,7 +349,10 @@
             }
           ]
         },
-        "coverage": "uv run --locked --isolated --python 3.12 pytest -c pyproject.toml tests/unit -q --cov --cov-config=pyproject.toml --cov-report=term-missing --cov-report=json:reports/coverage.json --junitxml=reports/coverage-unit.xml",
+        "coverage": {
+          "interpreter": "bash",
+          "shell": "set -euo pipefail\nreport_dir=\"$(mktemp -d)\"\ntrap 'rm -rf \"$report_dir\"' EXIT\ntest_status=0\nuv run --locked --isolated --python 3.12 pytest -c pyproject.toml tests/unit -q --cov --cov-config=pyproject.toml --cov-report=term-missing --cov-report=json:\"$report_dir/coverage.json\" --junitxml=\"$report_dir/unit.xml\" || test_status=$?\nmkdir -p reports\nif test -s \"$report_dir/coverage.json\"; then\n  mv \"$report_dir/coverage.json\" reports/coverage.json\nelse\n  echo 'pytest-cov did not write a coverage report' >&2\n  if [[ $test_status -eq 0 ]]; then test_status=1; fi\nfi\nif test -s \"$report_dir/unit.xml\"; then\n  mv \"$report_dir/unit.xml\" reports/coverage-unit.xml\nelse\n  echo 'pytest did not write a JUnit report' >&2\n  if [[ $test_status -eq 0 ]]; then test_status=1; fi\nfi\nexit \"$test_status\"\n"
+        },
         "format-check": "ruff format --check --config pyproject.toml .",
         "generated": "python -m scripts.check_openapi",
         "lint": "ruff check --config pyproject.toml .",
@@ -294,7 +371,10 @@
           "checks",
           "mutation"
         ],
-        "test": "pytest -c pyproject.toml tests/unit -q --junitxml=reports/unit.xml",
+        "test": {
+          "interpreter": "bash",
+          "shell": "set -euo pipefail\nreport_dir=\"$(mktemp -d)\"\ntrap 'rm -rf \"$report_dir\"' EXIT\ntest_status=0\npytest -c pyproject.toml tests/unit -q --junitxml=\"$report_dir/unit.xml\" || test_status=$?\nmkdir -p reports\nif test -s \"$report_dir/unit.xml\"; then\n  mv \"$report_dir/unit.xml\" reports/unit.xml\nelse\n  echo 'pytest did not write a JUnit report' >&2\n  if [[ $test_status -eq 0 ]]; then test_status=1; fi\nfi\nexit \"$test_status\"\n"
+        },
         "types": [
           "mypy",
           "basedpyright"