fix: deduplicate x-goog-api-client headers

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

@@ -20,6 +20,7 @@
 
 import enum
 import functools
+from typing import List, Tuple
 
 from google.api_core import grpc_helpers
 from google.api_core.gapic_v1 import client_info
@@ -57,6 +58,52 @@ def _apply_decorators(func, decorators):
     return func
 
 
+def _deduplicate_metadata_tokens(*headers: str | None) -> str:
+    """
+    Given one or more metadata payload strings, create a combined
+    string with deduplicated tokens, while preserving token order.
+
+    Inputs are expected to contain a set of metadata tokens separated by spaces
+    Example: `gl-python/3.14.0 grpc/1.76.0 gax/2.29.0 gapic/3.8.0 pb/6.33.4`
+
+    Args:
+      *headers: one or more metadata payload strings
+
+    Returns:
+        a single combined payload string
+    """
+    # Split all non-empty headers into individual tokens
+    token_list = " ".join(filter(None, headers)).split()
+    # Deduplicate while preserving order
+    return " ".join(dict.fromkeys(token_list))
+
+
+def _extract_metrics_header(metadata) -> Tuple[str, List[Tuple[str, str]]]:
+    """Extract x-google-api-client header from metadata list.
+
+    Args:
+        metadata (Sequence[Tuple[str, str]]): The metadata to extract from.
+
+    Returns:
+        A tuple containing:
+            - a string representing the header value.
+            - A sequence of remaining metadata tuples.
+    """
+    if not metadata:
+        return "", []
+
+    key_to_find = client_info.METRICS_METADATA_KEY
+
+    metric_str = _deduplicate_metadata_tokens(
+        " ".join([v for k, v in metadata if k == key_to_find])
+    )
+    if not metric_str:
+        return "", list(metadata)
+
+    arbitrary_metadata = [item for item in metadata if item[0] != key_to_find]
+    return metric_str, arbitrary_metadata
+
+
 class _GapicCallable(object):
     """Callable that applies retry, timeout, and metadata logic.
 
@@ -90,7 +137,16 @@ def __init__(
         self._retry = retry
         self._timeout = timeout
         self._compression = compression
-        self._metadata = metadata
+        # Pre-extract the x-goog-api-client header from the initialized metadata.
+        self._x_goog_api_client, remaining = _extract_metrics_header(metadata)
+        self._static_metadata = tuple(remaining)
+        if self._x_goog_api_client:
+            self._default_metadata = (
+                (client_info.METRICS_METADATA_KEY, self._x_goog_api_client),
+                *self._static_metadata,
+            )
+        else:
+            self._default_metadata = self._static_metadata
 
     def __call__(
         self, *args, timeout=DEFAULT, retry=DEFAULT, compression=DEFAULT, **kwargs
@@ -112,16 +168,21 @@ def __call__(
         # Apply all applicable decorators.
         wrapped_func = _apply_decorators(self._target, [retry, timeout])
 
-        # Add the user agent metadata to the call.
-        if self._metadata is not None:
-            metadata = kwargs.get("metadata", [])
-            # Due to the nature of invocation, None should be treated the same
-            # as not specified.
-            if metadata is None:
-                metadata = []
-            metadata = list(metadata)
-            metadata.extend(self._metadata)
-            kwargs["metadata"] = metadata
+        if user_metadata := kwargs.get("metadata"):
+            # Add the user agent metadata to the call.
+            final_metadata = list(self._static_metadata)
+            user_x_goog, remaining = _extract_metrics_header(user_metadata)
+
+            merged_header = _deduplicate_metadata_tokens(
+                self._x_goog_api_client, user_x_goog
+            )
+            if merged_header:
+                final_metadata.append((client_info.METRICS_METADATA_KEY, merged_header))
+            final_metadata.extend(remaining)
+            kwargs["metadata"] = final_metadata
+        elif self._default_metadata:
+            kwargs["metadata"] = self._default_metadata
+
         if self._compression is not None:
             kwargs["compression"] = compression
 

packages/google-api-core/google/api_core/grpc_helpers.py

@@ -254,11 +254,20 @@ def _create_composite_credentials(
     request = google.auth.transport.requests.Request()
 
     # Create the metadata plugin for inserting the authorization header.
-    metadata_plugin = google.auth.transport.grpc.AuthMetadataPlugin(
-        credentials,
-        request,
-        default_host=default_host,
-    )
+    try:
+        metadata_plugin = google.auth.transport.grpc.AuthMetadataPlugin(
+            credentials,
+            request,
+            default_host=default_host,
+            suppress_metrics_header=True,
+        )
+    except TypeError:
+        # Support older versions of google-auth that do not accept suppress_metrics_header
+        metadata_plugin = google.auth.transport.grpc.AuthMetadataPlugin(
+            credentials,
+            request,
+            default_host=default_host,
+        )
 
     # Create a set of grpc.CallCredentials using the metadata plugin.
     google_auth_credentials = grpc.metadata_call_credentials(metadata_plugin)

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

@@ -119,6 +119,83 @@ def test_invoke_wrapped_method_with_metadata_as_none():
     assert len(metadata) == 1
 
 
+def test_invoke_wrapped_method_no_client_info_with_custom_metadata():
+    method = mock.Mock(spec=["__call__"])
+
+    wrapped_method = google.api_core.gapic_v1.method.wrap_method(
+        method, client_info=None
+    )
+
+    wrapped_method(mock.sentinel.request, metadata=[("custom-header", "value")])
+
+    method.assert_called_once_with(
+        mock.sentinel.request, metadata=[("custom-header", "value")]
+    )
+
+
+def test_extract_metrics_header_duplicate_tokens():
+    metadata = [
+        ("x-goog-api-client", "token1 token2"),
+        ("x-goog-api-client", "token2 token3 token1"),
+        ("other-header", "value"),
+        ("x-goog-api-client", "token4 token2"),
+    ]
+
+    metric_str, arbitrary_metadata = (
+        google.api_core.gapic_v1.method._extract_metrics_header(metadata)
+    )
+
+    # Should maintain order of first appearance and eliminate duplicates
+    assert metric_str == "token1 token2 token3 token4"
+    assert arbitrary_metadata == [("other-header", "value")]
+
+
+def test_invoke_wrapped_method_with_duplicate_x_goog_api_client_metadata():
+    method = mock.Mock(spec=["__call__"])
+
+    # Create a custom ClientInfo with defined properties so we know exactly what is returned
+    client_info = google.api_core.gapic_v1.client_info.ClientInfo(
+        user_agent="custom-user-agent/1.0",
+        python_version="3.14.0",
+        grpc_version="1.76.0",
+        api_core_version="2.29.0",
+    )
+
+    wrapped_method = google.api_core.gapic_v1.method.wrap_method(
+        method, client_info=client_info
+    )
+
+    # Invoke the wrapped method with an explicit user-provided custom header that contains duplicates
+    # both within its own items and overlapping with the default client_info
+    wrapped_method(
+        mock.sentinel.request,
+        metadata=[
+            ("x-goog-api-client", "override-client/2.0"),
+            (
+                "x-goog-api-client",
+                "override-client/2.0 grpc/1.76.0 custom-user-agent/1.0",
+            ),
+            ("other-header", "value"),
+        ],
+    )
+
+    method.assert_called_once_with(mock.sentinel.request, metadata=mock.ANY)
+    metadata = method.call_args[1]["metadata"]
+
+    # There should only be one "x-goog-api-client" header, containing both values joined by space,
+    # plus the other-header.
+    assert len(metadata) == 2
+    metadata_dict = dict(metadata)
+    assert "other-header" in metadata_dict
+    assert metadata_dict["other-header"] == "value"
+    assert "x-goog-api-client" in metadata_dict
+    # Verify both the user-provided override value and the library system telemetry are merged explicitly
+    assert (
+        metadata_dict["x-goog-api-client"]
+        == "custom-user-agent/1.0 gl-python/3.14.0 grpc/1.76.0 gax/2.29.0 override-client/2.0"
+    )
+
+
 @mock.patch("time.sleep")
 def test_wrap_method_with_default_retry_and_timeout_and_compression(unused_sleep):
     method = mock.Mock(
@@ -248,3 +325,24 @@ def test_wrap_method_with_call_not_supported():
     with pytest.raises(ValueError) as exc_info:
         google.api_core.gapic_v1.method.wrap_method(method, with_call=True)
     assert "with_call=True is only supported for unary calls" in str(exc_info.value)
+
+
+@pytest.mark.parametrize(
+    "headers,expected",
+    [
+        ((), ""),
+        (("",), ""),
+        ((None,), ""),
+        (("", None, ""), ""),
+        (("token1",), "token1"),
+        (("token1 token1",), "token1"),
+        (("token1", "token1"), "token1"),
+        (("token1 token2 token1",), "token1 token2"),
+        (("token1", "token2", "token1"), "token1 token2"),
+        (("token1 token2", "token2 token3"), "token1 token2 token3"),
+        (("token1", None, "token2", "", "token1"), "token1 token2"),
+    ],
+)
+def test__deduplicate_metadata_tokens(headers, expected):
+    dedup = google.api_core.gapic_v1.method._deduplicate_metadata_tokens
+    assert dedup(*headers) == expected

packages/google-auth/google/auth/transport/grpc.py

@@ -48,16 +48,21 @@ class AuthMetadataPlugin(grpc.AuthMetadataPlugin):
         default_host (Optional[str]): A host like "pubsub.googleapis.com".
             This is used when a self-signed JWT is created from service
             account credentials.
+        suppress_metrics_header (bool): When enabled, ``x-goog-api-client``
+            will be stripped from authorization headers.
     """
 
