PageRenderTime 83ms CodeModel.GetById 30ms app.highlight 15ms RepoModel.GetById 36ms app.codeStats 0ms

/README.md

http://github.com/gimite/web-socket-js
Markdown | 169 lines | 103 code | 66 blank | 0 comment | 0 complexity | 0ffa22b45f8480d1942655a7183128ec MD5 | raw file
  1## How to try the sample
  2
  3Assuming you have Web server (e.g. Apache) running at **http://example.com/** .
  4
  51. Download [web-socket-ruby](http://github.com/gimite/web-socket-ruby/tree/master).
  62. Run sample Web Socket server (echo server) in example.com with: (#1)<br>
  7```
  8$ ruby web-socket-ruby/samples/echo_server.rb example.com 10081
  9```
 103. If your server already provides socket policy file at port **843**, modify the file to allow access to port **10081**. Otherwise you can skip this step. See below for details.
 114. Publish the web-socket-js directory with your Web server (e.g. put it in ~/public_html).
 125. Change ws://localhost:10081 to **ws://example.com:10081** in sample.html.
 136. Open sample.html in your browser.
 147. After "onopen" is shown, input something, click [Send] and confirm echo back.
 15
 16\#1: First argument of echo_server.rb means that it accepts Web Socket connection from HTML pages in example.com.
 17
 18
 19## How to use it in your application
 20
 21- Copy swfobject.js, web_socket.js, WebSocketMain.swf to your application directory.
 22- Write JavaScript code:
 23
 24```html
 25<!-- Import JavaScript Libraries. -->
 26<script type="text/javascript" src="swfobject.js"></script>
 27<script type="text/javascript" src="web_socket.js"></script>
 28
 29<script type="text/javascript">
 30  
 31  // Let the library know where WebSocketMain.swf is:
 32  WEB_SOCKET_SWF_LOCATION = "WebSocketMain.swf";
 33  
 34  // Write your code in the same way as for native WebSocket:
 35  var ws = new WebSocket("ws://example.com:10081/");
 36  ws.onopen = function() {
 37    ws.send("Hello");  // Sends a message.
 38  };
 39  ws.onmessage = function(e) {
 40    // Receives a message.
 41    alert(e.data);
 42  };
 43  ws.onclose = function() {
 44    alert("closed");
 45  };
 46  
 47</script>
 48```
 49
 50- Put Flash socket policy file to your server unless you use web-socket-ruby or em-websocket as your WebSocket server. See "Flash socket policy file" section below for details.
 51
 52
 53## Troubleshooting
 54
 55If it doesn't work, try these:
 56
 571. Try Chrome and IE 8 or 9.
 58
 59   - It doesn't work on Chrome:<br>
 60     It's likely an issue of your code or the server. Debug your code as usual e.g. using console.log.
 61   - It works on Chrome but it doesn't work on IE:<br>
 62     It's likely an issue of web-socket-js specific configuration (e.g. 3 and 4 below).
 63   - It works on both Chrome and IE, but it doesn't work on your browser:<br>
 64     Check "Supported environment" section below. Your browser may not be supported by web-socket-js.
 65
 662. Add this line before your code:
 67       WEB_SOCKET_DEBUG = true;
 68and use Developer Tools (Chrome/Safari) or Firebug (Firefox) to see if console.log outputs any errors.
 69
 703. Make sure you do NOT open your HTML page as local file e.g. file:///.../sample.html. web-socket-js doesn't work on local file. Open it via Web server e.g. http:///.../sample.html.
 71
 724. Make sure you host your HTML page and WebSocketMain.swf in the same domain. Otherwise, see "How to host HTML file and SWF file in different domains" section.
 73
 745. If you are NOT using web-socket-ruby or em-websocket as your WebSocket server, you need to place Flash socket policy file on your server. See "Flash socket policy file" section below for details.
 75
 766. Check if sample.html bundled with web-socket-js works.
 77
 787. Make sure the port used for WebSocket (10081 in example above) is not blocked by your server/client's firewall.
 79
 808. Install [debugger version of Flash Player](http://www.adobe.com/support/flashplayer/downloads.html) to see Flash errors.
 81
 829. If you followed the steps above and you still have an issue, please [report here](https://github.com/gimite/web-socket-js/issues) with these information:
 83
 84   - The WebSocket server library you use (e.g. em-websocket, pywebsocket) and its version
 85   - The Web browser you use and its version
 86   - The exact message you are trying to send from the server or the client
 87   - The result of all steps above, especially error message in step 2 if any
 88
 89
 90## Supported environments
 91
 92It should work on:
 93
 94- Google Chrome 4 or later, Firefox 6 or later (uses native WebSocket or MozWebSocket implementation)
 95- Firefox 3 to 5, Internet Explorer 8, 9 + Flash Player 10 or later
 96
 97It may or may not work on other browsers such as Safari, Opera or IE 6. Patch for these browsers are appreciated, but I will not work on fixing issues specific to these browsers by myself.
 98
 99
100## Limitations/differences compared to native WebSocket
101
102- You need some more lines in your JavaScript code. See "How to use it in your application" section above for details.
103- It requires Flash Player 10 or later unless the browser supports native WebSocket.
104- Your server must provide Flash socket policy file, unless you use web-socket-ruby or em-websocket. See "Flash socket policy file" section below for details.
105- It has limited support for Cookies on WebSocket. See "Cookie support" section below for details.
106- It doesn't use proxies specified in browser config. See "Proxy support" section below for details.
107
108
109### Flash socket policy file
110
111This implementation uses Flash's socket, which means that your server must provide Flash socket policy file to declare the server accepts connections from Flash.
112
113If you use [web-socket-ruby](http://github.com/gimite/web-socket-ruby/tree/master) or [em-websocket](https://github.com/igrigorik/em-websocket), you don't need anything special, because they handle Flash socket policy file request. But if you already provide socket policy file at port **843**, you need to modify the file to allow access to Web Socket port, because it precedes what the libraries provide.
114
115If you use other Web Socket server implementation, you need to provide socket policy file yourself. See [Setting up A Flash Socket Policy File](http://www.lightsphere.com/dev/articles/flash_socket_policy.html) for details. Implementation of socket policy file server is available at:
116
117- The article above (Perl implementation)
118- [Ruby implementation](https://github.com/futurechimp/flash_policy_server)
119- [Node.js implementation](https://github.com/3rd-Eden/FlashPolicyFileServer)
120
121Actually, it's still better to provide socket policy file at port 843 even if you use web-socket-ruby or em-websocket. Flash always try to connect to port 843 first, so providing the file at port 843 makes startup faster.
122
123
124### Cookie support
125
126web-socket-js has limited supported for Cookies on WebSocket.
127
128Cookie is sent if Web Socket host is exactly the same as the origin of JavaScript (The port can be different). Otherwise it is not sent, because I don't know way to send right Cookie (which is Cookie of the host of Web Socket, I heard). Also, HttpOnly Cookies are not sent.
129
130Note that it's technically possible that client sends arbitrary string as Cookie and any other headers (by modifying this library for example) once you place Flash socket policy file in your server. So don't trust Cookie and other headers if you allow connection from untrusted origin.
131
132
133### Proxy support
134
135[The WebSocket spec](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10) specifies instructions for User Agents to support proxied connections by implementing the HTTP CONNECT method.
136
137The AS3 Socket class doesn't implement this mechanism, which renders it useless for the scenarios where the user trying to open a socket is behind a proxy. 
138
139The class RFC2817Socket (by Christian Cantrell) effectively lets us implement this, as long as the proxy settings are known and provided by the interface that instantiates the WebSocket. As such, if you want to support proxied conncetions, you'll have to supply this information to the WebSocket constructor when Flash is being used. One way to go about it would be to ask the user for proxy settings information if the initial connection fails.
140
141
142## How to host HTML file and SWF file in different domains
143
144By default, HTML file and SWF file must be in the same domain. You can follow steps below to allow hosting them in different domain.
145
146**WARNING**: If you use the method below, HTML files in ANY domains can send arbitrary TCP data to your WebSocket server, regardless of configuration in Flash socket policy file. Arbitrary TCP data means that they can even fake request headers including Origin and Cookie.
147
1481. Unzip WebSocketMainInsecure.zip to extract WebSocketMainInsecure.swf.
1492. Put WebSocketMainInsecure.swf on your server, instead of WebSocketMain.swf.
1503. In JavaScript, set WEB_SOCKET_SWF_LOCATION to URL of your WebSocketMainInsecure.swf.
151
152
153## How to build WebSocketMain.swf
154
155Install [Flex 4 SDK](http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4).
156
157    $ cd flash-src
158    $ ./build.sh
159
160
161## WebSocket protocol versions
162
163- web-socket-js speaks WebSocket protocol defined in [RFC 6455](http://tools.ietf.org/html/rfc6455).
164- web-socket-js doesn't speak old draft versions of WebSocket protocol including hixie-76, which was supported by old version of this library. If you really need web-socket-js which speaks hixie-76, you can get it from [hixie-76 branch](https://github.com/gimite/web-socket-js/tree/hixie-76), but the branch is no longer maintained.
165
166
167## License
168
169New BSD License.