HTTP/3: add proxy CONNECT and MASQUE CONNECT-UDP support (ngtcp2 QUIC)

This patch adds two major proxy capabilities to curl (ngtcp2 QUIC):
- HTTP/3 Proxy CONNECT: Tunnel HTTP/1.1 or HTTP/2 traffic through an
  HTTPS proxy that speaks HTTP/3 (QUIC) using the standard CONNECT
  method over an HTTP/3 connection.
- MASQUE CONNECT-UDP: Tunnel HTTP/3 (QUIC) traffic through an HTTP
  proxy (speaking HTTP/1.1, HTTP/2, or HTTP/3) using the extended
  CONNECT method with the CONNECT-UDP protocol (RFC9297 & RFC9298).

Public API additions:
- `CURLPROXY_HTTPS3`: new proxy type constant for HTTP/3 proxy
- `--proxy-http3`: new CLI flag to negotiate HTTP/3 with HTTPS proxy

The implementation adds two new filters:
- `H3-PROXY` - enables negotiating HTTP/3 (QUIC) to the proxy and
  running CONNECT/CONNECT-UDP through that proxy transport.
- `CAPSULE` - dedicated filter inserted between QUIC transport and
  HTTP-PROXY to handle datagram capsule encapsulation/decapsulation.

Here is how the curl filter chaining looks in different scenarios:
- HTTP/3 Proxy CONNECT (tunneling TCP protocols over QUIC proxy):
  conn -> HTTP/1.1 or HTTP/2  -> SSL -> HTTP-PROXY ->
                                 H3-PROXY -> HAPPY-EYEBALLS -> UDP
- MASQUE CONNECT-UDP (tunneling QUIC over any proxy):
  conn -> HTTP/3 -> CAPSULE -> HTTP-PROXY -> H3-PROXY ->
                               HAPPY-EYEBALLS -> UDP
  conn -> HTTP/3 -> CAPSULE -> HTTP-PROXY -> H1-PROXY or H2-PROXY ->
                               SSL -> HAPPY-EYEBALLS -> TCP

- Both features currently require the ngtcp2 QUIC backend.
- Both features are experimental (disabled by default). Enable with
  `--enable-proxy-http3`(autotools) or `-DUSE_PROXY_HTTP3=ON`(CMake).

Tests:
- tests/unit/unit3400.c: Unit tests for capsule protocol encode/decode
- tests/http/test_60_h3_proxy.py: Comprehensive pytest integration suite
- tests/http/testenv/h2o.py: Managing h2o instances with HTTP/1.1, HTTP/2,
  and HTTP/3 (QUIC) listeners, proxy.connect and proxy.connect-udp enabled.

References:
  RFC 9297 - HTTP Datagrams and the Capsule Protocol
  RFC 9298 - Proxying UDP in HTTP
  RFC 9000 §16 — Variable-Length Integer Encoding

Signed-off-by: Aritra Basu <aritrbas+gh@cisco.com>

Closes #21153

docs/EXPERIMENTAL.md

@@ -43,6 +43,16 @@ Graduation requirements:
 
 - Using HTTP/3 with the given build should perform without risking busy-loops
 
+### HTTP/3 proxy and CONNECT-UDP support
+
+Support for HTTP/3 proxy and CONNECT-UDP tunneling is experimental and
+requires an explicit build-time opt-in (`--enable-proxy-http3` for
+autotools, `-DUSE_PROXY_HTTP3=ON` for CMake).
+
+Graduation requirements:
+
+- implementation stability over time with no known severe regressions
+
 ### The Rustls backend
 
 Graduation requirements:

docs/INSTALL-CMAKE.md

@@ -254,6 +254,7 @@ target_link_libraries(my_target PRIVATE CURL::libcurl)
 - `USE_SSLS_EXPORT`:                        Enable experimental SSL session import/export. Default: `OFF`
 - `USE_WIN32_IDN`:                          Use WinIDN for IDN support. Default: `OFF`
 - `USE_WIN32_LDAP`:                         Use Windows LDAP implementation. Default: `ON`
+- `USE_PROXY_HTTP3`:                        Enable experimental HTTP/3 proxy support. Default: `OFF`
 
 ## Disabling features
 

docs/cmdline-opts/Makefile.inc

