Update to 7.40.1

[platform/upstream/curl.git] / lib / README.http2

diff --git a/lib/README.http2 b/lib/README.http2
index 4d54c0c..936e3bb 100644 (file)
--- a/lib/README.http2
+++ b/lib/README.http2
@@ -1,19 +1,77 @@
 
 HTTP2 with libcurl
 
- Spec: http://tools.ietf.org/html/draft-ietf-httpbis-http2-06
+ Spec: http://tools.ietf.org/html/draft-ietf-httpbis-http2
+
+ Build prerequisites
+  - nghttp2
+  - OpenSSL, NSS, GnutTLS or PolarSSL with a new enough version
+
+ nghttp2 (https://github.com/tatsuhiro-t/nghttp2)
+
+  libcurl uses this 3rd party library for the low level protocol handling
+  parts. The reason for this is that HTTP2 is much more complex at that layer
+  than HTTP1.1 (which we implement on our own) and that nghttp2 is an already
+  existing and well functional library.
+
+  Right now, nghttp2 implements http2 draft-14
+
+  We require at least version 0.6.0
 
  Over an http:// URL
 
   If CURLOPT_HTTP_VERSION is set to CURL_HTTP_VERSION_2, libcurl will include
   an upgrade header in the initial request to the host to allow upgrading to
-  http2. Possibly introduce an option that will cause libcurl to fail if not
-  possible to upgrade. Possibly introduce an option that makes libcurl use
-  http2 at once over http://
+  http2.
+
+  Possibly we can later introduce an option that will cause libcurl to fail if
+  not possible to upgrade. Possibly we introduce an option that makes libcurl
+  use http2 at once over http://
 
  Over an https:// URL
 
   If CURLOPT_HTTP_VERSION is set to CURL_HTTP_VERSION_2, libcurl will use ALPN
   (or NPN) to negotiate which protocol to continue with. Possibly introduce an
   option that will cause libcurl to fail if not possible to use http2.
+  Consider options to explicitly disable ALPN and/or NPN.
+
+  ALPN is the TLS extension that http2 is expected to use. The NPN extension
+  is for a similar purpose, was made prior to ALPN and is used for SPDY so
+  early http2 servers are implemented using NPN before ALPN support is
+  widespread.
+
+SSL libs
+
+  The challenge is the ALPN and NPN support and all our different SSL
+  backends. You may need a fairly updated SSL library version for it to
+  provide the necessary TLS features. Right now we support:
+
+    OpenSSL:  ALPN and NPN
+    NSS:      ALPN and NPN
+    GnuTLS:   ALPN
+    PolarSSL: ALPN
+
+Alt-Svc
+
+  Alt-Svc is a suggested new header with a corresponding frame (ALTSVC) in
+  http2 that tells the client about an alternative "route" to the same content
+  for the same origin server that you get the response from. A browser or
+  long-living client can use that hint to create a new connection
+  asynchronously.  For libcurl, we may introduce a way to bring such clues to
+  the applicaton and/or let a subsequent request use the alternate route
+  automatically.
+
+Applications
+
+  We hide http2's binary nature and convert received http2 traffic to headers
+  in HTTP 1.1 style. This allows applications to work unmodified.
+
+curl tool
+
+  curl offers the --http2 command line option to enable use of http2
+
+To consider:
 
+  - How to tell libcurl when using the multi interface that all or some of the
+    handles are allowed to re-use the same physical connection. Can we just
+    re-use existing pipelining logic?