em-websocket 0.3.8 → 0.4.0

data/CHANGELOG.rdoc

@@ -1,5 +1,18 @@
 = Changelog
 
+== 0.4.0 / ?
+
+- 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:

data/README.md

@@ -7,66 +7,93 @@ EventMachine based, async, Ruby WebSocket server. Take a look at examples direct
 ## Simple server example
 
 ```ruby
-EventMachine.run {
-
-    EventMachine::WebSocket.start(: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'
+
+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
 }
 ```
 
 ## 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
+```
+
+## 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.
+
+## 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.
 
-It is also possible to log all errors when developing by including the `:debug => true` option when initialising the WebSocket connection.
+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
@@ -74,4 +101,4 @@ It is also possible to log all errors when developing by including the `:debug =
 
 # License
 
-The MIT License - Copyright (c) 2009 Ilya Grigorik
+The MIT License - Copyright (c) 2009 Ilya Grigorik

data/examples/echo.rb

@@ -1,8 +1,24 @@
 require File.expand_path('../../lib/em-websocket', __FILE__)
 
-EventMachine::WebSocket.start(:host => "0.0.0.0", :port => 8080, :debug => true) do |ws|
-  ws.onopen    { ws.send "Hello Client!"}
-  ws.onmessage { |msg| ws.send "Pong: #{msg}" }
-  ws.onclose   { puts "WebSocket closed" }
-  ws.onerror   { |e| puts "Error: #{e.message}" }
-end
+EM.run {
+  EM::WebSocket.run(:host => "0.0.0.0", :port => 8080, :debug => false) do |ws|
+    ws.onopen { |handshake|
+      puts "WebSocket opened #{{
+        :path => handshake.path,
+        :query => handshake.query,
+        :origin => handshake.origin,
+      }}"
+
+      ws.send "Hello Client!"
+    }
+    ws.onmessage { |msg|
+      ws.send "Pong: #{msg}"
+    }
+    ws.onclose {
+      puts "WebSocket closed"
+    }
+    ws.onerror { |e|
+      puts "Error: #{e.message}"
+    }
+  end
+}

data/examples/test.html

@@ -1,8 +1,5 @@
 <html>
   <head>
