apache · arturobernalg · Feb 4, 2026
diff --git a/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2PseudoRequestHeaders.java b/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2PseudoRequestHeaders.java
@@ -38,5 +38,9 @@ public final class H2PseudoRequestHeaders {
     public static final String SCHEME = ":scheme";
     public static final String AUTHORITY = ":authority";
     public static final String PATH = ":path";
+    /**
+     * RFC 8441 extended CONNECT pseudo-header.
+     */
+    public static final String PROTOCOL = ":protocol";
 
 }
diff --git a/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/DefaultH2RequestConverter.java b/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/DefaultH2RequestConverter.java
@@ -61,6 +61,7 @@ public HttpRequest convert(final List<Header> headers) throws HttpException {
         String scheme = null;
         String authority = null;
         String path = null;
+        String protocol = null;
         final List<Header> messageHeaders = new ArrayList<>();
 
         for (int i = 0; i < headers.size(); i++) {
@@ -98,6 +99,12 @@ public HttpRequest convert(final List<Header> headers) throws HttpException {
                     case H2PseudoRequestHeaders.AUTHORITY:
                         authority = value;
                         break;
+                    case H2PseudoRequestHeaders.PROTOCOL:
+                        if (protocol != null) {
+                            throw new ProtocolException("Multiple '%s' request headers are illegal", name);
+                        }
+                        protocol = value;
+                        break;
                     default:
                         throw new ProtocolException("Unsupported request header '%s'", name);
                 }
@@ -118,11 +125,21 @@ public HttpRequest convert(final List<Header> headers) throws HttpException {
             if (authority == null) {
                 throw new ProtocolException("Header '%s' is mandatory for CONNECT request", H2PseudoRequestHeaders.AUTHORITY);
             }
-            if (scheme != null) {
-                throw new ProtocolException("Header '%s' must not be set for CONNECT request", H2PseudoRequestHeaders.SCHEME);
-            }
-            if (path != null) {
-                throw new ProtocolException("Header '%s' must not be set for CONNECT request", H2PseudoRequestHeaders.PATH);
+            if (protocol != null) {
+                if (scheme == null) {
+                    throw new ProtocolException("Header '%s' is mandatory for extended CONNECT", H2PseudoRequestHeaders.SCHEME);
+                }
+                if (path == null) {
+                    throw new ProtocolException("Header '%s' is mandatory for extended CONNECT", H2PseudoRequestHeaders.PATH);
+                }
+                validatePathPseudoHeader(method, scheme, path);
+            } else {
+                if (scheme != null) {
+                    throw new ProtocolException("Header '%s' must not be set for CONNECT request", H2PseudoRequestHeaders.SCHEME);
+                }
+                if (path != null) {
+                    throw new ProtocolException("Header '%s' must not be set for CONNECT request", H2PseudoRequestHeaders.PATH);
+                }
             }
         } else {
             if (scheme == null) {
@@ -143,6 +160,9 @@ public HttpRequest convert(final List<Header> headers) throws HttpException {
             throw new ProtocolException(ex.getMessage(), ex);
         }
         httpRequest.setPath(path);
+        if (protocol != null) {
+            httpRequest.addHeader(new BasicHeader(H2PseudoRequestHeaders.PROTOCOL, protocol));
+        }
         for (int i = 0; i < messageHeaders.size(); i++) {
             httpRequest.addHeader(messageHeaders.get(i));
         }
@@ -155,12 +175,26 @@ public List<Header> convert(final HttpRequest message) throws HttpException {
             throw new ProtocolException("Request method is empty");
         }
         final boolean optionMethod = Method.CONNECT.name().equalsIgnoreCase(message.getMethod());
+        final Header protocolHeader = message.getFirstHeader(H2PseudoRequestHeaders.PROTOCOL);
+        final String protocol = protocolHeader != null ? protocolHeader.getValue() : null;
+        if (protocol != null && !optionMethod) {
+            throw new ProtocolException("Header name '%s' is invalid", H2PseudoRequestHeaders.PROTOCOL);
+        }
         if (optionMethod) {
             if (message.getAuthority() == null) {
                 throw new ProtocolException("CONNECT request authority is not set");
             }
-            if (message.getPath() != null) {
-                throw new ProtocolException("CONNECT request path must be null");
+            if (protocol != null) {
+                if (TextUtils.isBlank(message.getScheme())) {
+                    throw new ProtocolException("CONNECT request scheme is not set");
+                }
+                if (TextUtils.isBlank(message.getPath())) {
+                    throw new ProtocolException("CONNECT request path is not set");
+                }
+            } else {
+                if (message.getPath() != null) {
+                    throw new ProtocolException("CONNECT request path must be null");
+                }
             }
         } else {
             if (TextUtils.isBlank(message.getScheme())) {
@@ -173,7 +207,14 @@ public List<Header> convert(final HttpRequest message) throws HttpException {
         final List<Header> headers = new ArrayList<>();
         headers.add(new BasicHeader(H2PseudoRequestHeaders.METHOD, message.getMethod(), false));
         if (optionMethod) {
-            headers.add(new BasicHeader(H2PseudoRequestHeaders.AUTHORITY, message.getAuthority(), false));
+            if (protocol != null) {
+                headers.add(new BasicHeader(H2PseudoRequestHeaders.PROTOCOL, protocol, false));
+                headers.add(new BasicHeader(H2PseudoRequestHeaders.SCHEME, message.getScheme(), false));
+                headers.add(new BasicHeader(H2PseudoRequestHeaders.AUTHORITY, message.getAuthority(), false));
+                headers.add(new BasicHeader(H2PseudoRequestHeaders.PATH, message.getPath(), false));
+            } else {
+                headers.add(new BasicHeader(H2PseudoRequestHeaders.AUTHORITY, message.getAuthority(), false));
+            }
         } else {
             headers.add(new BasicHeader(H2PseudoRequestHeaders.SCHEME, message.getScheme(), false));
             if (message.getAuthority() != null) {
@@ -186,6 +227,12 @@ public List<Header> convert(final HttpRequest message) throws HttpException {
             final Header header = it.next();
             final String name = header.getName();
             final String value = header.getValue();
+            if (name.startsWith(":")) {
+                if (optionMethod && H2PseudoRequestHeaders.PROTOCOL.equals(name)) {
+                    continue;
+                }
+                throw new ProtocolException("Header name '%s' is invalid", name);
+            }
             if (!FieldValidationSupport.isNameValid(name)) {
                 throw new ProtocolException("Header name '%s' is invalid", name);
             }

diff --git a/...-h2/src/test/java/org/apache/hc/core5/http2/impl/TestExtendedConnectRequestConverter.java b/...-h2/src/test/java/org/apache/hc/core5/http2/impl/TestExtendedConnectRequestConverter.java
@@ -0,0 +1,80 @@
+/*
+ * ====================================================================
+ * 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.core5.http2.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.hc.core5.http.Header;
+import org.apache.hc.core5.http.HttpRequest;
+import org.apache.hc.core5.http.Method;
+import org.apache.hc.core5.http.message.BasicHeader;
+import org.apache.hc.core5.http2.H2PseudoRequestHeaders;
+import org.apache.hc.core5.net.URIAuthority;
+import org.junit.jupiter.api.Test;
+
+class TestExtendedConnectRequestConverter {
+
+    @Test
+    void parsesExtendedConnect() throws Exception {
+        final List<Header> headers = new ArrayList<>();
+        headers.add(new BasicHeader(H2PseudoRequestHeaders.METHOD, Method.CONNECT.name(), false));
+        headers.add(new BasicHeader(H2PseudoRequestHeaders.PROTOCOL, "websocket", false));
+        headers.add(new BasicHeader(H2PseudoRequestHeaders.SCHEME, "https", false));
+        headers.add(new BasicHeader(H2PseudoRequestHeaders.AUTHORITY, "example.com", false));
+        headers.add(new BasicHeader(H2PseudoRequestHeaders.PATH, "/echo", false));
+
+        final DefaultH2RequestConverter converter = new DefaultH2RequestConverter();
+        final HttpRequest request = converter.convert(headers);
+        assertNotNull(request);
+        assertEquals(Method.CONNECT.name(), request.getMethod());
+        assertEquals("/echo", request.getPath());
+        assertEquals("websocket", request.getFirstHeader(H2PseudoRequestHeaders.PROTOCOL).getValue());
+    }
+
+    @Test
+    void emitsProtocolPseudoHeader() throws Exception {
+        final DefaultH2RequestConverter converter = new DefaultH2RequestConverter();
+        final HttpRequest request = new org.apache.hc.core5.http.message.BasicHttpRequest(Method.CONNECT.name(), "/echo");
+        request.setScheme("https");
+        request.setAuthority(new URIAuthority("example.com"));
+        request.setPath("/echo");
+        request.addHeader(H2PseudoRequestHeaders.PROTOCOL, "websocket");
+        final List<Header> headers = converter.convert(request);
+        boolean found = false;
+        for (final Header header : headers) {
+            if (H2PseudoRequestHeaders.PROTOCOL.equals(header.getName())) {
+                found = true;
+                break;
+            }
+        }
+        assertEquals(true, found);
+    }
+}
diff --git a/httpcore5-websocket/pom.xml b/httpcore5-websocket/pom.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ====================================================================
+  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 />.
+--><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.apache.httpcomponents.core5</groupId>
+    <artifactId>httpcore5-parent</artifactId>
+    <version>5.5-alpha1-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>httpcore5-websocket</artifactId>
+  <name>Apache HttpComponents Core WebSocket</name>
+  <inceptionYear>2005</inceptionYear>
+  <description>Apache HttpComponents WebSocket server support built on HttpCore</description>
+
+  <properties>
+    <Automatic-Module-Name>org.apache.httpcomponents.core5.websocket</Automatic-Module-Name>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.httpcomponents.core5</groupId>
+      <artifactId>httpcore5</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.httpcomponents.core5</groupId>
+      <artifactId>httpcore5-h2</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.platform</groupId>
+      <artifactId>junit-platform-launcher</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.hamcrest</groupId>
+      <artifactId>hamcrest</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+</project>