feat(api-core): move mtls and client configuration logic to gapic_v1 public helpers

Introduces client_cert and config_helpers modules containing use_client_cert_effective, get_client_cert_source, and read_environment_variables helpers. Exposes these modules as public in gapic_v1.

Author: hebaalazzeh

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

@@ -25,9 +25,11 @@
 # Older Python versions safely ignore this variable.
 __lazy_modules__: Set[str] = {
     "google.api_core.gapic_v1.client_info",
+    "google.api_core.gapic_v1.client_cert",
+    "google.api_core.gapic_v1.config_helpers",
     "google.api_core.gapic_v1.routing_header",
 }
-__all__ = ["client_info", "routing_header"]
+__all__ = ["client_info", "client_cert", "config_helpers", "routing_header"]
 
 if _has_grpc:
     __lazy_modules__.update(
@@ -41,6 +43,8 @@
 
 from google.api_core.gapic_v1 import (  # noqa: E402
     client_info,
+    client_cert,
+    config_helpers,
     routing_header,
 )
 

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

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Helpers for client certificate handling and mTLS authentication."""
+
+import os
+from typing import Callable, Optional, Tuple
+
+from google.auth.transport import mtls  # type: ignore
+
+
+def use_client_cert_effective() -> bool:
+    """Returns whether client certificate should be used for mTLS if the
+    google-auth version supports should_use_client_cert automatic mTLS
+    enablement.
+
+    Alternatively, read from the GOOGLE_API_USE_CLIENT_CERTIFICATE env var.
+
+    Returns:
+        bool: whether client certificate should be used for mTLS
+    Raises:
+        ValueError: (If using a version of google-auth without
+        should_use_client_cert and GOOGLE_API_USE_CLIENT_CERTIFICATE is
+        set to an unexpected value.)
+    """
+    # check if google-auth version supports should_use_client_cert for
+    # automatic mTLS enablement
+    if hasattr(mtls, "should_use_client_cert"):  # pragma: NO COVER
+        return mtls.should_use_client_cert()
+    else:  # pragma: NO COVER
+        # if unsupported, fallback to reading from env var
+        use_client_cert_str = os.getenv(
+            "GOOGLE_API_USE_CLIENT_CERTIFICATE", "false"
+        ).lower()
+        if use_client_cert_str not in ("true", "false"):
+            raise ValueError(
+                "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` "
+                "must be either `true` or `false`"
+            )
+        return use_client_cert_str == "true"
+
+
+def get_client_cert_source(
+    provided_cert_source: Optional[Callable[[], Tuple[bytes, bytes]]],
+    use_cert_flag: bool,
+) -> Optional[Callable[[], Tuple[bytes, bytes]]]:
+    """Return the client cert source to be used by the client.
+
+    Args:
+        provided_cert_source (Callable[[], Tuple[bytes, bytes]]): The client certificate source provided.
+        use_cert_flag (bool): A flag indicating whether to use the
+            client certificate.
+
+    Returns:
+        Callable[[], Tuple[bytes, bytes]] or None: The client cert source to be used by the client.
+    """
+    client_cert_source = None
+    if use_cert_flag:
+        if provided_cert_source:
+            client_cert_source = provided_cert_source
+        elif (
+            hasattr(mtls, "has_default_client_cert_source")
+            and mtls.has_default_client_cert_source()
+        ):
+            client_cert_source = mtls.default_client_cert_source()
+    return client_cert_source

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

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Helpers for parsing environment variables."""
+
+import os
+from typing import Optional, Tuple
+
+from google.auth.exceptions import MutualTLSChannelError  # type: ignore
+
+from google.api_core.gapic_v1.client_cert import use_client_cert_effective
+
+
+def read_environment_variables() -> Tuple[bool, str, Optional[str]]:
+    """Returns the environment variables used by the client.
+
+    Returns:
+        Tuple[bool, str, Optional[str]]: returns the
+        GOOGLE_API_USE_CLIENT_CERTIFICATE, GOOGLE_API_USE_MTLS_ENDPOINT,
+        and GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variables.
+
+    Raises:
+        ValueError: If GOOGLE_API_USE_CLIENT_CERTIFICATE is not
+            any of ["true", "false"].
+        google.auth.exceptions.MutualTLSChannelError: If
+            GOOGLE_API_USE_MTLS_ENDPOINT is not any of
+            ["auto", "never", "always"].
+    """
+    use_client_cert = use_client_cert_effective()
+    use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto").lower()
+    universe_domain_env = os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
+    if use_mtls_endpoint not in ("auto", "never", "always"):
+        raise MutualTLSChannelError(
+            "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` "
+            "must be `never`, `auto` or `always`"
+        )
+    return use_client_cert, use_mtls_endpoint, universe_domain_env

packages/google-api-core/noxfile.py

@@ -350,7 +350,7 @@ def prerelease_deps(session):
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def core_deps_from_source(session):
     """Run the test suite installing dependencies from source."""
-    default(session, prerelease=True)
+    default(session, install_deps_from_source=True)
 
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)

