volcano-sdk-python 0.7.3__py3-none-any.whl → 0.8.0__py3-none-any.whl

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()
 

volcano_sdk/_transport.py

@@ -104,12 +104,17 @@ from ._generated.api.functions.invoke_function import (
     _get_kwargs as invoke_function_kwargs,
 )
 from ._generated.api.locks import (
-    acquire_project_lock,
     force_release_project_lock,
     get_project_lock,
     release_project_lock,
     renew_project_lock,
 )
+from ._generated.api.locks.acquire_project_lock import (
+    _build_response as build_lock_acquire_response,
+)
+from ._generated.api.locks.acquire_project_lock import (
+    _get_kwargs as lock_acquire_kwargs,
+)
 from ._generated.api.logs.get_project_log_activity import (
     _build_response as build_log_activity_response,
 )
@@ -253,6 +258,7 @@ if TYPE_CHECKING:
     )
     from .models import JSONValue
 
+HTTP_CREATED = 201
 HTTP_UNAUTHORIZED = 401
 HTTP_NOT_FOUND = 404
 HTTP_CONFLICT = 409
@@ -643,6 +649,7 @@ class Transport(Protocol):
         key: str,
         ttl: int,
         token: str,
+        request_id: str | None = None,
     ) -> TransportResponse: ...
 
     def release_project_lock(
@@ -651,6 +658,7 @@ class Transport(Protocol):
         authorization: str,
         key: str,
         token: str,
+        request_id: str | None = None,
     ) -> TransportResponse: ...
 
 
@@ -1735,15 +1743,19 @@ class GeneratedTransport:
         key: str,
         ttl: int,
         token: str,
+        request_id: str | None = None,
     ) -> TransportResponse:
         with self._client(authorization) as client:
-            response = acquire_project_lock.sync_detailed(
+            request_kwargs = lock_acquire_kwargs(
                 key,
-                client=client,
                 body=ProjectLockLeaseRequest(ttl_seconds=ttl),
                 x_volcano_lock_token=cast("UUID", token),
-                x_volcano_request_id=cast("UUID", str(uuid4())),
+                x_volcano_request_id=cast("UUID", request_id or str(uuid4())),
             )
+            raw_response = client.get_httpx_client().request(**request_kwargs)
+            if raw_response.status_code != HTTP_CREATED:
+                return self._raw_response(raw_response)
+            response = build_lock_acquire_response(client=client, response=raw_response)
         return self._response(response)
 
     def get_project_lock(
@@ -1751,12 +1763,13 @@ class GeneratedTransport:
         *,
         authorization: str,
         key: str,
+        request_id: str | None = None,
     ) -> TransportResponse:
         with self._client(authorization) as client:
             response = get_project_lock.sync_detailed(
                 key,
                 client=client,
-                x_volcano_request_id=cast("UUID", str(uuid4())),
+                x_volcano_request_id=cast("UUID", request_id or str(uuid4())),
             )
         return self._response(response)
 
@@ -1765,12 +1778,13 @@ class GeneratedTransport:
         *,
         authorization: str,
         key: str,
+        request_id: str | None = None,
     ) -> TransportResponse:
         with self._client(authorization) as client:
             response = force_release_project_lock.sync_detailed(
                 key,
                 client=client,
-                x_volcano_request_id=cast("UUID", str(uuid4())),
+                x_volcano_request_id=cast("UUID", request_id or str(uuid4())),
             )
         return self._response(response)
 
@@ -1781,6 +1795,7 @@ class GeneratedTransport:
         key: str,
         ttl: int,
         token: str,
+        request_id: str | None = None,
     ) -> TransportResponse:
         with self._client(authorization) as client:
             response = renew_project_lock.sync_detailed(
@@ -1788,7 +1803,7 @@ class GeneratedTransport:
                 client=client,
                 body=ProjectLockLeaseRequest(ttl_seconds=ttl),
                 x_volcano_lock_token=cast("UUID", token),
-                x_volcano_request_id=cast("UUID", str(uuid4())),
+                x_volcano_request_id=cast("UUID", request_id or str(uuid4())),
             )
         return self._response(response)
 
