feat(tracing): add request/response lifecycle 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);

tarantool-client/src/test/java/io/tarantool/client/integration/TarantoolBoxClientTest.java

@@ -44,11 +44,19 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
+import org.msgpack.core.MessageBufferPacker;
+import org.msgpack.core.MessagePack;
+import org.msgpack.core.MessageUnpacker;
+import org.msgpack.value.Value;
+import org.msgpack.value.ValueFactory;
 import org.testcontainers.containers.tarantool.TarantoolContainer;
 import org.testcontainers.containers.utils.TarantoolContainerClientHelper;
 import org.testcontainers.shaded.com.google.common.base.CaseFormat;
 
 import static io.tarantool.client.box.TarantoolBoxSpace.WITHOUT_ENABLED_FETCH_SCHEMA_OPTION_FOR_TARANTOOL_LESS_3_0_0;
+import static io.tarantool.core.protocol.requests.IProtoConstant.IPROTO_DATA;
+import static io.tarantool.core.protocol.requests.IProtoConstant.IPROTO_SYNC_ID;
+import static io.tarantool.core.protocol.requests.IProtoConstant.IPROTO_TYPE_CALL;
 import static io.tarantool.mapping.BaseTarantoolJacksonMapping.objectMapper;
 import io.tarantool.client.BaseOptions;
 import io.tarantool.client.ClientType;
@@ -64,7 +72,11 @@
 import io.tarantool.client.operation.Operations;
 import io.tarantool.core.IProtoClient;
 import io.tarantool.core.protocol.BoxIterator;
+import io.tarantool.core.protocol.ByteBodyValueWrapper;
+import io.tarantool.core.protocol.Handlers;
+import io.tarantool.core.protocol.IProtoRequest;
 import io.tarantool.core.protocol.IProtoResponse;
+import io.tarantool.mapping.BaseTarantoolJacksonMapping;
 import io.tarantool.mapping.NilErrorResponse;
 import io.tarantool.mapping.SelectResponse;
 import io.tarantool.mapping.TarantoolResponse;
@@ -250,25 +262,113 @@ public void testCallAndEval() {
 
   @Test
   public void testCallTimeoutWithIgnoredPacketsHandler() throws Exception {
+    List<IProtoRequest> timedOutRequests = new ArrayList<>();
+    List<List<Object>> localTriplets = new ArrayList<>();
+
+    TarantoolBoxClient testClient =
+        TarantoolFactory.box()
+            .withUser(API_USER)
+            .withPassword(CREDS.get(API_USER))
+            .withHost(tt.getHost())
+            .withPort(tt.getFirstMappedPort())
+            .withHandlers(
+                Handlers.builder()
+                    .onTimeout(
+                        request -> {
+                          synchronized (timedOutRequests) {
+                            timedOutRequests.add(request);
+                          }
+                        })
+                    .build())
+            .withIgnoredPacketsHandler(
+                (tag, index, packet) -> {
+                  synchronized (localTriplets) {
+                    localTriplets.add(Arrays.asList(tag, index, packet));
+                  }
+                })
+            .build();
+
     Options options = BaseOptions.builder().withTimeout(1_000L).build();
     Exception ex =
         assertThrows(
             CompletionException.class,
-            () -> client.call("slow_echo", Arrays.asList(1, true), options).join());
+            () -> testClient.call("slow_echo", Arrays.asList(1, true), options).join());
     Throwable cause = ex.getCause();
     assertEquals(TimeoutException.class, cause.getClass());
     Thread.sleep(600);
-    assertEquals(1, triplets.size());
+    assertEquals(1, localTriplets.size());
+
+    // Verify timeout handler and ignored packets have matching syncId
+    long requestSyncId = assertTimeoutHandler(timedOutRequests);
+    long responseSyncId = assertIgnoredPackets(localTriplets);
+    assertEquals(requestSyncId, responseSyncId, "Request and response syncId should match");
 
+    testClient.close();
+  }
+
+  private long assertTimeoutHandler(List<IProtoRequest> timedOutRequests) throws Exception {
+    assertEquals(1, timedOutRequests.size());
+    IProtoRequest timedOutRequest = timedOutRequests.get(0);
+    assertEquals(IPROTO_TYPE_CALL, timedOutRequest.getRequestType());
+
+    byte[] packetBytes = timedOutRequest.getPacket(MessagePack.newDefaultBufferPacker());
+    MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(packetBytes);
+    unpacker.unpackInt(); // Skip size prefix
+
+    Value headerValue = unpacker.unpackValue();
+    Value bodyValue = unpacker.unpackValue();
+
+    // Extract syncId from header (key 0x01)
+    long syncId =
+        headerValue
+            .asMapValue()
+            .map()
+            .get(ValueFactory.newInteger(IPROTO_SYNC_ID))
+            .asIntegerValue()
+            .asLong();
+
+    // Convert body to bytes and parse with objectMapper
+    MessageBufferPacker packer = MessagePack.newDefaultBufferPacker();
+    packer.packValue(bodyValue);
+    byte[] bodyBytes = packer.toByteArray();
+    Map<Integer, Object> body =
+        objectMapper.readValue(bodyBytes, new TypeReference<Map<Integer, Object>>() {});
+
+    assertEquals("slow_echo", body.get(0x22)); // IPROTO_FUNCTION_NAME
+    assertEquals(Arrays.asList(1, true), body.get(0x21)); // IPROTO_TUPLE
+
+    return syncId;
+  }
+
+  private long assertIgnoredPackets(List<List<Object>> triplets) throws Exception {
     Set<String> tags = new HashSet<>();
     Set<Integer> indexes = new HashSet<>();
+    long syncId = -1;
+
     for (List<Object> item : triplets) {
       tags.add((String) item.get(0));
       indexes.add((int) item.get(1));
       assertInstanceOf(IProtoResponse.class, item.get(2));
+      IProtoResponse response = (IProtoResponse) item.get(2);
+      assertFalse(response.isError());
+      assertTrue(response.hasSyncId());
+      syncId = response.getSyncId();
+      assertTrue(syncId > 0);
+
+      Map<Integer, Object> bodyAsObjects = new HashMap<>();
+      Map<Integer, ByteBodyValueWrapper> byteBodyValues = response.getByteBodyValues();
+      for (Map.Entry<Integer, ByteBodyValueWrapper> entry : byteBodyValues.entrySet()) {
+        bodyAsObjects.put(
+            entry.getKey(), BaseTarantoolJacksonMapping.readValue(entry.getValue(), Object.class));
+      }
+      assertEquals(byteBodyValues.size(), bodyAsObjects.size());
+      assertEquals(Arrays.asList(1, true), bodyAsObjects.get(IPROTO_DATA));
     }
+
     assertEquals(new HashSet<>(Collections.singletonList("default")), tags);
     assertEquals(Collections.singleton(0), indexes);
+
+    return syncId;
   }
 
   @Test