Improve handling of User-Agent header (#124)

- Expose it as a structured list of library versions.
- Migrate to new format (semicolon-separated with parentheses).
- Add operating system’s version to the list.

Fixes #121.

Author: Clément Le Provost

algoliasearch/src/main/java/com/algolia/search/saas/Client.java

@@ -65,7 +65,41 @@
 public class Client {
     private final static String version = "3.3.0";
 
-    protected String userAgent = "Algolia for Android " + version;
+    /**
+     * The user agents as a raw string. This is what is passed in request headers.
+     * WARNING: It is stored for efficiency purposes. It should not be modified directly.
+     */
+    private String userAgentRaw;
+
+    /***
+     * A version of a software library.
+     * Used to construct the <code>User-Agent</code> header.
+     */
+    public static class LibraryVersion {
+        public final @NonNull String name;
+        public final @NonNull String version;
+
+        public LibraryVersion(@NonNull String name, @NonNull String version) {
+            this.name = name;
+            this.version = version;
+        }
+
+        @Override
+        public boolean equals(Object object) {
+            if (!(object instanceof LibraryVersion))
+                return false;
+            LibraryVersion other = (LibraryVersion)object;
+            return this.name.equals(other.name) && this.version.equals(other.version);
+        }
+
+        @Override
+        public int hashCode() {
+            return name.hashCode() ^ version.hashCode();
+        }
+    }
+
+    /** The user agents, as a structured list of library versions. */
+    private List<LibraryVersion> userAgents = new ArrayList<>();
 
     /** Connect timeout (ms). */
     private int connectTimeout = 2000;
@@ -120,6 +154,8 @@ public Client(@NonNull String applicationID, @NonNull String apiKey) {
     public Client(@NonNull String applicationID, @NonNull String apiKey, String[] hosts) {
         this.applicationID = applicationID;
         this.apiKey = apiKey;
+        this.addUserAgent(new LibraryVersion("Algolia for Android", version));
+        this.addUserAgent(new LibraryVersion("Android", Build.VERSION.RELEASE));
         if (hosts != null) {
             setReadHosts(hosts);
             setWriteHosts(hosts);
@@ -280,6 +316,59 @@ public Index initIndex(@NonNull String indexName) {
         return new Index(this, indexName);
     }
 
+    /**
+     * Add a software library to the list of user agents.
+     *
+     * @param userAgent The library to add.
+     */
+    public void addUserAgent(@NonNull LibraryVersion userAgent) {
+        userAgents.add(userAgent);
+        updateUserAgents();
+    }
+
+    /**
+     * Remove a software library from the list of user agents.
+     *
+     * @param userAgent The library to remove.
+     */
+    public void removeUserAgent(@NonNull LibraryVersion userAgent) {
+        userAgents.remove(userAgent);
+        updateUserAgents();
+    }
+
+    /**
+     * Retrieve the list of declared user agents.
+     *
+     * @return The declared user agents.
+     */
+    public @NonNull LibraryVersion[] getUserAgents() {
+        return userAgents.toArray(new LibraryVersion[userAgents.size()]);
+    }
+
+    /**
+     * Test whether a user agent is declared.
+     *
+     * @param userAgent The user agent to look for.
+     * @return true if it is declared on this client, false otherwise.
+     */
+    public boolean hasUserAgent(@NonNull LibraryVersion userAgent) {
+        return userAgents.contains(userAgent);
+    }
+
+    private void updateUserAgents() {
+        StringBuilder s = new StringBuilder();
+        for (LibraryVersion userAgent : userAgents) {
+            if (s.length() != 0) {
+                s.append("; ");
+            }
+            s.append(userAgent.name);
+            s.append(" (");
+            s.append(userAgent.version);
+            s.append(")");
+        }
+        userAgentRaw = s.toString();
+    }
+
     // ----------------------------------------------------------------------
     // Public operations
     // ----------------------------------------------------------------------
@@ -679,7 +768,7 @@ private byte[] _requestRaw(Method m, String url, String json, List<String> hosts
                 }
 
                 // set user agent
-                hostConnection.setRequestProperty("User-Agent", userAgent);
+                hostConnection.setRequestProperty("User-Agent", userAgentRaw);
 
                 // write JSON entity
                 if (json != null) {

algoliasearch/src/offline/java/com/algolia/search/saas/OfflineClient.java

@@ -104,7 +104,7 @@ public OfflineClient(@NonNull Context context, @NonNull String applicationID, @N
         } else {
             this.rootDataDir = getDefaultDataDir();
         }
-        userAgent += ";algoliasearch-offline-core-android " + Sdk.getInstance().getVersionString();
+        this.addUserAgent(new LibraryVersion("algoliasearch-offline-core-android", Sdk.getInstance().getVersionString()));
     }
 
     /**

algoliasearch/src/test/java/com/algolia/search/saas/IndexTest.java

@@ -851,4 +851,18 @@ public void requestCompleted(JSONObject content, AlgoliaException error) {
         });
         assertTrue("No callback was called", signal.await(Helpers.wait, TimeUnit.SECONDS));
     }
+
+    @Test
+    public void testUserAgent() throws Exception {
+        // Test the default value.
+        String userAgent = (String)Whitebox.getInternalState(client, "userAgentRaw");
+        assertTrue(userAgent.matches("^Algolia for Android \\([0-9.]+\\); Android \\(([0-9.]+|unknown)\\)$"));
+
+        // Manipulate the list.
+        assertFalse(client.hasUserAgent(new Client.LibraryVersion("toto", "6.6.6")));
+        client.addUserAgent(new Client.LibraryVersion("toto", "6.6.6"));
+        assertTrue(client.hasUserAgent(new Client.LibraryVersion("toto", "6.6.6")));
+        userAgent = (String)Whitebox.getInternalState(client, "userAgentRaw");
+        assertTrue(userAgent.matches("^.*; toto \\(6.6.6\\)$"));
+    }
 }