diff options
Diffstat (limited to 'docs/HTTP3.md')
| -rw-r--r-- | docs/HTTP3.md | 44 |
1 files changed, 39 insertions, 5 deletions
diff --git a/docs/HTTP3.md b/docs/HTTP3.md index f1cb9648f..dc1befee4 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -15,7 +15,7 @@ QUIC libraries we are experimenting with: [quiche](https://github.com/cloudflare/quiche) -[msquic](https://github.com/microsoft/msquic) & [msh3](https://github.com/nibanks/msh3) +[msh3](https://github.com/nibanks/msh3) (with [msquic](https://github.com/microsoft/msquic)) ## Experimental @@ -25,13 +25,21 @@ notice. It needs to be enabled at build-time. Further development and tweaking of the HTTP/3 support in curl will happen in the master branch using pull-requests, just like ordinary changes. +To fix before we remove the experimental label: + + - working multiplexing and GTFO handling + - fallback or another flexible way to go (back to) h1/h2 if h3 fails + - enough test cases to verify basic HTTP/3 functionality + - no "important" bugs left on HTTP/3 + - it's fine to "leave" individual backends as experimental if necessary + # ngtcp2 version ## Build with OpenSSL Build (patched) OpenSSL - % git clone --depth 1 -b openssl-3.0.0+quic https://github.com/quictls/openssl + % git clone --depth 1 -b openssl-3.0.8+quic https://github.com/quictls/openssl % cd openssl % ./config enable-tls1_3 --prefix=<somewhere1> % make @@ -181,7 +189,7 @@ Build curl: Build msh3: - % git clone -b v0.4.0 --depth 1 --recursive https://github.com/nibanks/msh3 + % git clone -b v0.6.0 --depth 1 --recursive https://github.com/nibanks/msh3 % cd msh3 && mkdir build && cd build % cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=RelWithDebInfo .. % cmake --build . @@ -202,7 +210,7 @@ Run from `/usr/local/bin/curl`. Build msh3: - % git clone -b v0.4.0 --depth 1 --recursive https://github.com/nibanks/msh3 + % git clone -b v0.6.0 --depth 1 --recursive https://github.com/nibanks/msh3 % cd msh3 && mkdir build && cd build % cmake -G 'Visual Studio 17 2022' -DCMAKE_BUILD_TYPE=RelWithDebInfo .. % cmake --build . --config Release @@ -231,7 +239,11 @@ directory, or copy `msquic.dll` and `msh3.dll` from that directory to the # `--http3` -Use HTTP/3 directly: +Use only HTTP/3: + + curl --http3-only https://nghttp2.org:4433/ + +Use HTTP/3 with fallback to HTTP/2 or HTTP/1.1 (see "HTTPS eyeballing" below): curl --http3 https://nghttp2.org:4433/ @@ -241,6 +253,28 @@ Upgrade via Alt-Svc: See this [list of public HTTP/3 servers](https://bagder.github.io/HTTP3-test/) +### HTTPS eyeballing + +With option `--http3` curl will attempt earlier HTTP versions as well should the connect +attempt via HTTP/3 not succeed "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. + +So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms: + + * Ideally, the whole QUIC handshake happens and curl has a 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 will start 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 will try all those until one succeeds - just as with all other protocols. And if those IP addresses contain both IPv6 and IPv4, those attempts will happen, delayed, in parallel (the actual eyeballing). + ## Known Bugs Check out the [list of known HTTP3 bugs](https://curl.se/docs/knownbugs.html#HTTP3). |