Add ModifiableHttpHeaders method to overwrite HTTP header values

The documentation for `putHeader` was previously incorrect: the methods
retained old values instead of overwriting them. I renamed them to
`addHeader` to be more clear and added a `setHeader` method that behaves
the way `putHeader` was originally documented.

Author: rhernandez35

aws/integrations/aws-lambda-endpoint/src/main/java/software/amazon/smithy/java/aws/integrations/lambda/LambdaEndpoint.java

@@ -98,7 +98,7 @@ private static HttpRequest getRequest(ProxyRequest proxyRequest) {
         if (proxyRequest.getMultiValueHeaders() != null && !proxyRequest.getMultiValueHeaders().isEmpty()) {
             // TODO: handle single-value headers?
             // -- APIGW puts the actual headers in both, but only the latest header per key
-            headers.putHeaders(proxyRequest.getMultiValueHeaders());
+            headers.addHeaders(proxyRequest.getMultiValueHeaders());
         }
         URI uri;
         if (proxyRequest.getMultiValueQueryStringParameters() != null && !proxyRequest

aws/server/aws-server-restjson/src/main/java/software/amazon/smithy/java/aws/server/restjson/AwsRestJson1Protocol.java

@@ -168,7 +168,7 @@ public CompletableFuture<Void> serializeOutput(Job job, SerializableStruct outpu
         HttpResponse response = serializer.serializeResponse();
         httpJob.response().setSerializedValue(response.body());
         httpJob.response().setStatusCode(response.statusCode());
-        httpJob.response().headers().putHeaders(response.headers().map());
+        httpJob.response().headers().addHeaders(response.headers().map());
         return CompletableFuture.completedFuture(null);
     }
 }

http/http-api/src/main/java/software/amazon/smithy/java/http/api/ModifiableHttpHeaders.java

@@ -13,34 +13,80 @@
  */
 public interface ModifiableHttpHeaders extends HttpHeaders {
     /**
-     * Replace a header by name with the given value.
+     * Add a header by name with the given value.
      *
-     * <p>Any previously set values for this header are replaced.
+     * <p>Any previously set values for this header are retained. This value is added
+     * to a list of values for this header name. To overwrite an existing value, use
+     * {@link #setHeader(String, String)}.
      *
      * @param name Case-insensitive name of the header to set.
      * @param value Value to set.
      */
-    void putHeader(String name, String value);
+    void addHeader(String name, String value);
 
     /**
-     * Replace a header by name with the given values.
+     * Add a header by name with the given values.
      *
-     * <p>Any previously set values for this header are replaced.
+     * <p>Any previously set values for this header are retained. This value is added
+     * to a list of values for this header name. To overwrite an existing value, use
+     * {@link #setHeader(String, List)}.
      *
      * @param name Case-insensitive name of the header to set.
      * @param values Values to set.
      */
-    void putHeader(String name, List<String> values);
+    void addHeader(String name, List<String> values);
 
     /**
-     * Put the given {@code headers}, similarly to if {@link #putHeader(String, List)} were to be called for each
+     * Adds the given {@code headers}, similarly to if {@link #addHeader(String, List)} were to be called for each
      * entry in the given map.
      *
      * @param headers Map of case-insensitive header names to their values.
      */
-    default void putHeaders(Map<String, List<String>> headers) {
+    default void addHeaders(Map<String, List<String>> headers) {
         for (var entry : headers.entrySet()) {
-            putHeader(entry.getKey(), entry.getValue());
+            addHeader(entry.getKey(), entry.getValue());
+        }
+    }
+
+    /**
+     * Sets a header to the given value, overwriting old values if present.
+     *
+     * <p>Any previously set values for this header are replaced as if {@link #removeHeader(String) and
+     * {@link #addHeader(String, String)}} were called in sequence. To add a new value to a
+     * list of values, use {@link #addHeader(String, String)}.
+     *
+     * @param name Case-insensitive name of the header to set.
+     * @param value Value to set.
+     */
+    default void setHeader(String name, String value) {
+        removeHeader(name);
+        addHeader(name, value);
+    }
+
+    /**
+     * Sets a header to the given value, overwriting old values if present.
+     *
+     * <p>Any previously set values for this header are replaced as if {@link #removeHeader(String) and
+     * {@link #addHeader(String, String)}} were called in sequence. To add new values to a
+     * list of values, use {@link #addHeader(String, List)}.
+     *
+     * @param name Case-insensitive name of the header to set.
+     * @param values Values to set.
+     */
+    default void setHeader(String name, List<String> values) {
+        removeHeader(name);
+        addHeader(name, values);
+    }
+
+    /**
+     * Puts the given {@code headers}, similarly to if {@link #setHeader(String, List)} were to be called for each
+     * entry in the given map.
+     *
+     * @param headers Map of case-insensitive header names to their values.
+     */
+    default void setHeaders(Map<String, List<String>> headers) {
+        for (var entry : headers.entrySet()) {
+            setHeader(entry.getKey(), entry.getValue());
         }
     }
 

http/http-api/src/main/java/software/amazon/smithy/java/http/api/SimpleModifiableHttpHeaders.java

@@ -19,15 +19,47 @@ final class SimpleModifiableHttpHeaders implements ModifiableHttpHeaders {
     private final Map<String, List<String>> headers = new ConcurrentHashMap<>();
 
     @Override
-    public void putHeader(String name, String value) {
+    public void addHeader(String name, String value) {
         headers.computeIfAbsent(formatPutKey(name), k -> new ArrayList<>()).add(value);
     }
 
     @Override
-    public void putHeader(String name, List<String> values) {
+    public void addHeader(String name, List<String> values) {
         headers.computeIfAbsent(formatPutKey(name), k -> new ArrayList<>()).addAll(values);
     }
 
+    @Override
+    public void setHeader(String name, String value) {
+        var key = formatPutKey(name);
+        var list = headers.get(formatPutKey(name));
+        if (list == null) {
+            list = new ArrayList<>(1);
+            headers.put(key, list);
+        } else {
+            list.clear();
+        }
+
+        list.add(value);
+    }
+
+    @Override
+    public void setHeader(String name, List<String> values) {
+        var key = formatPutKey(name);
+        var list = headers.get(formatPutKey(name));
+        if (list == null) {
+            list = new ArrayList<>(values.size());
+            headers.put(key, list);
+        } else {
+            list.clear();
+        }
+
+        // believe it or not, this is more efficient than the bulk constructor
+        // https://bugs.openjdk.org/browse/JDK-8368292
+        for (var element : values) {
+            list.add(element);
+        }
+    }
+
     private static String formatPutKey(String name) {
         return name.trim().toLowerCase(Locale.ENGLISH);
     }

http/http-api/src/main/java/software/amazon/smithy/java/http/api/SimpleUnmodifiableHttpHeaders.java

@@ -80,7 +80,7 @@ public ModifiableHttpHeaders toModifiable() {
         for (var entry : headers.entrySet()) {
             copy.put(entry.getKey(), new ArrayList<>(entry.getValue()));
         }
-        mod.putHeaders(copy);
+        mod.addHeaders(copy);
         return mod;
     }
 

server/server-core/src/main/java/software/amazon/smithy/java/server/core/CorsHeaders.java

@@ -35,8 +35,8 @@ public static void addCorsHeaders(HttpJob job) {
             return;
         }
 
-        job.response().headers().putHeaders(BASE_CORS_HEADERS);
-        job.response().headers().putHeader("Access-Control-Allow-Origin", List.of(requestOrigin));
+        job.response().headers().addHeaders(BASE_CORS_HEADERS);
+        job.response().headers().addHeader("Access-Control-Allow-Origin", List.of(requestOrigin));
     }
 
     private static boolean shouldAddCorsHeaders(HttpJob job) {

server/server-core/src/test/java/software/amazon/smithy/java/server/core/TestStructs.java

@@ -140,12 +140,12 @@ public static class TestModifiableHttpHeaders implements ModifiableHttpHeaders {
         Map<String, List<String>> headers = new HashMap<>();
 
         @Override
-        public void putHeader(String name, String value) {
+        public void addHeader(String name, String value) {
             headers.put(name, List.of(value));
         }
 
         @Override
-        public void putHeader(String name, List<String> values) {
+        public void addHeader(String name, List<String> values) {
             headers.put(name, values);
         }
 

server/server-netty/src/main/java/software/amazon/smithy/java/server/netty/NettyHttpHeaders.java

@@ -38,15 +38,25 @@ public List<String> allValues(String name) {
     }
 
     @Override
-    public void putHeader(String name, String value) {
+    public void addHeader(String name, String value) {
         nettyHeaders.add(name, value);
     }
 
     @Override
-    public void putHeader(String name, List<String> values) {
+    public void addHeader(String name, List<String> values) {
         nettyHeaders.add(name, values);
     }
 
+    @Override
+    public void setHeader(String name, String value) {
+        nettyHeaders.set(name, value);
+    }
+
+    @Override
+    public void setHeader(String name, List<String> values) {
+        nettyHeaders.set(name, values);
+    }
+
     @Override
     public void removeHeader(String name) {
         nettyHeaders.remove(name);

server/server-rpcv2-cbor/src/main/java/software/amazon/smithy/java/server/rpcv2/RpcV2CborProtocol.java

@@ -99,7 +99,7 @@ public CompletableFuture<Void> serializeOutput(Job job, SerializableStruct outpu
         } else {
             statusCode = 200;
         }
-        httpJob.response().headers().putHeader("smithy-protocol", "rpc-v2-cbor");
+        httpJob.response().headers().setHeader("smithy-protocol", "rpc-v2-cbor");
         httpJob.response().setStatusCode(statusCode);
         return CompletableFuture.completedFuture(null);
     }