1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/xpcshell/node-http2/README.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,167 @@
1.4 +node-http2
1.5 +==========
1.6 +
1.7 +An HTTP/2 ([draft-ietf-httpbis-http2-10](http://tools.ietf.org/html/draft-ietf-httpbis-http2-10))
1.8 +client and server implementation for node.js.
1.9 +
1.10 +Installation
1.11 +------------
1.12 +
1.13 +```
1.14 +npm install http2
1.15 +```
1.16 +
1.17 +API
1.18 +---
1.19 +
1.20 +The API is very similar to the [standard node.js HTTPS API](http://nodejs.org/api/https.html). The
1.21 +goal is the perfect API compatibility, with additional HTTP2 related extensions (like server push).
1.22 +
1.23 +Detailed API documentation is primarily maintained in the `lib/http.js` file and is [available in
1.24 +the wiki](https://github.com/molnarg/node-http2/wiki/Public-API) as well.
1.25 +
1.26 +Examples
1.27 +--------
1.28 +
1.29 +### Using as a server ###
1.30 +
1.31 +```javascript
1.32 +var options = {
1.33 + key: fs.readFileSync('./example/localhost.key'),
1.34 + cert: fs.readFileSync('./example/localhost.crt')
1.35 +};
1.36 +
1.37 +require('http2').createServer(options, function(request, response) {
1.38 + response.end('Hello world!');
1.39 +}).listen(8080);
1.40 +```
1.41 +
1.42 +### Using as a client ###
1.43 +
1.44 +```javascript
1.45 +process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
1.46 +
1.47 +require('http2').get('https://localhost:8080/', function(response) {
1.48 + response.pipe(process.stdout);
1.49 +});
1.50 +```
1.51 +
1.52 +### Simple static file server ###
1.53 +
1.54 +An simple static file server serving up content from its own directory is available in the `example`
1.55 +directory. Running the server:
1.56 +
1.57 +```bash
1.58 +$ node ./example/server.js
1.59 +```
1.60 +
1.61 +### Simple command line client ###
1.62 +
1.63 +An example client is also available. Downloading the server's own source code from the server:
1.64 +
1.65 +```bash
1.66 +$ node ./example/client.js 'https://localhost:8080/server.js' >/tmp/server.js
1.67 +```
1.68 +
1.69 +### Server push ###
1.70 +
1.71 +For a server push example, see the source code of the example
1.72 +[server](https://github.com/molnarg/node-http2/blob/master/example/server.js) and
1.73 +[client](https://github.com/molnarg/node-http2/blob/master/example/client.js).
1.74 +
1.75 +Status
1.76 +------
1.77 +
1.78 +* ALPN is not yet supported in node.js (see
1.79 + [this issue](https://github.com/joyent/node/issues/5945)). For ALPN support, you will have to use
1.80 + [Shigeki Ohtsu's node.js fork](https://github.com/shigeki/node/tree/alpn_support) until this code
1.81 + gets merged upstream.
1.82 +* Upgrade mechanism to start HTTP/2 over unencrypted channel is not implemented yet
1.83 + (issue [#4](https://github.com/molnarg/node-http2/issues/4))
1.84 +* Other minor features found in
1.85 + [this list](https://github.com/molnarg/node-http2/issues?labels=feature) are not implemented yet
1.86 +
1.87 +Development
1.88 +-----------
1.89 +
1.90 +### Development dependencies ###
1.91 +
1.92 +There's a few library you will need to have installed to do anything described in the following
1.93 +sections. After installing/cloning node-http2, run `npm install` in its directory to install
1.94 +development dependencies.
1.95 +
1.96 +Used libraries:
1.97 +
1.98 +* [mocha](http://visionmedia.github.io/mocha/) for tests
1.99 +* [chai](http://chaijs.com/) for assertions
1.100 +* [istanbul](https://github.com/gotwarlost/istanbul) for code coverage analysis
1.101 +* [docco](http://jashkenas.github.io/docco/) for developer documentation
1.102 +* [bunyan](https://github.com/trentm/node-bunyan) for logging
1.103 +
1.104 +For pretty printing logs, you will also need a global install of bunyan (`npm install -g bunyan`).
1.105 +
1.106 +### Developer documentation ###
1.107 +
1.108 +The developer documentation is generated from the source code using docco and can be viewed online
1.109 +[here](http://molnarg.github.io/node-http2/doc/). If you'd like to have an offline copy, just run
1.110 +`npm run-script doc`.
1.111 +
1.112 +### Running the tests ###
1.113 +
1.114 +It's easy, just run `npm test`. The tests are written in BDD style, so they are a good starting
1.115 +point to understand the code.
1.116 +
1.117 +### Test coverage ###
1.118 +
1.119 +To generate a code coverage report, run `npm test --coverage` (which runs very slowly, be patient).
1.120 +Code coverage summary as of version 1.0.1:
1.121 +```
1.122 +Statements : 93.26% ( 1563/1676 )
1.123 +Branches : 84.85% ( 605/713 )
1.124 +Functions : 94.81% ( 201/212 )
1.125 +Lines : 93.23% ( 1557/1670 )
1.126 +```
1.127 +
1.128 +There's a hosted version of the detailed (line-by-line) coverage report
1.129 +[here](http://molnarg.github.io/node-http2/coverage/lcov-report/lib/).
1.130 +
1.131 +### Logging ###
1.132 +
1.133 +Logging is turned off by default. You can turn it on by passing a bunyan logger as `log` option when
1.134 +creating a server or agent.
1.135 +
1.136 +When using the example server or client, it's very easy to turn logging on: set the `HTTP2_LOG`
1.137 +environment variable to `fatal`, `error`, `warn`, `info`, `debug` or `trace` (the logging level).
1.138 +To log every single incoming and outgoing data chunk, use `HTTP2_LOG_DATA=1` besides
1.139 +`HTTP2_LOG=trace`. Log output goes to the standard error output. If the standard error is redirected
1.140 +into a file, then the log output is in bunyan's JSON format for easier post-mortem analysis.
1.141 +
1.142 +Running the example server and client with `info` level logging output:
1.143 +
1.144 +```bash
1.145 +$ HTTP2_LOG=info node ./example/server.js
1.146 +```
1.147 +
1.148 +```bash
1.149 +$ HTTP2_LOG=info node ./example/client.js 'http://localhost:8080/server.js' >/dev/null
1.150 +```
1.151 +
1.152 +Contributors
1.153 +------------
1.154 +
1.155 +Code contributions are always welcome! People who contributed to node-http2 so far:
1.156 +
1.157 +* Nick Hurley
1.158 +* Mike Belshe
1.159 +
1.160 +Special thanks to Google for financing the development of this module as part of their [Summer of
1.161 +Code program](https://developers.google.com/open-source/soc/) (project: [HTTP/2 prototype server
1.162 +implementation](https://google-melange.appspot.com/gsoc/project/google/gsoc2013/molnarg/5001)), and
1.163 +Nick Hurley of Mozilla, my GSoC mentor, who helped with regular code review and technical advices.
1.164 +
1.165 +License
1.166 +-------
1.167 +
1.168 +The MIT License
1.169 +
1.170 +Copyright (C) 2013 Gábor Molnár <gabor@molnar.es>