@@ -1798,12 +1813,13 @@ class GeneratedTransport:
         authorization: str,
         key: str,
         token: str,
+        request_id: str | None = None,
     ) -> TransportResponse:
         with self._client(authorization) as client:
             response = release_project_lock.sync_detailed(
                 key,
                 client=client,
                 x_volcano_lock_token=cast("UUID", token),
-                x_volcano_request_id=cast("UUID", str(uuid4())),
+                x_volcano_request_id=cast("UUID", request_id or str(uuid4())),
             )
         return self._response(response)

volcano_sdk/locks.py

@@ -5,11 +5,12 @@ from __future__ import annotations
 from contextlib import contextmanager, suppress
 from datetime import datetime
 from typing import TYPE_CHECKING, Protocol, cast
-from uuid import uuid4
+from uuid import UUID, uuid4
 
 from ._lock_guard import LockGuard, _lease_now
 from ._lock_worker import LockRenewer
 from ._transport import Transport, invoke, response_payload
+from .errors import ServerError, TransportError
 from .models import LockLease, LockState
 
 if TYPE_CHECKING:
@@ -37,6 +38,7 @@ class LockGetTransport(Protocol):
         *,
         authorization: str,
         key: str,
+        request_id: str | None = None,
     ) -> object:
         """Get one project-scoped lock."""
         ...
@@ -52,6 +54,7 @@ class LockRenewTransport(Protocol):
         key: str,
         ttl: int,
         token: str,
+        request_id: str | None = None,
     ) -> object:
         """Renew one project-scoped lock."""
         ...
@@ -65,6 +68,7 @@ class LockForceReleaseTransport(Protocol):
         *,
         authorization: str,
         key: str,
+        request_id: str | None = None,
     ) -> object:
         """Force release one project-scoped lock."""
         ...
@@ -85,6 +89,17 @@ def _validate_ttl(ttl: object) -> None:
         raise ValueError(_INVALID_LOCK_TTL)
 
 
+def _request_uuid(value: str | None, name: str) -> str:
+    if value is None:
+        return str(uuid4())
+    try:
+        UUID(value)
+    except (AttributeError, ValueError) as error:
+        message = f"{name} must be a UUID string"
+        raise ValueError(message) from error
+    return value
+
+
 class Locks:
     """Acquire and release project-scoped distributed locks."""
 
@@ -92,13 +107,14 @@ class Locks:
         """Create a lock facade backed by a client."""
         self._client = client
 
-    def get(self, key: str) -> LockState:
+    def get(self, key: str, *, request_id: str | None = None) -> LockState:
         """Return the current state of a project-scoped lock."""
         transport = cast("LockGetTransport", self._client._transport)
         response = invoke(
             transport.get_project_lock,
             authorization=self._client._service_token(),
             key=key,
+            request_id=_request_uuid(request_id, "request_id"),
         )
         payload = response_payload(response, 200)
         return LockState(
@@ -107,26 +123,64 @@ class Locks:
             fencing_token=payload.get("fencing_token"),
         )
 
-    def acquire(self, key: str, *, ttl: int) -> LockLease:
-        """Acquire a lock lease for the requested number of seconds."""
+    def acquire(
+        self,
+        key: str,
+        *,
+        ttl: int,
+        token: str | None = None,
+        request_id: str | None = None,
+    ) -> LockLease:
+        """Acquire with one bounded retry using the same ownership token."""
+        lease, _ = self._acquire_with_start(
+            key, ttl=ttl, token=token, request_id=request_id
+        )
+        return lease
+
+    def _acquire_with_start(
+        self,
+        key: str,
+        *,
+        ttl: int,
+        token: str | None,
+        request_id: str | None,
+    ) -> tuple[LockLease, float]:
         _validate_ttl(ttl)
