The Tor Browser / annotate

testing/xpcshell/node-http2/README.md@b8a032363ba2 (annotated)

testing/xpcshell/node-http2/README.md

Thu, 22 Jan 2015 13:21:57 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Thu, 22 Jan 2015 13:21:57 +0100
branch
TOR_BUG_9701
changeset 15
b8a032363ba2
permissions
-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0 1 node-http2
michael@0 2 ==========
michael@0 3
michael@0 4 An HTTP/2 ([draft-ietf-httpbis-http2-10](http://tools.ietf.org/html/draft-ietf-httpbis-http2-10))
michael@0 5 client and server implementation for node.js.
michael@0 6
michael@0 7 Installation
michael@0 8 ------------
michael@0 9
michael@0 10 ```
michael@0 11 npm install http2
michael@0 12 ```
michael@0 13
michael@0 14 API
michael@0 15 ---
michael@0 16
michael@0 17 The API is very similar to the [standard node.js HTTPS API](http://nodejs.org/api/https.html). The
michael@0 18 goal is the perfect API compatibility, with additional HTTP2 related extensions (like server push).
michael@0 19
michael@0 20 Detailed API documentation is primarily maintained in the `lib/http.js` file and is [available in
michael@0 21 the wiki](https://github.com/molnarg/node-http2/wiki/Public-API) as well.
michael@0 22
michael@0 23 Examples
michael@0 24 --------
michael@0 25
michael@0 26 ### Using as a server ###
michael@0 27
michael@0 28 ```javascript
michael@0 29 var options = {
michael@0 30 key: fs.readFileSync('./example/localhost.key'),
michael@0 31 cert: fs.readFileSync('./example/localhost.crt')
michael@0 32 };
michael@0 33
michael@0 34 require('http2').createServer(options, function(request, response) {
michael@0 35 response.end('Hello world!');
michael@0 36 }).listen(8080);
michael@0 37 ```
michael@0 38
michael@0 39 ### Using as a client ###
michael@0 40
michael@0 41 ```javascript
michael@0 42 process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
michael@0 43
michael@0 44 require('http2').get('https://localhost:8080/', function(response) {
michael@0 45 response.pipe(process.stdout);
michael@0 46 });
michael@0 47 ```
michael@0 48
michael@0 49 ### Simple static file server ###
michael@0 50
michael@0 51 An simple static file server serving up content from its own directory is available in the `example`
michael@0 52 directory. Running the server:
michael@0 53
michael@0 54 ```bash
michael@0 55 $ node ./example/server.js
michael@0 56 ```
michael@0 57
michael@0 58 ### Simple command line client ###
michael@0 59
michael@0 60 An example client is also available. Downloading the server's own source code from the server:
michael@0 61
michael@0 62 ```bash
michael@0 63 $ node ./example/client.js 'https://localhost:8080/server.js' >/tmp/server.js
michael@0 64 ```
michael@0 65
michael@0 66 ### Server push ###
michael@0 67
michael@0 68 For a server push example, see the source code of the example
michael@0 69 [server](https://github.com/molnarg/node-http2/blob/master/example/server.js) and
michael@0 70 [client](https://github.com/molnarg/node-http2/blob/master/example/client.js).
michael@0 71
michael@0 72 Status
michael@0 73 ------
michael@0 74
michael@0 75 * ALPN is not yet supported in node.js (see
michael@0 76 [this issue](https://github.com/joyent/node/issues/5945)). For ALPN support, you will have to use
michael@0 77 [Shigeki Ohtsu's node.js fork](https://github.com/shigeki/node/tree/alpn_support) until this code
michael@0 78 gets merged upstream.
michael@0 79 * Upgrade mechanism to start HTTP/2 over unencrypted channel is not implemented yet
michael@0 80 (issue [#4](https://github.com/molnarg/node-http2/issues/4))
michael@0 81 * Other minor features found in
michael@0 82 [this list](https://github.com/molnarg/node-http2/issues?labels=feature) are not implemented yet
michael@0 83
michael@0 84 Development
michael@0 85 -----------
michael@0 86
michael@0 87 ### Development dependencies ###
michael@0 88
michael@0 89 There's a few library you will need to have installed to do anything described in the following
michael@0 90 sections. After installing/cloning node-http2, run `npm install` in its directory to install
michael@0 91 development dependencies.
michael@0 92
michael@0 93 Used libraries:
michael@0 94
michael@0 95 * [mocha](http://visionmedia.github.io/mocha/) for tests
michael@0 96 * [chai](http://chaijs.com/) for assertions
michael@0 97 * [istanbul](https://github.com/gotwarlost/istanbul) for code coverage analysis
michael@0 98 * [docco](http://jashkenas.github.io/docco/) for developer documentation
michael@0 99 * [bunyan](https://github.com/trentm/node-bunyan) for logging
michael@0 100
michael@0 101 For pretty printing logs, you will also need a global install of bunyan (`npm install -g bunyan`).
michael@0 102
michael@0 103 ### Developer documentation ###
michael@0 104
michael@0 105 The developer documentation is generated from the source code using docco and can be viewed online
michael@0 106 [here](http://molnarg.github.io/node-http2/doc/). If you'd like to have an offline copy, just run
michael@0 107 `npm run-script doc`.
michael@0 108
michael@0 109 ### Running the tests ###
michael@0 110
michael@0 111 It's easy, just run `npm test`. The tests are written in BDD style, so they are a good starting
michael@0 112 point to understand the code.
michael@0 113
michael@0 114 ### Test coverage ###
michael@0 115
michael@0 116 To generate a code coverage report, run `npm test --coverage` (which runs very slowly, be patient).
michael@0 117 Code coverage summary as of version 1.0.1:
michael@0 118 ```
michael@0 119 Statements : 93.26% ( 1563/1676 )
michael@0 120 Branches : 84.85% ( 605/713 )
michael@0 121 Functions : 94.81% ( 201/212 )
michael@0 122 Lines : 93.23% ( 1557/1670 )
michael@0 123 ```
michael@0 124
michael@0 125 There's a hosted version of the detailed (line-by-line) coverage report
michael@0 126 [here](http://molnarg.github.io/node-http2/coverage/lcov-report/lib/).
michael@0 127
michael@0 128 ### Logging ###
michael@0 129
michael@0 130 Logging is turned off by default. You can turn it on by passing a bunyan logger as `log` option when
michael@0 131 creating a server or agent.
michael@0 132
michael@0 133 When using the example server or client, it's very easy to turn logging on: set the `HTTP2_LOG`
michael@0 134 environment variable to `fatal`, `error`, `warn`, `info`, `debug` or `trace` (the logging level).
michael@0 135 To log every single incoming and outgoing data chunk, use `HTTP2_LOG_DATA=1` besides
michael@0 136 `HTTP2_LOG=trace`. Log output goes to the standard error output. If the standard error is redirected
michael@0 137 into a file, then the log output is in bunyan's JSON format for easier post-mortem analysis.
michael@0 138
michael@0 139 Running the example server and client with `info` level logging output:
michael@0 140
michael@0 141 ```bash
michael@0 142 $ HTTP2_LOG=info node ./example/server.js
michael@0 143 ```
michael@0 144
michael@0 145 ```bash
michael@0 146 $ HTTP2_LOG=info node ./example/client.js 'http://localhost:8080/server.js' >/dev/null
michael@0 147 ```
michael@0 148
michael@0 149 Contributors
michael@0 150 ------------
michael@0 151
michael@0 152 Code contributions are always welcome! People who contributed to node-http2 so far:
michael@0 153
michael@0 154 * Nick Hurley
michael@0 155 * Mike Belshe
michael@0 156
michael@0 157 Special thanks to Google for financing the development of this module as part of their [Summer of
michael@0 158 Code program](https://developers.google.com/open-source/soc/) (project: [HTTP/2 prototype server
michael@0 159 implementation](https://google-melange.appspot.com/gsoc/project/google/gsoc2013/molnarg/5001)), and
michael@0 160 Nick Hurley of Mozilla, my GSoC mentor, who helped with regular code review and technical advices.
michael@0 161
michael@0 162 License
michael@0 163 -------
michael@0 164
michael@0 165 The MIT License
michael@0 166
michael@0 167 Copyright (C) 2013 Gábor Molnár <gabor@molnar.es>

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial