hyperping 1.6.0__tar.gz → 1.7.0__tar.gz

{hyperping-1.6.0 → hyperping-1.7.0}/.gitignore

@@ -36,3 +36,4 @@ htmlcov/
 # Local dev tooling
 .claude/
 dist/
+.worktrees/

{hyperping-1.6.0 → hyperping-1.7.0}/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-05-21
+
+### Added
+
+- `ensure_initialized()` on `HyperpingMcpClient` and `AsyncHyperpingMcpClient` for
+  startup health checks. Performs the MCP handshake now if it hasn't happened yet
+  and raises `HyperpingRateLimitError` if the server's `initialize` cap is hit.
+- New "MCP rate limits and connection lifecycle" section in README documenting
+  Hyperping's stateless MCP server, the undocumented `initialize` cap, and the
+  recommended client lifetime per process.
+
+### Fixed
+
+- MCP rate-limit errors that the server returns as HTTP 200 with JSON-RPC
+  `error.code = -32000` (notably the `initialize` per-minute cap) are now
+  classified as `HyperpingRateLimitError` with `retry_after` parsed from the
+  message, instead of a generic `HyperpingAPIError`. Existing HTTP 429 handling is
+  unchanged.
+- After a rate-limit on `initialize`, the MCP transport latches a cool-off so
+  subsequent `call_tool` invocations short-circuit with `HyperpingRateLimitError`
+  until the advertised `retry_after` elapses, instead of issuing further HTTP
+  requests that would burn more slots from the bucket.
+- TOCTOU race in lazy `initialize` where two concurrent first calls on the same
+  `HyperpingMcpClient` could each POST `initialize`. The handshake is now
+  performed under a dedicated lock with a double-checked flag, including a
+  lockless fast path so post-handshake `call_tool` does not contend on it.
+- Cool-off short-circuit now preserves the originating status code (200 for
+  JSON-RPC `-32000`, 429 for HTTP 429) so callers can distinguish buckets, and
+  `retry_after` uses `math.ceil` to avoid over-reporting by one second.
+- JSON-RPC rate-limit signals returned on the `notifications/initialized` leg
+  are now classified as `HyperpingRateLimitError` (previously they were
+  silently treated as a successful notification).
+- Rate-limit detection requires the message to contain `"rate limit exceeded"`
+  (the observed phrasing) to avoid false positives on unrelated server messages
+  that happen to mention `"rate limit"`. The `Retry-After` parser now also
+  accepts `Retry-After:` and `retry after N seconds` variants.
+
 ## [1.6.0] - 2026-05-06
 
 ### Added