-    <script src='js/swfobject.js'></script>
-    <script src='js/FABridge.js'></script>
-    <script src='js/web_socket.js'></script>
     <script>
       function init() {
         function debug(string) {
@@ -13,8 +10,8 @@
         }
 
         var Socket = "MozWebSocket" in window ? MozWebSocket : WebSocket;
-        var ws = new Socket("ws://localhost:8080/");
-        ws.onmessage = function(evt) { debug("Message: " + evt.data); };
+        var ws = new Socket("ws://localhost:8080/foo/bar?hello=world");
+        ws.onmessage = function(evt) { debug("Received: " + evt.data); };
         ws.onclose = function() { debug("socket closed"); };
         ws.onopen = function() {
           debug("connected...");

data/lib/em-websocket.rb

@@ -4,12 +4,13 @@ require "eventmachine"
 
 %w[
   debugger websocket connection
+  handshake
   handshake75 handshake76 handshake04
   framing76 framing03 framing04 framing05 framing07
   close75 close03 close05 close06
   masking04
   message_processor_03 message_processor_06
-  handler_factory handler handler75 handler76 handler03 handler05 handler06 handler07 handler08 handler13
+  handler handler75 handler76 handler03 handler05 handler06 handler07 handler08 handler13
 ].each do |file|
   require "em-websocket/#{file}"
 end

data/lib/em-websocket/connection.rb

@@ -1,5 +1,3 @@
-require 'addressable/uri'
-
 module EventMachine
   module WebSocket
     class Connection < EventMachine::Connection
@@ -18,8 +16,8 @@ module EventMachine
       def trigger_on_message(msg)
         @onmessage.call(msg) if @onmessage
       end
-      def trigger_on_open
-        @onopen.call if @onopen
+      def trigger_on_open(handshake)
+        @onopen.call(handshake) if @onopen
       end
       def trigger_on_close
         @onclose.call if @onclose
@@ -40,8 +38,8 @@ module EventMachine
         @options = options
         @debug = options[:debug] || false
         @secure = options[:secure] || false
+        @secure_proxy = options[:secure_proxy] || false
         @tls_options = options[:tls_options] || {}
-        @data = ''
 
         debug [:initialize]
       end
@@ -72,11 +70,6 @@ module EventMachine
         else
           dispatch(data)
         end
-      rescue HandshakeError => e
-        debug [:error, e]
-        trigger_on_error(e)
-        # Errors during the handshake require the connection to be aborted
-        abort
       rescue WSProtocolError => e
         debug [:error, e]
         trigger_on_error(e)
@@ -103,18 +96,30 @@ module EventMachine
       def dispatch(data)
         if data.match(/\A<policy-file-request\s*\/>/)
           send_flash_cross_domain_file
-          return false
         else
-          debug [:inbound_headers, data]
-          @data << data
-          @handler = HandlerFactory.build(self, @data, @secure, @debug)
-          unless @handler
-            # The whole header has not been received yet.
-            return false
+          @handshake ||= begin
+            handshake = Handshake.new(@secure || @secure_proxy)
+
+            handshake.callback { |upgrade_response, handler_klass|
+              debug [:accepting_ws_version, handshake.protocol_version]
+              debug [:upgrade_response, upgrade_response]
+              self.send_data(upgrade_response)
+              @handler = handler_klass.new(self, @debug)
+              @handshake = nil
+              trigger_on_open(handshake)
+            }
+
+            handshake.errback { |e|
+              debug [:error, e]
+              trigger_on_error(e)
+              # Handshake errors require the connection to be aborted
+              abort
+            }
+
+            handshake
           end
-          @data = nil
-          @handler.run
-          return true
+
+          @handshake.receive_data(data)
         end
       end
 
@@ -139,7 +144,7 @@ module EventMachine
       # A WebSocketError may be raised if the connection is in an opening or a
       # closing state, or if the passed in data is not valid UTF-8
       #
-      def send(data)
+      def send_text(data)
         # If we're using Ruby 1.9, be pedantic about encodings
         if ENCODING_SUPPORTED
           # Also accept ascii only data in other encodings for convenience
@@ -165,6 +170,18 @@ module EventMachine
         return nil
       end
 
+      alias :send :send_text
+
+      # Send a WebSocket binary frame.
+      #
+      def send_binary(data)
+        if @handler
+          @handler.send_frame(:binary, data)
+        else
+          raise WebSocketError, "Cannot send binary before onopen callback"
+        end
+      end
+
       # Send a ping to the client. The client must respond with a pong.
       #
       # In the case that the client is running a WebSocket draft < 01, false
@@ -202,10 +219,6 @@ module EventMachine
         end
       end
 
-      def request
-        @handler ? @handler.request : {}
-      end
-
       def state
         @handler ? @handler.state : :handshake
       end

data/lib/em-websocket/handler.rb

@@ -1,26 +1,44 @@
 module EventMachine
   module WebSocket
     class Handler
+      def self.klass_factory(version)
+        handler_klass = case version
+        when 75
+          Handler75
+        when 76
+          Handler76
+        when 1..3
+          # We'll use handler03 - I believe they're all compatible
+          Handler03
+        when 5
+          Handler05
+        when 6
+          Handler06
+        when 7
+          Handler07
+        when 8
+          # drafts 9, 10, 11 and 12 should never change the version
+          # number as they are all the same as version 08.
+          Handler08
+        when 13
+          # drafts 13 to 17 all identify as version 13 as they are
+          # only minor changes or text changes.
+          Handler13
+        else
+          # According to spec should abort the connection
+          raise HandshakeError, "Protocol version #{version} not supported"
+        end
+      end
+
       include Debugger
 
       attr_reader :request, :state
 
-      def initialize(connection, request, debug = false)
-        @connection, @request = connection, request
+      def initialize(connection, debug = false)
+        @connection = connection
         @debug = debug
-        @state = :handshake
-        initialize_framing
-      end
-
-      def run
-        @connection.send_data handshake
         @state = :connected
-        @connection.trigger_on_open
-      end
-
-      # Handshake response
-      def handshake
-        # Implemented in subclass
+        initialize_framing
       end
 
       def receive_data(data)

data/lib/em-websocket/handler03.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler03 < Handler
-      include Handshake76
       include Framing03
       include MessageProcessor03
       include Close03

data/lib/em-websocket/handler05.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler05 < Handler
-      include Handshake04
       include Framing05
       include MessageProcessor03
       include Close05

data/lib/em-websocket/handler06.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler06 < Handler
-      include Handshake04
       include Framing05
       include MessageProcessor06
       include Close06

data/lib/em-websocket/handler07.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler07 < Handler
-      include Handshake04
       include Framing07
       include MessageProcessor06
       include Close06

data/lib/em-websocket/handler08.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler08 < Handler
-      include Handshake04
       include Framing07
       include MessageProcessor06
       include Close06

data/lib/em-websocket/handler13.rb

@@ -1,7 +1,6 @@
 module EventMachine
   module WebSocket
     class Handler13 < Handler
-      include Handshake04
       include Framing07
       include MessageProcessor06
       include Close06