webex-message-handler 0.6.8__tar.gz → 0.6.10__tar.gz

{webex_message_handler-0.6.8 → webex_message_handler-0.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.8
+Version: 0.6.10
 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
 
@@ -219,6 +234,27 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 - **`await reconnect(new_token)`** — Update token and re-establish connection
 - **`status()`** — Returns `HandlerStatus` health check
 - **`connected`** — `bool` property: whether currently connected
+- **`device_registration()`** — Read-only copy of the WDM registration (`None` before connect)
+- **`service_url(name)`** — Look up a single WDM service URL by name (`None` if unknown)
+
+##### Outbound calls from wrappers
+
+This library is **inbound-only** — it never makes outbound calls. If your wrapper
+needs to send something back to Webex (e.g. a Conversation-service read-receipt),
+discover the service base URL from the WDM catalog the library already holds
+rather than hardcoding cluster hostnames (which vary across clusters and orgs):
+
+```python
+# Resolve a cluster-correct service URL after connect()
+conv_url = handler.service_url("conversationServiceUrl")
+if conv_url:
+    # Build your outbound acknowledge/activity request against conv_url.
+    # The activity URL needed for the acknowledge object is msg.url.
+    ...
+
+# Or grab the whole (read-only) registration:
+reg = handler.device_registration()  # None before connect()
+```
 
 #### Events
 
@@ -242,6 +278,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    url: str | None         # Conversation-service activity URL (when present)
     parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str

{webex_message_handler-0.6.8 → webex_message_handler-0.6.10}/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
 
@@ -187,6 +202,27 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 - **`await reconnect(new_token)`** — Update token and re-establish connection
 - **`status()`** — Returns `HandlerStatus` health check
 - **`connected`** — `bool` property: whether currently connected
+- **`device_registration()`** — Read-only copy of the WDM registration (`None` before connect)
+- **`service_url(name)`** — Look up a single WDM service URL by name (`None` if unknown)
+
+##### Outbound calls from wrappers
+
+This library is **inbound-only** — it never makes outbound calls. If your wrapper
+needs to send something back to Webex (e.g. a Conversation-service read-receipt),
+discover the service base URL from the WDM catalog the library already holds
+rather than hardcoding cluster hostnames (which vary across clusters and orgs):
+
+```python
+# Resolve a cluster-correct service URL after connect()
+conv_url = handler.service_url("conversationServiceUrl")
+if conv_url:
+    # Build your outbound acknowledge/activity request against conv_url.
+    # The activity URL needed for the acknowledge object is msg.url.
+    ...
+
+# Or grab the whole (read-only) registration:
+reg = handler.device_registration()  # None before connect()
+```
 
 #### Events
 
@@ -210,6 +246,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 @dataclass
 class DecryptedMessage:
     id: str
+    url: str | None         # Conversation-service activity URL (when present)
     parent_id: str | None   # Parent activity UUID (threaded replies)
     room_id: str
     person_id: str

{webex_message_handler-0.6.8 → webex_message_handler-0.6.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.6.8"
+version = "0.6.10"
 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.8 → webex_message_handler-0.6.10}/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.8 → webex_message_handler-0.6.10}/src/webex_message_handler/handler.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import time
 from collections.abc import Callable
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any
 
 import aiohttp
@@ -27,6 +28,7 @@ from .types import (
     HandlerStatus,
     InjectedWebSocket,
     MembershipActivity,
+    MetricsEvent,
     MercuryActivity,
     RoomActivity,
     WebexMessageHandlerConfig,
@@ -125,6 +127,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 +155,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:
@@ -200,7 +209,16 @@ class WebexMessageHandler:
     ) -> WebSocketFactory:
         """Create WebSocket adapter using native aiohttp."""
         async def ws_factory(url: str) -> InjectedWebSocket:
-            session = aiohttp.ClientSession(connector=connector)
+            # When a shared connector is provided, don't let the session close it
+            # when the WebSocket is rotated on reconnect — otherwise the next HTTP
+            # call (and every subsequent reconnect) fails with "Connector is closed".
+            # When no connector is provided, let the session own (and close) the
+            # auto-created one. Mirrors _create_native_http_adapter's ownership logic.
+            session = aiohttp.ClientSession(
+                connector=connector,
+                connector_owner=connector is None,
+                trust_env=True,
+            )
             ws = await session.ws_connect(url, max_msg_size=1 * 1024 * 1024)  # 1MB
 
             # Attach session for cleanup
