From 026840e35c7359c23741afe633bd3ab4b121c4ed Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 7 Aug 2019 14:17:48 +0200 Subject: CURLOPT_HTTP_VERSION: seting this to 3 forces HTTP/3 use directly Even though it cannot fall-back to a lower HTTP version automatically. The safer way to upgrade remains via CURLOPT_ALTSVC. CURLOPT_H3 no longer has any bits that do anything and might be removed before we remove the experimental label. Updated the curl tool accordingly to use "--http3". Closes #4197 --- docs/HTTP3.md | 10 +++++----- docs/cmdline-opts/Makefile.inc | 2 +- docs/cmdline-opts/http2.d | 1 + docs/cmdline-opts/http3-direct.d | 16 ---------------- docs/cmdline-opts/http3.d | 19 +++++++++++++++++++ docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 | 9 +++++---- docs/libcurl/opts/CURLOPT_H3.3 | 6 +----- docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 | 12 ++++++++++-- docs/libcurl/symbols-in-versions | 1 - 9 files changed, 42 insertions(+), 34 deletions(-) delete mode 100644 docs/cmdline-opts/http3-direct.d create mode 100644 docs/cmdline-opts/http3.d (limited to 'docs') diff --git a/docs/HTTP3.md b/docs/HTTP3.md index aa1303397..092d4d3e4 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -45,7 +45,7 @@ you'll just get ld.so linker errors. ## Invoke from command line - curl --http3-direct https://nghttp2.org:8443/ + curl --http3 https://nghttp2.org:8443/ # quiche version @@ -79,7 +79,7 @@ Clone and build curl: Make an HTTP/3 request. - % src/curl --http3-direct https://cloudflare-quic.com/ - % src/curl --http3-direct https://facebook.com/ - % src/curl --http3-direct https://quic.aiortc.org:4433/ - % src/curl --http3-direct https://quic.rocks:4433/ + % src/curl --http3 https://cloudflare-quic.com/ + % src/curl --http3 https://facebook.com/ + % src/curl --http3 https://quic.aiortc.org:4433/ + % src/curl --http3 https://quic.rocks:4433/ diff --git a/docs/cmdline-opts/Makefile.inc b/docs/cmdline-opts/Makefile.inc index 1bdda9885..6b4387475 100644 --- a/docs/cmdline-opts/Makefile.inc +++ b/docs/cmdline-opts/Makefile.inc @@ -65,7 +65,7 @@ DPAGES = \ http1.0.d \ http1.1.d http2.d \ http2-prior-knowledge.d \ - http3-direct.d \ + http3.d \ ignore-content-length.d \ include.d \ insecure.d \ diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d index 04cff00a4..cf8f2988e 100644 --- a/docs/cmdline-opts/http2.d +++ b/docs/cmdline-opts/http2.d @@ -6,5 +6,6 @@ Mutexed: http1.1 http1.0 http2-prior-knowledge Requires: HTTP/2 See-also: no-alpn Help: Use HTTP 2 +See-also: http1.1 http3 --- Tells curl to use HTTP version 2. diff --git a/docs/cmdline-opts/http3-direct.d b/docs/cmdline-opts/http3-direct.d deleted file mode 100644 index fb8c8cf28..000000000 --- a/docs/cmdline-opts/http3-direct.d +++ /dev/null @@ -1,16 +0,0 @@ -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/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d new file mode 100644 index 000000000..ca85e3a64 --- /dev/null +++ b/docs/cmdline-opts/http3.d @@ -0,0 +1,19 @@ +Long: http3 +Tags: Versions +Protocols: HTTP +Added: 7.66.0 +Mutexed: http1.1 http1.0 http2 http2-prior-knowledge +Requires: HTTP/3 +Help: Use HTTP v3 +See-also: http1.1 http2 +--- + +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. + +This option will make curl fail if a QUIC connection cannot be established, it +cannot fall back to a lower HTTP version on its own. diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 index b0f43e549..7e8931812 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, , et al. +.\" * 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 @@ -28,9 +28,10 @@ CURLINFO_HTTP_VERSION \- get the http version used in the connection CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p); .SH DESCRIPTION -Pass a pointer to a long to receive the version used in the last http connection. -The returned value will be CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, or -CURL_HTTP_VERSION_2_0, or 0 if the version can't be determined. +Pass a pointer to a long to receive the version used in the last http +connection. The returned value will be CURL_HTTP_VERSION_1_0, +CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the +version can't be determined. .SH PROTOCOLS HTTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_H3.3 b/docs/libcurl/opts/CURLOPT_H3.3 index be521b6bf..3411073fd 100644 --- a/docs/libcurl/opts/CURLOPT_H3.3 +++ b/docs/libcurl/opts/CURLOPT_H3.3 @@ -35,10 +35,6 @@ 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 @@ -49,7 +45,7 @@ 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); + curl_easy_setopt(curl, CURLOPT_H3, (long)0); ret = curl_easy_perform(curl); } .fi diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 index 741dfaa6c..564c0dc16 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, , et al. +.\" * 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 @@ -57,6 +57,14 @@ Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge that the server supports HTTP/2 straight away. HTTPS requests will still do HTTP/2 the standard way with negotiated protocol version in the TLS handshake. (Added in 7.49.0) +.IP CURL_HTTP_VERSION_3 +(Added in 7.66.0) Setting this value will make libcurl attempt to use HTTP/3 +directly to server given in the URL. Note that this cannot gracefully +downgrade to earlier HTTP version if the server doesn't support HTTP/3. + +For more reliably upgrading into HTTP/3, set the prefered version to something +lower and let the server announce its HTTP/3 support via Alt-Svc:. See +\fICURLOPT_ALTSVC(3)\fP. .SH DEFAULT Since curl 7.62.0: CURL_HTTP_VERSION_2TLS @@ -82,4 +90,4 @@ Along with HTTP Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_SSLVERSION "(3), " CURLOPT_HTTP200ALIASES "(3), " -.BR CURLOPT_HTTP09_ALLOWED "(3), " +.BR CURLOPT_HTTP09_ALLOWED "(3), " CURLOPT_H3 "(3), " CURLOPT_ALTSVC "(3) " diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 79243e25b..9a4cec2b0 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -209,7 +209,6 @@ 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 -- cgit v1.2.1