ledgix-python 0.1.1__tar.gz → 0.1.2__tar.gz

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ledgix-python
-Version: 0.1.1
+Version: 0.1.2
 Summary: Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault
 Project-URL: Homepage, https://github.com/ledgix-dev/python-sdk
 Project-URL: Documentation, https://docs.ledgix.dev

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ledgix-python"
-version = "0.1.1"
+version = "0.1.2"
 description = "Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault"
 readme = "README.md"
 license = { text = "MIT" }

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/src/ledgix_python/client.py

@@ -4,12 +4,16 @@
 from __future__ import annotations
 
 import json
+import random
 import time
+from collections.abc import Awaitable, Callable
 from typing import Any
 
 import httpx
 import jwt
 
+_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+
 from .config import VaultConfig
 from .exceptions import (
     ClearanceDeniedError,
@@ -74,6 +78,66 @@ class LedgixClient:
             )
         return self._async_client
 
+    # ------------------------------------------------------------------
+    # Retry helpers
+    # ------------------------------------------------------------------
+
+    def _backoff_delay(self, attempt: int) -> float:
+        """Exponential backoff with full jitter, capped at 30 seconds."""
+        delay = min(30.0, self.config.retry_base_delay * (2 ** attempt))
+        return random.uniform(0.0, delay)
+
+    def _sync_retry(self, fn: Callable[[], httpx.Response]) -> httpx.Response:
+        """Execute an HTTP callable with retry and exponential backoff.
+
+        Retries on ``httpx.TransportError`` (network errors, timeouts) and on
+        retryable HTTP status codes (429, 5xx). Raises ``VaultConnectionError``
+        after all attempts are exhausted.
+        """
+        last_exc: httpx.TransportError | None = None
+        response: httpx.Response | None = None
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                response = fn()
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.config.max_retries:
+                    time.sleep(self._backoff_delay(attempt))
+                    continue
+                raise VaultConnectionError(str(exc)) from exc
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self.config.max_retries:
+                time.sleep(self._backoff_delay(attempt))
+                continue
+            return response
+        if last_exc is not None:
+            raise VaultConnectionError(str(last_exc)) from last_exc
+        assert response is not None
+        return response
+
+    async def _async_retry(self, fn: Callable[[], Awaitable[httpx.Response]]) -> httpx.Response:
+        """Async variant of ``_sync_retry``."""
+        import asyncio
+
+        last_exc: httpx.TransportError | None = None
+        response: httpx.Response | None = None
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                response = await fn()
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.config.max_retries:
+                    await asyncio.sleep(self._backoff_delay(attempt))
+                    continue
+                raise VaultConnectionError(str(exc)) from exc
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self.config.max_retries:
+                await asyncio.sleep(self._backoff_delay(attempt))
+                continue
+            return response
+        if last_exc is not None:
+            raise VaultConnectionError(str(last_exc)) from last_exc
+        assert response is not None
+        return response
+
     # ------------------------------------------------------------------
     # Clearance — sync
     # ------------------------------------------------------------------
@@ -86,13 +150,13 @@ class LedgixClient:
             VaultConnectionError: If the Vault is unreachable.
         """
         try:
-            response = self._get_sync_client().post(
-                "/request-clearance",
-                content=request.model_dump_json(),
+            response = self._sync_retry(
+                lambda: self._get_sync_client().post(
+                    "/request-clearance",
+                    content=request.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -124,13 +188,13 @@ class LedgixClient:
             VaultConnectionError: If the Vault is unreachable.
         """
         try:
