generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

HTTP2.md: formatted properly

Browse Source
This commit is contained in:
Daniel Stenberg 2015-05-30 12:07:39 +02:00
parent a8904b39f3
commit 3628a90852
2 changed files with 70 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
docs/HTTP2.md
View File

@ -1,96 +1,104 @@
HTTP2 with libcurl HTTP/2 with curl
================
Spec: http://www.rfc-editor.org/rfc/rfc7540.txt [HTTP/2 Spec](http://www.rfc-editor.org/rfc/rfc7540.txt)
[http2 explained](http://daniel.haxx.se/http2/)
Document explaining it: http://daniel.haxx.se/http2/ Build prerequisites
-------------------
Build prerequisites
- nghttp2 - nghttp2
- OpenSSL, NSS, GnutTLS or PolarSSL with a new enough version - OpenSSL, NSS, GnutTLS or PolarSSL with a new enough version
nghttp2 (https://github.com/tatsuhiro-t/nghttp2) [nghttp2](https://nghttp2.org/)
-------------------------------
libcurl uses this 3rd party library for the low level protocol handling libcurl uses this 3rd party library for the low level protocol handling
parts. The reason for this is that HTTP/2 is much more complex at that layer parts. The reason for this is that HTTP/2 is much more complex at that layer
than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already
existing and well functional library. existing and well functional library.
We require at least version 1.0.0. We require at least version 1.0.0.
Over an http:// URL Over an http:// URL
-------------------
If CURLOPT_HTTP_VERSION is set to CURL_HTTP_VERSION_2_0, libcurl will If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will
include an upgrade header in the initial request to the host to allow include an upgrade header in the initial request to the host to allow
upgrading to http2. upgrading to HTTP/2.
Possibly we can later introduce an option that will cause libcurl to fail if 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 not possible to upgrade. Possibly we introduce an option that makes libcurl
use http2 at once over http:// use HTTP/2 at once over http://
Over an https:// URL Over an https:// URL
--------------------
If CURLOPT_HTTP_VERSION is set to CURL_HTTP_VERSION_2_0, libcurl will use If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will use
ALPN (or NPN) to negotiate which protocol to continue with. Possibly ALPN (or NPN) to negotiate which protocol to continue with. Possibly introduce
introduce an option that will cause libcurl to fail if not possible to use an option that will cause libcurl to fail if not possible to use HTTP/2.
http2. Consider options to explicitly disable ALPN and/or NPN. Consider options to explicitly disable ALPN and/or NPN.
ALPN is the TLS extension that http2 is expected to use. The NPN extension ALPN is the TLS extension that HTTP/2 is expected to use. The NPN extension is
is for a similar purpose, was made prior to ALPN and is used for SPDY so for a similar purpose, was made prior to ALPN and is used for SPDY so early
early http2 servers are implemented using NPN before ALPN support is HTTP/2 servers are implemented using NPN before ALPN support is widespread.
widespread.
SSL libs SSL libs
--------
The challenge is the ALPN and NPN support and all our different SSL 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 backends. You may need a fairly updated SSL library version for it to
provide the necessary TLS features. Right now we support: provide the necessary TLS features. Right now we support:
OpenSSL: ALPN and NPN - OpenSSL: ALPN and NPN
NSS: ALPN and NPN - NSS: ALPN and NPN
GnuTLS: ALPN - GnuTLS: ALPN
PolarSSL: ALPN - PolarSSL: ALPN
Multiplexing Multiplexing
------------
Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the 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 term for doing multiple independent transfers over the same physical TCP
connection. connection.
To take advantage of multiplexing, you need to use the multi interface and To take advantage of multiplexing, you need to use the multi interface and set
set CURLMOPT_PIPELINING to CURLPIPE_MULTIPLEX. With that bit set, libcurl `CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will
will attempt to re-use existing HTTP/2 connections and just add a new stream attempt to re-use existing HTTP/2 connections and just add a new stream over
over that when doing subsequent parallel requests. that when doing subsequent parallel requests.
While libcurl sets up a connection to a HTTP server there is a period during 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 which it doesn't know if it can pipeline or do multiplexing and if you add new
new transfers in that period, libcurl will default to start new connections transfers in that period, libcurl will default to start new connections for
for those transfers. With the new option CURLOPT_PIPEWAIT (added in 7.43.0), those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you
you can ask that a transfer should rather wait and see in case there's a 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 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 multiplex on. It favours keeping the number of connections low to the cost of
of slightly longer time to first byte transfered. slightly longer time to first byte transfered.
Applications Applications
------------
We hide http2's binary nature and convert received http2 traffic to headers We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers
in HTTP 1.1 style. This allows applications to work unmodified. in HTTP 1.1 style. This allows applications to work unmodified.
curl tool curl tool
---------
curl offers the --http2 command line option to enable use of http2 curl offers the `--http2` command line option to enable use of HTTP/2
HTTP Alternative Services HTTP Alternative Services
-------------------------
Alt-Svc is a suggested extension with a corresponding frame (ALTSVC) in Alt-Svc is a suggested extension with a corresponding frame (ALTSVC) in HTTP/2
http2 that tells the client about an alternative "route" to the same content that tells the client about an alternative "route" to the same content for the
for the same origin server that you get the response from. A browser or same origin server that you get the response from. A browser or long-living
long-living client can use that hint to create a new connection client can use that hint to create a new connection asynchronously. For
asynchronously. For libcurl, we may introduce a way to bring such clues to libcurl, we may introduce a way to bring such clues to the applicaton and/or
the applicaton and/or let a subsequent request use the alternate route let a subsequent request use the alternate route
automatically. Spec: automatically. [Spec](http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05)
http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05
TODO: TODO
----
- Provide API to set priorities / dependencies of individual streams - Provide API to set priorities / dependencies of individual streams

2
docs/Makefile.am
View File

@ -38,7 +38,7 @@ EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS \
KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL \ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL \
$(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \ $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \
MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS SECURITY RELEASE-PROCEDURE \ MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS SECURITY RELEASE-PROCEDURE \
SSL-PROBLEMS HTTP2.md SSL-PROBLEMS HTTP2.md ROADMAP.md
MAN2HTML= roffit < $< >$@ MAN2HTML= roffit < $< >$@