webex-message-handler 0.6.7__tar.gz → 0.6.9__tar.gz

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.7
+Version: 0.6.9
 Summary: Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK
 Project-URL: Homepage, https://github.com/3rg0n/webex-message-handler
 Project-URL: Repository, https://github.com/3rg0n/webex-message-handler
@@ -187,6 +187,20 @@ async def on_message(msg):
 
 Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
 
+## Delivery Guarantees
+
+This library provides **at-most-once** delivery semantics:
+
+- Mercury WebSocket acknowledges messages at the protocol level on receipt, before decryption or consumer delivery.
+- If decryption fails (e.g., KMS outage) or your callback throws an error, the message is **not redelivered**.
+- Mercury does not support application-level ACK/NACK — this is an inherent constraint of the Webex platform.
+
+**For consumers requiring stronger guarantees:**
+
+- Wrap your callback with a persistent queue (e.g., database, Redis, or message broker) to ensure processing completes.
+- Use the `error` event to detect and log decryption failures.
+- The KMS circuit breaker (v0.6.9+) prevents 30-second stalls during KMS outages by failing fast after 3 consecutive failures.
+
 ## API Reference
 
 ### `WebexMessageHandler`
@@ -211,6 +225,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 | `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |
 | `reconnect_backoff_max` | `float` | `32.0` | Max reconnect backoff (seconds) |
 | `max_reconnect_attempts` | `int` | `10` | Max reconnect attempts |
+| `metrics_callback` | `MetricsCallback \| None` | `None` | Optional callback for timing metrics (`connect`, `decrypt` events) |
 
 #### Methods
 

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/README.md

@@ -155,6 +155,20 @@ async def on_message(msg):
 
 Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
 
+## Delivery Guarantees
+
+This library provides **at-most-once** delivery semantics:
+
+- Mercury WebSocket acknowledges messages at the protocol level on receipt, before decryption or consumer delivery.
+- If decryption fails (e.g., KMS outage) or your callback throws an error, the message is **not redelivered**.
+- Mercury does not support application-level ACK/NACK — this is an inherent constraint of the Webex platform.
+
+**For consumers requiring stronger guarantees:**
+
+- Wrap your callback with a persistent queue (e.g., database, Redis, or message broker) to ensure processing completes.
+- Use the `error` event to detect and log decryption failures.
+- The KMS circuit breaker (v0.6.9+) prevents 30-second stalls during KMS outages by failing fast after 3 consecutive failures.
+
 ## API Reference
 
 ### `WebexMessageHandler`
@@ -179,6 +193,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 | `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |
 | `reconnect_backoff_max` | `float` | `32.0` | Max reconnect backoff (seconds) |
 | `max_reconnect_attempts` | `int` | `10` | Max reconnect attempts |
+| `metrics_callback` | `MetricsCallback \| None` | `None` | Optional callback for timing metrics (`connect`, `decrypt` events) |
 
 #### Methods
 

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.6.7"
+version = "0.6.9"
 description = "Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK"
 readme = "README.md"
 license = "MIT"

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/src/webex_message_handler/__init__.py

