Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 339 lines (250 sloc) 13.461 kB
a99b35c @majek Readme header.
majek authored
1 SockJS family:
2
752db5c @majek Repo migrated
majek authored
3 * [SockJS-client](https://github.com/sockjs/sockjs-client) JavaScript client library
4 * [SockJS-node](https://github.com/sockjs/sockjs-node) Node.js server
2896ab0 @majek Add link to Erlang server
majek authored
5 * [SockJS-erlang](https://github.com/sockjs/sockjs-erlang) Erlang server
c94c762 @majek Advertise Lua/Tornado/Vert.x SockJS servers
majek authored
6 * [SockJS-lua](https://github.com/luvit/sockjs-luvit) Lua/Luvit server
7 * [SockJS-tornado](https://github.com/MrJoes/sockjs-tornado) Python/Tornado server
8 * [vert.x](https://github.com/purplefox/vert.x) Java/vert.x server
a99b35c @majek Readme header.
majek authored
9
96eac01 @majek Mention other sockjs related projects
majek authored
10 Work in progress:
11
12 * [SockJS-ruby](https://github.com/sockjs/sockjs-ruby)
13 * [SockJS-netty](https://github.com/cgbystrom/sockjs-netty)
14 * [SockJS-gevent](https://github.com/sdiehl/sockjs-gevent)
15 * [pyramid-SockJS](https://github.com/fafhrd91/pyramid_sockjs)
16 * [wildcloud-websockets](https://github.com/wildcloud/wildcloud-websockets)
17
a99b35c @majek Readme header.
majek authored
18
19 SockJS-client
20 =============
3f903cf @majek Brief readme
majek authored
21
9465a55 @majek Readme tweaks.
majek authored
22 SockJS is a browser JavaScript library that provides a WebSocket-like
23 object. SockJS gives you a coherent, cross-browser, Javascript API
24 which creates a low latency, full duplex, cross-domain communication
25 channel between the browser and the web server.
26
27 Under the hood SockJS tries to use native WebSockets first. If that
28 fails it can use a variety of browser-specific transport protocols and
29 presents them through WebSocket-like abstractions.
30
31 SockJS is intended to work for all modern browsers and in environments
32 which don't support WebSocket protcol, for example behind restrictive
33 corporate proxies.
34
35 SockJS-client does require a server counterpart:
36
752db5c @majek Repo migrated
majek authored
37 * [SockJS-node](https://github.com/sockjs/sockjs-node) is a SockJS
9465a55 @majek Readme tweaks.
majek authored
38 server for Node.js.
6deef24 @majek More readme
majek authored
39
3f903cf @majek Brief readme
majek authored
40
140a129 @majek Few more words
majek authored
41 Philosophy:
42
9465a55 @majek Readme tweaks.
majek authored
43 * The API should follow
44 [HTML5 Websockets API](http://dev.w3.org/html5/websockets/) as
45 closely as possible.
46 * All the transports must support cross domain connections out of the
6deef24 @majek More readme
majek authored
47 box. It's possible and recommended to host SockJS server on
9465a55 @majek Readme tweaks.
majek authored
48 different server than your main web site.
140a129 @majek Few more words
majek authored
49 * There is a support for at least one streaming protocol for every
50 major browser.
3a00f84 @majek Advertise cross-domain streaming transports
majek authored
51 * Streaming transports should work cross-domain and
52 should support cookies (for cookie-based sticky sessions).
3f903cf @majek Brief readme
majek authored
53 * Polling transports are be used as a fallback for old browsers and
54 hosts behind restrictive proxies.
9465a55 @majek Readme tweaks.
majek authored
55 * Connection establishment should be fast and lightweight.
6deef24 @majek More readme
majek authored
56 * No Flash inside (no need to open port 843 - which doesn't work
57 through proxies, no need to host 'crossdomain.xml', no need
58 [to wait for 3 seconds](https://github.com/gimite/web-socket-js/issues/49)
59 in order to detect problems)
60
06099a6 @majek Githubify markup
majek authored
61
62 Subscribe to
6b10bae @majek Use new google groups interface
majek authored
63 [SockJS mailing list](https://groups.google.com/forum/#!forum/sockjs) for
06099a6 @majek Githubify markup
majek authored
64 discussions and support.
8307d18 @majek Advertise mailing list
majek authored
65
6deef24 @majek More readme
majek authored
66
f9c2839 @majek Deployed tests
majek authored
67 Live QUnit tests and smoke tests
68 --------------------------------
69
70 SockJS comes with some QUnit tests and a few smoke tests (using
752db5c @majek Repo migrated
majek authored
71 [SockJS-node](https://github.com/sockjs/sockjs-client) on the server
f9c2839 @majek Deployed tests
majek authored
72 side). At the moment they are deployed in few places:
73
74 * http://sockjs.popcnt.org/ (hosted in Europe)
8b86bd3 @majek Cosmetic, few words about deployment and load balancing.
majek authored
75 * http://sockjs.cloudfoundry.com/ (CloudFoundry, websockets disabled, loadbalanced)
76 * https://sockjs.cloudfoundry.com/ (CloudFoundry SSL, websockets disabled, loadbalanced)
77 * http://sockjs.herokuapp.com/ (Heroku, websockets disabled)
f9c2839 @majek Deployed tests
majek authored
78
79
6deef24 @majek More readme
majek authored
80 Example
81 -------
82
9465a55 @majek Readme tweaks.
majek authored
83 SockJS mimics [WebSockets API](http://dev.w3.org/html5/websockets/)
84 but instead of `WebSocket` there is a `SockJS` Javascript object.
fd59839 @majek Few more words in readme
majek authored
85
6deef24 @majek More readme
majek authored
86 First, you need to load SockJS JavaScript library, for example you can
87 put that in your http head:
88
ee89722 @majek Readme updated to 0.2
majek authored
89 <script src="http://cdn.sockjs.org/sockjs-0.2.min.js">
6deef24 @majek More readme
majek authored
90 </script>
91
92 After the script is loaded you can establish a connection with the
93 SockJS server. Here's a simple example:
94
fdf90ad @majek Edited README.md via GitHub
majek authored
95 ```javascript
96 <script>
97 var sock = new SockJS('http://mydomain.com/my_prefix');
98 sock.onopen = function() {
99 console.log('open');
100 };
101 sock.onmessage = function(e) {
102 console.log('message', e.data);
103 };
104 sock.onclose = function() {
105 console.log('close');
106 };
107 </script>
108 ```
3f903cf @majek Brief readme
majek authored
109
ceafdd6 @majek Generic htmlfile support
majek authored
110 SockJS-client API
111 -----------------
112
113 ### SockJS class
114
115 Similar to 'WebSocket' class 'SockJS' constructor takes one, or more arguments:
116
117 ```javascript
33fcc89 @majek API change - handle `protocols_whitelist` option instead of second pa…
majek authored
118 var sockjs = new SockJS(url, _reserved, options);
ceafdd6 @majek Generic htmlfile support
majek authored
119 ```
120
121 Where `options` is a hash which can contain:
122
72299c1 @majek Markdown: bold not italic
majek authored
123 * **debug (boolean)**
f78d642 @majek Github changed the markdown format. Is that better?
majek authored
124
33fcc89 @majek API change - handle `protocols_whitelist` option instead of second pa…
majek authored
125 Print some debugging messages using 'console.log'.
f78d642 @majek Github changed the markdown format. Is that better?
majek authored
126
72299c1 @majek Markdown: bold not italic
majek authored
127 * **devel (boolean)**
f78d642 @majek Github changed the markdown format. Is that better?
majek authored
128
33fcc89 @majek API change - handle `protocols_whitelist` option instead of second pa…
majek authored
129 Development mode. Currently setting it disables caching of the
130 'iframe.html'.
f78d642 @majek Github changed the markdown format. Is that better?
majek authored
131
33fcc89 @majek API change - handle `protocols_whitelist` option instead of second pa…
majek authored
132 * **protocols_whitelist (list of strings)**
133
134 Sometimes it is useful to disable some fallback protocols. This
135 option allows you to supply a list protocols that may be used by
136 SockJS. By default all available protocols will be used, which is
137 equivalent to supplying: "['websocket', 'xdr-streaming', 'xhr-streaming',
138 'iframe-eventsource', 'iframe-htmlfile', 'xdr-polling', 'xhr-polling',
139 'iframe-xhr-polling', 'jsonp-polling']"
f78d642 @majek Github changed the markdown format. Is that better?
majek authored
140
ceafdd6 @majek Generic htmlfile support
majek authored
141
1bde9be @majek A note on SockJS limitations
majek authored
142 Although the 'SockJS' object tries to emulate the 'WebSocket'
143 behaviour, it's impossible to support all features. One of the
144 important SockJS limitations is the fact that you're not allowed to
049e61e @majek Clarify opening multiple SockJS connections using subdomains.
majek authored
145 open more than one SockJS connection to a single domain at a time.
146 This limitation is caused by a in-browser limit of outgoing
8e077dd @majek Cosmetic: reformatting
majek authored
147 connections - usually browsers don't allow opening more than two
148 outgoing connections to a single domain. Single SockJS session
149 requires those two connections - one for downloading data, other for
150 sending messages. Opening second SockJS session at the same time
151 would most probably block and can result in both sessions timing out.
049e61e @majek Clarify opening multiple SockJS connections using subdomains.
majek authored
152
153 Opening more than one SockJS connection at a time is generally a
154 bad practice. If you absolutely must do it, you can use
155 mutliple subdomains, using different subdomain for every
156 SockJS connection.
1bde9be @majek A note on SockJS limitations
majek authored
157
1cbf147 @majek New transport table.
majek authored
158 Supported transports, by browser
159 --------------------------------
160
4b126d6 @majek Markdown: cosmetic, removed old tables
majek authored
161 _Browser_ | _Websockets_ | _Streaming_ | _Polling_
162 ----------------|------------------|-------------|-----------
93cde9b @majek cosmetic: mention ie6
majek authored
163 IE 6, 7 | no | no | jsonp-polling
80d2da0 @majek Separate xhr-polling from xdr-polling - new name for xdr transports.
majek authored
164 IE 8, 9 (cookies=no) | no | xdr-streaming &dagger; | xdr-polling &dagger;
1cbf147 @majek New transport table.
majek authored
165 IE 8, 9 (cookies=yes)| no | iframe-htmlfile | iframe-xhr-polling
166 Chrome 6-12 | hixie-76 | xhr-streaming | xhr-polling
167 Chrome 14+ | hybi-10 | xhr-streaming | xhr-polling
ec1a8ea @majek Add a note about disabled websockets to readme.
majek authored
168 Firefox <10 | no &Dagger; | xhr-streaming | xhr-polling
1cbf147 @majek New transport table.
majek authored
169 Firefox 10+ | hybi-10 | xhr-streaming | xhr-polling
170 Safari 5 | hixie-76 | xhr-streaming | xhr-polling
ec1a8ea @majek Add a note about disabled websockets to readme.
majek authored
171 Opera 10.70+ | no &Dagger; | iframe-eventsource | iframe-xhr-polling
4b126d6 @majek Markdown: cosmetic, removed old tables
majek authored
172 Konqueror | no | no | jsonp-polling
1cbf147 @majek New transport table.
majek authored
173
31db04a @majek Markdown: Let's try dagger instead of star. Multiline tables don't work
majek authored
174
4b126d6 @majek Markdown: cosmetic, removed old tables
majek authored
175 * **&dagger;**: IE 8+ supports [XDomainRequest][^9], which is
176 esentially a modified AJAX/XHR that can do requests across
177 domains. But unfortunately it doesn't send any cookies, which
178 makes it inaproppriate for deployments when the load balancer uses
179 JSESSIONID cookie to do sticky sessions.
31db04a @majek Markdown: Let's try dagger instead of star. Multiline tables don't work
majek authored
180
80d2da0 @majek Separate xhr-polling from xdr-polling - new name for xdr transports.
majek authored
181 * **&Dagger;**: Firefox 4.0 and Opera 11.00 and shipped with disabled
182 Websockets "hixie-76". They can still be enabled by manually
183 changing a browser setting.
1cbf147 @majek New transport table.
majek authored
184
185 Supported transports, by name
186 -----------------------------
187
4b126d6 @majek Markdown: cosmetic, removed old tables
majek authored
188 _Transport_ | _References_
189 ---------------------|---------------
1cbf147 @majek New transport table.
majek authored
190 websocket (hixie-76) | [draft-hixie-thewebsocketprotocol-76][^1]
191 websocket (hybi-10) | [draft-ietf-hybi-thewebsocketprotocol-10][^2]
80d2da0 @majek Separate xhr-polling from xdr-polling - new name for xdr transports.
majek authored
192 xhr-streaming | Transport using [Cross domain XHR][^5] [streaming][^7] capability (readyState=3).
193 xdr-streaming | Transport using [XDomainRequest][^9] [streaming][^7] capability (readyState=3).
1cbf147 @majek New transport table.
majek authored
194 iframe-eventsource | [EventSource][^4] used from an [iframe via postMessage][^3].
195 iframe-htmlfile | [HtmlFile][^8] used from an [iframe via postMessage][^3].
80d2da0 @majek Separate xhr-polling from xdr-polling - new name for xdr transports.
majek authored
196 xhr-polling | Long-polling using [cross domain XHR][^5].
197 xdr-polling | Long-polling using [XDomainRequest][^9].
31db04a @majek Markdown: Let's try dagger instead of star. Multiline tables don't work
majek authored
198 iframe-xhr-polling | Long-polling using normal AJAX from an [iframe via postMessage][^3].
c970573 @nehresma Typo fix
nehresma authored
199 jsonp-polling | Slow and old fashioned [JSONP polling][^6]. This transport will show "busy indicator" (aka: "spinning wheel") when sending data.
3f903cf @majek Brief readme
majek authored
200
5fa37d0 @majek Renamed xhrpolling to xhr-polling, other changes
majek authored
201
3f903cf @majek Brief readme
majek authored
202 [^1]: http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76
203 [^2]: http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10
baa277c @majek Brief readme
majek authored
204 [^3]: https://developer.mozilla.org/en/DOM/window.postMessage
a1f79ff @majek Brief readme
majek authored
205 [^4]: http://dev.w3.org/html5/eventsource/
52a6fb9 @majek Let's use the name XDR for cross domain XHR.
majek authored
206 [^5]: https://secure.wikimedia.org/wikipedia/en/wiki/XMLHttpRequest#Cross-domain_requests
207 [^6]: https://secure.wikimedia.org/wikipedia/en/wiki/JSONP
797c3ae @majek we do support xhr-streaming now
majek authored
208 [^7]: http://www.debugtheweb.com/test/teststreaming.aspx
ceafdd6 @majek Generic htmlfile support
majek authored
209 [^8]: http://cometdaily.com/2007/11/18/ie-activexhtmlfile-transport-part-ii/
1cbf147 @majek New transport table.
majek authored
210 [^9]: http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx
6deef24 @majek More readme
majek authored
211
212
213 Deployment
214 ----------
215
6579d41 @majek Use sockjs from CDN
majek authored
216 In order to utilize best performance you should use the SockJS-client
217 releases hosted on SockJS CDN. You should use a version of sockjs-client
218 that supports the protocol used by your server. For example:
219
ee89722 @majek Readme updated to 0.2
majek authored
220 <script src="http://cdn.sockjs.org/sockjs-0.2.min.js">
6579d41 @majek Use sockjs from CDN
majek authored
221 </script>
222
223 A list of files hosted on a CDN is available here: http://sockjs.github.com/sockjs-client/ .
8b86bd3 @majek Cosmetic, few words about deployment and load balancing.
majek authored
224
a1174fc @majek cloudfront can do ssl
majek authored
225 You can also use or CDN via https (using Cloud Front domain name):
226
ee89722 @majek Readme updated to 0.2
majek authored
227 <script src="https://d1fxtkz8shb9d2.cloudfront.net/sockjs-0.2.js">
a1174fc @majek cloudfront can do ssl
majek authored
228 </script>
229
8b86bd3 @majek Cosmetic, few words about deployment and load balancing.
majek authored
230 For server-side deployment tricks, especially about load balancing and
231 session stickiness, take a look at the
752db5c @majek Repo migrated
majek authored
232 [SockJS-node readme](https://github.com/sockjs/sockjs-node#readme).
fd59839 @majek Few more words in readme
majek authored
233
234
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
235 Development and testing
236 -----------------------
fd59839 @majek Few more words in readme
majek authored
237
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
238 SockJS-client needs [Node.js](http://nodejs.org/) for running a test
239 server and JavaScript minification. If you want to work on
240 SockJS-client source code, check out the git repo and follow this
241 steps:
fd59839 @majek Few more words in readme
majek authored
242
ce4a8b9 @majek Change directory before playing with npm
majek authored
243 cd sockjs-client
cfbc265 @majek Cosmetic.
majek authored
244 npm install --dev
fd59839 @majek Few more words in readme
majek authored
245
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
246 To generate JavaScript run:
fd59839 @majek Few more words in readme
majek authored
247
248 make sockjs.js
249
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
250 To generate minified JavaScript run:
fd59839 @majek Few more words in readme
majek authored
251
252 make sockjs.min.js
253
254 (To generate both run `make build`.)
255
256
257 ### Testing
258
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
259 Once you compiled SockJS-client you may want to check if your changes
260 pass all the tests. To run the tests you need a server that can answer
261 various SockJS requests. A common way is to use `SockJS-node` test
262 server for that. To run it (by default it will be listening on port 8081):
263
264 cd sockjs-node
265 npm install --dev
fe049be @majek Cosmetic.
majek authored
266 make build
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
267 make test_server
268
269 At this point you're ready to run a SockJS-client server that will
270 server your freshly compiled JavaScript and various static http and
271 javscript files (by default it will run on port 8080).
fd59839 @majek Few more words in readme
majek authored
272
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
273 cd sockjs-client
fd59839 @majek Few more words in readme
majek authored
274 make test
275
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
276 At that point you should have two web servers running: sockjs-node on
277 8081 and sockjs-client on 8080. When you open the browser on
278 [http://localhost:8080/](http://localhost:8080/) you should be able
279 run the QUnit tests against your sockjs-node server.
280
fe049be @majek Cosmetic.
majek authored
281 If you look at your browser console you will see warnings like that:
282
283 Incompatibile SockJS! Main site uses: "a", the iframe: "b".
284
285 This is due to a fact that SockJS-node test server is using compiled
286 javascript from CDN, rather than your freshly compiled version. To fix
287 that you must amend `sockjs_url` that is used by SockJS-node test
7ea8e5b @majek Cosmetic: Add links to `config.js` files.
majek authored
288 server. Edit the [`config.js`](https://github.com/sockjs/sockjs-node/blob/master/examples/test_server/config.js) file:
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
289
290 vim sockjs-node/examples/test_server/config.js
291
292 And replace `sockjs_url` setting which by default points to CDN:
293
ee89722 @majek Readme updated to 0.2
majek authored
294 sockjs_url: 'http://cdn.sockjs.org/sockjs-0.2.min.js',
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
295
fe049be @majek Cosmetic.
majek authored
296 to a freshly compiled sockjs, for example:
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
297
298 sockjs_url: 'http://localhost:8080/lib/sockjs.js',
fd59839 @majek Few more words in readme
majek authored
299
300
7ea8e5b @majek Cosmetic: Add links to `config.js` files.
majek authored
301 Also, if you want to run tests agains SockJS server not running on
302 `localhost:8081` you may want to edit the
303 [`tests/config.js`](https://github.com/sockjs/sockjs-client/blob/master/tests/config.js)
304 file.
305
bb17c8b @majek Test server was moved out to sockjs-node
majek authored
306 Additionally, if you're doing more serious development consider using
307 `make serve`, which will automatically reload the server when you
308 modify the source code.
9a45211 @majek Fix #18: start documentin browser quirks
majek authored
309
310
311 Browser Quirks
312 --------------
313
314 There are various browser quirks which we don't intend to address:
315
316 * Pressing ESC in Firefox closes SockJS connection ([described
317 in socket.io thread](https://groups.google.com/group/socket_io/browse_thread/thread/a705e4cb532e8808)).
db84a06 @majek Jsonp only shows spinning cursor on send.
majek authored
318 * Jsonp-polling transport will show a "spinning wheel" (aka. "busy indicator")
319 when sending data.
b796f67 @majek Mention single-sockjs-connection limitation in the quirks section
majek authored
320 * In most of the browsers you can't open more than one SockJS
088df5a @majek Few more comments about jsonp.
majek authored
321 connection to one domain at the same time (with the exception
322 of native websockets).
9b3321c @majek Don't test Unicode surrogates - it can't work against python sockjs s…
majek authored
323 * Although SockJS is trying to escape any strange Unicode characters
d566f76 @majek Apparently \xFFFE and \xFFFF aren't valid unicode characters
majek authored
324 (even invalid ones - [like surrogates \xD800-\xDBFF](http://en.wikipedia.org/wiki/Mapping_of_Unicode_characters#Surrogates) or [\xFFFE and \xFFFF](https://en.wikipedia.org/wiki/Unicode#Character_General_Category))
fc4f9dd @majek #29 Explain that we now support all unicode chars.
majek authored
325 it's advisable to use only valid characters. Using invalid
9b3321c @majek Don't test Unicode surrogates - it can't work against python sockjs s…
majek authored
326 characters is a bit slower, and may not work with SockJS servers
327 that have a proper Unicode support.
ae0d450 @majek Having a global `onmessage` function is a bad idea.
majek authored
328 * Having a global function called `onmessage` or such is probably a
088df5a @majek Few more comments about jsonp.
majek authored
329 bad idea, as it could be called by the built-in `postMessage` API.
d67c678 @majek Mention problems with file:// urls
majek authored
330 * Serving an html page that uses SockJS from `file://` url will not
331 work. This is due to a badly thought through
332 [CORS specification](http://dvcs.w3.org/hg/cors/raw-file/tip/Overview.html)
333 It is impossible to receive response to an Ajax request with
334 cookies set (`withCredentials` set to `true`) sent from a `file://`
335 origin.
6a5040a @majek Mention https in readme
majek authored
336 * From SockJS point of view there is nothing special about
337 SSL/HTTPS. Connecting between unencrypted and encrypted sites
338 should work just fine.
Something went wrong with that request. Please try again.