RubyGems - em-websocket - Versions diffs - 0.2.1 → 0.3.0 - Mend

em-websocket 0.2.1 → 0.3.0

Files changed (39) hide show

data/CHANGELOG.rdoc +10 -0
data/README.md +16 -0
data/examples/test.html +11 -8
data/lib/em-websocket.rb +6 -3
data/lib/em-websocket/close03.rb +11 -0
data/lib/em-websocket/close05.rb +11 -0
data/lib/em-websocket/close06.rb +16 -0
data/lib/em-websocket/close75.rb +10 -0
data/lib/em-websocket/connection.rb +58 -32
data/lib/em-websocket/framing03.rb +9 -30
data/lib/em-websocket/framing04.rb +15 -0
data/lib/em-websocket/framing05.rb +157 -0
data/lib/em-websocket/framing76.rb +5 -6
data/lib/em-websocket/handler.rb +2 -4
data/lib/em-websocket/handler03.rb +2 -6
data/lib/em-websocket/handler05.rb +10 -0
data/lib/em-websocket/handler06.rb +10 -0
data/lib/em-websocket/handler75.rb +1 -0
data/lib/em-websocket/handler76.rb +1 -0
data/lib/em-websocket/handler_factory.rb +41 -22
data/lib/em-websocket/handshake04.rb +35 -0
data/lib/em-websocket/handshake75.rb +4 -4
data/lib/em-websocket/handshake76.rb +8 -8
data/lib/em-websocket/masking04.rb +27 -0
data/lib/em-websocket/message_processor_03.rb +33 -0
data/lib/em-websocket/message_processor_06.rb +46 -0
data/lib/em-websocket/version.rb +1 -1
data/spec/helper.rb +54 -2
data/spec/integration/common_spec.rb +115 -0
data/spec/integration/draft03_spec.rb +26 -11
data/spec/integration/draft05_spec.rb +45 -0
data/spec/integration/draft06_spec.rb +79 -0
data/spec/integration/draft75_spec.rb +115 -0
data/spec/integration/draft76_spec.rb +25 -10
data/spec/integration/shared_examples.rb +62 -0
data/spec/unit/framing_spec.rb +55 -0
data/spec/unit/masking_spec.rb +18 -0
metadata +29 -33
data/spec/websocket_spec.rb +0 -210

data/CHANGELOG.rdoc CHANGED

@@ -1,5 +1,15 @@
 = Changelog
+== 0.3.0 / 2011-05-06
+- new features:
+  - Support WebSocket drafts 05 & 06
+- changes:
+  - Accept request headers in a case insensitive manner
+  - Change handling of errors. Previously some application errors were caught
+    internally and were invisible unless an onerror callback was supplied. See
+    readme for details
 == 0.2.1 / 2011-03-01
 - bugfixes:

data/README.md CHANGED

@@ -42,6 +42,22 @@ For example,
     ...
     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:
