README.http2: refreshed and added multiplexing info

1 files changed, 30 insertions, 18 deletions

diff --git a/lib/README.http2 b/lib/README.http2
index f6d9cb9a8..e9084233b 100644
--- a/lib/README.http2
+++ b/lib/README.http2
@@ -1,6 +1,6 @@
 HTTP2 with libcurl
 
- Spec: http://tools.ietf.org/html/draft-ietf-httpbis-http2
+ Spec: http://www.rfc-editor.org/rfc/rfc7540.txt
 
  Document explaining it: http://daniel.haxx.se/http2/
 
@@ -15,9 +15,7 @@ HTTP2 with libcurl
   than HTTP/1.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
+  We require at least version 1.0.0.
 
  Over an http:// URL
 
@@ -52,16 +50,25 @@ SSL libs
     GnuTLS:   ALPN
     PolarSSL: ALPN
 
-HTTP Alternative Services
+Multiplexing
 
-  Alt-Svc is a suggested extension 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. Spec:
-  http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05
+  Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the
+  term for doing multiple independent transfers over the same physical TCP
+  connection.
+
+  To take advantage of multiplexing, you need to use the multi interface and
+  set CURLMOPT_PIPELINING to CURLPIPE_MULTIPLEX. With that bit set, libcurl
+  will attempt to re-use existing HTTP/2 connections and just add a new stream
+  over that when doing subsequent parallel requests.
+
+  While libcurl sets up a connection to a HTTP server there is a period during
+  which it doesn't know if it can pipeline or do multiplexing and if you add
+  new transfers in that period, libcurl will default to start new connections
+  for those transfers. With the new option CURLOPT_PIPEWAIT (added in 7.43.0),
+  you can ask that a transfer should rather wait and see in case there's a
+  connection for the same host in progress that might end up being possible to
+  multiplex on. It favours keeping the number of connections low to the cost
+  of slightly longer time to first byte transfered.
 
 Applications
 
@@ -72,13 +79,18 @@ curl tool
 
   curl offers the --http2 command line option to enable use of http2
 
-TODO:
+HTTP Alternative Services
 
-  - Implement multiplexing
+  Alt-Svc is a suggested extension 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. Spec:
+  http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05
 
-  - 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?
+TODO:
 
   - Provide API to set priorities / dependencies of individual streams