packages/google-api-core/tests/conftest.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from unittest import mock
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def mock_mtls_env():
+    """Autouse session-scoped fixture to isolate unit tests from workstation mTLS environments."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false",
+            "CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE": "false",
+        },
+    ):
+        yield

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

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from unittest import mock
+
+import pytest
+
+
+from google.api_core.gapic_v1.client_cert import (
+    get_client_cert_source,
+    use_client_cert_effective,
+)
+
+
+@mock.patch("google.auth.transport.mtls.should_use_client_cert", create=True)
+def test_use_client_cert_effective_with_google_auth(mock_method):
+    # Test when google-auth supports the method
+    mock_method.return_value = True
+    assert use_client_cert_effective() is True
+
+    mock_method.return_value = False
+    assert use_client_cert_effective() is False
+
+
+@mock.patch.dict(os.environ, {}, clear=True)
+def test_use_client_cert_effective_fallback():
+    # We must patch hasattr to simulate google-auth lacking the method
+    with mock.patch("google.api_core.gapic_v1.client_cert.hasattr", return_value=False):
+        # Default is false
+        assert use_client_cert_effective() is False
+
+        env_true = {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"}
+        with mock.patch.dict(os.environ, env_true):
+            assert use_client_cert_effective() is True
+
+        with mock.patch.dict(
+            os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "false"}
+        ):
+            assert use_client_cert_effective() is False
+
+        with mock.patch.dict(
+            os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "invalid"}
+        ):
+            match_str = "must be either `true` or `false`"
+            with pytest.raises(ValueError, match=match_str):
+                use_client_cert_effective()
+
+
+@mock.patch(
+    "google.auth.transport.mtls.has_default_client_cert_source", create=True
+)  # noqa: E501
+@mock.patch(
+    "google.auth.transport.mtls.default_client_cert_source", create=True
+)  # noqa: E501
+def test_get_client_cert_source(mock_default, mock_has_default):
+    mock_default.return_value = b"default_cert"
+    mock_has_default.return_value = True
+
+    # When use_cert_flag is False, return None
+    assert get_client_cert_source(b"provided", False) is None
+
+    # When provided_cert_source is given, return provided
+    assert get_client_cert_source(b"provided", True) == b"provided"  # noqa: E501
+
+    # When no provided cert but default is available
+    assert get_client_cert_source(None, True) == b"default_cert"

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

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from unittest import mock
+
+import pytest
+
+from google.auth.exceptions import MutualTLSChannelError
+
+from google.api_core.gapic_v1.config_helpers import read_environment_variables
+
+
+@mock.patch(
+    "google.api_core.gapic_v1.config_helpers.use_client_cert_effective"
+)  # noqa: E501
+@mock.patch.dict(os.environ, clear=True)
+def test_read_environment_variables(mock_effective):
+    mock_effective.return_value = True
+    os.environ["GOOGLE_API_USE_MTLS_ENDPOINT"] = "always"
+    os.environ["GOOGLE_CLOUD_UNIVERSE_DOMAIN"] = "custom.com"
+
+    cert, mtls, domain = read_environment_variables()
+    assert cert is True
+    assert mtls == "always"
+    assert domain == "custom.com"
+
+
+@mock.patch.dict(os.environ, clear=True)
+def test_read_environment_variables_invalid_mtls():
+    os.environ["GOOGLE_API_USE_MTLS_ENDPOINT"] = "invalid"
+    with pytest.raises(
+        MutualTLSChannelError, match="must be `never`, `auto` or `always`"
+    ):
+        read_environment_variables()

packages/google-api-core/tests/unit/test_bidi.py

@@ -31,8 +31,7 @@
 except ImportError:  # pragma: NO COVER
     pytest.skip("No GRPC", allow_module_level=True)
 
-from google.api_core import bidi
-from google.api_core import exceptions
+from google.api_core import bidi, exceptions
 
 
 class Test_RequestQueueGenerator(object):
@@ -195,7 +194,7 @@ def test_delays_entry_attempts_above_threshold(self):
         # (NOTE: not using assert all(...), b/c the coverage check would complain)
         for i, entry in enumerate(entries):
             if i != 3:
-                assert entry["reported_wait"] == 0.0
+                assert entry["reported_wait"] < 0.01
 
         # The delayed entry is expected to have been delayed for a significant
         # chunk of the full second, and the actual and reported delay times