feat: add AsyncHyperpingClient with full async surface (SDK-PY-03) (#13)

* feat: add AsyncHyperpingClient with full async surface (SDK-PY-03)

Introduces AsyncHyperpingClient backed by httpx.AsyncClient with the
same retry, circuit-breaker, and error-mapping logic as HyperpingClient,
but using await/asyncio.sleep throughout. Adds six async mixin modules,
_AsyncClientProtocol base class, pytest-asyncio dependency, and 40 new
async unit tests covering all major code paths.

* fix: address all PR #12 and PR #13 review issues

- Extract shared internals to _internals.py (RETRY_AFTER_MAX, DEFAULT_USER_AGENT,
  sanitize_for_log) to eliminate private cross-module imports in _async_client.py
- Extract monitor constants to _monitor_constants.py (VALID_PERIODS,
  MONITOR_WRITABLE_FIELDS) to eliminate duplication between sync/async mixins
- Add collect_all_pages_async() to _utils.py for async pagination parity
- Bring _async_outages_mixin.py to full feature parity: add page/status/outage_type
  params with validation and auto-pagination via collect_all_pages_async
- Bring _async_statuspages_mixin.py to full feature parity: add page/search to
  list_status_pages and page/subscriber_type to list_subscribers
- Fix _statuspages_mixin.py: remove dead params-or-None in explicit-page branches,
  add HyperpingNotFoundError guard on collect_all_pages for list_status_pages
- Fix pyproject.toml: pytest-asyncio version was 1.3.0 (non-existent), corrected to 0.23.0
- Add tests for new async pagination paths; coverage now at 86.88%

Author: KhaledSalhab-Develeap

pyproject.toml

@@ -56,6 +56,7 @@ exclude = [".claude/", ".github/", "dist/", "uv.lock", "BACKLOG.md"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "--cov=hyperping --cov-report=term-missing --cov-fail-under=85"
+asyncio_mode = "auto"
 
 [tool.mypy]
 python_version = "3.11"
@@ -68,3 +69,8 @@ target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=0.23.0",
+]

src/hyperping/__init__.py

@@ -14,6 +14,7 @@
             print(f"{m.name}: {'down' if m.down else 'up'}")
 """
 
+from hyperping._async_client import AsyncHyperpingClient
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -78,7 +79,8 @@
 __all__ = [
     # Version
     "__version__",
-    # Client
+    # Clients
+    "AsyncHyperpingClient",
     "HyperpingClient",
     # Configuration
     "RetryConfig",

src/hyperping/_async_client.py

@@ -0,0 +1,351 @@
+"""Async Hyperping API client with retry logic and error handling.
+
+This module provides the :class:`AsyncHyperpingClient` class, a fully async
+counterpart to :class:`~hyperping.client.HyperpingClient`.
+
+Example::
+
+    async with AsyncHyperpingClient(api_key="sk_...") as client:
+        monitors = await client.list_monitors()
+        for m in monitors:
+            print(f"{m.name}: {'down' if m.down else 'up'}")
+"""
+
+import asyncio
+import logging
+import random
+from typing import Any
+
+import httpx
+from pydantic import SecretStr
+
+from hyperping._async_healthchecks_mixin import AsyncHealthchecksMixin
+from hyperping._async_incidents_mixin import AsyncIncidentsMixin
+from hyperping._async_maintenance_mixin import AsyncMaintenanceMixin
+from hyperping._async_monitors_mixin import AsyncMonitorsMixin
+from hyperping._async_outages_mixin import AsyncOutagesMixin
+from hyperping._async_statuspages_mixin import AsyncStatusPagesMixin
+from hyperping._circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+)
+from hyperping._internals import DEFAULT_USER_AGENT, RETRY_AFTER_MAX, sanitize_for_log
+from hyperping.client import DEFAULT_RETRY_CONFIG, RetryConfig
+from hyperping.endpoints import API_BASE
+from hyperping.exceptions import (
+    HyperpingAPIError,
+    HyperpingAuthError,
+    HyperpingRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncHyperpingClient(
+    AsyncMonitorsMixin,
+    AsyncIncidentsMixin,
+    AsyncMaintenanceMixin,
+    AsyncOutagesMixin,
+    AsyncStatusPagesMixin,
+    AsyncHealthchecksMixin,
+):
+    """Async client for interacting with the Hyperping API.
+
+    Handles authentication, retry logic, and error mapping using
+    ``httpx.AsyncClient`` for non-blocking I/O.
+
+    Example::
+
+        async with AsyncHyperpingClient(api_key="sk_xxx") as client:
+            monitors = await client.list_monitors()
+            for m in monitors:
+                print(f"{m.name}: {'down' if m.down else 'up'}")
+    """
+
+    DEFAULT_BASE_URL = API_BASE
+    DEFAULT_TIMEOUT = 30.0
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry_config: RetryConfig | None = None,
+        circuit_breaker_config: CircuitBreakerConfig | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        """Initialize the async Hyperping API client.
+
+        Args:
+            api_key: Hyperping API key (starts with ``sk_``). Accepts a plain
+                string or a :class:`pydantic.SecretStr`.
+            base_url: Override the default API base URL.
+            timeout: HTTP request timeout in seconds.
+            retry_config: Retry behaviour configuration.
+            circuit_breaker_config: Circuit breaker configuration.
+            user_agent: Custom ``User-Agent`` header value.
+        """
+        raw_key = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
+        if not raw_key or not raw_key.strip():
+            raise ValueError("api_key must be a non-empty string")
+        self._api_key = SecretStr(raw_key) if isinstance(api_key, str) else api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.retry_config = retry_config or DEFAULT_RETRY_CONFIG
+        self._circuit_breaker = CircuitBreaker(circuit_breaker_config)
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self._api_key.get_secret_value()}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": user_agent or DEFAULT_USER_AGENT,
+            },
+            timeout=self.timeout,
+        )
+
+    def __repr__(self) -> str:
+        return f"AsyncHyperpingClient(base_url={self.base_url!r})"
+
+    async def close(self) -> None:
+        """Close the async HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHyperpingClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    @property
+    def circuit_breaker(self) -> CircuitBreaker:
+        """Access the circuit breaker state (for monitoring)."""
+        return self._circuit_breaker
+
+    # ==================== Error Handling ====================
+
+    def _parse_error_body(self, response: httpx.Response) -> dict[str, Any]:
+        """Parse the JSON body from an error response."""
+        try:
+            return response.json()  # type: ignore[no-any-return]
+        except (ValueError, httpx.DecodingError):
+            return {"error": response.text or "Unknown error"}
+
+    def _parse_retry_after(self, response: httpx.Response) -> int | None:
+        """Extract and parse the ``Retry-After`` header value."""
+        retry_after = response.headers.get("Retry-After")
+        if not retry_after:
+            return None
+        try:
+            return int(retry_after)
+        except ValueError:
+            return None
+
+    def _handle_response_error(self, response: httpx.Response) -> None:
+        """Map HTTP errors to typed exceptions."""
+        from hyperping.exceptions import (
+            HyperpingNotFoundError,
+            HyperpingValidationError,
+        )
+
+        status = response.status_code
+        request_id = response.headers.get("x-request-id")
+        body = self._parse_error_body(response)
+        error_msg = body.get("error") or body.get("message") or f"HTTP {status}"
+
+        if status in (401, 403):
+            raise HyperpingAuthError(
+                message=f"Authentication failed: {error_msg}",
+                status_code=status,
+                response_body=None,
+                request_id=request_id,
+            )
+        if status == 404:
+            raise HyperpingNotFoundError(
+                message=f"Resource not found: {error_msg}",
+                status_code=status,
+                response_body=body,
+                request_id=request_id,
+            )
+        if status == 429:
+            raise HyperpingRateLimitError(
+                message=f"Rate limit exceeded: {error_msg}",
+                status_code=status,
+                response_body=body,
+                retry_after=self._parse_retry_after(response),
+                request_id=request_id,
+            )
+        if status in (400, 422):
+            from hyperping.exceptions import HyperpingValidationError
+            raise HyperpingValidationError(
+                message=f"Validation error: {error_msg}",
+                status_code=status,
+                response_body=body,
+                validation_errors=body.get("details") or body.get("errors"),
+                request_id=request_id,
+            )
+        raise HyperpingAPIError(
+            message=f"API error: {error_msg}",
+            status_code=status,
+            response_body=body,
+            request_id=request_id,
+        )
+
+    # ==================== Request Helpers ====================
+
+    def _compute_sleep_time(self, response: httpx.Response, delay: float) -> float:
+        """Compute how long to sleep before retrying a failed request."""
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            if retry_after:
+                try:
+                    return min(float(retry_after), RETRY_AFTER_MAX)
+                except (ValueError, OverflowError):
+                    pass
+        return delay + random.uniform(0, delay * 0.25)
+
+    def _should_retry(self, status_code: int, attempt: int) -> bool:
+        """Return True if this status/attempt combination warrants a retry."""
+        return (
+            status_code in self.retry_config.retry_on_status
+            and attempt < self.retry_config.max_retries
+        )
+
+    async def _execute_single_attempt(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]] | httpx.Response:
+        """Execute a single async HTTP request attempt."""
+        logger.debug(
+            "API request: %s %s (attempt)",
+            method,
+            path,
+            extra={
+                "json": sanitize_for_log(json),
+                "params": sanitize_for_log(params),
+            },
+        )
+
+        response = await self._client.request(method=method, url=path, json=json, params=params)
+
+        if response.status_code >= 400:
+            return response
+
+        self._circuit_breaker.record_success()
+        if response.status_code == 204:
+            return {}
+        return response.json()  # type: ignore[no-any-return]
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        """Make an async HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API path (e.g., Endpoint.MONITORS)
+            json: Request body as dict
+            params: Query parameters
+
+        Returns:
+            Response body as dict or list
+
+        Raises:
+            HyperpingAPIError: On API errors after retries exhausted
+        """
+        if not self._circuit_breaker.call_allowed():
+            cb = self._circuit_breaker
+            raise HyperpingAPIError(
+                f"Circuit breaker OPEN - API calls suspended. "
+                f"Consecutive failures: {cb.failure_count}. "
+                f"Will recover after {cb.recovery_timeout}s."
+            )
+
+        last_exception: Exception | None = None
+        delay = self.retry_config.initial_delay
+        max_attempts = self.retry_config.max_retries + 1
+
+        for attempt in range(max_attempts):
+            try:
+                result = await self._execute_single_attempt(method, path, json, params)
+
+                if not isinstance(result, httpx.Response):
+                    return result
+
+                response = result
+                if self._should_retry(response.status_code, attempt):
+                    sleep_time = self._compute_sleep_time(response, delay)
+                    logger.warning(
+                        "Retrying after %.2fs due to %d (attempt %d/%d)",
+                        sleep_time,
+                        response.status_code,
+                        attempt + 1,
+                        max_attempts,
+                    )
+                    await asyncio.sleep(sleep_time)
+                    delay = min(
+                        delay * self.retry_config.backoff_factor,
+                        self.retry_config.max_delay,
+                    )
+                    continue
+
+                if response.status_code >= 500:
+                    self._circuit_breaker.record_failure()
+                self._handle_response_error(response)
+
+            except (httpx.TimeoutException, httpx.RequestError) as e:
+                last_exception = e
+                if attempt < self.retry_config.max_retries:
+                    label = "timeout" if isinstance(e, httpx.TimeoutException) else str(e)
+                    sleep_time = delay + random.uniform(0, delay * 0.25)
+                    logger.warning(
+                        "Request %s, retrying after %.2fs (attempt %d/%d)",
+                        label,
+                        sleep_time,
+                        attempt + 1,
+                        max_attempts,
+                    )
+                    await asyncio.sleep(sleep_time)
+                    delay = min(
+                        delay * self.retry_config.backoff_factor,
+                        self.retry_config.max_delay,
+                    )
+                    continue
+                self._circuit_breaker.record_failure()
+                if isinstance(e, httpx.TimeoutException):
+                    raise HyperpingAPIError(
+                        f"Request timeout after {max_attempts} attempts"
+                    ) from e
+                raise HyperpingAPIError(f"Request failed: {e}") from e
+
+        raise HyperpingAPIError(  # pragma: no cover
+            "Request failed after all retries"
+        ) from last_exception
+
+    # ==================== Health Check ====================
+
+    async def ping(self) -> bool:
+        """Test API connectivity and authentication.
+
+        Returns:
+            True if connection successful
+
+        Raises:
+            HyperpingAuthError: If authentication fails
+            HyperpingAPIError: If connection fails
+        """
+        try:
+            await self.list_monitors()
+            return True
+        except HyperpingAuthError:
+            raise
+        except (HyperpingAPIError, httpx.RequestError, httpx.TimeoutException) as e:
+            raise HyperpingAPIError(f"API connectivity test failed: {e}") from e