@@ -275,6 +293,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 +333,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:
@@ -378,6 +399,34 @@ class WebexMessageHandler:
             reconnect_attempt=reconnect_attempt,
         )
 
+    def device_registration(self) -> DeviceRegistration | None:
+        """Return a read-only copy of the WDM registration obtained at connect
+        time, or None if not yet connected.
+
+        This library stays inbound-only — it does not make outbound calls. This
+        accessor exists so wrapper code can perform its own outbound calls (e.g.
+        a Conversation-service read-receipt) using the service catalog the
+        library already holds. Resolve outbound URLs from ``services`` rather
+        than hardcoding cluster hostnames, which vary across clusters and orgs.
+
+        The returned value is a copy: mutating it does not affect internal state.
+        """
+        if self._registration is None:
+            return None
+        return replace(self._registration, services=dict(self._registration.services))
+
+    def service_url(self, name: str) -> str | None:
+        """Return the URL for a named WDM service from the registration's
+        service catalog (e.g. ``"conversationServiceUrl"``), or None if not yet
+        connected or the service is unknown.
+
+        Use this to discover outbound service base URLs instead of hardcoding
+        cluster hostnames. See :meth:`device_registration` for the rationale.
+        """
+        if self._registration is None:
+            return None
+        return self._registration.services.get(name)
+
     async def _fetch_bot_person_id(self) -> None:
         """Fetch the bot's person ID for self-message filtering.
 
@@ -468,10 +517,18 @@ 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,
+                url=decrypted.url,
                 room_id=decrypted.target.id,
                 person_id=decrypted.actor.id,
                 person_email=decrypted.actor.email_address or "",

{webex_message_handler-0.6.8 → webex_message_handler-0.6.10}/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.
 
@@ -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.8 → webex_message_handler-0.6.10}/src/webex_message_handler/mercury_socket.py

@@ -421,6 +421,7 @@ def _parse_activity(raw: dict[str, Any]) -> MercuryActivity:
             tags=target_raw.get("tags", []),
         ),
         published=raw.get("published", ""),
+        url=raw.get("url"),
         encryption_key_url=raw.get("encryptionKeyUrl"),
         parent=parent,
     )

{webex_message_handler-0.6.8 → webex_message_handler-0.6.10}/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 ---
 
@@ -185,6 +188,9 @@ class MercuryActivity:
     object: MercuryObject
     target: MercuryTarget
     published: str
+    url: str | None = None
+    """Full Conversation-service activity URL, when present on the raw activity."""
+
     encryption_key_url: str | None = None
     parent: MercuryParent | None = None
 
@@ -224,6 +230,11 @@ class DecryptedMessage:
     created: str
     """ISO 8601 timestamp."""
 
+    url: str | None = None
+    """Full Conversation-service activity URL, when present on the raw Mercury
+    activity (e.g. for an outbound "acknowledge" read-receipt). None if Mercury
+    did not include it."""
+
     parent_id: str | None = None
     """Parent activity UUID for threaded replies. None if not a thread reply."""
 
@@ -359,3 +370,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.8 → webex_message_handler-0.6.10}/tests/test_handler.py

@@ -7,6 +7,7 @@ import pytest
 from webex_message_handler.handler import WebexMessageHandler
 from webex_message_handler.types import (
     DeviceRegistration,
+    FetchRequest,
     MercuryActivity,
     MercuryActor,
     MercuryObject,
@@ -109,6 +110,83 @@ class TestModeValidation:
             _make_handler(mode="invalid")
 
 
+class TestNativeConnectorOwnership:
+    """Regression tests for issue #20: a shared connector must survive WebSocket
+    rotation on reconnect. The WS session must not own (and therefore close) a
+    caller-provided connector."""
+
+    async def test_ws_adapter_does_not_own_shared_connector(self):
+        shared_connector = MagicMock()
+        handler = _make_handler(mode="native", connector=shared_connector)
+
+        captured = {}
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def ws_connect(self, *args, **kwargs):
+                return MagicMock()
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._ws_factory("wss://mercury.example.com/socket")
+
+        # The WS session must not own the shared connector, otherwise closing the
+        # session on reconnect drags the shared connector down with it.
+        assert captured["connector"] is shared_connector
+        assert captured["connector_owner"] is False
+
+    async def test_ws_adapter_owns_auto_created_connector(self):
+        handler = _make_handler(mode="native")  # no connector → auto-created
+
+        captured = {}
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def ws_connect(self, *args, **kwargs):
+                return MagicMock()
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._ws_factory("wss://mercury.example.com/socket")
+
+        # With no shared connector, the session owns the auto-created one and
+        # is responsible for closing it.
+        assert captured["connector"] is None
+        assert captured["connector_owner"] is True
+
+    async def test_http_adapter_does_not_own_shared_connector(self):
+        shared_connector = MagicMock()
+        handler = _make_handler(mode="native", connector=shared_connector)
+
+        captured = {}
+
+        class FakeResponse:
+            status = 200
+
+            async def read(self):
+                return b"{}"
+
+        class FakeSession:
+            def __init__(self, **kwargs):
+                captured.update(kwargs)
+
+            async def request(self, *args, **kwargs):
+                return FakeResponse()
+
+            async def close(self):
+                pass
+
+        with patch("aiohttp.ClientSession", FakeSession):
+            await handler._http_do(
+                FetchRequest(url="https://example.com", method="GET", headers={})
+            )
+
+        assert captured["connector"] is shared_connector
+        assert captured["connector_owner"] is False
+
+
 class TestConnect:
     @patch("webex_message_handler.handler.MessageDecryptor")
     @patch("webex_message_handler.handler.KmsClient")
@@ -256,6 +334,22 @@ class TestMessageHandling:
         assert msg.id == "msg-123"
         assert msg.parent_id == "parent-activity-uuid"
 
+    async def test_handle_message_propagates_url(self):
+        handler = _make_handler()
+        handler._message_decryptor = MagicMock()
+        activity = _make_activity(
+            url="https://conv-a.wbx2.com/conversation/api/v1/activities/msg-123",
+        )
+        handler._message_decryptor.decrypt_activity = AsyncMock(return_value=activity)
+
+        messages = []
+        handler.on("message:created", lambda msg: messages.append(msg))
+
+        await handler._handle_activity(activity)
+
+        assert len(messages) == 1
+        assert messages[0].url == "https://conv-a.wbx2.com/conversation/api/v1/activities/msg-123"
+
     async def test_handle_message_deleted(self):
         handler = _make_handler()
         activity = _make_activity(
@@ -458,3 +552,42 @@ class TestEventSystem:
         handler.on("connected", callback)
         handler.off("connected", callback)
         assert callback not in handler._listeners["connected"]
+
+
+class TestDeviceRegistrationAccessor:
+    """Issue #23: expose the WDM services catalog read-only so wrappers can make
+    outbound calls without hardcoding cluster hostnames."""
+
+    def test_returns_none_before_connect(self):
+        handler = _make_handler()
+        assert handler.device_registration() is None
+        assert handler.service_url("conversationServiceUrl") is None
+
+    def test_returns_registration_after_connect(self):
+        handler = _make_handler()
+        handler._registration = MOCK_REGISTRATION
+
+        reg = handler.device_registration()
+        assert reg is not None
+        assert reg.user_id == "user-123"
+        assert reg.services["encryptionServiceUrl"] == "https://encryption.example.com"
+        assert handler.service_url("messenger") == "https://messenger.example.com"
+        assert handler.service_url("nonexistent") is None
+
+    def test_returned_copy_is_isolated(self):
+        handler = _make_handler()
+        handler._registration = DeviceRegistration(
+            web_socket_url="wss://mercury.example.com/socket",
+            device_url="https://device.example.com",
+            user_id="user-123",
+            services={"encryptionServiceUrl": "https://encryption.example.com"},
+            encryption_service_url="https://encryption.example.com",
+        )
+
+        reg = handler.device_registration()
+        reg.services["encryptionServiceUrl"] = "https://evil.example.com"
+        reg.user_id = "tampered"
+
+        # Internal state must be unaffected by mutating the returned copy.
+        assert handler._registration.services["encryptionServiceUrl"] == "https://encryption.example.com"
+        assert handler._registration.user_id == "user-123"