1
  2<img src="https://github.com/flatiron/union/raw/master/union.png" />
  3
  4# Synopsis
  5A hybrid streaming middleware kernel backwards compatible with connect.
  6
  7# Motivation
  8The advantage to streaming middlewares is that they do not require buffering the entire stream in order to execute their function.
  9
 10# Status
 11
 12[![Build Status](https://secure.travis-ci.org/flatiron/union.png)](http://travis-ci.org/flatiron/union)
 13
 14# Installation
 15There are a few ways to use `union`. Install the library using npm. You can add it to your `package.json` file as a dependancy
 16
 17```bash
 18  $ [sudo] npm install union
 19```
 20
 21## Usage
 22Union's request handling is [connect](https://github.com/senchalabs/connect)-compatible, meaning that all existing connect middlewares should work out-of-the-box with union.
 23
 24**(Union 0.3.x is compatible with connect >= 2.1.0, [Extensively Tested](https://github.com/pksunkara/connect-union))**
 25
 26In addition, the response object passed to middlewares listens for a "next" event, which is equivalent to calling `next()`. Flatiron middlewares are written in this manner, meaning they are not reverse-compatible with connect.
 27
 28### A simple case
 29
 30``` js
 31var fs = require('fs'),
 32    union = require('../lib'),
 33    director = require('director');
 34
 35var router = new director.http.Router();
 36
 37var server = union.createServer({
 38  before: [
 39    function (req, res) {
 40      var found = router.dispatch(req, res);
 41      if (!found) {
 42        res.emit('next');
 43      }
 44    }
 45  ]
 46});
 47
 48router.get(/foo/, function () {
 49  this.res.writeHead(200, { 'Content-Type': 'text/plain' })
 50  this.res.end('hello world\n');
 51});
 52
 53router.post(/foo/, { stream: true }, function () {
 54  var req = this.req,
 55      res = this.res,
 56      writeStream;
 57
 58  writeStream = fs.createWriteStream(Date.now() + '-foo.txt');
 59  req.pipe(writeStream);
 60
 61  writeStream.on('close', function () {
 62    res.writeHead(200, { 'Content-Type': 'text/plain' });
 63    res.end('wrote to a stream!');
 64  });
 65});
 66
 67server.listen(9090);
 68console.log('union with director running on 9090');
 69```
 70
 71To demonstrate the code, we use [director](https://github.com/flatiron/director). A light-weight, Client AND Server side URL-Router for Node.js and Single Page Apps!
 72
 73### A case with connect
 74
 75Code based on connect
 76
 77```js
 78var connect = require('connect')
 79  , http = require('http');
 80
 81var app = connect()
 82  .use(connect.favicon())
 83  .use(connect.logger('dev'))
 84  .use(connect.static('public'))
 85  .use(connect.directory('public'))
 86  .use(connect.cookieParser('my secret here'))
 87  .use(connect.session())
 88  .use(function (req, res) {
 89    res.end('Hello from Connect!\n');
 90  });
 91
 92http.createServer(app).listen(3000);
 93```
 94
 95Code based on union
 96
 97```js
 98var connect = require('connect')
 99  , union = require('union');
100
101var server = union.createServer({
102  buffer: false,
103  before: [
104    connect.favicon(),
105    connect.logger('dev'),
106    connect.static('public'),
107    connect.directory('public'),
108    connect.cookieParser('my secret here'),
109    connect.session(),
110    function (req, res) {
111      res.end('Hello from Connect!\n');
112    },
113  ]
114}).listen(3000);
115```
116
117### SPDY enabled server example
118
119# API
120
121## union Static Members
122
123### createServer(options)
124The `options` object is required. Options include:
125
126Specification
127
128```
129  function createServer(options)
130
131  @param options {Object}
132  An object literal that represents the configuration for the server.
133
134    @option before {Array}
135    The `before` value is an array of middlewares, which are used to route and serve incoming
136    requests. For instance, in the example, `favicon` is a middleware which handles requests
137    for `/favicon.ico`.
138
139    @option after {Array}
140    The `after` value is an array of functions that return stream filters,
141    which are applied after the request handlers in `options.before`.
142    Stream filters inherit from `union.ResponseStream`, which implements the
143    Node.js core streams api with a bunch of other goodies.
144
145    @option limit {Object}
146    (optional) A value, passed to internal instantiations of `union.BufferedStream`.
147
148    @option https {Object}
149    (optional) A value that specifies the certificate and key necessary to create an instance of
150    `https.Server`.
151
152    @option spdy {Object}
153    (optional) A value that specifies the certificate and key necessary to create an instance of
154    `spdy.Server`.
155
156    @option headers {Object}
157    (optional) An object representing a set of headers to set in every outgoing response
158```
159
160Example
161
162```js
163var server = union.createServer({
164  before: [
165    favicon('./favicon.png'),
166    function (req, res) {
167      var found = router.dispatch(req, res);
168      if (!found) {
169        res.emit('next');
170      }
171    }
172  ]
173});
174```
175
176An example of the `https` or `spdy` option.
177
178``` js
179{
180  cert: 'path/to/cert.pem',
181  key: 'path/to/key.pem',
182  ca: 'path/to/ca.pem'
183}
184```
185
186An example of the `headers` option.
187
188``` js
189{
190  'x-powered-by': 'your-sweet-application v10.9.8'
191}
192```
193
194## Error Handling
195Error handler is similiar to middlware but takes an extra argument for error at the beginning.
196
197```js
198var handle = function (err, req, res) {
199  res.statusCode = err.status;
200  res.end(req.headers);
201};
202
203var server = union.createServer({
204  onError: handle,
205  before: [
206    favicon('./favicon.png'),
207    function (req, res) {
208      var found = router.dispatch(req, res);
209      if (!found) {
210        res.emit('next');
211      }
212    }
213  ]
214});
215```
216
217## BufferedStream Constructor
218This constructor inherits from `Stream` and can buffer data up to `limit` bytes. It also implements `pause` and `resume` methods.
219
220Specification
221
222```
223  function BufferedStream(limit)
224
225  @param limit {Number}
226  the limit for which the stream can be buffered
227```
228
229Example
230
231```js
232var bs = union.BufferedStream(n);
233```
234
235## HttpStream Constructor
236This constructor inherits from `union.BufferedStream` and returns a stream with these extra properties:
237
238Specification
239
240```
241  function HttpStream()
242```
243
244Example
245
246```js
247var hs = union.HttpStream();
248```
249
250## HttpStream Instance Members
251
252### url
253The url from the request.
254
255Example
256
257```js
258httpStream.url = '';
259```
260
261### headers
262The HTTP headers associated with the stream.
263
264Example
265
266```js
267httpStream.headers = '';
268```
269
270### method
271The HTTP method ("GET", "POST", etc).
272
273Example
274
275```js
276httpStream.method = 'POST';
277```
278
279### query
280The querystring associated with the stream (if applicable).
281
282Example
283
284```js
285httpStream.query = '';
286```
287
288## ResponseStream Constructor
289This constructor inherits from `union.HttpStream`, and is additionally writeable. Union supplies this constructor as a basic response stream middleware from which to inherit.
290
291Specification
292
293```
294  function ResponseStream()
295```
296
297Example
298
299```js
300var rs = union.ResponseStream();
301```
302
303# Tests
304
305All tests are written with [vows][0] and should be run with [npm][1]:
306
307``` bash
308  $ npm test
309```
310
311# Licence
312
313(The MIT License)
314
315Copyright (c) 2010-2012 Charlie Robbins & the Contributors
316Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
317
318The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
319
320THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
321
322[0]: http://vowsjs.org
323[1]: http://npmjs.org