volcano-sdk-python 0.7.3__tar.gz → 0.9.0__tar.gz

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

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

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.9.0](https://github.com/Kong/volcano-sdk-python/compare/v0.8.0...v0.9.0) (2026-09-18)
+
+
+### Features
+
+* **auth:** add token bootstrap with server session continuity ([#159](https://github.com/Kong/volcano-sdk-python/issues/159)) ([0dd9512](https://github.com/Kong/volcano-sdk-python/commit/0dd9512e543e2713233b3632a16ffae0e8c69d1b))
+
+## [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)
 
 

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.7.3
+Version: 0.9.0
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -182,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.
@@ -586,6 +593,14 @@ Success returns `None`. The reset revokes the recovered account's existing sessi
 sign it in. The client keeps any unrelated local session unchanged; sign in with the new password
 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.
+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).
+
 Copy a complete native session into another client's memory:
 
 ```python
@@ -643,9 +658,13 @@ client.auth.sign_out()
 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.
 Calling `sign_out()` without a session succeeds without a request. A revocation failure is raised
-after the captured local session is cleared. A newer session established while sign-out is in
-flight remains current.
+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
+share one result. A separate sign-in or adoption remains current.
 
 Realtime is async. Channels wrap `centrifuge-python`; the underlying client and
 subscription objects are not part of the public API.

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.0}/README.md

@@ -160,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.
@@ -564,6 +571,14 @@ Success returns `None`. The reset revokes the recovered account's existing sessi
 sign it in. The client keeps any unrelated local session unchanged; sign in with the new password
 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.
+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).
+
 Copy a complete native session into another client's memory:
 
 ```python
@@ -621,9 +636,13 @@ client.auth.sign_out()
 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.
 Calling `sign_out()` without a session succeeds without a request. A revocation failure is raised
-after the captured local session is cleared. A newer session established while sign-out is in
-flight remains current.
+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
+share one result. A separate sign-in or adoption remains current.
 
 Realtime is async. Channels wrap `centrifuge-python`; the underlying client and
 subscription objects are not part of the public API.

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.0}/docs/README.md

@@ -51,7 +51,7 @@ finally:
 ```
 
 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.
+It signs in, fetches the server-validated profile, prints the user's email, revokes its server session, 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`.
 
@@ -73,6 +73,41 @@ 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 a supplied access token
+
+For a server request that already carries a user's access token, create a client for that request:
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+
+def load_request_user(access_token: str):
+    client = VolcanoClient(
+        anon_key=os.environ["VOLCANO_ANON_KEY"],
+        access_token=access_token,
+    )
+    return client.auth.get_user()
+```
+
+Call this helper from your request handler with the bearer token from that request.
+For a Volcano function, use the access token in `event["__volcano_auth"]["access_token"]` supplied for that invocation.
+The helper validates the token with Volcano before returning the user.
+
+Once a user identity has been validated, a refresh response for another user is rejected and leaves the current credentials unchanged.
+Construction makes no request and does not persist credentials.
+The initial snapshot has `refresh_token=None`, `user_id=None`, and `user=None`.
+A successful profile read fills in the validated identity and cached user while retaining the supplied access token.
+Without a refresh token, an HTTP 401 remains an authentication error, `refresh_session()` raises `AuthenticationError`, and `sign_out()` revokes the server session identified by the access token before clearing local state.
+Refresh must preserve the server session identified by the access JWT, even before a profile is loaded. A different session is rejected, including another session for the same user. Supplied credentials need a readable session identifier to refresh, even when you provide a user profile or load it from the server. Profile data does not prove that access and refresh tokens belong together.
+For supplied credentials, sign-out revokes the access-token session. On HTTP 401, it can refresh once and revoke that same session without adopting the renewed credentials locally.
+When the SDK received both credentials together from sign-in or a validated refresh, it uses the refresh token directly, even if access has expired.
+Sign-out joins an existing refresh and prevents later refresh attempts for that session. Concurrent sign-outs share one result; a separate sign-in or adoption remains current.
+Pass `refresh_token` alongside `access_token` when the client should refresh that session.
+A revocation failure is reported after local clearing; it does not prove that copied tokens are invalid.
+Adopting a session with `set_session()` still requires complete credentials and identity.
+
 ## 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.
@@ -80,3 +115,5 @@ Realtime uses an asynchronous lifecycle; follow those examples to connect and di
 
 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.9.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.7.3 → volcano_sdk_python-0.9.0}/features/contract_support.py

@@ -116,6 +116,7 @@ class ContractWorld:
         self.last_outcome: Outcome | None = None
         self.previous_session: Session | None = None
         self.signed_out_session: Session | None = None
+        self.bootstrap_cleanup: Callable[[], None] | None = None
         self.auth_state_events: list[tuple[AuthChangeEvent, Session | None]] = []
         self.subscriber: Channel | None = None
         self.publisher: Channel | None = None

volcano_sdk_python-0.9.0/features/staged/auth-token-bootstrap.feature

@@ -0,0 +1,31 @@
+Feature: SDK token-only authentication
+
+  @auth @SDK-AUTH-008
+  Scenario: A client uses a supplied access token without inventing session fields
+    Given an authenticated client
+    When a fresh client tries to refresh a supplied profile without a session identifier
+    Then the SDK operation fails
+    When a fresh client starts with only the current access token
+    Then the SDK operation succeeds
+    And the token-only session has no cached user
+    And the session retains only the supplied access 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 session retains only the supplied access token
+    When the client signs out
+    Then the SDK operation succeeds
+    And the current session is empty
+    When a fresh client loads a profile with the signed-out access token
+    Then the SDK operation fails with an authentication error
+    When a fresh client starts with a rejected access token
+    And the client loads its server-validated profile
+    Then the SDK operation fails with an authentication error
+    And the session retains only the supplied access token
+    And the token-only session has no cached user
+    When the client refreshes the current session
+    Then the SDK operation fails
+    And the session retains only the supplied access token
+    When the client signs out
+    Then the SDK operation succeeds
+    And the current session is empty

volcano_sdk_python-0.9.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.3 → volcano_sdk_python-0.9.0}/features/steps/sdk_contract_steps.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import asyncio
 import time
+from dataclasses import replace
 from typing import Any
+from uuid import uuid4
 
 from behave import given, then, when
 from broadcast_pause import verify_broadcast_pause
@@ -77,6 +79,65 @@ def refresh_current_session(context: Any) -> None:
     world.record(world.client.auth.refresh_session)
 
 
+@when("a fresh client tries to refresh a supplied profile without a session identifier")
+def refresh_supplied_profile_without_sid(context: Any) -> None:
+    world = _world(context)
+    source = world.client.auth.get_session()
+    assert source is not None
+    target = VolcanoClient(
+        api_url=world.fixture["api_url"], anon_key=world.fixture["anon_key"]
+    )
+    supplied = target.auth.set_session(replace(source, access_token=REJECTED_BEARER))
+    world.record(target.auth.refresh_session)
+    assert target.auth.get_session() == supplied
+
+
+@when("a fresh client starts with only the current access token")
+def bootstrap_access_token(context: Any) -> None:
+    world = _world(context)
+    source = world.client
+    world.previous_session = source.auth.get_session()
+    assert world.previous_session is not None
+    world.bootstrap_cleanup = source.auth.sign_out
+    world.cleanup_callbacks.append(world.bootstrap_cleanup)
+    world.client = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=world.previous_session.access_token,
+    )
+    world.record(world.client.auth.get_session)
+
+
+@then("the token-only session has no cached user")
+def token_session_has_no_user(context: Any) -> None:
+    session = _world(context).client.current_session
+    assert session is not None
+    assert session.user_id is None
+    assert session.user is None
+
+
+@when("a fresh client starts with a rejected access token")
+def bootstrap_rejected_token(context: Any) -> None:
+    world = _world(context)
+    world.client = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=REJECTED_BEARER,
+    )
+    world.previous_session = world.client.current_session
+    world.record(world.client.auth.get_session)
+
+
+@then("the session retains only the supplied access token")
+def token_session_retains_access(context: Any) -> None:
+    world = _world(context)
+    session = world.client.current_session
+    assert session is not None
+    assert world.previous_session is not None
+    assert session.access_token == world.previous_session.access_token
+    assert session.refresh_token is None
+
+
 @then("the refreshed session becomes current")
 def refreshed_session_becomes_current(context: Any) -> None:
     world = _world(context)
@@ -91,7 +152,10 @@ def sign_out(context: Any) -> None:
     world = _world(context)
     world.signed_out_session = world.client.auth.get_session()
     assert world.signed_out_session is not None
-    world.record(world.client.auth.sign_out)
+    outcome = world.record(world.client.auth.sign_out)
+    if outcome.ok and world.bootstrap_cleanup is not None:
+        world.cleanup_callbacks.remove(world.bootstrap_cleanup)
+        world.bootstrap_cleanup = None
 
 
 @then("the current session is empty")
@@ -99,6 +163,18 @@ def current_session_is_empty(context: Any) -> None:
     assert _world(context).client.auth.get_session() is None
 
 
+@when("a fresh client loads a profile with the signed-out access token")
+def load_signed_out_profile(context: Any) -> None:
+    world = _world(context)
+    assert world.signed_out_session is not None
+    target = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=world.signed_out_session.access_token,
+    )
+    world.record(target.auth.get_user)
+
+
 @when("a fresh client tries to refresh the signed-out session")
 def refresh_signed_out_session(context: Any) -> None:
     world = _world(context)
@@ -127,6 +203,13 @@ def operation_succeeds(context: Any) -> None:
     assert outcome.ok, f"SDK operation failed ({outcome.category}): {outcome.error}"
 
 
+@then("the SDK operation fails")
+def operation_fails(context: Any) -> None:
+    outcome = _world(context).last_outcome
+    assert outcome is not None
+    assert not outcome.ok
+
+
 @then("the current session belongs to the contract user")
 def session_belongs_to_contract_user(context: Any) -> None:
     world = _world(context)
@@ -163,12 +246,14 @@ def authenticated_client(context: Any) -> None:
 
 @given("the client replaces its access token with a rejected token")
 def replace_access_token(context: Any) -> None:
-    client = _world(context).client
+    world = _world(context)
+    client = world.client
     session = client.auth.get_session()
     assert session is not None
-    client.auth.set_session(
+    header, payload, _signature = session.access_token.split(".")
+    world.previous_session = client.auth.set_session(
         Session(
-            access_token=REJECTED_BEARER,
+            access_token=f"{header}.{payload}.sdk-contract-rejected-signature",
             refresh_token=session.refresh_token,
             user_id=session.user_id,
         )
@@ -183,7 +268,8 @@ def read_replaced_token(context: Any) -> None:
     session = world.client.auth.get_session()
     assert session is not None
     assert session.access_token
-    assert session.access_token != REJECTED_BEARER
+    assert world.previous_session is not None
+    assert session.access_token != world.previous_session.access_token
     assert session.refresh_token
     assert session.user_id == world.fixture["user_id"]
 
@@ -551,6 +637,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.3 → volcano_sdk_python-0.9.0}/pyproject.toml

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

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.0}/scripts/check_package.sh

@@ -23,8 +23,12 @@ cat > "$smoke_dir/consumer.py" <<'PY'
 from typing import assert_type
 from volcano_sdk import Session, User, VolcanoClient
 
-client = VolcanoClient(anon_key="example")
+client = VolcanoClient(anon_key="example", access_token="supplied-access")
 assert_type(client.auth.get_session(), Session | None)
+session = client.auth.get_session()
+if session is not None:
+    assert_type(session.refresh_token, str | None)
+    assert_type(session.user_id, str | None)
 assert_type(client.auth.get_user(), User)
 assert_type(client.storage.from_("assets").download("hello.txt"), bytes)
 PY
@@ -49,6 +53,7 @@ PY
     "$typechecker" --no-incremental --python-executable "$smoke_dir/venv/bin/python" consumer.py
     cp consumer.py invalid.py
     echo 'client.auth.sign_in(email=42, password="example")' >> invalid.py
+    echo 'VolcanoClient(anon_key="example", access_token=42)' >> invalid.py
     if "$typechecker" --no-incremental --python-executable "$smoke_dir/venv/bin/python" invalid.py > typing-error.log 2>&1; then
       echo "Installed SDK did not reject an invalid argument type" >&2
       exit 1

{volcano_sdk_python-0.7.3 → volcano_sdk_python-0.9.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()