feat(timeout): add timeout handler callback for requests

Add Consumer<IProtoRequest> timeout handler that is called when a request
times out. This allows users to track which requests timed out and handle
them appropriately.

Changes:
- Add timeoutHandler field and getter to Options interface
- Add withTimeoutHandler() builder method to BaseOptions
- Add timeoutHandler support to all Options implementations
- Add withTimeoutHandler() to IProtoRequestOpts
- Call timeoutHandler in RequestStateMachine before killing the request
- Update TarantoolClientImpl to propagate timeoutHandler
- Add test for timeout handler with syncId verification

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

Author: ArtDu

tarantool-client/src/main/java/io/tarantool/client/BaseOptions.java

@@ -5,6 +5,10 @@
 
 package io.tarantool.client;
 
+import java.util.function.Consumer;
+
+import io.tarantool.core.protocol.IProtoRequest;
+
 /**
  * The class implements base options for operations.
  *
@@ -34,16 +38,25 @@ public class BaseOptions implements Options {
    */
   private final Long streamId;
 
+  /**
+   * Timeout handler for operation.
+   *
+   * <p>Default value: null.
+   */
+  private final Consumer<IProtoRequest> timeoutHandler;
+
   /**
    * This constructor creates options based on the passed parameters.
    *
    * @param timeout see also: {@link #timeout}.
    * @param streamId see also: {@link #streamId}.
+   * @param timeoutHandler see also: {@link #timeoutHandler}.
    * @see BaseOptions.Builder#build()
    */
