sonixlabs-em-websocket 0.3.8 → 0.5.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f123929d5bba3aae574ce13838da5a2da5618d68
+  data.tar.gz: f1c22e421235bd30754318281f984b10ac3fb615
+SHA512:
+  metadata.gz: 40a883e6e61d44f768780be9e5348b8d26c249adb4fcf039bed85a2d03eb81f0fbb41aeb8c8e97389f336418610c7f46ff6535219308c3cc92aa428d42d2f508
+  data.tar.gz: 3df7b288f64f260c3cf8c03c20cf19747a9950686d6c7da08ddef124fde6c742461ec992e27f9d0bb6949573b852eada0cc932979c3fd0432dc65c2756cc4de1

data/CHANGELOG.rdoc

@@ -1,5 +1,74 @@
 = Changelog
 
+== 0.5.1 / 2014-04-23
+
+- new features:
+  - Support for receiving binary messages
+
+- changed:
+  - Allow additional close codes to be sent by apps
+  - Raise better errors on missing Sec-WebSocket-Key2
+  - Updated http_parser.rb dependency to 0.6.0
+
+- bug fixes:
+  - Abort if HTTP request URI is invalid
+  - Force close connections that have been sent a close handshake after a timeout
+
+- improved spec compliance on:
+  - Missing continuation frames
+  - Fragmented control frames
+  - Close behaviour after protocol errors
+
+== 0.5.0 / 2013-03-05
+
+- new features:
+  - onclose handler is now passed a hash containing  was_clean (set to true in drafts 03 and above when a connection is closed with a closing handshake, either by the server or the client), the close code, and reason (drafts 06 and above). Close code 1005 indicates that no code was supplied, and 1006 that the connection was closed abnormally.
+  - use Connection#support_close_codes? to easily check whether close codes are supported by the WebSocket protocol (drafts 06 and above)
+  - closes connection with 1007 close code if text frame contains invalid UTF8
+  - added Handshake#secure? for checking whether the connection is secure (either ssl or behind an ssl proxy)
+
+- changed:
+  - Defaults to sending no close code rather than 1000 (consistent with browsers)
+  - Allows sending a 3xxx close code
+  - Renamed Connection#close_websocket to Connection#close (again for consistency with browsers). Old method is available till 0.6.
+  - Sends reasons with internally generated closure (previously only sent code)
+  - Echos close code when replying to close handshake
+
+== 0.4.0 / 2013-01-22
+
+- new features:
+  - on_open handler is now passed a handshake object which exposes the request headers, path, and query parameters
+  - Easily access the protocol version via Handshake#protocol_version
+  - Easily access the origin via Handshake#origin
+
+- changed:
+  - Removed Connection#request - change to using handshake passed to on_open
+
+- internals:
+  - Uses the http_parser.rb gem
+
+== 0.3.8 / 2012-07-12
+
+- bug fixes:
+  - Fixed support for Ruby 1.8.7 which was broken in 0.3.7
+
+== 0.3.7 / 2012-07-11
+
+- new features:
+  - Supports sending 1009 error code when incoming frame is too large to handle, and added associated exception class WSMessageTooBigError [Martyn Loughran]
+  - Supports overriding the maximum frame size by setting the max_frame_size accessor on the connection object (in bytes). Default unchanged at 10MB. [Martyn Loughran]
+
+- bug fixes:
+  - Fixes some encoding issues on Ruby 1.9 [Dingding Ye]
+  - Raises a HandshakeError if WS header is empty [Markus Fenske]
+  - Connection#send would mutate passed string to BINARY encoding. The fix still mutates the string by forcing the encoding back to UTF-8 before returning, but if the passed string was encoded as UTF-8 this is equivalent [Martyn Loughran]
+
+== 0.3.6 / 2011-12-23
+
+- new features:
+  - Supports sending ping & pong messages
+  - Supports binding to received ping & pong messages
+
 == 0.3.5 / 2011-10-24
 
 - new features:

