github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/public/libs/sockjs-client-1.1.0/README.md (about) 1 2 # SockJS-client 3 4 [](https://www.npmjs.com/package/sockjs-client)[](https://travis-ci.org/sockjs/sockjs-client)[](https://david-dm.org/sockjs/sockjs-client)[](https://gitter.im/sockjs/sockjs-client) 5 [](https://saucelabs.com/u/brycekahle) 6 7 SockJS is a browser JavaScript library that provides a WebSocket-like 8 object. SockJS gives you a coherent, cross-browser, Javascript API 9 which creates a low latency, full duplex, cross-domain communication 10 channel between the browser and the web server. 11 12 Under the hood SockJS tries to use native WebSockets first. If that 13 fails it can use a variety of browser-specific transport protocols and 14 presents them through WebSocket-like abstractions. 15 16 SockJS is intended to work for all modern browsers and in environments 17 which don't support the WebSocket protocol -- for example, behind restrictive 18 corporate proxies. 19 20 SockJS-client does require a server counterpart: 21 22 * [SockJS-node](https://github.com/sockjs/sockjs-node) is a SockJS 23 server for Node.js. 24 25 26 Philosophy: 27 28 * The API should follow 29 [HTML5 Websockets API](http://dev.w3.org/html5/websockets/) as 30 closely as possible. 31 * All the transports must support cross domain connections out of the 32 box. It's possible and recommended to host a SockJS server on a 33 different server than your main web site. 34 * There is support for at least one streaming protocol for every 35 major browser. 36 * Streaming transports should work cross-domain and 37 should support cookies (for cookie-based sticky sessions). 38 * Polling transports are used as a fallback for old browsers and 39 hosts behind restrictive proxies. 40 * Connection establishment should be fast and lightweight. 41 * No Flash inside (no need to open port 843 - which doesn't work 42 through proxies, no need to host 'crossdomain.xml', no need 43 [to wait for 3 seconds](https://github.com/gimite/web-socket-js/issues/49) 44 in order to detect problems) 45 46 47 Subscribe to 48 [SockJS mailing list](https://groups.google.com/forum/#!forum/sockjs) for 49 discussions and support. 50 51 SockJS family: 52 53 * [SockJS-client](https://github.com/sockjs/sockjs-client) JavaScript client library 54 * [SockJS-node](https://github.com/sockjs/sockjs-node) Node.js server 55 * [SockJS-erlang](https://github.com/sockjs/sockjs-erlang) Erlang server 56 * [SockJS-cyclone](https://github.com/flaviogrossi/sockjs-cyclone) Python/Cyclone/Twisted server 57 * [SockJS-tornado](https://github.com/MrJoes/sockjs-tornado) Python/Tornado server 58 * [SockJS-twisted](https://github.com/DesertBus/sockjs-twisted/) Python/Twisted server 59 * [Spring Framework](http://projects.spring.io/spring-framework) Java [client](http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/websocket.html#websocket-fallback-sockjs-client) & server 60 * [vert.x](https://github.com/vert-x/vert.x) Java/vert.x server 61 * [Xitrum](http://xitrum-framework.github.io/) Scala server 62 * [Atmosphere Framework](http://github.com/Atmosphere/atmosphere) JavaEE Server, Play Framework, Netty, Vert.x 63 64 Work in progress: 65 66 * [SockJS-ruby](https://github.com/nyarly/sockjs-ruby) 67 * [SockJS-netty](https://github.com/cgbystrom/sockjs-netty) 68 * [SockJS-gevent](https://github.com/ksava/sockjs-gevent) ([SockJS-gevent fork](https://github.com/njoyce/sockjs-gevent)) 69 * [pyramid-SockJS](https://github.com/fafhrd91/pyramid_sockjs) 70 * [wildcloud-websockets](https://github.com/wildcloud/wildcloud-websockets) 71 * [wai-SockJS](https://github.com/Palmik/wai-sockjs) 72 * [SockJS-perl](https://github.com/vti/sockjs-perl) 73 * [SockJS-go](https://github.com/igm/sockjs-go/) 74 75 Getting Started 76 ------- 77 78 SockJS mimics the [WebSockets API](http://dev.w3.org/html5/websockets/), 79 but instead of `WebSocket` there is a `SockJS` Javascript object. 80 81 First, you need to load the SockJS JavaScript library. For example, you can 82 put that in your HTML head: 83 84 ```html 85 <script src="//cdn.jsdelivr.net/sockjs/1/sockjs.min.js"></script> 86 ``` 87 88 After the script is loaded you can establish a connection with the 89 SockJS server. Here's a simple example: 90 91 ```javascript 92 var sock = new SockJS('http://mydomain.com/my_prefix'); 93 sock.onopen = function() { 94 console.log('open'); 95 }; 96 sock.onmessage = function(e) { 97 console.log('message', e.data); 98 }; 99 sock.onclose = function() { 100 console.log('close'); 101 }; 102 103 sock.send('test'); 104 sock.close(); 105 ``` 106 107 SockJS-client API 108 ----------------- 109 110 ### SockJS class 111 112 Similar to the 'WebSocket' API, the 'SockJS' constructor takes one, or more arguments: 113 114 ```javascript 115 var sockjs = new SockJS(url, _reserved, options); 116 ``` 117 118 `url` may contain a query string, if one is desired. 119 120 Where `options` is a hash which can contain: 121 122 * **server (string)** 123 124 String to append to url for actual data connection. Defaults to a random 4 digit number. 125 126 * **transports (string OR array of strings)** 127 128 Sometimes it is useful to disable some fallback transports. This 129 option allows you to supply a list transports that may be used by 130 SockJS. By default all available transports will be used. 131 132 * **sessionId (number OR function)** 133 134 Both client and server use session identifiers to distinguish connections. 135 If you specify this option as a number, SockJS will use its random string 136 generator function to generate session ids that are N-character long 137 (where N corresponds to the number specified by **sessionId**). 138 When you specify this option as a function, the function must return a 139 randomly generated string. Every time SockJS needs to generate a session 140 id it will call this function and use the returned string directly. 141 If you don't specify this option, the default is to use the default random 142 string generator to generate 8-character long session ids. 143 144 Although the 'SockJS' object tries to emulate the 'WebSocket' 145 behaviour, it's impossible to support all of its features. An 146 important SockJS limitation is the fact that you're not allowed to 147 open more than one SockJS connection to a single domain at a time. 148 This limitation is caused by an in-browser limit of outgoing 149 connections - usually [browsers don't allow opening more than two 150 outgoing connections to a single domain](http://stackoverflow.com/questions/985431/max-parallel-http-connections-in-a-browser). A single SockJS session 151 requires those two connections - one for downloading data, the other for 152 sending messages. Opening a second SockJS session at the same time 153 would most likely block, and can result in both sessions timing out. 154 155 Opening more than one SockJS connection at a time is generally a 156 bad practice. If you absolutely must do it, you can use 157 multiple subdomains, using a different subdomain for every 158 SockJS connection. 159 160 Supported transports, by browser (html served from http:// or https://) 161 ----------------------------------------------------------------------- 162 163 _Browser_ | _Websockets_ | _Streaming_ | _Polling_ 164 ----------------|------------------|-------------|------------------- 165 IE 6, 7 | no | no | jsonp-polling 166 IE 8, 9 (cookies=no) | no | xdr-streaming † | xdr-polling † 167 IE 8, 9 (cookies=yes)| no | iframe-htmlfile | iframe-xhr-polling 168 IE 10 | rfc6455 | xhr-streaming | xhr-polling 169 Chrome 6-13 | hixie-76 | xhr-streaming | xhr-polling 170 Chrome 14+ | hybi-10 / rfc6455| xhr-streaming | xhr-polling 171 Firefox <10 | no ‡ | xhr-streaming | xhr-polling 172 Firefox 10+ | hybi-10 / rfc6455| xhr-streaming | xhr-polling 173 Safari 5.x | hixie-76 | xhr-streaming | xhr-polling 174 Safari 6+ | rfc6455 | xhr-streaming | xhr-polling 175 Opera 10.70+ | no ‡ | iframe-eventsource | iframe-xhr-polling 176 Opera 12.10+ | rfc6455 | xhr-streaming | xhr-polling 177 Konqueror | no | no | jsonp-polling 178 179 180 * **†**: IE 8+ supports [XDomainRequest][^9], which is 181 essentially a modified AJAX/XHR that can do requests across 182 domains. But unfortunately it doesn't send any cookies, which 183 makes it inappropriate for deployments when the load balancer uses 184 JSESSIONID cookie to do sticky sessions. 185 186 * **‡**: Firefox 4.0 and Opera 11.00 and shipped with disabled 187 Websockets "hixie-76". They can still be enabled by manually 188 changing a browser setting. 189 190 Supported transports, by browser (html served from file://) 191 ----------------------------------------------------------- 192 193 Sometimes you may want to serve your html from "file://" address - for 194 development or if you're using PhoneGap or similar technologies. But 195 due to the Cross Origin Policy files served from "file://" have no 196 Origin, and that means some of SockJS transports won't work. For this 197 reason the SockJS transport table is different than usually, major 198 differences are: 199 200 _Browser_ | _Websockets_ | _Streaming_ | _Polling_ 201 ----------------|---------------|--------------------|------------------- 202 IE 8, 9 | same as above | iframe-htmlfile | iframe-xhr-polling 203 Other | same as above | iframe-eventsource | iframe-xhr-polling 204 205 Supported transports, by name 206 ----------------------------- 207 208 _Transport_ | _References_ 209 ---------------------|--------------- 210 websocket (rfc6455) | [rfc 6455][^10] 211 websocket (hixie-76) | [draft-hixie-thewebsocketprotocol-76][^1] 212 websocket (hybi-10) | [draft-ietf-hybi-thewebsocketprotocol-10][^2] 213 xhr-streaming | Transport using [Cross domain XHR][^5] [streaming][^7] capability (readyState=3). 214 xdr-streaming | Transport using [XDomainRequest][^9] [streaming][^7] capability (readyState=3). 215 eventsource | [EventSource][^4]. 216 iframe-eventsource | [EventSource][^4] used from an [iframe via postMessage][^3]. 217 htmlfile | [HtmlFile][^8]. 218 iframe-htmlfile | [HtmlFile][^8] used from an [iframe via postMessage][^3]. 219 xhr-polling | Long-polling using [cross domain XHR][^5]. 220 xdr-polling | Long-polling using [XDomainRequest][^9]. 221 iframe-xhr-polling | Long-polling using normal AJAX from an [iframe via postMessage][^3]. 222 jsonp-polling | Slow and old fashioned [JSONP polling][^6]. This transport will show "busy indicator" (aka: "spinning wheel") when sending data. 223 224 225 [^1]: http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76 226 [^2]: http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 227 [^3]: https://developer.mozilla.org/en/DOM/window.postMessage 228 [^4]: http://dev.w3.org/html5/eventsource/ 229 [^5]: https://secure.wikimedia.org/wikipedia/en/wiki/XMLHttpRequest#Cross-domain_requests 230 [^6]: https://secure.wikimedia.org/wikipedia/en/wiki/JSONP 231 [^7]: http://www.debugtheweb.com/test/teststreaming.aspx 232 [^8]: http://cometdaily.com/2007/11/18/ie-activexhtmlfile-transport-part-ii/ 233 [^9]: http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx 234 [^10]: http://www.rfc-editor.org/rfc/rfc6455.txt 235 236 237 Connecting to SockJS without the client 238 --------------------------------------- 239 240 Although the main point of SockJS is to enable browser-to-server 241 connectivity, it is possible to connect to SockJS from an external 242 application. Any SockJS server complying with 0.3 protocol does 243 support a raw WebSocket url. The raw WebSocket url for the test server 244 looks like: 245 246 * ws://localhost:8081/echo/websocket 247 248 You can connect any WebSocket RFC 6455 compliant WebSocket client to 249 this url. This can be a command line client, external application, 250 third party code or even a browser (though I don't know why you would 251 want to do so). 252 253 254 Deployment 255 ---------- 256 257 You should use a version of sockjs-client 258 that supports the protocol used by your server. For example: 259 260 ```html 261 <script src="//cdn.jsdelivr.net/sockjs/1/sockjs.min.js"></script> 262 ``` 263 264 265 For server-side deployment tricks, especially about load balancing and 266 session stickiness, take a look at the 267 [SockJS-node readme](https://github.com/sockjs/sockjs-node#readme). 268 269 270 Development and testing 271 ----------------------- 272 273 SockJS-client needs [node.js](http://nodejs.org/) for running a test 274 server and JavaScript minification. If you want to work on 275 SockJS-client source code, checkout the git repo and follow these 276 steps: 277 278 cd sockjs-client 279 npm install 280 281 To generate JavaScript, run: 282 283 gulp browserify 284 285 To generate minified JavaScript, run: 286 287 gulp browserify:min 288 289 Both commands output into the `build` directory. 290 291 ### Testing 292 293 Once you've compiled the SockJS-client you may want to check if your changes 294 pass all the tests. 295 296 make test-local 297 298 This will start [zuul](https://github.com/defunctzombie/zuul) and a test support server. Open the browser to [http://localhost:9090/_zuul](http://localhost:9090/_zuul) and watch the tests run. 299 300 Browser Quirks 301 -------------- 302 303 There are various browser quirks which we don't intend to address: 304 305 * Pressing ESC in Firefox, before Firefox 20, closes the SockJS connection. For a workaround 306 and discussion see [#18](https://github.com/sockjs/sockjs-client/issues/18). 307 * `jsonp-polling` transport will show a "spinning wheel" (aka. "busy indicator") 308 when sending data. 309 * You can't open more than one SockJS connection to one domain at the 310 same time due to [the browser's limit of concurrent connections](http://stackoverflow.com/questions/985431/max-parallel-http-connections-in-a-browser) 311 (this limit is not counting native WebSocket connections). 312 * Although SockJS is trying to escape any strange Unicode characters 313 (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)) 314 it's advisable to use only valid characters. Using invalid 315 characters is a bit slower, and may not work with SockJS servers 316 that have proper Unicode support. 317 * Having a global function called `onmessage` or such is probably a 318 bad idea, as it could be called by the built-in `postMessage` API. 319 * From SockJS' point of view there is nothing special about 320 SSL/HTTPS. Connecting between unencrypted and encrypted sites 321 should work just fine. 322 * Although SockJS does its best to support both prefix and cookie based 323 sticky sessions, the latter may not work well cross-domain with 324 browsers that don't accept third-party cookies by default (Safari). 325 In order to get around this make sure you're connecting to SockJS 326 from the same parent domain as the main site. For example 327 'sockjs.a.com' is able to set cookies if you're connecting from 328 'www.a.com' or 'a.com'. 329 * Trying to connect from secure "https://" to insecure "http://" is 330 not a good idea. The other way around should be fine. 331 * Long polling is known to cause problems on Heroku, but a 332 [workaround for SockJS is available](https://github.com/sockjs/sockjs-node/issues/57#issuecomment-5242187). 333 * SockJS [websocket transport is more stable over SSL](https://github.com/sockjs/sockjs-client/issues/94). If 334 you're a serious SockJS user then consider using SSL 335 ([more info](http://www.ietf.org/mail-archive/web/hybi/current/msg01605.html)). 336