volcano-sdk-python 0.7.2__tar.gz → 0.8.0__tar.gz

volcano_sdk_python-0.8.0/.github/workflows/lint-docs.yml

@@ -0,0 +1,16 @@
+name: Lint docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/lint-docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    uses: Kong/volcano-docs/.github/workflows/lint-docs.yml@2eed9e93cae0b070f57788e7c270ccfbb4cd4579
+    with:
+      path: docs

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

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

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0](https://github.com/Kong/volcano-sdk-python/compare/v0.7.3...v0.8.0) (2026-09-18)
+
+
+### Features
+
+* **locks:** add recoverable acquisition with caller-owned tokens ([#160](https://github.com/Kong/volcano-sdk-python/issues/160)) ([ba0f261](https://github.com/Kong/volcano-sdk-python/commit/ba0f26149d7ca33b9043bb1932ad10b95e43073e))
+
+## [0.7.3](https://github.com/Kong/volcano-sdk-python/compare/v0.7.2...v0.7.3) (2026-09-17)
+
+
+### Bug Fixes
+
+* **auth:** refresh rejected profile requests within their session ([#157](https://github.com/Kong/volcano-sdk-python/issues/157)) ([534e5e2](https://github.com/Kong/volcano-sdk-python/commit/534e5e270c94cad758779d98714b217263537dc0))
+
 ## [0.7.2](https://github.com/Kong/volcano-sdk-python/compare/v0.7.1...v0.7.2) (2026-09-17)
 
 

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.7.2
+Version: 0.8.0
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 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).
+
 ## Install
 
 ```shell
@@ -180,6 +182,13 @@ original error. `on_progress` runs after each successful part with cumulative
 uploaded bytes and the total size.
 `upload_part()` returns immutable part metadata and can safely retry the same
 part number to replace that part.
+Acquisition accepts caller-owned UUID `token` and `request_id` values and retries
+an ambiguous transport failure or HTTP 503 once with the same request and credential.
+Retain those IDs to recover an uncertain acquisition. Other lock methods accept
+`request_id`; block-scoped helpers forward initial IDs only to acquisition.
+See the [lock guide](https://github.com/Kong/volcano-sdk-python/blob/main/docs/locks.md)
+for examples and fencing requirements.
+
 `locks.get()` returns immutable lock availability, expiry, and fencing-token
 state without acquiring the lock.
 Lock acquisition and renewal require an integer TTL from 5 seconds through 90 days.

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/README.md

@@ -3,6 +3,8 @@
 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).
+
 ## Install
 
 ```shell
@@ -158,6 +160,13 @@ original error. `on_progress` runs after each successful part with cumulative
 uploaded bytes and the total size.
 `upload_part()` returns immutable part metadata and can safely retry the same
 part number to replace that part.
+Acquisition accepts caller-owned UUID `token` and `request_id` values and retries
+an ambiguous transport failure or HTTP 503 once with the same request and credential.
+Retain those IDs to recover an uncertain acquisition. Other lock methods accept
+`request_id`; block-scoped helpers forward initial IDs only to acquisition.
+See the [lock guide](https://github.com/Kong/volcano-sdk-python/blob/main/docs/locks.md)
+for examples and fencing requirements.
+
 `locks.get()` returns immutable lock availability, expiry, and fencing-token
 state without acquiring the lock.
 Lock acquisition and renewal require an integer TTL from 5 seconds through 90 days.

volcano_sdk_python-0.8.0/docs/README.md

@@ -0,0 +1,84 @@
+---
+title: Python SDK
+description: Install the Volcano Python SDK and authenticate a user from a Python application.
+order: 1
+---
+
+Use `volcano-sdk-python` for authentication, database queries, storage, functions, logs, locks, and realtime events.
+REST calls are synchronous and raise typed exceptions on failure.
+Python 3.11 or later is required; CI tests Python 3.11 and 3.14.
+
+## Install the published package
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install volcano-sdk-python
+```
+
+The [PyPI distribution](https://pypi.org/project/volcano-sdk-python/) is named `volcano-sdk-python`.
+Import it as `volcano_sdk`.
+The package includes type information for mypy and other PEP 561-compatible checkers.
+
+## Sign in and read a profile
+
+Create a project, enable [email and password authentication](/platform/authentication/configuring-auth-methods), and create a user with a confirmed email when your project requires confirmation.
+Use that project's [anonymous key](/platform/authentication/security/anon-keys).
+Set `VOLCANO_ANON_KEY`, `VOLCANO_USER_EMAIL`, and `VOLCANO_USER_PASSWORD` in your environment.
+Set `VOLCANO_API_URL` only when using a different API endpoint, such as local mode.
+
+Save this as `quickstart.py`:
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+session = client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+try:
+    user = client.auth.get_user()
+    assert user.id == session.user_id
+    print(f"Signed in as {user.email}")
+finally:
+    client.auth.sign_out()
+```
+
+Run it with `python quickstart.py`.
+It signs in, fetches the server-validated profile, prints the user's email, revokes its refresh token, and clears the local session.
+An invalid email or password raises `AuthenticationError`; failed network requests raise `TransportError`.
+Both inherit from `VolcanoError` and are exported from `volcano_sdk`.
+
+## Keep authentication scoped to one user
+
+A client holds its current session in memory.
+Use a separate client for each independent user session; do not share one mutable client across users in a web server.
+`client.current_session` and `client.auth.get_session()` read the local immutable snapshot without a request.
+Use `client.auth.get_user()` when you need a server-validated profile.
+Successful profile operations update the cached user while preserving the current credentials.
+If `get_user()`, `update_user()`, `convert_anonymous()`, or `confirm_email_change()` receives an HTTP 401 and the session has a usable refresh token, the client refreshes once and retries with the original request values.
+These operations do not retry other HTTP failures or ambiguous network failures, and they never retry under a replacement session.
+
+`sign_up()` returns an acknowledgement without signing in by default.
+Pass `sign_in_when_allowed=True` to sign in only when the project does not require email confirmation.
+To adopt an existing session, pass a `Session` containing its access token, refresh token, and user ID to `client.auth.set_session()`.
+The SDK does not persist tokens for you.
+
+For operations that require a [service key](/platform/authentication/security/service-keys), pass `service_key` to the constructor in trusted server code.
+Keep service keys and user credentials out of source control and client applications.
+
+## Use the rest of the API
+
+The SDK repository contains [examples for every public facade](https://github.com/Kong/volcano-sdk-python#try-the-contract-facade), including database filters and mutations, resumable uploads, function invocation, log queries, lock guards, and realtime presence and database changes.
+Realtime uses an asynchronous lifecycle; follow those examples to connect and disconnect its channels.
+
+See [release notes](https://github.com/Kong/volcano-sdk-python/releases) for version changes and [GitHub issues](https://github.com/Kong/volcano-sdk-python/issues) to report a problem.
+Include the package version, Python version, and a minimal reproduction without credentials.
+
+See [Distributed locks](./locks.md) for acquisition recovery, renewal, and fencing.

volcano_sdk_python-0.8.0/docs/locks.md

@@ -0,0 +1,94 @@
+---
+title: Distributed locks
+description: Coordinate Python workers with project-scoped lock leases, renewal, and fencing tokens.
+order: 7
+---
+
+Acquire a project-scoped lease from trusted server code using a service key.
+Set `VOLCANO_ANON_KEY` and `VOLCANO_SERVICE_KEY` for the same project.
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    service_key=os.environ["VOLCANO_SERVICE_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+lease = client.locks.acquire("daily-report", ttl=30)
+try:
+    print("Lease acquired", lease.fencing_token)
+finally:
+    client.locks.release("daily-report", lease)
+```
+
+`acquire()` returns an immutable `LockLease` containing the key, ownership token, expiration, and fencing token.
+Release and renew using that lease; the ownership token identifies the holder.
+TTLs are integer seconds from 5 seconds through 90 days.
+A competing owner can cause `ConflictError`.
+
+## Renew or inspect a lease
+
+```python
+state = client.locks.get("daily-report")
+print(state.held, state.expires_at, state.fencing_token)
+
+lease = client.locks.acquire("daily-report", ttl=30)
+try:
+    lease = client.locks.renew("daily-report", lease, ttl=60)
+finally:
+    client.locks.release("daily-report", lease)
+```
+
+`get()` reports availability without acquiring the lock.
+`renew()` returns a new immutable lease, so retain its return value.
+
+## Renew for the duration of a block
+
+```python
+with client.locks.with_lock("daily-report", ttl=30) as guard:
+    print("Current fence", guard.lease.fencing_token)
+    if guard.lost:
+        raise RuntimeError("Lock ownership was lost")
+```
+
+The context manager renews in the background and attempts to release its latest lease on exit.
+`guard.lease` reads the latest lease; `guard.lost` checks ownership loss, and `guard.wait_lost(timeout=1.0)` waits up to one second for it.
+Stop protected work when ownership is lost.
+Use fencing tokens in the protected data store so an expired worker cannot overwrite work performed by a newer holder.
+Lease renewal alone cannot stop application code that is already running.
+
+If the block succeeds, a renewal failure is raised after cleanup.
+An exception from the block takes precedence.
+
+## Recover an abandoned lock
+
+`client.locks.force_release("daily-report")` removes the current lease without its ownership token.
+Use this only for administrative recovery with fencing enforced by the protected resource.
+
+## Recover an uncertain acquisition
+
+Acquisition retries a transport failure or HTTP 503 once with the same ownership
+token, request ID, key, TTL, and credential. Other HTTP errors are not retried.
+For recovery after that retry also fails, generate and retain identifiers before
+acquiring, then reuse them for the same acquisition attempt:
+
+```python
+from uuid import uuid4
+
+owner_token = str(uuid4())
+request_id = str(uuid4())
+lease = client.locks.acquire(
+    "daily-report", ttl=30, token=owner_token, request_id=request_id
+)
+```
+
+Caller-supplied UUID strings retain their exact spelling across retries and lease operations.
+Every lock method accepts `request_id`. `with_lock()` also accepts `token` and
+`request_id` for acquisition; its renewal and release calls use new request IDs.
+
+Use a new ownership token for a new lease after release or expiry. Keep ownership
+tokens private. A failed response does not prove the server failed to acquire;
+reuse the original token to recover the outcome rather than starting a new owner.

volcano_sdk_python-0.8.0/features/staged/auth-profile-refresh.feature

@@ -0,0 +1,10 @@
+Feature: SDK profile authentication recovery
+
+  @auth @SDK-AUTH-007
+  Scenario: A rejected profile read refreshes the session and caches the same user
+    Given an authenticated client
+    And the client replaces its access token with a rejected token
+    When the client loads its server-validated profile
+    Then the SDK operation succeeds
+    And the returned and cached profiles belong to the contract user
+    And the profile read replaces the rejected token for the same user

volcano_sdk_python-0.8.0/features/staged/locks-recovery.feature

@@ -0,0 +1,18 @@
+Feature: SDK lock recovery and lifecycle
+
+  @locks @SDK-LOCKS-002
+  Scenario: Caller-owned acquisition can be recovered and renewed
+    Given a service-role client
+    When the client recovers the contract lock with caller-owned tokens
+    Then the SDK operation succeeds
+    And recovery and renewal preserve the held lease until release
+
+  @locks @SDK-LOCKS-003
+  Scenario: Administrative release removes the current lease
+    Given a service-role client
+    When the client acquires and force releases the contract lock
+    Then the SDK operation succeeds
+    And the force-released lock is available
+    When the client reacquires the force-released contract lock
+    Then the SDK operation succeeds
+    And the replacement owner receives a higher fencing token

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/features/steps/sdk_contract_steps.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import time
 from typing import Any
+from uuid import uuid4
 
 from behave import given, then, when
 from broadcast_pause import verify_broadcast_pause
@@ -175,6 +176,7 @@ def replace_access_token(context: Any) -> None:
     )
 
 
+@then("the profile read replaces the rejected token for the same user")
 @then("the storage operation replaces the rejected token for the same user")
 @then("the database read replaces the rejected token for the same user")
 def read_replaced_token(context: Any) -> None:
@@ -187,6 +189,23 @@ def read_replaced_token(context: Any) -> None:
     assert session.user_id == world.fixture["user_id"]
 
 
+@when("the client loads its server-validated profile")
+def load_server_profile(context: Any) -> None:
+    world = _world(context)
+    world.record(world.client.auth.get_user)
+
+
+@then("the returned and cached profiles belong to the contract user")
+def profiles_belong_to_contract_user(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value.id == world.fixture["user_id"]
+    session = world.client.current_session
+    assert session is not None
+    assert session.user is not None
+    assert session.user["id"] == world.fixture["user_id"]
+
+
 @when("one client pauses delivery for 1 second and then resumes with the same handler")
 def pause_and_resume(context: Any) -> None:
     world = _world(context)
@@ -533,6 +552,103 @@ def released_lease_not_held(context: Any) -> None:
     assert world.last_outcome.value["released"] is True
 
 
+@when("the client recovers the contract lock with caller-owned tokens")
+def recover_lock(context: Any) -> None:
+    world = _world(context)
+
+    def operation() -> dict[str, Any]:
+        locks, key = world.service_client.locks, world.lock_key
+        token, request_id = str(uuid4()), str(uuid4())
+        lease = locks.acquire(key, ttl=30, token=token, request_id=request_id)
+        cleanup = world.register_lock_cleanup(key, lease)
+        recovered = locks.acquire(key, ttl=30, token=token, request_id=request_id)
+        held = locks.get(key, request_id=str(uuid4()))
+        renewed = locks.renew(key, recovered, ttl=60, request_id=str(uuid4()))
+        locks.release(key, renewed, request_id=str(uuid4()))
+        available = locks.get(key, request_id=str(uuid4()))
+        return {
+            "token": token,
+            "cleanup": cleanup,
+            "lease": lease,
+            "recovered": recovered,
+            "held": held,
+            "renewed": renewed,
+            "available": available,
+        }
+
+    world.record(operation)
+
+
+@then("recovery and renewal preserve the held lease until release")
+def recovered_lock_lifecycle(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    value = world.last_outcome.value
+    assert value["held"].held is True
+    assert value["available"].held is False
+    world.cleanup_callbacks.remove(value["cleanup"])
+    assert (
+        value["token"]
+        == value["lease"].token
+        == value["recovered"].token
+        == value["renewed"].token
+    )
+    assert value["lease"].fencing_token is not None
+    assert (
+        value["lease"].fencing_token
+        == value["recovered"].fencing_token
+        == value["held"].fencing_token
+        == value["renewed"].fencing_token
+    )
+
+
+@when("the client acquires and force releases the contract lock")
+def force_release_lock(context: Any) -> None:
+    world = _world(context)
+
+    def operation() -> object:
+        locks, key = world.service_client.locks, world.lock_key
+        lease = locks.acquire(key, ttl=30)
+        cleanup = world.register_lock_cleanup(key, lease)
+        locks.force_release(key, request_id=str(uuid4()))
+        return {"lease": lease, "cleanup": cleanup, "available": locks.get(key)}
+
+    world.record(operation)
+
+
+@then("the force-released lock is available")
+def force_released_lock_available(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value["available"].held is False
+    world.cleanup_callbacks.remove(world.last_outcome.value["cleanup"])
+
+
+@when("the client reacquires the force-released contract lock")
+def reacquire_force_released_lock(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    original = world.last_outcome.value["lease"]
+
+    def operation() -> object:
+        replacement = world.service_client.locks.acquire(world.lock_key, ttl=30)
+        world.register_lock_cleanup(world.lock_key, replacement)
+        return {"original": original, "replacement": replacement}
+
+    world.record(operation)
+
+
+@then("the replacement owner receives a higher fencing token")
+def replacement_lock_fence_increases(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    original = world.last_outcome.value["original"]
+    replacement = world.last_outcome.value["replacement"]
+    assert replacement.token != original.token
+    assert original.fencing_token is not None
+    assert replacement.fencing_token > original.fencing_token
+
+
 @given("two authenticated realtime clients")
 def two_realtime_clients(context: Any) -> None:
     world = _world(context)

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "volcano-sdk-python"
-version = "0.7.2"
+version = "0.8.0"
 description = "Official Python SDK for Volcano"
 readme = "README.md"
 requires-python = ">=3.11"

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.8.0}/src/volcano_sdk/_lock_guard.py

@@ -54,13 +54,16 @@ class LockGuard:
         *,
         ttl: int,
         started_at: float,
+        lease_started_at: float | None = None,
     ) -> None:
         """Track one acquired lease against its local monotonic deadline."""
         self._state_lock = threading.Lock()
         self._lease = lease
         self._ttl = ttl
         self._absolute_deadline = started_at + MAX_LOCK_LIFETIME_SECONDS
-        self._lease_deadline = min(started_at + ttl, self._absolute_deadline)
+        # A successful retry renews the TTL, not the maximum ownership lifetime.
+        lease_started_at = started_at if lease_started_at is None else lease_started_at
+        self._lease_deadline = min(lease_started_at + ttl, self._absolute_deadline)
         self._failure: Exception | None = None
         self._lost = threading.Event()