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, NSS, GnutTLS, 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.0.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 (or NPN) to negotiate which protocol to continue with. Possibly introduce 39an 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 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. The NPN extension is 45for a similar purpose, was made prior to ALPN and is used for SPDY so early 46HTTP/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 49applications to explicitly disable ALPN or NPN. 50 51SSL libs 52-------- 53 54The challenge is the ALPN and NPN support and all our different SSL 55backends. You may need a fairly updated SSL library version for it to provide 56the 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 67Multiplexing 68------------ 69 70Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the 71term for doing multiple independent transfers over the same physical TCP 72connection. 73 74To 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 76attempt to re-use existing HTTP/2 connections and just add a new stream over 77that when doing subsequent parallel requests. 78 79While libcurl sets up a connection to a HTTP server there is a period during 80which it doesn't know if it can pipeline or do multiplexing and if you add new 81transfers in that period, libcurl will default to start new connections for 82those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you 83can ask that a transfer should rather wait and see in case there's a 84connection for the same host in progress that might end up being possible to 85multiplex on. It favours keeping the number of connections low to the cost of 86slightly longer time to first byte transferred. 87 88Applications 89------------ 90 91We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers 92in HTTP 1.1 style. This allows applications to work unmodified. 93 94curl tool 95--------- 96 97curl offers the `--http2` command line option to enable use of HTTP/2. 98 99curl offers the `--http2-prior-knowledge` command line option to enable use of 100HTTP/2 without HTTP/1.1 Upgrade. 101 102Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections. 103 104HTTP Alternative Services 105------------------------- 106 107Alt-Svc is a suggested extension with a corresponding frame (ALTSVC) in HTTP/2 108that tells the client about an alternative "route" to the same content for the 109same origin server that you get the response from. A browser or long-living 110client can use that hint to create a new connection asynchronously. For 111libcurl, we may introduce a way to bring such clues to the applicaton and/or 112let a subsequent request use the alternate route 113automatically. [Spec](https://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-14) 114