-        token = str(uuid4())
-        response = invoke(
-            self._client._transport.acquire_project_lock,
-            authorization=self._client._service_token(),
+        token = _request_uuid(token, "token")
+        request_id = _request_uuid(request_id, "request_id")
+        authorization = self._client._service_token()
+        started_at = _lease_now()
+        try:
+            payload = self._acquire_payload(key, ttl, token, request_id, authorization)
+        except (TransportError, ServerError) as error:
+            if error.status not in (None, 503):
+                raise
+            started_at = _lease_now()
+            payload = self._acquire_payload(key, ttl, token, request_id, authorization)
+        lease = LockLease(
             key=key,
-            ttl=ttl,
             token=token,
+            expires_at=_parse_datetime(payload.get("expires_at")),
+            fencing_token=cast("int | None", payload.get("fencing_token")),
         )
-        payload = response_payload(response, 201)
-        return LockLease(
+        return lease, started_at
+
+    def _acquire_payload(
+        self, key: str, ttl: int, token: str, request_id: str, authorization: str
+    ) -> dict[str, object]:
+        response = invoke(
+            self._client._transport.acquire_project_lock,
+            authorization=authorization,
             key=key,
+            ttl=ttl,
             token=token,
-            expires_at=_parse_datetime(payload.get("expires_at")),
-            fencing_token=payload.get("fencing_token"),
+            request_id=request_id,
         )
+        return cast("dict[str, object]", response_payload(response, 201))
 
-    def renew(self, key: str, lease: LockLease, *, ttl: int) -> LockLease:
+    def renew(
+        self, key: str, lease: LockLease, *, ttl: int, request_id: str | None = None
+    ) -> LockLease:
         """Renew a lock lease and return its immutable replacement."""
         _validate_ttl(ttl)
         transport = cast("LockRenewTransport", self._client._transport)
@@ -134,6 +188,7 @@ class Locks:
             transport.renew_project_lock,
             authorization=self._client._service_token(),
             key=key,
+            request_id=_request_uuid(request_id, "request_id"),
             ttl=ttl,
             token=lease.token,
         )
@@ -145,35 +200,47 @@ class Locks:
             fencing_token=payload.get("fencing_token"),
         )
 
-    def release(self, key: str, lease: LockLease) -> None:
+    def release(
+        self, key: str, lease: LockLease, *, request_id: str | None = None
+    ) -> None:
         """Release a lock lease."""
         response = invoke(
             self._client._transport.release_project_lock,
             authorization=self._client._service_token(),
             key=key,
+            request_id=_request_uuid(request_id, "request_id"),
             token=lease.token,
         )
         response_payload(response, 204)
 
-    def force_release(self, key: str) -> None:
+    def force_release(self, key: str, *, request_id: str | None = None) -> None:
         """Release a lock regardless of which token owns it."""
         transport = cast("LockForceReleaseTransport", self._client._transport)
         response = invoke(
             transport.force_release_project_lock,
             authorization=self._client._service_token(),
             key=key,
+            request_id=_request_uuid(request_id, "request_id"),
         )
         response_payload(response, 204)
 
     @contextmanager
-    def with_lock(self, key: str, *, ttl: int) -> Generator[LockGuard, None, None]:
+    def with_lock(
+        self,
+        key: str,
+        *,
+        ttl: int,
+        token: str | None = None,
+        request_id: str | None = None,
+    ) -> Generator[LockGuard, None, None]:
         """Hold and automatically renew a lock for the context's lifetime."""
         _validate_ttl(ttl)
         started_at = _lease_now()
+        lease, lease_started_at = self._acquire_with_start(
+            key, ttl=ttl, token=token, request_id=request_id
+        )
         guard = LockGuard(
-            self.acquire(key, ttl=ttl),
-            ttl=ttl,
-            started_at=started_at,
+            lease, ttl=ttl, started_at=started_at, lease_started_at=lease_started_at
         )
         renewer = LockRenewer(self, key, guard, ttl=ttl)
         renewer_started = False