@@ -212,6 +212,7 @@ DPAGES = \
   proxy-digest.md \
   proxy-header.md \
   proxy-http2.md \
+  proxy-http3.md \
   proxy-insecure.md \
   proxy-key-type.md \
   proxy-key.md \

docs/cmdline-opts/proxy-http2.md

@@ -5,7 +5,7 @@ Long: proxy-http2
 Tags: Versions HTTP/2
 Protocols: HTTP
 Added: 8.1.0
-Mutexed:
+Mutexed: proxy-http3
 Requires: HTTP/2
 Help: Use HTTP/2 with HTTPS proxy
 Category: http proxy
@@ -22,3 +22,5 @@ Negotiate HTTP/2 with an HTTPS proxy. The proxy might still only offer HTTP/1
 and then curl sticks to using that version.
 
 This has no effect for any other kinds of proxies.
+
+This option is mutually exclusive with `--proxy-http3`.

docs/cmdline-opts/proxy-http3.md

@@ -0,0 +1,31 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Long: proxy-http3
+Tags: Versions HTTP/3
+Protocols: HTTP
+Added: 8.21.0
+Mutexed: proxy-http2
+Requires: HTTP/3
+Help: Use HTTP/3 with HTTPS proxy
+Category: http proxy
+Multi: boolean
+See-also:
+  - proxy
+  - proxy-http2
+Example:
+  - --proxy-http3 -x proxy $URL
+---
+
+# `--proxy-http3`
+
+Negotiate HTTP/3 with an HTTPS proxy.
+Fails to perform the transfer if the given proxy does not support HTTP/3.
+
+This has no effect for any other kinds of proxies.
+
+This option is mutually exclusive with `--proxy-http2`.
+
+This feature is experimental and requires a build with HTTP/3 proxy support
+enabled. For autotools builds, use `--enable-proxy-http3`. For CMake builds,
+use `-DUSE_PROXY_HTTP3=ON`.

docs/internals/CONNECTION-FILTERS.md

@@ -156,9 +156,9 @@ The currently existing filter types (curl 8.5.0) are:
   `accept()`ed in a `listen()`
 * `SSL`: filter that applies TLS en-/decryption and handshake. Manages the
   underlying TLS backend implementation.
-* `HTTP-PROXY`, `H1-PROXY`, `H2-PROXY`: the first manages the connection to an
-  HTTP proxy server and uses the other depending on which ALPN protocol has
-  been negotiated.
+* `HTTP-PROXY`, `H1-PROXY`, `H2-PROXY`, `H3-PROXY`: the first manages the
+   connection to an HTTP proxy server and uses the other depending on which
+   ALPN protocol has been negotiated.
 * `SOCKS-PROXY`: filter for the various SOCKS proxy protocol variations
 * `HAPROXY`: filter for the protocol of the same name, providing client IP
   information to a server.
@@ -166,7 +166,7 @@ The currently existing filter types (curl 8.5.0) are:
   connection
 * `HTTP/3`: filter for handling multiplexed transfers over an HTTP/3+QUIC
   connection
-* `HAPPY-EYEBALLS`: meta filter that implements IPv4/IPv6 "happy eyeballing".
+* `HAPPY-EYEBALLS`: meta filter that implements IPv4/IPv6 "happy eyeballs".
   It creates up to 2 sub-filters that race each other for a connection.
 * `SETUP`: meta filter that manages the creation of sub-filter chains for a
   specific transport (e.g. TCP or QUIC).
@@ -220,6 +220,37 @@ as an `SSL` flagged filter is seen first. `conn3` is also encrypted as the
 
 Similar checks can determine if a connection is multiplexed or not.
 
