fix: retry connection resets, drop hidden PATCH retries, and wrap download read failures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -227,8 +227,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   They will be removed in the next major version.
 
 ### Fixed
+- A connection failure while reading a downloaded document
+  (`translateDocumentDownload()`) or translation memory export
+  (`downloadTranslationMemoryExport()`) now throws `ConnectionException`
+  instead of a raw `IOException`; `IOException` is left for failures writing
+  the output.
 - A `User-Agent` header passed with `setHeaders()` now replaces the built
   `User-Agent` in any casing, e.g. `user-agent`.
+- `PATCH` requests no longer make up to 3 hidden extra attempts per try on top
+  of `maxRetries`.
+- Connection resets and broken pipes are now retried, and
+  `ConnectionException.getShouldRetry()` returns `true` for them.
 - The language query parameters of `getMultilingualGlossaryDictionaryEntries()`
   and `deleteMultilingualGlossaryDictionary()` now encode a space as `%20`
   instead of `+`.

README.md

@@ -1808,13 +1808,15 @@ invalid arguments are provided, they may raise the standard exceptions
 - `TooManyRequestsException`: HTTP 429 after all retries.
 - `QuotaExceededException`: the quota is exceeded (HTTP 456).
 - `ConnectionException`: no HTTP response was received, for example after a
-  connection, DNS or timeout failure.
+  connection, DNS or timeout failure or a connection reset, or the connection
+  failed while a downloaded document or translation memory export was being
+  read.
 - A malformed API response raises a `DeepLException`.
 
 `DeepLException.getHttpStatusCode()` returns the HTTP status code of the failed
 response, or `null` if there was none. `DeepLException.getShouldRetry()`
 returns `true` for transient errors (HTTP 429, HTTP 5xx, connection, DNS and
-timeout failures); the client has already retried these up to the configured
+timeout failures, connection resets and broken pipes); the client has already retried these up to the configured
 maximum number of retries.
 
 ### Writing a Plugin
@@ -1857,8 +1859,10 @@ The available options setters are:
 
 - `setMaxRetries()`: maximum number of failed HTTP requests to retry, the
   default is 5. Note: only failures due to transient conditions are retried:
-  HTTP 429, HTTP 5xx, and connection, DNS and timeout failures, including a
-  timeout while reading the response.
+  HTTP 429, HTTP 5xx, and connection, DNS and timeout failures, connection
+  resets and broken pipes, including a timeout while reading the response.
+  Every request, including `PATCH` requests, is sent at most `maxRetries + 1`
+  times.
 - `setTimeout()`: connection timeout for each HTTP request.
 - `setProxy()`: provide details about a proxy to use for all HTTP requests to
   DeepL, as a `java.net.Proxy`.

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

@@ -2553,7 +2553,7 @@ public void downloadTranslationMemoryExport(TranslationMemoryJob job, File outpu
    *
    * @param job Completed export job carrying the download URL.
    * @param outputStream Stream to download the exported translation memory to.
-   * @throws IOException If an I/O error occurs.
+   * @throws IOException If an I/O error occurs while writing to the output stream.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
    * @throws DeepLException If the job has no download URL, or any error occurs while downloading.
    * @see DeepLClient#downloadTranslationMemoryExport(TranslationMemoryJob, File)
@@ -2579,7 +2579,7 @@ public void downloadTranslationMemoryExport(TranslationMemoryJob job, OutputStre
             .setHttpStatusCode(response.getCode());
       }
       assert response.getBody() != null;
-      StreamUtil.transferTo(response.getBody(), outputStream);
+      HttpClientWrapper.copyBody(response.getBody(), outputStream);
     }
   }
 

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