{volcano_sdk_python-0.7.3.dist-info → volcano_sdk_python-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.7.3
+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
@@ -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.

{volcano_sdk_python-0.7.3.dist-info → volcano_sdk_python-0.8.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
 volcano_sdk/__init__.py,sha256=rPSFMLjFbxeQvSRkL1Ee8MsNWArIhs8fgNFgtDuMNzI,1954
 volcano_sdk/_function_resolution.py,sha256=_gC3LY6x71NtJc_o9d9eq3N27Z-T_Un3p2-XRu2-Cqs,5088
-volcano_sdk/_lock_guard.py,sha256=EZzcwOPTFTCNUrIWIQ0-nMg9tm_nPkaYkcocgeLbu94,5572
+volcano_sdk/_lock_guard.py,sha256=VhHTgBc4e5EDj8j15vVIhdBOTp6fvD628x3hVBeF39o,5794
 volcano_sdk/_lock_renewer.py,sha256=tFo1ZeRiPKB5VSbW61uoMpNR67ZDYyMEe-dCjpAM3As,841
 volcano_sdk/_lock_worker.py,sha256=QhSmwR0WcwgT-7ueJMlbCogLqOakQ5eRAtyWV74fgV0,3057
 volcano_sdk/_realtime_fetch_worker.py,sha256=zQTgFF4cIUBeAL4J2OpWAlz_sIynv2BLfu588EogAdo,9269
-volcano_sdk/_transport.py,sha256=PzdO7uhqvgI2L-Ff0rwZCWeF7yuH_Ty-OvZx0F7dMpo,57509
+volcano_sdk/_transport.py,sha256=AFd47C3X1WAHwq3f9V2ux0WNzwGIn4NBxrwgaIN-xl0,58296
 volcano_sdk/auth.py,sha256=Z5UCrqdvmHBS6n6ZleXya04hYV94rH4SRV1GW2yimXo,43185
 volcano_sdk/client.py,sha256=KutjBUOEJyK73OibKilrcWazpWeXKEZYUehSAH8qxUE,10366
 volcano_sdk/connection_string.py,sha256=LlTZigsrCF4IfAqQ8SDTWJv35hnnzNu1MfeVv5JW-Kk,2331
 volcano_sdk/database.py,sha256=p_5OaqlBjKAtIUfKQCflXM_CGqokrVmpOMsp6KHiJ8A,9493
 volcano_sdk/errors.py,sha256=ffs66FIN_jhyh5SMj7KdXb-zVV3DSgVK6xJEPNA5h9Y,1613
 volcano_sdk/functions.py,sha256=zDeAKyCieNnI6wzb9iZMlg9_cbjaYWXYbXHb7jzCle4,10126
-volcano_sdk/locks.py,sha256=iWMhdbZQDw44ZNwENaZWu7WelakjpHhjYzKzufD7SNU,6932
+volcano_sdk/locks.py,sha256=eSkidfHQ_wml5-1LT2hBtHxeALP6E1cGYK0FzHjbrNk,9241
 volcano_sdk/logs.py,sha256=lxORRQBvsnJ0BdMau19MXrIeig5_mEucQSyJ4F1CZxU,4666
 volcano_sdk/models.py,sha256=43zM6LQ9eJ3Hn6q9PiVSozSmOzPSr4m4OL8G8KVb-gg,8619
 volcano_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
@@ -773,7 +773,7 @@ volcano_sdk/_generated/models/usage_data_point.py,sha256=d4U08JbVTiIMM_l2BmRILL1
 volcano_sdk/_generated/models/variable.py,sha256=tvGDOMv77gW6j5skufnfrlNAhzCzA1F7nuPCQWx79yY,5926
 volcano_sdk/_generated/models/variable_deploy_source.py,sha256=G_aCiFHzQx8WhJFs0GvYZEFclfTrfkDvd3kT1e3vty8,463
 volcano_sdk/_generated/models/variable_status.py,sha256=THSsKBSiAYG4kAtBzGA4TZqxjgx8hdL0Q4qCdZfOj00,391
-volcano_sdk_python-0.7.3.dist-info/METADATA,sha256=0lDdNzghgpaKsYFFqMZZrWCn0rUt9nqdaGWSg0FhU_U,33557
-volcano_sdk_python-0.7.3.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
-volcano_sdk_python-0.7.3.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
-volcano_sdk_python-0.7.3.dist-info/RECORD,,
+volcano_sdk_python-0.8.0.dist-info/METADATA,sha256=lJ43KIGGSaMGAsRRM_EqJYI9AJXnEibMrg9CqElZU78,34010
+volcano_sdk_python-0.8.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+volcano_sdk_python-0.8.0.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
+volcano_sdk_python-0.8.0.dist-info/RECORD,,