feat: Add support for custom HTTP request headers (#585)

* fix: Make HttpWrapper#setHttpClient public

* feat: Support custom request headers

* refactor: Immutable custom headers map

Author: SMadani

CHANGELOG.md

@@ -2,6 +2,11 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+# [9.2.0] - 2025-04-30
+- Added support for setting additional request headers in `HttpConfig`
+- Allow setting `HttpClient` and `HttpConfig` on `HttpWrapper`
+- Bumped Jackson version to 2.19.0
+
 # [9.1.0] - 2025-04-22
 - Added custom HTTP requests support via `CustomClient` (see [README](README.md#custom-requests) for details)
 

README.md

@@ -74,7 +74,7 @@ Add the following to your `build.gradle` or `build.gradle.kts` file:
 
 ```groovy
 dependencies {
-    implementation("com.vonage:server-sdk:9.1.0")
+    implementation("com.vonage:server-sdk:9.2.0")
 }
 ```
 
@@ -85,7 +85,7 @@ Add the following to the `<dependencies>` section of your `pom.xml` file:
 <dependency>
     <groupId>com.vonage</groupId>
     <artifactId>server-sdk</artifactId>
-    <version>9.1.0</version>
+    <version>9.2.0</version>
 </dependency>
 ```
 
@@ -248,6 +248,35 @@ VonageClient client = VonageClient.builder()
         .build();
 ```
 
+### Proxy
+
+You can set a proxy server for requests using the `proxy` method on `HttpConfig.Builder`.
+
+```java
+VonageClient client = VonageClient.builder()
+        .applicationId(APPLICATION_ID)
+        .privateKeyPath(PRIVATE_KEY_PATH)
+        .httpConfig(HttpConfig.builder().proxy("https://myserver.example.com").build())
+        .build();
+```
+
+
+### Request Headers
+
+With the `HttpConfig` class, you can also set custom request headers for all requests made by the SDK.
+
+```java
+VonageClient client = VonageClient.builder()
+        .applicationId(APPLICATION_ID)
+        .privateKeyPath(PRIVATE_KEY_PATH)
+        .httpConfig(HttpConfig.builder()
+                .addRequestHeader("X-My-Header", "MyValue")
+                .addRequestHeader("Correlation-Id", "123-456-789")
+                .build()
+        )
+        .build();
+```
+
 ### Logging
 
 The SDK uses [Java's built-in logging library (`java.util.logging`)](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) to log requests and responses.

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>com.vonage</groupId>
   <artifactId>server-sdk</artifactId>
-  <version>9.1.0</version>
+  <version>9.2.0</version>
 
   <name>Vonage Java Server SDK</name>
   <description>Java client for Vonage APIs</description>
@@ -45,7 +45,7 @@
     <java.testVersion>21</java.testVersion>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <nexusUrl>https://oss.sonatype.org</nexusUrl>
-    <jackson.version>2.18.3</jackson.version>
+    <jackson.version>2.19.0</jackson.version>
     <mockito.version>5.17.0</mockito.version>
     <jjwt.version>0.12.6</jjwt.version>
   </properties>

src/main/java/com/vonage/client/AbstractMethod.java

@@ -34,7 +34,7 @@
  * Abstract class to assist in implementing a call against a REST endpoint.
  * <p>
  * Concrete implementations must implement {@link #makeRequest(Object)} to construct a {@link RequestBuilder} from the
- * provided parameterized request object, and {@link #parseResponse(HttpResponse)} to construct the parameterized
+ * provided parameterised request object, and {@link #parseResponse(HttpResponse)} to construct the parameterized
  * {@link HttpResponse} object.
  * <p>
  * The REST call is executed by calling {@link #execute(Object)}.
@@ -86,9 +86,10 @@ protected RES postProcessParsedResponse(RES response) {
         return response;
     }
 
-    private HttpUriRequest createFullHttpRequest(REQ request) throws VonageClientException {
-        return applyAuth(makeRequest(request))
-                .setHeader(HttpHeaders.USER_AGENT, httpWrapper.getUserAgent())
+    HttpUriRequest createFullHttpRequest(REQ request) throws VonageClientException {
+        RequestBuilder rqb = applyAuth(makeRequest(request));
+        httpWrapper.getHttpConfig().getCustomHeaders().forEach(rqb::setHeader);
+        return rqb.setHeader(HttpHeaders.USER_AGENT, httpWrapper.getUserAgent())
                 .setCharset(StandardCharsets.UTF_8).build();
     }
 

src/main/java/com/vonage/client/HttpConfig.java

@@ -16,6 +16,8 @@
 package com.vonage.client;
 
 import java.net.URI;
+import java.util.LinkedHashMap;
+import java.util.Map;
 import java.util.Objects;
 import java.util.function.Function;
 
@@ -30,6 +32,7 @@ public class HttpConfig {
     private final String customUserAgent, apiBaseUri, restBaseUri, apiEuBaseUri, videoBaseUri;
     private final Function<ApiRegion, String> regionalUriGetter;
     private final URI proxy;
+    private final Map<String, String> customHeaders;
 
     private HttpConfig(Builder builder) {
         if ((timeoutMillis = builder.timeoutMillis) < 10) {
@@ -42,6 +45,7 @@ private HttpConfig(Builder builder) {
         apiEuBaseUri = builder.apiEuBaseUri;
         regionalUriGetter = builder.regionalUriGetter;
         customUserAgent = builder.customUserAgent;
+        customHeaders = builder.customHeaders;
     }
 
     /**
@@ -54,18 +58,39 @@ public int getTimeoutMillis() {
         return timeoutMillis;
     }
 
+    /**
+     * Returns the base URI for the "api" endpoints.
+     *
+     * @return The base URI for the "api" endpoints.
+     */
     public String getApiBaseUri() {
         return apiBaseUri;
     }
 
+    /**
+     * Returns the base URI for the "rest" endpoints.
+     *
+     * @return The base URI for the "rest" endpoints.
+     */
     public String getRestBaseUri() {
         return restBaseUri;
     }
 
+    /**
+     * Returns the base URI for the "video" endpoints.
+     *
+     * @return The base URI for the "video" endpoints.
+     * @since 8.0.0
+     */
     public String getVideoBaseUri() {
         return videoBaseUri;
     }
 
+    /**
+     * Returns the base URI for the "api-eu" endpoints.
+     *
+     * @return The base URI for the "api-eu" endpoints.
+     */
     public String getApiEuBaseUri() {
         return apiEuBaseUri;
     }
@@ -91,6 +116,16 @@ public String getCustomUserAgent() {
         return customUserAgent;
     }
 
+    /**
+     * Returns the additional headers to be included in all requests.
+     *
+     * @return A map of custom headers (may be empty if none are set).
+     * @since 9.2.0
+     */
+    public Map<String, String> getCustomHeaders() {
+        return customHeaders;
+    }
+
     /**
      * Returns the proxy URL to use for the underlying HTTP client configuration.
      *
@@ -125,6 +160,7 @@ public static Builder builder() {
     public static final class Builder {
         private int timeoutMillis = 60_000;
         private URI proxy;
+        private Map<String, String> customHeaders = new LinkedHashMap<>(4);
         private Function<ApiRegion, String> regionalUriGetter = region -> "https://"+region+".vonage.com";
         private String customUserAgent,
                 apiBaseUri = DEFAULT_API_BASE_URI,
@@ -187,6 +223,20 @@ public Builder proxy(URI proxy) {
             return this;
         }
 
+        /**
+         * Add a custom HTTP header to all requests made with this client.
+         *
+         * @param name The header name.
+         * @param value The header value.
+         *
+         * @return This builder.
+         * @since 9.2.0
+         */
+        public Builder addRequestHeader(String name, String value) {
+            customHeaders.put(name, value);
+            return this;
+        }
+
         /**
          * Replaces the URI used in "api" endpoints.
          *
@@ -240,12 +290,11 @@ public Builder videoBaseUri(String videoBaseUri) {
          */
         public Builder baseUri(String baseUri) {
             String sanitizedUri = sanitizeUri(baseUri);
-            regionalUriGetter(region -> sanitizedUri.replace("://", "://" + region + '.'));
             apiBaseUri = sanitizedUri;
             restBaseUri = sanitizedUri;
             apiEuBaseUri = sanitizedUri;
             videoBaseUri = sanitizedUri;
-            return this;
+            return regionalUriGetter(region -> sanitizedUri.replace("://", "://" + region + '.'));
         }
 
         /**

src/main/java/com/vonage/client/HttpWrapper.java

@@ -37,7 +37,7 @@
 public class HttpWrapper {
     private static final String
             CLIENT_NAME = "vonage-java-sdk",
-            CLIENT_VERSION = "9.1.0",
+            CLIENT_VERSION = "9.2.0",
             JAVA_VERSION = System.getProperty("java.version"),
             USER_AGENT = String.format("%s/%s java/%s", CLIENT_NAME, CLIENT_VERSION, JAVA_VERSION);
 
@@ -54,34 +54,68 @@ public class HttpWrapper {
      *
      * @since 9.0.0
      */
-    HttpWrapper(HttpConfig httpConfig, AuthCollection authCollection, HttpClient httpClient) {
+    public HttpWrapper(HttpConfig httpConfig, AuthCollection authCollection, HttpClient httpClient) {
         this.authCollection = authCollection;
         this.httpConfig = httpConfig;
         this.httpClient = httpClient instanceof CloseableHttpClient ?
                 (CloseableHttpClient) httpClient : createHttpClient();
     }
 
+    /**
+     * Creates a new instance of the HttpWrapper class.
+     *
+     * @param httpConfig The HTTP configuration settings to use.
+     * @param authCollection The authentication settings to use.
+     */
     public HttpWrapper(HttpConfig httpConfig, AuthCollection authCollection) {
         this(httpConfig, authCollection, null);
     }
 
+    /**
+     * Creates a new instance of the HttpWrapper class.
+     *
+     * @param authCollection The authentication settings to use.
+     */
     public HttpWrapper(AuthCollection authCollection) {
         this(HttpConfig.builder().build(), authCollection);
     }
 
+    /**
+     * Creates a new instance of the HttpWrapper class.
+     *
+     * @param authMethods The authentication methods to use.
+     */
     public HttpWrapper(AuthMethod... authMethods) {
         this(HttpConfig.builder().build(), authMethods);
     }
 
+    /**
+     * Creates a new instance of the HttpWrapper class.
+     *
+     * @param httpConfig The HTTP configuration settings to use.
+     * @param authMethods The authentication methods to use.
+     */
     public HttpWrapper(HttpConfig httpConfig, AuthMethod... authMethods) {
         this(httpConfig, new AuthCollection(authMethods));
     }
 
-    void setHttpClient(CloseableHttpClient httpClient) {
+    /**
+     * Sets the HTTP client to be used by the SDK.
+     *
+     * @param httpClient The custom HTTP client instance to use.
+     * @deprecated Please use {@linkplain HttpConfig} options where possible.
+     */
+    @Deprecated
+    public void setHttpClient(CloseableHttpClient httpClient) {
         this.httpClient = httpClient;
     }
 
-    void setHttpConfig(HttpConfig httpConfig) {
+    /**
+     * Sets the HTTP configuration options for the client.
+     *
+     * @param httpConfig The HTTP configuration settings to use.
+     */
+    public void setHttpConfig(HttpConfig httpConfig) {
         this.httpConfig = httpConfig;
     }
 

src/test/java/com/vonage/client/AbstractMethodTest.java

@@ -20,7 +20,10 @@
 import com.vonage.client.auth.*;
 import com.vonage.client.auth.hashutils.HashType;
 import org.apache.commons.codec.binary.Base64;
-import org.apache.http.*;
+import org.apache.http.HttpEntity;
+import org.apache.http.HttpEntityEnclosingRequest;
+import org.apache.http.HttpResponse;
+import org.apache.http.ProtocolVersion;
 import org.apache.http.client.methods.CloseableHttpResponse;
 import org.apache.http.client.methods.HttpUriRequest;
 import org.apache.http.client.methods.RequestBuilder;
@@ -34,7 +37,10 @@
 import org.junit.jupiter.api.*;
 import org.mockito.ArgumentCaptor;
 import static org.mockito.Mockito.*;
-import java.io.*;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
 import java.net.InetSocketAddress;
 import java.net.SocketTimeoutException;
 import java.nio.charset.StandardCharsets;
@@ -119,6 +125,9 @@ public void setUp() throws Exception {
         AuthCollection mockAuthMethods = mock(AuthCollection.class);
         mockAuthMethod = mock(AuthMethod.class);
         mockHttpClient = mock(CloseableHttpClient.class);
+        var httpConfig = HttpConfig.builder().build();
+        when(mockWrapper.getHttpConfig()).thenReturn(httpConfig);
+        when(mockAuthMethod.getSortKey()).thenReturn(0);
         when(mockAuthMethods.getAcceptableAuthMethod(any())).thenReturn(mockAuthMethod);
         when(mockWrapper.getHttpClient()).thenReturn(mockHttpClient);
         when(mockHttpClient.execute(any(HttpUriRequest.class))).thenReturn(basicResponse);
@@ -159,6 +168,22 @@ public void testExecuteHeaders() throws Exception {
         assertEquals(expected, result);
     }
 
+    @Test
+    public void testCustomHeaderDoesNotOverrideUserAgent() {
+        var overridenUa = "my-custom-agent Should not be possible";
+        var cm = new ConcreteMethod(new HttpWrapper(HttpConfig.builder()
+                    .addRequestHeader("X-Correlation-Id", "aaaa-bbbb-cccc-dddd")
+                    .addRequestHeader("User-Agent", overridenUa)
+                .build(), new NoAuthMethod()
+        ));
+        var request = cm.createFullHttpRequest("https://example.com");
+        var userAgentHeaders = request.getHeaders("User-Agent");
+        assertNotNull(userAgentHeaders);
+        assertEquals(1, userAgentHeaders.length);
+        assertNotEquals(overridenUa, userAgentHeaders[0].getValue());
+        assertEquals("aaaa-bbbb-cccc-dddd", request.getFirstHeader("X-Correlation-Id").getValue());
+    }
+
     @Test
     public void testGetAuthMethod() {
         ConcreteMethod method = new ConcreteMethod(mockWrapper);