Add exception handler on HTTP/2 parent channel to suppress WARN logs

In HTTP/2, reactor-netty multiplexes streams on a shared parent TCP connection.
The parent channel pipeline has no ChannelOperationsHandler (unlike HTTP/1.1),
so TCP-level exceptions like Connection reset by peer (ECONNRESET) propagate to
Netty's TailContext, which logs them as WARN.

This adds Http2ParentChannelExceptionHandler to the parent channel via
doOnConnected (accessing channel.parent()). The handler consumes exceptions
at DEBUG level WITHOUT closing the channel or altering connection lifecycle,
matching HTTP/1.1 logging behavior.

Changes:
- Handler logs cause.toString() (not getMessage()) for null-safe diagnostics
- Defensive try-catch for duplicate handler name on concurrent stream creation
- Before/after verified with EmbeddedChannel unit tests

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jeet1995

sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/http/Http2ParentChannelExceptionHandlerTest.java

@@ -0,0 +1,86 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.cosmos.implementation.http;
+
+import io.netty.channel.embedded.EmbeddedChannel;
+import org.testng.annotations.Test;
+
+import java.io.IOException;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Verifies that {@link Http2ParentChannelExceptionHandler} consumes exceptions
+ * on the HTTP/2 parent channel, preventing the Netty WARN log
+ * "An exceptionCaught() event was fired, and it reached at the tail of the pipeline".
+ *
+ * Uses Netty's {@link EmbeddedChannel} which records unhandled exceptions internally.
+ * {@code checkException()} re-throws any exception that reached the pipeline tail.
+ */
+public class Http2ParentChannelExceptionHandlerTest {
+
+    /**
+     * BEFORE fix — without the handler, exceptions reach the pipeline tail.
+     * EmbeddedChannel's checkException() re-throws the unhandled exception,
+     * proving it reached Netty's TailContext (which in production logs as WARN).
+     */
+    @Test(groups = "unit")
+    public void withoutHandler_exceptionReachesTail() {
+        EmbeddedChannel channel = new EmbeddedChannel();
+
+        channel.pipeline().fireExceptionCaught(
+            new IOException("Connection reset by peer"));
+
+        assertThatThrownBy(channel::checkException)
+            .isInstanceOf(IOException.class)
+            .hasMessageContaining("Connection reset by peer");
+
+        channel.finishAndReleaseAll();
+    }
+
+    /**
+     * AFTER fix — with the handler installed, exceptions are consumed at DEBUG
+     * level. checkException() does NOT throw, proving the exception never reached
+     * the pipeline tail.
+     */
+    @Test(groups = "unit")
+    public void withHandler_exceptionConsumedAndChannelStaysOpen() {
+        EmbeddedChannel channel = new EmbeddedChannel(
+            new Http2ParentChannelExceptionHandler());
+
+        channel.pipeline().fireExceptionCaught(
+            new IOException("Connection reset by peer"));
+
+        // Exception consumed — does NOT reach tail
+        channel.checkException();
+
+        // Channel is NOT closed — handler does not alter lifecycle
+        assertThat(channel.isOpen()).isTrue();
+
+        channel.finishAndReleaseAll();
+    }
+
+    /**
+     * NativeIoException is the actual exception type seen in production.
+     * Verify RuntimeException subclasses are also consumed (NativeIoException
+     * extends RuntimeException, not IOException).
+     */
+    @Test(groups = "unit")
+    public void withHandler_runtimeExceptionAlsoConsumed() {
+        EmbeddedChannel channel = new EmbeddedChannel(
+            new Http2ParentChannelExceptionHandler());
+
+        channel.pipeline().fireExceptionCaught(
+            new RuntimeException("recvAddress(..) failed with error(-104): Connection reset by peer"));
+
+        // Exception consumed
+        channel.checkException();
+
+        // Channel stays open
+        assertThat(channel.isOpen()).isTrue();
+
+        channel.finishAndReleaseAll();
+    }
+}

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -7,7 +7,8 @@
 #### Breaking Changes
 
 #### Bugs Fixed