+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.
+    ws.onerror { |error|
+      if e.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`.
+It is also possible to log all errors when developing by including the `:debug => true` option when initialising the WebSocket connection.
 ## Examples & Projects using em-websocket
 * [Pusher](http://pusherapp.com) - Realtime client push

data/examples/test.html CHANGED

@@ -1,26 +1,29 @@
 <html>
   <head>
-    <script src='http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js'></script>
     <script src='js/swfobject.js'></script>
     <script src='js/FABridge.js'></script>
     <script src='js/web_socket.js'></script>
     <script>
-      $(document).ready(function(){
-        function debug(str){ $("#debug").append("<p>" +  str); };
+      function init() {
+        function debug(string) {
+          var element = document.getElementById("debug");
+          var p = document.createElement("p");
+          p.appendChild(document.createTextNode(string));
+          element.appendChild(p);
+        }
         ws = new WebSocket("ws://localhost:8080/");
-        ws.onmessage = function(evt) { $("#msg").append("<p>"+evt.data+"</p>"); };
+        ws.onmessage = function(evt) { debug("Message: " + evt.data); };
         ws.onclose = function() { debug("socket closed"); };
         ws.onopen = function() {
           debug("connected...");
           ws.send("hello server");
           ws.send("hello again");
         };
-      });
+      };
     </script>
   </head>
-  <body>
+  <body onload="init();">
     <div id="debug"></div>
-    <div id="msg"></div>
   </body>
-</html>
+</html>

data/lib/em-websocket.rb CHANGED

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

data/lib/em-websocket/close03.rb ADDED

@@ -0,0 +1,11 @@
+module EventMachine
+  module WebSocket
+    module Close03
+      def close_websocket(code, body)
+        # TODO: Ideally send body data and check that it matches in ack
+        send_frame(:close, '')
+        @state = :closing
+      end
+    end
+  end
+end

data/lib/em-websocket/close05.rb ADDED

@@ -0,0 +1,11 @@
+module EventMachine
+  module WebSocket
+    module Close05
+      def close_websocket(code, body)
+        # TODO: Ideally send body data and check that it matches in ack
+        send_frame(:close, "\x53")
+        @state = :closing
+      end
+    end
+  end
+end

data/lib/em-websocket/close06.rb ADDED

@@ -0,0 +1,16 @@
+module EventMachine
+  module WebSocket
+    module Close06
+      def close_websocket(code, body)
+        if code
+          close_data = [code].pack('n')
+          close_data << body if body
+          send_frame(:close, close_data)
+        else
+          send_frame(:close, '')
+        end
+        @state = :closing
+      end
+    end
+  end
+end

data/lib/em-websocket/close75.rb ADDED

@@ -0,0 +1,10 @@
+module EventMachine
+  module WebSocket
+    module Close75
+      def close_websocket(code, body)
+        @state = :closed
+        @connection.close_connection_after_writing
+      end
+    end
+  end
+end

data/lib/em-websocket/connection.rb CHANGED

@@ -20,6 +20,11 @@ module EventMachine
       def trigger_on_close
         @onclose.call if @onclose
       end
+      def trigger_on_error(reason)
+        return false unless @onerror
+        @onerror.call(reason)
+        true
+      end
       def initialize(options)
         @options = options
@@ -34,13 +39,15 @@ module EventMachine
       # Use this method to close the websocket connection cleanly
       # This sends a close frame and waits for acknowlegement before closing
       # the connection
-      def close_websocket
-        if @handler
-          @handler.close_websocket
-        else
-          # The handshake hasn't completed - should be safe to terminate
-          close_connection
+      def close_websocket(code = nil, body = nil)
+        if code && !(4000..4999).include?(code)
+          raise "Application code may only use codes in the range 4000-4999"
         end
+        # If code not defined then set to 1000 (normal closure)
+        code ||= 1000
+        close_websocket_private(code, body)
       end
       def post_init
@@ -55,12 +62,32 @@ 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 WebSocketError => e
+        debug [:error, e]
+        trigger_on_error(e)
+        close_websocket_private(1002) # 1002 indicates a protocol error
+      rescue => e
+        debug [:error, e]
+        # These are application errors - raise unless onerror defined
+        trigger_on_error(e) || raise(e)
+        # There is no code defined for application errors, so use 3000
+        # (which is reserved for frameworks)
+        close_websocket_private(3000)
       end
       def unbind
         debug [:unbind, :connection]
         @handler.unbind if @handler
+      rescue => e
+        debug [:error, e]
+        # These are application errors - raise unless onerror defined
+        trigger_on_error(e) || raise(e)
       end
       def dispatch(data)
@@ -69,30 +96,18 @@ module EventMachine
           return false
         else
           debug [:inbound_headers, data]
-          begin
-            @data << data
-            @handler = HandlerFactory.build(self, @data, @secure, @debug)
-            unless @handler
-              # The whole header has not been received yet.
-              return false
-            end
-            @data = nil
-            @handler.run
-            return true
-          rescue => e
-            debug [:error, e]
-            process_bad_request(e)
+          @data << data
+          @handler = HandlerFactory.build(self, @data, @secure, @debug)
+          unless @handler
+            # The whole header has not been received yet.
             return false
           end
+          @data = nil
+          @handler.run
+          return true
         end
       end
-      def process_bad_request(reason)
-        @onerror.call(reason) if @onerror
-        send_data "HTTP/1.1 400 Bad request\r\n\r\n"
-        close_connection_after_writing
-      end
       def send_flash_cross_domain_file
         file =  '<?xml version="1.0"?><cross-domain-policy><allow-access-from domain="*" to-ports="*"/></cross-domain-policy>'
         debug [:cross_domain, file]
@@ -105,8 +120,6 @@ module EventMachine
       end
       def send(data)
-        debug [:send, data]
         if @handler
           @handler.send_text_frame(data)
         else
@@ -114,11 +127,6 @@ module EventMachine
         end
       end
-      def close_with_error(message)
-        @onerror.call(message) if @onerror
-        close_connection_after_writing
-      end
       def request
         @handler ? @handler.request : {}
       end
@@ -126,6 +134,24 @@ module EventMachine
       def state
         @handler ? @handler.state : :handshake
       end
+      private
+      # As definited in draft 06 7.2.2, some failures require that the server
+      # abort the websocket connection rather than close cleanly
+      def abort
+        close_connection
+      end
+      def close_websocket_private(code, body = nil)
+        if @handler
+          debug [:closing, code]
+          @handler.close_websocket(code, body)
+        else
+          # The handshake hasn't completed - should be safe to terminate
+          abort
+        end
+      end
     end
   end
 end

data/lib/em-websocket/framing03.rb CHANGED

@@ -3,7 +3,7 @@
 module EventMachine
   module WebSocket
     module Framing03
       def initialize_framing
         @data = ''
         @application_data_buffer = '' # Used for MORE frames
@@ -15,7 +15,7 @@ module EventMachine
         while !error && @data.size > 1
           pointer = 0
-          more = (@data.getbyte(pointer) & 0b10000000) == 0b10000000
+          more = ((@data.getbyte(pointer) & 0b10000000) == 0b10000000) ^ fin
           # Ignoring rsv1-3 for now
           opcode = @data.getbyte(0) & 0b00001111
           pointer += 1
@@ -28,7 +28,7 @@ module EventMachine
           when 127 # Length defined by 8 bytes
             # Check buffer size
             if @data.getbyte(pointer+8-1) == nil
-              debug [:buffer_incomplete, @data.inspect]
+              debug [:buffer_incomplete, @data]
               error = true
               next
             end
@@ -41,7 +41,7 @@ module EventMachine
           when 126 # Length defined by 2 bytes
             # Check buffer size
             if @data.getbyte(pointer+2-1) == nil
-              debug [:buffer_incomplete, @data.inspect]
+              debug [:buffer_incomplete, @data]
               error = true
               next
             end
@@ -55,7 +55,7 @@ module EventMachine
           # Check buffer size
           if @data.getbyte(pointer+payload_length-1) == nil
-            debug [:buffer_incomplete, @data.inspect]
+            debug [:buffer_incomplete, @data]
             error = true
             next
           end
@@ -91,6 +91,8 @@ module EventMachine
       end
       def send_frame(frame_type, application_data)
+        debug [:sending_frame, frame_type, application_data]
         if @state == :closing && data_frame?(frame_type)
           raise WebSocketError, "Cannot send data frame since connection is closing"
         end
@@ -124,31 +126,8 @@ module EventMachine
       private
-      def message(message_type, extension_data, application_data)
-        case message_type
-        when :close
-          if @state == :closing
-            # TODO: Check that message body matches sent data
-            # We can close connection immediately since there is no more data
-            # is allowed to be sent or received on this connection
-            @connection.close_connection
-            @state = :closed
-          else
-            # Acknowlege close
-            # The connection is considered closed
-            send_frame(:close, application_data)
-            @state = :closed
-            @connection.close_connection_after_writing
-          end
-        when :ping
-          # Pong back the same data
-          send_frame(:pong, application_data)
-        when :pong
-          # TODO: Do something. Complete a deferrable established by a ping?
-        when :text, :binary
-          @connection.trigger_on_message(application_data)
-        end
-      end
+      # This allows flipping the more bit to fin for draft 04
+      def fin; false; end
       FRAME_TYPES = {
         :continuation => 0,

data/lib/em-websocket/framing04.rb ADDED

@@ -0,0 +1,15 @@
+# encoding: BINARY
+module EventMachine
+  module WebSocket
+    # The only difference between draft 03 framing and draft 04 framing is
+    # that the MORE bit has been changed to a FIN bit
+    module Framing04
+      include Framing03
+      private
+      def fin; true; end
+    end
+  end
+end

data/lib/em-websocket/framing05.rb ADDED

@@ -0,0 +1,157 @@
+# encoding: BINARY
+module EventMachine
+  module WebSocket
+    module Framing05
+      def initialize_framing
+        @data = MaskedString.new
+        @application_data_buffer = '' # Used for MORE frames
+      end
+      def process_data(newdata)
+        error = false
+        while !error && @data.size > 5 # mask plus first byte present
+          pointer = 0
+          @data.read_mask
+          fin = (@data.getbyte(pointer) & 0b10000000) == 0b10000000
+          # Ignoring rsv1-3 for now
+          opcode = @data.getbyte(pointer) & 0b00001111
+          pointer += 1
+          # Ignoring rsv4
+          length = @data.getbyte(pointer) & 0b01111111
+          pointer += 1
+          payload_length = case length
+          when 127 # Length defined by 8 bytes
+            # Check buffer size
+            if @data.getbyte(pointer+8-1) == nil
+              debug [:buffer_incomplete, @data]
+              error = true
+              next
+            end
+            # Only using the last 4 bytes for now, till I work out how to
+            # unpack 8 bytes. I'm sure 4GB frames will do for now :)
+            l = @data.getbytes(pointer+4, 4).unpack('N').first
+            pointer += 8
+            l
+          when 126 # Length defined by 2 bytes
+            # Check buffer size
+            if @data.getbyte(pointer+2-1) == nil
+              debug [:buffer_incomplete, @data]
+              error = true
+              next
+            end
+            l = @data.getbytes(pointer, 2).unpack('n').first
+            pointer += 2
+            l
+          else
+            length
+          end
+          # Check buffer size
+          if @data.getbyte(pointer+payload_length-1) == nil
+            debug [:buffer_incomplete, @data]
+            error = true
+            next
+          end
+          # Read application data
+          application_data = @data.getbytes(pointer, payload_length)
+          pointer += payload_length
+          # Throw away data up to pointer
+          @data.slice!(0...(pointer + 4))
+          frame_type = opcode_to_type(opcode)
+          if frame_type == :continuation && !@frame_type
+            raise WebSocketError, 'Continuation frame not expected'
+          end
+          if !fin
+            debug [:moreframe, frame_type, application_data]
+            @application_data_buffer << application_data
+            @frame_type = frame_type
+          else
+            # Message is complete
+            if frame_type == :continuation
+              @application_data_buffer << application_data
+              message(@frame_type, '', @application_data_buffer)
+              @application_data_buffer = ''
+              @frame_type = nil
+            else
+              message(frame_type, '', application_data)
+            end
+          end
+        end # end while
+      end
+      def send_frame(frame_type, application_data)
+        debug [:sending_frame, frame_type, application_data]
+        if @state == :closing && data_frame?(frame_type)
+          raise WebSocketError, "Cannot send data frame since connection is closing"
+        end
+        frame = ''
+        opcode = type_to_opcode(frame_type)
+        byte1 = opcode | 0b10000000 # fin bit set, rsv1-3 are 0
+        frame << byte1
+        length = application_data.size
+        if length <= 125
+          byte2 = length # since rsv4 is 0
+          frame << byte2
+        elsif length < 65536 # write 2 byte length
+          frame << 126
+          frame << [length].pack('n')
+        else # write 8 byte length
+          frame << 127
+          frame << [length >> 32, length & 0xFFFFFFFF].pack("NN")
+        end
+        frame << application_data
+        @connection.send_data(frame)
+      end
+      def send_text_frame(data)
+        send_frame(:text, data)
+      end
+      private
+      FRAME_TYPES = {
+        :continuation => 0,
+        :close => 1,
+        :ping => 2,
+        :pong => 3,
+        :text => 4,
+        :binary => 5
+      }
+      FRAME_TYPES_INVERSE = FRAME_TYPES.invert
+      # Frames are either data frames or control frames
+      DATA_FRAMES = [:text, :binary, :continuation]
+      def type_to_opcode(frame_type)
+        FRAME_TYPES[frame_type] || raise("Unknown frame type")
+      end
+      def opcode_to_type(opcode)
+        FRAME_TYPES_INVERSE[opcode] || raise("Unknown opcode")
+      end
+      def data_frame?(type)
+        DATA_FRAMES.include?(type)
+      end
+    end
+  end
+end