-            response = await self._get_async_client().post(
-                "/request-clearance",
-                content=request.model_dump_json(),
+            response = await self._async_retry(
+                lambda: self._get_async_client().post(
+                    "/request-clearance",
+                    content=request.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -157,13 +221,13 @@ class LedgixClient:
     def register_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
         """Register a policy with the Vault (sync)."""
         try:
-            response = self._get_sync_client().post(
-                "/register-policy",
-                content=policy.model_dump_json(),
+            response = self._sync_retry(
+                lambda: self._get_sync_client().post(
+                    "/register-policy",
+                    content=policy.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise PolicyRegistrationError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -174,13 +238,13 @@ class LedgixClient:
     async def aregister_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
         """Register a policy with the Vault (async)."""
         try:
-            response = await self._get_async_client().post(
-                "/register-policy",
-                content=policy.model_dump_json(),
+            response = await self._async_retry(
+                lambda: self._get_async_client().post(
+                    "/register-policy",
+                    content=policy.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise PolicyRegistrationError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -225,10 +289,10 @@ class LedgixClient:
     def fetch_jwks(self) -> dict[str, Any]:
         """Fetch the Vault's JWKS (JSON Web Key Set) for token verification (sync)."""
         try:
-            response = self._get_sync_client().get("/.well-known/jwks.json")
+            response = self._sync_retry(
+                lambda: self._get_sync_client().get("/.well-known/jwks.json")
+            )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
@@ -240,10 +304,10 @@ class LedgixClient:
     async def afetch_jwks(self) -> dict[str, Any]:
         """Fetch the Vault's JWKS for token verification (async)."""
         try:
-            response = await self._get_async_client().get("/.well-known/jwks.json")
+            response = await self._async_retry(
+                lambda: self._get_async_client().get("/.well-known/jwks.json")
+            )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
@@ -261,37 +325,31 @@ class LedgixClient:
             TokenVerificationError: If the token is invalid, expired, or
                 the JWKS cannot be fetched.
         """
-        return self._verify_token_internal(token, sync=True)
+        if self._jwks_cache is None:
+            self.fetch_jwks()
+        return self._decode_token(token)
 
     async def averify_token(self, token: str) -> dict[str, Any]:
-        """Verify an A-JWT using the Vault's public key (async)."""
-        return self._verify_token_internal(token, sync=False)
+        """Verify an A-JWT using the Vault's public key (async).
 
-    def _verify_token_internal(self, token: str, sync: bool = True) -> dict[str, Any]:
-        """Shared verification logic.
-
-        Note: For async callers this is still synchronous internally
-        because PyJWT is sync. The async variant pre-fetches JWKS
-        asynchronously before calling this.
+        Raises:
+            TokenVerificationError: If the token is invalid, expired, or
+                the JWKS cannot be fetched.
         """
         if self._jwks_cache is None:
-            if sync:
-                self.fetch_jwks()
-            else:
-                # In async context, caller must have pre-fetched JWKS.
-                # Fall back to sync fetch if cache is empty.
-                self.fetch_jwks()
+            await self.afetch_jwks()
+        return self._decode_token(token)
 
+    def _decode_token(self, token: str) -> dict[str, Any]:
+        """Verify an A-JWT against the cached JWKS. JWKS must already be populated."""
         if not self._jwks_cache:
             raise TokenVerificationError("No JWKS available from Vault")
 
         try:
-            # Extract the first key from the JWKS
             jwks = self._jwks_cache
             if "keys" not in jwks or not jwks["keys"]:
                 raise TokenVerificationError("JWKS contains no keys")
 
-            # Build a PyJWT key from the JWK
             key_data = jwks["keys"][0]
             public_key = jwt.algorithms.OKPAlgorithm.from_jwk(json.dumps(key_data))
 
@@ -307,6 +365,8 @@ class LedgixClient:
                 raise TokenVerificationError("Invalid A-JWT: unexpected subject")
             return decoded
 
+        except TokenVerificationError:
+            raise
         except jwt.ExpiredSignatureError as exc:
             raise TokenVerificationError("A-JWT has expired") from exc
         except jwt.InvalidTokenError as exc:

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/src/ledgix_python/config.py

@@ -49,3 +49,9 @@ class VaultConfig(BaseSettings):
 
     review_timeout: float = 300.0
     """Maximum wait time in seconds for a pending manual review decision."""
+
+    max_retries: int = 3
+    """Number of retry attempts for transient failures (connection errors, 5xx responses)."""
+
+    retry_base_delay: float = 0.5
+    """Base delay in seconds for exponential backoff between retries (full jitter applied)."""

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/src/ledgix_python/enforce.py

@@ -148,17 +148,23 @@ def _extract_tool_args(
     args: tuple[Any, ...],
     kwargs: dict[str, Any],
 ) -> dict[str, Any]:
-    """Best-effort extraction of function arguments as a dict for the clearance request."""
+    """Best-effort extraction of function arguments as a dict for the clearance request.
+
+    Skips ``self``, private parameters (prefixed with ``_``), ``*args``, and
+    ``**kwargs`` captures so only named, user-visible parameters are included.
+    """
     try:
         sig = inspect.signature(func)
         bound = sig.bind_partial(*args, **kwargs)
         bound.apply_defaults()
-        # Filter out internal kwargs
-        return {
-            k: v
-            for k, v in bound.arguments.items()
-            if not k.startswith("_") and k != "self"
-        }
-    except Exception:
-        # Fallback: just return kwargs
+        result: dict[str, Any] = {}
+        for name, value in bound.arguments.items():
+            if name.startswith("_") or name == "self":
+                continue
+            param = sig.parameters[name]
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            result[name] = value
+        return result
+    except (TypeError, ValueError):
         return {k: v for k, v in kwargs.items() if not k.startswith("_")}

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/tests/conftest.py

@@ -88,6 +88,7 @@ def vault_config() -> VaultConfig:
         jwt_audience="ledgix-sdk",
         agent_id="test-agent",
         session_id="test-session",
+        max_retries=0,
     )
 
 
@@ -102,6 +103,22 @@ def vault_config_with_jwt() -> VaultConfig:
         jwt_audience="ledgix-sdk",
         agent_id="test-agent",
         session_id="test-session",
+        max_retries=0,
+    )
+
+
+@pytest.fixture
+def vault_config_retry() -> VaultConfig:
+    """Config with retries enabled and zero backoff delay for fast retry tests."""
+    return VaultConfig(
+        vault_url="https://vault.test",
+        vault_api_key="test-api-key",
+        vault_timeout=5.0,
+        verify_jwt=False,
+        agent_id="test-agent",
+        session_id="test-session",
+        max_retries=2,
+        retry_base_delay=0.0,
     )
 
 

{ledgix_python-0.1.1 → ledgix_python-0.1.2}/tests/test_client.py

@@ -314,6 +314,100 @@ class TestTokenVerification:
 # ──────────────────────────────────────────────────────────────────────
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Retry behaviour
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestRetry:
+    """Tests for automatic retry with exponential backoff."""
+
+    @respx.mock
+    def test_retries_on_connection_error_then_succeeds(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        route = respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                httpx.ConnectError("Connection refused"),
+                httpx.ConnectError("Connection refused"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = client.request_clearance(request)
+
+        assert result.approved is True
+        assert route.call_count == 3
+        client.close()
+
+    @respx.mock
+    def test_retries_on_5xx_then_succeeds(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                Response(503, text="Service Unavailable"),
+                Response(503, text="Service Unavailable"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = client.request_clearance(request)
+
+        assert result.approved is True
+        client.close()
+
+    @respx.mock
+    def test_raises_after_exhausting_retries(self, vault_config_retry: VaultConfig):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=httpx.ConnectError("Connection refused")
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        with pytest.raises(VaultConnectionError):
+            client.request_clearance(request)
+        client.close()
+
+    @respx.mock
+    def test_does_not_retry_on_4xx(self, vault_config_retry: VaultConfig):
+        client = LedgixClient(config=vault_config_retry)
+        route = respx.post("https://vault.test/request-clearance").mock(
+            return_value=Response(400, text="Bad Request")
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        with pytest.raises(VaultConnectionError):
+            client.request_clearance(request)
+
+        # 400 is not retryable — should only be called once
+        assert route.call_count == 1
+        client.close()
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_retries_on_connection_error(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                httpx.ConnectError("Connection refused"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = await client.arequest_clearance(request)
+
+        assert result.approved is True
+        await client.aclose()
+
+
 class TestClientLifecycle:
     """Tests for context manager and close behavior."""