Add RFC 8297 (103 Early Hints) support to HttpClient5 (classic & async)

httpclient5/src/main/java/org/apache/hc/client5/http/EarlyHintsListener.java

@@ -0,0 +1,79 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http;
+
+import java.io.IOException;
+
+import org.apache.hc.core5.http.HttpException;
+import org.apache.hc.core5.http.HttpResponse;
+import org.apache.hc.core5.http.protocol.HttpContext;
+
+/**
+ * Callback interface for receiving {@code 103 Early Hints} (RFC&nbsp;8297)
+ * informational responses emitted by the origin server before the final response.
+ *
+ * <p>The listener is invoked zero or more times per request, once for each
+ * {@code 103} received. It is <strong>never</strong> invoked for the final
+ * (non-1xx) response.</p>
+ *
+ * <h2>Semantics</h2>
+ * <ul>
+ *   <li>Invoked on the I/O thread (async clients) or the request thread
+ *   (classic clients). Implementations should be fast and non-blocking.</li>
+ *   <li>Headers observed in Early Hints are advisory. Clients typically act only
+ *   on safe headers such as {@code Link: ...; rel=preload} or
+ *   {@code rel=preconnect}.</li>
+ *   <li>Multiple {@code 103} responses may be received; ordering follows the
+ *   network order prior to the final response.</li>
+ * </ul>
+ *
+ * <h2>Example</h2>
+ * <pre>{@code
+ * HttpClients.custom()
+ *     .setEarlyHintsListener((hints, context) -> {
+ *         for (Header h : hints.getHeaders("Link")) {
+ *             // inspect preload links, metrics, etc.
+ *         }
+ *     })
+ *     .build();
+ * }</pre>
+ *
+ * @since 5.6
+ */
+@FunctionalInterface
+public interface EarlyHintsListener {
+
+    /**
+     * Called for each received {@code 103 Early Hints} informational response.
+     *
+     * @param hints   the {@code 103} response object as received on the wire
+     * @param context the current execution context (never {@code null})
+     * @throws HttpException to signal an HTTP-layer error while handling hints
+     * @throws IOException   to signal an I/O error while handling hints
+     */
+    void onEarlyHints(HttpResponse hints, HttpContext context) throws HttpException, IOException;
+}

httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/EarlyHintsAsyncExec.java

