From d704b92fd9efddb68f6f16ff50fec7703b7fad77 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 27 Jul 2013 21:56:46 +0900 Subject: [PATCH] Update README.rst --- README.rst | 280 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 238 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 5dd1ac5b..2d07c3d4 100644 --- a/README.rst +++ b/README.rst @@ -14,69 +14,265 @@ spdylay code base. The following features are not implemented: * Header continuation -* ALPN: ``nghttp`` client and ``nghttpd`` server use OpenSSL without ALPN - support and still use NPN to negotiate ``HTTP-draft-04/2.0``. +* ALPN: instead, NPN is used * HTTP Upgrade dance -With those missing parts, the library is not still inter-operable -right now. +Requirements +------------ -The ``nghttp`` client and ``nghttpd`` server are working now assuming -the above limitation. Both programs start HTTP/2.0 with `prior -knowledge -`_ -or TLS NPN negotiation. No HTTP upgrade dance is supported yet. You -can see the HTTP/2.0 frames back and forth and connection-level and -stream level flow controls. +The following packages are needed to build the library: -Here is sample output from ``nghttp`` client:: +* pkg-config >= 0.20 +* zlib >= 1.2.3 - $ src/nghttp https://localhost:3000/COPYING http://localhost:3000/AUTHORS -nv --no-tls - [ 0.000] Handshake complete - [ 0.000] recv SETTINGS frame - (niv=1) - [4:100] - [ 0.000] send HEADERS frame +To build and run the unit test programs, the following packages are +required: + +* cunit >= 2.1 + +To build and run the application programs (``nghttp``, ``nghttpd`` and +``nghttpx``) in ``src`` directory, the following packages are +required: + +* OpenSSL >= 1.0.1 +* libevent-openssl >= 2.0.8 + +To enable SPDY protocol in the application program ``nghttpx``, the +following packages are required: + +* spdylay >= 1.0.0 + +To enable ``-a`` option (getting linked assets from the downloaded +resouce) in ``nghttp``, the following +packages are needed: + +* libxml2 >= 2.7.7 + +If you are using Ubuntu 12.04, you need the following packages +installed: + +* autoconf +* automake +* autotools-dev +* libtool +* pkg-config +* zlib1g-dev +* libcunit1-dev +* libssl-dev +* libxml2-dev +* libevent-dev + +spdylay is not packaged in Ubuntu, so you need to build it yourself: +http://spdylay.sourceforge.net/ + +Building documentation +---------------------- + +.. note:: + + Documentation is still incomplete. + +To build documentation, run:: + + $ make html + +The documents will be generated under ``doc/manual/html/``. + +The generated documents will not be installed with ``make install``. + +Client, Server and Proxy programs +--------------------------------- + +The src directory contains HTTP/2.0 client, server and proxy programs. + +nghttp - client ++++++++++++++++ + +``nghttp`` is HTTP-default04/2.0 client. It can connect to the +HTTP/2.0 server with prior knowledge (without HTTP Upgrade) and NPN in +TLS extension. + +It has verbose output mode for framing information. Here is sample +output from ``nghttp`` client:: + + $ src/nghttp -nv https://localhost:3000/ + [ 0.000] NPN select next protocol: the remote server offers: + * HTTP-draft-04/2.0 + * spdy/3 + * spdy/2 + * http/1.1 + NPN selected the protocol: HTTP-draft-04/2.0 + [ 0.005] send SETTINGS frame + (niv=0) + [ 0.005] send HEADERS frame ; END_STREAM | END_HEADERS ; Open new stream :host: localhost:3000 :method: GET - :path: /COPYING + :path: / :scheme: https accept: */* accept-encoding: gzip, deflate user-agent: nghttp2/0.1.0-DEV - [ 0.000] send HEADERS frame + [ 0.005] recv SETTINGS frame + (niv=2) + [4:100] + [7:65536] + [ 0.005] recv WINDOW_UPDATE frame + ; END_FLOW_CONTROL + (window_size_increment=0) + [ 0.006] recv HEADERS frame + ; END_HEADERS + ; First response header + :status: 200 OK + accept-ranges: bytes + content-encoding: gzip + content-length: 56 + content-type: text/html + date: Sat, 27 Jul 2013 12:08:56 GMT + etag: "cf405c-2d-45adabdf282c0" + last-modified: Tue, 04 Nov 2008 10:44:03 GMT + server: Apache/2.2.22 (Debian) + vary: Accept-Encoding + via: 1.1 nghttpx + [ 0.006] recv DATA frame (length=56, flags=0, stream_id=1) + [ 0.006] recv DATA frame (length=0, flags=1, stream_id=1) + [ 0.006] send GOAWAY frame + (last_stream_id=0, error_code=NO_ERROR(0), opaque_data=) + +nghttpd - server +++++++++++++++++ + +``nghttpd`` is static web server. It is single threaded and +multiplexes connections using non-blocking socket. + +Just like ``nghttp``, it has verbose output mode for framing +information. Here is sample output from ``nghttpd`` server:: + + $ src/nghttpd 3000 --no-tls -v + IPv4: listen on port 3000 + IPv6: listen on port 3000 + [id=1] [ 1.020] send SETTINGS frame + (niv=1) + [4:100] + [id=1] [ 1.020] closed + [id=2] [ 1.838] send SETTINGS frame + (niv=1) + [4:100] + [id=2] [ 1.838] recv SETTINGS frame + (niv=0) + [id=2] [ 1.838] recv HEADERS frame ; END_STREAM | END_HEADERS ; Open new stream :host: localhost:3000 :method: GET - :path: /AUTHORS + :path: / :scheme: http accept: */* accept-encoding: gzip, deflate user-agent: nghttp2/0.1.0-DEV - [ 0.001] recv HEADERS frame + [id=2] [ 1.838] send HEADERS frame ; END_HEADERS ; First response header - :status: 200 OK - cache-control: max-age=3600 - content-length: 1080 - date: Fri, 19 Jul 2013 17:02:21 GMT - last-modified: Fri, 12 Jul 2013 14:55:22 GMT + :status: 404 Not Found + content-encoding: gzip + content-type: text/html; charset=UTF-8 + date: Sat, 27 Jul 2013 12:32:10 GMT server: nghttpd nghttp2/0.1.0-DEV - [ 0.001] recv DATA frame (length=1080, flags=0, stream_id=1) - [ 0.001] recv DATA frame (length=0, flags=1, stream_id=1) - [ 0.001] recv HEADERS frame - ; END_HEADERS - ; First response header - :status: 200 OK - cache-control: max-age=3600 - content-length: 66 - date: Fri, 19 Jul 2013 17:02:21 GMT - last-modified: Fri, 12 Jul 2013 14:55:22 GMT - server: nghttpd nghttp2/0.1.0-DEV - [ 0.001] recv DATA frame (length=66, flags=0, stream_id=3) - [ 0.001] recv DATA frame (length=0, flags=1, stream_id=3) - [ 0.001] send GOAWAY frame - (last_stream_id=0, error_code=NO_ERROR(0), opaque_data=) + [id=2] [ 1.838] send DATA frame (length=127, flags=0, stream_id=1) + [id=2] [ 1.838] send DATA frame (length=0, flags=1, stream_id=1) + [id=2] [ 1.838] stream_id=1 closed + [id=2] [ 1.839] closed + +nghttpx - proxy ++++++++++++++++ + +The ``nghttpx`` is a multi-threaded reverse proxy for +HTTP-draft-04/2.0, SPDY/HTTPS. It has several operation modes: + +================== ======================== ======== ====================== +Mode option Frontend Backend Note +================== ======================== ======== ====================== +default HTTP/2.0, SPDY, HTTPS HTTP/1.1 Reverse proxy +``--spdy`` HTTP/2.0, SPDY, HTTPS HTTP/1.1 SPDY proxy +``--spdy-bridge`` HTTP/2.0, SPDY, HTTPS HTTP/2.0 SPDY proxy +``--client`` HTTP/1.1 HTTP/2.0 1.1 <-> 2.0 conversion +``--client-proxy`` HTTP/1.1 HTTP/2.0 Forward proxy +================== ======================== ======== ====================== + +The interesting mode at the moment is the default mode. It works like +a reverse proxy and listens HTTP-draft-04/2.0 as well as SPDY and +HTTPS and can be deployed SSL/TLS terminator for existing web server. + +The ``nghttpx`` supports configuration file. See ``--conf`` option and +sample configuration file ``nghttpx.conf.sample``. + +The ``nghttpx`` is ported from ``shrpx`` in spdylay project, and it +still has SPDY color in option names. They will be fixed as the +development goes. + +Without any of ``-s``, ``--spdy-bridge``, ``-p`` and ``--client`` +options, ``nghttpx`` works as reverse proxy to the backend server:: + + Client <-- (HTTP/2.0, SPDY, HTTPS) --> nghttpx <-- (HTTP) --> Web Server + [reverse proxy] + +With ``-s`` option, it works as so called secure SPDY proxy:: + + Client <-- (HTTP/2.0, SPDY, HTTPS) --> nghttpx <-- (HTTP) --> Proxy + [SPDY proxy] (e.g., Squid) + +The ``Client`` in the above is needs to be configured to use nghttpx as +secure SPDY proxy. + +At the time of this writing, Chrome is the only browser which supports +secure SPDY proxy. The one way to configure Chrome to use secure SPDY +proxy is create proxy.pac script like this:: + + function FindProxyForURL(url, host) { + return "HTTPS SERVERADDR:PORT"; + } + +``SERVERADDR`` and ``PORT`` is the hostname/address and port of the +machine nghttpx is running. Please note that Chrome requires valid +certificate for secure SPDY proxy. + +Then run chrome with the following arguments:: + + $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn + +With ``--spdy-bridge``, it accepts HTTP/2.0, SPDY and HTTPS +connections and communicates with backend in HTTP/2.0:: + + Client <-- (HTTP/2.0, SPDY, HTTPS) --> nghttpx <-- (HTTP/2.0) --> Web or HTTP/2.0 Proxy etc + [SPDY bridge] (e.g., nghttpx -s) + +With ``-p`` option, it works as forward proxy and expects that the +backend is HTTP/2.0 proxy:: + + Client <-- (HTTP) --> nghttpx <-- (HTTP/2.0) --> HTTP/2.0 Proxy + [forward proxy] (e.g., nghttpx -s) + +The ``Client`` is needs to be configured to use nghttpx as forward proxy. + +With the above configuration, one can use HTTP/1.1 client to access +and test their HTTP/2.0 servers. + +With ``--client`` option, it works as reverse proxy and expects that +the backend is HTTP/2.0 Web server:: + + Client <-- (HTTP) --> nghttpx <-- (HTTP/2.0) --> Web Server + [reverse proxy] + +For the operation modes which talk to the backend in HTTP/2.0, the +backend connections can be tunneled though HTTP proxy. The proxy is +specified using ``--backend-http-proxy-uri`` option. The following +figure illustrates the example of ``--spdy-bridge`` and +``--backend-http-proxy-uri`` option to talk to the outside HTTP/2.0 proxy +through HTTP proxy:: + + Client <-- (HTTP/2.0, SPDY, HTTPS) --> nghttpx <-- (HTTP/2.0) -- + [SPDY bridge] + + --===================---> HTTP/2.0 Proxy + (HTTP proxy tunnel) (e.g., nghttpx -s)