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

src/java.net.http/share/classes/java/net/http/HttpResponse.java

@@ -99,6 +99,24 @@ 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()}.
+     *
+     * @since 25
+     */
+    default Optional<String> connectionLabel() {
+        return Optional.empty();
+    }
+
     /**
      * Returns the {@link HttpRequest} corresponding to this response.
      *

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);

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();
     }
 

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();
     }
 

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) {

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;

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);
         }

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

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

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() {