docs: clarify get_default_mtls_endpoint pass-through, fix: support port suffixes in mTLS conversion

Author: hebaalazzeh

packages/google-api-core/google/api_core/gapic_v1/client_utils.py

@@ -26,6 +26,8 @@ def get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
 
     Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
     "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+    Other URLs (including those that do not match these domain suffixes or
+    already contain '.mtls.') are passed through as-is.
 
     Args:
         api_endpoint (Optional[str]): the api endpoint to convert.
@@ -36,14 +38,19 @@ def get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
     if not api_endpoint or ".mtls." in api_endpoint.lower():
         return api_endpoint
 
-    lowered_endpoint = api_endpoint.lower()
-    if lowered_endpoint.endswith(".sandbox.googleapis.com"):
+    # Handle optional port suffix (e.g. ":443")
+    parts = api_endpoint.split(":")
+    host = parts[0]
+    port = ":" + parts[1] if len(parts) > 1 else ""
+
+    lowered_host = host.lower()
+    if lowered_host.endswith(".sandbox.googleapis.com"):
         # len(".sandbox.googleapis.com") == 23
-        return api_endpoint[:-23] + ".mtls.sandbox.googleapis.com"
+        return host[:-23] + ".mtls.sandbox.googleapis.com" + port
 
-    if lowered_endpoint.endswith(".googleapis.com"):
+    if lowered_host.endswith(".googleapis.com"):
         # len(".googleapis.com") == 15
-        return api_endpoint[:-15] + ".mtls.googleapis.com"
+        return host[:-15] + ".mtls.googleapis.com" + port
 
     return api_endpoint
 

packages/google-api-core/tests/unit/gapic/test_client_utils.py

@@ -45,12 +45,32 @@ def test_get_default_mtls_endpoint():
         == "foo.mtls.sandbox.googleapis.com"
     )
 
+    # Test valid API endpoints with ports
+    assert (
+        get_default_mtls_endpoint("foo.googleapis.com:443")
+        == "foo.mtls.googleapis.com:443"
+    )
+    assert (
+        get_default_mtls_endpoint("foo.sandbox.googleapis.com:443")
+        == "foo.mtls.sandbox.googleapis.com:443"
+    )
+    # Test case-insensitivity with ports
+    assert (
+        get_default_mtls_endpoint("foo.GoogleAPIs.com:443")
+        == "foo.mtls.googleapis.com:443"
+    )
+    assert (
+        get_default_mtls_endpoint("foo.Sandbox.GoogleAPIs.com:443")
+        == "foo.mtls.sandbox.googleapis.com:443"
+    )
+
     # Test endpoints that shouldn't be converted
     assert (
         get_default_mtls_endpoint("foo.mtls.googleapis.com")
         == "foo.mtls.googleapis.com"
     )
     assert get_default_mtls_endpoint("foo.com") == "foo.com"
+    assert get_default_mtls_endpoint("foo.com:8080") == "foo.com:8080"
 
     # Test empty/None endpoints
     assert get_default_mtls_endpoint("") == ""