feat(tracing): add request/response handlers

Add Handlers class with 4 lifecycle callbacks:
- onBeforeSend: called before sending request
- onSuccess: called on successful response
- onTimeout: called when request times out
- onIgnoredResponse: called when response arrives after timeout

Handlers are configured at client level via withHandlers() builder method
and propagated through: Builder -> ClientImpl -> Pool -> PoolEntry -> IProtoClient

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

Author: ArtDu

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolBoxClientBuilder.java

@@ -34,6 +34,7 @@
 import io.tarantool.client.box.TarantoolBoxClient;
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -159,6 +160,9 @@ public class TarantoolBoxClientBuilder {
   /** Optional listener for pool events. */
   private PoolEventListener poolEventListener;
 
+  /** Custom handlers for protocol operations. */
+  private Handlers handlers;
+
   /**
    * Getter for {@link #options}.
    *
@@ -819,6 +823,17 @@ public TarantoolBoxClientBuilder withPoolEventListener(PoolEventListener listene
     return this;
   }
 
+  /**
+   * Sets custom handlers for protocol operations.
+   *
+   * @param handlers handlers instance
+   * @return {@link TarantoolBoxClientBuilder} object.
+   */
+  public TarantoolBoxClientBuilder withHandlers(Handlers handlers) {
+    this.handlers = handlers;
+    return this;
+  }
+
   /**
    * Builds specific {@link TarantoolBoxClient} class instance with parameters.
    *
@@ -859,6 +874,7 @@ public TarantoolBoxClient build() throws Exception {
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         poolEventListener);
   }

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolBoxClientImpl.java

@@ -23,6 +23,7 @@
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
 import io.tarantool.core.exceptions.ClientException;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -119,6 +120,7 @@ final class TarantoolBoxClientImpl extends TarantoolClientImpl implements Tarant
       long reconnectAfter,
       MeterRegistry metricsRegistry,
       TripleConsumer<String, Integer, IProtoResponse> ignoredPacketsHandler,
+      Handlers handlers,
       SslContext sslContext,
       PoolEventListener poolEventListener)
       throws InvocationTargetException,
@@ -138,6 +140,7 @@ final class TarantoolBoxClientImpl extends TarantoolClientImpl implements Tarant
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         !fetchSchema,
         poolEventListener);

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolClientImpl.java

@@ -33,6 +33,7 @@
 import io.tarantool.core.WatcherOptions;
 import io.tarantool.core.connection.ConnectionFactory;
 import io.tarantool.core.exceptions.ServerException;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoRequestOpts;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.mapping.TarantoolJacksonMapping;
@@ -94,6 +95,7 @@ abstract class TarantoolClientImpl implements TarantoolClient {
    * @param reconnectAfter time after which reconnect occurs
    * @param metricsRegistry micrometer {@link TarantoolClientImpl#metricsRegistry}
    * @param ignoredPacketsHandler handler for ignored IProto-packets.
+   * @param handlers handlers for request/response lifecycle events.
    * @param sslContext SslContext with settings for establishing SSL/TLS connection between
    *     Tarantool.
    * @param useTupleExtension Use TUPLE_EXT feature if true.
@@ -123,6 +125,7 @@ protected TarantoolClientImpl(
       long reconnectAfter,
       MeterRegistry metricsRegistry,
       TripleConsumer<String, Integer, IProtoResponse> ignoredPacketsHandler,
+      Handlers handlers,
       SslContext sslContext,
       boolean useTupleExtension,
       PoolEventListener poolEventListener)
@@ -144,6 +147,7 @@ protected TarantoolClientImpl(
             watcherOpts,
             this.metricsRegistry,
             ignoredPacketsHandler,
+            handlers,
             useTupleExtension,
             poolEventListener);
     pool.setGroups(groups);

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolCrudClientBuilder.java

@@ -33,6 +33,7 @@
 import io.tarantool.client.crud.TarantoolCrudClient;
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -148,6 +149,8 @@ public class TarantoolCrudClientBuilder {
   /** Optional listener for pool lifecycle events. */
   private PoolEventListener poolEventListener;
 
+  private Handlers handlers;
+
   public Map<ChannelOption<?>, Object> getOptions() {
     return options;
   }
@@ -762,6 +765,11 @@ public TarantoolCrudClientBuilder withPoolEventListener(PoolEventListener listen
     return this;
   }
 
+  public TarantoolCrudClientBuilder withHandlers(Handlers handlers) {
+    this.handlers = handlers;
+    return this;
+  }
+
   /**
    * Builds specific {@link TarantoolCrudClient} class instance with parameters.
    *
@@ -800,6 +808,7 @@ public TarantoolCrudClient build() throws Exception {
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         useTupleExtension,
         poolEventListener);

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolCrudClientImpl.java

@@ -20,6 +20,7 @@
 import io.tarantool.client.crud.options.CrudOptions;
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -70,6 +71,7 @@ final class TarantoolCrudClientImpl extends TarantoolClientImpl implements Taran
    * @param reconnectAfter see reconnectAfter in{@link TarantoolCrudClientBuilder}.
    * @param metricsRegistry see metricsRegistry in{@link TarantoolCrudClientBuilder}.
    * @param ignoredPacketsHandler see ignoredPacketsHandler in{@link TarantoolCrudClientBuilder}.
+   * @param handlers see handlers in{@link TarantoolCrudClientBuilder}.
    * @param sslContext see sslContext in{@link TarantoolCrudClientBuilder}.
    * @param useTupleExtension see useTupleExtension in{@link TarantoolCrudClientBuilder}.
    * @throws NoSuchMethodException if a matching method is not found.
@@ -96,6 +98,7 @@ final class TarantoolCrudClientImpl extends TarantoolClientImpl implements Taran
       long reconnectAfter,
       MeterRegistry metricsRegistry,
       TripleConsumer<String, Integer, IProtoResponse> ignoredPacketsHandler,
+      Handlers handlers,
       SslContext sslContext,
       boolean useTupleExtension,
       PoolEventListener poolEventListener)
@@ -116,6 +119,7 @@ final class TarantoolCrudClientImpl extends TarantoolClientImpl implements Taran
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         useTupleExtension,
         poolEventListener);

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolDataGridClientBuilder.java

@@ -33,6 +33,7 @@
 import io.tarantool.client.tdg.TarantoolDataGridClient;
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -158,6 +159,9 @@ public class TarantoolDataGridClientBuilder {
   /** Optional listener for pool lifecycle events. */
   private PoolEventListener poolEventListener;
 
+  /** Handlers for protocol messages. */
+  private Handlers handlers;
+
   public Map<ChannelOption<?>, Object> getOptions() {
     return options;
   }
@@ -840,6 +844,17 @@ public TarantoolDataGridClientBuilder withCredentials(Map<String, Object> creden
     return this;
   }
 
+  /**
+   * Sets the {@link #handlers} parameter when constructing an instance of a builder class.
+   *
+   * @param handlers see {@link #handlers} field.
+   * @return {@link TarantoolDataGridClientBuilder} object.
+   */
+  public TarantoolDataGridClientBuilder withHandlers(Handlers handlers) {
+    this.handlers = handlers;
+    return this;
+  }
+
   /**
    * Builds specific {@link TarantoolDataGridClient} class instance with parameters.
    *
@@ -878,6 +893,7 @@ public TarantoolDataGridClient build() throws Exception {
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         useTupleExtension,
         useTdg1Context,

tarantool-client/src/main/java/io/tarantool/client/factory/TarantoolDataGridClientImpl.java

@@ -19,6 +19,7 @@
 import io.tarantool.client.tdg.TarantoolDataGridSpace;
 import io.tarantool.core.ManagedResource;
 import io.tarantool.core.WatcherOptions;
+import io.tarantool.core.protocol.Handlers;
 import io.tarantool.core.protocol.IProtoResponse;
 import io.tarantool.pool.HeartbeatOpts;
 import io.tarantool.pool.InstanceConnectionGroup;
@@ -70,6 +71,7 @@ protected TarantoolDataGridClientImpl(
       long reconnectAfter,
       MeterRegistry metricsRegistry,
       TripleConsumer<String, Integer, IProtoResponse> ignoredPacketsHandler,
+      Handlers handlers,
       SslContext sslContext,
       boolean useTupleExtension,
       boolean useTdg1Context,
@@ -92,6 +94,7 @@ protected TarantoolDataGridClientImpl(
         reconnectAfter,
         metricsRegistry,
         ignoredPacketsHandler,
+        handlers,
         sslContext,
         useTupleExtension,
         poolEventListener);