Annotation of embedaddon/curl/docs/HTTP2.md, revision 1.1
1.1 ! misho 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)
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>