feat: extensibility ums destination changes

src/sap_cloud_sdk/extensibility/_ums_transport.py

@@ -22,7 +22,6 @@
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 import httpx
-
 from sap_cloud_sdk.core.telemetry import Module
 from sap_cloud_sdk.destination import ConsumptionLevel
 from sap_cloud_sdk.destination import create_client as create_destination_client
@@ -41,6 +40,7 @@
     OnFailure,
 )
 from sap_cloud_sdk.extensibility.exceptions import TransportError
+from sap_cloud_sdk.destination import ConsumptionOptions
 
 if TYPE_CHECKING:
     from sap_cloud_sdk.extensibility.config import ExtensibilityConfig
@@ -53,7 +53,8 @@
 
 ENV_CONHOS_LANDSCAPE = "APPFND_CONHOS_LANDSCAPE"
 ENV_UMS_DESTINATION_NAME = "APPFND_UMS_DESTINATION_NAME"
-_UMS_DESTINATION_PREFIX = "sap-managed-runtime-ums-"
+ENV_UMS_URL = "APPFND_CONHOS_UMS_URL"
+_IAS_DESTINATION_PREFIX = "sap-managed-runtime-ias-"
 
 # ---------------------------------------------------------------------------
 # GraphQL query
@@ -182,24 +183,25 @@ def _parse_method_safe(value: str) -> HTTPMethod:
 
 
 def _ums_destination_name(config_override: Optional[str] = None) -> Optional[str]:
-    """Construct the UMS destination name from configuration or environment.
+    """Construct the IAS destination name from configuration or environment.
 
     Resolution order:
 
     1. **Config override** -- if ``config.destination_name`` is set, use
        it directly.
     2. **Explicit env var override** -- if ``APPFND_UMS_DESTINATION_NAME``
-       is set, use its value directly.  This is useful in subaccounts
-       where the UMS destination follows a non-standard naming convention.
-    3. **Landscape-based construction** -- the destination name is built as
-       ``sap-managed-runtime-ums-{APPFND_CONHOS_LANDSCAPE}``.
+       is set, use its value directly.
+    3. **Landscape-based construction** -- built as
+       ``sap-managed-runtime-ias-{APPFND_CONHOS_LANDSCAPE}``.
+       ``APPFND_CONHOS_UMS_URL`` must be set; a warning is logged and
+       ``None`` is returned if it is absent.
 
     Args:
         config_override: Optional destination name from
             :class:`ExtensibilityConfig`.  Takes highest priority when set.
 
     Returns:
-        The resolved UMS destination name, or ``None`` if no configuration
+        The resolved destination name, or ``None`` if no configuration
         or environment variables are available to determine it.
     """
     # 0. Config-level override takes highest priority
@@ -232,9 +234,18 @@ def _ums_destination_name(config_override: Optional[str] = None) -> Optional[str
         )
         return None
 
-    destination_name = f"{_UMS_DESTINATION_PREFIX}{landscape}"
+    if not os.environ.get(ENV_UMS_URL):
+        logger.warning(
+            "%s is not set; cannot construct IAS destination name. "
+            "Set %s or %s to configure the destination name.",
+            ENV_UMS_URL,
+            ENV_UMS_DESTINATION_NAME,
+            ENV_UMS_URL,
+        )
+        return None
+    destination_name = f"{_IAS_DESTINATION_PREFIX}{landscape}"
     logger.debug(
-        "Resolved UMS destination name from %s: %s",
+        "Resolved IAS destination name from %s: %s",
         ENV_CONHOS_LANDSCAPE,
         destination_name,
     )
@@ -428,17 +439,27 @@ def _transform_ums_response(
 class UmsTransport:
     """UMS GraphQL transport for the extensibility service.
 
-    Resolves the UMS destination via the Destination SDK, then sends
-    a GraphQL query to the UMS ``/graphql`` endpoint and transforms
-    the response into an :class:`ExtensionCapabilityImplementation`.
+    Resolves the UMS destination, then sends a GraphQL query to the UMS
+    ``/graphql`` endpoint and transforms the response into an
+    :class:`ExtensionCapabilityImplementation`.
 
-    The destination name is resolved in order:
+    **Destination name** is resolved in order:
 
     1. ``config.destination_name`` (explicit config override).
     2. ``APPFND_UMS_DESTINATION_NAME`` environment variable.
