Return to HTTP2.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

curl

    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.12.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:   - Secure Transport: ALPN
   67: 
   68: Multiplexing
   69: ------------
   70: 
   71: Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the
   72: term for doing multiple independent transfers over the same physical TCP
   73: connection.
   74: 
   75: To take advantage of multiplexing, you need to use the multi interface and set
   76: `CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will
   77: attempt to re-use existing HTTP/2 connections and just add a new stream over
   78: that when doing subsequent parallel requests.
   79: 
   80: While libcurl sets up a connection to a HTTP server there is a period during
   81: which it doesn't know if it can pipeline or do multiplexing and if you add new
   82: transfers in that period, libcurl will default to start new connections for
   83: those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you
   84: can ask that a transfer should rather wait and see in case there's a
   85: connection for the same host in progress that might end up being possible to
   86: multiplex on. It favours keeping the number of connections low to the cost of
   87: slightly longer time to first byte transferred.
   88: 
   89: Applications
   90: ------------
   91: 
   92: We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers
   93: in HTTP 1.1 style. This allows applications to work unmodified.
   94: 
   95: curl tool
   96: ---------
   97: 
   98: curl offers the `--http2` command line option to enable use of HTTP/2.
   99: 
  100: curl offers the `--http2-prior-knowledge` command line option to enable use of
  101: HTTP/2 without HTTP/1.1 Upgrade.
  102: 
  103: Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections.
  104: 
  105: curl tool limitations
  106: ---------------------
  107: 
  108: The command line tool won't do any HTTP/2 multiplexing even though libcurl
  109: supports it, simply because the curl tool is not written to take advantage of
  110: the libcurl API that's necessary for this (the multi interface). We have an
  111: outstanding TODO item for this and **you** can help us make it happen.
  112: 
  113: The command line tool also doesn't support HTTP/2 server push for the same
  114: reason it doesn't do multiplexing: it needs to use the multi interface for
  115: that so that multiplexing is supported.
  116: 
  117: HTTP Alternative Services
  118: -------------------------
  119: 
  120: Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that
  121: tells the client about an alternative "route" to the same content for the same
  122: origin server that you get the response from. A browser or long-living client
  123: can use that hint to create a new connection asynchronously.  For libcurl, we
  124: may introduce a way to bring such clues to the application and/or let a
  125: subsequent request use the alternate route automatically.
  126: 
  127: [Detailed in RFC 7838](https://tools.ietf.org/html/rfc7838)