hyperping 1.7.0__tar.gz → 1.8.1__tar.gz

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

@@ -5,6 +5,71 @@ 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.1] - 2026-07-14
+
+### Fixed
+
+- **`list_status_pages()` returned an empty list against the live v2 API.** The
+  `StatusPage` model required a `subdomain` field, but the API returns the hosted
+  subdomain under the key `hostedsubdomain` (and omits it entirely for custom-domain
+  pages). Every record failed validation and was silently skipped. `subdomain` is now
+  optional and aliased to `hostedsubdomain`; `hostname` and `url` are also parsed.
+
+### Added
+
+- **`create_maintenance()` now guards against the silent status-page overflow.**
+  Hyperping's v1 maintenance-windows API accepts a create with more than 51 status
+  pages (returns a uuid) but never persists the window. `create_maintenance` now raises
+  `HyperpingValidationError` when `statuspages` exceeds `MAX_STATUSPAGES_PER_MAINTENANCE`
+  (51), instead of returning a phantom window. Split larger sets across multiple windows.
+- **`create_maintenance_windows()`** (sync + async): convenience helper that splits a
+  large `statuspages` list into consecutive windows of at most 51 pages, so callers can
+  cover more pages than one window allows. Each window carries the full monitor set (the
+  API requires at least one monitor per window). `MAX_STATUSPAGES_PER_MAINTENANCE` is
+  exported for callers that chunk themselves (e.g. a broadcast-to-all-tenants command).
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.7.0
+Version: 1.8.1
 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
@@ -12,6 +12,7 @@ License: MIT
 License-File: LICENSE
 Keywords: api-client,httpx,hyperping,incident,monitoring,pydantic,python,sdk,status-page,uptime
 Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -25,6 +26,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: cli
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
@@ -33,6 +36,7 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # hyperping

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.7.0"
+version = "1.8.1"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}
@@ -23,6 +23,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
     "Typing :: Typed",
