source: trip-planner-front/node_modules/sockjs-client/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

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