From 3af0e76d1e71995b7790c74e79b76af86ee7c681 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 21 Jul 2019 23:48:58 +0200 Subject: HTTP3: initial (experimental) support USe configure --with-ngtcp2 or --with-quiche Using either option will enable a HTTP3 build. Co-authored-by: Alessandro Ghedini Closes #3500 --- docs/HTTP3.md | 85 ++++++++++++++++++++++++++++++++++++++++ docs/Makefile.am | 1 + docs/cmdline-opts/Makefile.inc | 1 + docs/cmdline-opts/http3-direct.d | 16 ++++++++ docs/libcurl/curl_easy_setopt.3 | 2 + docs/libcurl/opts/CURLOPT_H3.3 | 61 ++++++++++++++++++++++++++++ docs/libcurl/opts/Makefile.inc | 1 + docs/libcurl/symbols-in-versions | 3 ++ 8 files changed, 170 insertions(+) create mode 100644 docs/HTTP3.md create mode 100644 docs/cmdline-opts/http3-direct.d create mode 100644 docs/libcurl/opts/CURLOPT_H3.3 (limited to 'docs') diff --git a/docs/HTTP3.md b/docs/HTTP3.md new file mode 100644 index 000000000..c09bf0a76 --- /dev/null +++ b/docs/HTTP3.md @@ -0,0 +1,85 @@ +# HTTP3 (and QUIC) + +## Resources + +[HTTP/3 Explained](https://daniel.haxx.se/http3-explained/) - the online free +book describing the protocols involved. + +[QUIC implementation](https://github.com/curl/curl/wiki/QUIC-implementation) - +the wiki page describing the plan for how to support QUIC and HTTP/3 in curl +and libcurl. + +[quicwg.org](https://quicwg.org/) - home of the official protocol drafts + +## QUIC libraries + +QUIC libraries we're experiementing with: + +[ngtcp2](https://github.com/ngtcp2/ngtcp2) + +[quiche](https://github.com/cloudflare/quiche) + +## Experimental! + +HTTP/3 and QUIC support in curl is not yet working and this is early days. +Consider all QUIC and HTTP/3 code to be **EXPERIMENTAL** until further notice. + +curl does not have HTTP/3 support (yet). + +The bleeding edge QUIC work is done in the dedicated +[QUIC](https://github.com/curl/curl/tree/QUIC) branch, but the plan is to +merge as often as possible from there to master. All QUIC related code will +remain being build-time conditionally enabled. + +# ngtcp2 version + +## Build + +1. clone ngtcp2 from git (the draft-17 branch) +2. build and install ngtcp2's custom OpenSSL version (the quic-draft-17 branch) +3. build and install ngtcp2 according to its instructions +4. configure curl with ngtcp2 support: `./configure --with-ngtcp2=` +5. build curl "normally" + +## Running + +Make sure the custom OpenSSL library is the one used at run-time, as otherwise +you'll just get ld.so linker errors. + +## Invoke from command line + + curl --http3-direct https://nghttp2.org:8443/ + +# quiche version + +## build + +Build BoringSSL (it needs to be built manually so it can be reused with curl): + + % mkdir -p quiche/deps/boringssl/build + % cd quiche/deps/boringssl/build + % cmake -DCMAKE_POSITION_INDEPENDENT_CODE=on .. + % make -j`nproc` + % cd .. + % mkdir .openssl/lib -p + % cp build/crypto/libcrypto.a build/ssl/libssl.a .openssl/lib + % ln -s $PWD/include .openssl + +Build quiche: + + % cd ../.. + % QUICHE_BSSL_PATH=$PWD/deps/boringssl cargo build --release + +Clone and build curl: + + % cd .. + % git clone https://github.com/curl/curl + % ./buildconf + % ./configure --with-ssl=$PWD/../quiche/deps/boringssl/.openssl --with-quiche=$PWD/../quiche --enable-debug + % make -j`nproc` + +## Running + +Make an HTTP/1.1 request to a QUIC server: + + % src/curl --http3-direct https://cloudflare-quic.com/ diff --git a/docs/Makefile.am b/docs/Makefile.am index ed6a212e0..a29c059a1 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -60,6 +60,7 @@ EXTRA_DIST = \ HISTORY.md \ HTTP-COOKIES.md \ HTTP2.md \ + HTTP3.md \ INSTALL \ INSTALL.cmake \ INSTALL.md \ diff --git a/docs/cmdline-opts/Makefile.inc b/docs/cmdline-opts/Makefile.inc index 886fa6caf..d50a8bb26 100644 --- a/docs/cmdline-opts/Makefile.inc +++ b/docs/cmdline-opts/Makefile.inc @@ -65,6 +65,7 @@ DPAGES = \ http1.0.d \ http1.1.d http2.d \ http2-prior-knowledge.d \ + http3-direct.d \ ignore-content-length.d \ include.d \ insecure.d \ diff --git a/docs/cmdline-opts/http3-direct.d b/docs/cmdline-opts/http3-direct.d new file mode 100644 index 000000000..fb8c8cf28 --- /dev/null +++ b/docs/cmdline-opts/http3-direct.d @@ -0,0 +1,16 @@ +Long: http3-direct +Tags: Versions +Protocols: HTTP +Added: 7.66.0 +Mutexed: http1.1 http1.0 http2 http2-prior-knowledge +Requires: HTTP/3 +Help: Use HTTP v3 +--- + +WARNING: this option is experiemental. Do not use in production. + +Tells curl to use HTTP version 3 directly to the host and port number used in +the URL. A normal HTTP/3 transaction will be done to a host and then get +redirected via Alt-SVc, but this option allows a user to circumvent that when +you know that the target speaks HTTP/3 on the given host and port. + diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1f18a3494..cb5c418fb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -321,6 +321,8 @@ Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP .IP CURLOPT_REQUEST_TARGET Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP +.IP CURLOPT_H3 +Specify HTTP/3 behavior. \fICURLOPT_H3(3)\fP .IP CURLOPT_HTTP_VERSION HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP .IP CURLOPT_HTTP09_ALLOWED diff --git a/docs/libcurl/opts/CURLOPT_H3.3 b/docs/libcurl/opts/CURLOPT_H3.3 new file mode 100644 index 000000000..be521b6bf --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_H3.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_H3 3 "27 Nov 2018" "libcurl 7.66.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_H3 \- specify HTTP/3 protocol behavior +.SH SYNOPSIS +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_H3, long bitmask); +.SH EXPERIMENTAL +Warning: this feature is early code and is marked as experimental. It can only +be enabled by explicitly invoking configure with \fB--with-quiche\fP or +\fB--with-ngtcp2\fP. You are advised to not ship this feature used in +production before the experimental label is removed. +.SH DESCRIPTION +This function accepts a long \fIbitmask\fP with a set of flags set that +controls the HTTP/3 behavior for this transfer. +.IP "CURLH3_DIRECT" +If this bit is set in \fIbitmask\fP, the host name and port number given in +the URL will be used to connect to directly with QUIC and the port number then +being a UDP port number. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTPS +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_H3, (long)CURLH3_DIRECT); + ret = curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.66.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, an error otherwise. +.SH "SEE ALSO" +.BR CURLOPT_HTTP_VERSION "(3), " diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index c8e15a5ed..5460b2a57 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -150,6 +150,7 @@ man_MANS = \ CURLOPT_FTP_USE_EPSV.3 \ CURLOPT_FTP_USE_PRET.3 \ CURLOPT_GSSAPI_DELEGATION.3 \ + CURLOPT_H3.3 \ CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 \ CURLOPT_HAPROXYPROTOCOL.3 \ CURLOPT_HEADER.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 16fb5622c..1b452d245 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -209,6 +209,7 @@ CURLFTP_CREATE_DIR_RETRY 7.19.4 CURLGSSAPI_DELEGATION_FLAG 7.22.0 CURLGSSAPI_DELEGATION_NONE 7.22.0 CURLGSSAPI_DELEGATION_POLICY_FLAG 7.22.0 +CURLH3_DIRECT 7.66.0 CURLHEADER_SEPARATE 7.37.0 CURLHEADER_UNIFIED 7.37.0 CURLINFO_ACTIVESOCKET 7.45.0 @@ -424,6 +425,7 @@ CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 CURLOPT_GSSAPI_DELEGATION 7.22.0 +CURLOPT_H3 7.66.0 CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 7.59.0 CURLOPT_HAPROXYPROTOCOL 7.60.0 CURLOPT_HEADER 7.1 @@ -925,6 +927,7 @@ CURL_VERSION_DEBUG 7.10.6 CURL_VERSION_GSSAPI 7.38.0 CURL_VERSION_GSSNEGOTIATE 7.10.6 7.38.0 CURL_VERSION_HTTP2 7.33.0 +CURL_VERSION_HTTP3 7.66.0 CURL_VERSION_HTTPS_PROXY 7.52.0 CURL_VERSION_IDN 7.12.0 CURL_VERSION_IPV6 7.10 -- cgit v1.2.3