Skip to content
Newer
Older
100644 82 lines (51 sloc) 4.49 KB
ad4d044 @jed fix formatting
authored
1 ෴ browserver-node ෴
2 ======================
5fcbe4c @jed GitHub for Mac: Throw-away commit.
authored
3
962f6a2 @jed add travis-ci status [ci skip]
authored
4 [![Build Status](https://secure.travis-ci.org/jed/browserver-node.png?branch=master)](http://travis-ci.org/jed/browserver-node)
5
ab0e00f @jed flesh out README
authored
6 This is a [browserver](http://browserver.org) proxy for [node.js](http://nodejs.org).
7
6a2db93 @jed bullet points are clearer
authored
8 Use browserver-node to create servers that act as a two-way proxies between an HTTP server and a WebSocket server, by
9
10 - forwarding incoming HTTP requests on to WebSocket connected clients, and back.
11 - forwarding incoming WebSocket messages to other HTTP servers, and back.
5bd0812 @jed add browserver client reference
authored
12
13 This library, along with [browserver-client](https://github.com/jed/browserver-client), is all the code you need to set up your own browserver.
ab0e00f @jed flesh out README
authored
14
15 Example
16 -------
17
18 ```javascript
19 // http, websocket, and browservers
20 var http = require("http")
21 var engine = require("engine.io")
ab2c259 @jed rename for npm
authored
22 var brow = require("browserver")
ab0e00f @jed flesh out README
authored
23
24 function handler(req, res) {
25 // your usual HTTP server logic
26 }
27
28 // instantiate http and websocket servers
29 var httpServer = http.createServer(handler)
30 var wsServer = engine.attach(httpServer)
31
32 // pass each to a new browserver...
a6c4a65 @jed update README
authored
33 var browServer = new brow.Server
34 browServer.listen(wsServer)
35 browServer.listen(httpServer, {hostname: "*.mydomain.org"})
ab0e00f @jed flesh out README
authored
36
37 // ... and start listening!
38 httpServer.listen(80, function() {
39 // wait for incoming/outgoing browser connections...
40 })
41 ```
42
43 Installation
44 ------------
45
46 browserver is available through npm.
47
ab2c259 @jed rename for npm
authored
48 `npm install browserver`
ab0e00f @jed flesh out README
authored
49
50 API
51 ---
52
a6c4a65 @jed update README
authored
53 ### browserver = new brow.Server
54
55 This creates a new browserver proxy, which works by listening to both a WebSocket-alike server and an HTTP server.
56
57 ### browserver.listen(webSocketServer, [options])
58
59 `webSocketServer` is required, and must be an instance of a WebSocket server (such as [ws](https://github.com/einaros/ws)) or compatible shim (such as [socket.io](https://github.com/learnboost/socket.io), [engine.io](https://github.com/learnboost/engine.io)) that emits socket instances through `connection` events.
60
61 `options` is an optional object that can have any of the following properties:
ab0e00f @jed flesh out README
authored
62
a6c4a65 @jed update README
authored
63 - `authorize`: An optional request method used for authorization of client requests FROM the browser. This method is invoked with the request as the `this` context and a callback as the first argument (`authorize.call(request, callback)`). If this method calls back without an error, the request will be passed on. If this method calls back with an error, a 403 is returned with the error message as the body of the response. By default, browserver will forward-proxy any request from a browser to the greater Internet, so use this method to limit the resources to which browserver clients have access.
ab0e00f @jed flesh out README
authored
64
a6c4a65 @jed update README
authored
65 ### browserver.listen(httpServer, [options])
ab0e00f @jed flesh out README
authored
66
a6c4a65 @jed update README
authored
67 `httpServer` is required, and can either be an instance of `http.Server`, or a primitive (such as `3572` or `undefined`) to be used as the port on which a new server instance will listen.
ab0e00f @jed flesh out README
authored
68
a6c4a65 @jed update README
authored
69 `options` is an optional object that can have any of the following properties:
ab0e00f @jed flesh out README
authored
70
a6c4a65 @jed update README
authored
71 - `hostname` Optional. If specified, must be a string containing one and only one asterisk (`*`), which is replaced with a socket id when a WebSocket connection is established. Note that this means you will need a wildcard CNAME or A record in your DNS settings that resolves to the appropriate domain or IP address. If omitted, CloudFoundry's [*.vcap.me](https://github.com/cloudfoundry/vcap/) domain is used, which resolves all domains/subdomains to `127.0.0.1`.
ab0e00f @jed flesh out README
authored
72
a6c4a65 @jed update README
authored
73 - `authorize`: An optional request method used for authorization of server requests TO the browser. This method is invoked with the request as the `this` context and a callback as the first argument (`authorize.call(request, callback)`). If this method calls back without an error, the request will be passed on to the browserver client. If this method calls back with an error, a 403 is returned with the error message as the body of the response. By default, browserver will reverse-proxy any request from the greater Internet to a browserver clients, so use this method to authenticate or limit the requests actually sent to which browserver clients.
ab0e00f @jed flesh out README
authored
74
ebba769 @jed emit servers instead of hostnames
authored
75 ### browserver.on("connection", function(server){ ... })
ab0e00f @jed flesh out README
authored
76
ebba769 @jed emit servers instead of hostnames
authored
77 The browserver server proxy emits a `connection` event whenever a browserver client connects. The listener is called with one argument, the browserver server. The server's unique hostname is available at the `hostname` propery.
ab0e00f @jed flesh out README
authored
78
ebba769 @jed emit servers instead of hostnames
authored
79 ### browserver.on("disconnection", function(server){ ... })
ab0e00f @jed flesh out README
authored
80
ebba769 @jed emit servers instead of hostnames
authored
81 The browserver server proxy emits a `disconnection` event whenever a browserver client disconnects. The listener is called with one argument, the disconnected browserver server.
Something went wrong with that request. Please try again.