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,30 @@ public class HttpHeadersUtils {
     return null;
   }
 
+  /**
+   * Retrieves the first 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 first string value of the header, or {@code null} if not found
+   */
+  public static @Nullable String getFirstHeader(Map<String, Object> headers, String name) {
+    for (Map.Entry<String, Object> entry : headers.entrySet()) {
+      if (entry.getKey().equalsIgnoreCase(name)) {
+        return extractFirstString(entry.getValue());
+      }
+    }
+    return null;
+  }
+
+  private static @Nullable String extractFirstString(Object headerValue) {
+    if (headerValue instanceof Iterable) {
+      Object firstElement = Iterables.getFirst((Iterable<?>) headerValue, null);
+      return firstElement != null ? firstElement.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

@@ -130,4 +130,29 @@ void testGetUserAgentValue() {
     headersMap = ImmutableMap.of("Custom-Header", "CustomHeader", "accept", "Accept");
     assertNull(HttpHeadersUtils.getUserAgentValue(headersMap));
   }
+
+  @Test
+  void testGetFirstHeader() {
+    Map<String, Object> headersMap =
+        ImmutableMap.<String, Object>builder()
+            .put("X-Goog-Upload-URL", "https://test.googleapis.com/upload")
+            .put("Location", ImmutableList.of("https://redirect.url", "https://secondary.url"))
+            .put("Content-Length", 1024L)
+            .put("Empty-List-Header", ImmutableList.of())
+            .put("Null-First-Header", java.util.Collections.singletonList(null))
+            .build();
+
+    assertEquals(
+        "https://test.googleapis.com/upload",
+        HttpHeadersUtils.getFirstHeader(headersMap, "X-Goog-Upload-URL"));
+    assertEquals(
+        "https://test.googleapis.com/upload",
+        HttpHeadersUtils.getFirstHeader(headersMap, "x-goog-upload-url"));
+    assertEquals(
+        "https://redirect.url", HttpHeadersUtils.getFirstHeader(headersMap, "location"));
+    assertEquals("1024", HttpHeadersUtils.getFirstHeader(headersMap, "content-length"));
+    assertNull(HttpHeadersUtils.getFirstHeader(headersMap, "empty-list-header"));
+    assertNull(HttpHeadersUtils.getFirstHeader(headersMap, "null-first-header"));
+    assertNull(HttpHeadersUtils.getFirstHeader(headersMap, "non-existent-header"));
+  }
 }