{hyperping-1.6.0 → hyperping-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.6.0
+Version: 1.7.0
 Summary: Python SDK for the Hyperping uptime monitoring and incident management API
 Project-URL: Homepage, https://github.com/develeap/hyperping-python
 Project-URL: Documentation, https://github.com/develeap/hyperping-python#readme
@@ -230,6 +230,59 @@ The MCP client uses the same API key as `HyperpingClient`. All methods return
 plain dicts/lists; use the exported Pydantic models (e.g., `OnCallSchedule`,
 `EscalationPolicy`) for validation if needed.
 
+### MCP rate limits and connection lifecycle
+
+The Hyperping MCP server (`https://api.hyperping.io/v1/mcp`) is
+[documented by Hyperping as stateless over HTTP](https://hyperping.com/mcp)
+and rate-limits per API key. The publicly documented limit is 300 requests per
+minute shared with the REST API
+([rate-limit docs](https://hyperping.com/docs/monitoring/api-rate-limits)), but
+the server also enforces a separate, undocumented cap on the `initialize`
+handshake (observed around 5/minute). Because every new `HyperpingMcpClient`
+instance must perform the MCP `initialize` handshake on its first call,
+instantiating the client in a hot path or running several short-lived processes
+against one key will trip this cap.
+
+Operational guidance:
+
+- **Create one `HyperpingMcpClient` per process and reuse it.** Do not instantiate
+  it inside a loop. The first call performs the handshake; subsequent calls reuse
+  it for the life of the client.
+- **Catch `HyperpingRateLimitError` and honour `retry_after`.** Rate-limit signals
+  arrive two ways: as HTTP 429 (with a standard `Retry-After` header) and as a
+  JSON-RPC server error (`code: -32000`, HTTP 200) on `initialize`. Both surface as
+  `HyperpingRateLimitError` with `retry_after` parsed from whichever signal was
+  used. The `status_code` attribute is `429` or `200`, matching the underlying
+  signal; cool-off short-circuits preserve the originating status code so callers
+  can disambiguate the two buckets.
+- **Use `ensure_initialized()` for startup health checks.** Calling it once on
+  service boot lets you fail fast if the key is already at the `initialize` cap,
+  instead of failing on the first business call.
+- **Several workloads on one key collide on the `initialize` cap.** A weekly cron,
+  a watchdog daemon, and a developer running the CLI cannot all warm up the same
+  API key inside one minute. Use one long-lived process per workload, or separate
+  API keys per workload if your plan allows.
+- **After a rate-limit on `initialize`, the SDK latches a cool-off** so that
+  subsequent `call_tool` invocations on the same client fail fast with
+  `HyperpingRateLimitError` (no extra HTTP traffic) until `retry_after` elapses.
+  This prevents accidentally burning more slots from the bucket. The latch is
+  per-`HyperpingMcpClient` instance and per-process; it does not coordinate
+  across separate Python processes sharing the same API key, so multi-process
+  setups still need the workload-separation advice above.
+
+```python
+from hyperping import HyperpingMcpClient, HyperpingRateLimitError
+
+mcp = HyperpingMcpClient(api_key="sk_...")
+try:
+    mcp.ensure_initialized()
+except HyperpingRateLimitError as e:
+    print(f"MCP cold-start rate-limited; retry in {e.retry_after}s")
+    raise
+
+summary = mcp.get_status_summary()
+```
+
 ### Healthchecks
 
 ```python

{hyperping-1.6.0 → hyperping-1.7.0}/README.md

@@ -193,6 +193,59 @@ The MCP client uses the same API key as `HyperpingClient`. All methods return
 plain dicts/lists; use the exported Pydantic models (e.g., `OnCallSchedule`,
 `EscalationPolicy`) for validation if needed.
 
+### MCP rate limits and connection lifecycle
+
+The Hyperping MCP server (`https://api.hyperping.io/v1/mcp`) is
+[documented by Hyperping as stateless over HTTP](https://hyperping.com/mcp)
+and rate-limits per API key. The publicly documented limit is 300 requests per
+minute shared with the REST API
+([rate-limit docs](https://hyperping.com/docs/monitoring/api-rate-limits)), but
+the server also enforces a separate, undocumented cap on the `initialize`
+handshake (observed around 5/minute). Because every new `HyperpingMcpClient`
+instance must perform the MCP `initialize` handshake on its first call,
+instantiating the client in a hot path or running several short-lived processes
+against one key will trip this cap.
+
+Operational guidance:
+
+- **Create one `HyperpingMcpClient` per process and reuse it.** Do not instantiate
+  it inside a loop. The first call performs the handshake; subsequent calls reuse
+  it for the life of the client.
+- **Catch `HyperpingRateLimitError` and honour `retry_after`.** Rate-limit signals
+  arrive two ways: as HTTP 429 (with a standard `Retry-After` header) and as a
+  JSON-RPC server error (`code: -32000`, HTTP 200) on `initialize`. Both surface as
+  `HyperpingRateLimitError` with `retry_after` parsed from whichever signal was
+  used. The `status_code` attribute is `429` or `200`, matching the underlying
+  signal; cool-off short-circuits preserve the originating status code so callers
+  can disambiguate the two buckets.
+- **Use `ensure_initialized()` for startup health checks.** Calling it once on
+  service boot lets you fail fast if the key is already at the `initialize` cap,
+  instead of failing on the first business call.
+- **Several workloads on one key collide on the `initialize` cap.** A weekly cron,
+  a watchdog daemon, and a developer running the CLI cannot all warm up the same
+  API key inside one minute. Use one long-lived process per workload, or separate
+  API keys per workload if your plan allows.
+- **After a rate-limit on `initialize`, the SDK latches a cool-off** so that
+  subsequent `call_tool` invocations on the same client fail fast with
+  `HyperpingRateLimitError` (no extra HTTP traffic) until `retry_after` elapses.
+  This prevents accidentally burning more slots from the bucket. The latch is
+  per-`HyperpingMcpClient` instance and per-process; it does not coordinate
+  across separate Python processes sharing the same API key, so multi-process
+  setups still need the workload-separation advice above.
+
+```python
+from hyperping import HyperpingMcpClient, HyperpingRateLimitError
+
+mcp = HyperpingMcpClient(api_key="sk_...")
+try:
+    mcp.ensure_initialized()
+except HyperpingRateLimitError as e:
+    print(f"MCP cold-start rate-limited; retry in {e.retry_after}s")
+    raise
+
+summary = mcp.get_status_summary()
+```
+
 ### Healthchecks
 
 ```python

{hyperping-1.6.0 → hyperping-1.7.0}/SECURITY.md

@@ -6,8 +6,9 @@ We release patches for security vulnerabilities for the following versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.5.x   | :white_check_mark: |
-| < 1.5   | :x:                |
+| 1.7.x   | :white_check_mark: |
+| 1.6.x   | :white_check_mark: |
+| < 1.6   | :x:                |
 
 Older releases may receive a fix at maintainers' discretion when the issue is severe and an upgrade is not feasible. The latest 1.x release is always the recommended target.
 

{hyperping-1.6.0 → hyperping-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.6.0"
+version = "1.7.0"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}
@@ -51,7 +51,7 @@ Issues        = "https://github.com/develeap/hyperping-python/issues"
 packages = ["src/hyperping"]
 
 [tool.hatch.build.targets.sdist]
-exclude = [".claude/", ".github/", "dist/", "uv.lock", "BACKLOG.md"]
+exclude = [".claude/", ".github/", ".worktrees/", "dist/", "docs/plans/", "uv.lock", "BACKLOG.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{hyperping-1.6.0 → hyperping-1.7.0}/src/hyperping/_async_mcp_client.py

@@ -63,6 +63,27 @@ class AsyncHyperpingMcpClient:
         """Call an MCP tool via the transport."""
         return await self._transport.call_tool(tool, args or {})
 
+    async def ensure_initialized(self) -> None:
+        """Perform the MCP handshake now if it hasn't happened yet.
+
+        Async counterpart to
+        :meth:`hyperping.mcp_client.HyperpingMcpClient.ensure_initialized`.
+        Idempotent.
+
+        Raises:
+            HyperpingRateLimitError: If the server rate-limits ``initialize``,
+                either via HTTP 429 or via the JSON-RPC ``-32000`` rate-limit
+                payload. Inspect ``.retry_after`` to back off.
+            HyperpingAuthError: If the API key is invalid (HTTP 401/403).
+            HyperpingNotFoundError: If the MCP endpoint URL is wrong
+                (HTTP 404).
+            HyperpingValidationError: If the server rejects the handshake
+                payload (HTTP 400/422; unusual on initialize).
+            HyperpingAPIError: Any other transport-level error (HTTP 5xx,
+                malformed body, etc.).
+        """
+        await self._transport.initialize()
+
     # ==================== Context Manager ====================
 
     async def close(self) -> None:

hyperping-1.7.0/src/hyperping/_async_mcp_transport.py

@@ -0,0 +1,308 @@
+"""Async JSON-RPC 2.0 transport for the Hyperping MCP server."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import re
+import time
+from typing import Any
+
+import httpx
+from pydantic import SecretStr
+
+from hyperping._version import __version__
+from hyperping.endpoints import MCP_URL
+from hyperping.exceptions import (
+    HyperpingAPIError,
+    HyperpingAuthError,
+    HyperpingNotFoundError,
+    HyperpingRateLimitError,
+    HyperpingValidationError,
+)
+
+_PROTOCOL_VERSION = "2025-03-26"
+
+# Tight marker: the server's observed phrasing is "rate limit exceeded ...".
+# Bare "rate limit" would risk classifying messages like "rate limit
+# configuration invalid" as a rate-limit error.
+_MCP_RATE_LIMIT_MARKER = "rate limit exceeded"
+# Accept "Retry after Ns", "Retry-After: Ns", "retry after 30 seconds", etc.
+# Captures only the integer; sub-second values are floored.
+_MCP_RATE_LIMIT_RETRY_AFTER_RE = re.compile(
+    r"retry[\s\-]after[:\s]+(\d+)",
+    re.IGNORECASE,
+)
+# Default cool-off when the server fails to advertise one.
+_COOLOFF_DEFAULT_SECONDS = 30
+
+
+class AsyncMcpTransport:
+    """Async low-level JSON-RPC 2.0 client for the Hyperping MCP server.
+
+    The MCP server exposes tools not available via the REST API: on-call
+    schedules, anomalies, alerts, integrations, probe logs, and more.
+
+    Uses the same Bearer token API key as the REST client.
+    """
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str = MCP_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        token = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
+        self._url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json, text/event-stream",
+            },
+            timeout=timeout,
+        )
+        self._initialized = False
+        self._request_id = 0
+        self._lock = asyncio.Lock()
+        # Separate lock for the handshake so request-id increment and the
+        # initialize() critical section don't contend.
+        self._init_lock = asyncio.Lock()
+        # Monotonic deadline (process-local). 0.0 means no latch.
+        self._init_blocked_until: float = 0.0
+        # Status code of the original rate-limit response that armed the
+        # latch, propagated through short-circuit raises so callers can tell
+        # whether they hit HTTP 429 or HTTP 200 + JSON-RPC -32000.
+        self._init_blocked_status_code: int = 200
+        self._init_result: dict[str, Any] = {}
+        self._max_retries = max_retries
+
+    async def _next_id(self) -> int:
+        async with self._lock:
+            self._request_id += 1
+            return self._request_id
+
+    async def _send_rpc(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        is_notification: bool = False,
+    ) -> dict[str, Any] | None:
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            payload["params"] = params
+        if not is_notification:
+            payload["id"] = await self._next_id()
+
+        resp = await self._client.post(self._url, content=json.dumps(payload))
+
+        if resp.status_code in (401, 403):
+            raise HyperpingAuthError("Invalid or expired API key")
+        if resp.status_code == 202:
+            return None  # Notification accepted
+        if resp.status_code == 404:
+            raise HyperpingNotFoundError(
+                "Resource not found",
+                status_code=404,
+            )
+        if resp.status_code == 429:
+            retry_after = None
+            raw_retry = resp.headers.get("retry-after")
+            if raw_retry:
+                try:
+                    retry_after = int(raw_retry)
+                except ValueError:
+                    pass
+            raise HyperpingRateLimitError(
+                "Rate limit exceeded",
+                retry_after=retry_after,
+                status_code=429,
+                response_body={"raw": resp.text[:500]},
+            )
+        if resp.status_code in (400, 422):
+            raise HyperpingValidationError(
+                f"Validation error: HTTP {resp.status_code}",
+                status_code=resp.status_code,
+            )
+        if resp.status_code != 200:
+            raise HyperpingAPIError(
+                f"MCP server returned HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                response_body={"raw": resp.text[:500]},
+            )
+
+        # HTTP 200. Parse the body so we classify JSON-RPC errors (including
+        # rate-limit signals) on notification responses too -- the server can
+        # return 200 + JSON-RPC error on a "notifications/initialized" leg.
+        try:
+            data = resp.json()
+        except (json.JSONDecodeError, ValueError):
+            if is_notification:
+                return None
+            raise HyperpingAPIError(
+                "MCP server returned 200 with non-JSON body",
+                status_code=200,
+                response_body={"raw": resp.text[:500]},
+            ) from None
+
+        if isinstance(data, dict) and "error" in data:
+            self._raise_for_jsonrpc_error(data["error"], resp.status_code)
+
+        if is_notification:
+            return None
+        return data  # type: ignore[no-any-return]
+
+    @staticmethod
+    def _raise_for_jsonrpc_error(err: Any, status_code: int) -> None:
+        """Map a JSON-RPC ``error`` payload to a typed exception and raise it."""
+        if (
+            isinstance(err, dict)
+            and err.get("code") == -32000
+            and isinstance(err.get("message"), str)
+            and _MCP_RATE_LIMIT_MARKER in err["message"].lower()
+        ):
+            rl_retry_after: int | None = None
+            match = _MCP_RATE_LIMIT_RETRY_AFTER_RE.search(err["message"])
+            if match:
+                rl_retry_after = int(match.group(1))
+            raise HyperpingRateLimitError(
+                err["message"],
+                retry_after=rl_retry_after,
+                status_code=status_code,
+                response_body=err if isinstance(err, dict) else None,
+            )
+        code = err.get("code", "?") if isinstance(err, dict) else "?"
+        message = err.get("message", "unknown") if isinstance(err, dict) else str(err)
+        raise HyperpingAPIError(
+            f"MCP error {code}: {message}",
+            status_code=status_code,
+            response_body=err if isinstance(err, dict) else None,
+        )
+
+    async def initialize(self) -> dict[str, Any]:
+        """Async idempotent and concurrency-safe MCP handshake.
+
+        Calling this more than once on the same transport is a no-op after the
+        first successful handshake. While an ``initialize`` cool-off latch is
+        active, raises :class:`HyperpingRateLimitError` without issuing any
+        HTTP request.
+
+        The cool-off latch is per-transport-instance and per-process. It does
+        not coordinate across separate Python processes sharing the same API
+        key; each process keeps its own latch.
+        """
+        # Fast path: avoid lock acquisition on every call after the handshake
+        # has succeeded. ``_initialized`` is only assigned True under the lock
+        # after both legs of the handshake, so a True read here is safe.
+        if self._initialized:
+            return self._init_result
+        async with self._init_lock:
+            if self._initialized:
+                return self._init_result
+            return await self._initialize_locked()
+
+    async def _initialize_locked(self) -> dict[str, Any]:
+        """Perform the handshake. Assumes ``self._init_lock`` is held."""
+        # ``time.monotonic`` is used deliberately over ``time.time`` so the
+        # latch is immune to wall-clock jumps (NTP adjustments, suspend/resume).
+        remaining = self._init_blocked_until - time.monotonic()
+        if remaining > 0:
+            raise HyperpingRateLimitError(
+                "MCP initialize rate limit cool-off active; retry later",
+                retry_after=max(math.ceil(remaining), 1),
+                status_code=self._init_blocked_status_code,
+            )
+        try:
+            result = await self._send_rpc(
+                "initialize",
+                {
+                    "protocolVersion": _PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {"name": "hyperping-python", "version": __version__},
+                },
+            )
+            await self._send_rpc("notifications/initialized", is_notification=True)
+        except HyperpingRateLimitError as exc:
+            # retry_after=None -> default cool-off; retry_after=0 -> no latch
+            # (the server is telling us we may retry immediately); positive
+            # values are honoured verbatim.
+            if exc.retry_after is None:
+                wait = _COOLOFF_DEFAULT_SECONDS
+            else:
+                wait = max(int(exc.retry_after), 0)
+            self._init_blocked_until = time.monotonic() + wait
+            self._init_blocked_status_code = exc.status_code or 200
+            raise
+        self._init_result = result.get("result", {}) if result else {}
+        self._init_blocked_until = 0.0
+        # Set last so the fast path in initialize() never returns a stale
+        # ``_init_result``.
+        self._initialized = True
+        return self._init_result
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call an MCP tool and return parsed response data.
+
+        Auto-initializes on first call. Extracts and parses the JSON
+        string from ``result.content[0].text``.
+
+        Retries automatically on transient HTTP server errors (500, 502, 503, 504)
+        up to ``max_retries`` times with exponential back-off. Rate-limit errors
+        (HTTP 429 or JSON-RPC -32000) are NEVER retried at this layer; they raise
+        :class:`HyperpingRateLimitError` immediately so callers can honour
+        ``retry_after``.
+        """
+        await self.initialize()
+
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                result = await self._send_rpc(
+                    "tools/call",
+                    {"name": tool_name, "arguments": arguments or {}},
+                )
+                break
+            except HyperpingAPIError as exc:
+                if exc.status_code and exc.status_code in (500, 502, 503, 504):
+                    last_exc = exc
+                    if attempt < self._max_retries:
+                        await asyncio.sleep(min(2**attempt, 10))
+                        continue
+                raise
+        else:
+            raise last_exc  # type: ignore[misc]
+        if result is None:
+            return None
+
+        content = result.get("result", {}).get("content", [])
+        if not content:
+            return None
+
+        text = content[0].get("text", "")
+        if not text:
+            return None
+
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise HyperpingAPIError(
+                f"Failed to parse MCP tool response: {exc}",
+                status_code=200,
+                response_body={"raw": text[:500]},
+            ) from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncMcpTransport:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()