Merge branch 'main' into fix/13-add-request-response-debug-logging

Author: codebestia

src/shade/__init__.py

@@ -1,5 +1,9 @@
+import sys
+from types import ModuleType
+from typing import Optional
+
 from .client import ShadeClient
-from .config import config
+from .config import config, Environment
 from .gateway import Gateway
 from .http import AsyncHTTPClient, SyncHTTPClient
 from .errors import (
@@ -14,9 +18,13 @@
 
 __version__ = "0.1.0"
 
+# ShadeClient is an alias for Gateway.
+ShadeClient = Gateway
+
 __all__ = [
     "AsyncHTTPClient",
     "AuthenticationError",
+    "Environment",
     "Gateway",
     "HTTPError",
     "InvalidRequestError",
@@ -27,4 +35,22 @@
     "ShadeError",
     "SyncHTTPClient",
     "config",
+    "api_base",
 ]
+
+
+class _ShadeModule(ModuleType):
+    """Module subclass that exposes api_base as a settable attribute backed by config."""
+
+    @property
+    def api_base(self) -> Optional[str]:
+        from . import config as _config
+        return _config.api_base
+
+    @api_base.setter
+    def api_base(self, value: Optional[str]) -> None:
+        from . import config as _config
+        _config.api_base = value
+
+
+sys.modules[__name__].__class__ = _ShadeModule

src/shade/config.py

@@ -1,7 +1,39 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from stellar_sdk import Network
+
+# Module-level API base URL override. Intended for development and testing only.
+# Set this before creating any client to route all requests to a custom host.
+api_base: Optional[str] = None
+
 class Config:
     """Global SDK configuration."""
 
     debug: bool = False
 
 
+class Environment(str, Enum):
+    MAINNET = "mainnet"
+    TESTNET = "testnet"
+
+    @property
+    def base_url(self) -> str:
+        _urls: dict[str, str] = {
+            "mainnet": "https://api.shadeprotocol.io/v1",
+            "testnet": "https://testnet.api.shadeprotocol.io/v1",
+        }
+        return _urls[self.value]
+
+    @property
+    def network_passphrase(self) -> str:
+        _passphrases: dict[str, str] = {
+            "mainnet": Network.PUBLIC_NETWORK_PASSPHRASE,
+            "testnet": Network.TESTNET_NETWORK_PASSPHRASE,
+        }
+        return _passphrases[self.value]
+
+
 config = Config()

src/shade/gateway.py

@@ -2,6 +2,8 @@
 
 from typing import Any, Dict, Optional
 
+from . import config as _config
+from .config import Environment
 from .http import AsyncHTTPClient, SyncHTTPClient, DEFAULT_MAX_RETRIES
 
 
@@ -13,28 +15,42 @@ class Gateway:
     ----------
     api_key : str
         Your Shade API key.
+    environment : Environment
+        Controls the Stellar network passphrase and the default API URL.
+        Defaults to ``Environment.MAINNET``.
+    api_base : str, optional
+        Override the API host for this client (useful for local dev or staging).
+        Takes precedence over the module-level ``shade.api_base`` and the
+        URL derived from ``environment``. Trailing slashes are trimmed.
+        Intended for development and testing only.
     base_url : str
-        Override the default API base URL (useful for testing).
+        Deprecated. Prefer ``api_base``.
     max_retries : int
         Number of automatic retries on HTTP 429.  Defaults to
         ``DEFAULT_MAX_RETRIES`` (3).  Set to ``0`` to disable.
     timeout : float
         Per-request socket timeout in seconds.
     """
 
-    _DEFAULT_BASE_URL = "https://api.shadeprotocol.io/v1"
-
     def __init__(
         self,
         api_key: str = "",
+        environment: Environment = Environment.MAINNET,
+        api_base: Optional[str] = None,
         base_url: str = "",
         max_retries: int = DEFAULT_MAX_RETRIES,
         timeout: float = 30.0,
     ) -> None:
         if not api_key:
             raise ValueError("api_key must be a non-empty string")
         self.api_key = api_key
-        self._base_url = base_url or self._DEFAULT_BASE_URL
+        self.environment = environment
+
+        # Resolution order: explicit api_base > module-level shade.api_base
+        # > legacy base_url > environment URL
+        resolved = api_base or _config.api_base or base_url or environment.base_url
+        self._base_url = resolved.rstrip("/")
+
         self._http = SyncHTTPClient(
             base_url=self._base_url,
             api_key=api_key,
@@ -86,4 +102,4 @@ async def process_payment_async(
             "POST",
             "/payments",
             {"amount": amount, "currency": currency},
-        )
+        )

src/shade/http.py

@@ -10,14 +10,30 @@
 from __future__ import annotations
 
 import json
+import logging
 import math
+import random
 import time
 import urllib.error
 import urllib.parse
 import urllib.request
 from typing import Any, Dict, Optional, Tuple
 
-from .errors import HTTPError, RateLimitError
+from .errors import (
+    AuthenticationError,
+    HTTPError,
+    InvalidRequestError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+try:  # pragma: no cover - optional dependency
+    import httpx
+except ImportError:  # pragma: no cover - optional dependency
+    httpx = None
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -62,6 +78,72 @@ def _backoff_seconds(attempt: int) -> float:
     return min(_BASE_BACKOFF * math.pow(2, attempt), _MAX_BACKOFF)
 
 
+def _retry_delay(attempt: int, base_delay: float) -> float:
+    """Return a capped exponential delay with randomized jitter."""
+    return min(base_delay * (2**attempt) + random.uniform(0, 0.5), _MAX_BACKOFF)
+
+
+def _is_retryable_transport_error(exc: Exception) -> bool:
+    """Return True for transient network failures that should be retried."""
+    if httpx is not None and isinstance(exc, (httpx.ConnectError, httpx.TimeoutException)):
+        return True
+
+    try:
+        import aiohttp
+    except ImportError:
+        aiohttp = None
+
+    if aiohttp is not None and isinstance(
+        exc,
+        (
+            aiohttp.ClientConnectionError,
+            aiohttp.ClientConnectorError,
+            aiohttp.ClientOSError,
+            aiohttp.ServerDisconnectedError,
+        ),
+    ):
+        return True
+
+    if isinstance(exc, (ConnectionResetError, TimeoutError, urllib.error.URLError)):
+        return True
+    return False
+
+
+def _is_retryable_status(status: int) -> bool:
+    return status in {502, 503, 504}
+
+
+def _retry_with_backoff(fn, max_retries: int, base_delay: float):
+    """Execute *fn* and retry transient failures with exponential back-off."""
+    for attempt in range(max_retries + 1):
+        try:
+            return fn()
+        except Exception as exc:
+            if attempt >= max_retries or not _is_retryable_error(exc):
+                raise
+            delay = _retry_delay(attempt, base_delay)
+            logger.debug(
+                "Retrying request after transient failure (attempt %s/%s) in %.3fs",
+                attempt + 1,
+                max_retries + 1,
+                delay,
+            )
+            time.sleep(delay)
+
+
+def _is_retryable_error(exc: Exception) -> bool:
+    if _is_retryable_transport_error(exc):
+        return True
+
+    if httpx is not None and isinstance(exc, httpx.HTTPStatusError):
+        return _is_retryable_status(exc.response.status_code)
+
+    if isinstance(exc, HTTPError):
+        return _is_retryable_status(exc.status_code or 0)
+
+    return False
+
+
 def _raise_for_status(
     status: int,
     headers: Any,
@@ -81,6 +163,14 @@ def _raise_for_status(
     ------
     RateLimitError
         If HTTP 429 and retries are exhausted (or auto-retry is off).
+    InvalidRequestError
+        For HTTP 400 responses.
+    AuthenticationError
+        For HTTP 401/403 responses.
+    NotFoundError
+        For HTTP 404 responses.
+    NetworkError
+        For transient 502/503/504 responses after retries are exhausted.
     HTTPError
         For any other non-2xx status.
     """
@@ -100,6 +190,32 @@ def _raise_for_status(
         msg = f"Rate limit exceeded. {detail}".strip()
         raise RateLimitError(msg, retry_after=retry_after)
 
+    if status == 400:
+        raise InvalidRequestError("Invalid request", status_code=status)
+
+    if status in {401, 403}:
+        raise AuthenticationError("Authentication failed", status_code=status)
+
+    if status == 404:
+        response_body = body.decode("utf-8", errors="replace")
+        raise NotFoundError(
+            "Resource not found",
+            status_code=status,
+            response_body=response_body,
+        )
+
+    if status in {502, 503, 504}:
+        if attempt < max_retries:
+            wait = _retry_delay(attempt, _BASE_BACKOFF)
+            logger.debug(
+                "Retrying request after server error (attempt %s/%s) in %.3fs",
+                attempt + 1,
+                max_retries + 1,
+                wait,
+            )
+            return wait
+        raise NetworkError(f"Request failed with transient server error: {status}", status_code=status)
+
     try:
         detail = json.loads(body).get("error", {}).get("message", "")
     except Exception:
@@ -176,12 +292,29 @@ def request(
         attempt = 0
         while True:
             req = self._build_request(method, path, payload)
-            status, headers, body = self._execute(req)
+            try:
+                status, headers, body = self._execute(req)
+            except Exception as exc:
+                if _is_retryable_transport_error(exc):
+                    if attempt >= self.max_retries:
+                        raise NetworkError(
+                            "Request failed after exhausting retries",
+                            status_code=None,
+                        ) from exc
+                    delay = _retry_delay(attempt, _BASE_BACKOFF)
+                    logger.debug(
+                        "Retrying request after transient failure (attempt %s/%s) in %.3fs",
+                        attempt + 1,
+                        self.max_retries + 1,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                raise
             wait = _raise_for_status(status, headers, body, attempt, self.max_retries)
             if wait is None:
-                # success
                 return json.loads(body) if body else {}
-            # 429 — sleep and retry
             time.sleep(wait)
             attempt += 1
 
@@ -269,18 +402,36 @@ async def request(
         ) as session:
             while True:
                 url = f"{url_base}/{path.lstrip('/')}"
-                resp = await session.request(
-                    method.upper(),
-                    url,
-                    json=payload,
-                    headers=headers,
-                )
-                body = await resp.read()
+                try:
+                    resp = await session.request(
+                        method.upper(),
+                        url,
+                        json=payload,
+                        headers=headers,
+                    )
+                    body = await resp.read()
+                except Exception as exc:
+                    if _is_retryable_transport_error(exc):
+                        if attempt >= self.max_retries:
+                            raise NetworkError(
+                                "Request failed after exhausting retries",
+                                status_code=None,
+                            ) from exc
+                        delay = _retry_delay(attempt, _BASE_BACKOFF)
+                        logger.debug(
+                            "Retrying request after transient failure (attempt %s/%s) in %.3fs",
+                            attempt + 1,
+                            self.max_retries + 1,
+                            delay,
+                        )
+                        await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+                    raise
                 wait = _raise_for_status(
                     resp.status, resp.headers, body, attempt, self.max_retries
                 )
                 if wait is None:
                     return json.loads(body) if body else {}
-                # 429 — non-blocking sleep
                 await asyncio.sleep(wait)
                 attempt += 1