Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 258 lines (153 sloc) 7.616 kb
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
1 Socket.IO Server: Sockets for the rest of us
2 ============================================
3
5620539 Jed Schmidt fixed bad pluralization.
jed authored
4 The `Socket.IO` server provides seamless support for a variety of transports intended for realtime communication.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
5
24b2714 Guillermo Rauch [README] Transports clarification
rauchg authored
6 - WebSocket
7 - WebSocket over Flash (+ XML security policy support)
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
8 - XHR Polling
9 - XHR Multipart Streaming
10 - Forever Iframe
24b2714 Guillermo Rauch [README] Transports clarification
rauchg authored
11 - JSONP Polling (for cross domain)
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
12
58ac323 Guillermo Rauch Extended `how to use` section
rauchg authored
13 ## Requirements
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
14
50f9810 Guillermo Rauch Node required version
rauchg authored
15 - Node v0.1.103+
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
16 - The [Socket.IO client](http://github.com/LearnBoost/Socket.IO), to connect from the browser
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
17
58ac323 Guillermo Rauch Extended `how to use` section
rauchg authored
18 ## How to use
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
19
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
20 To run the demo, execute the following:
7b7270d Guillermo Rauch Better `how to use`
rauchg authored
21
4f1553b Guillermo Rauch Updated README to reflect no-more-submodules
rauchg authored
22 git clone git://github.com/LearnBoost/Socket.IO-node.git socket.io
23 cd socket.io/example/
7b7270d Guillermo Rauch Better `how to use`
rauchg authored
24 sudo node server.js
25
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
26 and point your browser to `http://localhost:8080`. In addition to `8080`, if the transport `flashsocket` is enabled, a server will be initialized to listen for requests on port `843`.
7b7270d Guillermo Rauch Better `how to use`
rauchg authored
27
28 ### Implementing it on your project
29
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
30 `Socket.IO` is designed not to take over an entire port or Node `http.Server` instance. This means that if you choose to have your HTTP server listen on port `80`, `socket.io` can intercept requests directed to it, and normal requests will still be served.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
31
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
32 By default, the server will intercept requests that contain `socket.io` in the path / resource part of the URI. You can change this as shown in the available options below.
33
34 On the server:
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
35
36 var http = require('http'),
4acf98d Guillermo Rauch Fixed require path in README (thanks Tobsn)
rauchg authored
37 io = require('./path/to/socket.io'),
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
38
39 server = http.createServer(function(req, res){
40 // your normal server code
41 res.writeHeader(200, {'Content-Type': 'text/html'});
42 res.writeBody('<h1>Hello world</h1>');
43 res.finish();
44 });
2c0aa50 Guillermo Rauch Added missing .listen() call to example. Fixes #80. Thanks @machee
rauchg authored
45
46 server.listen(80);
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
47
48 // socket.io, I choose you
58ac323 Guillermo Rauch Extended `how to use` section
rauchg authored
49 var socket = io.listen(server);
50
51 socket.on('connection', function(client){
52 // new client is here!
53 client.on('message', function(){ … })
54 client.on('disconnect', function(){ … })
55 });
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
56
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
57 On the client:
61f4e27 Guillermo Rauch Socket.IO-node now serves the client out of the box for easier implement...
rauchg authored
58
59 <script src="/socket.io/socket.io.js"></script>
60 <script>
61 var socket = new io.Socket();
62 socket.on('connect', function(){ … })
63 socket.on('message', function(){ … })
64 socket.on('disconnect', function(){ … })
65 </script>
66
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
67 The [client-side](http://github.com/learnboost/socket.io) files are served automatically by `Socket.IO-node`.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
68
69 ## Documentation
70
71 ### Listener
72
73 io.listen(<http.Server>, [options])
74
75 Returns: a `Listener` instance
76
77 Public Properties:
78
79 - *server*
80
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
81 An instance of _process.http.Server_.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
82
83 - *options*
84
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
85 The passed-in options, combined with the defaults.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
86
87 - *clients*
88
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
89 An object of clients, indexed by session ID.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
90
91 Methods:
92
93 - *addListener(event, λ)*
94
95 Adds a listener for the specified event. Optionally, you can pass it as an option to `io.listen`, prefixed by `on`. For example: `onClientConnect: function(){}`
96
97 - *removeListener(event, λ)*
98
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
99 Removes a listener from the listener array for the specified event.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
100
101 - *broadcast(message, [except])*
102
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
103 Broadcasts a message to all clients. Optionally, you can pass a single session ID or array of session IDs to avoid broadcasting to, as the second argument.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
104
105 Options:
106
107 - *resource*
108
109 socket.io
110
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
111 The resource is what allows the `socket.io` server to identify incoming connections from `socket.io` clients. Make sure they're in sync.
c168c89 Arnout Kazemier Added the flash policy server, it's enabled by default but can be turned...
3rd-Eden authored
112
113 - *flashPolicyServer*
114
115 true
116
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
117 Create a Flash Policy file server on port `843` (this is restricted port and you will need to have root permission). If you disable the FlashPolicy file server, Socket.IO will automatically fall back to serving the policy file inline.
c168c89 Arnout Kazemier Added the flash policy server, it's enabled by default but can be turned...
3rd-Eden authored
118
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
119
120 - *transports*
121
122 ['websocket', 'server-events', 'flashsocket', 'htmlfile', 'xhr-multipart', 'xhr-polling']
123
124 A list of the accepted transports.
125
0459c95 Guillermo Rauch Added support for Node 0.1.94
rauchg authored
126 - *transportOptions*
127
128 An object of options to pass to each transport. For example `{ websocket: { closeTimeout: 8000 }}`
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
129
130 - *log*
131
132 ƒ(){ sys.log }
133
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
134 The logging function. Defaults to outputting to `stdout` through `sys.log`
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
135
136 Events:
137
138 - *clientConnect(client)*
139
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
140 Fired when a client is connected. Receives the Client instance as parameter.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
141
142 - *clientMessage(message, client)*
143
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
144 Fired when a message from a client is received. Receives the message and Client instance as parameters.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
145
146 - *clientDisconnect(client)*
147
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
148 Fired when a client is disconnected. Receives the Client instance as a parameter.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
149
150 Important note: `this` in the event listener refers to the `Listener` instance.
151
152 ### Client
153
154 Client(listener, req, res)
155
156 Public Properties:
157
158 - *listener*
159
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
160 The `Listener` instance to which this client belongs.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
161
162 - *connected*
163
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
164 Whether the client is connected.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
165
166 - *connections*
167
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
168 Number of times the client has connected.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
169
170 Methods:
171
172 - *send(message)*
173
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
174 Sends a message to the client.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
175
176 - *broadcast(message)*
177
967238a Jed Schmidt cleaned up grammar, missing punctuation, etc.
jed authored
178 Sends a message to all other clients. Equivalent to Listener::broadcast(message, client.sessionId).
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
179
180 ## Protocol
181
ca751d7 Guillermo Rauch New protocol / data encoding specification
rauchg authored
182 In order to make polling transports simulate the behavior of a full-duplex WebSocket, a session protocol and a message framing mechanism are required.
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
183
ca751d7 Guillermo Rauch New protocol / data encoding specification
rauchg authored
184 The session protocol consists of the generation of a session id that is passed to the client when the communication starts. Subsequent connections to the server within that session send that session id in the URI along with the transport type.
185
186 ### Message encoding
187
188 (message type)":"(content length)":"(data)","
189
190 (message type) is a single digit that represents one of the known message types (described below).
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
191
ca751d7 Guillermo Rauch New protocol / data encoding specification
rauchg authored
192 (content length) is the number of characters of (data)
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
193
ca751d7 Guillermo Rauch New protocol / data encoding specification
rauchg authored
194 (data) is the message
195
196 0 = force disconnection
197 No data or annotations are sent with this message (it's thus always sent as "0:0:,")
198
199 1 = message
200 Data format:
201 (annotations)":"(message)
202
203 Annotations are meta-information associated with a message to make the Socket.IO protocol extensible. They're conceptually similar to HTTP headers. They take this format:
204
205 [key[:value][\n key[:value][\n ...]]]
206
207 For example, when you `.send('Hello world')` within the realm `'chat'`, Socket.IO really is sending:
208
209 1:18:r:chat:Hello world,
210
211 Two annotations are used by the Socket.IO client: `r` (for `realm`) and `j` (for automatic `json` encoding / decoding of the message).
212
213 2 = heartbeat
214 Data format:
215 (heartbeat numeric index)
216
217 Example:
218 2:1:0,
219 2:1:1,
220
221 3 = session id handshake
222 Data format:
223 (session id)
224
225 Example:
226 3:3:253,
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
227
228 ## Credits
229
fbb9a46 Guillermo Rauch Credits to 3rd-Eden for his many patches
rauchg authored
230 - Guillermo Rauch &lt;guillermo@learnboost.com&gt; ([Guille](http://github.com/guille))
231
232 - Arnout Kazemier ([3rd-Eden](http://github.com/3rd-Eden))
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
233
234 ## License
235
236 (The MIT License)
237
6ce8c52 Guillermo Rauch Updated README
rauchg authored
238 Copyright (c) 2010 LearnBoost &lt;dev@learnboost.com&gt;
c8edad8 Guillermo Rauch Initial commit (some transports untested!)
rauchg authored
239
240 Permission is hereby granted, free of charge, to any person obtaining
241 a copy of this software and associated documentation files (the
242 'Software'), to deal in the Software without restriction, including
243 without limitation the rights to use, copy, modify, merge, publish,
244 distribute, sublicense, and/or sell copies of the Software, and to
245 permit persons to whom the Software is furnished to do so, subject to
246 the following conditions:
247
248 The above copyright notice and this permission notice shall be
249 included in all copies or substantial portions of the Software.
250
251 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
252 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
253 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
254 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
255 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
256 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
ca751d7 Guillermo Rauch New protocol / data encoding specification
rauchg authored
257 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.