Artifactspublic-v0

curl

master
ply4 git calls78 ms291 KiB3 cachedprotocol v2
375 lines12 KiBRaw

HTTP3 (and QUIC)

Resources

HTTP/3 Explained - the online free book describing the protocols involved.

quicwg.org - home of the official protocol drafts

QUIC libraries

QUIC libraries we are using:

ngtcp2

quiche - EXPERIMENTAL

Experimental

HTTP/3 support using quiche in curl is considered EXPERIMENTAL until further notice. Only the ngtcp2 backend is not experimental.

Further development and tweaking of the HTTP/3 support in curl happens in the master branch using pull-requests like ordinary changes.

To fix before we remove the experimental label:

  • the used QUIC library needs to consider itself non-beta
  • it is fine to "leave" individual backends as experimental if necessary

ngtcp2 version

Building curl with ngtcp2 involves 3 components: ngtcp2 itself, nghttp3 and a QUIC supporting TLS library. The supported TLS libraries are covered below.

While any version of ngtcp2 and nghttp3 from 1.0.0 on are expected to work, using the latest versions often brings functional and performance improvements.

The build examples use $NGHTTP3_VERSION and $NGTCP2_VERSION as placeholders for the version you build.

Build with OpenSSL or fork

OpenSSL 3.5.0+ requires ngtcp2 1.12.0+. Earlier versions do not work.

Build OpenSSL (3.5.0+) or fork AWS-LC, BoringSSL, LibreSSL or quictls:

 # Instructions for OpenSSL 3.5.0+
 % git clone --depth 1 --branch openssl-$OPENSSL_VERSION https://github.com/openssl/openssl
 % cd openssl
 % ./config --prefix=/path/to/openssl --libdir=lib
 % make
 % make install

Build nghttp3:

 % cd ..
 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
 % cd nghttp3
 % git submodule update --init
 % autoreconf -fi
 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
 % make
 % make install

Build ngtcp2:

 % cd ..
 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
 % cd ngtcp2
 % autoreconf -fi
 # Change --with-openssl to --with-boringssl for AWS-LC and BoringSSL
 % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" \
   --prefix=/path/to/ngtcp2 --enable-lib-only --with-openssl
 % make
 % make install

Build curl (with autotools):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % autoreconf -fi
 % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" \
   --with-openssl=/path/to/openssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
 % make
 % make install

Build curl (with CMake):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld \
   -DOPENSSL_ROOT_DIR=/path/to/openssl -DUSE_NGTCP2=ON
 % cmake --build bld

Build with GnuTLS

Build GnuTLS:

 % git clone --depth 1 https://gitlab.com/gnutls/gnutls
 % cd gnutls
 % ./bootstrap
 % ./configure --prefix=/path/to/gnutls
 % make
 % make install

Build nghttp3:

 % cd ..
 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
 % cd nghttp3
 % git submodule update --init
 % autoreconf -fi
 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
 % make
 % make install

Build ngtcp2:

 % cd ..
 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
 % cd ngtcp2
 % autoreconf -fi
 % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/gnutls/lib" \
   --prefix=/path/to/ngtcp2 --enable-lib-only --with-gnutls
 % make
 % make install

Build curl (with autotools):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % autoreconf -fi
 % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig --with-gnutls=/path/to/gnutls --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
 % make
 % make install

Build curl (with CMake):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_GNUTLS=ON -DUSE_NGTCP2=ON
 % cmake --build bld

Build with wolfSSL

Build wolfSSL:

 % git clone --depth 1 https://github.com/wolfSSL/wolfssl
 % cd wolfssl
 % autoreconf -fi
 % ./configure --prefix=/path/to/wolfssl --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains
 % make
 % make install

Build nghttp3:

 % cd ..
 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
 % cd nghttp3
 % git submodule update --init
 % autoreconf -fi
 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
 % make
 % make install

Build ngtcp2:

 % cd ..
 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
 % cd ngtcp2
 % autoreconf -fi
 % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/wolfssl/lib" \
   --prefix=/path/to/ngtcp2 --enable-lib-only --with-wolfssl
 % make
 % make install

Build curl (with autotools):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % autoreconf -fi
 % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig --with-wolfssl=/path/to/wolfssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
 % make
 % make install

Build curl (with CMake):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_WOLFSSL=ON -DUSE_NGTCP2=ON
 % cmake --build bld

quiche version

quiche support is EXPERIMENTAL

