add experimental RFC 9218 Priority header support.

arturobernalg · arturobernalg · commit d6fba2ce4a76 · 2025-10-19T08:05:22.000+02:00
Wire H2RequestPriority via H2AsyncClientBuilder.enablePriorityHeader(); omit on defaults, allow overwrite.
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java
@@ -32,8 +32,10 @@
 import java.util.concurrent.TimeUnit;
 
 import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.Experimental;
 import org.apache.hc.core5.annotation.ThreadingBehavior;
 import org.apache.hc.core5.http.HttpHost;
+import org.apache.hc.core5.http2.priority.PriorityValue;
 import org.apache.hc.core5.util.Args;
 import org.apache.hc.core5.util.TimeValue;
 import org.apache.hc.core5.util.Timeout;
@@ -69,13 +71,18 @@ public class RequestConfig implements Cloneable {
 
     private final ExpectContinueTrigger expectContinueTrigger;
 
+    /**
+     * HTTP/2 Priority header value to emit when using H2+. Null means “don’t emit”.
+     */
+    private final PriorityValue h2Priority;
+
     /**
      * Intended for CDI compatibility
     */
     protected RequestConfig() {
         this(false, null, null, false, false, 0, false, null, null,
                 DEFAULT_CONNECTION_REQUEST_TIMEOUT, null, null, DEFAULT_CONN_KEEP_ALIVE, false, false, false, null,
-                ExpectContinueTrigger.ALWAYS);
+                ExpectContinueTrigger.ALWAYS, null);
     }
 
     RequestConfig(
@@ -96,7 +103,8 @@ protected RequestConfig() {
             final boolean hardCancellationEnabled,
             final boolean protocolUpgradeEnabled,
             final Path unixDomainSocket,
-            final ExpectContinueTrigger expectContinueTrigger) {
+            final ExpectContinueTrigger expectContinueTrigger,
+            final PriorityValue h2Priority) {
         super();
         this.expectContinueEnabled = expectContinueEnabled;
         this.proxy = proxy;
@@ -116,6 +124,7 @@ protected RequestConfig() {
         this.protocolUpgradeEnabled = protocolUpgradeEnabled;
         this.unixDomainSocket = unixDomainSocket;
         this.expectContinueTrigger = expectContinueTrigger;
+        this.h2Priority = h2Priority;
     }
 
     /**
@@ -244,6 +253,15 @@ public ExpectContinueTrigger getExpectContinueTrigger() {
         return expectContinueTrigger;
     }
 
+    /**
+     * Returns the HTTP/2+ priority preference for this request or {@code null} if unset.
+     * @since 5.6
+     */
+    @Experimental
+    public PriorityValue getH2Priority() {
+        return h2Priority;
+    }
+
     @Override
     protected RequestConfig clone() throws CloneNotSupportedException {
         return (RequestConfig) super.clone();
@@ -296,7 +314,8 @@ public static RequestConfig.Builder copy(final RequestConfig config) {
             .setContentCompressionEnabled(config.isContentCompressionEnabled())
             .setHardCancellationEnabled(config.isHardCancellationEnabled())
             .setProtocolUpgradeEnabled(config.isProtocolUpgradeEnabled())
-            .setUnixDomainSocket(config.getUnixDomainSocket());
+            .setUnixDomainSocket(config.getUnixDomainSocket())
+            .setH2Priority(config.getH2Priority());
     }
 
     public static class Builder {
@@ -319,6 +338,7 @@ public static class Builder {
         private boolean protocolUpgradeEnabled;
         private Path unixDomainSocket;
         private ExpectContinueTrigger expectContinueTrigger;
+        private PriorityValue h2Priority;
 
         Builder() {
             super();
@@ -691,6 +711,16 @@ public Builder setExpectContinueTrigger(final ExpectContinueTrigger trigger) {
             return this;
         }
 
+        /**
+         * Sets HTTP/2+ request priority. If {@code null}, the header is not emitted.
+         * @since 5.6
+         */
+        @Experimental
+        public Builder setH2Priority(final PriorityValue priority) {
+            this.h2Priority = priority;
+            return this;
+        }
+
         public RequestConfig build() {
             return new RequestConfig(
                     expectContinueEnabled,
@@ -710,7 +740,8 @@ public RequestConfig build() {
                     hardCancellationEnabled,
                     protocolUpgradeEnabled,
                     unixDomainSocket,
-                    expectContinueTrigger);
+                    expectContinueTrigger,
+                    h2Priority);
         }
 
     }
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/H2AsyncClientBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/H2AsyncClientBuilder.java
@@ -64,13 +64,15 @@
 import org.apache.hc.client5.http.impl.auth.SystemDefaultCredentialsProvider;
 import org.apache.hc.client5.http.impl.nio.MultihomeConnectionInitiator;
 import org.apache.hc.client5.http.impl.routing.DefaultRoutePlanner;
+import org.apache.hc.client5.http.protocol.H2RequestPriority;
 import org.apache.hc.client5.http.protocol.RedirectStrategy;
 import org.apache.hc.client5.http.protocol.RequestAddCookies;
 import org.apache.hc.client5.http.protocol.RequestDefaultHeaders;
 import org.apache.hc.client5.http.protocol.RequestExpectContinue;
 import org.apache.hc.client5.http.protocol.ResponseProcessCookies;
 import org.apache.hc.client5.http.routing.HttpRoutePlanner;
 import org.apache.hc.client5.http.ssl.DefaultClientTlsStrategy;
+import org.apache.hc.core5.annotation.Experimental;
 import org.apache.hc.core5.annotation.Internal;
 import org.apache.hc.core5.concurrent.DefaultThreadFactory;
 import org.apache.hc.core5.function.Callback;
@@ -216,6 +218,8 @@ private ExecInterceptorEntry(
 
     private Decorator<IOSession> ioSessionDecorator;
 
+    private boolean priorityHeaderDisabled;
+
     public static H2AsyncClientBuilder create() {
         return new H2AsyncClientBuilder();
     }
@@ -312,6 +316,16 @@ public final H2AsyncClientBuilder setIoSessionDecorator(final Decorator<IOSessio
         return this;
     }
 
+    /**
+     * Disable installing the HTTP/2 Priority header interceptor by default.
+     * @since 5.6
+     */
+    @Experimental
+    public final H2AsyncClientBuilder disablePriorityHeader() {
+        this.priorityHeaderDisabled = true;
+        return this;
+    }
+
     /**
      * Adds this protocol interceptor to the head of the protocol processing list.
      *
@@ -699,6 +713,7 @@ public final H2AsyncClientBuilder evictIdleConnections(final TimeValue maxIdleTi
         return this;
     }
 
+
     /**
      * Request exec chain customization and extension.
      * <p>
@@ -762,6 +777,11 @@ public CloseableHttpAsyncClient build() {
                 }
             }
         }
+
+        if (!priorityHeaderDisabled) {
+            b.addLast(H2RequestPriority.INSTANCE);
+        }
+
         b.addAll(
                 new H2RequestTargetHost(),
                 new RequestDefaultHeaders(defaultHeaders),
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/H2RequestPriority.java b/httpclient5/src/main/java/org/apache/hc/client5/http/protocol/H2RequestPriority.java
@@ -0,0 +1,107 @@
+/*
+ * ====================================================================
+ * 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.protocol;
+
+import java.io.IOException;
+
+import org.apache.hc.client5.http.config.RequestConfig;
+import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.Experimental;
+import org.apache.hc.core5.annotation.ThreadingBehavior;
+import org.apache.hc.core5.http.EntityDetails;
+import org.apache.hc.core5.http.Header;
+import org.apache.hc.core5.http.HttpException;
+import org.apache.hc.core5.http.HttpHeaders;
+import org.apache.hc.core5.http.HttpRequest;
+import org.apache.hc.core5.http.HttpRequestInterceptor;
+import org.apache.hc.core5.http.HttpVersion;
+import org.apache.hc.core5.http.ProtocolVersion;
+import org.apache.hc.core5.http.protocol.HttpContext;
+import org.apache.hc.core5.http2.priority.PriorityFormatter;
+import org.apache.hc.core5.http2.priority.PriorityValue;
+import org.apache.hc.core5.util.Args;
+
+/**
+ * Adds the {@code Priority} request header to HTTP/2+ requests when a per-request
+ * priority is configured.
+ * <p>
+ * The priority is taken from {@link RequestConfig#getH2Priority()}. If a {@code Priority}
+ * header is already present on the request, it is left unchanged. If formatting the
+ * configured value yields an empty string (e.g., because it encodes protocol defaults),
+ * the header is not added.
+ *
+ * @since 5.6
+ */
+@Experimental
+@Contract(threading = ThreadingBehavior.IMMUTABLE)
+public final class H2RequestPriority implements HttpRequestInterceptor {
+
+    /**
+     * Singleton instance.
+     */
+    public static final H2RequestPriority INSTANCE = new H2RequestPriority();
+
+    @Override
+    public void process(
+            final HttpRequest request,
+            final EntityDetails entity,
+            final HttpContext context) throws HttpException, IOException {
+
+        Args.notNull(request, "HTTP request");
+        Args.notNull(context, "HTTP context");
+
+        final HttpClientContext httpClientContext = HttpClientContext.cast(context);
+
+        final ProtocolVersion pv = httpClientContext.getProtocolVersion();
+        if (pv.compareToVersion(HttpVersion.HTTP_2) < 0) {
+            return; // only for HTTP/2+
+        }
+
+        final Header existing = request.getFirstHeader(HttpHeaders.PRIORITY);
+        if (existing != null) {
+            return;
+        }
+
+        final RequestConfig requestConfig = httpClientContext.getRequestConfigOrDefault();
+        if (requestConfig == null) {
+            return;
+        }
+
+        final PriorityValue pri = requestConfig.getH2Priority();
+        if (pri == null || PriorityValue.defaults().equals(pri)) {
+            return;
+        }
+
+        final Header header = PriorityFormatter.formatHeader(pri);
+        if (header.getValue() == null || header.getValue().isEmpty()) {
+            return;
+        }
+
+        request.addHeader(header);
+    }
+}
diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/examples/AsyncClientH2Priority.java b/httpclient5/src/test/java/org/apache/hc/client5/http/examples/AsyncClientH2Priority.java
@@ -0,0 +1,113 @@
+/*
+ * ====================================================================
+ * 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.examples;
+
+import java.util.concurrent.Future;
+
+import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
+import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
+import org.apache.hc.client5.http.async.methods.SimpleRequestBuilder;
+import org.apache.hc.client5.http.config.RequestConfig;
+import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
+import org.apache.hc.client5.http.impl.async.H2AsyncClientBuilder;
+import org.apache.hc.client5.http.protocol.HttpClientContext;
+import org.apache.hc.core5.annotation.Experimental;
+import org.apache.hc.core5.http2.config.H2Config;
+import org.apache.hc.core5.http2.priority.PriorityValue;
+
+/**
+ * Demonstrates sending the HTTP/2 {@code Priority} request header using per-request configuration.
+ *
+ * <p><strong>How it works</strong>:
+ * <ul>
+ *   <li>Call {@code enablePriorityHeader()} on the H2 client builder to register
+ *       {@link org.apache.hc.client5.http.protocol.H2RequestPriority}.</li>
+ *   <li>For each request, set a priority on the {@link RequestConfig} via
+ *       {@link RequestConfig.Builder#setH2Priority(PriorityValue)} and attach it to the
+ *       {@link HttpClientContext} passed to {@code execute}.</li>
+ * </ul>
+ *
+ * <p><strong>Notes</strong>:
+ * <ul>
+ *   <li>If a {@code Priority} header is already present on the request, it is preserved.</li>
+ *   <li>If the configured value encodes protocol defaults, the header is omitted.</li>
+ *   <li>Applies to HTTP/2+ only; HTTP/1.1 requests are unaffected.</li>
+ * </ul>
+ *
+ * @since 5.6
+ */
+@Experimental
+public class AsyncClientH2Priority {
+
+    public static void main(final String[] args) throws Exception {
+        try (CloseableHttpAsyncClient client = H2AsyncClientBuilder.create()
+                .setH2Config(H2Config.custom()
+                        .setPushEnabled(false)
+                        .build())
+                .build()) {
+
+            client.start();
+
+            // --- Request 1: non-default priority -> header sent (e.g., "u=0, i")
+            final HttpClientContext ctx1 = HttpClientContext.create();
+            ctx1.setRequestConfig(RequestConfig.custom()
+                    .setH2Priority(PriorityValue.of(0, true))
+                    .build());
+
+            final SimpleHttpRequest req1 = SimpleRequestBuilder.get("https://nghttp2.org/httpbin/headers").build();
+            final Future<SimpleHttpResponse> f1 = client.execute(req1, ctx1, null);
+            final SimpleHttpResponse r1 = f1.get();
+            System.out.println("[/httpbin/headers] -> " + r1.getCode());
+            System.out.println("Negotiated protocol (req1): " + ctx1.getProtocolVersion());
+            System.out.println(r1.getBodyText());
+
+            // --- Request 2: defaults -> header omitted
+            final HttpClientContext ctx2 = HttpClientContext.create();
+            ctx2.setRequestConfig(RequestConfig.custom()
+                    .setH2Priority(PriorityValue.defaults())
+                    .build());
+
+            final SimpleHttpRequest req2 = SimpleRequestBuilder.get("https://nghttp2.org/httpbin/user-agent").build();
+            final SimpleHttpResponse r2 = client.execute(req2, ctx2, null).get();
+            System.out.println("[/httpbin/user-agent] -> " + r2.getCode());
+            System.out.println("Negotiated protocol (req2): " + ctx2.getProtocolVersion());
+            System.out.println(r2.getBodyText());
+
+            // --- Request 3: user-provided header -> preserved (no overwrite)
+            final HttpClientContext ctx3 = HttpClientContext.create();
+            ctx3.setRequestConfig(RequestConfig.custom()
+                    .setH2Priority(PriorityValue.of(5, false))
+                    .build());
+            final SimpleHttpRequest req3 = SimpleRequestBuilder.get("https://nghttp2.org/httpbin/headers").build();
+            req3.addHeader("Priority", "u=2");
+            final SimpleHttpResponse r3 = client.execute(req3, ctx3, null).get();
+            System.out.println("[/httpbin/headers with user header] -> " + r3.getCode());
+            System.out.println("Negotiated protocol (req3): " + ctx3.getProtocolVersion());
+            System.out.println(r3.getBodyText());
+        }
+    }
+}
diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/protocol/H2RequestPriorityTest.java b/httpclient5/src/test/java/org/apache/hc/client5/http/protocol/H2RequestPriorityTest.java
