Merge #503

503: Feature/Analytics r=alallema a=brunoocasali

What this PR does:

- Add a new item to be changed when we create a new release of this SDK (sorry about that `@alallema).`
- Add the user-agent headers through the Client/Config.

Add this disclaimer to the release:

## 🚀 Enhancements

* Add User-Agent header to have analytics in every HTTP request (#503) `@brunoocasali`

Analytics is enabled by default in the server, but you can disable them by following [this guide](https://docs.meilisearch.com/learn/what_is_meilisearch/telemetry.html#how-to-disable-data-collection)
Also, of course, every analytics data we collect are **ANONYMOUS** [read the guide for more information](https://docs.meilisearch.com/learn/what_is_meilisearch/telemetry.html).

Thanks again to `@brunoocasali!` 🎉 


Co-authored-by: Bruno Casali <[email protected]>
Co-authored-by: Amélie <[email protected]>

Author: 3 people

CONTRIBUTING.md

@@ -115,6 +115,12 @@ _[Read more about this](https://github.com/meilisearch/integration-guides/blob/m
 
 Make a PR modifying the following files with the right version:
 
+- [`Version.java`](/src/main/java/com/meilisearch/sdk/Version.java)
+
+```java
+VERSION = "X.X.X";
+```
+
 - [`build.gradle`](/build.gradle)
 
 ```java

src/main/java/com/meilisearch/sdk/Config.java

@@ -2,6 +2,11 @@
 
 import com.meilisearch.sdk.json.GsonJsonHandler;
 import com.meilisearch.sdk.json.JsonHandler;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import lombok.Getter;
 import lombok.Setter;
 
@@ -12,6 +17,7 @@ public class Config {
     protected final String hostUrl;
     protected final String apiKey;
     protected final HttpClient httpClient;
+    protected final Map<String, String> headers;
     protected JsonHandler jsonHandler;
 
     /**
@@ -24,14 +30,30 @@ public Config(String hostUrl) {
     }
 
     /**
-     * Creates a configuration with an API key
+     * Creates a configuration with an API key and no customized headers.
      *
      * @param hostUrl URL of the Meilisearch instance
      * @param apiKey API key to pass to the header of requests sent to Meilisearch
      */
     public Config(String hostUrl, String apiKey) {
         this.hostUrl = hostUrl;
         this.apiKey = apiKey;
+        this.headers = configHeaders(new String[0]);
+        this.jsonHandler = new GsonJsonHandler();
+        this.httpClient = new HttpClient(this);
+    }
+
+    /**
+     * Creates a configuration with an API key
+     *
+     * @param hostUrl URL of the Meilisearch instance
+     * @param apiKey API key to pass to the header of requests sent to Meilisearch
+     * @param clientAgents List of customized agents to be passed to User-Agent header.
+     */
+    public Config(String hostUrl, String apiKey, String[] clientAgents) {
+        this.hostUrl = hostUrl;
+        this.apiKey = apiKey;
+        this.headers = configHeaders(clientAgents);
         this.jsonHandler = new GsonJsonHandler();
         this.httpClient = new HttpClient(this);
     }
@@ -44,4 +66,14 @@ public Config(String hostUrl, String apiKey) {
     public String getBearerApiKey() {
         return "Bearer " + apiKey;
     }
+
+    private Map<String, String> configHeaders(String[] clientAgents) {
+        List<String> list = new ArrayList<String>(Arrays.asList(clientAgents));
+        list.add(0, Version.getQualifiedVersion());
+
+        Map<String, String> data = new HashMap<>();
+        data.put("User-Agent", String.join(";", list));
+
+        return data;
+    }
 }

src/main/java/com/meilisearch/sdk/HttpClient.java

@@ -12,12 +12,14 @@
 import com.meilisearch.sdk.json.GsonJsonHandler;
 import com.meilisearch.sdk.json.JsonHandler;
 import java.util.Collections;
+import java.util.Map;
 
 /** HTTP client used for API calls to Meilisearch */
 public class HttpClient {
     private final CustomOkHttpClient client;
     private final BasicRequest request;
     private final BasicResponse response;
+    private final Map<String, String> headers;
     protected final JsonHandler jsonHandler;
 
     /**
@@ -28,6 +30,7 @@ public class HttpClient {
     public HttpClient(Config config) {
         this.client = new CustomOkHttpClient(config);
         this.jsonHandler = config.jsonHandler;
+        this.headers = config.headers;
         this.request = new BasicRequest(jsonHandler);
         this.response = new BasicResponse(jsonHandler);
     }
@@ -41,6 +44,7 @@ public HttpClient(Config config) {
     public HttpClient(CustomOkHttpClient client, BasicRequest request) {
         this.client = client;
         this.request = request;
+        this.headers = Collections.<String, String>emptyMap();
         this.jsonHandler = new GsonJsonHandler();
         this.response = new BasicResponse(jsonHandler);
     }
@@ -67,8 +71,7 @@ <T> T get(String api, Class<T> targetClass, Class<?>... parameters)
      */
     <T> T get(String api, String param, Class<T> targetClass, Class<?>... parameters)
             throws MeilisearchException {
-        HttpRequest requestConfig =
-                request.create(HttpMethod.GET, api + param, Collections.emptyMap(), null);
+        HttpRequest requestConfig = request.create(HttpMethod.GET, api + param, this.headers, null);
         HttpResponse<T> httpRequest = this.client.get(requestConfig);
         HttpResponse<T> httpResponse = response.create(httpRequest, targetClass, parameters);
 
@@ -88,8 +91,7 @@ <T> T get(String api, String param, Class<T> targetClass, Class<?>... parameters
      * @throws MeilisearchException if the response is an error
      */
     <S, T> T post(String api, S body, Class<T> targetClass) throws MeilisearchException {
-        HttpRequest requestConfig =
-                request.create(HttpMethod.POST, api, Collections.emptyMap(), body);
+        HttpRequest requestConfig = request.create(HttpMethod.POST, api, this.headers, body);
         HttpResponse<T> httpRequest = this.client.post(requestConfig);
         HttpResponse<T> httpResponse = response.create(httpRequest, targetClass);
 
@@ -109,8 +111,7 @@ <S, T> T post(String api, S body, Class<T> targetClass) throws MeilisearchExcept
      * @throws MeilisearchException if the response is an error
      */
     <S, T> T put(String api, S body, Class<T> targetClass) throws MeilisearchException {
-        HttpRequest requestConfig =
-                request.create(HttpMethod.PUT, api, Collections.emptyMap(), body);
+        HttpRequest requestConfig = request.create(HttpMethod.PUT, api, this.headers, body);
         HttpResponse<T> httpRequest = this.client.put(requestConfig);
         HttpResponse<T> httpResponse = response.create(httpRequest, targetClass);
 
@@ -130,8 +131,7 @@ <S, T> T put(String api, S body, Class<T> targetClass) throws MeilisearchExcepti
      * @throws MeilisearchException if the response is an error
      */
     <S, T> T patch(String api, S body, Class<T> targetClass) throws MeilisearchException {
-        HttpRequest requestConfig =
-                request.create(HttpMethod.PATCH, api, Collections.emptyMap(), body);
+        HttpRequest requestConfig = request.create(HttpMethod.PATCH, api, this.headers, body);
         HttpResponse<T> httpRequest = this.client.patch(requestConfig);
         HttpResponse<T> httpResponse = response.create(httpRequest, targetClass);
 
@@ -150,8 +150,7 @@ <S, T> T patch(String api, S body, Class<T> targetClass) throws MeilisearchExcep
      * @throws MeilisearchException if the response is an error
      */
     <T> T delete(String api, Class<T> targetClass) throws MeilisearchException {
-        HttpRequest requestConfig =
-                request.create(HttpMethod.DELETE, api, Collections.emptyMap(), null);
+        HttpRequest requestConfig = request.create(HttpMethod.DELETE, api, this.headers, null);
         HttpResponse<T> httpRequest = this.client.delete(requestConfig);
         HttpResponse<T> httpResponse = response.create(httpRequest, targetClass);
 

src/main/java/com/meilisearch/sdk/Version.java

@@ -0,0 +1,9 @@
+package com.meilisearch.sdk;
+
+public class Version {
+    static final String VERSION = "0.8.0";
+
+    public static String getQualifiedVersion() {
+        return "Meilisearch Java (v" + VERSION + ")";
+    }
+}

src/main/java/com/meilisearch/sdk/http/CustomOkHttpClient.java

@@ -55,8 +55,14 @@ private Request buildRequest(HttpRequest request) throws MalformedURLException {
         URL url = new URL(this.config.getHostUrl() + request.getPath());
         Request.Builder builder = new Request.Builder();
         builder.url(url);
+
         if (this.config.getApiKey() != null)
             builder.addHeader("Authorization", this.config.getBearerApiKey());
+
+        for (Map.Entry<String, String> entry : request.getHeaders().entrySet()) {
+            builder.addHeader(entry.getKey(), entry.getValue());
+        }
+
         switch (request.getMethod()) {
             case GET:
                 builder.get();

src/main/java/com/meilisearch/sdk/http/request/HttpRequest.java

@@ -10,7 +10,7 @@
 public class HttpRequest {
     @Setter private HttpMethod method;
     @Setter private String path;
-    @Setter private Map<String, String> headers;
+    @Getter private Map<String, String> headers;
     private String content;
 
     public HttpRequest() {}

src/test/java/com/meilisearch/sdk/http/CustomOkHttpClientTest.java

@@ -1,12 +1,14 @@
 package com.meilisearch.sdk.http;
 
 import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.notNullValue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.*;
 
 import com.meilisearch.sdk.Config;
+import com.meilisearch.sdk.Version;
 import com.meilisearch.sdk.http.request.HttpMethod;
 import com.meilisearch.sdk.http.request.HttpRequest;
 import com.meilisearch.sdk.http.response.HttpResponse;
@@ -15,6 +17,8 @@
 import java.io.InputStreamReader;
 import java.util.ArrayDeque;
 import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.stream.Collectors;
 import okhttp3.*;
 import okhttp3.internal.connection.RealCall;
@@ -219,4 +223,33 @@ void deleteWithoutBody() throws Exception {
                 expectedRequest.url().toString(),
                 equalTo(this.config.getHostUrl() + request.getPath()));
     }
+
+    @Test
+    void requestWithHeaders() throws Exception {
+        Map<String, String> headers = new HashMap<String, String>();
+        headers.put("User-Agent", "Meilisearch (v1.2.3)");
+
+        HttpRequest request = new HttpRequest(HttpMethod.DELETE, "/test", headers, null);
+        HttpResponse<Object> response = classToTest.delete(request);
+
+        Request expectedRequest = requestQueue.poll();
+        assertThat(expectedRequest, notNullValue());
+        assertThat(expectedRequest.headers().toString(), containsString("Meilisearch (v1.2.3)"));
+    }
+
+    @Test
+    void defaultConfigHasAnalytics() throws Exception {
+        assertThat(
+                config.getHeaders().get("User-Agent").toString(),
+                containsString(Version.getQualifiedVersion()));
+    }
+
+    @Test
+    void customConfigWithCustomAnalyticsHasBoth() throws Exception {
+        Config newConfig = new Config("host", "key", new String[] {"MyApp v1.44"});
+
+        assertThat(
+                newConfig.getHeaders().get("User-Agent").toString(),
+                containsString(Version.getQualifiedVersion() + ";MyApp v1.44"));
+    }
 }