Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 159 lines (104 sloc) 5.812 kb
3e1fc95 @mscdex Initial commit.
authored
1 Grappler
2 ========
3
56af9ba @mscdex Lots of changes.
authored
4 Grappler is a minimalistic server for "comet" connections that exposes a single, consistent API across all transports.
5 Grappler currently supports the following transports (each with a list of currently known supported browsers):
3e1fc95 @mscdex Initial commit.
authored
6
56af9ba @mscdex Lots of changes.
authored
7 * WebSockets (with Flash policy support -- watches for policy requests on the same port as the grappler server)
8 * Firefox 4, Chrome 4+, Safari 5, or any browser that supports at least Flash 9.x
9 * XHR Multipart Streaming
10 * Firefox 3+, Safari 5 (maybe 4.0 also?), Chrome 1+
11 * Server-Sent Events
12 * Chrome 6+, Safari 5, Opera 9.x-10.x (DOM only)
13 * XHR Long Polling
14 * Any browser that supports XMLHttpRequest*
3e1fc95 @mscdex Initial commit.
authored
15
56af9ba @mscdex Lots of changes.
authored
16 \* - Some browsers' XMLHttpRequest implementations contain unexpected quirks (e.g. the built-in web browser for Android 1.6)
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
17
3e1fc95 @mscdex Initial commit.
authored
18 Requirements
4113773 @mscdex Major overhaul after much testing.
authored
19 ============
3e1fc95 @mscdex Initial commit.
authored
20
56af9ba @mscdex Lots of changes.
authored
21 * Node.JS (tested with v0.4.2 -- may work with older versions)
22 * A client supporting one of the aforementioned transports.
23 * For HTTP (non-WebSocket) clients, cookies must be enabled for clients ONLY if they are going to send messages (i.e. via POST) to the server.
3e1fc95 @mscdex Initial commit.
authored
24
56af9ba @mscdex Lots of changes.
authored
25 Example (broadcast echo)
26 ========================
3e1fc95 @mscdex Initial commit.
authored
27
56af9ba @mscdex Lots of changes.
authored
28 1. Run examples/echo/server.js.
29 2. Visit the demo server's page in one or more browsers: http://127.0.0.1:8080/demo.htm
4113773 @mscdex Major overhaul after much testing.
authored
30
31 API
32 ===
33
56af9ba @mscdex Lots of changes.
authored
34 Grappler exports one main object: `Server`.
35
36 lib/common.js exports `LOG` and `STATE` objects, which contain constants used for
37 when logging messages and checking the state of a client respectively.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
38
39 The `LOG` object is:
56af9ba @mscdex Lots of changes.
authored
40
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
41 {
56af9ba @mscdex Lots of changes.
authored
42 INFO: 1,
43 WARN: 2,
44 ERROR: 3
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
45 }
46
47 The `STATE` object is:
56af9ba @mscdex Lots of changes.
authored
48
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
49 {
56af9ba @mscdex Lots of changes.
authored
50 ACCEPTED: 1, // internal use only
51 TEMP: 2, // internal use only
52 PROTO_HTTP: 4, // client is HTTP-based
53 PROTO_WEBSOCKET: 8 // client is WebSocket-based
54 }
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
55
56 ## Server
57
58 ### Constructor: new Server([options], [fnHandleNormalHTTP], [fnAcceptClient])
59
60 Creates a new instance of a grappler server.
61
62 `options` is an object with the following default values:
56af9ba @mscdex Lots of changes.
authored
63
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
64 {
65 // A callback for receiving "debug" information. It is called with two arguments: message and message level.
56af9ba @mscdex Lots of changes.
authored
66 // Message level is one of the values in the `LOG` object.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
67 logger: function(msg, msgLevel) {},
68
56af9ba @mscdex Lots of changes.
authored
69 // A string or array of strings which denote who is allowed to connect to this grappler Server instance.
70 // The format of the string is: "hostname:port", "hostname", or an asterisk substituted for either the hostname
71 // or port, or both, to act as a wildcard.
72 origins: "*:*",
73
74 // An integer value in milliseconds representing the interval in which a ping is sent to an HTTP client for those
75 // transports that need to do so.
76 pingInterval: 3000,
77
78 // A storage provider used to store client objects. The default is to use 'object', a simple hash. Other available
79 // storage providers can be found in lib/storage. The value here is the name without the 'storage' prefix and file extension.
80 storage: 'object'
81 }
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
82
83 `fnHandleNormalHTTP` is a callback which is able to override grappler for an incoming HTTP connection.
84 If no headers are sent, then grappler takes control of the connection. The arguments provided to this callback are the
56af9ba @mscdex Lots of changes.
authored
85 same for `http.Server`'s `request` event, that is: http.ServerRequest and http.ServerResponse objects. It should be
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
86 noted that if you want grappler to automatically handle all incoming HTTP connections but want to specify a callback
56af9ba @mscdex Lots of changes.
authored
87 for `fnAcceptClient`, you need to specify a `false` value for `fnHandleNormalHTTP`.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
88
56af9ba @mscdex Lots of changes.
authored
89 `fnAcceptClient` is a callback that is executed the moment a client connects. The main purpose of this callback is to
90 have the chance to immediately deny a client further access to the grappler server. For example, your application may
91 maintain a blacklist or may automatically blacklist/throttle back a certain IP after x connections in a certain amount of time.
92 If this callback returns `false`, the connection will automatically be dropped, otherwise the connection will be permitted.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
93 The callback receives one argument, which is the `net.Stream` object representing the connection.
94
95 ### Event: connection
96
97 `function(client) { }`
98
99 This event is emitted every time a new client has successfully connected to the system.
56af9ba @mscdex Lots of changes.
authored
100 `client` is an instance of `HttpClient`.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
101
102 ### Event: error
103
104 `function(err) { }`
105
106 Emitted when an unexpected error occurs.
107
108 ### listen(port, [host])
109
110 Starts the server listening on the specified `port` and `host`. If `host` is omitted, the server will listen on any IP address.
111
56af9ba @mscdex Lots of changes.
authored
112 ### broadcast(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
113
56af9ba @mscdex Lots of changes.
authored
114 Sends `data` to every connected client using an optional `encoding`.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
115
116 ### shutdown()
117
118 Shuts down the server by no longer listening for incoming connections and severing any existing client connections.
119
120
56af9ba @mscdex Lots of changes.
authored
121 ## HttpClient
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
122
56af9ba @mscdex Lots of changes.
authored
123 There is one other important object that is used in grappler, and that is the `HttpClient` object.
124 `HttpClient` represents a user connected to the server and can be used to interact with that user.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
125
126 ### Event: drain
127
128 `function() { }`
129
130 Emitted when the client's write buffer becomes empty.
131
132 ### Event: close
133
134 `function() { }`
135
136 Emitted when the client has disconnected.
137
138 ### state
139
56af9ba @mscdex Lots of changes.
authored
140 A bit field containing the current state of the client. See the previously mentioned `STATE` object for valid bits.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
141
142 ### remoteAddress
143
144 The IP address of the client.
145
56af9ba @mscdex Lots of changes.
authored
146 ### write(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
147
d31310d @mscdex Fixed README typos.
authored
148 Sends `data` using an optional `encoding` to the client.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
149 This function returns `true` if the entire data was flushed successfully to the kernel
150 buffer. Otherwise, it will return `false` if all or part of the data was queued in user memory.
151 `drain` will be emitted when the kernel buffer is free again.
152
56af9ba @mscdex Lots of changes.
authored
153 ### broadcast(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
154
56af9ba @mscdex Lots of changes.
authored
155 Sends `data` to all other connected clients using an optional `encoding`.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net.St...
authored
156
157 ### disconnect()
158
159 Forcefully severs the client's connection to the server.
Something went wrong with that request. Please try again.