@@ -0,0 +1,108 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http.impl.async;
+
+import org.apache.hc.client5.http.EarlyHintsListener;
+import org.apache.hc.client5.http.async.AsyncExecCallback;
+import org.apache.hc.client5.http.async.AsyncExecChain;
+import org.apache.hc.client5.http.async.AsyncExecChainHandler;
+import org.apache.hc.core5.http.EntityDetails;
+import org.apache.hc.core5.http.HttpException;
+import org.apache.hc.core5.http.HttpRequest;
+import org.apache.hc.core5.http.HttpResponse;
+import org.apache.hc.core5.http.HttpStatus;
+import org.apache.hc.core5.http.nio.AsyncEntityProducer;
+import org.apache.hc.core5.http.protocol.HttpContext;
+
+/**
+ * Execution chain handler that delivers {@code 103 Early Hints} (RFC&nbsp;8297)
+ * informational responses to a user-provided {@link org.apache.hc.client5.http.EarlyHintsListener}
+ * without affecting the final (non-1xx) response processing.
+ *
+ * <p>This handler wraps the downstream {@link org.apache.hc.client5.http.async.AsyncExecCallback}
+ * and forwards any informational response with code
+ * {@link org.apache.hc.core5.http.HttpStatus#SC_EARLY_HINTS 103} to the listener.
+ * All other responses (including the final response) are delegated unchanged.</p>
+ *
+ *
+ * <p>For security and interoperability, applications typically act only on
+ * headers considered safe in Early Hints (for example, {@code Link} with
+ * {@code rel=preload} or {@code rel=preconnect}).</p>
+ *
+ * @see org.apache.hc.client5.http.EarlyHintsListener
+ * @see org.apache.hc.core5.http.HttpStatus#SC_EARLY_HINTS
+ * @see org.apache.hc.core5.http.nio.ResponseChannel#sendInformation(HttpResponse, HttpContext)
+ * @since 5.6
+ */
+public final class EarlyHintsAsyncExec implements AsyncExecChainHandler {
+    private final EarlyHintsListener listener;
+
+    public EarlyHintsAsyncExec(final EarlyHintsListener listener) {
+        this.listener = listener;
+    }
+
+    @Override
+    public void execute(final HttpRequest request,
+                        final AsyncEntityProducer entityProducer,
+                        final AsyncExecChain.Scope scope,
+                        final AsyncExecChain chain,
+                        final AsyncExecCallback callback) throws HttpException, java.io.IOException {
+
+        if (listener == null) {
+            chain.proceed(request, entityProducer, scope, callback);
+            return;
+        }
+
+        chain.proceed(request, entityProducer, scope, new AsyncExecCallback() {
+            @Override
+            public void handleInformationResponse(final HttpResponse response)
+                    throws HttpException, java.io.IOException {
+                if (response.getCode() == HttpStatus.SC_EARLY_HINTS) {
+                    listener.onEarlyHints(response, scope.clientContext);
+                }
+                callback.handleInformationResponse(response);
+            }
+
+            @Override
+            public org.apache.hc.core5.http.nio.AsyncDataConsumer handleResponse(
+                    final HttpResponse response, final EntityDetails entityDetails)
+                    throws HttpException, java.io.IOException {
+                return callback.handleResponse(response, entityDetails);
+            }
+
+            @Override
+            public void completed() {
+                callback.completed();
+            }
+
+            @Override
+            public void failed(final Exception cause) {
+                callback.failed(cause);
+            }
+        });
+    }
+}

httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.java

@@ -42,6 +42,7 @@
 
 import org.apache.hc.client5.http.AuthenticationStrategy;
 import org.apache.hc.client5.http.ConnectionKeepAliveStrategy;
+import org.apache.hc.client5.http.EarlyHintsListener;
 import org.apache.hc.client5.http.HttpRequestRetryStrategy;
 import org.apache.hc.client5.http.SchemePortResolver;
 import org.apache.hc.client5.http.UserTokenHandler;
@@ -262,6 +263,8 @@ private ExecInterceptorEntry(
 
     private ProxySelector proxySelector;
 
+    private EarlyHintsListener earlyHintsListener;
+
     /**
      * Maps {@code Content-Encoding} tokens to decoder factories in insertion order.
      */
@@ -889,6 +892,22 @@ public HttpAsyncClientBuilder disableContentCompression() {
         return this;
     }
 
+    /**
+     * Registers a global {@link org.apache.hc.client5.http.EarlyHintsListener}
+     * that will be notified when the client receives {@code 103 Early Hints}
+     * informational responses for any request executed by the built client.
+     *
+     * @param listener the listener to receive {@code 103 Early Hints} events,
+     *                 or {@code null} to remove the listener
+     * @return this builder
+     * @since 5.6
+     */
+    public final HttpAsyncClientBuilder setEarlyHintsListener(final EarlyHintsListener listener) {
+        this.earlyHintsListener = listener;
+        return this;
+    }
+
+
     /**
      * Request exec chain customization and extension.
      * <p>
@@ -1026,6 +1045,11 @@ public CloseableHttpAsyncClient build() {
                         authCachingDisabled),
                 ChainElement.CONNECT.name());
 
+        if (earlyHintsListener != null) {
+            addExecInterceptorBefore(ChainElement.PROTOCOL.name(), "early-hints",
+                    new EarlyHintsAsyncExec(earlyHintsListener));
+        }
+
         execChainDefinition.addFirst(
                 new AsyncProtocolExec(
                         targetAuthStrategyCopy,