data/Gemfile

@@ -1,3 +1,9 @@
 source "http://rubygems.org"
 
 gemspec
+
+gem "em-websocket-client", git: "git@github.com:movitto/em-websocket-client.git", branch: "expose-websocket-api"
+gem "em-spec", "~> 0.2.6"
+gem "em-http-request", "~> 1.1.1"
+gem "rspec", "~> 2.12.0"
+gem "rake"

data/LICENCE

@@ -0,0 +1,7 @@
+Copyright (c) 2009-2014 Ilya Grigorik, Martyn Loughran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,98 +1,142 @@
 # EM-WebSocket
 
-EventMachine based, async, Ruby WebSocket server and client. Take a look at examples directory, or check out the blog post below:
+[![Gem Version](https://badge.fury.io/rb/em-websocket.png)](http://rubygems.org/gems/em-websocket)
+[![Analytics](https://ga-beacon.appspot.com/UA-71196-10/em-websocket/readme)](https://github.com/igrigorik/ga-beacon)
 
-* [Ruby & Websockets: TCP for the Web](http://www.igvita.com/2009/12/22/ruby-websockets-tcp-for-the-browser/)
+EventMachine based, async, Ruby WebSocket server. Take a look at examples directory, or check out the blog post: [Ruby & Websockets: TCP for the Web](http://www.igvita.com/2009/12/22/ruby-websockets-tcp-for-the-browser/).
 
 ## Simple server example
 
 ```ruby
-EventMachine.run {
-
-    EventMachine::WebSocket.start_ws_server(:host => "0.0.0.0", :port => 8080) do |ws|
-        ws.onopen {
-          puts "WebSocket connection open"
-
-          # publish message to the client
-          ws.send "Hello Client"
-        }
-
-        ws.onclose { puts "Connection closed" }
-        ws.onmessage { |msg|
-          puts "Recieved message: #{msg}"
-          ws.send "Pong: #{msg}"
-        }
-    end
-}
-```
+require 'em-websocket'
 
-## Simple client example
+EM.run {
+  EM::WebSocket.run(:host => "0.0.0.0", :port => 8080) do |ws|
+    ws.onopen { |handshake|
+      puts "WebSocket connection open"
 
-```ruby
-EventMachine.run {
+      # Access properties on the EM::WebSocket::Handshake object, e.g.
+      # path, query_string, origin, headers
 
-    EventMachine::WebSocket.start_ws_client(:host => "echo.websocket.org", :port => 80) do |ws|
-        ws.onopen {
-          puts "WebSocket client connection open"
+      # Publish message to the client
+      ws.send "Hello Client, you connected to #{handshake.path}"
+    }
 
-          # publish message to the server
-          ws.send "Hello server", :text
-        }
+    ws.onclose { puts "Connection closed" }
 
-        ws.onclose { puts "Connection closed" }
-        ws.onmessage{ |msg, type|
-          puts "Received message: #{msg}"
-        }
-    end
+    ws.onmessage { |msg|
+      puts "Recieved message: #{msg}"
+      ws.send "Pong: #{msg}"
+    }
+  end
 }
 ```
 
+## Protocols supported, and protocol specific functionality
+
+Supports all WebSocket protocols in use in the wild (and a few that are not): drafts 75, 76, 1-17, rfc.
+
+While some of the changes between protocols are unimportant from the point of view of application developers, a few drafts did introduce new functionality. It's possible to easily test for this functionality by using
+
+### Ping & pong supported
+
+Call `ws.pingable?` to check whether ping & pong is supported by the protocol in use.
+
+It's possible to send a ping frame (`ws.ping(body = '')`), which the client must respond to with a pong, or the server can send an unsolicited pong frame (`ws.pong(body = '')`) which the client should not respond to. These methods can be used regardless of protocol version; they return true if the protocol supports ping&pong or false otherwise.
+
+When receiving a ping, the server will automatically respond with a pong as the spec requires (so you should _not_ write an onping handler that replies with a pong), however it is possible to bind to ping & pong events if desired by using the `onping` and `onpong` methods.
+
+### Close codes and reasons
+
+A WebSocket connection can be closed cleanly, regardless of protocol, by calling `ws.close(code = nil, body = nil)`.
+
+Early protocols just close the TCP connection, draft 3 introduced a close handshake, and draft 6 added close codes and reasons to the close handshake. Call `ws.supports_close_codes?` to check whether close codes are supported (i.e. the protocol version is 6 or above).
+
+The `onclose` callback is passed a hash which may contain following keys (depending on the protocol version):
+
+* `was_clean`: boolean indicating whether the connection was closed via the close handshake.
+* `code`: the close code. There are two special close codes which the server may set (as defined in the WebSocket spec):
+  * 1005: no code was supplied
+  * 1006: abnormal closure (the same as `was_clean: false`)
+* `reason`: the close reason
+
+Acceptable close codes are defined in the WebSocket rfc (<http://tools.ietf.org/html/rfc6455#section-7.4>). The following codes can be supplies when calling `ws.close(code)`:
+
+* 1000: a generic normal close
+* range 3xxx: reserved for libraries, frameworks, and applications (and can be registered with IANA)
+* range 4xxx: for private use
+
+If unsure use a code in the 4xxx range. em-websocket may also close a connection with one of the following close codes:
+
+* 1002: WebSocket protocol error.
+* 1009: Message too big to process. By default em-websocket will accept frames up to 10MB in size. If a frame is larger than this the connection will be closed without reading the frame data. The limit can be overriden globally (`EM::WebSocket.max_frame_size = bytes`) or on a specific connection (`ws.max_frame_size = bytes`).
+
 ## Secure server
 
-It is possible to accept secure wss:// connections by passing :secure => true when opening the connection. Safari 5 does not currently support prompting on untrusted SSL certificates therefore using signed certificates is highly recommended. Pass a :tls_options hash containing keys as described in http://eventmachine.rubyforge.org/EventMachine/Connection.html#M000296
+It is possible to accept secure `wss://` connections by passing `:secure => true` when opening the connection. Pass a `:tls_options` hash containing keys as described in http://eventmachine.rubyforge.org/EventMachine/Connection.html#start_tls-instance_method
 
-For example,
+**Warning**: Safari 5 does not currently support prompting on untrusted SSL certificates therefore using a self signed certificate may leave you scratching your head.
 
 ```ruby
-EventMachine::WebSocket.start({
-    :host => "0.0.0.0",
-    :port => 443
-    :secure => true,
-    :tls_options => {
-      :private_key_file => "/private/key",
-      :cert_chain_file => "/ssl/certificate"
-    }
+EM::WebSocket.start({
+  :host => "0.0.0.0",
+  :port => 443,
+  :secure => true,
+  :tls_options => {
+    :private_key_file => "/private/key",
+    :cert_chain_file => "/ssl/certificate"
+  }
+}) do |ws|
+  # ...
+end
+```
+
+It's possible to check whether an incoming connection is secure by reading `handshake.secure?` in the onopen callback.
+
+## Running behind an SSL Proxy/Terminator, like Stunnel
+
+The `:secure_proxy => true` option makes it possible to use em-websocket behind a secure SSL proxy/terminator like [Stunnel](http://www.stunnel.org/) which does the actual encryption & decryption.
+
+Note that this option is only required to support drafts 75 & 76 correctly (e.g. Safari 5.1.x & earlier, and Safari on iOS 5.x & earlier).
+
+```ruby
+EM::WebSocket.start({
+  :host => "0.0.0.0",
+  :port => 8080,
+  :secure_proxy => true
 }) do |ws|
-...
+  # ...
 end
 ```
 
 ## Handling errors
 
-There are two kinds of errors that need to be handled - errors caused by incompatible WebSocket clients sending invalid data and errors in application code. They are handled as follows:
+There are two kinds of errors that need to be handled -- WebSocket protocol errors and errors in application code.
 
-Errors caused by invalid WebSocket data (for example invalid errors in the WebSocket handshake or invalid message frames) raise errors which descend from `EventMachine::WebSocket::WebSocketError`. Such errors are rescued internally and the WebSocket connection will be closed immediately or an error code sent to the browser in accordance to the WebSocket specification. However it is possible to be notified in application code on such errors by including an `onerror` callback.
+WebSocket protocol errors (for example invalid data in the handshake or invalid message frames) raise errors which descend from `EM::WebSocket::WebSocketError`. Such errors are rescued internally and the WebSocket connection will be closed immediately or an error code sent to the browser in accordance to the WebSocket specification. It is possible to be notified in application code of such errors by including an `onerror` callback.
 
 ```ruby
 ws.onerror { |error|
-  if e.kind_of?(EM::WebSocket::WebSocketError)
-    ...
+  if error.kind_of?(EM::WebSocket::WebSocketError)
+    # ...
   end
 }
 ```
 
-Application errors are treated differently. If no `onerror` callback has been defined these errors will propagate to the EventMachine reactor, typically causing your program to terminate. If you wish to handle exceptions, simply supply an `onerror callback` and check for exceptions which are not decendant from `EventMachine::WebSocket::WebSocketError`.
+Application errors are treated differently. If no `onerror` callback has been defined these errors will propagate to the EventMachine reactor, typically causing your program to terminate. If you wish to handle exceptions, simply supply an `onerror callback` and check for exceptions which are not descendant from `EM::WebSocket::WebSocketError`.
+
+It is also possible to log all errors when developing by including the `:debug => true` option when initialising the WebSocket server.
 
-It is also possible to log all errors when developing by including the `:debug => true` option when initialising the WebSocket connection.
+## Emulating WebSockets in older browsers
+
+It is possible to emulate WebSockets in older browsers using flash emulation. For example take a look at the [web-socket-js](https://github.com/gimite/web-socket-js) project.
+
+Using flash emulation does require some minimal support from em-websocket which is enabled by default. If flash connects to the WebSocket port and requests a policy file (which it will do if it fails to receive a policy file on port 843 after a timeout), em-websocket will return one. Also see <https://github.com/igrigorik/em-websocket/issues/61> for an example policy file server which you can run on port 843.
 
 ## Examples & Projects using em-websocket
 
-* [Pusher](http://pusherapp.com) - Realtime client push
+* [Pusher](http://pusher.com) - Realtime Messaging Service
 * [Livereload](https://github.com/mockko/livereload) - LiveReload applies CSS/JS changes to Safari or Chrome w/o reloading
 * [Twitter AMQP WebSocket Example](http://github.com/rubenfonseca/twitter-amqp-websocket-example)
 * examples/multicast.rb - broadcast all ruby tweets to all subscribers
 * examples/echo.rb - server <> client exchange via a websocket
-
-# License
-
-The MIT License - Copyright (c) 2009 Ilya Grigorik

data/README.md.BACKUP.14928.md

@@ -0,0 +1,195 @@
+# EM-WebSocket
+
+<<<<<<< HEAD
+EventMachine based, async, Ruby WebSocket server and client. Take a look at examples directory, or check out the blog post below:
+=======
+[![Gem Version](https://badge.fury.io/rb/em-websocket.png)](http://rubygems.org/gems/em-websocket)
+[![Analytics](https://ga-beacon.appspot.com/UA-71196-10/em-websocket/readme)](https://github.com/igrigorik/ga-beacon)
+>>>>>>> upstream/master
+
+EventMachine based, async, Ruby WebSocket server. Take a look at examples directory, or check out the blog post: [Ruby & Websockets: TCP for the Web](http://www.igvita.com/2009/12/22/ruby-websockets-tcp-for-the-browser/).
+
+## Simple server example
+
+```ruby
+<<<<<<< HEAD
+EventMachine.run {
+
+    EventMachine::WebSocket.start_ws_server(:host => "0.0.0.0", :port => 8080) do |ws|
+        ws.onopen {
+          puts "WebSocket connection open"
+
+          # publish message to the client
+          ws.send "Hello Client"
+        }
+
+        ws.onclose { puts "Connection closed" }
+        ws.onmessage { |msg|
+          puts "Recieved message: #{msg}"
+          ws.send "Pong: #{msg}"
+        }
+    end
+}
+```
+
+## Simple client example
+
+```ruby
+EventMachine.run {
+
+    EventMachine::WebSocket.start_ws_client(:host => "echo.websocket.org", :port => 80) do |ws|
+        ws.onopen {
+          puts "WebSocket client connection open"
+
+          # publish message to the server
+          ws.send "Hello server", :text
+        }
+
+        ws.onclose { puts "Connection closed" }
+        ws.onmessage{ |msg, type|
+          puts "Received message: #{msg}"
+        }
+    end
+}
+```
+=======
+require 'em-websocket'
+
+EM.run {
+  EM::WebSocket.run(:host => "0.0.0.0", :port => 8080) do |ws|
+    ws.onopen { |handshake|
+      puts "WebSocket connection open"
+
+      # Access properties on the EM::WebSocket::Handshake object, e.g.
+      # path, query_string, origin, headers
+
+      # Publish message to the client
+      ws.send "Hello Client, you connected to #{handshake.path}"
+    }
+
+    ws.onclose { puts "Connection closed" }
+
+    ws.onmessage { |msg|
+      puts "Recieved message: #{msg}"
+      ws.send "Pong: #{msg}"
+    }
+  end
+}
+```
+
+## Protocols supported, and protocol specific functionality
+
+Supports all WebSocket protocols in use in the wild (and a few that are not): drafts 75, 76, 1-17, rfc.
+
+While some of the changes between protocols are unimportant from the point of view of application developers, a few drafts did introduce new functionality. It's possible to easily test for this functionality by using
+
+### Ping & pong supported
+
+Call `ws.pingable?` to check whether ping & pong is supported by the protocol in use.
+
+It's possible to send a ping frame (`ws.ping(body = '')`), which the client must respond to with a pong, or the server can send an unsolicited pong frame (`ws.pong(body = '')`) which the client should not respond to. These methods can be used regardless of protocol version; they return true if the protocol supports ping&pong or false otherwise.
+
+When receiving a ping, the server will automatically respond with a pong as the spec requires (so you should _not_ write an onping handler that replies with a pong), however it is possible to bind to ping & pong events if desired by using the `onping` and `onpong` methods.
+
+### Close codes and reasons
+
+A WebSocket connection can be closed cleanly, regardless of protocol, by calling `ws.close(code = nil, body = nil)`.
+
+Early protocols just close the TCP connection, draft 3 introduced a close handshake, and draft 6 added close codes and reasons to the close handshake. Call `ws.supports_close_codes?` to check whether close codes are supported (i.e. the protocol version is 6 or above).
+
+The `onclose` callback is passed a hash which may contain following keys (depending on the protocol version):
+
+* `was_clean`: boolean indicating whether the connection was closed via the close handshake.
+* `code`: the close code. There are two special close codes which the server may set (as defined in the WebSocket spec):
+  * 1005: no code was supplied
+  * 1006: abnormal closure (the same as `was_clean: false`)
+* `reason`: the close reason
+
+Acceptable close codes are defined in the WebSocket rfc (<http://tools.ietf.org/html/rfc6455#section-7.4>). The following codes can be supplies when calling `ws.close(code)`:
+
+* 1000: a generic normal close
+* range 3xxx: reserved for libraries, frameworks, and applications (and can be registered with IANA)
+* range 4xxx: for private use
+
+If unsure use a code in the 4xxx range. em-websocket may also close a connection with one of the following close codes:
+
+* 1002: WebSocket protocol error.
+* 1009: Message too big to process. By default em-websocket will accept frames up to 10MB in size. If a frame is larger than this the connection will be closed without reading the frame data. The limit can be overriden globally (`EM::WebSocket.max_frame_size = bytes`) or on a specific connection (`ws.max_frame_size = bytes`).
+>>>>>>> upstream/master
+
+## Secure server
+
+It is possible to accept secure `wss://` connections by passing `:secure => true` when opening the connection. Pass a `:tls_options` hash containing keys as described in http://eventmachine.rubyforge.org/EventMachine/Connection.html#start_tls-instance_method
+
+**Warning**: Safari 5 does not currently support prompting on untrusted SSL certificates therefore using a self signed certificate may leave you scratching your head.
+
+```ruby
+EM::WebSocket.start({
+  :host => "0.0.0.0",
+  :port => 443,
+  :secure => true,
+  :tls_options => {
+    :private_key_file => "/private/key",
+    :cert_chain_file => "/ssl/certificate"
+  }
+}) do |ws|
+  # ...
+end
+```
+
+It's possible to check whether an incoming connection is secure by reading `handshake.secure?` in the onopen callback.
+
+## Running behind an SSL Proxy/Terminator, like Stunnel
+
+The `:secure_proxy => true` option makes it possible to use em-websocket behind a secure SSL proxy/terminator like [Stunnel](http://www.stunnel.org/) which does the actual encryption & decryption.
+
+Note that this option is only required to support drafts 75 & 76 correctly (e.g. Safari 5.1.x & earlier, and Safari on iOS 5.x & earlier).
+
+```ruby
+EM::WebSocket.start({
+  :host => "0.0.0.0",
+  :port => 8080,
+  :secure_proxy => true
+}) do |ws|
+  # ...
+end
+```
+
+## Handling errors
+
+There are two kinds of errors that need to be handled -- WebSocket protocol errors and errors in application code.
+
+WebSocket protocol errors (for example invalid data in the handshake or invalid message frames) raise errors which descend from `EM::WebSocket::WebSocketError`. Such errors are rescued internally and the WebSocket connection will be closed immediately or an error code sent to the browser in accordance to the WebSocket specification. It is possible to be notified in application code of such errors by including an `onerror` callback.
+
+```ruby
+ws.onerror { |error|
+  if error.kind_of?(EM::WebSocket::WebSocketError)
+    # ...
+  end
+}
+```
+
+Application errors are treated differently. If no `onerror` callback has been defined these errors will propagate to the EventMachine reactor, typically causing your program to terminate. If you wish to handle exceptions, simply supply an `onerror callback` and check for exceptions which are not descendant from `EM::WebSocket::WebSocketError`.
+
+It is also possible to log all errors when developing by including the `:debug => true` option when initialising the WebSocket server.
+
+## Emulating WebSockets in older browsers
+
+It is possible to emulate WebSockets in older browsers using flash emulation. For example take a look at the [web-socket-js](https://github.com/gimite/web-socket-js) project.
+
+Using flash emulation does require some minimal support from em-websocket which is enabled by default. If flash connects to the WebSocket port and requests a policy file (which it will do if it fails to receive a policy file on port 843 after a timeout), em-websocket will return one. Also see <https://github.com/igrigorik/em-websocket/issues/61> for an example policy file server which you can run on port 843.
+
+## Examples & Projects using em-websocket
+
+* [Pusher](http://pusher.com) - Realtime Messaging Service
+* [Livereload](https://github.com/mockko/livereload) - LiveReload applies CSS/JS changes to Safari or Chrome w/o reloading
+* [Twitter AMQP WebSocket Example](http://github.com/rubenfonseca/twitter-amqp-websocket-example)
+* examples/multicast.rb - broadcast all ruby tweets to all subscribers
+* examples/echo.rb - server <> client exchange via a websocket
+<<<<<<< HEAD
+
+# License
+
+The MIT License - Copyright (c) 2009 Ilya Grigorik
+=======
+>>>>>>> upstream/master