hyperping 1.6.0__tar.gz → 1.8.0__tar.gz

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

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

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

@@ -5,6 +5,85 @@ 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).
 
+## [Unreleased]
+
+## [1.8.0] - 2026-05-31
+
+This is a security-focused release. It closes several credential-leak and validation gaps surfaced by an independent audit. One change is breaking for local-development workflows; see Upgrade Notes below.
+
+### Security
+
+- `validate_base_url` is now applied at every constructor that accepts a `base_url` or `mcp_url`: both the sync and async REST clients, both MCP transports, and the high-level MCP clients. The validator rejects non-`https` URLs by default, rejects URLs that carry userinfo (`user:pass@host` or bare `user@host`), and rejects URLs with a query string or fragment. The `Authorization: Bearer` header therefore cannot reach an attacker-controlled host through a misconfigured base URL.
+- `HyperpingAPIError.response_body` is now recursively redacted at construction time. Sensitive keys (authorization, tokens, cookies, set-cookie, request headers, request body, emails, webhooks) are replaced with `[REDACTED]`. Free-form string values are scrubbed for `Bearer <token>` and `sk_<token>` shapes. The recursion is bounded to prevent `RecursionError` from pathological payloads. Applies to all subclasses, including `HyperpingRateLimitError`.
+- `HyperpingAPIError` formatted messages now strip C0 control bytes (preserving `\t` and `\n`) and cap at 256 characters, so a server-supplied error string carrying ANSI escapes or a 1 KB blob cannot poison terminal output or downstream log pipelines.
+- The MCP transport no longer captures the first 500 bytes of server response as `response_body["raw"]` on rate-limit (429), generic HTTP error, or JSON-parse failure paths. Subscriber emails or webhook URLs that the server may echo cannot leak through that channel.
+- `_utils.parse_list` no longer logs the full `pydantic.ValidationError` string on per-item parse failures (Pydantic v2 includes the offending input by default). It now logs only the exception class and field locations.
+- The `breaker_key_fn` callback is now used through an LRU-bounded map. A custom callback that returns unbounded unique strings can no longer leak memory in long-running processes: the per-endpoint breaker map is capped at 1024 entries and evicts oldest on overflow. Applies to both sync and async clients.
+
+### Added
+
+- `allow_insecure: bool = False` keyword argument on every constructor that accepts a `base_url` or `mcp_url`. When set to `True`, `http://` URLs are permitted and an `InsecureTransportWarning` is emitted. Provided for local-development workflows; not recommended for production.
+- `InsecureTransportWarning` warning class exported from `hyperping`.
+
+### Changed
+
+- `_parse_retry_after` documents that it intentionally supports only the delta-seconds form of the `Retry-After` header. HTTP-date values fall through to exponential backoff rather than raising. Trade-off is documented in the docstring; no behavioral change for callers passing the integer form.
+
+### Upgrade Notes
+
+If your code instantiates `HyperpingClient` (or any MCP client) against a `http://localhost` URL for local development or against a mock server, the constructor will now raise `ValueError`. Pass `allow_insecure=True` to opt in, and expect an `InsecureTransportWarning` at runtime:
+
+```python
+from hyperping import HyperpingClient
+
+client = HyperpingClient(
+    api_key="sk_test_xxx",
+    base_url="http://localhost:8000",
+    allow_insecure=True,
+)
+```
+
+Production callers using `https://api.hyperping.io` are unaffected.
+
+URLs that previously carried embedded credentials (`https://user:pass@api.example.com`) or a trailing query string / fragment will now also raise at construction time. Refactor to pass credentials through `api_key` and to keep query strings out of the base URL.
+
+## [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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.6.0
+Version: 1.8.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.8.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.8.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.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.6.0"
+version = "1.8.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.8.0}/src/hyperping/_async_client.py

@@ -15,6 +15,7 @@ import asyncio
 import logging
 import random
 import threading
+from collections import OrderedDict
 from collections.abc import Callable
 from typing import Any
 from urllib.parse import urlsplit
@@ -33,8 +34,13 @@ from hyperping._circuit_breaker import (
     CircuitBreakerConfig,
     CircuitState,
 )
