volcano-sdk-python 0.9.3__py3-none-any.whl → 0.9.4__py3-none-any.whl

volcano_sdk/_function_resolution.py

@@ -12,8 +12,12 @@ from __future__ import annotations
 import threading
 import time
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 from urllib.parse import urlsplit
 
+if TYPE_CHECKING:
+    from .errors import NotFoundError
+
 MAX_ENTRIES = 1024
 NEGATIVE_TTL_SECONDS = 30.0
 
@@ -41,6 +45,9 @@ class CachedOutcome:
     """A cached resolve result: a resolution, or a remembered miss when None."""
 
     resolution: FunctionResolution | None
+    message: str = "Function was not found"
+    code: str | None = None
+    retry_after: int | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -122,13 +129,19 @@ def store(
     _store((api_url, authorization, name), CachedOutcome(resolution), ttl_seconds)
 
 
-def store_missing(api_url: str, authorization: str, name: str) -> None:
+def store_missing(
+    api_url: str, authorization: str, name: str, error: NotFoundError
+) -> None:
     """Remember briefly that a name does not resolve.
 
     A caller retrying an unknown name in a loop would otherwise re-ask the
     server on every attempt.
     """
-    _store((api_url, authorization, name), CachedOutcome(None), NEGATIVE_TTL_SECONDS)
+    _store(
+        (api_url, authorization, name),
+        CachedOutcome(None, str(error), error.code, error.retry_after),
+        NEGATIVE_TTL_SECONDS,
+    )
 
 
 def _store(

volcano_sdk/functions.py

@@ -28,7 +28,6 @@ _INVALID_FUNCTION_NAME = (
 )
 _INVALID_FUNCTION_RESPONSE = "Expected a complete function response"
 _INVALID_FUNCTION_PAYLOAD = "Function payload must be a mapping"
-_UNKNOWN_FUNCTION = "Function was not found"
 _HTTP_SUCCESS_MIN = 200
 _HTTP_SUCCESS_MAX = 300
 _HTTP_NOT_FOUND = 404
@@ -214,7 +213,12 @@ class Functions:
         if cached is None:
             return None
         if cached.resolution is None:
-            raise NotFoundError(_UNKNOWN_FUNCTION, status=_HTTP_NOT_FOUND)
+            raise NotFoundError(
+                cached.message,
+                status=_HTTP_NOT_FOUND,
+                code=cached.code,
+                retry_after=cached.retry_after,
+            )
         return cached.resolution
 
     def _resolve_uncached(
@@ -229,9 +233,11 @@ class Functions:
             authorization=authorization,
             name=name,
         )
-        if int(resolved.status_code) == _HTTP_NOT_FOUND:
-            _function_resolution.store_missing(api_url, authorization, name)
-        payload = response_payload(resolved, _HTTP_SUCCESS_MIN)
+        try:
+            payload = response_payload(resolved, _HTTP_SUCCESS_MIN)
+        except NotFoundError as error:
+            _function_resolution.store_missing(api_url, authorization, name, error)
+            raise
         resolution = self._resolution(payload, api_url)
         _function_resolution.store(
             api_url, authorization, name, resolution, self._cache_ttl(payload)

{volcano_sdk_python-0.9.3.dist-info → volcano_sdk_python-0.9.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.9.3
+Version: 0.9.4
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -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
@@ -218,7 +223,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 +232,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
@@ -326,7 +330,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 +348,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 +452,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 +483,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 +579,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 +595,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 +612,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 +623,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 +654,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 +677,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 +690,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

{volcano_sdk_python-0.9.3.dist-info → volcano_sdk_python-0.9.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 volcano_sdk/__init__.py,sha256=rPSFMLjFbxeQvSRkL1Ee8MsNWArIhs8fgNFgtDuMNzI,1954
-volcano_sdk/_function_resolution.py,sha256=_gC3LY6x71NtJc_o9d9eq3N27Z-T_Un3p2-XRu2-Cqs,5088
+volcano_sdk/_function_resolution.py,sha256=g04npZTP6h2ePEAnpJryP889l5erCfFkcLloBV84eTs,5387
 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
@@ -12,7 +12,7 @@ volcano_sdk/client.py,sha256=CJJnf_iTcXnyY2Y57LXJVAn39mTUsepblUg9op-Thzo,12283
 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=bk523Ss80nREwMD1wk6_pO2XKqOIXqDKylq0fQvMmb0,12540
+volcano_sdk/functions.py,sha256=31OWRkzBAFjvgynErRFfgjhvzA_sIfv73gz7gYX3G-0,12645
 volcano_sdk/locks.py,sha256=eSkidfHQ_wml5-1LT2hBtHxeALP6E1cGYK0FzHjbrNk,9241
 volcano_sdk/logs.py,sha256=lxORRQBvsnJ0BdMau19MXrIeig5_mEucQSyJ4F1CZxU,4666
 volcano_sdk/models.py,sha256=n5EdzkWzmOstXsuFlvfGOILRemQAqG2P4VCLMelW8SA,8690
@@ -775,7 +775,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.9.3.dist-info/METADATA,sha256=AmqFIPDJDOmZgEWKZUIn0jW8EK4ITcvAG92gKMDl1Mk,36008
-volcano_sdk_python-0.9.3.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
-volcano_sdk_python-0.9.3.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
-volcano_sdk_python-0.9.3.dist-info/RECORD,,
+volcano_sdk_python-0.9.4.dist-info/METADATA,sha256=RxgSj08eiYMbgWjVj-CXOia39awfCLKsyjRmytGlwmY,37824
+volcano_sdk_python-0.9.4.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+volcano_sdk_python-0.9.4.dist-info/licenses/LICENSE,sha256=AIHJy-5MFqM8fHfuGFTTb9a8rvJGypcVgN4aZ-7XTWw,11387
+volcano_sdk_python-0.9.4.dist-info/RECORD,,