1HTTP/2 with curl
2================
3
4[HTTP/2 Spec](https://www.rfc-editor.org/rfc/rfc7540.txt)
5[http2 explained](http://daniel.haxx.se/http2/)
6
7Build prerequisites
8-------------------
9  - nghttp2
10  - OpenSSL, NSS, GnutTLS or PolarSSL with a new enough version
11
12[nghttp2](https://nghttp2.org/)
13-------------------------------
14
15libcurl uses this 3rd party library for the low level protocol handling
16parts. The reason for this is that HTTP/2 is much more complex at that layer
17than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already
18existing and well functional library.
19
20We require at least version 1.0.0.
21
22Over an http:// URL
23-------------------
24
25If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will
26include an upgrade header in the initial request to the host to allow
27upgrading to HTTP/2.
28
29Possibly we can later introduce an option that will cause libcurl to fail if
30not possible to upgrade. Possibly we introduce an option that makes libcurl
31use HTTP/2 at once over http://
32
33Over an https:// URL
34--------------------
35
36If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will use
37ALPN (or NPN) to negotiate which protocol to continue with. Possibly introduce
38an option that will cause libcurl to fail if not possible to use HTTP/2.
39Consider options to explicitly disable ALPN and/or NPN.
40
41ALPN is the TLS extension that HTTP/2 is expected to use. The NPN extension is
42for a similar purpose, was made prior to ALPN and is used for SPDY so early
43HTTP/2 servers are implemented using NPN before ALPN support is widespread.
44
45SSL libs
46--------
47
48The challenge is the ALPN and NPN support and all our different SSL
49backends. You may need a fairly updated SSL library version for it to
50provide the necessary TLS features. Right now we support:
51
52  - OpenSSL:  ALPN and NPN
53  - NSS:      ALPN and NPN
54  - GnuTLS:   ALPN
55  - PolarSSL: ALPN
56
57Multiplexing
58------------
59
60Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the
61term for doing multiple independent transfers over the same physical TCP
62connection.
63
64To take advantage of multiplexing, you need to use the multi interface and set
65`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will
66attempt to re-use existing HTTP/2 connections and just add a new stream over
67that when doing subsequent parallel requests.
68
69While libcurl sets up a connection to a HTTP server there is a period during
70which it doesn't know if it can pipeline or do multiplexing and if you add new
71transfers in that period, libcurl will default to start new connections for
72those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you
73can ask that a transfer should rather wait and see in case there's a
74connection for the same host in progress that might end up being possible to
75multiplex on. It favours keeping the number of connections low to the cost of
76slightly longer time to first byte transferred.
77
78Applications
79------------
80
81We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers
82in HTTP 1.1 style. This allows applications to work unmodified.
83
84curl tool
85---------
86
87curl offers the `--http2` command line option to enable use of HTTP/2
88
89HTTP Alternative Services
90-------------------------
91
92Alt-Svc is a suggested extension with a corresponding frame (ALTSVC) in HTTP/2
93that tells the client about an alternative "route" to the same content for the
94same origin server that you get the response from. A browser or long-living
95client can use that hint to create a new connection asynchronously.  For
96libcurl, we may introduce a way to bring such clues to the applicaton and/or
97let a subsequent request use the alternate route
98automatically. [Spec](https://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05)
99
100TODO
101----
102
103  - Provide API to set priorities / dependencies of individual streams
104
105  - Implement "prior-knowledge" HTTP/2 connecitons over clear text so that
106    curl can connect with HTTP/2 at once without 1.1+Upgrade.
107
108