Add :protocol pseudo-header support for Extended CONNECT (RFC 9220) (#15771)

Netty's HTTP/3 codec currently only recognizes the standard
pseudo-headers (`:method`, `:scheme`, `:authority`, `:path`, `:status`),
but RFC 9220 defines an additional `:protocol` pseudo-header for
Extended CONNECT requests. This prevents applications from implementing
WebTransport over HTTP/3 and WebSocket over HTTP/3.

- Added `PROTOCOL` enum value to `Http3Headers.PseudoHeaderName`
- Added `protocol()` getter and `protocol(CharSequence)` setter to
`Http3Headers` interface
- Implemented protocol methods in `DefaultHttp3Headers`
- Enhanced `Http3HeadersSink` validation to distinguish between:
  - Regular CONNECT (requires `:method`, `:authority`)
- Extended CONNECT (requires `:method`, `:scheme`, `:authority`,
`:path`, `:protocol`)

- Extended CONNECT requests with `:protocol` header are now accepted
- WebTransport over HTTP/3 implementations can use Netty's HTTP/3 codec
- WebSocket over HTTP/3 (RFC 9220) is now supported
- Fully backward compatible with existing CONNECT requests

- [RFC 9220: Bootstrapping WebSockets with
HTTP/3](https://www.rfc-editor.org/rfc/rfc9220.html)
- [WebTransport over HTTP/3
(draft-ietf-webtrans-http3)](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/)
- [RFC 9114: HTTP/3](https://www.rfc-editor.org/rfc/rfc9114.html)
Section 4.4

Co-authored-by: Paul Gregoire <mondain@gmail.com>

Author: normanmaurer

src/main/java/io/netty/incubator/codec/http3/Http3Headers.java

@@ -51,7 +51,18 @@ enum PseudoHeaderName {
         /**
          * {@code :status}.
          */
-        STATUS(":status", false, 0x10);
+        STATUS(":status", false, 0x10),
+
+        /**
+         * {@code :protocol}.
+         * <p>
+         * Used for Extended CONNECT requests as defined in RFC 9220.
+         * This pseudo-header is only valid for CONNECT requests and indicates
+         * the desired protocol for the connection (e.g., "webtransport", "websocket").
+         *
+         * @see <a href="https://www.rfc-editor.org/rfc/rfc9220.html">RFC 9220: Bootstrapping WebSockets with HTTP/3</a>
+         */
+        PROTOCOL(":protocol", true, 0x20);
 
         private static final char PSEUDO_HEADER_PREFIX = ':';
         private static final byte PSEUDO_HEADER_PREFIX_BYTE = (byte) PSEUDO_HEADER_PREFIX;
@@ -184,6 +195,21 @@ public int getFlag() {
      */
     Http3Headers status(CharSequence value);
 
+    /**
+     * Sets the {@link PseudoHeaderName#PROTOCOL} header
+     * <p>
+     * This pseudo-header is used for Extended CONNECT requests as defined in RFC 9220.
+     * Common values include "webtransport" and "websocket".
+     *
+     * @param value the value for the header.
+     * @return      this instance itself.
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9220.html">RFC 9220: Bootstrapping WebSockets with HTTP/3</a>
+     */
+    default Http3Headers protocol(CharSequence value) {
+        set(PseudoHeaderName.PROTOCOL.value(), value);
+        return this;
+    }
+
     /**
      * Gets the {@link PseudoHeaderName#METHOD} header or {@code null} if there is no such header
      *
@@ -224,6 +250,19 @@ public int getFlag() {
     @Nullable
     CharSequence status();
 
+    /**
+     * Gets the {@link PseudoHeaderName#PROTOCOL} header or {@code null} if there is no such header
+     * <p>
+     * This pseudo-header is used for Extended CONNECT requests as defined in RFC 9220.
+     *
+     * @return the value of the header.
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9220.html">RFC 9220: Bootstrapping WebSockets with HTTP/3</a>
+     */
+    @Nullable
+    default CharSequence protocol() {
+        return get(PseudoHeaderName.PROTOCOL.value());
+    }
+
     /**
      * Returns {@code true} if a header with the {@code name} and {@code value} exists, {@code false} otherwise.
      * <p>

src/main/java/io/netty/incubator/codec/http3/Http3HeadersSink.java

@@ -23,6 +23,7 @@
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.AUTHORITY;
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.METHOD;
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.PATH;
+import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.PROTOCOL;
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.SCHEME;
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.STATUS;
 import static io.netty.incubator.codec.http3.Http3Headers.PseudoHeaderName.getPseudoHeader;
@@ -76,12 +77,29 @@ void finish() throws Http3HeadersValidationException, Http3Exception {
                 CharSequence method = headers.method();
                 // fast-path
                 if (HttpMethod.CONNECT.asciiName().contentEqualsIgnoreCase(method)) {
-                    // For CONNECT we must only include:
-                    // - :method
-                    // - :authority
-                    final int requiredPseudoHeaders = METHOD.getFlag() | AUTHORITY.getFlag();
-                    if (receivedPseudoHeaders != requiredPseudoHeaders) {
-                        throw new Http3HeadersValidationException("Not all mandatory pseudo-headers included.");
+                    // Check if this is an Extended CONNECT request (RFC 9220)
+                    // Extended CONNECT includes the :protocol pseudo-header
+                    if ((receivedPseudoHeaders & PROTOCOL.getFlag()) != 0) {
+                        // Extended CONNECT (RFC 9220) requires:
+                        // - :method
+                        // - :scheme
+                        // - :authority
+                        // - :path
+                        // - :protocol
+                        final int requiredPseudoHeaders = METHOD.getFlag() | SCHEME.getFlag() |
+                                AUTHORITY.getFlag() | PATH.getFlag() | PROTOCOL.getFlag();
+                        if (receivedPseudoHeaders != requiredPseudoHeaders) {
+                            throw new Http3HeadersValidationException(
+                                    "Not all mandatory pseudo-headers included for Extended CONNECT.");
+                        }
+                    } else {
+                        // Regular CONNECT (RFC 9114) requires:
+                        // - :method
+                        // - :authority
+                        final int requiredPseudoHeaders = METHOD.getFlag() | AUTHORITY.getFlag();
+                        if (receivedPseudoHeaders != requiredPseudoHeaders) {
+                            throw new Http3HeadersValidationException("Not all mandatory pseudo-headers included.");
+                        }
                     }
                 } else if (HttpMethod.OPTIONS.asciiName().contentEqualsIgnoreCase(method)) {
                     // See:

src/main/java/io/netty/incubator/codec/http3/Http3SettingsFrame.java

@@ -40,6 +40,12 @@ public interface Http3SettingsFrame extends Http3ControlStreamFrame, Iterable<Ma
      */
     long HTTP3_SETTINGS_MAX_FIELD_SECTION_SIZE = 0x6;
 
+    /**
+     * See <a href="https://www.rfc-editor.org/rfc/rfc9220.html#section-5">
+     *     SETTINGS_ENABLE_CONNECT_PROTOCOL</a>.
+     */
+    long HTTP3_SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x8;
+
     @Override
     default long type() {
         return Http3CodecUtils.HTTP3_SETTINGS_FRAME_TYPE;