volcano-sdk-python 0.9.3__tar.gz → 0.10.0__tar.gz

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

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

{volcano_sdk_python-0.9.3 → volcano_sdk_python-0.10.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.0](https://github.com/Kong/volcano-sdk-python/compare/v0.9.4...v0.10.0) (2026-09-19)
+
+
+### Features
+
+* **durable:** start, follow and author durable executions ([#133](https://github.com/Kong/volcano-sdk-python/issues/133)) ([f97aeee](https://github.com/Kong/volcano-sdk-python/commit/f97aeee64760d9c4b5458199b5692f5811b5a840))
+
+## [0.9.4](https://github.com/Kong/volcano-sdk-python/compare/v0.9.3...v0.9.4) (2026-09-18)
+
+
+### Bug Fixes
+
+* **functions:** preserve cached resolution error metadata ([#176](https://github.com/Kong/volcano-sdk-python/issues/176)) ([b83c2de](https://github.com/Kong/volcano-sdk-python/commit/b83c2deb156fbfe8f1212c21f0540f2cd6fdbb13))
+
 ## [0.9.3](https://github.com/Kong/volcano-sdk-python/compare/v0.9.2...v0.9.3) (2026-09-18)
 
 

{volcano_sdk_python-0.9.3 → volcano_sdk_python-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.9.3
+Version: 0.10.0
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -16,8 +16,8 @@ Requires-Python: >=3.11
 Requires-Dist: attrs>=26.1.0
 Requires-Dist: centrifuge-python<0.7.0,>=0.6.0
 Requires-Dist: httpx<0.29.0,>=0.28.1
-Requires-Dist: python-dateutil<3.0.0,>=2.9.0.post0
-Requires-Dist: typing-extensions>=4.15.0
+Provides-Extra: durable
+Requires-Dist: aws-durable-execution-sdk-python<3.0.0,>=2.0.0; extra == 'durable'
 Description-Content-Type: text/markdown
 
 # Volcano Python SDK
@@ -26,6 +26,9 @@ Use the Volcano Python SDK to access authentication, databases, storage,
 functions, locks, logs, and realtime events. Requires Python 3.11 or later.
 
 Start with the [Python quickstart](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md).
+See the [functions guide](https://github.com/Kong/volcano-sdk-python/blob/main/docs/functions.md) for invocation identity and response handling.
+
+See [Authentication](https://github.com/Kong/volcano-sdk-python/blob/main/docs/authentication.md) for account, session, email, and OAuth workflows.
 
 ## Install
 
@@ -54,13 +57,15 @@ client = VolcanoClient(
 
 sign_up = client.auth.sign_up(
     email="new-user@example.com",
-    password="secret",
+    password="correct-horse-battery-staple",
     metadata={"display_name": "New User"},
 )
 if sign_up.confirmation_required:
     print(sign_up.message)
 
-session = client.auth.sign_in(email="user@example.com", password="secret")
+session = client.auth.sign_in(
+    email="user@example.com", password="correct-horse-battery-staple"
+)
 current_session = client.auth.get_session()
 assert current_session == session
 
@@ -68,7 +73,7 @@ user = client.auth.get_user()
 assert user.id == session.user_id
 
 updated_user = client.auth.update_user(
-    password="new-secret",
+    password="new-correct-horse-battery-staple",
     metadata={"display_name": "Grace", "avatar": None},
 )
 assert updated_user.id == session.user_id
@@ -79,6 +84,27 @@ function = client.functions.invoke(
 )
 print(function.status, function.version, function.data)
 
+execution = client.durable.start(
+    "order-pipeline",
+    {"order_id": 4417},
+    execution_name="order-4417",
+)
+print(execution.id, execution.status)
+
+execution = client.durable.get(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+print(execution.is_terminal, execution.result)
+
+executions = client.durable.list(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", status="running"
+)
+print(executions.total, executions.has_more)
+
+client.durable.stop(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+
 # Project logs use a control-plane project token, not this end-user session.
 logs_client = VolcanoClient(
     anon_key="ak_your_anon_key", access_token="vpat_your_project_token"
@@ -218,7 +244,7 @@ The request goes to the function's own domain rather than to `api_url`, so an
 egress rule that allows only the API host will block it; the resolved endpoint
 is cached for the lifetime the platform gives it. Deployments with no public
 function domain invoke through the API host instead.
-It uses the active user session when present, then a configured service key,
+It uses the current session token, including a supplied `access_token`, then a configured service key,
 then the anonymous key. An anonymous key can invoke a public function without a
 user session; the function receives no user identity. The immutable result
 includes the response body, status, headers, and `X-Volcano-Version`. The body
@@ -227,7 +253,6 @@ JSON arrays become immutable tuples. Invalid JSON is returned as text. A
 function's own non-2xx response is returned when Volcano confirms it ran;
 non-success platform HTTP responses raise typed SDK errors.
 
-
 Function resolution and invocation recover from a platform HTTP 401 before dispatch:
 the SDK refreshes the captured session and retries the rejected request once.
 Concurrent calls share successful recovery. Replacing or signing out that session
@@ -235,6 +260,91 @@ prevents replay under another identity. The call preserves its original payload
 A function's own response, HTTP 403, or a network failure never triggers this retry.
 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()`
+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.
+`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
+stopped changing, and counts `unknown` — the status the platform writes for an
+outcome it could not determine — as finished. `stop()` is accepted rather than
+awaited: what it returns is the execution read back after asking, often still
+`running`, so poll `get()` to see it reach `stopped`. Repeating a stop is safe.
+
+## Write a durable function
+
+`volcano_sdk.durable_authoring` is what the durable function itself is written
+against. It needs a durable-capable runtime — `python3.13` or `python3.14` — and
+`volcano-sdk-python` in the function's `requirements.txt`. Nothing else: the runtime
+that does the checkpointing is installed by Volcano when it builds a function
+deployed as durable.
+
+Importing this module never requires that runtime, so a standard function or a
+script that imports it still installs and runs; the handler fails only when it
+is actually invoked somewhere durable execution does not exist.
+
+```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")
+
+    packed = ctx.map(
+        event["items"],
+        lambda item, item_ctx, index: item_ctx.step("pack-item", lambda s: pack(item)),
+        "pack",
+    )
+
+    return {"charged": charge["id"], "packed": packed.results}
+```
+
+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
+runs again on every resume, so it has to reach the same operations in the same
+order. Keep decisions that must not change inside a `step`, and do not branch on
+the clock or a random value.
+
+| Operation | What it does |
+|---|---|
+| `ctx.step(name, fn, retry=..., at_most_once=...)` | Runs one atomic operation and records its result. `retry=False` fails on the first error; `RetryOptions` sets attempts and backoff. |
+| `ctx.wait(name, duration)` | Suspends the execution. `"30s"`, `"2h"`, `"1m30s"`, a whole number of seconds, or `{"hours": 2}`. |
+| `ctx.wait_until(check, options, name=None)` | Polls your own state until `options.until` holds, suspending between checks. `options.initial_state` is required. |
+| `ctx.map(items, fn, name=None, options=None)` | Runs the same work over every item, each in its own child context. |
+| `ctx.parallel(branches, name=None, options=None)` | Runs independent branches at the same time. |
+| `ctx.child(name, fn)` | Groups operations under one recorded context. |
+| `ctx.log` | The execution's logger, suppressed while an operation is replayed. |
+
+`ctx.map` and `ctx.parallel` both return a batch result: `items` (the items that
+finished, each with `index`, `status`, `result`, `error`), `results`, `errors`,
+`succeeded`, `failed`, `completed`, `completion_reason`, and `throw_if_failed()`.
+`options.min_succeeded` ends the batch while other items are still running, and
+those are not in the result — whether the platform can reproduce an in-flight
+item when the execution resumes is not guaranteed, so a handler that branched on
+one would take a different path on the replay. `completion_reason` is how to tell
+why the batch ended.
+
+Durable operations are synchronous here — there is no `await`, and a step's own
+function is handed a scope carrying `log` and `attempt`. A wait is held by the
+platform rather than by your code, so an execution suspended for an hour costs
+nothing while it waits. Running the handler anywhere durable execution does not
+exist raises `DurableRuntimeMissingError` rather than an import error from an
+unfamiliar package.
+
 `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.
@@ -326,7 +436,9 @@ The signup acknowledgement is identical for new and existing email addresses. Pa
 
 ```python
 result = client.auth.sign_up(
-    email="new-user@example.com", password="secret", sign_in_when_allowed=True
+    email="new-user@example.com",
+    password="correct-horse-battery-staple",
+    sign_in_when_allowed=True,
 )
 session = result.session  # None when no follow-up sign-in ran.
 ```
@@ -342,21 +454,23 @@ request. It is cached data, not proof of authentication; use `auth.get_user()`
 to fetch the server-validated profile. Existing three-field `Session` construction
 still works, with `user=None`. An adopted snapshot must have the same user ID.
 Successful `get_user()`, `update_user()`, `convert_anonymous()`, and
-`confirm_email_change()` calls update that local snapshot without changing tokens
-or emitting an auth-state event. Previously returned sessions remain immutable.
+`confirm_email_change()` calls update that local snapshot. Automatic HTTP 401 recovery
+can rotate credentials and emit `TOKEN_REFRESHED`; the profile update itself does not. Previously returned sessions remain immutable.
 Profile identity checks compare UUID values; the session retains its original
 user ID spelling, including in the cached snapshot.
 
 `get_user()` sends the active access token to Volcano and returns an immutable, server-validated
 profile with the complete public AuthUser fields. Profile timestamps are timezone-aware `datetime`
 values, and nested user and application metadata are immutable. The request updates the cached
-profile without changing credentials. If another authentication operation replaces the session
+profile without changing credentials unless HTTP 401 recovery requires a refresh.
+Successful recovery rotates credentials and emits `TOKEN_REFRESHED`. If another authentication operation replaces the session
 while the request is in flight, `get_user()` raises `SessionChangedError` instead of returning a
 profile for stale credentials.
 
 `update_user()` updates the current user's password, metadata, or both. Metadata is a shallow patch:
 omitted keys remain unchanged, and setting a key to `None` removes it. The method returns the same
-immutable profile type as `get_user()` and updates the cached profile without changing credentials.
+immutable profile type as `get_user()` and updates the cached profile without changing credentials unless HTTP 401 recovery requires a refresh.
+Successful recovery rotates credentials and emits `TOKEN_REFRESHED`.
 It also rejects a response if another authentication operation replaces the session while the
 update is in flight.
 
@@ -444,7 +558,9 @@ hosted_url = client.auth.get_hosted_auth_url(
 ```
 
 Store `hosted_state` in the user's signed server-side session before redirecting to `hosted_url`.
-After parsing the returned fragment into a `Session`, validate and adopt it atomically:
+In the callback, atomically fetch and delete the stored state before validation,
+even if validation or adoption fails. Reject a missing or already-consumed state.
+After parsing the returned fragment into a `Session`, validate and adopt it:
 
 ```python
 session = client.auth.adopt_hosted_auth_session(
@@ -473,8 +589,9 @@ authorization_url = client.auth.sign_in_with_oauth(
 ```
 
 Store `oauth_state` in the user's signed server-side session, then redirect the user to the returned
-URL. In the callback, pass the returned and stored states to the SDK so it rejects login CSRF before
-exchanging the one-time code:
+URL. In the callback, atomically fetch and delete the stored nonce as `stored_oauth_state`;
+reject a missing or already-consumed nonce. Pass the returned and consumed states to
+the SDK so it rejects login CSRF before exchanging the one-time code:
 
 ```python
 session = client.auth.exchange_oauth_code(
@@ -568,9 +685,11 @@ Revoke one session by ID:
 client.auth.delete_session(session_id="00000000-0000-4000-8000-000000000099")
 ```
 
-The request uses the current access token. Deleting that token's own session clears local
-credentials, including when the request outcome is uncertain; deleting another session preserves
-them. If another authentication operation replaces the session before deletion finishes, the method
+The request uses the current access token. When its JWT contains a readable UUID `session_id`,
+deleting that session clears local credentials even if the request outcome is uncertain.
+Without that identifier, the SDK cannot recognize self-deletion. Deleting another session does not
+itself clear local state. HTTP 401 recovery can rotate credentials and emit `TOKEN_REFRESHED`;
+a server-rejected refresh clears the captured session before the operation raises. If another authentication operation replaces the session before deletion finishes, the method
 raises `SessionChangedError` instead of clearing the replacement or acknowledging a stale result.
 
 Create an anonymous account and make its tokens the current session:
@@ -582,12 +701,12 @@ session = client.auth.sign_in_anonymously(metadata={"device": "mobile"})
 Anonymous sign-ins must be enabled for the project. Convert the account before signing out if the
 user needs to recover it later.
 
-Attach email credentials without changing the anonymous user's ID or current session:
+Attach email credentials while preserving the anonymous user's ID:
 
 ```python
 user = client.auth.convert_anonymous(
     email="user@example.com",
-    password="secure-password",
+    password="a-long-example-password-2026",
     metadata={"display_name": "Ada"},
 )
 ```
@@ -599,7 +718,7 @@ Set a new password with the recovery token from that email:
 ```python
 client.auth.reset_password(
     token="recovery-token",
-    new_password="new-secret",
+    new_password="new-correct-horse-battery-staple",
 )
 ```
 
@@ -610,10 +729,13 @@ when the reset flow completes.
 To start with only a supplied user access token, pass `access_token` to
 `VolcanoClient`. Construction makes no request and leaves `refresh_token`,
 `user_id`, and `user` as `None` until supplied or validated by the server.
-`get_user()` validates and caches the profile without changing credentials.
+`get_user()` validates and caches the profile without changing credentials unless HTTP 401 recovery requires a refresh.
+Successful recovery rotates credentials and emits `TOKEN_REFRESHED`.
 Without a refresh token, `refresh_session()` raises `AuthenticationError` and
-`sign_out()` revokes the server session using the access token and clears local state.
-Supply `refresh_token` with `access_token` to enable refresh. See the [token bootstrap example](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md#use-a-supplied-access-token).
+`sign_out()` clears local state and revokes the server session when the access JWT
+contains a readable UUID `session_id`.
+Supplied credentials require both a refresh token and an access JWT with a readable UUID
+`session_id` to enable refresh. See the [token bootstrap example](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md#use-a-supplied-access-token).
 
 Copy a complete native session into another client's memory:
 
@@ -638,7 +760,8 @@ assert client.auth.get_session() is refreshed
 ```
 
 On success, `refresh_session()` replaces the in-memory session and returns the immutable new
-snapshot. An authentication failure clears the session that initiated the request. Server and
+snapshot. An authentication rejection from the refresh endpoint clears the captured session.
+Missing refresh credentials, failed session-continuity checks, server errors, and
 transport failures preserve it, and a late response never replaces a newer session. The SDK does
 not persist sessions.
 
@@ -660,8 +783,8 @@ subscription.unsubscribe()
 Registration queues `INITIAL_SESSION`. It normally arrives before registration returns, but an
 existing notification dispatch may deliver it afterward. Successful session creation, refresh, and
 local clearing emit `SIGNED_IN`, `TOKEN_REFRESHED`, and `SIGNED_OUT`. Callbacks are delivered locally
-in transition order after the state lock is released, and callback failures cannot interrupt auth
-operations. Unsubscribing prevents queued and future delivery; a callback already selected for
+in transition order after the state lock is released. Ordinary callback `Exception` failures are
+isolated; exceptions such as `KeyboardInterrupt` propagate after the session transition has committed. Unsubscribing prevents queued and future delivery; a callback already selected for
 delivery may finish after `unsubscribe()` returns. The SDK does not broadcast between processes or
 persist sessions.
 
@@ -673,8 +796,10 @@ assert client.auth.get_session() is None
 ```
 
 Sign-out uses the refresh token directly when the SDK received both credentials together from
-sign-in or a validated refresh. Supplied credentials use the access-token session; on HTTP 401,
-the SDK can refresh once and revoke that same session without adopting the renewed credentials.
+sign-in or a validated refresh. Supplied credentials use the access-token session when its JWT
+contains a readable UUID `session_id`; on HTTP 401, the SDK can refresh once and revoke that
+same session without adopting the renewed credentials. Without that identifier, sign-out uses
+the supplied refresh token, or only clears local state if no refresh token is available.
 Calling `sign_out()` without a session succeeds without a request. A revocation failure is raised
 after the captured local session is cleared. Sign-out waits for an already-running refresh and uses its validated credentials.
 Later refresh attempts raise `SessionChangedError` without a request. Concurrent sign-out calls
@@ -811,6 +936,29 @@ included. Tune a channel's batching with `fetch_batch_window_ms` and
 without querying their rows. Pass `None` to `set_database_name()` to disable
 row fetching for every channel.
 
+## Dependencies
+
+Installing `volcano-sdk-python` pulls in three packages, plus their own transitive
+dependencies:
+
+| Package                                                            | Why                                        |
+| ------------------------------------------------------------------ | ------------------------------------------ |
+| [`httpx`](https://pypi.org/project/httpx/)                         | The HTTP client every request goes through |
+| [`attrs`](https://pypi.org/project/attrs/)                         | The generated client's models              |
+| [`centrifuge-python`](https://pypi.org/project/centrifuge-python/) | The realtime protocol client               |
+
+A durable function you deploy needs one more, and you do not install it:
+Volcano adds it when it builds the function.
+
+| Package                                                                                          | Why                                                                   |
+| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| [`aws-durable-execution-sdk-python`](https://pypi.org/project/aws-durable-execution-sdk-python/) | Checkpointing. `volcano_sdk.durable_authoring` is written on top of it |
+
+The `durable` extra installs it if you want it yourself — to run a durable
+handler in your own tests, or to pin a version, since the build leaves a
+function that pins the runtime exactly as it is. A function's `requirements.txt`
+does not need it otherwise.
+
 ## Compatibility
 
 CI tests the SDK on Python 3.11 and 3.14. Its public facade is intentionally