@@ -28,6 +28,8 @@ from .types import (
     HandlerStatus,
     InjectedWebSocket,
     MembershipActivity,
+    MetricsCallback,
+    MetricsEvent,
     MercuryActivity,
     MercuryActor,
     MercuryEnvelope,
@@ -88,4 +90,7 @@ __all__ = [
     "FetchFunction",
     "InjectedWebSocket",
     "WebSocketFactory",
+    # Metrics types
+    "MetricsEvent",
+    "MetricsCallback",
 ]

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/src/webex_message_handler/handler.py

@@ -27,6 +27,7 @@ from .types import (
     HandlerStatus,
     InjectedWebSocket,
     MembershipActivity,
+    MetricsEvent,
     MercuryActivity,
     RoomActivity,
     WebexMessageHandlerConfig,
@@ -125,6 +126,7 @@ class WebexMessageHandler:
 
         self._ignore_self_messages = config.ignore_self_messages
         self._bot_person_id: str | None = None
+        self._metrics_callback = config.metrics_callback
 
         self._kms_client: KmsClient | None = None
         self._message_decryptor: MessageDecryptor | None = None
@@ -152,6 +154,12 @@ class WebexMessageHandler:
 
         self._setup_mercury_listeners()
 
+    def _report_metric(self, name: str, start_time: float, success: bool, metadata: dict[str, str] | None = None) -> None:
+        """Report a timing metric if callback is set."""
+        if self._metrics_callback:
+            duration_ms = (time.monotonic() - start_time) * 1000
+            self._metrics_callback(MetricsEvent(name=name, duration_ms=duration_ms, success=success, metadata=metadata))
+
     def _create_native_http_adapter(
         self, connector: aiohttp.BaseConnector | None
     ) -> FetchFunction:
@@ -275,6 +283,7 @@ class WebexMessageHandler:
         self._logger.info("Connecting to Webex...")
         self._connecting = True
 
+        connect_start = time.monotonic()
         try:
             # Step 1: Register device with WDM
             self._registration = await self._device_manager.register(self._token)
@@ -314,10 +323,12 @@ class WebexMessageHandler:
             self._connecting = False
             self._connected = True
             self._logger.info("Connected to Webex")
+            self._report_metric("connect", connect_start, True)
             self._emit("connected")
 
         except Exception:
             self._connecting = False
+            self._report_metric("connect", connect_start, False)
             raise
 
     async def disconnect(self) -> None:
@@ -468,7 +479,14 @@ class WebexMessageHandler:
                 self._logger.warning("Received activity but decryptor not initialized")
                 return
 
-            decrypted = await self._message_decryptor.decrypt_activity(activity)
+            decrypt_start = time.monotonic()
+            try:
+                decrypted = await self._message_decryptor.decrypt_activity(activity)
+                self._report_metric("decrypt", decrypt_start, True)
+            except Exception:
+                self._report_metric("decrypt", decrypt_start, False)
+                raise
+
             mentions = parse_mentions(decrypted.object.content)
             message = DecryptedMessage(
                 id=decrypted.id,

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/src/webex_message_handler/kms_client.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import time
 import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Any
@@ -26,6 +27,8 @@ from .types import FetchFunction, FetchRequest
 from .url_validation import validate_webex_url
 
 KMS_RESPONSE_TIMEOUT = 30.0  # seconds
+CB_FAILURE_THRESHOLD = 3
+CB_COOLDOWN_SECONDS = 30.0
 
 
 class KmsClient:
@@ -64,6 +67,11 @@ class KmsClient:
         # Lock to serialize KMS HTTP requests
         self._kms_request_lock = asyncio.Lock()
 
+        # Circuit breaker state
+        self._cb_state: str = "closed"  # "closed", "open", "half_open"
+        self._cb_failures: int = 0
+        self._cb_last_failure: float = 0.0
+
     def handle_kms_message(self, data: dict[str, Any]) -> None:
         """Handle a KMS response that arrived via Mercury WebSocket.
 
@@ -106,8 +114,8 @@ class KmsClient:
             kms_details = await response.json()
 
             self._kms_cluster = kms_details["kmsCluster"]
-            # Validate KMS cluster URL
-            validate_webex_url(self._kms_cluster, "https")
+            # Validate KMS cluster URL — Webex returns kms:// scheme for this field
+            validate_webex_url(self._kms_cluster, "kms")
 
             rsa_public_key_raw = kms_details["rsaPublicKey"]
             if isinstance(rsa_public_key_raw, str):
@@ -231,69 +239,91 @@ class KmsClient:
             if not self._initialized or not self._ephemeral_key:
                 raise KmsError("KMS context not initialized")
 
-            # Build retrieve request
-            request_id = str(uuid.uuid4())
-            retrieve_body = {
-                "client": {
-                    "clientId": self._device_url,
-                    "credential": {
-                        "userId": self._user_id,
-                        "bearer": self._token,
-                    },
-                },
-                "method": "retrieve",
-                "uri": key_uri,
-                "requestId": request_id,
-            }
-
-            # Wrap with ephemeral key (dir + A256GCM — key is CEK directly)
-            wrapped = _jwe_encrypt(
-                plaintext=json.dumps(retrieve_body).encode(),
-                key=self._ephemeral_key,
-                alg="dir",
-                enc="A256GCM",
-            )
-
-            # POST and wait for Mercury response
-            wrapped_response = await self._send_kms_request(request_id, wrapped)
-
-            # Unwrap response
-            response_body = _unwrap_kms_response(wrapped_response, self._ephemeral_key)
-            response_data = json.loads(response_body)
-
-            # Extract the content key
-            key_data = (
-                response_data.get("body", {}).get("key", {}).get("jwk")
-                or response_data.get("key", {}).get("jwk")
-            )
-            if (
-                not key_data
-                and "body" in response_data
-                and "key" in response_data["body"]
-            ):
-                key_obj = response_data["body"]["key"]
-                key_data = key_obj["jwk"] if isinstance(key_obj, dict) and "jwk" in key_obj else key_obj
-
-            if not key_data:
-                raise KmsError("No key found in KMS response")
-
-            if isinstance(key_data, str):
-                key_data = json.loads(key_data)
+            # Check circuit breaker state
+            if self._cb_state == "open":
+                if time.monotonic() - self._cb_last_failure >= CB_COOLDOWN_SECONDS:
+                    self._cb_state = "half_open"
+                    self._logger.info("KMS circuit breaker transitioned to half_open — attempting recovery")
+                else:
+                    raise KmsError("KMS circuit breaker is open — failing fast")
+
+            # Build retrieve request with retry logic
+            max_attempts = 2
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    request_id = str(uuid.uuid4())
+                    retrieve_body = {
+                        "client": {
+                            "clientId": self._device_url,
+                            "credential": {
+                                "userId": self._user_id,
+                                "bearer": self._token,
+                            },
+                        },
+                        "method": "retrieve",
+                        "uri": key_uri,
+                        "requestId": request_id,
+                    }
+
+                    # Wrap with ephemeral key (dir + A256GCM — key is CEK directly)
+                    wrapped = _jwe_encrypt(
+                        plaintext=json.dumps(retrieve_body).encode(),
+                        key=self._ephemeral_key,
+                        alg="dir",
+                        enc="A256GCM",
+                    )
 
-            content_key = jwk.JWK(**key_data)
+                    # POST and wait for Mercury response
+                    wrapped_response = await self._send_kms_request(request_id, wrapped)
 
-            # Bound key cache size
-            if len(self._key_cache) > 100:
-                self._logger.warning(f"Key cache size exceeded (size={len(self._key_cache)}), clearing cache")
-                self._key_cache.clear()
+                    # Unwrap response
+                    response_body = _unwrap_kms_response(wrapped_response, self._ephemeral_key)
+                    response_data = json.loads(response_body)
 
-            self._key_cache[key_uri] = content_key
-            self._logger.info(f"Key retrieved and cached: {key_uri}")
-            return content_key
+                    # Extract the content key
+                    key_data = (
+                        response_data.get("body", {}).get("key", {}).get("jwk")
+                        or response_data.get("key", {}).get("jwk")
+                    )
+                    if (
+                        not key_data
+                        and "body" in response_data
+                        and "key" in response_data["body"]
+                    ):
+                        key_obj = response_data["body"]["key"]
+                        key_data = key_obj["jwk"] if isinstance(key_obj, dict) and "jwk" in key_obj else key_obj
+
+                    if not key_data:
+                        raise KmsError("No key found in KMS response")
+
+                    if isinstance(key_data, str):
+                        key_data = json.loads(key_data)
+
+                    content_key = jwk.JWK(**key_data)
+
+                    # Bound key cache size
+                    if len(self._key_cache) > 100:
+                        self._logger.warning(f"Key cache size exceeded (size={len(self._key_cache)}), clearing cache")
+                        self._key_cache.clear()
+
+                    self._key_cache[key_uri] = content_key
+                    self._logger.info(f"Key retrieved and cached: {key_uri}")
+                    self._cb_reset()
+                    return content_key
+                except KmsError as exc:
+                    if attempt < max_attempts and self._is_retryable_kms_error(exc):
+                        self._logger.warning(
+                            f"KMS key fetch failed (attempt {attempt}/{max_attempts}), retrying in 1s: {exc}"
+                        )
+                        await asyncio.sleep(1.0)
+                        continue
+                    self._cb_record_failure()
+                    raise
 
         except KmsError:
             raise
         except Exception as exc:
+            self._cb_record_failure()
             raise KmsError(f"Failed to get key: {exc}") from exc
 
     async def _send_kms_request(self, request_id: str, wrapped: str) -> str:
@@ -355,6 +385,26 @@ class KmsClient:
         buffer = timedelta(seconds=30)
         return datetime.now(timezone.utc) > (self._context_expiration - buffer)
 
+    def _is_retryable_kms_error(self, error: Exception) -> bool:
+        """Check if a KMS error is retryable (transient failure)."""
+        msg = str(error).lower()
+        return "timed out" in msg or "http request failed" in msg
+
+    def _cb_reset(self) -> None:
+        """Reset circuit breaker to closed state (KMS recovered)."""
+        if self._cb_state != "closed":
+            self._logger.info("KMS circuit breaker closed — KMS recovered")
+        self._cb_state = "closed"
+        self._cb_failures = 0
+
+    def _cb_record_failure(self) -> None:
+        """Record a KMS failure and update circuit breaker state."""
+        self._cb_failures += 1
+        self._cb_last_failure = time.monotonic()
+        if self._cb_failures >= CB_FAILURE_THRESHOLD:
+            self._cb_state = "open"
+            self._logger.warning(f"KMS circuit breaker opened after {self._cb_failures} consecutive failures")
+
 
 class _PendingRequest:
     """A pending KMS request awaiting Mercury response."""

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/src/webex_message_handler/types.py

@@ -107,6 +107,9 @@ class WebexMessageHandlerConfig:
     ignore_self_messages: bool = True
     """Automatically filter out messages sent by this bot to prevent loops (default: True)."""
 
+    metrics_callback: "MetricsCallback | None" = None
+    """Optional metrics callback for timing events (no overhead if not set)."""
+
 
 # --- Device Registration ---
 
@@ -359,3 +362,26 @@ class HandlerStatus:
 
     reconnect_attempt: int
     """Current auto-reconnect attempt number (0 if not reconnecting)."""
+
+
+# --- Metrics ---
+
+
+@dataclass
+class MetricsEvent:
+    """A timing metric event."""
+
+    name: str
+    """Metric name: 'connect', 'kms_fetch', or 'decrypt'."""
+
+    duration_ms: float
+    """Duration in milliseconds."""
+
+    success: bool
+    """Whether the operation succeeded."""
+
+    metadata: dict[str, str] | None = None
+    """Optional context metadata (e.g., key URI for kms_fetch)."""
+
+
+MetricsCallback = Callable[["MetricsEvent"], None]

{webex_message_handler-0.6.7 → webex_message_handler-0.6.9}/src/webex_message_handler/url_validation.py

@@ -2,7 +2,7 @@
 
 from urllib.parse import urlparse
 
-ALLOWED_DOMAIN_SUFFIXES = ('.webex.com', '.wbx2.com', '.ciscospark.com', '.example.com')
+ALLOWED_WEBEX_DOMAINS = ("webex.com", "wbx2.com", "ciscospark.com", "example.com")
 
 
 def validate_webex_url(raw_url: str, required_scheme: str) -> None:
@@ -19,5 +19,5 @@ def validate_webex_url(raw_url: str, required_scheme: str) -> None:
     if parsed.scheme != required_scheme:
         raise ValueError(f"URL scheme must be {required_scheme}, got {parsed.scheme}")
     host = (parsed.hostname or "").lower()
-    if not any(host.endswith(suffix) for suffix in ALLOWED_DOMAIN_SUFFIXES):
+    if not any(host == domain or host.endswith(f".{domain}") for domain in ALLOWED_WEBEX_DOMAINS):
         raise ValueError(f"URL host {host} is not a recognized Webex domain")

webex_message_handler-0.6.9/tests/test_kms_client.py

@@ -0,0 +1,103 @@
+"""Tests for KmsClient."""
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+from jwcrypto import jwk
+from jwcrypto.common import base64url_encode
+
+from webex_message_handler.errors import KmsError
+from webex_message_handler.kms_client import KmsClient
+from webex_message_handler.types import FetchRequest
+
+
+class _FakeFetchResponse:
+    def __init__(self, *, status: int, ok: bool, payload: dict[str, object]) -> None:
+        self.status = status
+        self.ok = ok
+        self._payload = payload
+
+    async def json(self) -> dict[str, object]:
+        return self._payload
+
+    async def text(self) -> str:
+        return json.dumps(self._payload)
+
+
+def _make_kms_response_token(payload: dict[str, object]) -> str:
+    header = base64url_encode(b'{"alg":"none"}')
+    body = base64url_encode(json.dumps(payload).encode("utf-8"))
+    signature = base64url_encode(b"signature")
+    return f"{header}.{body}.{signature}"
+
+
+def _build_kms_details(*, kms_cluster: str) -> dict[str, object]:
+    rsa_public_key = jwk.JWK.generate(kty="RSA", size=2048)
+    return {
+        "kmsCluster": kms_cluster,
+        "rsaPublicKey": json.loads(rsa_public_key.export_public()),
+    }
+
+
+@pytest.mark.asyncio
+async def test_initialize_accepts_kms_cluster_url() -> None:
+    requests: list[FetchRequest] = []
+    kms_details = _build_kms_details(kms_cluster="kms://ciscospark.com/keys")
+    remote_key = jwk.JWK.generate(kty="EC", crv="P-256")
+    wrapped_response = _make_kms_response_token(
+        {
+            "body": {
+                "key": {
+                    "jwk": json.loads(remote_key.export_public()),
+                    "uri": "kms://ciscospark.com/keys/key/123",
+                    "expirationDate": "2026-01-01T00:00:00Z",
+                }
+            }
+        }
+    )
+
+    async def http_do(request: FetchRequest) -> _FakeFetchResponse:
+        requests.append(request)
+        return _FakeFetchResponse(status=200, ok=True, payload=kms_details)
+
+    client = KmsClient(
+        token="test-token",
+        device_url="https://device.example.com",
+        user_id="user-123",
+        encryption_service_url="https://encryption.example.com",
+        http_do=http_do,
+    )
+    client._send_kms_request = AsyncMock(return_value=wrapped_response)  # type: ignore[method-assign]
+
+    await client.initialize()
+
+    assert client._initialized is True
+    assert client._kms_cluster == "kms://ciscospark.com/keys"
+    assert client._ephemeral_key is not None
+    assert client._ephemeral_key.get("kid") == "kms://ciscospark.com/keys/key/123"
+    assert len(requests) == 1
+    assert requests[0].method == "GET"
+    assert requests[0].url == "https://encryption.example.com/kms/user-123"
+
+
+@pytest.mark.asyncio
+async def test_initialize_rejects_https_kms_cluster_url() -> None:
+    kms_details = _build_kms_details(kms_cluster="https://ciscospark.com/keys")
+
+    async def http_do(request: FetchRequest) -> _FakeFetchResponse:
+        return _FakeFetchResponse(status=200, ok=True, payload=kms_details)
+
+    client = KmsClient(
+        token="test-token",
+        device_url="https://device.example.com",
+        user_id="user-123",
+        encryption_service_url="https://encryption.example.com",
+        http_do=http_do,
+    )
+    client._send_kms_request = AsyncMock()  # type: ignore[method-assign]
+
+    with pytest.raises(KmsError, match="URL scheme must be kms, got https"):
+        await client.initialize()
+
+    client._send_kms_request.assert_not_called()