Since the quiche build manages its dependencies, curl can be built against the latest version. You are probably able to build against their main branch, but in case of problems, we recommend their latest release tag.

Build

Build quiche and BoringSSL (described here for quiche 0.30.0, the locations where BoringSSL is to be found vary with version):

 % git clone --depth 1 --branch 0.30.0 --recursive https://github.com/cloudflare/quiche
 % cd quiche
 % cargo build --package quiche --release --features ffi,pkg-config-meta,qlog
 % ln -s libquiche.so target/release/libquiche.so.0
 % mkdir -p boringssl/lib
 % find target/release \( -name libcrypto.a -o -name libssl.a \) -exec ln -vnf -- '{}' boringssl/lib \;
 % find target/release/build/boring-sys-*/out/boringssl -maxdepth 1 \( -name include \) -exec ln -vsf -- '../{}' boringssl \;

Build curl (with autotools):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % autoreconf -fi
 % CC=clang ./configure --with-openssl=$PWD/../quiche/boringssl --with-quiche=$PWD/../quiche/target/release CFLAGS=-fPIC LDFLAGS=-lstdc++
 % make
 % make install

Build curl (with CMake):

 % cd ..
 % git clone --depth 1 https://github.com/curl/curl
 % cd curl
 % PKG_CONFIG_PATH=$PWD/../quiche/target/release CC=clang cmake -B bld -DOPENSSL_ROOT_DIR=$PWD/../quiche/boringssl -DOPENSSL_USE_STATIC_LIBS=ON -DUSE_QUICHE=ON
 % cmake --build bld

If the install step results in Permission denied error, you need to prepend it with sudo.

--http3

Use only HTTP/3:

 % curl --http3-only https://example.org:4433/

Use HTTP/3 with fallback to HTTP/2 or HTTP/1.1 (see "HTTPS eyeballing" below):

 % curl --http3 https://example.org:4433/

Upgrade via Alt-Svc:

 % curl --alt-svc altsvc.cache https://curl.se/

See this list of public HTTP/3 servers

HTTPS eyeballing

With option --http3 curl attempts earlier HTTP versions as well should the connect attempt via HTTP/3 fail "fast enough". This strategy is similar to IPv4/6 happy eyeballing where the alternate address family is used in parallel after a short delay.

The IPv4/6 eyeballing has a default of 200ms and you may override that via --happy-eyeballs-timeout-ms value. Since HTTP/3 is still relatively new, we decided to use this timeout also for the HTTP eyeballing - with a slight twist.

The happy-eyeballs-timeout-ms value is the hard timeout, meaning after that time expired, a TLS connection is opened in addition to negotiate HTTP/2 or HTTP/1.1. At half of that value - currently - is the soft timeout. The soft timeout fires, when there has been no data at all seen from the server on the HTTP/3 connection.

Without you specifying anything, the hard timeout is 200ms and the soft is 100ms:

  • Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection in less than 100ms.
  • When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
  • In the worst case, UDP replies start before 100ms, but drag on. This starts the TLS+TCP connection after 200ms.
  • When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.

The whole transfer only fails, when both QUIC and TLS+TCP fail to handshake or time out.

Note that all this happens in addition to IP version happy eyeballing. If the name resolution for the server gives more than one IP address, curl tries all those until one succeeds - as with all other protocols. If those IP addresses contain both IPv6 and IPv4, those attempts happen, delayed, in parallel (the actual eyeballing).

Known Bugs

Check out the list of known HTTP3 bugs.

HTTP/3 Test server

This is not advice on how to run anything in production. This is for development and experimenting.

Prerequisite(s)

An existing local HTTP/1.1 server that hosts files. Preferably also a few huge ones. You can easily create huge local files like truncate -s=8G 8GB - they are huge but do not occupy that much space on disk since they are big holes.

In a Debian setup you can install apache2. It runs on port 80 and has a document root in /var/www/html. Download the 8GB file from apache with curl localhost/8GB -o dev/null

In this description we setup and run an HTTP/3 reverse-proxy in front of the HTTP/1 server.

Setup

You can select either or both of these server solutions.

nghttpx

Get, build and install quictls, nghttp3 and ngtcp2 as described above.

Get, build and install nghttp2:

 % git clone --depth 1 https://github.com/nghttp2/nghttp2
 % cd nghttp2
 % autoreconf -fi
 % PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/quictls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig \
   LDFLAGS=-L/path/to/quictls/lib CFLAGS=-I/path/to/quictls/include ./configure --enable-maintainer-mode \
   --prefix=/path/to/nghttp2 --disable-shared --enable-app --enable-http3 --without-jemalloc --without-libxml2 --without-systemd
 % make && make install

