curl.h: add CURL_HTTP_VERSION_3ONLY

As the previous CURL_HTTP_VERSION_3 option gets a slightly altered meaning. Closes curl#10264
bch · Jul 19, 2023 · a39126c · a39126c
1 parent 995f966
commit a39126c
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 9 deletions.
diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3
@@ -66,13 +66,12 @@ 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 does not support HTTP/3.
-
-For more reliably upgrading to HTTP/3, set the preferred version to something
-lower and let the server announce its HTTP/3 support via Alt-Svc:. See
-\fICURLOPT_ALTSVC(3)\fP.
+(Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host
+given in the URL, with fallback to earlier HTTP versions if needed.
+.IP CURL_HTTP_VERSION_3ONLY
+(Added in 7.88.0) Setting this value will make libcurl attempt to use HTTP/3
+directly to server given in the URL but will not downgrade to earlier HTTP
+version if the server does not support HTTP/3.
 .SH DEFAULT
 Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
 

diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
@@ -53,6 +53,7 @@ CURL_HTTP_VERSION_2_0           7.33.0
 CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE 7.49.0
 CURL_HTTP_VERSION_2TLS          7.47.0
 CURL_HTTP_VERSION_3             7.66.0
+CURL_HTTP_VERSION_3ONLY         7.88.0
 CURL_HTTP_VERSION_NONE          7.9.1
 CURL_HTTPPOST_BUFFER            7.46.0
 CURL_HTTPPOST_CALLBACK          7.46.0

diff --git a/include/curl/curl.h b/include/curl/curl.h
@@ -2259,8 +2259,13 @@ enum {
   CURL_HTTP_VERSION_2TLS, /* use version 2 for HTTPS, version 1.1 for HTTP */
   CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE,  /* please use HTTP 2 without HTTP/1.1
                                            Upgrade */
-  CURL_HTTP_VERSION_3 = 30, /* Makes use of explicit HTTP/3 without fallback.
-                               Use CURLOPT_ALTSVC to enable HTTP/3 upgrade */
+  CURL_HTTP_VERSION_3 = 30, /* Use HTTP/3, fallback to HTTP/2 or HTTP/1 if
+                               needed. For HTTPS only. For HTTP, this option
+                               makes libcurl return error. */
+  CURL_HTTP_VERSION_3ONLY = 31, /* Use HTTP/3 without fallback. For HTTPS
+                                   only. For HTTP, this makes libcurl
+                                   return error. */
+
   CURL_HTTP_VERSION_LAST /* *ILLEGAL* http version */
 };