feat(gax): add getFirstHeader to HttpHeadersUtils

Author: whowes

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpHeadersUtils.java

@@ -34,6 +34,7 @@
 import com.google.api.client.util.FieldInfo;
 import com.google.api.core.InternalApi;
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
 import java.util.List;
 import java.util.Map;
 import org.jspecify.annotations.NullMarked;
@@ -52,6 +53,34 @@ public class HttpHeadersUtils {
     return null;
   }
 
+  /**
+   * Retrieves the single string value of a header by case-insensitive name from a headers map.
+   *
+   * @param headers the map of header names to header values
+   * @param name the case-insensitive header name to look up
+   * @return the single string value of the header, or {@code null} if not found
+   * @throws IllegalArgumentException if multiple values are present for the header
+   */
+  public static @Nullable String getSingleHeader(Map<String, Object> headers, String name) {
+    return headers.entrySet().stream()
+        .filter(entry -> name.equalsIgnoreCase(entry.getKey()))
+        .findFirst()
+        .map(entry -> extractSingleString(entry.getValue()))
+        .orElse(null);
+  }
+
+  private static @Nullable String extractSingleString(@Nullable Object headerValue) {
+    if (headerValue == null) {
+      return null;
+    }
+    // HttpHeaders stores known headers as Lists
+    if (headerValue instanceof Iterable) {
+      Object onlyElement = Iterables.getOnlyElement((Iterable<?>) headerValue, null);
+      return onlyElement != null ? onlyElement.toString() : null;
+    }
+    return headerValue.toString();
+  }
+
   public static HttpHeaders setHeaders(HttpHeaders headers, Map<String, String> headersMap) {
     for (Map.Entry<String, String> entry : headersMap.entrySet()) {
       setHeader(headers, entry.getKey(), entry.getValue());

sdk-platform-java/gax-java/gax-httpjson/src/test/java/com/google/api/gax/httpjson/HttpHeadersUtilsTest.java

@@ -29,12 +29,16 @@
  */
 package com.google.api.gax.httpjson;
 
+import static com.google.common.truth.Truth.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import com.google.api.client.http.HttpHeaders;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
+import java.util.Collections;
+import java.util.HashMap;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
 
@@ -130,4 +134,56 @@ void testGetUserAgentValue() {
     headersMap = ImmutableMap.of("Custom-Header", "CustomHeader", "accept", "Accept");
     assertNull(HttpHeadersUtils.getUserAgentValue(headersMap));
   }
+
+  @Test
+  void getSingleHeader_success() {
+    Map<String, Object> headers =
+        ImmutableMap.of(
+            "X-Goog-Upload-URL",
+            "https://test.googleapis.com/upload",
+            "Location",
+            ImmutableList.of("https://redirect.url"),
+            "Content-Length",
+            1024L);
+
+    // Case-insensitive & exact lookup
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "X-Goog-Upload-URL"))
+        .isEqualTo("https://test.googleapis.com/upload");
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "x-goog-upload-url"))
+        .isEqualTo("https://test.googleapis.com/upload");
+
+    // Single-element iterable
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "location"))
+        .isEqualTo("https://redirect.url");
+
+    // Non-string object conversion
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "content-length")).isEqualTo("1024");
+  }
+
+  @Test
+  void getSingleHeader_multipleElements_throwsIllegalArgumentException() {
+    Map<String, Object> headers =
+        ImmutableMap.of(
+            "Location", ImmutableList.of("https://redirect.url", "https://secondary.url"));
+
+    assertThrows(
+        IllegalArgumentException.class,
+        () -> HttpHeadersUtils.getSingleHeader(headers, "location"));
+  }
+
+  @Test
+  void getSingleHeader_missingOrEmpty_returnsNull() {
+    Map<String, Object> headers = new HashMap<>();
+    headers.put("Existing-Header", "value");
+    headers.put("Null-Value-Header", null);
+    headers.put("Empty-List-Header", Collections.emptyList());
+    headers.put("Null-First-Header", Collections.singletonList(null));
+    headers.put(null, "some-value");
+
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "non-existent-header")).isNull();
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "null-value-header")).isNull();
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "empty-list-header")).isNull();
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "null-first-header")).isNull();
+    assertThat(HttpHeadersUtils.getSingleHeader(headers, "any-header")).isNull();
+  }
 }