+## Adding CONNECT-UDP support
+HTTP/3 on top of HTTP/1.1 (MASQUE CONNECT-UDP):
+```
+conn --> HTTP/3 --> CAPSULE --> HTTP-PROXY --> H1-PROXY --> SSL --> HAPPY-EYEBALLS --> TCP
+```
+
+HTTP/3 on top of HTTP/2 (MASQUE CONNECT-UDP):
+```
+conn --> HTTP/3 --> CAPSULE --> HTTP-PROXY --> H2-PROXY --> SSL --> HAPPY-EYEBALLS --> TCP
+```
+
+The CAPSULE filter handles RFC 9297 capsule protocol encapsulation and
+decapsulation of UDP datagrams. It is inserted automatically when the
+HTTP-PROXY filter completes a successful CONNECT-UDP tunnel.
+
+## Adding H3-PROXY support
+HTTP/1.1 on top of HTTP/3 (CONNECT over QUIC):
+```
+conn --> HTTP/1.1 --> SSL --> HTTP-PROXY --> H3-PROXY --> HAPPY-EYEBALLS --> UDP
+```
+
+HTTP/2 on top of HTTP/3 (CONNECT over QUIC):
+```
+conn --> HTTP/2 --> SSL --> HTTP-PROXY --> H3-PROXY --> HAPPY-EYEBALLS --> UDP
+```
+
+HTTP/3 on top of HTTP/3 (MASQUE CONNECT-UDP over QUIC):
+```
+conn --> HTTP/3 --> CAPSULE --> HTTP-PROXY --> H3-PROXY --> HAPPY-EYEBALLS --> UDP
+```
+
 ## Filter Tracing
 
 Filters may make use of special trace macros like `CURL_TRC_CF(data, cf, msg,

docs/libcurl/curl_version_info.md

@@ -298,6 +298,13 @@ supports HTTP NTLM
 libcurl was built with support for NTLM delegation to a winbind helper. This
 feature was removed from curl in 8.8.0.
 
+## `PROXY-HTTP3`
+
+*features* mask bit: non-existent
+
+libcurl was built with EXPERIMENTAL support for HTTP/3 proxy tunneling
+(Added in 8.21.0)
+
 ## `PSL`
 
 *features* mask bit: CURL_VERSION_PSL

docs/libcurl/opts/CURLOPT_PROXY.md

@@ -58,7 +58,11 @@ HTTPS Proxy. (with OpenSSL, GnuTLS, mbedTLS, Rustls, Schannel or wolfSSL.)
 This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to
 **CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy.
 
-## `socks4://`
+Setting CURLOPT_PROXYTYPE(3) to **CURLPROXY_HTTPS3** allows libcurl to
+negotiate using HTTP/3 with proxy. This feature is experimental and requires
+a build with HTTP/3 proxy support enabled.
+
+## socks4://
 
 SOCKS4 Proxy.
 

docs/libcurl/opts/CURLOPT_PROXYTYPE.md

@@ -41,6 +41,12 @@ HTTPS Proxy using HTTP/1. (Added in 7.52.0 for OpenSSL and GnuTLS. Since
 
 HTTPS Proxy and attempt to speak HTTP/2 over it. (Added in 8.1.0)
 
+## CURLPROXY_HTTPS3
+
+HTTPS Proxy and attempt to speak HTTP/3 over it. (Added in 8.21.0)
+This feature is experimental and requires a build with HTTP/3 proxy support
+enabled.
+
 ## CURLPROXY_HTTP_1_0
 
 HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for

docs/libcurl/symbols-in-versions

@@ -993,6 +993,7 @@ CURLPROXY_HTTP                  7.10
 CURLPROXY_HTTP_1_0              7.19.4
 CURLPROXY_HTTPS                 7.52.0
 CURLPROXY_HTTPS2                8.1.0
+CURLPROXY_HTTPS3                8.21.0
 CURLPROXY_SOCKS4                7.10
 CURLPROXY_SOCKS4A               7.18.0
 CURLPROXY_SOCKS5                7.10

docs/options-in-versions

@@ -177,6 +177,7 @@
 --proxy-digest                       7.12.0
 --proxy-header                       7.37.0
 --proxy-http2                        8.1.0
+--proxy-http3                        8.21.0
 --proxy-insecure                     7.52.0
 --proxy-key                          7.52.0
 --proxy-key-type                     7.52.0

docs/tests/HTTP.md

@@ -62,6 +62,9 @@ Via curl's `configure` script you may specify:
   * `--with-test-nghttpx=<path-of-nghttpx>` if you have nghttpx to use
    somewhere outside your `$PATH`.
 
+  * `--with-test-h2o=<path-of-h2o>` if you have h2o to use somewhere
+   outside your `$PATH`.
+
   * `--with-test-httpd=<httpd-install-path>` if you have an Apache httpd
    installed somewhere else. On Debian/Ubuntu it otherwise looks into
    `/usr/bin` and `/usr/sbin` to find those.