feat: Send platform information in user-agent with API requests, add opt-out for this feature

Author: JanEbbing

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
 * Script to check our source code for license headers and a step for them in the CI.
+* Added system and java version information to the user-agent string that is sent with API calls, along with an opt-out.
+* Added method for applications that use this library to identify themselves in API requests they make.
+
 
 ## [1.1.0] - 2023-01-26
 ### Added

README.md

@@ -517,6 +517,26 @@ All module functions may raise `DeepLException` or one of its subclasses. If
 invalid arguments are provided, they may raise the standard exceptions
 `IllegalArgumentException`.
 
+### Writing a Plugin
+
+If you use this library in an application, please identify the application with
+`TranslatorOptions.setAppInfo()`, which takes the name and version of the app:
+
+```java
+class Example {  // Continuing class Example from above
+    public void configurationExample() throws Exception {
+        TranslatorOptions options =
+                new TranslatorOptions().setAppInfo("my-java-translation-plugin", "1.2.3");
+        Translator translator = new Translator(authKey, options);
+    }
+}
+```
+
+This information is passed along when the library makes calls to the DeepL API.
+Both name and version are required. Please note that setting the `User-Agent` header
+via `TranslatorOptions.setHeaders()` will override this setting, if you need to use this,
+please manually identify your Application in the `User-Agent` header.
+
 ### Configuration
 
 The `Translator` constructor accepts `TranslatorOptions` as a second argument,
@@ -546,6 +566,34 @@ The available options setters are:
   purposes. By default, the correct DeepL API (Free or Pro) is automatically
   selected.
 
+#### Anonymous platform information
+
+By default, we send some basic information about the platform the client library is running on with each request, see [here for an explanation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). This data is completely anonymous and only used to improve our product, not track any individual users. If you do not wish to send this data, you can opt-out when creating your `Translator` object by calling the `setSendPlatformInfo()` setter on the `TranslatorOptions` like so:
+
+```java
+class Example {  // Continuing class Example from above
+    public void configurationExample() throws Exception {
+        TranslatorOptions options =
+                new TranslatorOptions().setSendPlatformInfo(false);
+        Translator translator = new Translator(authKey, options);
+    }
+}
+```
+
+You can also customize the `User-Agent` header by setting its value explicitly in the `TranslatorOptions` object via the header field. Example:
+
+```java
+class Example {  // Continuing class Example from above
+    public void configurationExample() throws Exception {
+        Map<String, String> headers = new HashMap<>();
+        headers.put("User-Agent", "my custom user agent");
+        TranslatorOptions options =
+                new TranslatorOptions().setHeaders(headers);
+        Translator translator = new Translator(authKey, options);
+    }
+}
+```
+
 ## Issues
 
 If you experience problems using the library, or would like to request a new

deepl-java/build.gradle.kts

