8350279: HttpClient: Add a new HttpResponse method to identify connections

Volkan Yazici · jaikiran · commit 5fc18f5b8aa1 · 2025-04-15T11:41:47.000Z
Reviewed-by: dfuchs, jpai
diff --git a/src/java.net.http/share/classes/java/net/http/HttpResponse.java b/src/java.net.http/share/classes/java/net/http/HttpResponse.java
@@ -99,6 +99,28 @@ public interface HttpResponse<T> {
      */
     public int statusCode();
 
+    /**
+     * {@return if present, a label identifying the connection on which the
+     * response was received}
+     * <p>
+     * The format of the string is opaque, but the value is fixed and unique
+     * for any connection in the scope of the associated {@link HttpClient}
+     * instance.
+     *
+     * @implSpec
+     * The default implementation of this method returns
+     * {@link Optional#empty() Optional.empty()}.
+     *
+     * @implNote
+     * Instances of {@code HttpResponse} returned by the JDK built-in
+     * implementation of {@code HttpClient} always return a non-empty value.
+     *
+     * @since 25
+     */
+    default Optional<String> connectionLabel() {
+        return Optional.empty();
+    }
+
     /**
      * Returns the {@link HttpRequest} corresponding to this response.
      *
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/AbstractAsyncSSLConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/AbstractAsyncSSLConnection.java
@@ -74,8 +74,9 @@ abstract class AbstractAsyncSSLConnection extends HttpConnection
     AbstractAsyncSSLConnection(InetSocketAddress addr,
                                HttpClientImpl client,
                                ServerName serverName, int port,
-                               String[] alpn) {
-        super(addr, client);
+                               String[] alpn,
+                               String label) {
+        super(addr, client, label);
         this.sniServerNames = formSNIServerNames(serverName, client);
         SSLContext context = client.theSSLContext();
         sslParameters = createSSLParameters(client, this.sniServerNames, alpn);
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/AsyncSSLConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/AsyncSSLConnection.java
@@ -44,9 +44,10 @@ class AsyncSSLConnection extends AbstractAsyncSSLConnection {
 
     AsyncSSLConnection(InetSocketAddress addr,
                        HttpClientImpl client,
-                       String[] alpn) {
-        super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn);
-        plainConnection = new PlainHttpConnection(addr, client);
+                       String[] alpn,
+                       String label) {
+        super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn, label);
+        plainConnection = new PlainHttpConnection(addr, client, label);
         writePublisher = new PlainHttpPublisher();
     }
 
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/AsyncSSLTunnelConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/AsyncSSLTunnelConnection.java
@@ -47,10 +47,11 @@ class AsyncSSLTunnelConnection extends AbstractAsyncSSLConnection {
                              HttpClientImpl client,
                              String[] alpn,
                              InetSocketAddress proxy,
-                             ProxyHeaders proxyHeaders)
+                             ProxyHeaders proxyHeaders,
+                             String label)
     {
-        super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn);
-        this.plainConnection = new PlainTunnelingConnection(addr, proxy, client, proxyHeaders);
+        super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn, label);
+        this.plainConnection = new PlainTunnelingConnection(addr, proxy, client, proxyHeaders, label);
         this.writePublisher = new PlainHttpPublisher();
     }
 
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/HttpConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/HttpConnection.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,6 +28,7 @@
 import java.io.Closeable;
 import java.io.IOException;
 import java.net.InetSocketAddress;
+import java.net.http.HttpResponse;
 import java.nio.ByteBuffer;
 import java.nio.channels.SocketChannel;
 import java.util.Arrays;
@@ -39,6 +40,7 @@
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.ConcurrentLinkedDeque;
 import java.util.concurrent.Flow;
+import java.util.concurrent.atomic.AtomicLong;
 import java.util.function.BiPredicate;
 import java.util.function.Predicate;
 import java.net.http.HttpClient;
@@ -76,17 +78,46 @@ abstract class HttpConnection implements Closeable {
     public static final Comparator<HttpConnection> COMPARE_BY_ID
             = Comparator.comparing(HttpConnection::id);
 
+    private static final AtomicLong LABEL_COUNTER = new AtomicLong();
+
     /** The address this connection is connected to. Could be a server or a proxy. */
     final InetSocketAddress address;
     private final HttpClientImpl client;
     private final TrailingOperations trailingOperations;
+
+    /**
+     * A unique identifier that provides a total order among instances.
+     */
     private final long id;
 
-    HttpConnection(InetSocketAddress address, HttpClientImpl client) {
+    /**
+     * A label to identify the connection.
+     * <p>
+     * This label helps with associating multiple components participating in a
+     * connection. For instance, an {@link AsyncSSLConnection} and the
+     * {@link PlainHttpConnection} it wraps will share the same label.
+     * </p>
+     */
+    private final String label;
+
+    HttpConnection(InetSocketAddress address, HttpClientImpl client, String label) {
         this.address = address;
         this.client = client;
         trailingOperations = new TrailingOperations();
         this.id = newConnectionId(client);
+        this.label = label;
+    }
+
+    private static String nextLabel() {
+        return "" + LABEL_COUNTER.incrementAndGet();
+    }
+
+    /**
+     * {@return a label identifying the connection to facilitate
+     * {@link HttpResponse#connectionLabel() HttpResponse::connectionLabel}}
+     */
+    public final String label() {
+        return label;
     }
 
     // This is overridden in tests
@@ -303,11 +334,13 @@ private static HttpConnection getSSLConnection(InetSocketAddress addr,
                                                    String[] alpn,
                                                    HttpRequestImpl request,
                                                    HttpClientImpl client) {
+        String label = nextLabel();
         if (proxy != null)
             return new AsyncSSLTunnelConnection(addr, client, alpn, proxy,
-                                                proxyTunnelHeaders(request));
+                                                proxyTunnelHeaders(request),
+                                                label);
         else
-            return new AsyncSSLConnection(addr, client, alpn);
+            return new AsyncSSLConnection(addr, client, alpn, label);
     }
 
     /**
@@ -381,14 +414,16 @@ private static HttpConnection getPlainConnection(InetSocketAddress addr,
                                                      InetSocketAddress proxy,
                                                      HttpRequestImpl request,
                                                      HttpClientImpl client) {
+        String label = nextLabel();
         if (request.isWebSocket() && proxy != null)
             return new PlainTunnelingConnection(addr, proxy, client,
-                                                proxyTunnelHeaders(request));
+                                                proxyTunnelHeaders(request),
+                                                label);
 
         if (proxy == null)
-            return new PlainHttpConnection(addr, client);
+            return new PlainHttpConnection(addr, client, label);
         else
-            return new PlainProxyConnection(proxy, client);
+            return new PlainProxyConnection(proxy, client, label);
     }
 
     void closeOrReturnToCache(HttpHeaders hdrs) {
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/HttpResponseImpl.java b/src/java.net.http/share/classes/jdk/internal/net/http/HttpResponseImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,6 +44,7 @@
 class HttpResponseImpl<T> implements HttpResponse<T>, RawChannel.Provider {
 
     final int responseCode;
+    private final String connectionLabel;
     final HttpRequest initialRequest;
     final Optional<HttpResponse<T>> previousResponse;
     final HttpHeaders headers;
@@ -59,6 +60,7 @@ public HttpResponseImpl(HttpRequest initialRequest,
                             T body,
                             Exchange<T> exch) {
         this.responseCode = response.statusCode();
+        this.connectionLabel = connectionLabel(exch).orElse(null);
         this.initialRequest = initialRequest;
         this.previousResponse = Optional.ofNullable(previousResponse);
         this.headers = response.headers();
@@ -70,11 +72,23 @@ public HttpResponseImpl(HttpRequest initialRequest,
         this.body = body;
     }
 
+    private static Optional<String> connectionLabel(Exchange<?> exchange) {
+        return Optional.ofNullable(exchange)
+                .map(e -> e.exchImpl)
+                .map(ExchangeImpl::connection)
+                .map(HttpConnection::label);
+    }
+
     @Override
     public int statusCode() {
         return responseCode;
     }
 
+    @Override
+    public Optional<String> connectionLabel() {
+        return Optional.ofNullable(connectionLabel);
+    }
+
     @Override
     public HttpRequest request() {
         return initialRequest;
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/PlainHttpConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/PlainHttpConnection.java
@@ -310,8 +310,8 @@ final FlowTube getConnectionFlow() {
         return tube;
     }
 
-    PlainHttpConnection(InetSocketAddress addr, HttpClientImpl client) {
-        super(addr, client);
+    PlainHttpConnection(InetSocketAddress addr, HttpClientImpl client, String label) {
+        super(addr, client, label);
         try {
             this.chan = SocketChannel.open();
             chan.configureBlocking(false);
@@ -335,7 +335,7 @@ final FlowTube getConnectionFlow() {
             }
             chan.setOption(StandardSocketOptions.TCP_NODELAY, true);
             // wrap the channel in a Tube for async reading and writing
-            tube = new SocketTube(client(), chan, Utils::getBuffer);
+            tube = new SocketTube(client(), chan, Utils::getBuffer, label);
         } catch (IOException e) {
             throw new InternalError(e);
         }
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/PlainProxyConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/PlainProxyConnection.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -29,8 +29,8 @@
 
 class PlainProxyConnection extends PlainHttpConnection {
 
-    PlainProxyConnection(InetSocketAddress proxy, HttpClientImpl client) {
-        super(proxy, client);
+    PlainProxyConnection(InetSocketAddress proxy, HttpClientImpl client, String label) {
+        super(proxy, client, label);
     }
 
     @Override
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/PlainTunnelingConnection.java b/src/java.net.http/share/classes/jdk/internal/net/http/PlainTunnelingConnection.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,11 +54,12 @@ final class PlainTunnelingConnection extends HttpConnection {
     protected PlainTunnelingConnection(InetSocketAddress addr,
                                        InetSocketAddress proxy,
                                        HttpClientImpl client,
-                                       ProxyHeaders proxyHeaders) {
-        super(addr, client);
+                                       ProxyHeaders proxyHeaders,
+                                       String label) {
+        super(addr, client, label);
         this.proxyAddr = proxy;
         this.proxyHeaders = proxyHeaders;
-        delegate = new PlainHttpConnection(proxy, client);
+        delegate = new PlainHttpConnection(proxy, client, label);
     }
 
     @Override
diff --git a/src/java.net.http/share/classes/jdk/internal/net/http/SocketTube.java b/src/java.net.http/share/classes/jdk/internal/net/http/SocketTube.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,7 +31,6 @@
 import java.util.Objects;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.Flow;
-import java.util.concurrent.atomic.AtomicLong;
 import java.util.concurrent.atomic.AtomicReference;
 import java.nio.channels.SelectableChannel;
 import java.nio.channels.SelectionKey;
@@ -59,7 +58,6 @@
 final class SocketTube implements FlowTube {
 
     final Logger debug = Utils.getDebugLogger(this::dbgString, Utils.DEBUG);
-    static final AtomicLong IDS = new AtomicLong();
 
     private final HttpClientImpl client;
     private final SocketChannel channel;
@@ -68,14 +66,15 @@ final class SocketTube implements FlowTube {
     private final AtomicReference<Throwable> errorRef = new AtomicReference<>();
     private final InternalReadPublisher readPublisher;
     private final InternalWriteSubscriber writeSubscriber;
-    private final long id = IDS.incrementAndGet();
+    private final String connectionLabel;
 
     public SocketTube(HttpClientImpl client, SocketChannel channel,
-                      Supplier<ByteBuffer> buffersFactory) {
+                      Supplier<ByteBuffer> buffersFactory,
+                      String connectionLabel) {
         this.client = client;
         this.channel = channel;
         this.sliceBuffersSource = new SliceBufferSource(buffersFactory);
-
+        this.connectionLabel = connectionLabel;
         this.readPublisher = new InternalReadPublisher();
         this.writeSubscriber = new InternalWriteSubscriber();
     }
@@ -1343,7 +1342,7 @@ public String toString() {
     }
 
     final String dbgString() {
-        return "SocketTube("+id+")";
+        return "SocketTube("+ connectionLabel +")";
     }
 
     final String channelDescr() {
diff --git a/test/jdk/java/net/httpclient/HttpResponseConnectionLabelTest.java b/test/jdk/java/net/httpclient/HttpResponseConnectionLabelTest.java
diff --git a/test/jdk/java/net/httpclient/whitebox/java.net.http/jdk/internal/net/http/ConnectionPoolTest.java b/test/jdk/java/net/httpclient/whitebox/java.net.http/jdk/internal/net/http/ConnectionPoolTest.java

Original file line number	Diff line number	Diff line change
`@@ -47,10 +47,11 @@ class AsyncSSLTunnelConnection extends AbstractAsyncSSLConnection {`
`47`	`47`	`HttpClientImpl client,`
`48`	`48`	`String[] alpn,`
`49`	`49`	`InetSocketAddress proxy,`
`50`		`- ProxyHeaders proxyHeaders)`
	`50`	`+ ProxyHeaders proxyHeaders,`
	`51`	`+ String label)`
`51`	`52`	`{`
`52`		`- super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn);`
`53`		`- this.plainConnection = new PlainTunnelingConnection(addr, proxy, client, proxyHeaders);`
	`53`	`+ super(addr, client, Utils.getServerName(addr), addr.getPort(), alpn, label);`
	`54`	`+ this.plainConnection = new PlainTunnelingConnection(addr, proxy, client, proxyHeaders, label);`
`54`	`55`	`this.writePublisher = new PlainHttpPublisher();`
`55`	`56`	`}`
`56`	`57`
Original file line number	Diff line number	Diff line change
`@@ -310,8 +310,8 @@ final FlowTube getConnectionFlow() {`
`310`	`310`	`return tube;`
`311`	`311`	`}`
`312`	`312`
`313`		`- PlainHttpConnection(InetSocketAddress addr, HttpClientImpl client) {`
`314`		`- super(addr, client);`
	`313`	`+ PlainHttpConnection(InetSocketAddress addr, HttpClientImpl client, String label) {`
	`314`	`+ super(addr, client, label);`
`315`	`315`	`try {`
`316`	`316`	`this.chan = SocketChannel.open();`
`317`	`317`	`chan.configureBlocking(false);`
`@@ -335,7 +335,7 @@ final FlowTube getConnectionFlow() {`
`335`	`335`	`}`
`336`	`336`	`chan.setOption(StandardSocketOptions.TCP_NODELAY, true);`
`337`	`337`	`// wrap the channel in a Tube for async reading and writing`
`338`		`- tube = new SocketTube(client(), chan, Utils::getBuffer);`
	`338`	`+ tube = new SocketTube(client(), chan, Utils::getBuffer, label);`
`339`	`339`	`} catch (IOException e) {`
`340`	`340`	`throw new InternalError(e);`
`341`	`341`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.`
	`2`	`+ * Copyright (c) 2015, 2025, Oracle and/or its affiliates. All rights reserved.`
`3`	`3`	`* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.`
`4`	`4`	`*`
`5`	`5`	`* This code is free software; you can redistribute it and/or modify it`
`@@ -29,8 +29,8 @@`
`29`	`29`
`30`	`30`	`class PlainProxyConnection extends PlainHttpConnection {`
`31`	`31`
`32`		`- PlainProxyConnection(InetSocketAddress proxy, HttpClientImpl client) {`
`33`		`- super(proxy, client);`
	`32`	`+ PlainProxyConnection(InetSocketAddress proxy, HttpClientImpl client, String label) {`
	`33`	`+ super(proxy, client, label);`
`34`	`34`	`}`
`35`	`35`
`36`	`36`	`@Override`