+    "Environment :: Console",
 ]
 dependencies = [
     "httpx>=0.27,<1.0",
@@ -30,6 +31,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+cli = ["typer[all]>=0.12,<1.0"]
 dev = [
     "pytest>=9.0.3",
     "pytest-cov",
@@ -38,8 +40,12 @@ dev = [
     "mypy>=1.10",
     "pydantic",
     "pip-audit>=2.7",
+    "typer[all]>=0.12,<1.0",
 ]
 
+[project.scripts]
+hyp = "hyperping.cli._app:app"
+
 [project.urls]
 Homepage      = "https://github.com/develeap/hyperping-python"
 Documentation = "https://github.com/develeap/hyperping-python#readme"

{hyperping-1.7.0 → hyperping-1.8.1}/src/hyperping/__init__.py

@@ -16,6 +16,7 @@ Quick start::
 
 from hyperping._async_client import AsyncHyperpingClient
 from hyperping._async_mcp_client import AsyncHyperpingMcpClient
+from hyperping._maintenance_mixin import MAX_STATUSPAGES_PER_MAINTENANCE
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -44,6 +45,7 @@ from hyperping.models import (
     AlertHistory,
     DnsRecordType,
     EscalationPolicy,
+    EscalationStep,
     Healthcheck,
     HealthcheckCreate,
     HealthcheckUpdate,
@@ -149,6 +151,7 @@ __all__ = [
     "IncidentStatus",
     "IncidentUpdateCreate",
     # Maintenance
+    "MAX_STATUSPAGES_PER_MAINTENANCE",
     "Maintenance",
     "MaintenanceCreate",
     "MaintenanceUpdate",
@@ -168,6 +171,7 @@ __all__ = [
     "ProbeLogResponse",
     # On-call
     "OnCallSchedule",
+    "EscalationStep",
     "EscalationPolicy",
     "TeamMember",
     # Integrations

{hyperping-1.7.0 → hyperping-1.8.1}/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.7.0 → hyperping-1.8.1}/src/hyperping/_async_maintenance_mixin.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 import logging
 from datetime import UTC, datetime
 
+from hyperping._maintenance_mixin import MAX_STATUSPAGES_PER_MAINTENANCE
 from hyperping._protocols import _AsyncClientProtocol
 from hyperping._utils import expect_dict, parse_list, unwrap_list, validate_id
 from hyperping.endpoints import Endpoint
+from hyperping.exceptions import HyperpingValidationError
 from hyperping.models import (
     Maintenance,
     MaintenanceCreate,
@@ -82,6 +84,15 @@ class AsyncMaintenanceMixin(_AsyncClientProtocol):
             v1 API returns {"uuid": "..."} on create, not the full maintenance object.
             The full maintenance window is fetched after creation.
         """
+        n_statuspages = len(maintenance.statuspages or [])
+        if n_statuspages > MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"A maintenance window can reference at most "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE} status pages, but {n_statuspages} "
+                f"were supplied. Above this limit Hyperping's API accepts the create "
+                f"(returns a uuid) but silently fails to persist the window. Split the "
+                f"status pages across multiple maintenance windows."
+            )
         payload = maintenance.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = expect_dict(
             await self._request("POST", Endpoint.MAINTENANCE, json=payload),
@@ -91,6 +102,33 @@ class AsyncMaintenanceMixin(_AsyncClientProtocol):
             return await self.get_maintenance(response["uuid"])
         return Maintenance.model_validate(response)
 
+    async def create_maintenance_windows(
+        self,
+        maintenance: MaintenanceCreate,
+        *,
+        chunk_size: int = MAX_STATUSPAGES_PER_MAINTENANCE,
+    ) -> list[Maintenance]:
+        """Create one or more windows, splitting status pages into chunks.
+
+        Async mirror of
+        :meth:`~hyperping._maintenance_mixin.MaintenanceMixin.create_maintenance_windows`.
+        """
+        if not 1 <= chunk_size <= MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"chunk_size must be between 1 and "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE}, got {chunk_size}."
+            )
+        pages = list(maintenance.statuspages or [])
+        if len(pages) <= chunk_size:
+            return [await self.create_maintenance(maintenance)]
+        windows: list[Maintenance] = []
+        for start in range(0, len(pages), chunk_size):
+            chunk = maintenance.model_copy(
+                update={"statuspages": pages[start : start + chunk_size]}
+            )
+            windows.append(await self.create_maintenance(chunk))
+        return windows
+
     async def update_maintenance(
         self,
         maintenance_id: str,

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

@@ -21,7 +21,7 @@ from pydantic import SecretStr
 from hyperping._async_mcp_transport import AsyncMcpTransport
 from hyperping.endpoints import MCP_URL
 from hyperping.models._integration_models import Integration
-from hyperping.models._monitor_models import Monitor
+from hyperping.models._monitor_models import Monitor, MonitorCreate
 from hyperping.models._observability_models import MonitorAnomaly, ProbeLogResponse
 from hyperping.models._oncall_models import EscalationPolicy, OnCallSchedule, TeamMember
 from hyperping.models._outage_models import OutageTimeline
@@ -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 ====================
@@ -268,3 +270,52 @@ class AsyncHyperpingMcpClient:
         data = await self._call("search_monitors_by_name", {"query": query})
         raw = data if isinstance(data, list) else []
         return [Monitor.model_validate(m) for m in raw]
+
+    async def create_monitor(self, monitor: MonitorCreate) -> Monitor:
+        """Create a new monitor.
+
+        Args:
+            monitor: Monitor configuration.
+        """
+        return Monitor.model_validate(
+            await self._call("create_monitor", monitor.model_dump(exclude_none=True))
+        )
+
+    async def update_monitor(self, monitor_uuid: str, **kwargs: Any) -> Monitor:
+        """Update an existing monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Fields to update.
+        """
+        return Monitor.model_validate(
+            await self._call("update_monitor", {"uuid": monitor_uuid, **kwargs})
+        )
+
+    async def pause_monitor(self, monitor_uuid: str) -> Monitor:
+        """Pause a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        return Monitor.model_validate(
+            await self._call("pause_monitor", {"uuid": monitor_uuid})
+        )
+
+    async def resume_monitor(self, monitor_uuid: str) -> Monitor:
+        """Resume a paused monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        return Monitor.model_validate(
+            await self._call("resume_monitor", {"uuid": monitor_uuid})
+        )
+
+    async def delete_monitor(self, monitor_uuid: str) -> None:
+        """Delete a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        await self._call("delete_monitor", {"uuid": monitor_uuid})

{hyperping-1.7.0 → hyperping-1.8.1}/src/hyperping/_async_mcp_transport.py

@@ -12,6 +12,7 @@ from typing import Any
 import httpx
 from pydantic import SecretStr
 
+from hyperping._internals import validate_base_url
 from hyperping._version import __version__
 from hyperping.endpoints import MCP_URL
 from hyperping.exceptions import (
@@ -53,9 +54,14 @@ class AsyncMcpTransport:
         base_url: str = MCP_URL,
         timeout: float = 30.0,
         max_retries: int = 2,
+        allow_insecure: bool = False,
     ) -> None:
         token = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
-        self._url = base_url.rstrip("/")
+        self._url = validate_base_url(
+            base_url,
+            allow_insecure=allow_insecure,
+            param_name="base_url",
+        )
         self._client = httpx.AsyncClient(
             headers={
                 "Authorization": f"Bearer {token}",
@@ -116,11 +122,13 @@ class AsyncMcpTransport:
                     retry_after = int(raw_retry)
                 except ValueError:
                     pass
+            # Drop the raw body for the same reason as the sync transport:
+            # the structured exception still carries retry_after.
             raise HyperpingRateLimitError(
                 "Rate limit exceeded",
                 retry_after=retry_after,
                 status_code=429,
-                response_body={"raw": resp.text[:500]},
+                response_body=None,
             )
         if resp.status_code in (400, 422):
             raise HyperpingValidationError(
@@ -128,10 +136,14 @@ class AsyncMcpTransport:
                 status_code=resp.status_code,
             )
         if resp.status_code != 200:
+            # Drop the raw body for the same reason as the 429 path: the server
+            # may echo subscriber emails, webhook URLs, or other PII in free-
+            # form error text that the structured key-based redactor cannot
+            # match. The status code in the exception is enough for callers.
             raise HyperpingAPIError(
                 f"MCP server returned HTTP {resp.status_code}",
                 status_code=resp.status_code,
-                response_body={"raw": resp.text[:500]},
+                response_body=None,
             )
 
         # HTTP 200. Parse the body so we classify JSON-RPC errors (including
@@ -145,7 +157,7 @@ class AsyncMcpTransport:
             raise HyperpingAPIError(
                 "MCP server returned 200 with non-JSON body",
                 status_code=200,
-                response_body={"raw": resp.text[:500]},
+                response_body=None,
             ) from None
 
         if isinstance(data, dict) and "error" in data:
@@ -292,10 +304,12 @@ class AsyncMcpTransport:
         try:
             return json.loads(text)
         except json.JSONDecodeError as exc:
+            # Server-controlled ``text`` may carry PII; drop it instead of
+            # embedding the first 500 bytes into the exception.
             raise HyperpingAPIError(
                 f"Failed to parse MCP tool response: {exc}",
                 status_code=200,
-                response_body={"raw": text[:500]},
+                response_body=None,
             ) from exc
 
     async def close(self) -> None: