From a2eb67c86e2e86ebdf579e4efff23e4bd60eeb71 Mon Sep 17 00:00:00 2001
From: colin-lamed <9568290+colin-lamed@users.noreply.github.com>
Date: Tue, 5 Jul 2022 17:28:34 +0100
Subject: [PATCH] BAU Introduce setHeader and deprecate replaceHeader and
 addHeaders

---
 README.md                                                   | 6 ++++--
 .../main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala   | 5 +++++
 .../scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala    | 5 ++++-
 .../scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala    | 4 ++--
 4 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5e83da08..e1706de3 100644
--- a/README.md
+++ b/README.md
@@ -80,12 +80,14 @@ httpClientV2.post(url"$url").withBody(Json.toJson(payload)).addHeaders(headers).
 
 #### Header manipulation
 
-With `HttpClient`, replacing a header can require providing a customised client implementation (e.g. to replace the user-agent header), or updating the `HeaderCarrier` (e.g. to replace the authorisation header). This can now all be done with the `replaceHeader` on `HttpClientV2` per call. e.g.
+With `HttpClient`, replacing a header can require providing a customised client implementation (e.g. to replace the user-agent header), or updating the `HeaderCarrier` (e.g. to replace the authorisation header). This can now all be done with the `setHeader` on `HttpClientV2` per call. e.g.
 
 ```scala
-httpClientV2.get(url"$url").replaceHeader("User-Agent" -> userAgent).replaceHeader("Authorization" -> authorization).execute[ResponseType]
+httpClientV2.get(url"$url").setHeader("User-Agent" -> userAgent).setHeader("Authorization" -> authorization).execute[ResponseType]
 ```
 
+As well as replacing existing header values, `setHeader` can be used to add new headers too, and in most cases should be used in preference to `addHeaders` where the values are merged with any existing ones (e.g. from HeaderCarrier).
+
 #### Using proxy
 
 With `HttpClient`, to use a proxy requires creating a new instance of HttpClient to mix in `WSProxy` and configure. With `HttpClientV2` this can be done with the same client, calling `withProxy` per call. e.g.
diff --git a/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala b/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala
index 2c3b3a87..98e7a99c 100644
--- a/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala
+++ b/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2.scala
@@ -61,8 +61,13 @@ trait RequestBuilder {
 
   // support functions
 
+  /** Adds the header. If the header has already been defined (e.g. from HeaderCarrier), it will be replaced. */
+  def setHeader(header: (String, String)): RequestBuilder
+
+  @deprecated("Use setHeader", "14.5.0")
   def replaceHeader(header: (String, String)): RequestBuilder
 
+  @deprecated("Use setHeader to add or replace, or use transform(_.addHttpHeaders) to append header values to existing", "14.5.0")
   def addHeaders(headers: (String, String)*): RequestBuilder
 
   def withProxy: RequestBuilder
diff --git a/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala b/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala
index c9bc349c..a466bfc8 100644
--- a/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala
+++ b/http-verbs-common/src/main/scala/uk/gov/hmrc/http/client/HttpClientV2Impl.scala
@@ -111,9 +111,12 @@ final class RequestBuilderImpl(
     request.withHttpHeaders(denormalise(hdrsWithoutKey) :+ header : _*)
   }
 
-  override def replaceHeader(header: (String, String)): RequestBuilderImpl =
+  override def setHeader(header: (String, String)): RequestBuilderImpl =
     transform(replaceHeaderOnRequest(_, header))
 
+  override def replaceHeader(header: (String, String)): RequestBuilderImpl =
+    setHeader(header)
+
   override def addHeaders(headers: (String, String)*): RequestBuilderImpl =
     transform(_.addHttpHeaders(headers: _*))
 
diff --git a/http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala b/http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala
index c341e11c..5adb208b 100644
--- a/http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala
+++ b/http-verbs-common/src/test/scala/uk/gov/hmrc/http/client/HttpClientV2Spec.scala
@@ -531,7 +531,7 @@ class HttpClientV2Spec
         httpClientV2
           .put(url"$wireMockUrl/")
           .transform(_.withBody(Json.toJson(ReqDomain("req"))))
-          .replaceHeader("User-Agent" -> "ua2")
+          .setHeader("User-Agent" -> "ua2")
           .execute[ResDomain]
     }
 
@@ -547,7 +547,7 @@ class HttpClientV2Spec
         httpClientV2
           .put(url"$wireMockUrl/")
           .withBody(Json.toJson(ReqDomain("req")))
-          .replaceHeader("User-Agent" -> "ua2")
+          .setHeader("User-Agent" -> "ua2")
           .execute[ResDomain]
 
       res.futureValue shouldBe ResDomain("res")