-    3. ``sap-managed-runtime-ums-{APPFND_CONHOS_LANDSCAPE}`` (constructed).
+    3. Landscape-based construction:
+
+       * ``sap-managed-runtime-ias-{APPFND_CONHOS_LANDSCAPE}`` (requires
+         ``APPFND_CONHOS_UMS_URL`` to be set; logs a warning and returns
+         ``None`` otherwise).
 
-    If none of the above are available, resolution fails with a warning.
+    **Base URL** is resolved as:
+
+    * ``APPFND_CONHOS_UMS_URL`` environment variable when set (new flow).
+    * The URL configured on the resolved destination otherwise (legacy flow).
+
+    In both cases the **mTLS certificate** is taken from the resolved
+    destination.
 
     Args:
         agent_ord_id: ORD ID of the agent.
@@ -502,15 +523,6 @@ def get_extension_capability_implementation(
             TransportError: If destination resolution, HTTP communication,
                 or response parsing fails.
         """
-        # Guard: destination name must be resolved
-        if self._destination_name is None:
-            raise TransportError(
-                "UMS destination name could not be resolved. "
-                "Set the APPFND_UMS_DESTINATION_NAME or "
-                "APPFND_CONHOS_LANDSCAPE environment variable, or provide "
-                "a destination_name in ExtensibilityConfig."
-            )
-
         # 0. Cache lookup ------------------------------------------------
         cache_key = (tenant, capability_id)
         all_edges: List[Dict[str, Any]] = []
@@ -541,10 +553,20 @@ def get_extension_capability_implementation(
                     )
 
         # 1. Resolve destination -----------------------------------------
+        if self._destination_name is None:
+            raise TransportError(
+                "UMS destination name could not be resolved. "
+                "Either set APPFND_UMS_DESTINATION_NAME directly, "
+                "or set both APPFND_CONHOS_LANDSCAPE and APPFND_CONHOS_UMS_URL "
+                "to construct the IAS destination name, "
+                "or provide a destination_name in ExtensibilityConfig."
+            )
+
         try:
             dest = self._dest_client.get_destination(
                 self._destination_name,
                 level=ConsumptionLevel.PROVIDER_SUBACCOUNT,
+                options=ConsumptionOptions(skip_token_retrieval=True) 
             )
         except Exception as exc:
             raise TransportError(
@@ -556,13 +578,28 @@ def get_extension_capability_implementation(
                 f"Destination '{self._destination_name}' not found in Destination Service."
             )
 
-        base_url = dest.url
-        if base_url is None:
-            raise TransportError(
-                f"Destination '{self._destination_name}' has no URL configured."
+        # 2. Resolve base URL --------------------------------------------
+        #    New flow: use APPFND_CONHOS_UMS_URL env var directly.
+        #    Legacy flow: use the URL from the destination itself.
+        ums_url_override = os.environ.get(ENV_UMS_URL)
+        if ums_url_override:
+            base_url = ums_url_override
+            logger.debug(
+                "Using UMS URL from %s: %s", ENV_UMS_URL, base_url
+            )
+        else:
+            base_url = dest.url
+            if base_url is None:
+                raise TransportError(
+                    f"Destination '{self._destination_name}' has no URL configured."
+                )
+            logger.debug(
+                "Using UMS URL from destination '%s': %s",
+                self._destination_name,
+                base_url,
             )
 
-        # 2. Extract client certificate ----------------------------------
+        # 3. Extract client certificate ----------------------------------
         if not dest.certificates:
             raise TransportError(
                 f"Destination '{self._destination_name}' has no "
@@ -578,7 +615,7 @@ def get_extension_capability_implementation(
                 f"Failed to decode client certificate '{cert.name}': {exc}"
             ) from exc
 
-        # 3. Build GraphQL request --------------------------------------
+        # 4. Build GraphQL request --------------------------------------
         url = f"{base_url.rstrip('/')}{_UMS_GRAPHQL_PATH}"
 
         agent_filter: dict[str, Any] = {
@@ -599,7 +636,7 @@ def get_extension_capability_implementation(
             "X-Tenant": tenant,
         }
 
-        # 4. Send paginated requests with mTLS --------------------------
+        # 5. Send paginated requests with mTLS --------------------------
         all_edges = []
         cursor: Optional[str] = None
         try:
@@ -626,7 +663,7 @@ def get_extension_capability_implementation(
                             headers=request_headers,
                         )
 
-                        # 5. Parse response ---------------------------------
+                        # 6. Parse response ---------------------------------
                         try:
                             response.raise_for_status()
                         except httpx.HTTPStatusError as exc:
@@ -674,7 +711,7 @@ def get_extension_capability_implementation(
         except Exception as exc:
             raise TransportError(f"HTTP request to UMS endpoint failed: {exc}") from exc
 
-        # 6. Populate cache ----------------------------------------------
+        # 7. Populate cache ----------------------------------------------
         now = time.monotonic()
 
         with self._cache_lock:
@@ -693,10 +730,10 @@ def get_extension_capability_implementation(
 
             self._cache[cache_key] = (now, all_edges)
 
-        # 7. Transform -----------------------------------------------------------
+        # 8. Transform -----------------------------------------------------------
         combined_data: Dict[str, Any] = {
             "EXTHUB__ExtCapImplementationInstances": {"edges": all_edges},
         }
         result = _transform_ums_response(combined_data, capability_id)
 
-        return result
+        return result

src/sap_cloud_sdk/extensibility/config.py

@@ -20,14 +20,11 @@ class ExtensibilityConfig:
 
     Attributes:
         destination_name: Optional override for the UMS destination name.
-            When ``None`` (the default), the destination name is resolved
-            automatically in order:
-            (1) ``APPFND_UMS_DESTINATION_NAME`` environment variable,
-            (2) ``sap-managed-runtime-ums-{APPFND_CONHOS_LANDSCAPE}``.
-            If neither is available, resolution fails with a warning.
-            Set this only when the destination follows a non-standard
-            naming convention that cannot be expressed via environment
-            variables.
+            When set, it is used directly, bypassing automatic resolution.
+            When ``None`` (the default), the destination name is resolved via
+            ``APPFND_UMS_DESTINATION_NAME`` or constructed as
+            ``sap-managed-runtime-ias-{APPFND_CONHOS_LANDSCAPE}`` (requires
+            ``APPFND_CONHOS_UMS_URL`` to be set).
         destination_instance: Destination service instance name. When ``"default"``,
             resolves to the default destination service instance. Specify a name
             only if your deployment binds the destination service under a
@@ -52,4 +49,4 @@ class HookConfig:
     endpoint: str
     auth_token: Optional[str] = None
     payload: Optional[dict] = None
-    headers: Optional[dict] = None
+    headers: Optional[dict] = None

tests/extensibility/unit/test_ums_transport.py

@@ -13,9 +13,9 @@
 from sap_cloud_sdk.extensibility._ums_transport import (
     UmsTransport,
     _ums_destination_name,
-    _UMS_DESTINATION_PREFIX,
     ENV_CONHOS_LANDSCAPE,
     ENV_UMS_DESTINATION_NAME,
+    ENV_UMS_URL,
     _GRAPHQL_QUERY,
 )
 from sap_cloud_sdk.extensibility.config import ExtensibilityConfig
@@ -38,12 +38,14 @@ class TestUmsDestinationName:
     def test_constructs_from_landscape_env(self, monkeypatch):
         monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
-        assert _ums_destination_name() == "sap-managed-runtime-ums-exttest-dev-eu12"
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
+        assert _ums_destination_name() == "sap-managed-runtime-ias-exttest-dev-eu12"
 
     def test_constructs_from_landscape_env_prod(self, monkeypatch):
         monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "myagent-prod-eu10")
-        assert _ums_destination_name() == "sap-managed-runtime-ums-myagent-prod-eu10"
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
+        assert _ums_destination_name() == "sap-managed-runtime-ias-myagent-prod-eu10"
 
     def test_returns_none_when_env_not_set(self, monkeypatch):
         monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
@@ -55,8 +57,11 @@ def test_returns_none_when_env_empty(self, monkeypatch):
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "")
         assert _ums_destination_name() is None
 
-    def test_prefix_constant(self):
-        assert _UMS_DESTINATION_PREFIX == "sap-managed-runtime-ums-"
+    def test_returns_none_when_ums_url_not_set(self, monkeypatch):
+        monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
+        monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
+        monkeypatch.delenv(ENV_UMS_URL, raising=False)
+        assert _ums_destination_name() is None
 
     def test_override_env_takes_precedence(self, monkeypatch):
         monkeypatch.setenv(ENV_UMS_DESTINATION_NAME, "ums-exttest-dev-eu12")
@@ -71,7 +76,8 @@ def test_override_env_without_landscape(self, monkeypatch):
     def test_empty_override_falls_through_to_landscape(self, monkeypatch):
         monkeypatch.setenv(ENV_UMS_DESTINATION_NAME, "")
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
-        assert _ums_destination_name() == "sap-managed-runtime-ums-exttest-dev-eu12"
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
+        assert _ums_destination_name() == "sap-managed-runtime-ias-exttest-dev-eu12"
 
     def test_config_override_takes_highest_priority(self, monkeypatch):
         monkeypatch.setenv(ENV_UMS_DESTINATION_NAME, "env-override")
@@ -85,9 +91,10 @@ def test_config_override_none_falls_through(self, monkeypatch):
     def test_config_override_empty_falls_through(self, monkeypatch):
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
         monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
         assert (
             _ums_destination_name(config_override="")
-            == "sap-managed-runtime-ums-exttest-dev-eu12"
+            == "sap-managed-runtime-ias-exttest-dev-eu12"
         )
 
 # ---------------------------------------------------------------------------
@@ -100,10 +107,11 @@ class TestUmsTransportInit:
     def test_valid_config(self, mock_dest_client, monkeypatch):
         monkeypatch.delenv(ENV_UMS_DESTINATION_NAME, raising=False)
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
         config = _make_config()
         transport = UmsTransport(AGENT_ORD_ID, config)
         assert transport._config is config
-        assert transport._destination_name == "sap-managed-runtime-ums-exttest-dev-eu12"
+        assert transport._destination_name == "sap-managed-runtime-ias-exttest-dev-eu12"
         mock_dest_client.assert_called_once()
         assert mock_dest_client.call_args.kwargs["instance"] == "default"
 
@@ -136,6 +144,7 @@ class TestUmsTransportGetExtCapImpl:
     @pytest.fixture(autouse=True)
     def _set_landscape_env(self, monkeypatch):
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
 
     @patch("sap_cloud_sdk.extensibility._ums_transport.create_destination_client")
     def _make_transport(self, mock_dest_client, dest=None):
@@ -196,7 +205,7 @@ def test_uses_resolved_destination_name(self):
             transport.get_extension_capability_implementation()
 
         dest_client.get_destination.assert_called_once_with(
-            "sap-managed-runtime-ums-exttest-dev-eu12", level=ANY
+            "sap-managed-runtime-ias-exttest-dev-eu12", level=ANY, options=ANY
         )
 
     def test_sends_correct_graphql_query(self):
@@ -277,9 +286,10 @@ def test_destination_resolution_failure(self):
         with pytest.raises(TransportError, match="Failed to resolve destination"):
             transport.get_extension_capability_implementation()
 
-    def test_destination_no_url(self):
+    def test_destination_no_url(self, monkeypatch):
         dest = _make_dest(url=None)
         transport, dest_client = self._make_transport(dest=dest)
+        monkeypatch.delenv(ENV_UMS_URL, raising=False)
 
         with pytest.raises(TransportError, match="has no URL configured"):
             transport.get_extension_capability_implementation()
@@ -452,6 +462,7 @@ class TestUmsTransportTenant:
     @pytest.fixture(autouse=True)
     def _set_landscape_env(self, monkeypatch):
         monkeypatch.setenv(ENV_CONHOS_LANDSCAPE, "exttest-dev-eu12")
+        monkeypatch.setenv(ENV_UMS_URL, "https://ums.example.com")
 
     @patch("sap_cloud_sdk.extensibility._ums_transport.create_destination_client")
     def _make_transport(self, mock_dest_client, dest=None):
@@ -477,9 +488,9 @@ def test_tenant_does_not_affect_destination_call(self):
 
             transport.get_extension_capability_implementation(tenant="my-subscriber")
 
-        # get_destination is called without any ConsumptionOptions
+        # get_destination is called with skip_token_retrieval option
         dest_client.get_destination.assert_called_once_with(
-            "sap-managed-runtime-ums-exttest-dev-eu12", level=ANY
+            "sap-managed-runtime-ias-exttest-dev-eu12", level=ANY, options=ANY
         )
 
     def test_tenant_included_in_agent_filter(self):
@@ -559,4 +570,4 @@ def test_ums_init_failure_degrades_to_noop(self, mock_ums_cls):
         # Should return empty results (NoOpTransport behavior)
         result = client.get_extension_capability_implementation(tenant="test-tenant")
         assert result.mcp_servers == []
-        assert result.instruction is None
+        assert result.instruction is None