Allow retry policy to handle client-side DriverTimeoutException

[dkropachev]

Problem

The Java driver currently treats client-side request timeout as a terminal failure and completes the request with DriverTimeoutException without giving the configured retry policy a chance to decide.

Example failure:

com.datastax.oss.driver.api.core.DriverTimeoutException: Query timed out after PT30M
    at com.datastax.oss.driver.internal.core.cql.CqlRequestHandler.lambda$scheduleTimeout$1(CqlRequestHandler.java:258)

This timeout is produced by the driver's request timer. It is different from server-side ReadTimeoutException / WriteTimeoutException, which already go through retry policy callbacks.

In Scylla Migrator / Spark connector reads, this means a long source scan can fail on either:

• the initial query request
• a later paged request through AsyncResultSet.fetchNextPage()

and the connector cannot rely on the driver's configured retry policy to handle it.

Current behavior

CqlRequestHandler.scheduleTimeout schedules a timeout task and fails the request directly with DriverTimeoutException when basic.request.timeout expires.

The configured retry policy is not consulted for this failure path.

Requested behavior

Make it possible for a retry policy to handle client-side request timeouts.

Possible API shape:

• add a retry-policy callback for client-side request timeout, for example onRequestTimeout(...)
• or route DriverTimeoutException through an existing/new retry-policy decision path
• include enough context for safe decisions: statement, idempotence, retry count, consistency, current node/errors if available
• preserve current behavior by default: default policy should not retry client-side request timeouts unless explicitly configured

Important safety point: client-side timeout does not prove the server did not execute the request. For non-idempotent statements, automatic retry can duplicate effects. The API should allow policies to reject retries for non-idempotent statements by default.

Why this is needed

Higher-level clients such as the Spark connector can add their own retry wrappers, but that duplicates driver retry logic and cannot reuse the configured driver retry policy. It is cleaner if the driver exposes a first-class retry-policy hook for this timeout class.

The Spark connector still needs connector-level handling for paged reads, but the driver should make DriverTimeoutException retryable by policy where safe.

Acceptance criteria

• Retry policy can make a decision for client-side request timeout / DriverTimeoutException.
• Default behavior remains backward-compatible: no automatic retry unless policy chooses it.
• The decision receives retry count and statement idempotence information.
• Tests cover retry and no-retry cases for client-side request timeout.
• Documentation explains the difference between server-side timeout responses and client-side driver request timeout.

Related

• Retry client-side DriverTimeoutException for first-page and paged read requests spark-scylladb-connector#117
• Expose and use connector retries for client-side DriverTimeoutException during reads scylla-migrator#399
• Getting timeout from scylla migrator if system is configured with ipv6 scylla-migrator#61