Skip to content
This repository
Newer
Older
100644 322 lines (234 sloc) 7.886 kb
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
1
6621f07c »
2012-01-13 [docs] docs update
2 <img src="https://github.com/flatiron/union/raw/master/union.png" />
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
3
6621f07c »
2012-01-13 [docs] docs update
4 # Synopsis
5 A hybrid streaming middleware kernel backwards compatible with connect.
6
7 # Motivation
8 The 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
15 There 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
22 Union'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
18846027 »
2012-04-06 [docs] Update connect compatibility
24 (Union 0.3.0 is compatible with connect >= 2.1.0, [Extensively Tested](https://github.com/pksunkara/connect-union))
737b0527 »
2012-03-27 [doc] Added docs for connect compatibility, FIxes #19
25
6621f07c »
2012-01-13 [docs] docs update
26 In 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
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
29
30 ``` js
31 var fs = require('fs'),
32 union = require('../lib'),
fe0e5bdf »
2011-11-17 [dist minor] Update references to `sugarskull` with `director`
33 director = require('director'),
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
34 favicon = require('./middleware/favicon');
35
fe0e5bdf »
2011-11-17 [dist minor] Update references to `sugarskull` with `director`
36 var router = new director.http.Router();
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
37
38 var server = union.createServer({
93ad24fc »
2011-11-08 [doc] First pass at API docs
39 before: [
40 favicon('./favicon.png'),
41 function (req, res) {
42 var found = router.dispatch(req, res);
43 if (!found) {
44 res.emit('next');
45 }
46 }
47 ]
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
48 });
49
50 router.get(/foo/, function () {
51 this.res.writeHead(200, { 'Content-Type': 'text/plain' })
52 this.res.end('hello world\n');
53 });
54
55 router.post(/foo/, { stream: true }, function () {
56 var req = this.req,
57 res = this.res,
58 writeStream;
59
93ad24fc »
2011-11-08 [doc] First pass at API docs
60 writeStream = fs.createWriteStream(Date.now() + '-foo.txt');
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
61 req.pipe(writeStream);
62
63 writeStream.on('close', function () {
64 res.writeHead(200, { 'Content-Type': 'text/plain' });
65 res.end('wrote to a stream!');
66 });
67 });
68
1b5420db »
2011-11-28 [fix] Update 8080 to 9090. Fixes #6
69 server.listen(9090);
70 console.log('union with director running on 9090');
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
71 ```
72
483172cf »
2012-01-13 [docs] docs update
73 To 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!
74
737b0527 »
2012-03-27 [doc] Added docs for connect compatibility, FIxes #19
75 ### A case with connect
76
77 Code based on connect
78
79 ```js
80 var connect = require('connect')
81 , http = require('http');
82
83 var app = connect()
84 .use(connect.favicon())
85 .use(connect.logger('dev'))
86 .use(connect.static('public'))
87 .use(connect.directory('public'))
88 .use(connect.cookieParser('my secret here'))
89 .use(connect.session())
90 .use(function(req, res){
91 res.end('Hello from Connect!\n');
92 });
93
94 http.createServer(app).listen(3000);
95 ```
96
97 Code based on union
98
99 ```js
100 var connect = require('connect')
101 , union = require('union');
102
103 var server = union.createServer({
104 before: [
105 connect.favicon(),
106 connect.logger('dev'),
107 connect.static('public'),
108 connect.directory('public'),
109 connect.cookieParser('my secret here'),
110 connect.session(),
111 function(req, res) {
112 res.end('Hello from Connect!\n');
113 },
114 ]
115 }).listen(3000);
116 ```
117
6621f07c »
2012-01-13 [docs] docs update
118 # API
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
119
6464f700 »
2012-01-13 [docs] docs update
120 ## union Static Members
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
121
6621f07c »
2012-01-13 [docs] docs update
122 ### createServer(options)
123 The `options` object is required. Options include:
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
124
6464f700 »
2012-01-13 [docs] docs update
125 Specification
2961d393 »
2012-01-13 [docs] docs update
126
6621f07c »
2012-01-13 [docs] docs update
127 ```
128 function createServer(options)
93ad24fc »
2011-11-08 [doc] First pass at API docs
129
6464f700 »
2012-01-13 [docs] docs update
130 @param options {Object}
131 An object literal that represents the configuration for the server.
132
133 @option before {Array}
5b1f47f0 »
2012-01-13 [docs] docs update
134 The `before` value is an array of middlewares, which are used to route and serve incoming
135 requests. For instance, in the example, `favicon` is a middleware which handles requests
136 for `/favicon.ico`.
93ad24fc »
2011-11-08 [doc] First pass at API docs
137
6464f700 »
2012-01-13 [docs] docs update
138 @option after {Array}
7447d624 »
2012-03-20 [dist api] interface change on after filters
139 The `after` value is an array of functions that return stream filters,
140 which are applied after the request handlers in `options.before`.
141 Stream filters inherit from `union.ResponseStream`, which implements the
5b1f47f0 »
2012-01-13 [docs] docs update
142 Node.js core streams api with a bunch of other goodies.
93ad24fc »
2011-11-08 [doc] First pass at API docs
143
6464f700 »
2012-01-13 [docs] docs update
144 @option limit {Object}
145 (optional) A value, passed to internal instantiations of `union.BufferedStream`.
93ad24fc »
2011-11-08 [doc] First pass at API docs
146
6464f700 »
2012-01-13 [docs] docs update
147 @option https {Object}
5b1f47f0 »
2012-01-13 [docs] docs update
148 (optional) A value that specifies the certificate and key necessary to create an instance of
149 `https.Server`.
93ad24fc »
2011-11-08 [doc] First pass at API docs
150
6464f700 »
2012-01-13 [docs] docs update
151 @option headers {Object}
152 (optional) An object representing a set of headers to set in every outgoing response
6621f07c »
2012-01-13 [docs] docs update
153 ```
fbdbe5d1 »
2011-11-08 Second pass at README
154
6464f700 »
2012-01-13 [docs] docs update
155 Example
2961d393 »
2012-01-13 [docs] docs update
156
6621f07c »
2012-01-13 [docs] docs update
157 ```js
158 var server = union.createServer({
159 before: [
160 favicon('./favicon.png'),
161 function (req, res) {
162 var found = router.dispatch(req, res);
163 if (!found) {
164 res.emit('next');
165 }
166 }
167 ]
168 });
169 ```
93ad24fc »
2011-11-08 [doc] First pass at API docs
170
6621f07c »
2012-01-13 [docs] docs update
171 An example of the `https` option.
93ad24fc »
2011-11-08 [doc] First pass at API docs
172
6621f07c »
2012-01-13 [docs] docs update
173 ``` js
174 {
175 https: {
176 cert: 'path/to/cert.pem',
177 key: 'path/to/key.pem',
178 ca: 'path/to/ca.pem'
179 }
180 }
181 ```
fbdbe5d1 »
2011-11-08 Second pass at README
182
6621f07c »
2012-01-13 [docs] docs update
183 An example of the `headers` option.
93ad24fc »
2011-11-08 [doc] First pass at API docs
184
6621f07c »
2012-01-13 [docs] docs update
185 ``` js
186 {
187 'x-powered-by': 'your-sweet-application v10.9.8'
188 }
189 ```
93ad24fc »
2011-11-08 [doc] First pass at API docs
190
81fbc953 »
2012-03-26 [api] Implement next(err) and modify errorHandling
191 ## Error Handling
192 Error handler is similiar to middlware but takes an extra argument for error at the beginning.
193
194 ```js
195 var handle = function (err, req, res) {
196 res.statusCode = err.status;
197 res.end(req.headers);
198 };
199
200 var server = union.createServer({
201 onError: handle,
202 before: [
203 favicon('./favicon.png'),
204 function (req, res) {
205 var found = router.dispatch(req, res);
206 if (!found) {
207 res.emit('next');
208 }
209 }
210 ]
211 });
212 ```
213
6621f07c »
2012-01-13 [docs] docs update
214 ## BufferedStream Constructor
215 This constructor inherits from `Stream` and can buffer data up to `limit` bytes. It also implements `pause` and `resume` methods.
fbdbe5d1 »
2011-11-08 Second pass at README
216
6464f700 »
2012-01-13 [docs] docs update
217 Specification
2961d393 »
2012-01-13 [docs] docs update
218
6621f07c »
2012-01-13 [docs] docs update
219 ```
220 function BufferedStream(limit)
6464f700 »
2012-01-13 [docs] docs update
221
222 @param limit {Number}
223 the limit for which the stream can be buffered
6621f07c »
2012-01-13 [docs] docs update
224 ```
832a5e14 »
2011-11-18 [api doc] Enable creation of `https` servers in union. Fixes #5
225
6464f700 »
2012-01-13 [docs] docs update
226 Example
2961d393 »
2012-01-13 [docs] docs update
227
6621f07c »
2012-01-13 [docs] docs update
228 ```js
229 var bs = union.BufferedStream(n);
230 ```
832a5e14 »
2011-11-18 [api doc] Enable creation of `https` servers in union. Fixes #5
231
6621f07c »
2012-01-13 [docs] docs update
232 ## HttpStream Constructor
233 This constructor inherits from `union.BufferedStream` and returns a stream with these extra properties:
234
6464f700 »
2012-01-13 [docs] docs update
235 Specification
2961d393 »
2012-01-13 [docs] docs update
236
6464f700 »
2012-01-13 [docs] docs update
237 ```
238 function HttpStream()
239 ```
240
241 Example
2961d393 »
2012-01-13 [docs] docs update
242
6621f07c »
2012-01-13 [docs] docs update
243 ```js
244 var hs = union.HttpStream();
832a5e14 »
2011-11-18 [api doc] Enable creation of `https` servers in union. Fixes #5
245 ```
246
6621f07c »
2012-01-13 [docs] docs update
247 ## HttpStream Instance Memebers
3284b100 »
2011-12-09 [api test] Add options for exposing default response headers
248
6621f07c »
2012-01-13 [docs] docs update
249 ### url
250 The url from the request.
3284b100 »
2011-12-09 [api test] Add options for exposing default response headers
251
6464f700 »
2012-01-13 [docs] docs update
252 Example
2961d393 »
2012-01-13 [docs] docs update
253
6621f07c »
2012-01-13 [docs] docs update
254 ```js
255 httpStream.url = '';
3284b100 »
2011-12-09 [api test] Add options for exposing default response headers
256 ```
257
6621f07c »
2012-01-13 [docs] docs update
258 ### headers
259 The HTTP headers associated with the stream.
93ad24fc »
2011-11-08 [doc] First pass at API docs
260
6464f700 »
2012-01-13 [docs] docs update
261 Example
2961d393 »
2012-01-13 [docs] docs update
262
6621f07c »
2012-01-13 [docs] docs update
263 ```js
264 httpStream.headers = '';
265 ```
93ad24fc »
2011-11-08 [doc] First pass at API docs
266
6621f07c »
2012-01-13 [docs] docs update
267 ### method
268 The HTTP method ("GET", "POST", etc).
fbdbe5d1 »
2011-11-08 Second pass at README
269
6464f700 »
2012-01-13 [docs] docs update
270 Example
2961d393 »
2012-01-13 [docs] docs update
271
6621f07c »
2012-01-13 [docs] docs update
272 ```js
273 httpStream.method = 'POST';
274 ```
fbdbe5d1 »
2011-11-08 Second pass at README
275
6621f07c »
2012-01-13 [docs] docs update
276 ### query
277 The querystring associated with the stream (if applicable).
93ad24fc »
2011-11-08 [doc] First pass at API docs
278
6464f700 »
2012-01-13 [docs] docs update
279 Example
2961d393 »
2012-01-13 [docs] docs update
280
6621f07c »
2012-01-13 [docs] docs update
281 ```js
282 httpStream.query = '';
283 ```
93ad24fc »
2011-11-08 [doc] First pass at API docs
284
6621f07c »
2012-01-13 [docs] docs update
285 ## ResponseStream Constructor
286 This constructor inherits from `union.HttpStream`, and is additionally writeable. Union supplies this constructor as a basic response stream middleware from which to inherit.
fbdbe5d1 »
2011-11-08 Second pass at README
287
6464f700 »
2012-01-13 [docs] docs update
288 Specification
2961d393 »
2012-01-13 [docs] docs update
289
6464f700 »
2012-01-13 [docs] docs update
290 ```
291 function ResponseStream()
292 ```
293
294 Example
2961d393 »
2012-01-13 [docs] docs update
295
6621f07c »
2012-01-13 [docs] docs update
296 ```js
297 var rs = union.ResponseStream();
298 ```
93ad24fc »
2011-11-08 [doc] First pass at API docs
299
6621f07c »
2012-01-13 [docs] docs update
300 # Tests
93ad24fc »
2011-11-08 [doc] First pass at API docs
301
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
302 All tests are written with [vows][0] and should be run with [npm][1]:
303
304 ``` bash
305 $ npm test
306 ```
307
6621f07c »
2012-01-13 [docs] docs update
308 # Licence
309
310 (The MIT License)
311
312 Copyright (c) 2010 Nodejitsu Inc. <http://www.twitter.com/nodejitsu>
313
314 Permission 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:
315
316 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
317
318 THE 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.
0083f8b0 »
2011-11-09 [doc dist] Update README.md LICENSE and package.json. `flatiron-http`…
319
320 [0]: http://vowsjs.org
93ad24fc »
2011-11-08 [doc] First pass at API docs
321 [1]: http://npmjs.org
Something went wrong with that request. Please try again.