feat(client): opt-in retry with backoff honoring Retry-After

README.md

@@ -58,6 +58,30 @@ If no token is provided at all, `CodesphereSDK()` raises an
 `AuthenticationError` at construction (importing the package never requires
 any environment variable).
 
+### Retries
+
+Retries are off by default. Opt in with a `RetryConfig`:
+
+```python
+from codesphere import CodesphereSDK, RetryConfig
+
+sdk = CodesphereSDK(
+    token="your-api-token",
+    retry=RetryConfig(max_retries=3),
+)
+```
+
+Requests using an idempotent method (`GET`, `HEAD`, `PUT`, `DELETE`) are then
+retried on `429`, `502`, `503`, and `504` responses as well as on
+connect/timeout errors. The delay honors the server's `Retry-After` header
+(seconds or HTTP-date) when present, otherwise exponential backoff with
+jitter (`backoff_factor * 2**attempt`). `POST` is never retried unless you
+add it to `retry_methods` explicitly:
+
+```python
+RetryConfig(max_retries=3, retry_methods=frozenset({"GET", "POST"}))
+```
+
 ## Quick Start
 
 ```python

src/codesphere/__init__.py

@@ -22,6 +22,7 @@
 import logging
 
 from .client import CodesphereSDK
+from .config import RetryConfig
 from .exceptions import (
     APIError,
     AuthenticationError,
@@ -75,6 +76,7 @@
     "NetworkError",
     "NotFoundError",
     "RateLimitError",
+    "RetryConfig",
     # Resources
     "Team",
     "TeamBase",

src/codesphere/client.py

@@ -3,7 +3,7 @@
 import httpx
 from pydantic import SecretStr
 
-from .config import Settings
+from .config import RetryConfig, Settings
 from .exceptions import AuthenticationError
 from .http_client import APIHttpClient
 from .resources.metadata import MetadataResource
@@ -30,6 +30,7 @@ def __init__(
         token: str | SecretStr | None = None,
         base_url: str | None = None,
         timeout: httpx.Timeout | None = None,
+        retry: RetryConfig | None = None,
         http_client: APIHttpClient | None = None,
     ):
         if http_client is not None:
@@ -53,6 +54,7 @@ def __init__(
                 token=resolved_token,
                 base_url=resolved_base_url,
                 timeout=resolved_timeout,
+                retry=retry,
             )
 
         self.teams = TeamsResource(self._http_client)

src/codesphere/config.py

@@ -1,9 +1,30 @@
+from dataclasses import dataclass
+
 from pydantic import HttpUrl, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 DEFAULT_BASE_URL = "https://codesphere.com/api"
 
 
+@dataclass(frozen=True, slots=True)
+class RetryConfig:
+    """Opt-in retry behavior for transient failures.
+
+    Disabled by default (``max_retries=0``). When enabled, requests using a
+    method in ``retry_methods`` are retried on the statuses in
+    ``retry_statuses`` and on connect/timeout errors. The delay honors a
+    ``Retry-After`` response header (seconds or HTTP-date) when present,
+    otherwise exponential backoff with jitter is used. Only idempotent
+    methods are retried by default; add ``"POST"`` to ``retry_methods``
+    explicitly if your endpoints tolerate it.
+    """
+
+    max_retries: int = 0
+    backoff_factor: float = 0.5
+    retry_statuses: frozenset[int] = frozenset({429, 502, 503, 504})
+    retry_methods: frozenset[str] = frozenset({"GET", "HEAD", "PUT", "DELETE"})
+
+
 class Settings(BaseSettings):
     """Environment-driven defaults (``CS_*`` variables, optional ``.env``).
 

src/codesphere/http_client.py

@@ -1,28 +1,54 @@
+import asyncio
 import logging
+import random
 from contextlib import AbstractAsyncContextManager
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 from types import TracebackType
 from typing import Any, cast
 
 import httpx
 from pydantic import SecretStr
 
+from .config import RetryConfig
 from .exceptions import NetworkError, TimeoutError, raise_for_status
 
 log = logging.getLogger(__name__)
 
 
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a Retry-After header: delta-seconds or an HTTP-date."""
+    if not value:
+        return None
+    if value.isdigit():
+        return float(value)
+    try:
+        retry_at = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, (retry_at - datetime.now(UTC)).total_seconds())
+
+
 class APIHttpClient:
     """Thin async transport around httpx.
 
     Receives its full configuration from the caller (the SDK resolves
     arguments, environment variables, and defaults) and owns nothing but
-    the connection lifecycle and error mapping.
+    the connection lifecycle, error mapping, and opt-in retries.
     """
 
-    def __init__(self, *, token: SecretStr, base_url: str, timeout: httpx.Timeout):
+    def __init__(
+        self,
+        *,
+        token: SecretStr,
+        base_url: str,
+        timeout: httpx.Timeout,
+        retry: RetryConfig | None = None,
+    ):
         self._token = token.get_secret_value()
         self._base_url = base_url
         self._client: httpx.AsyncClient | None = None
+        self._retry = retry if retry is not None else RetryConfig()
 
         self._timeout_config = timeout
         self._client_config: dict[str, Any] = {
@@ -92,28 +118,66 @@ async def request(
         log.debug(f"Request: {method} {endpoint}")
         log.debug(f"Request kwargs: {kwargs}")
 
-        try:
-            response = await client.request(method, endpoint, **kwargs)
+        retryable_method = method.upper() in self._retry.retry_methods
+        attempts = self._retry.max_retries + 1 if retryable_method else 1
+
+        for attempt in range(attempts):
+            last_attempt = attempt == attempts - 1
+            try:
+                response = await client.request(method, endpoint, **kwargs)
+            except httpx.TimeoutException as e:
+                if not last_attempt:
+                    await self._sleep_before_retry(attempt, None, method, endpoint)
+                    continue
+                log.error(f"Request timeout for {method} {endpoint}: {e}")
+                raise TimeoutError(f"Request to {endpoint} timed out.") from e
+            except httpx.ConnectError as e:
+                if not last_attempt:
+                    await self._sleep_before_retry(attempt, None, method, endpoint)
+                    continue
+                log.error(f"Connection error for {method} {endpoint}: {e}")
+                raise NetworkError(
+                    f"Failed to connect to the API: {e}",
+                    original_error=e,
+                ) from e
+            except httpx.RequestError as e:
+                log.error(f"Network error for {method} {endpoint}: {e}")
+                raise NetworkError(
+                    f"A network error occurred: {e}",
+                    original_error=e,
+                ) from e
+
             log.debug(
                 f"Response: {response.status_code} {response.reason_phrase} "
                 f"for {method} {endpoint}"
             )
 
+            if response.status_code in self._retry.retry_statuses and not last_attempt:
+                await self._sleep_before_retry(attempt, response, method, endpoint)
+                continue
+
             raise_for_status(response)
             return response
 
-        except httpx.TimeoutException as e:
-            log.error(f"Request timeout for {method} {endpoint}: {e}")
-            raise TimeoutError(f"Request to {endpoint} timed out.") from e
-        except httpx.ConnectError as e:
-            log.error(f"Connection error for {method} {endpoint}: {e}")
-            raise NetworkError(
-                f"Failed to connect to the API: {e}",
-                original_error=e,
-            ) from e
-        except httpx.RequestError as e:
-            log.error(f"Network error for {method} {endpoint}: {e}")
-            raise NetworkError(
-                f"A network error occurred: {e}",
-                original_error=e,
-            ) from e
+        raise AssertionError("unreachable: retry loop must return or raise")
+
+    async def _sleep_before_retry(
+        self,
+        attempt: int,
+        response: httpx.Response | None,
+        method: str,
+        endpoint: str,
+    ) -> None:
+        delay = None
+        if response is not None:
+            delay = _parse_retry_after(response.headers.get("Retry-After"))
+        if delay is None:
+            delay = self._retry.backoff_factor * (2**attempt)
+            # Jitter to avoid thundering herds; not security-relevant.
+            delay += random.uniform(0, self._retry.backoff_factor / 2)  # nosec B311
+
+        log.debug(
+            f"Retrying {method} {endpoint} in {delay:.2f}s "
+            f"(attempt {attempt + 1}/{self._retry.max_retries})"
+        )
+        await asyncio.sleep(delay)