@@ -147,7 +147,9 @@ private HttpResponse sendPatchRequestWithBackoff(String relativeUrl, HttpContent
   private HttpResponse sendPatchRequest(
       String relativeUrl, HttpContent content, BackoffTimer backoffTimer) throws DeepLException {
     // Like HttpURLConnection, honor the JVM's proxy settings unless a proxy was configured.
-    HttpClientBuilder builder = HttpClients.custom().useSystemProperties();
+    // Automatic retries are disabled so that only the backoff loop retries, up to maxRetries.
+    HttpClientBuilder builder =
+        HttpClients.custom().useSystemProperties().disableAutomaticRetries();
     if (proxy != null) {
       InetSocketAddress addr = (InetSocketAddress) proxy.address();
       builder.setProxy(new HttpHost(addr.getHostName(), addr.getPort()));
@@ -328,7 +330,7 @@ private HttpResponseStream sendRequest(
       } catch (IOException e) {
         ConnectionException failure = toConnectionException(e);
         throw new ConnectionException(
-            failure.getMessage(), failure.getShouldRetry(), e, failure.getShouldRetry());
+            failure.getMessage(), failure.getShouldRetry(), e, isUnsentFailure(e));
       }
 
       if (content != null) {
@@ -356,14 +358,50 @@ private HttpResponseStream sendRequest(
     }
   }
 
-  // Connect, DNS and timeout failures are transient: the request is retried.
+  /**
+   * Copies a streamed response body to the output stream. A failure while reading the body is a
+   * {@link ConnectionException}; a failure while writing the output stays an {@link IOException}.
+   */
+  static void copyBody(InputStream body, OutputStream outputStream)
+      throws ConnectionException, IOException {
+    final byte[] buffer = new byte[8192];
+    while (true) {
+      int read;
+      try {
+        read = body.read(buffer);
+      } catch (RuntimeException | IOException e) {
+        throw toConnectionException(e);
+      }
+      if (read < 0) {
+        return;
+      }
+      outputStream.write(buffer, 0, read);
+    }
+  }
+
+  // Connect, DNS, timeout, connection reset and broken pipe failures are transient: the request is
+  // retried.
   private static ConnectionException toConnectionException(Exception e) {
-    boolean shouldRetry =
-        e instanceof SocketTimeoutException
-            || e instanceof ConnectException
-            || e instanceof NoRouteToHostException
-            || e instanceof UnknownHostException
-            || e instanceof ConnectTimeoutException;
+    boolean shouldRetry = isUnsentFailure(e) || isConnectionResetOrBrokenPipe(e);
     return new ConnectionException(e.getMessage(), shouldRetry, e);
   }
+
+  // Failures of the connect step after which the server cannot have received the request.
+  private static boolean isUnsentFailure(Exception e) {
+    return e instanceof SocketTimeoutException
+        || e instanceof ConnectException
+        || e instanceof NoRouteToHostException
+        || e instanceof UnknownHostException
+        || e instanceof ConnectTimeoutException;
+  }
+
+  // Java has no exception types for these, only SocketException messages such as
+  // "Connection reset", "Connection reset by peer" and "Broken pipe (Write failed)".
+  private static boolean isConnectionResetOrBrokenPipe(Exception e) {
+    if (!(e instanceof SocketException) || e.getMessage() == null) {
+      return false;
+    }
+    String message = e.getMessage().toLowerCase(Locale.ROOT);
+    return message.contains("connection reset") || message.contains("broken pipe");
+  }
 }

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

@@ -652,7 +652,7 @@ public void translateDocumentDownload(DocumentHandle handle, File outputFile)
    *
    * @param handle Handle associated with document translation to download.
    * @param outputStream Stream to download translated document to.
-   * @throws IOException If an I/O error occurs.
+   * @throws IOException If an I/O error occurs while writing to the output stream.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
@@ -666,7 +666,7 @@ public void translateDocumentDownload(DocumentHandle handle, OutputStream output
     try (HttpResponseStream response = httpClientWrapper.downloadWithBackoff(relativeUrl, params)) {
       checkResponse(response);
       assert response.getBody() != null;
-      StreamUtil.transferTo(response.getBody(), outputStream);
+      HttpClientWrapper.copyBody(response.getBody(), outputStream);
     }
   }
 

deepl-java/src/offlineTest/java/com/deepl/api/HttpClientTest.java

@@ -18,8 +18,12 @@
 import com.github.tomakehurst.wiremock.http.Fault;
 import com.github.tomakehurst.wiremock.stubbing.Scenario;
 import java.net.Proxy;
+import java.net.ServerSocket;
+import java.net.Socket;
+import java.net.SocketException;
 import java.net.UnknownHostException;
 import java.time.Duration;
+import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
@@ -118,6 +122,61 @@ void throwsConnectionExceptionWhenTheConnectionIsReset() {
     assertThrows(ConnectionException.class, () -> client(0).getUsage());
   }
 
+  // A PATCH request, because HttpURLConnection silently resends a GET once after a reset.
+  @Test
+  void retriesAConnectionReset() throws Exception {
+    wm.stubFor(
+        patch(urlEqualTo("/v3/glossaries/g1"))
+            .inScenario("reset")
+            .whenScenarioStateIs(Scenario.STARTED)
+            .willSetStateTo("recovered")
+            .willReturn(aResponse().withFault(Fault.CONNECTION_RESET_BY_PEER)));
+    wm.stubFor(
+        patch(urlEqualTo("/v3/glossaries/g1"))
+            .inScenario("reset")
+            .whenScenarioStateIs("recovered")
+            .willReturn(okJson(GLOSSARY)));
+    client(1).updateMultilingualGlossaryName("g1", "n");
+    wm.verify(2, patchRequestedFor(urlEqualTo("/v3/glossaries/g1")));
+  }
+
+  // WireMock reads the whole request before failing, so a socket that resets every connection
+  // stands in for a server that drops the connection while the request body is still being sent.
+  @Test
+  void sendsAPatchRequestOnlyOnceWhenMaxRetriesIsZero() throws Exception {
+    AtomicInteger connections = new AtomicInteger();
+    try (ServerSocket server = new ServerSocket(0)) {
+      Thread acceptor =
+          new Thread(
+              () -> {
+                try {
+                  while (true) {
+                    Socket socket = server.accept();
+                    connections.incrementAndGet();
+                    socket.setSoLinger(true, 0);
+                    socket.close();
+                  }
+                } catch (Exception closed) {
+                  // the server socket was closed at the end of the test
+                }
+              });
+      acceptor.start();
+      DeepLClientOptions options =
+          new DeepLClientOptions().setServerUrl("http://127.0.0.1:" + server.getLocalPort());
+      DeepLClient resetClient = new DeepLClient("k", options.setMaxRetries(0));
+      StringBuilder longName = new StringBuilder();
+      for (int i = 0; i < 1 << 23; i++) {
+        longName.append('n');
+      }
+      ConnectionException thrown =
+          assertThrows(
+              ConnectionException.class,
+              () -> resetClient.updateMultilingualGlossaryName("g1", longName.toString()));
+      assertTrue(thrown.getCause() instanceof SocketException, thrown.toString());
+    }
+    assertEquals(1, connections.get());
+  }
+
   // A request to any host but the local server goes to the refusing proxy that the offline
   // suite configures through the JVM settings. The .invalid host never resolves, so a request
   // that ignored the proxy would fail with another message.

deepl-java/src/offlineTest/java/com/deepl/api/TranslateDocumentTest.java

@@ -20,6 +20,7 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.github.tomakehurst.wiremock.client.MappingBuilder;
+import com.github.tomakehurst.wiremock.http.Fault;
 import com.github.tomakehurst.wiremock.http.Request;
 import com.github.tomakehurst.wiremock.stubbing.Scenario;
 import com.github.tomakehurst.wiremock.stubbing.ServeEvent;
@@ -429,6 +430,16 @@ void sendsTheDocumentKeyWhenDownloadingTheResultToAFile() throws Exception {
     assertEquals("Protonenstrahl", Fixtures.readFile(output));
   }
 
+  @Test
+  void throwsConnectionExceptionWhenTheDownloadedDocumentIsCutOff() {
+    wm.stubFor(
+        post("/v2/document/D1/result")
+            .willReturn(aResponse().withFault(Fault.MALFORMED_RESPONSE_CHUNK)));
+    assertThrows(
+        ConnectionException.class,
+        () -> client.translateDocumentDownload(HANDLE_OBJECT, new ByteArrayOutputStream()));
+  }
+
   @Test
   void throwsDocumentNotReadyWhenTheResultIsNotAvailableYet() {
     wm.stubFor(post("/v2/document/D1/result").willReturn(aResponse().withStatus(503)));

deepl-java/src/offlineTest/java/com/deepl/api/TranslationMemoriesTest.java

@@ -21,6 +21,7 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import com.github.tomakehurst.wiremock.http.Fault;
 import com.github.tomakehurst.wiremock.stubbing.Scenario;
 import java.io.ByteArrayOutputStream;
 import java.io.File;
@@ -455,6 +456,16 @@ void downloadsTheExportToAStream() throws Exception {
     assertEquals((byte) 0xff, output.toByteArray()[1]);
   }
 
+  @Test
+  void throwsConnectionExceptionWhenTheExportDownloadIsCutOff() {
+    wm.stubFor(
+        get("/storage/export").willReturn(aResponse().withFault(Fault.MALFORMED_RESPONSE_CHUNK)));
+    assertThrows(
+        ConnectionException.class,
+        () ->
+            client.downloadTranslationMemoryExport(completedExport(), new ByteArrayOutputStream()));
+  }
+
   @Test
   void leavesNoFileBehindWhenTheDownloadFails() throws Exception {
     wm.stubFor(get("/storage/export").willReturn(aResponse().withStatus(500)));