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