webex-message-handler 0.6.13__tar.gz → 0.6.14__tar.gz

{webex_message_handler-0.6.13 → webex_message_handler-0.6.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.6.13
+Version: 0.6.14
 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
@@ -188,6 +188,15 @@ async def on_message(msg):
 
 Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
 
+## Region Discovery
+
+Webex assigns each org to a service region (e.g. `wdm-a`, `wdm-r`). On connect,
+the library discovers your org's correct WDM endpoint from the Webex U2C service
+catalog and registers there automatically — no configuration needed. Registering
+in the wrong region produces a socket that authorizes and completes the KMS
+handshake but never receives that org's messages, so this is done for you. If
+discovery fails for any reason, it falls back to the default region.
+
 ## Delivery Guarantees
 
 This library provides **at-most-once** delivery semantics:

{webex_message_handler-0.6.13 → webex_message_handler-0.6.14}/README.md

@@ -157,6 +157,15 @@ async def on_message(msg):
 
 Resource types: `"MESSAGE"`, `"PEOPLE"`, `"ROOM"`.
 
+## Region Discovery
+
+Webex assigns each org to a service region (e.g. `wdm-a`, `wdm-r`). On connect,
+the library discovers your org's correct WDM endpoint from the Webex U2C service
+catalog and registers there automatically — no configuration needed. Registering
+in the wrong region produces a socket that authorizes and completes the KMS
+handshake but never receives that org's messages, so this is done for you. If
+discovery fails for any reason, it falls back to the default region.
+
 ## Delivery Guarantees
 
 This library provides **at-most-once** delivery semantics:

{webex_message_handler-0.6.13 → webex_message_handler-0.6.14}/pyproject.toml

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

@@ -11,6 +11,7 @@ from .types import DeviceRegistration, FetchFunction, FetchRequest
 from .url_validation import validate_webex_url
 
 WDM_API_BASE = "https://wdm-a.wbx2.com/wdm/api/v1/devices"
+U2C_CATALOG_URL = "https://u2c.wbx2.com/u2c/api/v1/catalog?format=hostmap"
 
 _DEVICE_BODY = {
     "deviceName": "webex-message-handler",
@@ -35,6 +36,66 @@ class DeviceManager:
         self._logger: Logger = logger or noop_logger  # type: ignore[assignment]
         self._http_do = http_do
         self._device_url: str | None = None
+        self._wdm_devices_url: str | None = None
+
+    async def _discover_wdm_base(self, token: str) -> str:
+        """Discover the org-assigned WDM devices endpoint from U2C.
+
+        Caches the result. On any failure falls back to the hard-coded WDM_API_BASE
+        (never fatal), so a U2C outage degrades to today's behavior.
+        """
+        if self._wdm_devices_url:
+            return self._wdm_devices_url
+
+        try:
+            response = await self._http_do(
+                FetchRequest(
+                    url=U2C_CATALOG_URL,
+                    method="GET",
+                    headers={"Authorization": f"Bearer {token}"},
+                )
+            )
+
+            if not response.ok:
+                self._logger.warning(
+                    f"U2C discovery returned {response.status}; falling back to {WDM_API_BASE}"
+                )
+                self._wdm_devices_url = WDM_API_BASE
+                return self._wdm_devices_url
+
+            catalog = await response.json()
+            wdm = catalog.get("serviceLinks", {}).get("wdm")
+
+            if not wdm:
+                self._logger.warning(
+                    f"U2C catalog has no wdm service link; falling back to {WDM_API_BASE}"
+                )
+                self._wdm_devices_url = WDM_API_BASE
+                return self._wdm_devices_url
+
+            try:
+                validate_webex_url(wdm, "https")
+            except ValueError as exc:
+                self._logger.error(
+                    f'U2C-discovered wdm URL "{wdm}" untrusted ({exc}); falling back to {WDM_API_BASE}'
+                )
+                self._wdm_devices_url = WDM_API_BASE
+                return self._wdm_devices_url
+
+            self._wdm_devices_url = wdm.rstrip("/") + "/devices"
+            self._logger.info(f"Discovered region-correct WDM endpoint: {self._wdm_devices_url}")
+            return self._wdm_devices_url
+
+        except Exception as exc:
+            self._logger.warning(
+                f"U2C discovery failed ({exc}); falling back to {WDM_API_BASE}"
+            )
+            self._wdm_devices_url = WDM_API_BASE
+            return self._wdm_devices_url
+
+    def set_wdm_devices_url(self, url: str) -> None:
+        """Pre-seed the discovered WDM devices endpoint (test helper)."""
+        self._wdm_devices_url = url
 
     async def register(self, token: str) -> DeviceRegistration:
         """Register a new device with WDM.
@@ -75,7 +136,8 @@ class DeviceManager:
     async def _create_device(self, token: str) -> DeviceRegistration:
         """Perform the raw POST /devices registration."""
         try:
-            create_url = f"{WDM_API_BASE}?includeUpstreamServices=all"
+            base = await self._discover_wdm_base(token)
+            create_url = f"{base}?includeUpstreamServices=all"
             response = await self._http_do(
                 FetchRequest(
                     url=create_url,
@@ -159,10 +221,11 @@ class DeviceManager:
             self._logger.warning(f"Could not list devices to reap: {exc}")
 
     async def _list_devices(self, token: str) -> list[Any]:
-        """Fetches the account's current WDM device registrations."""
+        """Fetches the account's current WDM device registrations from the region-correct endpoint."""
+        base = await self._discover_wdm_base(token)
         response = await self._http_do(
             FetchRequest(
-                url=WDM_API_BASE,
+                url=base,
                 method="GET",
                 headers={"Authorization": f"Bearer {token}"},
             )

{webex_message_handler-0.6.13 → webex_message_handler-0.6.14}/tests/test_device_manager.py

@@ -3,7 +3,7 @@
 import pytest
 
 from tests.conftest import MockHttpDo
-from webex_message_handler.device_manager import WDM_API_BASE, DeviceManager
+from webex_message_handler.device_manager import U2C_CATALOG_URL, WDM_API_BASE, DeviceManager
 from webex_message_handler.errors import AuthError, DeviceRegistrationError
 
 MOCK_TOKEN = "test-token"
@@ -30,6 +30,7 @@ class TestRegister:
             .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         result = await dm.register(MOCK_TOKEN)
 
         assert result.web_socket_url == MOCK_WS_URL
@@ -45,6 +46,7 @@ class TestRegister:
             .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", status=401)  # create fails with 401
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         with pytest.raises(AuthError):
             await dm.register(MOCK_TOKEN)
 
@@ -55,6 +57,7 @@ class TestRegister:
             .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", status=400)  # create fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         with pytest.raises(DeviceRegistrationError, match="Failed to register device"):
             await dm.register(MOCK_TOKEN)
 
@@ -69,6 +72,7 @@ class TestRegister:
             )  # create fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         with pytest.raises(DeviceRegistrationError):
             await dm.register(MOCK_TOKEN)
 
@@ -83,6 +87,7 @@ class TestRefresh:
             .add("PUT", MOCK_DEVICE_URL, payload=refreshed)  # refresh
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         result = await dm.refresh(MOCK_TOKEN)
 
@@ -102,6 +107,7 @@ class TestRefresh:
             .add("PUT", MOCK_DEVICE_URL, status=401)  # refresh fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         with pytest.raises(AuthError):
             await dm.refresh(MOCK_TOKEN)
@@ -114,6 +120,7 @@ class TestRefresh:
             .add("PUT", MOCK_DEVICE_URL, status=500)  # refresh fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         with pytest.raises(DeviceRegistrationError):
             await dm.refresh(MOCK_TOKEN)
@@ -128,6 +135,7 @@ class TestUnregister:
             .add("DELETE", MOCK_DEVICE_URL, status=204)  # unregister
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         await dm.unregister(MOCK_TOKEN)
 
@@ -145,6 +153,7 @@ class TestUnregister:
             .add("DELETE", MOCK_DEVICE_URL, status=401)  # unregister fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         with pytest.raises(AuthError):
             await dm.unregister(MOCK_TOKEN)
@@ -157,6 +166,7 @@ class TestUnregister:
             .add("DELETE", MOCK_DEVICE_URL, status=500)  # unregister fails
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         await dm.register(MOCK_TOKEN)
         with pytest.raises(DeviceRegistrationError):
             await dm.unregister(MOCK_TOKEN)
@@ -216,6 +226,7 @@ class TestDeviceReuseAndReaping:
             .add("PUT", MOCK_DEVICE_URL, payload=MOCK_WDM_RESPONSE)
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         result = await dm.register(MOCK_TOKEN)
 
         assert result.device_url == MOCK_DEVICE_URL
@@ -249,6 +260,7 @@ class TestDeviceReuseAndReaping:
             .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # retry POST
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         result = await dm.register(MOCK_TOKEN)
 
         assert result.device_url == MOCK_DEVICE_URL
@@ -268,8 +280,127 @@ class TestDeviceReuseAndReaping:
             .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create succeeds
         )
         dm = DeviceManager(http_do=http_do)
+        dm.set_wdm_devices_url(WDM_API_BASE)
         result = await dm.register(MOCK_TOKEN)
 
         assert result.device_url == MOCK_DEVICE_URL
         # Should be: GET (list fails) + POST (create succeeds)
         assert len(http_do.calls) == 2
+
+
+class TestU2CRegionDiscovery:
+    """Tests for U2C region discovery (#27)."""
+
+    async def test_discovers_region_correct_wdm_endpoint_from_u2c(self):
+        """Verify that register resolves the org-assigned WDM region from U2C."""
+        u2c_catalog = {"serviceLinks": {"wdm": "https://wdm-r.wbx2.com/wdm/api/v1"}}
+        regional_device_url = "https://wdm-r.wbx2.com/wdm/api/v1/devices/test-device-id"
+        regional_response = {**MOCK_WDM_RESPONSE, "url": regional_device_url}
+
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, payload=u2c_catalog)  # U2C discovery
+            .add("GET", "https://wdm-r.wbx2.com/wdm/api/v1/devices", payload={"devices": []})  # list
+            .add(
+                "POST",
+                "https://wdm-r.wbx2.com/wdm/api/v1/devices?includeUpstreamServices=all",
+                payload=regional_response,
+            )  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+        result = await dm.register(MOCK_TOKEN)
+
+        assert result.device_url == regional_device_url
+        # Verify POST went to discovered regional endpoint, not hardcoded wdm-a
+        post_calls = [c for c in http_do.calls if c.method == "POST"]
+        assert "wdm-r.wbx2.com" in post_calls[0].url
+
+    async def test_caches_discovered_wdm_endpoint(self):
+        """Verify that the discovered WDM endpoint is cached."""
+        u2c_catalog = {"serviceLinks": {"wdm": "https://wdm-r.wbx2.com/wdm/api/v1"}}
+
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, payload=u2c_catalog)  # U2C discovery (first call)
+            .add("GET", "https://wdm-r.wbx2.com/wdm/api/v1/devices", payload={"devices": []})  # list
+            .add(
+                "POST",
+                "https://wdm-r.wbx2.com/wdm/api/v1/devices?includeUpstreamServices=all",
+                payload={**MOCK_WDM_RESPONSE, "url": "https://wdm-r.wbx2.com/wdm/api/v1/devices/id1"},
+            )  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+
+        # Register once; U2C should be called
+        await dm.register(MOCK_TOKEN)
+        u2c_calls = [c for c in http_do.calls if "u2c.wbx2.com" in c.url]
+        assert len(u2c_calls) == 1
+
+        # Pre-seed the cache
+        dm.set_wdm_devices_url("https://wdm-r.wbx2.com/wdm/api/v1/devices")
+        # Verify cache doesn't trigger another U2C call (would fail with assertion)
+
+    async def test_falls_back_to_wdm_a_when_u2c_returns_non_2xx(self):
+        """Verify discovery is best-effort: non-2xx U2C falls back to wdm-a."""
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, status=500)  # U2C discovery fails
+            .add("GET", WDM_API_BASE, payload={"devices": []})  # list uses fallback
+            .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+        result = await dm.register(MOCK_TOKEN)
+
+        assert result.device_url == MOCK_DEVICE_URL
+        # Verify POST went to fallback wdm-a
+        post_calls = [c for c in http_do.calls if c.method == "POST"]
+        assert "wdm-a.wbx2.com" in post_calls[0].url
+
+    async def test_falls_back_to_wdm_a_when_u2c_has_no_wdm_link(self):
+        """Verify that missing wdm link in U2C response falls back to wdm-a."""
+        u2c_catalog = {"serviceLinks": {}}  # Missing wdm link
+
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, payload=u2c_catalog)  # U2C discovery
+            .add("GET", WDM_API_BASE, payload={"devices": []})  # list uses fallback
+            .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+        result = await dm.register(MOCK_TOKEN)
+
+        assert result.device_url == MOCK_DEVICE_URL
+        post_calls = [c for c in http_do.calls if c.method == "POST"]
+        assert "wdm-a.wbx2.com" in post_calls[0].url
+
+    async def test_rejects_untrusted_wdm_host_from_u2c_and_falls_back(self):
+        """Verify that non-Webex wdm link from U2C is rejected and falls back."""
+        u2c_catalog = {"serviceLinks": {"wdm": "https://evil.attacker.com/wdm/api/v1"}}
+
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, payload=u2c_catalog)  # U2C discovery
+            .add("GET", WDM_API_BASE, payload={"devices": []})  # list uses fallback
+            .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+        result = await dm.register(MOCK_TOKEN)
+
+        assert result.device_url == MOCK_DEVICE_URL
+        post_calls = [c for c in http_do.calls if c.method == "POST"]
+        assert "wdm-a.wbx2.com" in post_calls[0].url
+
+    async def test_falls_back_to_wdm_a_on_u2c_fetch_error(self):
+        """Verify that U2C fetch errors fall back to wdm-a."""
+        http_do = (
+            MockHttpDo()
+            .add("GET", U2C_CATALOG_URL, exc=ConnectionError("Network error"))  # U2C discovery fails
+            .add("GET", WDM_API_BASE, payload={"devices": []})  # list uses fallback
+            .add("POST", f"{WDM_API_BASE}?includeUpstreamServices=all", payload=MOCK_WDM_RESPONSE)  # create
+        )
+        dm = DeviceManager(http_do=http_do)
+        result = await dm.register(MOCK_TOKEN)
+
+        assert result.device_url == MOCK_DEVICE_URL
+        post_calls = [c for c in http_do.calls if c.method == "POST"]
+        assert "wdm-a.wbx2.com" in post_calls[0].url