Refactor HTTP headers handling (#931)

* Add `CaseInsensitiveMap` class

* Add `HttpHeaders` class

* Use `HttpHeaders` in `StripeRequest`

* Use `HttpHeaders` in `StripeResponse`

* Address review comments

Author: ob-stripe

src/main/java/com/stripe/net/HttpClient.java

@@ -8,6 +8,7 @@
 import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ThreadLocalRandom;
 
 /** Base abstract class for HTTP clients used to send requests to Stripe's API. */
@@ -57,7 +58,11 @@ public HttpClient(int maxNetworkRetries) {
    * @throws StripeException If the request fails for any reason
    */
   public StripeResponse requestWithTelemetry(StripeRequest request) throws StripeException {
-    requestTelemetry.maybeAddTelemetryHeader(request.headers());
+    Optional<String> telemetryHeaderValue = requestTelemetry.getHeaderValue(request.headers());
+    if (telemetryHeaderValue.isPresent()) {
+      request =
+          request.withAdditionalHeader(RequestTelemetry.HEADER_NAME, telemetryHeaderValue.get());
+    }
 
     Stopwatch stopwatch = Stopwatch.startNew();
 
@@ -189,7 +194,7 @@ private boolean shouldRetry(int numRetries, StripeException exception, StripeRes
     // The API may ask us not to retry (eg; if doing so would be a no-op)
     // or advise us to retry (eg; in cases of lock timeouts); we defer to that.
     if ((response != null) && (response.headers() != null)) {
-      String value = response.headers().get("Stripe-Should-Retry");
+      String value = response.headers().firstValue("Stripe-Should-Retry").orElse(null);
 
       if ("true".equals(value)) {
         return true;

src/main/java/com/stripe/net/HttpHeaders.java

@@ -0,0 +1,144 @@
+package com.stripe.net;
+
+import static java.util.Objects.requireNonNull;
+
+import com.stripe.util.CaseInsensitiveMap;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import lombok.EqualsAndHashCode;
+
+/**
+ * A read-only view of a set of HTTP headers.
+ *
+ * <p>This class mimics the {@code java.net.http.HttpHeaders} added in Java 11.
+ */
+@EqualsAndHashCode
+public class HttpHeaders {
+  private CaseInsensitiveMap<List<String>> headerMap;
+
+  private HttpHeaders(CaseInsensitiveMap<List<String>> headerMap) {
+    this.headerMap = headerMap;
+  }
+
+  /**
+   * Returns an {@link HttpHeaders} instance initialized from the given map.
+   *
+   * @param headerMap the map containing the header names and values
+   * @return an {@link HttpHeaders} instance containing the given headers
+   * @throws NullPointerException if {@code headerMap} is {@code null}
+   */
+  public static HttpHeaders of(Map<String, List<String>> headerMap) {
+    requireNonNull(headerMap);
+    return new HttpHeaders(CaseInsensitiveMap.of(headerMap));
+  }
+
+  /**
+   * Returns a new {@link HttpHeaders} instance containing the headers of the current instance plus
+   * the provided header.
+   *
+   * @param name the name of the header to add
+   * @param value the value of the header to add
+   * @return the new {@link HttpHeaders} instance
+   * @throws NullPointerException if {@code name} or {@code value} is {@code null}
+   */
+  public HttpHeaders withAdditionalHeader(String name, String value) {
+    requireNonNull(name);
+    requireNonNull(value);
+    return this.withAdditionalHeader(name, Arrays.asList(value));
+  }
+
+  /**
+   * Returns a new {@link HttpHeaders} instance containing the headers of the current instance plus
+   * the provided header.
+   *
+   * @param name the name of the header to add
+   * @param values the values of the header to add
+   * @return the new {@link HttpHeaders} instance
+   * @throws NullPointerException if {@code name} or {@code values} is {@code null}
+   */
+  public HttpHeaders withAdditionalHeader(String name, List<String> values) {
+    requireNonNull(name);
+    requireNonNull(values);
+    Map<String, List<String>> headerMap = new HashMap<>();
+    headerMap.put(name, values);
+    return this.withAdditionalHeaders(headerMap);
+  }
+
+  /**
+   * Returns a new {@link HttpHeaders} instance containing the headers of the current instance plus
+   * the provided headers.
+   *
+   * @param headerMap the map containing the headers to add
+   * @return the new {@link HttpHeaders} instance
+   * @throws NullPointerException if {@code headerMap} is {@code null}
+   */
+  public HttpHeaders withAdditionalHeaders(Map<String, List<String>> headerMap) {
+    requireNonNull(headerMap);
+    Map<String, List<String>> newHeaderMap = new HashMap<>(this.map());
+    newHeaderMap.putAll(headerMap);
+    return HttpHeaders.of(newHeaderMap);
+  }
+
+  /**
+   * Returns an unmodifiable List of all of the header string values of the given named header.
+   * Always returns a List, which may be empty if the header is not present.
+   *
+   * @param name the header name
+   * @return a List of headers string values
+   */
+  public List<String> allValues(String name) {
+    if (this.headerMap.containsKey(name)) {
+      List<String> values = this.headerMap.get(name);
+      if ((values != null) && (values.size() > 0)) {
+        return Collections.unmodifiableList(values);
+      }
+    }
+    return Collections.emptyList();
+  }
+
+  /**
+   * Returns an {@link Optional} containing the first header string value of the given named (and
+   * possibly multi-valued) header. If the header is not present, then the returned {@code Optional}
+   * is empty.
+   *
+   * @param name the header name
+   * @return an {@code Optional<String>} containing the first named header string value, if present
+   */
+  public Optional<String> firstValue(String name) {
+    if (this.headerMap.containsKey(name)) {
+      List<String> values = this.headerMap.get(name);
+      if ((values != null) && (values.size() > 0)) {
+        return Optional.of(values.get(0));
+      }
+    }
+    return Optional.empty();
+  }
+
+  /**
+   * Returns an unmodifiable Map view of this HttpHeaders.
+   *
+   * @return the Map
+   */
+  public Map<String, List<String>> map() {
+    return Collections.unmodifiableMap(this.headerMap);
+  }
+
+  /**
+   * Returns this {@link HttpHeaders} as a string.
+   *
+   * @return a string describing the HTTP headers
+   */
+  @Override
+  public String toString() {
+    StringBuilder sb = new StringBuilder();
+    sb.append(super.toString());
+    sb.append(" { ");
+    sb.append(map());
+    sb.append(" }");
+    return sb.toString();
+  }
+}

src/main/java/com/stripe/net/HttpURLConnectionClient.java

@@ -8,6 +8,7 @@
 import java.net.Authenticator;
 import java.net.HttpURLConnection;
 import java.net.PasswordAuthentication;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -78,18 +79,14 @@ public StripeResponse request(StripeRequest request) throws ApiConnectionExcepti
     }
   }
 
-  static Map<String, String> getHeaders(StripeRequest request) {
-    Map<String, String> headers = new HashMap<>();
+  static HttpHeaders getHeaders(StripeRequest request) {
+    Map<String, List<String>> userAgentHeadersMap = new HashMap<>();
 
-    headers.putAll(request.headers());
+    userAgentHeadersMap.put("User-Agent", Arrays.asList(buildUserAgentString()));
+    userAgentHeadersMap.put(
+        "X-Stripe-Client-User-Agent", Arrays.asList(buildXStripeClientUserAgentString()));
 
-    headers.put("Accept-Charset", ApiResource.CHARSET);
-    headers.put("Accept", "application/json");
-
-    headers.put("User-Agent", buildUserAgentString());
-    headers.put("X-Stripe-Client-User-Agent", buildXStripeClientUserAgentString());
-
-    return headers;
+    return request.headers().withAdditionalHeaders(userAgentHeadersMap);
   }
 
   private static HttpURLConnection createStripeConnection(StripeRequest request)
@@ -112,8 +109,8 @@ protected PasswordAuthentication getPasswordAuthentication() {
     conn.setConnectTimeout(request.options().getConnectTimeout());
     conn.setReadTimeout(request.options().getReadTimeout());
     conn.setUseCaches(false);
-    for (Map.Entry<String, String> header : getHeaders(request).entrySet()) {
-      conn.setRequestProperty(header.getKey(), header.getValue());
+    for (Map.Entry<String, List<String>> entry : getHeaders(request).map().entrySet()) {
+      conn.setRequestProperty(entry.getKey(), String.join(",", entry.getValue()));
     }
 
     conn.setRequestMethod(request.method().name());

src/main/java/com/stripe/net/RequestTelemetry.java

@@ -4,12 +4,15 @@
 import com.google.gson.annotations.SerializedName;
 import com.stripe.Stripe;
 import java.time.Duration;
-import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import lombok.Data;
 
 /** Helper class used by {@link LiveStripeResponseGetter} to manage request telemetry. */
 class RequestTelemetry {
+  /** The name of the header used to send request telemetry in requests. */
+  public static final String HEADER_NAME = "X-Stripe-Client-Telemetry";
+
   private static final int MAX_REQUEST_METRICS_QUEUE_SIZE = 100;
 
   private static final Gson gson = new Gson();
@@ -18,27 +21,28 @@ class RequestTelemetry {
       new ConcurrentLinkedQueue<RequestMetrics>();
 
   /**
-   * If telemetry is enabled and there is at least one metrics item in the queue, then add a {@code
-   * X-Stripe-Client-Telemetry} header with the item; otherwise, do nothing.
+   * Returns an {@link Optional} containing the value of the {@code X-Stripe-Telemetry} header to
+   * add to the request. If the header is already present in the request, or if there is available
+   * metrics, or if telemetry is disabled, then the returned {@code Optional} is empty.
    *
    * @param headers the request headers
    */
-  public void maybeAddTelemetryHeader(Map<String, String> headers) {
-    if (headers.containsKey("X-Stripe-Telemetry")) {
-      return;
+  public Optional<String> getHeaderValue(HttpHeaders headers) {
+    if (headers.firstValue(HEADER_NAME).isPresent()) {
+      return Optional.empty();
     }
 
     RequestMetrics requestMetrics = prevRequestMetrics.poll();
     if (requestMetrics == null) {
-      return;
+      return Optional.empty();
     }
 
     if (!Stripe.enableTelemetry) {
-      return;
+      return Optional.empty();
     }
 
     ClientTelemetryPayload payload = new ClientTelemetryPayload(requestMetrics);
-    headers.put("X-Stripe-Client-Telemetry", gson.toJson(payload));
+    return Optional.of(gson.toJson(payload));
   }
 
   /**