]> git.ipfire.org Git - thirdparty/curl.git/commit
HTTP/3: add proxy CONNECT and MASQUE CONNECT-UDP support (ngtcp2 QUIC)
authorAritra Basu <aritrbas+gh@cisco.com>
Mon, 27 Apr 2026 23:35:38 +0000 (19:35 -0400)
committerDaniel Stenberg <daniel@haxx.se>
Wed, 27 May 2026 06:49:53 +0000 (08:49 +0200)
commite78b1b3eccfa6a2e367a1225ea1b66dafcdac3c4
treeef1e81c77bd6f059bd9ad613a5d31224b7dae741
parentefc3f2309e1c87c67700350f7df8da508cd307cd
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
66 files changed:
.github/scripts/pyspelling.words
CMakeLists.txt
configure.ac
docs/EXPERIMENTAL.md
docs/INSTALL-CMAKE.md
docs/cmdline-opts/Makefile.inc
docs/cmdline-opts/proxy-http2.md
docs/cmdline-opts/proxy-http3.md [new file with mode: 0644]
docs/internals/CONNECTION-FILTERS.md
docs/libcurl/curl_version_info.md
docs/libcurl/opts/CURLOPT_PROXY.md
docs/libcurl/opts/CURLOPT_PROXYTYPE.md
docs/libcurl/symbols-in-versions
docs/options-in-versions
docs/tests/HTTP.md
include/curl/curl.h
lib/Makefile.inc
lib/capsule.c [new file with mode: 0644]
lib/capsule.h [new file with mode: 0644]
lib/cf-capsule.c [new file with mode: 0644]
lib/cf-capsule.h [new file with mode: 0644]
lib/cf-h1-proxy.c
lib/cf-h1-proxy.h
lib/cf-h2-proxy.c
lib/cf-h2-proxy.h
lib/cf-h3-proxy.c [new file with mode: 0644]
lib/cf-h3-proxy.h [new file with mode: 0644]
lib/cf-ip-happy.c
lib/cf-ip-happy.h
lib/connect.c
lib/curl_config-cmake.h.in
lib/curl_trc.c
lib/http.c
lib/http.h
lib/http2.c
lib/http_proxy.c
lib/http_proxy.h
lib/peer.c
lib/peer.h
lib/setopt.c
lib/url.c
lib/version.c
lib/vquic/curl_ngtcp2.c
lib/vquic/curl_ngtcp2.h
lib/vquic/curl_quiche.c
lib/vquic/vquic-tls.c
lib/vquic/vquic.c
lib/vquic/vquic.h
lib/vtls/openssl.c
lib/vtls/vtls.c
lib/vtls/vtls_int.h
src/tool_getparam.c
src/tool_getparam.h
src/tool_listhelp.c
tests/data/Makefile.am
tests/data/test3400 [new file with mode: 0644]
tests/http/CMakeLists.txt
tests/http/Makefile.am
tests/http/config.ini.in
tests/http/conftest.py
tests/http/test_60_h3_proxy.py [new file with mode: 0644]
tests/http/testenv/curl.py
tests/http/testenv/env.py
tests/http/testenv/h2o.py [new file with mode: 0644]
tests/unit/Makefile.inc
tests/unit/unit3400.c [new file with mode: 0644]