1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/xpcshell/node-spdy/README.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,150 @@
1.4 +# SPDY Server for node.js [](http://travis-ci.org/indutny/node-spdy)
1.5 +
1.6 +<a href="http://flattr.com/thing/758213/indutnynode-spdy-on-GitHub" target="_blank">
1.7 +<img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a>
1.8 +
1.9 +With this module you can create [SPDY](http://www.chromium.org/spdy) servers
1.10 +in node.js with natural http module interface and fallback to regular https
1.11 +(for browsers that doesn't support SPDY yet).
1.12 +
1.13 +## Usage
1.14 +
1.15 +```javascript
1.16 +var spdy = require('spdy'),
1.17 + fs = require('fs');
1.18 +
1.19 +var options = {
1.20 + key: fs.readFileSync(__dirname + '/keys/spdy-key.pem'),
1.21 + cert: fs.readFileSync(__dirname + '/keys/spdy-cert.pem'),
1.22 + ca: fs.readFileSync(__dirname + '/keys/spdy-csr.pem'),
1.23 +
1.24 + // SPDY-specific options
1.25 + windowSize: 1024, // Server's window size
1.26 +};
1.27 +
1.28 +var server = spdy.createServer(options, function(req, res) {
1.29 + res.writeHead(200);
1.30 + res.end('hello world!');
1.31 +});
1.32 +
1.33 +server.listen(443);
1.34 +```
1.35 +
1.36 +And by popular demand - usage with
1.37 +[express](https://github.com/visionmedia/express):
1.38 +
1.39 +```javascript
1.40 +var spdy = require('spdy'),
1.41 + express = require('express'),
1.42 + fs = require('fs');
1.43 +
1.44 +var options = { /* the same as above */ };
1.45 +
1.46 +var app = express();
1.47 +
1.48 +app.use(/* your favorite middleware */);
1.49 +
1.50 +var server = spdy.createServer(options, app);
1.51 +
1.52 +server.listen(443);
1.53 +```
1.54 +
1.55 +## API
1.56 +
1.57 +API is compatible with `http` and `https` module, but you can use another
1.58 +function as base class for SPDYServer.
1.59 +
1.60 +```javascript
1.61 +spdy.createServer(
1.62 + [base class constructor, i.e. https.Server],
1.63 + { /* keys and options */ }, // <- the only one required argument
1.64 + [request listener]
1.65 +).listen([port], [host], [callback]);
1.66 +```
1.67 +
1.68 +Request listener will receive two arguments: `request` and `response`. They're
1.69 +both instances of `http`'s `IncomingMessage` and `OutgoingMessage`. But three
1.70 +custom properties are added to both of them: `streamID`, `isSpdy`,
1.71 +`spdyVersion`. The first one indicates on which spdy stream are sitting request
1.72 +and response. Second is always true and can be checked to ensure that incoming
1.73 +request wasn't received by HTTPS fallback and last one is a number representing
1.74 +used SPDY protocol version (2 or 3 for now).
1.75 +
1.76 +### Push streams
1.77 +
1.78 +It is possible to initiate 'push' streams to send content to clients _before_
1.79 +the client requests it.
1.80 +
1.81 +```javascript
1.82 +spdy.createServer(options, function(req, res) {
1.83 + var headers = { 'content-type': 'application/javascript' };
1.84 + res.push('/main.js', headers, function(err, stream) {
1.85 + if (err) return;
1.86 +
1.87 + stream.end('alert("hello from push stream!");');
1.88 + });
1.89 +
1.90 + res.end('<script src="/main.js"></script>');
1.91 +}).listen(443);
1.92 +```
1.93 +
1.94 +Push is accomplished via the `push()` method invoked on the current response
1.95 +object (this works for express.js response objects as well). The format of the
1.96 +`push()` method is:
1.97 +
1.98 +`.push('full or relative url', { ... headers ... }, optional priority, callback)`
1.99 +
1.100 +You can use either full ( `http://host/path` ) or relative ( `/path` ) urls with
1.101 +`.push()`. `headers` are the same as for regular response object. `callback`
1.102 +will receive two arguments: `err` (if any error is happened) and `stream`
1.103 +(stream object have API compatible with a
1.104 +[net.Socket](http://nodejs.org/docs/latest/api/net.html#net.Socket) ).
1.105 +
1.106 +### Options
1.107 +
1.108 +All options supported by
1.109 +[tls](http://nodejs.org/docs/latest/api/tls.html#tls.createServer) are working
1.110 +with node-spdy. In addition, `maxStreams` options is available. it allows you
1.111 +controlling [maximum concurrent streams][http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft2#TOC-SETTINGS]
1.112 +protocol option (if client will start more streams than that limit, RST_STREAM
1.113 +will be sent for each additional stream).
1.114 +
1.115 +Additional options:
1.116 +
1.117 +* `plain` - if defined, server will accept only plain (non-encrypted)
1.118 + connections.
1.119 +
1.120 +#### Contributors
1.121 +
1.122 +* [Fedor Indutny](https://github.com/indutny)
1.123 +* [Chris Strom](https://github.com/eee-c)
1.124 +* [François de Metz](https://github.com/francois2metz)
1.125 +* [Ilya Grigorik](https://github.com/igrigorik)
1.126 +* [Roberto Peon](https://github.com/grmocg)
1.127 +* [Tatsuhiro Tsujikawa](https://github.com/tatsuhiro-t)
1.128 +* [Jesse Cravens](https://github.com/jessecravens)
1.129 +
1.130 +#### LICENSE
1.131 +
1.132 +This software is licensed under the MIT License.
1.133 +
1.134 +Copyright Fedor Indutny, 2012.
1.135 +
1.136 +Permission is hereby granted, free of charge, to any person obtaining a
1.137 +copy of this software and associated documentation files (the
1.138 +"Software"), to deal in the Software without restriction, including
1.139 +without limitation the rights to use, copy, modify, merge, publish,
1.140 +distribute, sublicense, and/or sell copies of the Software, and to permit
1.141 +persons to whom the Software is furnished to do so, subject to the
1.142 +following conditions:
1.143 +
1.144 +The above copyright notice and this permission notice shall be included
1.145 +in all copies or substantial portions of the Software.
1.146 +
1.147 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
1.148 +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1.149 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
1.150 +NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
1.151 +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
1.152 +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
1.153 +USE OR OTHER DEALINGS IN THE SOFTWARE.
