michael@0: # SPDY Server for node.js [![Build Status](https://secure.travis-ci.org/indutny/node-spdy.png)](http://travis-ci.org/indutny/node-spdy)
michael@0: 
michael@0: <a href="http://flattr.com/thing/758213/indutnynode-spdy-on-GitHub" target="_blank">
michael@0: <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a>
michael@0: 
michael@0: With this module you can create [SPDY](http://www.chromium.org/spdy) servers
michael@0: in node.js with natural http module interface and fallback to regular https
michael@0: (for browsers that doesn't support SPDY yet).
michael@0: 
michael@0: ## Usage
michael@0: 
michael@0: ```javascript
michael@0: var spdy = require('spdy'),
michael@0:     fs = require('fs');
michael@0: 
michael@0: var options = {
michael@0:   key: fs.readFileSync(__dirname + '/keys/spdy-key.pem'),
michael@0:   cert: fs.readFileSync(__dirname + '/keys/spdy-cert.pem'),
michael@0:   ca: fs.readFileSync(__dirname + '/keys/spdy-csr.pem'),
michael@0: 
michael@0:   // SPDY-specific options
michael@0:   windowSize: 1024, // Server's window size
michael@0: };
michael@0: 
michael@0: var server = spdy.createServer(options, function(req, res) {
michael@0:   res.writeHead(200);
michael@0:   res.end('hello world!');
michael@0: });
michael@0: 
michael@0: server.listen(443);
michael@0: ```
michael@0: 
michael@0: And by popular demand - usage with
michael@0: [express](https://github.com/visionmedia/express):
michael@0: 
michael@0: ```javascript
michael@0: var spdy = require('spdy'),
michael@0:     express = require('express'),
michael@0:     fs = require('fs');
michael@0: 
michael@0: var options = { /* the same as above */ };
michael@0: 
michael@0: var app = express();
michael@0: 
michael@0: app.use(/* your favorite middleware */);
michael@0: 
michael@0: var server = spdy.createServer(options, app);
michael@0: 
michael@0: server.listen(443);
michael@0: ```
michael@0: 
michael@0: ## API
michael@0: 
michael@0: API is compatible with `http` and `https` module, but you can use another
michael@0: function as base class for SPDYServer.
michael@0: 
michael@0: ```javascript
michael@0: spdy.createServer(
michael@0:   [base class constructor, i.e. https.Server],
michael@0:   { /* keys and options */ }, // <- the only one required argument
michael@0:   [request listener]
michael@0: ).listen([port], [host], [callback]);
michael@0: ```
michael@0: 
michael@0: Request listener will receive two arguments: `request` and `response`. They're
michael@0: both instances of `http`'s `IncomingMessage` and `OutgoingMessage`. But three
michael@0: custom properties are added to both of them: `streamID`, `isSpdy`,
michael@0: `spdyVersion`. The first one indicates on which spdy stream are sitting request
michael@0: and response. Second is always true and can be checked to ensure that incoming
michael@0: request wasn't received by HTTPS fallback and last one is a number representing
michael@0: used SPDY protocol version (2 or 3 for now).
michael@0: 
michael@0: ### Push streams
michael@0: 
michael@0: It is possible to initiate 'push' streams to send content to clients _before_
michael@0: the client requests it.
michael@0: 
michael@0: ```javascript
michael@0: spdy.createServer(options, function(req, res) {
michael@0:   var headers = { 'content-type': 'application/javascript' };
michael@0:   res.push('/main.js', headers, function(err, stream) {
michael@0:     if (err) return;
michael@0: 
michael@0:     stream.end('alert("hello from push stream!");');
michael@0:   });
michael@0: 
michael@0:   res.end('<script src="/main.js"></script>');
michael@0: }).listen(443);
michael@0: ```
michael@0: 
michael@0: Push is accomplished via the `push()` method invoked on the current response
michael@0: object (this works for express.js response objects as well).  The format of the
michael@0: `push()` method is:
michael@0: 
michael@0: `.push('full or relative url', { ... headers ... }, optional priority, callback)`
michael@0: 
michael@0: You can use either full ( `http://host/path` ) or relative ( `/path` ) urls with
michael@0: `.push()`. `headers` are the same as for regular response object. `callback`
michael@0: will receive two arguments: `err` (if any error is happened) and `stream`
michael@0: (stream object have API compatible with a
michael@0: [net.Socket](http://nodejs.org/docs/latest/api/net.html#net.Socket) ).
michael@0: 
michael@0: ### Options
michael@0: 
michael@0: All options supported by
michael@0: [tls](http://nodejs.org/docs/latest/api/tls.html#tls.createServer) are working
michael@0: with node-spdy. In addition, `maxStreams` options is available. it allows you
michael@0: controlling [maximum concurrent streams][http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft2#TOC-SETTINGS]
michael@0: protocol option (if client will start more streams than that limit, RST_STREAM
michael@0: will be sent for each additional stream).
michael@0: 
michael@0: Additional options:
michael@0: 
michael@0: * `plain` - if defined, server will accept only plain (non-encrypted)
michael@0:   connections.
michael@0: 
michael@0: #### Contributors
michael@0: 
michael@0: * [Fedor Indutny](https://github.com/indutny)
michael@0: * [Chris Strom](https://github.com/eee-c)
michael@0: * [François de Metz](https://github.com/francois2metz)
michael@0: * [Ilya Grigorik](https://github.com/igrigorik)
michael@0: * [Roberto Peon](https://github.com/grmocg)
michael@0: * [Tatsuhiro Tsujikawa](https://github.com/tatsuhiro-t)
michael@0: * [Jesse Cravens](https://github.com/jessecravens)
michael@0: 
michael@0: #### LICENSE
michael@0: 
michael@0: This software is licensed under the MIT License.
michael@0: 
michael@0: Copyright Fedor Indutny, 2012.
michael@0: 
michael@0: Permission is hereby granted, free of charge, to any person obtaining a
michael@0: copy of this software and associated documentation files (the
michael@0: "Software"), to deal in the Software without restriction, including
michael@0: without limitation the rights to use, copy, modify, merge, publish,
michael@0: distribute, sublicense, and/or sell copies of the Software, and to permit
michael@0: persons to whom the Software is furnished to do so, subject to the
michael@0: following conditions:
michael@0: 
michael@0: The above copyright notice and this permission notice shall be included
michael@0: in all copies or substantial portions of the Software.
michael@0: 
michael@0: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
michael@0: OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
michael@0: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
michael@0: NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
michael@0: DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
michael@0: OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
michael@0: USE OR OTHER DEALINGS IN THE SOFTWARE.