hud-python 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

hud/server/requests.py

@@ -11,95 +11,25 @@ from typing import Any
 
 import httpx
 
+from hud.exceptions import (
+    HudAuthenticationError,
+    HudNetworkError,
+    HudRequestError,
+    HudTimeoutError,
+)
+
 # Set up logger
 logger = logging.getLogger("hud.http")
 logger.setLevel(logging.DEBUG)
 
 
-class RequestError(Exception):
-    """Custom exception for API request errors"""
-
-    def __init__(
-        self,
-        message: str,
-        status_code: int | None = None,
-        response_text: str | None = None,
-        response_json: dict[str, Any] | None = None,
-        response_headers: dict[str, str] | None = None,
-    ) -> None:
-        self.message = message
-        self.status_code = status_code
-        self.response_text = response_text
-        self.response_json = response_json
-        self.response_headers = response_headers
-        super().__init__(message)
-
-    def __str__(self) -> str:
-        parts = [self.message]
-
-        if self.status_code:
-            parts.append(f"Status: {self.status_code}")
-
-        if self.response_text:
-            parts.append(f"Response Text: {self.response_text}")
-
-        if self.response_json:
-            parts.append(f"Response JSON: {self.response_json}")
-
-        if self.response_headers:
-            parts.append(f"Headers: {self.response_headers}")
-
-        return " | ".join(parts)
-
-    @classmethod
-    def from_http_error(
-        cls, error: httpx.HTTPStatusError, context: str = ""
-    ) -> RequestError:
-        """Create a RequestError from an HTTP error response"""
-        response = error.response
-        status_code = response.status_code
-        response_text = response.text
-        response_headers = dict(response.headers)
-
-        # Try to get detailed error info from JSON if available
-        response_json = None
-        try:
-            response_json = response.json()
-            detail = response_json.get("detail")
-            if detail:
-                message = f"Request failed: {detail}"
-            else:
-                # If no detail field but we have JSON, include a summary
-                message = f"Request failed with status {status_code}"
-                if (
-                    len(response_json) <= 5
-                ):  # If it's a small object, include it in the message
-                    message += f" - JSON response: {response_json}"
-        except Exception:
-            # Fallback to simple message if JSON parsing fails
-            message = f"Request failed with status {status_code}"
-
-        # Add context if provided
-        if context:
-            message = f"{context}: {message}"
-
-        # Log the error details
-        logger.error(
-            "HTTP error from HUD SDK: %s | URL: %s | Status: %s | Response: %s%s",
-            message,
-            response.url,
-            status_code,
-            response_text[:500],
-            "..." if len(response_text) > 500 else "",
-        )
-
-        return cls(
-            message=message,
-            status_code=status_code,
-            response_text=response_text,
-            response_json=response_json,
-            response_headers=response_headers,
-        )
+# Long running requests can take up to 10 minutes.
+_DEFAULT_TIMEOUT = 600.0
+_DEFAULT_LIMITS = httpx.Limits(
+    max_connections=1000,
+    max_keepalive_connections=1000,
+    keepalive_expiry=10.0,
+)
 
 
 async def _handle_retry(
@@ -118,6 +48,22 @@ async def _handle_retry(
     await asyncio.sleep(retry_time)
 
 
+def _create_default_async_client() -> httpx.AsyncClient:
+    """Create a default httpx AsyncClient with standard configuration."""
+    return httpx.AsyncClient(
+        timeout=_DEFAULT_TIMEOUT,
+        limits=_DEFAULT_LIMITS,
+    )
+
+
+def _create_default_sync_client() -> httpx.Client:
+    """Create a default httpx Client with standard configuration."""
+    return httpx.Client(
+        timeout=_DEFAULT_TIMEOUT,
+        limits=_DEFAULT_LIMITS,
+    )
+
+
 async def make_request(
     method: str,
     url: str,
@@ -125,6 +71,7 @@ async def make_request(
     api_key: str | None = None,
     max_retries: int = 4,
     retry_delay: float = 2.0,
+    client: httpx.AsyncClient | None = None,
 ) -> dict[str, Any]:
     """
     Make an asynchronous HTTP request to the HUD API.
@@ -136,62 +83,69 @@ async def make_request(
         api_key: API key for authentication
         max_retries: Maximum number of retries
         retry_delay: Delay between retries
+        *,
+        client: Optional custom httpx.AsyncClient
+
     Returns:
         dict: JSON response from the server
 
     Raises:
-        RequestError: If API key is missing or request fails
+        HudAuthenticationError: If API key is missing or invalid.
+        HudRequestError: If the request fails with a non-retryable status code.
+        HudNetworkError: If there are network-related issues.
+        HudTimeoutError: If the request times out.
     """
     if not api_key:
-        raise RequestError("API key is required but not provided")
+        raise HudAuthenticationError("API key is required but not provided")
 
     headers = {"Authorization": f"Bearer {api_key}"}
     retry_status_codes = [502, 503, 504]
     attempt = 0
-
-    while attempt <= max_retries:
-        attempt += 1
-
-        try:
-            async with httpx.AsyncClient(
-                timeout=600.0, # Long running requests can take up to 10 minutes
-                limits=httpx.Limits(
-                    max_connections=1000,
-                    max_keepalive_connections=1000,
-                    keepalive_expiry=10.0,
-                ),
-            ) as client:
-                response = await client.request(
-                    method=method, url=url, json=json, headers=headers
-                )
-
-            # Check if we got a retriable status code
-            if response.status_code in retry_status_codes and attempt <= max_retries:
-                await _handle_retry(
-                    attempt,
-                    max_retries,
-                    retry_delay,
-                    url,
-                    f"Received status {response.status_code}",
-                )
-                continue
-
-            response.raise_for_status()
-            result = response.json()
-            return result
-        except httpx.HTTPStatusError as e:
-            raise RequestError.from_http_error(e) from None
-        except httpx.RequestError as e:
-            if attempt <= max_retries:
-                await _handle_retry(
-                    attempt, max_retries, retry_delay, url, f"Network error: {e}"
-                )
-                continue
-            else:
-                raise RequestError(f"Network error: {e!s}") from None
-        except Exception as e:
-            raise RequestError(f"Unexpected error: {e!s}") from None
-    raise RequestError(f"Request failed after {max_retries} retries with unknown error")
+    should_close_client = False
+
+    if client is None:
+        client = _create_default_async_client()
+        should_close_client = True
+
+    try:
+        while attempt <= max_retries:
+            attempt += 1
+
+            try:
+                response = await client.request(method=method, url=url, json=json, headers=headers)
+
+                # Check if we got a retriable status code
+                if response.status_code in retry_status_codes and attempt <= max_retries:
+                    await _handle_retry(
+                        attempt,
+                        max_retries,
+                        retry_delay,
+                        url,
+                        f"Received status {response.status_code}",
+                    )
+                    continue
+
+                response.raise_for_status()
+                result = response.json()
+                return result
+            except httpx.TimeoutException as e:
+                raise HudTimeoutError(f"Request timed out: {e!s}") from None
+            except httpx.HTTPStatusError as e:
+                raise HudRequestError.from_httpx_error(e) from None
+            except httpx.RequestError as e:
+                if attempt <= max_retries:
+                    await _handle_retry(
+                        attempt, max_retries, retry_delay, url, f"Network error: {e}"
+                    )
+                    continue
+                else:
+                    raise HudNetworkError(f"Network error: {e!s}") from None
+            except Exception as e:
+                raise HudRequestError(f"Unexpected error: {e!s}") from None
+        raise HudRequestError(f"Request failed after {max_retries} retries with unknown error")
+    finally:
+        if should_close_client:
+            await client.aclose()
 
 
 def make_request_sync(
@@ -201,6 +155,8 @@ def make_request_sync(
     api_key: str | None = None,
     max_retries: int = 4,
     retry_delay: float = 2.0,
+    *,
+    client: httpx.Client | None = None,
 ) -> dict[str, Any]:
     """
     Make a synchronous HTTP request to the HUD API.
@@ -212,69 +168,75 @@ def make_request_sync(
         api_key: API key for authentication
         max_retries: Maximum number of retries
         retry_delay: Delay between retries
+        client: Optional custom httpx.Client
+
     Returns:
         dict: JSON response from the server
 
     Raises:
-        RequestError: If API key is missing or request fails
+        HudAuthenticationError: If API key is missing or invalid.
+        HudRequestError: If the request fails with a non-retryable status code.
+        HudNetworkError: If there are network-related issues.
+        HudTimeoutError: If the request times out.
     """
     if not api_key:
-        raise RequestError("API key is required but not provided")
+        raise HudAuthenticationError("API key is required but not provided")
 
     headers = {"Authorization": f"Bearer {api_key}"}
     retry_status_codes = [502, 503, 504]
     attempt = 0
-
-    while attempt <= max_retries:
-        attempt += 1
-
-        try:
-            with httpx.Client(
-                timeout=600.0, # Long running requests can take up to 10 minutes
-                limits=httpx.Limits(
-                    max_connections=1000,
-                    max_keepalive_connections=1000,
-                    keepalive_expiry=10.0,
-                ),
-            ) as client:
-                response = client.request(
-                    method=method, url=url, json=json, headers=headers
-                )
-
-            # Check if we got a retriable status code
-            if response.status_code in retry_status_codes and attempt <= max_retries:
-                retry_time = retry_delay * (2 ** (attempt - 1))  # Exponential backoff
-                logger.warning(
-                    "Received status %d from %s, retrying in %.2f seconds (attempt %d/%d)",
-                    response.status_code,
-                    url,
-                    retry_time,
-                    attempt,
-                    max_retries,
-                )
-                time.sleep(retry_time)
-                continue
-
-            response.raise_for_status()
-            result = response.json()
-            return result
-        except httpx.HTTPStatusError as e:
-            raise RequestError.from_http_error(e) from None
-        except httpx.RequestError as e:
-            if attempt <= max_retries:
-                retry_time = retry_delay * (2 ** (attempt - 1))
-                logger.warning(
-                    "Network error %s from %s, retrying in %.2f seconds (attempt %d/%d)",
-                    str(e),
-                    url,
-                    retry_time,
-                    attempt,
-                    max_retries,
-                )
-                time.sleep(retry_time)
-                continue
-            else:
-                raise RequestError(f"Network error: {e!s}") from None
-        except Exception as e:
-            raise RequestError(f"Unexpected error: {e!s}") from None
-    raise RequestError(f"Request failed after {max_retries} retries with unknown error")
+    should_close_client = False
+
+    if client is None:
+        client = _create_default_sync_client()
+        should_close_client = True
+
+    try:
+        while attempt <= max_retries:
+            attempt += 1
+
+            try:
+                response = client.request(method=method, url=url, json=json, headers=headers)
+
+                # Check if we got a retriable status code
+                if response.status_code in retry_status_codes and attempt <= max_retries:
+                    retry_time = retry_delay * (2 ** (attempt - 1))  # Exponential backoff
+                    logger.warning(
+                        "Received status %d from %s, retrying in %.2f seconds (attempt %d/%d)",
+                        response.status_code,
+                        url,
+                        retry_time,
+                        attempt,
+                        max_retries,
+                    )
+                    time.sleep(retry_time)
+                    continue
+
+                response.raise_for_status()
+                result = response.json()
+                return result
+            except httpx.TimeoutException as e:
+                raise HudTimeoutError(f"Request timed out: {e!s}") from None
+            except httpx.HTTPStatusError as e:
+                raise HudRequestError.from_httpx_error(e) from None
+            except httpx.RequestError as e:
+                if attempt <= max_retries:
+                    retry_time = retry_delay * (2 ** (attempt - 1))
+                    logger.warning(
+                        "Network error %s from %s, retrying in %.2f seconds (attempt %d/%d)",
+                        str(e),
+                        url,
+                        retry_time,
+                        attempt,
+                        max_retries,
+                    )
+                    time.sleep(retry_time)
+                    continue
+                else:
+                    raise HudNetworkError(f"Network error: {e!s}") from None
+            except Exception as e:
+                raise HudRequestError(f"Unexpected error: {e!s}") from None
+        raise HudRequestError(f"Request failed after {max_retries} retries with unknown error")
+    finally:
+        if should_close_client:
+            client.close()

hud/server/tests/test_requests.py

@@ -0,0 +1,275 @@
+"""Tests for the HTTP request utilities in the HUD API."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any
+from unittest.mock import AsyncMock, Mock, patch
+
+import httpx
+import pytest
+
+from hud.exceptions import (
+    HudAuthenticationError,
+    HudNetworkError,
+    HudRequestError,
+    HudTimeoutError,
+)
+from hud.server.requests import (
+    _handle_retry,
+    make_request,
+    make_request_sync,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def _create_mock_response(
+    status_code: int = 200,
+    json_data: dict[str, Any] | None = None,
+    raise_exception: Exception | None = None,
+) -> Callable[[httpx.Request], httpx.Response]:
+    """Create a mock response handler for httpx.MockTransport."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if "Authorization" not in request.headers:
+            return httpx.Response(HTTPStatus.UNAUTHORIZED, json={"error": "Unauthorized"})
+
+        if raise_exception:
+            raise raise_exception
+
+        return httpx.Response(status_code, json=json_data or {"result": "success"}, request=request)
+
+    return handler
+
+
+@pytest.mark.asyncio
+async def test_handle_retry():
+    """Test the retry handler."""
+    with patch("asyncio.sleep") as mock_sleep:
+        mock_sleep.return_value = None
+        await _handle_retry(
+            attempt=2,
+            max_retries=3,
+            retry_delay=1.0,
+            url="https://example.com",
+            error_msg="Test error",
+        )
+
+        # Check exponential backoff formula: delay * (2 ^ (attempt - 1))
+        mock_sleep.assert_awaited_once_with(2.0)
+
+
+@pytest.mark.asyncio
+async def test_make_request_success():
+    """Test successful async request."""
+    expected_data = {"id": "123", "name": "test"}
+    async_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(_create_mock_response(200, expected_data))
+    )
+    result = await make_request(
+        "GET", "https://api.test.com/data", api_key="test-key", client=async_client
+    )
+    assert result == expected_data
+
+
+@pytest.mark.asyncio
+async def test_make_request_no_api_key():
+    """Test request without API key."""
+    with pytest.raises(HudAuthenticationError):
+        await make_request("GET", "https://api.test.com/data", api_key=None)
+
+
+@pytest.mark.asyncio
+async def test_make_request_http_error():
+    """Test HTTP error handling."""
+    async_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(_create_mock_response(404, {"error": "Not found"}))
+    )
+
+    with pytest.raises(HudRequestError) as excinfo:
+        await make_request(
+            "GET", "https://api.test.com/data", api_key="test-key", client=async_client
+        )
+
+    assert "404" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_make_request_network_error():
+    """Test network error handling with retry exhaustion."""
+    request_error = httpx.RequestError(
+        "Connection error", request=httpx.Request("GET", "https://api.test.com")
+    )
+    async_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=request_error))
+    )
+
+    # Replace handle_retry to avoid sleep
+    with patch("hud.server.requests._handle_retry", AsyncMock()) as mock_retry:
+        mock_retry.return_value = None
+
+        with pytest.raises(HudNetworkError) as excinfo:
+            await make_request(
+                "GET",
+                "https://api.test.com/data",
+                api_key="test-key",
+                max_retries=2,
+                retry_delay=0.01,
+                client=async_client,
+            )
+
+        assert "Connection error" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_make_request_timeout():
+    """Test timeout error handling."""
+    timeout_error = httpx.TimeoutException(
+        "Request timed out", request=httpx.Request("GET", "https://api.test.com")
+    )
+    async_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=timeout_error))
+    )
+
+    with pytest.raises(HudTimeoutError) as excinfo:
+        await make_request(
+            "GET", "https://api.test.com/data", api_key="test-key", client=async_client
+        )
+
+    assert "timed out" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_make_request_unexpected_error():
+    """Test handling of unexpected errors."""
+    unexpected_error = ValueError("Unexpected error")
+    async_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=unexpected_error))
+    )
+    with pytest.raises(HudRequestError) as excinfo:
+        await make_request(
+            "GET", "https://api.test.com/data", api_key="test-key", client=async_client
+        )
+
+    assert "Unexpected error" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_make_request_auto_client_creation(mocker):
+    """Test automatic client creation when not provided."""
+    mock_create_client = mocker.patch("hud.server.requests._create_default_async_client")
+    mock_client = AsyncMock()
+    mock_client.request.return_value = httpx.Response(
+        200, json={"result": "success"}, request=httpx.Request("GET", "https://api.test.com")
+    )
+    mock_client.aclose = AsyncMock()
+    mock_create_client.return_value = mock_client
+
+    result = await make_request("GET", "https://api.test.com/data", api_key="test-key")
+
+    assert result == {"result": "success"}
+    mock_client.aclose.assert_awaited_once()
+
+
+def test_make_request_sync_success():
+    """Test successful sync request."""
+    expected_data = {"id": "123", "name": "test"}
+    sync_client = httpx.Client(
+        transport=httpx.MockTransport(_create_mock_response(200, expected_data))
+    )
+
+    result = make_request_sync(
+        "GET", "https://api.test.com/data", api_key="test-key", client=sync_client
+    )
+
+    assert result == expected_data
+
+
+def test_make_request_sync_no_api_key():
+    """Test sync request without API key."""
+    with pytest.raises(HudAuthenticationError):
+        make_request_sync("GET", "https://api.test.com/data", api_key=None)
+
+
+def test_make_request_sync_http_error():
+    """Test HTTP error handling."""
+    sync_client = httpx.Client(
+        transport=httpx.MockTransport(_create_mock_response(404, {"error": "Not found"}))
+    )
+    with pytest.raises(HudRequestError) as excinfo:
+        make_request_sync(
+            "GET", "https://api.test.com/data", api_key="test-key", client=sync_client
+        )
+
+    assert "404" in str(excinfo.value)
+
+
+def test_make_request_sync_network_error():
+    """Test network error handling with retry exhaustion."""
+    request_error = httpx.RequestError(
+        "Connection error", request=httpx.Request("GET", "https://api.test.com")
+    )
+    sync_client = httpx.Client(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=request_error))
+    )
+    with patch("time.sleep", lambda _: None):
+        with pytest.raises(HudNetworkError) as excinfo:
+            make_request_sync(
+                "GET",
+                "https://api.test.com/data",
+                api_key="test-key",
+                max_retries=2,
+                retry_delay=0.01,
+                client=sync_client,
+            )
+
+        assert "Connection error" in str(excinfo.value)
+
+
+def test_make_request_sync_timeout():
+    """Test timeout error handling."""
+    timeout_error = httpx.TimeoutException(
+        "Request timed out", request=httpx.Request("GET", "https://api.test.com")
+    )
+    sync_client = httpx.Client(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=timeout_error))
+    )
+    with pytest.raises(HudTimeoutError) as excinfo:
+        make_request_sync(
+            "GET", "https://api.test.com/data", api_key="test-key", client=sync_client
+        )
+
+    assert "timed out" in str(excinfo.value)
+
+
+def test_make_request_sync_unexpected_error():
+    """Test handling of unexpected errors."""
+    unexpected_error = ValueError("Unexpected error")
+    sync_client = httpx.Client(
+        transport=httpx.MockTransport(_create_mock_response(raise_exception=unexpected_error))
+    )
+
+    with pytest.raises(HudRequestError) as excinfo:
+        make_request_sync(
+            "GET", "https://api.test.com/data", api_key="test-key", client=sync_client
+        )
+
+    assert "Unexpected error" in str(excinfo.value)
+
+
+def test_make_request_sync_auto_client_creation():
+    """Test automatic client creation when not provided."""
+    with patch("hud.server.requests._create_default_sync_client") as mock_create_client:
+        mock_client = Mock()
+        mock_client.request.return_value = httpx.Response(
+            200, json={"result": "success"}, request=httpx.Request("GET", "https://api.test.com")
+        )
+        mock_client.close = Mock()
+        mock_create_client.return_value = mock_client
+
+        result = make_request_sync("GET", "https://api.test.com/data", api_key="test-key")
+
+        assert result == {"result": "success"}
+        mock_client.close.assert_called_once()