@@ -8,6 +8,12 @@ plugins {
 group = "com.deepl.api"
 version = "1.1.0"
 
+val sharedManifest = the<JavaPluginConvention>().manifest {
+    attributes (
+        "Implementation-Title" to "Gradle",
+        "Implementation-Version" to version
+    )
+}
 java {
     sourceCompatibility = JavaVersion.VERSION_1_8
     targetCompatibility = JavaVersion.VERSION_1_8
@@ -20,6 +26,7 @@ repositories {
 dependencies {
     implementation("org.jetbrains:annotations:20.1.0")
     testImplementation("org.junit.jupiter:junit-jupiter:5.8.1")
+    testImplementation("org.mockito:mockito-inline:4.11.0")
 
     api("org.apache.commons:commons-math3:3.6.1")
 
@@ -42,11 +49,17 @@ spotless {
 tasks.register<Jar>("sourcesJar") {
     archiveClassifier.set("sources")
     from(sourceSets.main.get().allJava)
+    manifest = project.the<JavaPluginConvention>().manifest {
+        from(sharedManifest)
+    }
 }
 
 tasks.register<Jar>("javadocJar") {
     archiveClassifier.set("javadoc")
     from(tasks.javadoc.get().destinationDir)
+    manifest = project.the<JavaPluginConvention>().manifest {
+        from(sharedManifest)
+    }
 }
 
 publishing {

deepl-java/src/main/java/com/deepl/api/AppInfo.java

@@ -0,0 +1,22 @@
+// Copyright 2023 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+package com.deepl.api;
+
+public class AppInfo {
+  private String appName;
+  private String appVersion;
+
+  public AppInfo(String appName, String appVersion) {
+    this.appName = appName;
+    this.appVersion = appVersion;
+  }
+
+  public String getAppName() {
+    return appName;
+  }
+
+  public String getAppVersion() {
+    return appVersion;
+  }
+}

deepl-java/src/main/java/com/deepl/api/Translator.java

@@ -55,7 +55,9 @@ public Translator(String authKey, TranslatorOptions options) throws IllegalArgum
       headers.putAll(options.getHeaders());
     }
     headers.putIfAbsent("Authorization", "DeepL-Auth-Key " + authKey);
-    headers.putIfAbsent("User-Agent", "deepl-java/1.1.0");
+    headers.putIfAbsent(
+        "User-Agent",
+        constructUserAgentString(options.getSendPlatformInfo(), options.getAppInfo()));
 
     this.httpClientWrapper =
         new HttpClientWrapper(
@@ -76,6 +78,27 @@ public Translator(String authKey) throws IllegalArgumentException {
     this(authKey, new TranslatorOptions());
   }
 
+  /**
+   * Builds the user-agent String which contains platform information.
+   *
+   * @return A string containing the client library version, java version and operating system.
+   */
+  private String constructUserAgentString(boolean sendPlatformInfo, AppInfo appInfo) {
+    StringBuilder sb = new StringBuilder();
+    sb.append("deepl-java/1.1.0");
+    if (sendPlatformInfo) {
+      sb.append(" (");
+      Properties props = System.getProperties();
+      sb.append(props.get("os.name") + "-" + props.get("os.version") + "-" + props.get("os.arch"));
+      sb.append(") java/");
+      sb.append(props.get("java.version"));
+    }
+    if (appInfo != null) {
+      sb.append(" " + appInfo.getAppName() + "/" + appInfo.getAppVersion());
+    }
+    return sb.toString();
+  }
+
   /**
    * Determines if the given DeepL Authentication Key belongs to an API Free account.
    *

deepl-java/src/main/java/com/deepl/api/TranslatorOptions.java

@@ -24,6 +24,8 @@ public class TranslatorOptions {
   @Nullable private Proxy proxy = null;
   @Nullable private Map<String, String> headers = null;
   @Nullable private String serverUrl = null;
+  private boolean sendPlatformInfo = true;
+  @Nullable private AppInfo appInfo = null;
 
   /**
    * Set the maximum number of failed attempts that {@link Translator} will retry, per request. By
@@ -69,6 +71,26 @@ public TranslatorOptions setServerUrl(String serverUrl) {
     return this;
   }
 
+  /**
+   * Set whether to send basic platform information with each API call to improve DeepL products.
+   * Defaults to `true`, set to `false` to opt out. This option will be overriden if a
+   * `'User-agent'` header is present in this objects `headers`.
+   */
+  public TranslatorOptions setSendPlatformInfo(boolean sendPlatformInfo) {
+    this.sendPlatformInfo = sendPlatformInfo;
+    return this;
+  }
+
+  /**
+   * Set an identifier and a version for the program/plugin that uses this Client Library. Example:
+   * `Translator t = new Translator(myAuthKey, new TranslatorOptions()
+   * .setAppInfo('deepl-hadoop-plugin', '1.2.0'))
+   */
+  public TranslatorOptions setAppInfo(String appName, String appVersion) {
+    this.appInfo = new AppInfo(appName, appVersion);
+    return this;
+  }
+
   /** Gets the current maximum number of retries. */
   public int getMaxRetries() {
     return maxRetries;
@@ -93,4 +115,14 @@ public Duration getTimeout() {
   public @Nullable String getServerUrl() {
     return serverUrl;
   }
+
+  /** Gets the `sendPlatformInfo` option */
+  public boolean getSendPlatformInfo() {
+    return sendPlatformInfo;
+  }
+
+  /** Gets the `appInfo` identifiers */
+  public @Nullable AppInfo getAppInfo() {
+    return appInfo;
+  }
 }

deepl-java/src/test/java/com/deepl/api/GeneralTest.java

@@ -3,11 +3,19 @@
 // license that can be found in the LICENSE file.
 package com.deepl.api;
 
+import static org.mockito.Mockito.*;
+
 import java.io.*;
 import java.net.*;
 import java.time.*;
 import java.util.*;
+import java.util.stream.Stream;
 import org.junit.jupiter.api.*;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.mockito.MockedConstruction;
+import org.mockito.Mockito;
 
 class GeneralTest extends TestBase {
 
@@ -237,4 +245,96 @@ void testUsageTeamDocumentLimit() throws Exception {
     Assertions.assertNotNull(usage.getTeamDocument());
     Assertions.assertTrue(usage.getTeamDocument().limitReached());
   }
+
+  @ParameterizedTest
+  @MethodSource("provideUserAgentTestData")
+  void testUserAgent(
+      SessionOptions sessionOptions,
+      TranslatorOptions translatorOptions,
+      Iterable<String> requiredStrings,
+      Iterable<String> blocklistedStrings)
+      throws Exception {
+    Map<String, String> headers = new HashMap<>();
+    HttpURLConnection con = Mockito.mock(HttpURLConnection.class);
+    Mockito.doAnswer(
+            invocation -> {
+              String key = (String) invocation.getArgument(0);
+              String value = (String) invocation.getArgument(1);
+              headers.put(key, value);
+              return null;
+            })
+        .when(con)
+        .setRequestProperty(Mockito.any(String.class), Mockito.any(String.class));
+    Mockito.when(con.getResponseCode()).thenReturn(200);
+    try (MockedConstruction<URL> mockUrl =
+        Mockito.mockConstruction(
+            URL.class,
+            (mock, context) -> {
+              Mockito.when(mock.openConnection()).thenReturn(con);
+            })) {
+      Translator translator = createTranslator(sessionOptions, translatorOptions);
+      Usage usage = translator.getUsage();
+      String userAgentHeader = headers.get("User-Agent");
+      for (String s : requiredStrings) {
+        Assertions.assertTrue(
+            userAgentHeader.contains(s),
+            String.format(
+                "Expected User-Agent header to contain %s\nActual:\n%s", s, userAgentHeader));
+      }
+      for (String n : blocklistedStrings) {
+        Assertions.assertFalse(
+            userAgentHeader.contains(n),
+            String.format(
+                "Expected User-Agent header not to contain %s\nActual:\n%s", n, userAgentHeader));
+      }
+    }
+  }
+
+  // Session options & Translator options: Used to construct the `Translator`
+  // Next arg: List of Strings that must be contained in the user agent header
+  // Last arg: List of Strings that must not be contained in the user agent header
+  private static Stream<? extends Arguments> provideUserAgentTestData() {
+    Map<String, String> testHeaders = new HashMap<>();
+    testHeaders.put("User-Agent", "my custom user agent");
+    Iterable<String> lightPlatformInfo = Arrays.asList("deepl-java/");
+    Iterable<String> lightPlatformInfoWithAppInfo =
+        Arrays.asList("deepl", "my-java-translation-plugin/1.2.3");
+    Iterable<String> detailedPlatformInfo = Arrays.asList(" java/", "(");
+    Iterable<String> detailedPlatformInfoWithAppInfo =
+        Arrays.asList(" java/", "(", "my-java-translation-plugin/1.2.3");
+    Iterable<String> customUserAgent = Arrays.asList("my custom user agent");
+    Iterable<String> noStrings = new ArrayList<String>();
+    return Stream.of(
+        Arguments.of(
+            new SessionOptions(), new TranslatorOptions(), detailedPlatformInfo, noStrings),
+        Arguments.of(
+            new SessionOptions(),
+            new TranslatorOptions().setSendPlatformInfo(false),
+            lightPlatformInfo,
+            detailedPlatformInfo),
+        Arguments.of(
+            new SessionOptions(),
+            new TranslatorOptions().setHeaders(testHeaders),
+            customUserAgent,
+            detailedPlatformInfo),
+        Arguments.of(
+            new SessionOptions(),
+            new TranslatorOptions().setAppInfo("my-java-translation-plugin", "1.2.3"),
+            detailedPlatformInfoWithAppInfo,
+            noStrings),
+        Arguments.of(
+            new SessionOptions(),
+            new TranslatorOptions()
+                .setSendPlatformInfo(false)
+                .setAppInfo("my-java-translation-plugin", "1.2.3"),
+            lightPlatformInfoWithAppInfo,
+            detailedPlatformInfo),
+        Arguments.of(
+            new SessionOptions(),
+            new TranslatorOptions()
+                .setHeaders(testHeaders)
+                .setAppInfo("my-java-translation-plugin", "1.2.3"),
+            customUserAgent,
+            detailedPlatformInfoWithAppInfo));
+  }
 }