1<!-- 2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4SPDX-License-Identifier: curl 5--> 6 7HTTP/2 with curl 8================ 9 10[HTTP/2 Spec](https://www.rfc-editor.org/rfc/rfc7540.txt) 11[http2 explained](https://daniel.haxx.se/http2/) 12 13Build prerequisites 14------------------- 15 - nghttp2 16 - OpenSSL, libressl, BoringSSL, GnuTLS, mbedTLS, wolfSSL or Schannel 17 with a new enough version. 18 19[nghttp2](https://nghttp2.org/) 20------------------------------- 21 22libcurl uses this 3rd party library for the low level protocol handling 23parts. The reason for this is that HTTP/2 is much more complex at that layer 24than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already 25existing and well functional library. 26 27We require at least version 1.12.0. 28 29Over an http:// URL 30------------------- 31 32If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl includes 33an upgrade header in the initial request to the host to allow upgrading to 34HTTP/2. 35 36Possibly we can later introduce an option that causes libcurl to fail if it is 37not possible to upgrade. Possibly we introduce an option that makes libcurl 38use HTTP/2 at once over http:// 39 40Over an https:// URL 41-------------------- 42 43If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl uses ALPN 44to negotiate which protocol to continue with. Possibly introduce an option 45that causes libcurl to fail if not possible to use HTTP/2. 46 47`CURL_HTTP_VERSION_2TLS` was added in 7.47.0 as a way to ask libcurl to prefer 48HTTP/2 for HTTPS but stick to 1.1 by default for plain old HTTP connections. 49 50ALPN is the TLS extension that HTTP/2 is expected to use. 51 52`CURLOPT_SSL_ENABLE_ALPN` is offered to allow applications to explicitly 53disable ALPN. 54 55Multiplexing 56------------ 57 58Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the 59term for doing multiple independent transfers over the same physical TCP 60connection. 61 62To take advantage of multiplexing, you need to use the multi interface and set 63`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl 64attempts to reuse existing HTTP/2 connections and just add a new stream over 65that when doing subsequent parallel requests. 66 67While libcurl sets up a connection to an HTTP server there is a period during 68which it does not know if it can pipeline or do multiplexing and if you add 69new transfers in that period, libcurl defaults to starting new connections for 70those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you 71can ask that a transfer should rather wait and see in case there is a 72connection for the same host in progress that might end up being possible to 73multiplex on. It favors keeping the number of connections low to the cost of 74slightly longer time to first byte transferred. 75 76Applications 77------------ 78 79We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers 80in HTTP 1.1 style. This allows applications to work unmodified. 81 82curl tool 83--------- 84 85curl offers the `--http2` command line option to enable use of HTTP/2. 86 87curl offers the `--http2-prior-knowledge` command line option to enable use of 88HTTP/2 without HTTP/1.1 Upgrade. 89 90Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections. 91 92curl tool limitations 93--------------------- 94 95The command line tool does not support HTTP/2 server push. It supports 96multiplexing when the parallel transfer option is used. 97 98HTTP Alternative Services 99------------------------- 100 101Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that 102tells the client about an alternative "route" to the same content for the same 103origin server that you get the response from. A browser or long-living client 104can use that hint to create a new connection asynchronously. For libcurl, we 105may introduce a way to bring such clues to the application and/or let a 106subsequent request use the alternate route automatically. 107 108[Detailed in RFC 7838](https://datatracker.ietf.org/doc/html/rfc7838) 109
