feat(streaming): async streaming helpers for long-poll endpoints (PY-10)

pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
  "Environment :: Console",
 ]
 dependencies = [
- "httpx>=0.27,<1.0",
+ "httpx2>=2.4,<3.0",
  "pydantic>=2.0,<3.0",
 ]
 

src/hyperping/__init__.py

@@ -41,7 +41,9 @@
 from hyperping.models import (
  DEFAULT_REGIONS,
  AddIncidentUpdateRequest,
+ Alert,
  AlertHistory,
+ AlertType,
  DnsRecordType,
  EscalationPolicy,
  EscalationStep,
@@ -121,6 +123,9 @@
  "HyperpingNotFoundError",
  "HyperpingRateLimitError",
  "HyperpingValidationError",
+ # Alert models (PY-10: provisional, reconcile when alerts endpoint ships)
+ "Alert",
+ "AlertType",
  # Monitor enums
  "HttpMethod",
  "MonitorFrequency",

src/hyperping/_async_client.py

@@ -20,7 +20,7 @@
 from typing import Any
 from urllib.parse import urlsplit
 
-import httpx
+import httpx2 as httpx
 from pydantic import SecretStr
 
 from hyperping._async_healthchecks_mixin import AsyncHealthchecksMixin
@@ -29,6 +29,7 @@
 from hyperping._async_monitors_mixin import AsyncMonitorsMixin
 from hyperping._async_outages_mixin import AsyncOutagesMixin
 from hyperping._async_statuspages_mixin import AsyncStatusPagesMixin
+from hyperping._async_streaming_mixin import AsyncStreamingMixin
 from hyperping._circuit_breaker import (
  CircuitBreaker,
  CircuitBreakerConfig,
@@ -58,6 +59,7 @@ class AsyncHyperpingClient(
  AsyncOutagesMixin,
  AsyncStatusPagesMixin,
  AsyncHealthchecksMixin,
+ AsyncStreamingMixin,
 ):
  """Async client for interacting with the Hyperping API.
 

src/hyperping/_async_mcp_transport.py

@@ -9,7 +9,7 @@
 import time
 from typing import Any
 
-import httpx
+import httpx2 as httpx
 from pydantic import SecretStr
 
 from hyperping._internals import validate_base_url

src/hyperping/_async_streaming_mixin.py

@@ -0,0 +1,113 @@
+"""Async streaming helpers for event-driven integrations (PY-10).
+
+Provides poll-based AsyncIterator helpers on top of existing REST endpoints.
+Public signatures are stable; only the poll internals change when Hyperping
+ships SSE or a discrete alerts endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from hyperping._protocols import _AsyncClientProtocol
+from hyperping._utils import parse_list, unwrap_list, validate_id
+from hyperping.endpoints import Endpoint
+from hyperping.models import IncidentUpdate, Monitor
+from hyperping.models._alert_models import Alert, AlertType
+
+if TYPE_CHECKING:
+ from hyperping.models import Incident
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncStreamingMixin(_AsyncClientProtocol):
+ """Poll-based streaming helpers for alert and incident monitoring."""
+
+ if TYPE_CHECKING:
+
+ async def get_incident(self, incident_id: str) -> Incident: ...
+
+ async def stream_alerts(self, *, poll_interval: float = 30.0) -> AsyncIterator[Alert]:
+ """Stream monitor state-transition events.
+
+ Polls ``GET /v1/monitors`` at *poll_interval* seconds. Yields an
+ :class:`~hyperping.models.Alert` on each up/down state change.
+ The first poll establishes the baseline and yields nothing.
+
+ Rate-limit note: at the default 30-second interval this uses
+ 2 requests/min, roughly 0.67% of the 300 req/min account limit.
+
+ Args:
+ poll_interval: Seconds between polls. Defaults to 30.0.
+
+ Yields:
+ :class:`~hyperping.models.Alert` on each monitor state transition.
+
+ Note:
+ This implementation is provisional. The ``Alert`` model fields are
+ inferred from the monitors list endpoint. When Hyperping ships a
+ dedicated alerts endpoint, the model will be reconciled and the
+ poll internals replaced with SSE or long-poll without any change
+ to this method's signature.
+ """
+ baseline: dict[str, bool] = {}
+
+ while True:
+ response = await self._request("GET", Endpoint.MONITORS)
+ monitors = parse_list(unwrap_list(response, "monitors"), Monitor, "monitor")
+
+ for monitor in monitors:
+ uuid = monitor.uuid
+ down = monitor.down
+
+ if uuid in baseline and baseline[uuid] != down:
+ alert_type = AlertType.DOWN if down else AlertType.UP
+ yield Alert(
+ monitor_uuid=uuid,
+ monitor_name=monitor.name,
+ type=alert_type,
+ timestamp=datetime.now(UTC).isoformat(),
+ )
+
+ baseline[uuid] = down
+
+ await asyncio.sleep(poll_interval)
+
+ async def stream_incident_updates(
+ self, incident_uuid: str, *, poll_interval: float = 30.0
+ ) -> AsyncIterator[IncidentUpdate]:
+ """Stream new updates for an incident.
+
+ Polls ``GET /v3/incidents/{uuid}`` at *poll_interval* seconds. Yields
+ each :class:`~hyperping.models.IncidentUpdate` exactly once, deduped
+ by update UUID. All updates present on the first poll are yielded
+ immediately; only new updates are yielded on subsequent polls.
+
+ Args:
+ incident_uuid: UUID of the incident to watch.
+ poll_interval: Seconds between polls. Defaults to 30.0.
+
+ Yields:
+ :class:`~hyperping.models.IncidentUpdate` for each new update.
+
+ Raises:
+ ValueError: If *incident_uuid* contains unsafe characters.
+ HyperpingNotFoundError: If the incident does not exist (first poll).
+ """
+ validate_id(incident_uuid, "incident_uuid")
+ seen: set[str] = set()
+
+ while True:
+ incident = await self.get_incident(incident_uuid)
+
+ for update in incident.updates:
+ if update.uuid not in seen:
+ seen.add(update.uuid)
+ yield update
+
+ await asyncio.sleep(poll_interval)

src/hyperping/_internals.py

@@ -83,20 +83,11 @@ def validate_base_url(
  # (``https://@host``, ``https://:@host``). ``parts.username`` is an empty
  # string in those cases, so the previous ``or`` truthiness guard let them
  # through. Checking the raw authority for ``@`` is exhaustive.
- if (
- "@" in parts.netloc
- or parts.username is not None
- or parts.password is not None
- ):
- raise ValueError(
- f"{param_name} must not embed userinfo (credentials) in the URL"
- )
+ if "@" in parts.netloc or parts.username is not None or parts.password is not None:
+ raise ValueError(f"{param_name} must not embed userinfo (credentials) in the URL")
 
  if parts.query or parts.fragment:
- raise ValueError(
- f"{param_name} must not carry a query string or fragment "
- f"(got {url!r})"
- )
+ raise ValueError(f"{param_name} must not carry a query string or fragment (got {url!r})")
 
  if parts.scheme == "http":
  if not allow_insecure:

src/hyperping/_mcp_transport.py

@@ -9,7 +9,7 @@
 import time
 from typing import Any
 
-import httpx
+import httpx2 as httpx
 from pydantic import SecretStr
 
 from hyperping._internals import validate_base_url

src/hyperping/client.py

@@ -18,7 +18,7 @@
 from typing import Any
 from urllib.parse import urlsplit
 
-import httpx
+import httpx2 as httpx
 from pydantic import SecretStr
 
 from hyperping._circuit_breaker import (

src/hyperping/models/__init__.py

@@ -9,6 +9,7 @@
 be removed in v0.3.0.
 """
 
+from hyperping.models._alert_models import Alert, AlertType
 from hyperping.models._healthcheck_models import (
  Healthcheck,
  HealthcheckCreate,
@@ -86,6 +87,9 @@
 )
 
 __all__ = [
+ # Alert models (PY-10: provisional, reconcile when alerts endpoint ships)
+ "Alert",
+ "AlertType",
  # Shared primitives
  "LocalizedText",
  "RequestHeader",

src/hyperping/models/_alert_models.py

@@ -0,0 +1,36 @@
+"""Alert models for streaming helpers (PY-10).
+
+This module is provisional. The Alert model fields are derived from the monitors
+list endpoint. When Hyperping ships a discrete alerts endpoint, the model will
+be reconciled with the real API shape.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AlertType(StrEnum):
+ """Alert transition type."""
+
+ DOWN = "down"
+ UP = "up"
+ DEGRADED = "degraded"
+
+
+class Alert(BaseModel):
+ """A monitor state-transition event yielded by stream_alerts.
+
+ Provisional model: fields are inferred from the monitors list endpoint.
+ When Hyperping ships a dedicated alerts endpoint, this model will be
+ reconciled against the real API shape.
+ """
+
+ model_config = ConfigDict(extra="allow", populate_by_name=True, frozen=True)
+
+ monitor_uuid: str = Field(..., alias="monitorUuid")
+ monitor_name: str = Field(..., alias="monitorName")
+ type: AlertType = Field(...)
+ timestamp: str = Field(...)

tests/unit/conftest.py

@@ -3,10 +3,22 @@
 from collections.abc import Generator
 
 import pytest
+from respx.mocks import HTTPCoreMocker
 
 from hyperping.client import HyperpingClient, RetryConfig
 from hyperping.endpoints import API_BASE
 
+# httpx2 uses httpcore2 instead of httpcore; extend respx's default mocker so
+# that @respx.mock intercepts requests made through httpx2 clients.
+HTTPCoreMocker.add_targets(
+ "httpcore2._sync.connection.HTTPConnection",
+ "httpcore2._sync.connection_pool.ConnectionPool",
+ "httpcore2._sync.http_proxy.HTTPProxy",
+ "httpcore2._async.connection.AsyncHTTPConnection",
+ "httpcore2._async.connection_pool.AsyncConnectionPool",
+ "httpcore2._async.http_proxy.AsyncHTTPProxy",
+)
+
 
 @pytest.fixture
 def client() -> Generator[HyperpingClient, None, None]:

tests/unit/test_async_client.py

@@ -2,7 +2,7 @@
 
 from unittest.mock import AsyncMock, MagicMock, patch
 
-import httpx
+import httpx2 as httpx
 import pytest
 import pytest_asyncio
 

tests/unit/test_async_mcp_client.py

@@ -362,7 +362,9 @@ async def test_ensure_initialized_delegates_to_transport():
 async def test_ensure_initialized_propagates_rate_limit():
  client = make_client()
  client._transport.initialize.side_effect = HyperpingRateLimitError(
- "rate limited on initialize", retry_after=30, status_code=200,
+ "rate limited on initialize",
+ retry_after=30,
+ status_code=200,
  )
  with pytest.raises(HyperpingRateLimitError) as exc_info:
  await client.ensure_initialized()