• file
• revisions
• annotate
• diff
• comparison
• raw

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

testing/xpcshell/node-http2/README.md

Wed, 31 Dec 2014 06:09:35 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 06:09:35 +0100

changeset 0

6474c204b198

permissions

-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

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>