-from hyperping._internals import DEFAULT_USER_AGENT, RETRY_AFTER_MAX, sanitize_for_log
-from hyperping.client import DEFAULT_RETRY_CONFIG, RetryConfig
+from hyperping._internals import (
+    DEFAULT_USER_AGENT,
+    RETRY_AFTER_MAX,
+    sanitize_for_log,
+    validate_base_url,
+)
+from hyperping.client import _ENDPOINT_BREAKERS_MAX, DEFAULT_RETRY_CONFIG, RetryConfig
 from hyperping.endpoints import API_BASE, Endpoint
 from hyperping.exceptions import (
     HyperpingAPIError,
@@ -79,6 +85,7 @@ class AsyncHyperpingClient(
         user_agent: str | None = None,
         per_endpoint_circuit_breaker: bool = False,
         breaker_key_fn: Callable[[str], str] | None = None,
+        allow_insecure: bool = False,
     ) -> None:
         """Initialize the async Hyperping API client.
 
@@ -106,14 +113,17 @@ class AsyncHyperpingClient(
         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.base_url = validate_base_url(
+            base_url or self.DEFAULT_BASE_URL,
+            allow_insecure=allow_insecure,
+        )
         self.timeout = timeout
         self.retry_config = retry_config or DEFAULT_RETRY_CONFIG
         self._circuit_breaker_config = circuit_breaker_config
         self._circuit_breaker = CircuitBreaker(circuit_breaker_config)
         self._per_endpoint_circuit_breaker = per_endpoint_circuit_breaker
         self._breaker_key_fn = breaker_key_fn
-        self._endpoint_breakers: dict[str, CircuitBreaker] = {}
+        self._endpoint_breakers: OrderedDict[str, CircuitBreaker] = OrderedDict()
         self._endpoint_breakers_lock = threading.Lock()
 
         self._client = httpx.AsyncClient(
@@ -167,17 +177,39 @@ class AsyncHyperpingClient(
         return pure
 
     def _breaker_for(self, path: str) -> CircuitBreaker:
-        """Return the breaker that governs ``path`` (shared, or per-endpoint)."""
+        """Return the breaker that governs ``path`` (shared, or per-endpoint).
+
+        The critical section under ``_endpoint_breakers_lock`` is purely
+        CPU-bound (a single ``OrderedDict.get`` / ``__setitem__`` /
+        ``move_to_end`` / ``popitem``) and never awaits, so wrapping it in a
+        ``threading.Lock`` does not block the event loop in practice; the
+        loop only "stalls" for the duration of one dict operation, which is
+        well below the resolution of any asyncio scheduling decision.
+
+        We keep ``threading.Lock`` (rather than ``asyncio.Lock``) so the same
+        breaker map remains safe if a caller drives the async client from
+        multiple OS threads (e.g. via ``loop.run_in_executor`` or a thread
+        pool that re-enters the SDK). Switching to ``asyncio.Lock`` would
+        make the per-endpoint path correct only on the loop that owns the
+        lock; ``threading.Lock`` is correct in both cases. Regression
+        coverage:
+        ``tests/unit/test_security_breaker_cap.py
+        ::test_async_breaker_lock_does_not_deadlock_under_gather``.
+        """
         if not self._per_endpoint_circuit_breaker:
             return self._circuit_breaker
         key = self._resolve_breaker_key(path)
-        # threading.Lock here is intentional: see HyperpingClient._breaker_for
-        # for the rationale (works under both pure-asyncio and mixed-thread use).
         with self._endpoint_breakers_lock:
             breaker = self._endpoint_breakers.get(key)
             if breaker is None:
                 breaker = CircuitBreaker(self._circuit_breaker_config)
                 self._endpoint_breakers[key] = breaker
+                # Evict LRU once the cap is hit to bound memory under a
+                # pathological breaker_key_fn (see HyperpingClient).
+                while len(self._endpoint_breakers) > _ENDPOINT_BREAKERS_MAX:
+                    self._endpoint_breakers.popitem(last=False)
+            else:
+                self._endpoint_breakers.move_to_end(key)
             return breaker
 
     def circuit_breaker_state_for(self, path: str) -> CircuitState:
@@ -220,7 +252,12 @@ class AsyncHyperpingClient(
             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."""
+        """Extract and parse the ``Retry-After`` header value.
+
+        Only the delta-seconds form (RFC 7231 7.1.3) is parsed; HTTP-date
+        is intentionally not supported (see
+        :meth:`HyperpingClient._parse_retry_after` for rationale).
+        """
         retry_after = response.headers.get("Retry-After")
         if not retry_after:
             return None

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

@@ -50,11 +50,13 @@ class AsyncHyperpingMcpClient:
         api_key: str | SecretStr,
         base_url: str = MCP_URL,
         timeout: float = 30.0,
+        allow_insecure: bool = False,
     ) -> None:
         self._transport = AsyncMcpTransport(
             api_key=api_key,
             base_url=base_url,
             timeout=timeout,
+            allow_insecure=allow_insecure,
         )
 
     # ==================== Internal ====================
@@ -63,6 +65,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: