docs/HTTP2.md

   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 HTTP Alternative Services
 105 -------------------------
 106
 107 Alt-Svc is a suggested extension with a corresponding frame (ALTSVC) in HTTP/2
 108 that tells the client about an alternative "route" to the same content for the
 109 same origin server that you get the response from. A browser or long-living
 110 client can use that hint to create a new connection asynchronously.  For
 111 libcurl, we may introduce a way to bring such clues to the applicaton and/or
 112 let a subsequent request use the alternate route
 113 automatically. [Spec](https://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-14)