-Fixing an NPE caused due to boxed Boolean conversion. - See [PR 48656](https://github.com/Azure/azure-sdk-for-java/pull/48656/)
+* Fixing an NPE caused due to boxed Boolean conversion. - See [PR 48656](https://github.com/Azure/azure-sdk-for-java/pull/48656/)
+* Fixed Netty WARN log "An exceptionCaught() event was fired, and it reached at the tail of the pipeline" appearing on HTTP/2 connections when the server resets idle TCP connections. Added an exception handler on the HTTP/2 parent channel to consume connection-level exceptions at DEBUG level, matching HTTP/1.1 behavior.
 
 #### Other Changes
 

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/http/Http2ParentChannelExceptionHandler.java

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.cosmos.implementation.http;
+
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.ChannelInboundHandlerAdapter;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Exception handler for the HTTP/2 parent (TCP) channel pipeline.
+ * <p>
+ * In HTTP/2, reactor-netty multiplexes streams on a shared parent TCP connection.
+ * Child stream channels have {@code ChannelOperationsHandler} which catches exceptions
+ * and fails the active subscriber (matching HTTP/1.1 behavior). However, the parent
+ * channel has no such handler — exceptions propagate to Netty's {@code TailContext}
+ * which logs them as WARN ("An exceptionCaught() event was fired, and it reached at
+ * the tail of the pipeline").
+ * <p>
+ * This handler is installed on the parent channel to consume those exceptions at
+ * DEBUG level, aligning the logging behavior with HTTP/1.1. It does NOT close the
+ * channel or alter connection lifecycle — reactor-netty and the connection pool's
+ * eviction predicate ({@code !channel.isActive()}) handle that independently.
+ * <ul>
+ *   <li>{@code NativeIoException: recvAddress(..) failed with error(-104)} — TCP RST
+ *       from server-side idle timeout, load balancer recycling, or network interruption</li>
+ *   <li>{@code IOException} (broken pipe, connection reset) — connection already dead</li>
+ *   <li>{@code SSLException} — post-handshake TLS error on established connection</li>
+ *   <li>{@code Http2Exception} — protocol errors already handled internally by
+ *       {@code Http2FrameCodec} and {@code Http2MultiplexHandler} before reaching here</li>
+ * </ul>
+ * <p>
+ * Typical exceptions that reach this handler (after being processed by
+ * {@code Http2FrameCodec} and {@code Http2MultiplexHandler} internally):
+ *
+ * @see ReactorNettyClient#configureChannelPipelineHandlers()
+ */
+final class Http2ParentChannelExceptionHandler extends ChannelInboundHandlerAdapter {
+
+    static final String HANDLER_NAME = "cosmosH2ParentExceptionHandler";
+
+    private static final Logger logger = LoggerFactory.getLogger(Http2ParentChannelExceptionHandler.class);
+
+    @Override
+    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
+        if (logger.isDebugEnabled()) {
+            logger.debug("Exception on HTTP/2 parent connection [id:{}]: {}",
+                ctx.channel().id().asShortText(), cause.toString(), cause);
+        }
+        // Do NOT close the channel or alter connection lifecycle.
+        // Reactor-netty and the pool eviction predicate handle that independently.
+    }
+}

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/http/ReactorNettyClient.java

@@ -164,6 +164,25 @@ private void configureChannelPipelineHandlers() {
                             "customHeaderCleaner",
                             new Http2ResponseHeaderCleanerHandler());
                     }
+
+                    // Install exception handler on the HTTP/2 parent (TCP) channel.
+                    // In H2, doOnConnected fires for stream (child) channels — channel.parent()
+                    // is the TCP connection. The parent pipeline has no ChannelOperationsHandler
+                    // (unlike H1.1), so TCP-level exceptions (RST, broken pipe) propagate to
+                    // Netty's TailContext and get logged as WARN. This handler matches H1.1
+                    // behavior by consuming exceptions at DEBUG level.
+                    Channel parent = connection.channel().parent();
+                    if (parent != null
+                        && parent.pipeline().get(Http2ParentChannelExceptionHandler.HANDLER_NAME) == null) {
+
+                        try {
+                            parent.pipeline().addLast(
+                                Http2ParentChannelExceptionHandler.HANDLER_NAME,
+                                new Http2ParentChannelExceptionHandler());
+                        } catch (IllegalArgumentException ignored) {
+                            // Duplicate handler — already installed by a concurrent stream
+                        }
+                    }
                 }));
         }
     }