Skip to content
Newer
Older
100644 159 lines (104 sloc) 5.68 KB
3e1fc95 @mscdex Initial commit.
authored Jul 13, 2010
1 Grappler
2 ========
3
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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 Jul 14, 2010
6
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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 Jul 14, 2010
15
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
17
3e1fc95 @mscdex Initial commit.
authored Jul 14, 2010
18 Requirements
4113773 @mscdex Major overhaul after much testing.
authored Jul 19, 2010
19 ============
3e1fc95 @mscdex Initial commit.
authored Jul 14, 2010
20
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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 Jul 14, 2010
24
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
25 Example (broadcast echo)
26 ========================
3e1fc95 @mscdex Initial commit.
authored Jul 14, 2010
27
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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 Jul 19, 2010
30
31 API
32 ===
33
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
38
39 The `LOG` object is:
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
40
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
41 {
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
42 INFO: 1,
43 WARN: 2,
44 ERROR: 3
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
45 }
46
47 The `STATE` object is:
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
48
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
49 {
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
63
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
64 {
65 // A callback for receiving "debug" information. It is called with two arguments: message and message level.
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
67 logger: function(msg, msgLevel) {},
68
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
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…
authored Jul 26, 2010
88
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
100 `client` is an instance of `HttpClient`.
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
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 Mar 17, 2011
112 ### broadcast(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
113
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
121 ## HttpClient
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
122
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
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 Mar 17, 2011
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…
authored Jul 26, 2010
141
142 ### remoteAddress
143
144 The IP address of the client.
145
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
146 ### write(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
147
d31310d @mscdex Fixed README typos.
authored Jul 26, 2010
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…
authored Jul 26, 2010
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 Mar 17, 2011
153 ### broadcast(data[, encoding])
d0283c3 @mscdex Add API docs to README and make HttpClient.write behave more like net…
authored Jul 26, 2010
154
56af9ba @mscdex Lots of changes.
authored Mar 17, 2011
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…
authored Jul 26, 2010
156
157 ### disconnect()
158
159 Forcefully severs the client's connection to the server.
Something went wrong with that request. Please try again.