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>