1 HTTP/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 7 Build prerequisites 8 ------------------- 9 - nghttp2 10 - OpenSSL, libressl, BoringSSL, NSS, GnutTLS, mbedTLS, wolfSSL or SChannel 11 with a new enough version. 12 13 [nghttp2](https://nghttp2.org/) 14 ------------------------------- 15 16 libcurl uses this 3rd party library for the low level protocol handling 17 parts. The reason for this is that HTTP/2 is much more complex at that layer 18 than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already 19 existing and well functional library. 20 21 We require at least version 1.0.0. 22 23 Over an http:// URL 24 ------------------- 25 26 If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will 27 include an upgrade header in the initial request to the host to allow 28 upgrading to HTTP/2. 29 30 Possibly we can later introduce an option that will cause libcurl to fail if 31 not possible to upgrade. Possibly we introduce an option that makes libcurl 32 use HTTP/2 at once over http:// 33 34 Over an https:// URL 35 -------------------- 36 37 If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will use 38 ALPN (or NPN) to negotiate which protocol to continue with. Possibly introduce 39 an option 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 42 HTTP/2 for HTTPS but stick to 1.1 by default for plain old HTTP connections. 43 44 ALPN is the TLS extension that HTTP/2 is expected to use. The NPN extension is 45 for a similar purpose, was made prior to ALPN and is used for SPDY so early 46 HTTP/2 servers are implemented using NPN before ALPN support is widespread. 47 48 `CURLOPT_SSL_ENABLE_ALPN` and `CURLOPT_SSL_ENABLE_NPN` are offered to allow 49 applications to explicitly disable ALPN or NPN. 50 51 SSL libs 52 -------- 53 54 The challenge is the ALPN and NPN support and all our different SSL 55 backends. You may need a fairly updated SSL library version for it to provide 56 the necessary TLS features. Right now we support: 57 58 - OpenSSL: ALPN and NPN 59 - libressl: ALPN and NPN 60 - BoringSSL: ALPN and NPN 61 - NSS: ALPN and NPN 62 - GnuTLS: ALPN 63 - mbedTLS: ALPN 64 - SChannel: ALPN 65 - wolfSSL: ALPN 66 67 Multiplexing 68 ------------ 69 70 Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the 71 term for doing multiple independent transfers over the same physical TCP 72 connection. 73 74 To take advantage of multiplexing, you need to use the multi interface and set 75 `CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will 76 attempt to re-use existing HTTP/2 connections and just add a new stream over 77 that when doing subsequent parallel requests. 78 79 While libcurl sets up a connection to a HTTP server there is a period during 80 which it doesn't know if it can pipeline or do multiplexing and if you add new 81 transfers in that period, libcurl will default to start new connections for 82 those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you 83 can ask that a transfer should rather wait and see in case there's a 84 connection for the same host in progress that might end up being possible to 85 multiplex on. It favours keeping the number of connections low to the cost of 86 slightly longer time to first byte transferred. 87 88 Applications 89 ------------ 90 91 We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers 92 in HTTP 1.1 style. This allows applications to work unmodified. 93 94 curl tool 95 --------- 96 97 curl offers the `--http2` command line option to enable use of HTTP/2. 98 99 curl offers the `--http2-prior-knowledge` command line option to enable use of 100 HTTP/2 without HTTP/1.1 Upgrade. 101 102 Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections. 103 104 curl tool limitations 105 --------------------- 106 107 The command line tool won't do any HTTP/2 multiplexing even though libcurl 108 supports it, simply because the curl tool is not written to take advantage of 109 the libcurl API that's necessary for this (the multi interface). We have an 110 outstanding TODO item for this and **you** can help us make it happen. 111 112 The command line tool also doesn't support HTTP/2 server push for the same 113 reason it doesn't do multiplexing: it needs to use the multi interface for 114 that so that multiplexing is supported. 115 116 HTTP Alternative Services 117 ------------------------- 118 119 Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that 120 tells the client about an alternative "route" to the same content for the same 121 origin server that you get the response from. A browser or long-living client 122 can use that hint to create a new connection asynchronously. For libcurl, we 123 may introduce a way to bring such clues to the application and/or let a 124 subsequent request use the alternate route automatically. 125 126 [Detailed in RFC 7838](https://tools.ietf.org/html/rfc7838) 127
