1 | Socket.IO Server: Sockets for the rest of us
|
2 | ============================================
|
3 |
|
4 | The `Socket.IO` server provides seamless support for a variety of transports intended for realtime communication.
|
5 |
|
6 | - WebSocket
|
7 | - WebSocket over Flash (+ XML security policy support)
|
8 | - XHR Polling
|
9 | - XHR Multipart Streaming
|
10 | - Forever Iframe
|
11 | - JSONP Polling (for cross domain)
|
12 |
|
13 | ## Requirements
|
14 |
|
15 | - Node v0.1.103+ with `crypto` module support (make sure you have OpenSSL
|
16 | headers when installing Node to get it)
|
17 | - The [Socket.IO client](http://github.com/LearnBoost/Socket.IO), to connect from the browser
|
18 |
|
19 | ## How to use
|
20 |
|
21 | To run the demo, execute the following:
|
22 |
|
23 | git clone git://github.com/LearnBoost/Socket.IO-node.git socket.io
|
24 | cd socket.io/example/
|
25 | sudo node server.js
|
26 |
|
27 | 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`.
|
28 |
|
29 | ### Implementing it on your project
|
30 |
|
31 | `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.
|
32 |
|
33 | 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.
|
34 |
|
35 | On the server:
|
36 |
|
37 | var http = require('http'),
|
38 | io = require('./path/to/socket.io'),
|
39 |
|
40 | server = http.createServer(function(req, res){
|
41 | // your normal server code
|
42 | res.writeHead(200, {'Content-Type': 'text/html'});
|
43 | res.end('<h1>Hello world</h1>');
|
44 | });
|
45 |
|
46 | server.listen(80);
|
47 |
|
48 | // socket.io, I choose you
|
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 | });
|
56 |
|
57 | On the client:
|
58 |
|
59 | <script src="/socket.io/socket.io.js"></script>
|
60 | <script>
|
61 | var socket = new io.Socket();
|
62 | socket.connect();
|
63 | socket.on('connect', function(){ … })
|
64 | socket.on('message', function(){ … })
|
65 | socket.on('disconnect', function(){ … })
|
66 | </script>
|
67 |
|
68 | The [client-side](http://github.com/learnboost/socket.io) files are served automatically by `Socket.IO-node`.
|
69 |
|
70 | ## Documentation
|
71 |
|
72 | ### Listener
|
73 |
|
74 | io.listen(<http.Server>, [options])
|
75 |
|
76 | Returns: a `Listener` instance
|
77 |
|
78 | Public Properties:
|
79 |
|
80 | - *server*
|
81 |
|
82 | An instance of _process.http.Server_.
|
83 |
|
84 | - *options*
|
85 |
|
86 | The passed-in options, combined with the defaults.
|
87 |
|
88 | - *clients*
|
89 |
|
90 | An object of clients, indexed by session ID.
|
91 |
|
92 | Methods:
|
93 |
|
94 | - *addListener(event, λ)*
|
95 |
|
96 | 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(){}`
|
97 |
|
98 | - *removeListener(event, λ)*
|
99 |
|
100 | Removes a listener from the listener array for the specified event.
|
101 |
|
102 | - *broadcast(message, [except])*
|
103 |
|
104 | 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.
|
105 |
|
106 | Options:
|
107 |
|
108 | - *resource*
|
109 |
|
110 | socket.io
|
111 |
|
112 | The resource is what allows the `socket.io` server to identify incoming connections from `socket.io` clients. Make sure they're in sync.
|
113 |
|
114 | - *flashPolicyServer*
|
115 |
|
116 | true
|
117 |
|
118 | 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.
|
119 |
|
120 |
|
121 | - *transports*
|
122 |
|
123 | ['websocket', 'flashsocket', 'htmlfile', 'xhr-multipart', 'xhr-polling',
|
124 | 'jsonp-polling']
|
125 |
|
126 | A list of the accepted transports.
|
127 |
|
128 | - *transportOptions*
|
129 |
|
130 | An object of options to pass to each transport. For example `{ websocket: { closeTimeout: 8000 }}`
|
131 |
|
132 | - *log*
|
133 |
|
134 | ƒ(){ sys.log }
|
135 |
|
136 | The logging function. Defaults to outputting to `stdout` through `sys.log`
|
137 |
|
138 | Events:
|
139 |
|
140 | - *clientConnect(client)*
|
141 |
|
142 | Fired when a client is connected. Receives the Client instance as parameter.
|
143 |
|
144 | - *clientMessage(message, client)*
|
145 |
|
146 | Fired when a message from a client is received. Receives the message and Client instance as parameters.
|
147 |
|
148 | - *clientDisconnect(client)*
|
149 |
|
150 | Fired when a client is disconnected. Receives the Client instance as a parameter.
|
151 |
|
152 | Important note: `this` in the event listener refers to the `Listener` instance.
|
153 |
|
154 | ### Client
|
155 |
|
156 | Client(listener, req, res)
|
157 |
|
158 | Public Properties:
|
159 |
|
160 | - *listener*
|
161 |
|
162 | The `Listener` instance to which this client belongs.
|
163 |
|
164 | - *connected*
|
165 |
|
166 | Whether the client is connected.
|
167 |
|
168 | - *connections*
|
169 |
|
170 | Number of times the client has connected.
|
171 |
|
172 | Methods:
|
173 |
|
174 | - *send(message)*
|
175 |
|
176 | Sends a message to the client.
|
177 |
|
178 | - *broadcast(message)*
|
179 |
|
180 | Sends a message to all other clients. Equivalent to Listener::broadcast(message, client.sessionId).
|
181 |
|
182 | ## Protocol
|
183 |
|
184 | One of the design goals is that you should be able to implement whatever protocol you desire without `Socket.IO` getting in the way. `Socket.IO` has a minimal, unobtrusive protocol layer, consisting of two parts:
|
185 |
|
186 | * Connection handshake
|
187 |
|
188 | This is required to simulate a full duplex socket with transports such as XHR Polling or Server-sent Events (which is a "one-way socket"). The basic idea is that the first message received from the server will be a JSON object that contains a session ID used for further communications exchanged between the client and server.
|
189 |
|
190 | The concept of session also naturally benefits a full-duplex WebSocket, in the event of an accidental disconnection and a quick reconnection. Messages that the server intends to deliver to the client are cached temporarily until reconnection.
|
191 |
|
192 | The implementation of reconnection logic (potentially with retries) is left for the user. By default, transports that are keep-alive or open all the time (like WebSocket) have a timeout of 0 if a disconnection is detected.
|
193 |
|
194 | * Message batching
|
195 |
|
196 | Messages are buffered in order to optimize resources. In the event of the server trying to send multiple messages while a client is temporarily disconnected (eg: xhr polling), the messages are stacked and then encoded in a lightweight way, and sent to the client whenever it becomes available.
|
197 |
|
198 | Despite this extra layer, the messages are delivered unaltered to the various event listeners. You can `JSON.stringify()` objects, send XML, or even plain text.
|
199 |
|
200 | ## Credits
|
201 |
|
202 | - Guillermo Rauch <guillermo@learnboost.com> ([Guille](http://github.com/guille))
|
203 |
|
204 | - Arnout Kazemier ([3rd-Eden](http://github.com/3rd-Eden))
|
205 |
|
206 | ## License
|
207 |
|
208 | (The MIT License)
|
209 |
|
210 | Copyright (c) 2010 LearnBoost <dev@learnboost.com>
|
211 |
|
212 | Permission is hereby granted, free of charge, to any person obtaining
|
213 | a copy of this software and associated documentation files (the
|
214 | 'Software'), to deal in the Software without restriction, including
|
215 | without limitation the rights to use, copy, modify, merge, publish,
|
216 | distribute, sublicense, and/or sell copies of the Software, and to
|
217 | permit persons to whom the Software is furnished to do so, subject to
|
218 | the following conditions:
|
219 |
|
220 | The above copyright notice and this permission notice shall be
|
221 | included in all copies or substantial portions of the Software.
|
222 |
|
223 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
224 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
225 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
226 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
227 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
228 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
229 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|