Allow retry policies to handle client-side request timeouts

changelog/README.md

@@ -23,6 +23,7 @@ under the License.
 
 ### 4.19.2
 
+- [improvement] #958: Allow retry policies to handle client-side request timeouts
 - [bug] CASSJAVA-116: Retry or Speculative Execution with RequestIdGenerator throws "Duplicate Key"
 
 ### 4.19.1

core/revapi.json

@@ -14,6 +14,11 @@
       }
     },
     "ignore": [
+      {
+        "code": "java.method.addedToInterface",
+        "new": "method com.datastax.oss.driver.api.core.retry.RetryVerdict com.datastax.oss.driver.api.core.retry.RetryPolicy::onRequestTimeoutVerdict(com.datastax.oss.driver.api.core.session.Request, com.datastax.oss.driver.api.core.ConsistencyLevel, com.datastax.oss.driver.api.core.DriverTimeoutException, boolean, int)",
+        "justification": "#958: Expose a dedicated callback for client-side request timeouts"
+      },
       {
         "code": "java.method.removed",
         "old": "method com.datastax.oss.driver.api.core.cql.BatchStatementBuilder com.datastax.oss.driver.api.core.cql.BatchStatementBuilder::withKeyspace(com.datastax.oss.driver.api.core.CqlIdentifier)",

core/src/main/java/com/datastax/oss/driver/api/core/retry/RetryPolicy.java

@@ -18,6 +18,7 @@
 package com.datastax.oss.driver.api.core.retry;
 
 import com.datastax.oss.driver.api.core.ConsistencyLevel;
+import com.datastax.oss.driver.api.core.DriverTimeoutException;
 import com.datastax.oss.driver.api.core.connection.ClosedConnectionException;
 import com.datastax.oss.driver.api.core.connection.HeartbeatException;
 import com.datastax.oss.driver.api.core.loadbalancing.LoadBalancingPolicy;
@@ -216,6 +217,39 @@ default RetryVerdict onUnavailableVerdict(
     return () -> decision;
   }
 
+  /**
+   * Whether to retry when the driver did not receive a response before the client-side request
+   * timeout expired.
+   *
+   * <p>This is different from {@link #onReadTimeoutVerdict(Request, ConsistencyLevel, int, int,
+   * boolean, int)} and {@link #onWriteTimeoutVerdict(Request, ConsistencyLevel, WriteType, int,
+   * int, int)}: those methods handle server-side timeout responses returned by a coordinator, while
+   * this method handles a timeout raised by the driver itself.
+   *
+   * <p>Since a client-side timeout does not prove that the coordinator failed to execute the
+   * request, policies should only retry when {@code requestIdempotent} is {@code true}, unless
+   * duplicate execution is explicitly acceptable for the request.
+   *
+   * <p>If this method returns a retry verdict, the driver starts a new attempt and schedules the
+   * client-side request timeout again for the retried request.
+   *
+   * @param request the request that timed out.
+   * @param cl the requested consistency level.
+   * @param error the timeout raised by the driver.
+   * @param requestIdempotent the request idempotence, resolved from {@link Request#isIdempotent()}
+   *     and the configured default.
+   * @param retryCount how many times the retry policy has been invoked already for this request
+   *     (not counting the current invocation).
+   */
+  default RetryVerdict onRequestTimeoutVerdict(
+      @NonNull Request request,
+      @NonNull ConsistencyLevel cl,
+      @NonNull DriverTimeoutException error,
+      boolean requestIdempotent,
+      int retryCount) {
+    return RetryVerdict.RETHROW;
+  }
+
   /**
    * Whether to retry when a request was aborted before we could get a response from the server.
    *