-    def __init__(self, credentials, request, default_host=None):
+    def __init__(
+        self, credentials, request, default_host=None, *, suppress_metrics_header=False
+    ):
         # pylint: disable=no-value-for-parameter
         # pylint doesn't realize that the super method takes no arguments
         # because this class is the same name as the superclass.
         super(AuthMetadataPlugin, self).__init__()
         self._credentials = credentials
         self._request = request
         self._default_host = default_host
+        self._suppress_metrics_header = suppress_metrics_header
 
     def _get_authorization_headers(self, context):
         """Gets the authorization headers for a request.
@@ -81,6 +86,9 @@ def _get_authorization_headers(self, context):
             self._request, context.method_name, context.service_url, headers
         )
 
+        if self._suppress_metrics_header and "x-goog-api-client" in headers:
+            del headers["x-goog-api-client"]
+
         return list(headers.items())
 
     def __call__(self, context, callback):

packages/google-auth/tests/transport/test_grpc.py

@@ -132,6 +132,35 @@ def test__get_authorization_headers_with_service_account_and_default_host(self):
             "https://{}/".format(default_host)
         )
 
+    def test_suppress_metrics_header(self):
+        credentials = mock.create_autospec(service_account.Credentials)
+
+        # Mock credentials before_request that adds metric and authorization
+        def mock_before_request(request, method, url, headers):
+            headers["x-goog-api-client"] = "foo"
+            headers["authorization"] = "Bearer token"
+
+        credentials.before_request.side_effect = mock_before_request
+        request = mock.create_autospec(transport.Request)
+
+        # By default, suppress_metrics_header=False
+        plugin = google.auth.transport.grpc.AuthMetadataPlugin(credentials, request)
+        context = mock.create_autospec(grpc.AuthMetadataContext, instance=True)
+        context.method_name = "methodName"
+        context.service_url = "https://pubsub.googleapis.com/methodName"
+
+        headers = dict(plugin._get_authorization_headers(context))
+        assert "x-goog-api-client" in headers
+        assert headers["x-goog-api-client"] == "foo"
+
+        # With suppress_metrics_header=True
+        plugin_suppressed = google.auth.transport.grpc.AuthMetadataPlugin(
+            credentials, request, suppress_metrics_header=True
+        )
+        headers_suppressed = dict(plugin_suppressed._get_authorization_headers(context))
+        assert "x-goog-api-client" not in headers_suppressed
+        assert headers_suppressed["authorization"] == "Bearer token"
+
 
 @mock.patch(
     "google.auth.transport._mtls_helper.get_client_ssl_credentials", autospec=True