michael@0: node-http2 michael@0: ========== michael@0: michael@0: An HTTP/2 ([draft-ietf-httpbis-http2-10](http://tools.ietf.org/html/draft-ietf-httpbis-http2-10)) michael@0: client and server implementation for node.js. michael@0: michael@0: Installation michael@0: ------------ michael@0: michael@0: ``` michael@0: npm install http2 michael@0: ``` michael@0: michael@0: API michael@0: --- michael@0: michael@0: The API is very similar to the [standard node.js HTTPS API](http://nodejs.org/api/https.html). The michael@0: goal is the perfect API compatibility, with additional HTTP2 related extensions (like server push). michael@0: michael@0: Detailed API documentation is primarily maintained in the `lib/http.js` file and is [available in michael@0: the wiki](https://github.com/molnarg/node-http2/wiki/Public-API) as well. michael@0: michael@0: Examples michael@0: -------- michael@0: michael@0: ### Using as a server ### michael@0: michael@0: ```javascript michael@0: var options = { michael@0: key: fs.readFileSync('./example/localhost.key'), michael@0: cert: fs.readFileSync('./example/localhost.crt') michael@0: }; michael@0: michael@0: require('http2').createServer(options, function(request, response) { michael@0: response.end('Hello world!'); michael@0: }).listen(8080); michael@0: ``` michael@0: michael@0: ### Using as a client ### michael@0: michael@0: ```javascript michael@0: process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; michael@0: michael@0: require('http2').get('https://localhost:8080/', function(response) { michael@0: response.pipe(process.stdout); michael@0: }); michael@0: ``` michael@0: michael@0: ### Simple static file server ### michael@0: michael@0: An simple static file server serving up content from its own directory is available in the `example` michael@0: directory. Running the server: michael@0: michael@0: ```bash michael@0: $ node ./example/server.js michael@0: ``` michael@0: michael@0: ### Simple command line client ### michael@0: michael@0: An example client is also available. Downloading the server's own source code from the server: michael@0: michael@0: ```bash michael@0: $ node ./example/client.js 'https://localhost:8080/server.js' >/tmp/server.js michael@0: ``` michael@0: michael@0: ### Server push ### michael@0: michael@0: For a server push example, see the source code of the example michael@0: [server](https://github.com/molnarg/node-http2/blob/master/example/server.js) and michael@0: [client](https://github.com/molnarg/node-http2/blob/master/example/client.js). michael@0: michael@0: Status michael@0: ------ michael@0: michael@0: * ALPN is not yet supported in node.js (see michael@0: [this issue](https://github.com/joyent/node/issues/5945)). For ALPN support, you will have to use michael@0: [Shigeki Ohtsu's node.js fork](https://github.com/shigeki/node/tree/alpn_support) until this code michael@0: gets merged upstream. michael@0: * Upgrade mechanism to start HTTP/2 over unencrypted channel is not implemented yet michael@0: (issue [#4](https://github.com/molnarg/node-http2/issues/4)) michael@0: * Other minor features found in michael@0: [this list](https://github.com/molnarg/node-http2/issues?labels=feature) are not implemented yet michael@0: michael@0: Development michael@0: ----------- michael@0: michael@0: ### Development dependencies ### michael@0: michael@0: There's a few library you will need to have installed to do anything described in the following michael@0: sections. After installing/cloning node-http2, run `npm install` in its directory to install michael@0: development dependencies. michael@0: michael@0: Used libraries: michael@0: michael@0: * [mocha](http://visionmedia.github.io/mocha/) for tests michael@0: * [chai](http://chaijs.com/) for assertions michael@0: * [istanbul](https://github.com/gotwarlost/istanbul) for code coverage analysis michael@0: * [docco](http://jashkenas.github.io/docco/) for developer documentation michael@0: * [bunyan](https://github.com/trentm/node-bunyan) for logging michael@0: michael@0: For pretty printing logs, you will also need a global install of bunyan (`npm install -g bunyan`). michael@0: michael@0: ### Developer documentation ### michael@0: michael@0: The developer documentation is generated from the source code using docco and can be viewed online michael@0: [here](http://molnarg.github.io/node-http2/doc/). If you'd like to have an offline copy, just run michael@0: `npm run-script doc`. michael@0: michael@0: ### Running the tests ### michael@0: michael@0: It's easy, just run `npm test`. The tests are written in BDD style, so they are a good starting michael@0: point to understand the code. michael@0: michael@0: ### Test coverage ### michael@0: michael@0: To generate a code coverage report, run `npm test --coverage` (which runs very slowly, be patient). michael@0: Code coverage summary as of version 1.0.1: michael@0: ``` michael@0: Statements : 93.26% ( 1563/1676 ) michael@0: Branches : 84.85% ( 605/713 ) michael@0: Functions : 94.81% ( 201/212 ) michael@0: Lines : 93.23% ( 1557/1670 ) michael@0: ``` michael@0: michael@0: There's a hosted version of the detailed (line-by-line) coverage report michael@0: [here](http://molnarg.github.io/node-http2/coverage/lcov-report/lib/). michael@0: michael@0: ### Logging ### michael@0: michael@0: Logging is turned off by default. You can turn it on by passing a bunyan logger as `log` option when michael@0: creating a server or agent. michael@0: michael@0: When using the example server or client, it's very easy to turn logging on: set the `HTTP2_LOG` michael@0: environment variable to `fatal`, `error`, `warn`, `info`, `debug` or `trace` (the logging level). michael@0: To log every single incoming and outgoing data chunk, use `HTTP2_LOG_DATA=1` besides michael@0: `HTTP2_LOG=trace`. Log output goes to the standard error output. If the standard error is redirected michael@0: into a file, then the log output is in bunyan's JSON format for easier post-mortem analysis. michael@0: michael@0: Running the example server and client with `info` level logging output: michael@0: michael@0: ```bash michael@0: $ HTTP2_LOG=info node ./example/server.js michael@0: ``` michael@0: michael@0: ```bash michael@0: $ HTTP2_LOG=info node ./example/client.js 'http://localhost:8080/server.js' >/dev/null michael@0: ``` michael@0: michael@0: Contributors michael@0: ------------ michael@0: michael@0: Code contributions are always welcome! People who contributed to node-http2 so far: michael@0: michael@0: * Nick Hurley michael@0: * Mike Belshe michael@0: michael@0: Special thanks to Google for financing the development of this module as part of their [Summer of michael@0: Code program](https://developers.google.com/open-source/soc/) (project: [HTTP/2 prototype server michael@0: implementation](https://google-melange.appspot.com/gsoc/project/google/gsoc2013/molnarg/5001)), and michael@0: Nick Hurley of Mozilla, my GSoC mentor, who helped with regular code review and technical advices. michael@0: michael@0: License michael@0: ------- michael@0: michael@0: The MIT License michael@0: michael@0: Copyright (C) 2013 Gábor Molnár