Run the local h3 server on port 9443, make it proxy all traffic through to HTTP/1 on localhost port 80. For local toying, we can use the test cert that exists in curl's test dir.

 % CERT=/path/to/stunnel.pem
 % $HOME/bin/nghttpx $CERT $CERT --backend=localhost,80 \
   --frontend="localhost,9443;quic"

Caddy

Install Caddy. For easiest use, the binary should be either in your PATH or your current directory.

Create a Caddyfile with the following content:

localhost:7443 {
  respond "Hello, world! you are using {http.request.proto}"
}

Then run Caddy:

 % ./caddy start

Making requests to https://localhost:7443 should tell you which protocol is being used.

You can change the hard-coded response to something more useful by replacing respond with reverse_proxy or file_server, for example: reverse_proxy localhost:80

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# HTTP3 (and QUIC)
9## Resources
11[HTTP/3 Explained](https://http3-explained.haxx.se/en/) - the online free
12book describing the protocols involved.
14[quicwg.org](https://quicwg.org/) - home of the official protocol drafts
16## QUIC libraries
18QUIC libraries we are using:
20[ngtcp2](https://github.com/ngtcp2/ngtcp2)
22[quiche](https://github.com/cloudflare/quiche) - **EXPERIMENTAL**
24## Experimental
26HTTP/3 support using *quiche* in curl is considered **EXPERIMENTAL** until
27further notice. Only the *ngtcp2* backend is not experimental.
29Further development and tweaking of the HTTP/3 support in curl happens in the
30master branch using pull-requests like ordinary changes.
32To fix before we remove the experimental label:
34- the used QUIC library needs to consider itself non-beta
35- it is fine to "leave" individual backends as experimental if necessary
37# ngtcp2 version
39Building curl with ngtcp2 involves 3 components: `ngtcp2` itself, `nghttp3`
40and a QUIC supporting TLS library. The supported TLS libraries are covered
41below.
43While any version of `ngtcp2` and `nghttp3` from 1.0.0 on are expected to
44work, using the latest versions often brings functional and performance
45improvements.
47The build examples use `$NGHTTP3_VERSION` and `$NGTCP2_VERSION` as
48placeholders for the version you build.
50## Build with OpenSSL or fork
52OpenSSL 3.5.0+ requires *ngtcp2* 1.12.0+. Earlier versions do not work.
54Build OpenSSL (3.5.0+) or fork AWS-LC, BoringSSL, LibreSSL or quictls:
56 # Instructions for OpenSSL 3.5.0+
57 % git clone --depth 1 --branch openssl-$OPENSSL_VERSION https://github.com/openssl/openssl
58 % cd openssl
59 % ./config --prefix=/path/to/openssl --libdir=lib
60 % make
61 % make install
63Build nghttp3:
65 % cd ..
66 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
67 % cd nghttp3
68 % git submodule update --init
69 % autoreconf -fi
70 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
71 % make
72 % make install
74Build ngtcp2:
76 % cd ..
77 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
78 % cd ngtcp2
79 % autoreconf -fi
80 # Change --with-openssl to --with-boringssl for AWS-LC and BoringSSL
81 % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" \
82 --prefix=/path/to/ngtcp2 --enable-lib-only --with-openssl
83 % make
84 % make install
86Build curl (with autotools):
88 % cd ..
89 % git clone --depth 1 https://github.com/curl/curl
90 % cd curl
91 % autoreconf -fi
92 % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" \
93 --with-openssl=/path/to/openssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
94 % make
95 % make install
97Build curl (with CMake):
99 % cd ..
100 % git clone --depth 1 https://github.com/curl/curl
101 % cd curl
102 % PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld \
103 -DOPENSSL_ROOT_DIR=/path/to/openssl -DUSE_NGTCP2=ON
104 % cmake --build bld
106## Build with GnuTLS
108Build GnuTLS:
110 % git clone --depth 1 https://gitlab.com/gnutls/gnutls
111 % cd gnutls
112 % ./bootstrap
113 % ./configure --prefix=/path/to/gnutls
114 % make
115 % make install
117Build nghttp3:
119 % cd ..
120 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
121 % cd nghttp3
122 % git submodule update --init
123 % autoreconf -fi
124 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
125 % make
126 % make install
128Build ngtcp2:
130 % cd ..
131 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
132 % cd ngtcp2
133 % autoreconf -fi
134 % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/gnutls/lib" \
135 --prefix=/path/to/ngtcp2 --enable-lib-only --with-gnutls
136 % make
137 % make install
139Build curl (with autotools):
141 % cd ..
142 % git clone --depth 1 https://github.com/curl/curl
143 % cd curl
144 % autoreconf -fi
145 % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig --with-gnutls=/path/to/gnutls --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
146 % make
147 % make install
149Build curl (with CMake):
151 % cd ..
152 % git clone --depth 1 https://github.com/curl/curl
153 % cd curl
154 % PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_GNUTLS=ON -DUSE_NGTCP2=ON
155 % cmake --build bld
157## Build with wolfSSL
159Build wolfSSL:
161 % git clone --depth 1 https://github.com/wolfSSL/wolfssl
162 % cd wolfssl
163 % autoreconf -fi
164 % ./configure --prefix=/path/to/wolfssl --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains
165 % make
166 % make install
168Build nghttp3:
170 % cd ..
171 % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
172 % cd nghttp3
173 % git submodule update --init
174 % autoreconf -fi
175 % ./configure --prefix=/path/to/nghttp3 --enable-lib-only
176 % make
177 % make install
179Build ngtcp2:
181 % cd ..
182 % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
183 % cd ngtcp2
184 % autoreconf -fi
185 % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/wolfssl/lib" \
186 --prefix=/path/to/ngtcp2 --enable-lib-only --with-wolfssl
187 % make
188 % make install
190Build curl (with autotools):
192 % cd ..
193 % git clone --depth 1 https://github.com/curl/curl
194 % cd curl
195 % autoreconf -fi
196 % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig --with-wolfssl=/path/to/wolfssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
197 % make
198 % make install
200Build curl (with CMake):
202 % cd ..
203 % git clone --depth 1 https://github.com/curl/curl
204 % cd curl
205 % PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_WOLFSSL=ON -DUSE_NGTCP2=ON
206 % cmake --build bld
208# quiche version
210quiche support is **EXPERIMENTAL**
212Since the quiche build manages its dependencies, curl can be built against the
213latest version. You are *probably* able to build against their main branch,
214but in case of problems, we recommend their latest release tag.
216## Build
218Build quiche and BoringSSL (described here for quiche 0.30.0, the locations
219where BoringSSL is to be found vary with version):
221 % git clone --depth 1 --branch 0.30.0 --recursive https://github.com/cloudflare/quiche
222 % cd quiche
223 % cargo build --package quiche --release --features ffi,pkg-config-meta,qlog
224 % ln -s libquiche.so target/release/libquiche.so.0
225 % mkdir -p boringssl/lib
226 % find target/release \( -name libcrypto.a -o -name libssl.a \) -exec ln -vnf -- '{}' boringssl/lib \;
227 % find target/release/build/boring-sys-*/out/boringssl -maxdepth 1 \( -name include \) -exec ln -vsf -- '../{}' boringssl \;
229Build curl (with autotools):
231 % cd ..
232 % git clone --depth 1 https://github.com/curl/curl
233 % cd curl
234 % autoreconf -fi
235 % CC=clang ./configure --with-openssl=$PWD/../quiche/boringssl --with-quiche=$PWD/../quiche/target/release CFLAGS=-fPIC LDFLAGS=-lstdc++
236 % make
237 % make install
239Build curl (with CMake):
241 % cd ..
242 % git clone --depth 1 https://github.com/curl/curl
243 % cd curl
244 % PKG_CONFIG_PATH=$PWD/../quiche/target/release CC=clang cmake -B bld -DOPENSSL_ROOT_DIR=$PWD/../quiche/boringssl -DOPENSSL_USE_STATIC_LIBS=ON -DUSE_QUICHE=ON
245 % cmake --build bld
247If the install step results in `Permission denied` error, you need to prepend
248it with `sudo`.
250# `--http3`
252Use only HTTP/3:
254 % curl --http3-only https://example.org:4433/
256Use HTTP/3 with fallback to HTTP/2 or HTTP/1.1 (see "HTTPS eyeballing" below):
258 % curl --http3 https://example.org:4433/
260Upgrade via Alt-Svc:
262 % curl --alt-svc altsvc.cache https://curl.se/
264See this [list of public HTTP/3 servers](https://bagder.github.io/HTTP3-test/)
266### HTTPS eyeballing
268With option `--http3` curl attempts earlier HTTP versions as well should the
269connect attempt via HTTP/3 fail "fast enough". This strategy is similar
270to IPv4/6 happy eyeballing where the alternate address family is used in
271parallel after a short delay.
273The IPv4/6 eyeballing has a default of 200ms and you may override that via
274`--happy-eyeballs-timeout-ms value`. Since HTTP/3 is still relatively new, we
275decided to use this timeout also for the HTTP eyeballing - with a slight
276twist.
278The `happy-eyeballs-timeout-ms` value is the **hard** timeout, meaning after
279that time expired, a TLS connection is opened in addition to negotiate HTTP/2
280or HTTP/1.1. At half of that value - currently - is the **soft** timeout. The
281soft timeout fires, when there has been **no data at all** seen from the
282server on the HTTP/3 connection.
284Without you specifying anything, the hard timeout is 200ms and the soft is
285100ms:
287* Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection
288 in less than 100ms.
289* When QUIC is not supported (or UDP does not work for this network path), no
290 reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
291* In the worst case, UDP replies start before 100ms, but drag on. This starts
292 the TLS+TCP connection after 200ms.
293* When the QUIC handshake fails, the TLS+TCP connection is attempted right
294 away. For example, when the QUIC server presents the wrong certificate.
296The whole transfer only fails, when **both** QUIC and TLS+TCP fail to
297handshake or time out.
299Note that all this happens in addition to IP version happy eyeballing. If the
300name resolution for the server gives more than one IP address, curl tries all
301those until one succeeds - as with all other protocols. If those IP addresses
302contain both IPv6 and IPv4, those attempts happen, delayed, in parallel (the
303actual eyeballing).
305## Known Bugs
307Check out the [list of known HTTP3 bugs](https://curl.se/docs/knownbugs.html#HTTP3).
309# HTTP/3 Test server
311This is not advice on how to run anything in production. This is for
312development and experimenting.
314## Prerequisite(s)
316An existing local HTTP/1.1 server that hosts files. Preferably also a few huge
317ones. You can easily create huge local files like `truncate -s=8G 8GB` - they
318are huge but do not occupy that much space on disk since they are big holes.
320In a Debian setup you can install apache2. It runs on port 80 and has a
321document root in `/var/www/html`. Download the 8GB file from apache with `curl
322localhost/8GB -o dev/null`
324In this description we setup and run an HTTP/3 reverse-proxy in front of the
325HTTP/1 server.
327## Setup
329You can select either or both of these server solutions.
331### nghttpx
333Get, build and install quictls, nghttp3 and ngtcp2 as described
334above.
336Get, build and install nghttp2:
338 % git clone --depth 1 https://github.com/nghttp2/nghttp2
339 % cd nghttp2
340 % autoreconf -fi
341 % PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/quictls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig \
342 LDFLAGS=-L/path/to/quictls/lib CFLAGS=-I/path/to/quictls/include ./configure --enable-maintainer-mode \
343 --prefix=/path/to/nghttp2 --disable-shared --enable-app --enable-http3 --without-jemalloc --without-libxml2 --without-systemd
344 % make && make install
346Run the local h3 server on port 9443, make it proxy all traffic through to
347HTTP/1 on localhost port 80. For local toying, we can use the test cert that
348exists in curl's test dir.
350 % CERT=/path/to/stunnel.pem
351 % $HOME/bin/nghttpx $CERT $CERT --backend=localhost,80 \
352 --frontend="localhost,9443;quic"
354### Caddy
356[Install Caddy](https://caddyserver.com/docs/install). For easiest use, the
357binary should be either in your PATH or your current directory.
359Create a `Caddyfile` with the following content:
360~~~
361localhost:7443 {
362 respond "Hello, world! you are using {http.request.proto}"
364~~~
366Then run Caddy:
368 % ./caddy start
370Making requests to `https://localhost:7443` should tell you which protocol is
371being used.
373You can change the hard-coded response to something more useful by replacing
374`respond` with `reverse_proxy` or `file_server`, for example: `reverse_proxy
375localhost:80`
Diagnostics4 git calls · 78 ms
CallStatusSizeTime078 ms
discover200152 B25 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=25
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit49 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=24
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=24
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2004.2 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=25
git.response.bytes=4250
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.wants=c913aebd2457901227e40a1870b582a23574ccbb
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4250
git.pkt.payload.max=4229
git.sideband.band1.bytes=4228
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e98e94cbf1cf3e
Request
afdf614e…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format