feat: gapic centralization into api core

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

@@ -12,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from google.api_core.gapic_v1 import client_info
-from google.api_core.gapic_v1 import config
-from google.api_core.gapic_v1 import config_async
-from google.api_core.gapic_v1 import method
-from google.api_core.gapic_v1 import method_async
-from google.api_core.gapic_v1 import routing_header
+from google.api_core.gapic_v1 import (
+    client_info,
+    config,
+    config_async,
+    method,
+    method_async,
+    routing_header,
+)
 
 __all__ = [
     "client_info",

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

@@ -0,0 +1,78 @@
+# -*- 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 Any, Optional
+
+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[Any], use_cert_flag: bool
+) -> Optional[Any]:
+    """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,49 @@
+# -*- 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.api_core.gapic_v1._client_cert import use_client_cert_effective
+from google.auth.exceptions import MutualTLSChannelError  # type: ignore
+
+
+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/google/api_core/gapic_v1/_method_helpers.py

@@ -0,0 +1,51 @@
+# -*- 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 method requests."""
+
+import uuid
+from typing import Any
+
+
+def setup_request_id(request: Any, field_name: str, is_proto3_optional: bool) -> None:
+    """Populate a UUID4 field in the request if it is not already set.
+
+    Args:
+        request (Union[google.protobuf.message.Message, dict]): The
+            request object.
+        field_name (str): The name of the field to populate.
+        is_proto3_optional (bool): Whether the field is proto3 optional.
+    """
+    if isinstance(request, dict):
+        if is_proto3_optional:
+            if field_name not in request:
+                request[field_name] = str(uuid.uuid4())
+        elif not request.get(field_name):
+            request[field_name] = str(uuid.uuid4())
+        return
+
+    if is_proto3_optional:
+        try:
+            # Pure protobuf messages
+            if not request.HasField(field_name):
+                setattr(request, field_name, str(uuid.uuid4()))
+        except (AttributeError, ValueError):
+            # Proto-plus messages or other objects
+            if field_name not in request:
+                setattr(request, field_name, str(uuid.uuid4()))
+    else:
+        if not getattr(request, field_name):
+            setattr(request, field_name, str(uuid.uuid4()))

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

@@ -0,0 +1,98 @@
+# -*- 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 routing and endpoint resolution."""
+
+import re
+from typing import Any, Optional
+
+from google.auth.exceptions import MutualTLSChannelError  # type: ignore
+
+_MTLS_ENDPOINT_RE = re.compile(
+    r"(?P<name>[^.]+)(?P<mtls>\.mtls)?(?P<sandbox>\.sandbox)?"
+    r"(?P<googledomain>\.googleapis\.com)?"
+)
+
+
+def get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
+    """Converts api endpoint to mTLS endpoint.
+
+    Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+    "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+    Args:
+        api_endpoint (Optional[str]): the api endpoint to convert.
+    Returns:
+        Optional[str]: converted mTLS api endpoint.
+    """
+    if not api_endpoint:
+        return api_endpoint
+
+    m = _MTLS_ENDPOINT_RE.match(api_endpoint)
+    if m is None:
+        # Could not parse api_endpoint; return as-is.
+        return api_endpoint
+
+    name, mtls_group, sandbox, googledomain = m.groups()
+    if mtls_group or not googledomain:
+        return api_endpoint
+
+    if sandbox:
+        return api_endpoint.replace(
+            "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+        )
+
+    return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+
+def get_api_endpoint(
+    api_override: Optional[str],
+    client_cert_source: Optional[Any],
+    universe_domain: str,
+    use_mtls_endpoint: str,
+    default_universe: str,
+    default_mtls_endpoint: Optional[str],
+    default_endpoint_template: str,
+) -> Optional[str]:
+    """Return the API endpoint used by the client."""
+    if api_override is not None:
+        return api_override
+    elif use_mtls_endpoint == "always" or (
+        use_mtls_endpoint == "auto" and client_cert_source
+    ):
+        if universe_domain != default_universe:
+            raise MutualTLSChannelError(
+                f"mTLS is not supported in any universe other than "
+                f"{default_universe}."
+            )
+        return default_mtls_endpoint
+    else:
+        return default_endpoint_template.format(UNIVERSE_DOMAIN=universe_domain)
+
+
+def get_universe_domain(
+    client_universe_domain: Optional[str],
+    universe_domain_env: Optional[str],
+    default_universe: str,
+) -> str:
+    """Return the universe domain used by the client."""
+    universe_domain = default_universe
+    if client_universe_domain is not None:
+        universe_domain = client_universe_domain
+    elif universe_domain_env is not None:
+        universe_domain = universe_domain_env
+    if len(universe_domain.strip()) == 0:
+        raise ValueError("Universe Domain cannot be an empty string.")
+    return universe_domain

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

@@ -0,0 +1,85 @@
+# -*- 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
+
+try:
+    import grpc  # noqa: F401
+except ImportError:
+    pytest.skip("No GRPC", allow_module_level=True)
+
+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"