-  protected BaseOptions(long timeout, Long streamId) {
+  protected BaseOptions(long timeout, Long streamId, Consumer<IProtoRequest> timeoutHandler) {
     this.timeout = timeout;
     this.streamId = streamId;
+    this.timeoutHandler = timeoutHandler;
   }
 
   /**
@@ -74,6 +87,16 @@ public Long getStreamId() {
     return this.streamId;
   }
 
+  /**
+   * Returns timeout handler for operation.
+   *
+   * @return null - if {@link BaseOptions#timeoutHandler} is null, otherwise - {@link
+   *     BaseOptions#timeoutHandler} value.
+   */
+  public Consumer<IProtoRequest> getTimeoutHandler() {
+    return this.timeoutHandler;
+  }
+
   /** A specific builder for {@link BaseOptions} class. */
   public static class Builder {
 
@@ -87,6 +110,11 @@ public static class Builder {
      */
     private Long streamId;
 
+    /**
+     * @see BaseOptions#timeoutHandler
+     */
+    private Consumer<IProtoRequest> timeoutHandler;
+
     /**
      * Sets the {@link BaseOptions#timeout} parameter (in milliseconds) when constructing an
      * instance of a builder class. The following example creates a {@link BaseOptions} object with
@@ -161,13 +189,38 @@ public Builder withStreamId(long streamId) {
       return this;
     }
 
+    /**
+     * Sets the {@link BaseOptions#timeoutHandler} parameter when constructing an instance of a
+     * builder class. The following example creates a {@link BaseOptions} object with a specified
+     * {@link BaseOptions#timeoutHandler} parameter:
+     *
+     * <pre>{@code
+     * BaseOptions options = BaseOptions
+     *                               .builder()
+     *                               .withTimeoutHandler(request -> {
+     *                                   System.out.println("Request timed out: " + request);
+     *                               })   // OK!
+     *                               .build();
+     *
+     *
+     *
+     * }</pre>
+     *
+     * @param timeoutHandler see {@link BaseOptions#timeoutHandler} field.
+     * @return {@link BaseOptions.Builder} object.
+     */
+    public Builder withTimeoutHandler(Consumer<IProtoRequest> timeoutHandler) {
+      this.timeoutHandler = timeoutHandler;
+      return this;
+    }
+
     /**
      * Builds specific {@link BaseOptions} class instance with parameters.
      *
      * @return {@link BaseOptions} object.
      */
     public BaseOptions build() {
-      return new BaseOptions(timeout, streamId);
+      return new BaseOptions(timeout, streamId, timeoutHandler);
     }
   }
 }

tarantool-client/src/main/java/io/tarantool/client/OnlyKeyValueOptions.java

@@ -8,10 +8,13 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.function.Consumer;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import io.tarantool.core.protocol.IProtoRequest;
+
 /** TODO: Rename this class to a more elegant name. */
 public class OnlyKeyValueOptions implements OptionsMap {
 
@@ -45,19 +48,28 @@ public class OnlyKeyValueOptions implements OptionsMap {
   /** A map containing the correspondence between option names and their meanings. */
   private final Map<String, Object> options;
 
+  /**
+   * Timeout handler for operation.
+   *
+   * <p>Default value: null.
+   */
+  private final Consumer<IProtoRequest> timeoutHandler;
+
   /**
    * Creates a {@link OnlyKeyValueOptions} object with the given parameters.
    *
    * @param timeout {@link #timeout}
    * @param streamId {@link #streamId}
+   * @param timeoutHandler {@link #timeoutHandler}
    * @param options {@link #options}
    * @see OnlyKeyValueOptions
    */
-  public OnlyKeyValueOptions(Long timeout, Long streamId, Map<String, Object> options) {
+  public OnlyKeyValueOptions(Long timeout, Long streamId, Consumer<IProtoRequest> timeoutHandler, Map<String, Object> options) {
     this.options = options;
 
     this.timeout = timeout;
     this.streamId = streamId;
+    this.timeoutHandler = timeoutHandler;
   }
 
   /**
@@ -99,6 +111,16 @@ public Map<String, Object> getOptions() {
     return Collections.unmodifiableMap(options);
   }
 
+  /**
+   * Returns timeout handler for operation.
+   *
+   * @return null - if {@link #timeoutHandler} is null, otherwise - {@link #timeoutHandler} value.
+   */
+  @Override
+  public Consumer<IProtoRequest> getTimeoutHandler() {
+    return this.timeoutHandler;
+  }
+
   /**
    * Builder class for {@link OnlyKeyValueOptions}.
    *
@@ -115,6 +137,9 @@ public static class Builder {
     /** See also: {@link OnlyKeyValueOptions#streamId}. */
     private Long streamId;
 
+    /** See also: {@link OnlyKeyValueOptions#timeoutHandler}. */
+    private Consumer<IProtoRequest> timeoutHandler;
+
     /**
      * Sets value of {@link #timeout} option. Timeout parameter should be greater than 0.
      *
@@ -179,14 +204,26 @@ public Builder withOption(String optionName, Object optionValue) {
       return this;
     }
 
+    /**
+     * Sets the {@link OnlyKeyValueOptions#timeoutHandler} parameter when constructing an instance of a
+     * builder class.
+     *
+     * @param timeoutHandler see {@link OnlyKeyValueOptions#timeoutHandler} field.
+     * @return {@link OnlyKeyValueOptions.Builder} object.
+     */
+    public Builder withTimeoutHandler(Consumer<IProtoRequest> timeoutHandler) {
+      this.timeoutHandler = timeoutHandler;
+      return this;
+    }
+
     /**
      * Builds object of {@link OnlyKeyValueOptions} class.
      *
      * @return {@link OnlyKeyValueOptions} object
      * @see OnlyKeyValueOptions
      */
     public OnlyKeyValueOptions build() {
-      return new OnlyKeyValueOptions(timeout, streamId, options);
+      return new OnlyKeyValueOptions(timeout, streamId, timeoutHandler, options);
     }
   }
 }

tarantool-client/src/main/java/io/tarantool/client/Options.java

@@ -5,6 +5,10 @@
 
 package io.tarantool.client;
 
+import java.util.function.Consumer;
+
+import io.tarantool.core.protocol.IProtoRequest;
+
 /**
  * Provides a contract for basic client options.
  *
@@ -26,4 +30,11 @@ public interface Options {
    * @return null - if stream id is null, otherwise - stream id value.
    */
   Long getStreamId();
+
+  /**
+   * Returns timeout handler for operation.
+   *
+   * @return null - if timeout handler is not set, otherwise - timeout handler.
+   */
+  Consumer<IProtoRequest> getTimeoutHandler();
 }

tarantool-client/src/main/java/io/tarantool/client/box/options/DeleteOptions.java

@@ -6,11 +6,13 @@
 package io.tarantool.client.box.options;
 
 import java.util.List;
+import java.util.function.Consumer;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 
 import io.tarantool.client.box.TarantoolBoxClient;
 import io.tarantool.client.box.TarantoolBoxSpace;
+import io.tarantool.core.protocol.IProtoRequest;
 
 /**
  * The class implements options for the delete operation of the {@link TarantoolBoxClient
@@ -68,18 +70,27 @@ public class DeleteOptions implements OptionsWithIndex {
   /** Name of the index. */
   private final String indexName;
 
+  /**
+   * Timeout handler for operation.
+   *
+   * <p>Default value: null.
+   */
+  private final Consumer<IProtoRequest> timeoutHandler;
+
   /**
    * Creates options based on the passed parameters.
    *
    * @param timeout see also: {@link DeleteOptions#timeout}.
    * @param streamId see also: {@link DeleteOptions#streamId}.
+   * @param timeoutHandler see also: {@link DeleteOptions#timeoutHandler}.
    * @param indexId see also: {@link DeleteOptions#indexId}.
    * @param indexName see also: {@link DeleteOptions#indexName}.
    * @see Builder#build()
    */
-  private DeleteOptions(long timeout, Long streamId, int indexId, String indexName) {
+  private DeleteOptions(long timeout, Long streamId, Consumer<IProtoRequest> timeoutHandler, int indexId, String indexName) {
     this.timeout = timeout;
     this.streamId = streamId;
+    this.timeoutHandler = timeoutHandler;
     this.indexId = indexId;
     this.indexName = indexName;
   }
@@ -130,6 +141,16 @@ public String getIndexName() {
     return indexName;
   }
 
+  /**
+   * Returns timeout handler for operation.
+   *
+   * @return null - if {@link DeleteOptions#timeoutHandler} is null, otherwise - {@link
+   *     DeleteOptions#timeoutHandler} value.
+   */
+  public Consumer<IProtoRequest> getTimeoutHandler() {
+    return this.timeoutHandler;
+  }
+
   /** A specific builder for {@link DeleteOptions} class. */
   public static class Builder {
 
@@ -153,6 +174,11 @@ public static class Builder {
      */
     private String indexName;
 
+    /**
+     * @see DeleteOptions#timeoutHandler
+     */
+    private Consumer<IProtoRequest> timeoutHandler;
+
     /**
      * Sets the {@link DeleteOptions#timeout} parameter (in milliseconds) when constructing an
      * instance of a builder class. The following example creates a {@link DeleteOptions} object
@@ -311,13 +337,25 @@ public Builder withIndex(String indexName) {
       return this;
     }
 
+    /**
+     * Sets the {@link DeleteOptions#timeoutHandler} parameter when constructing an instance of a
+     * builder class.
+     *
+     * @param timeoutHandler see {@link DeleteOptions#timeoutHandler} field.
+     * @return {@link DeleteOptions.Builder} object.
+     */
+    public Builder withTimeoutHandler(Consumer<IProtoRequest> timeoutHandler) {
+      this.timeoutHandler = timeoutHandler;
+      return this;
+    }
+
     /**
      * Builds specific {@link DeleteOptions} class instance with parameters.
      *
      * @return {@link DeleteOptions} object.
      */
     public DeleteOptions build() {
-      return new DeleteOptions(timeout, streamId, indexId, indexName);
+      return new DeleteOptions(timeout, streamId, timeoutHandler, indexId, indexName);
     }
   }
 }