em-websocket 0.4.0 → 0.5.0

data/CHANGELOG.rdoc

@@ -1,6 +1,21 @@
 = Changelog
 
-== 0.4.0 / ?
+== 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

data/README.md

@@ -31,6 +31,45 @@ EM.run {
 }
 ```
 
+## 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. Pass a `:tls_options` hash containing keys as described in http://eventmachine.rubyforge.org/EventMachine/Connection.html#start_tls-instance_method
@@ -51,6 +90,8 @@ EM::WebSocket.start({
 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.
@@ -101,4 +142,4 @@ Using flash emulation does require some minimal support from em-websocket which
 
 # License
 
-The MIT License - Copyright (c) 2009 Ilya Grigorik
+The MIT License - Copyright (c) 2009-2013 Ilya Grigorik, Martyn Loughran

data/examples/test.html

@@ -12,7 +12,9 @@
         var Socket = "MozWebSocket" in window ? MozWebSocket : WebSocket;
         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.onclose = function(event) {
+          debug("Closed - code: " + event.code + ", reason: " + event.reason + ", wasClean: " + event.wasClean);
+        };
         ws.onopen = function() {
           debug("connected...");
           ws.send("hello server");

data/lib/em-websocket/close03.rb

@@ -6,6 +6,8 @@ module EventMachine
         send_frame(:close, '')
         @state = :closing
       end
+
+      def supports_close_codes?; false; end
     end
   end
 end

data/lib/em-websocket/close05.rb

@@ -6,6 +6,8 @@ module EventMachine
         send_frame(:close, "\x53")
         @state = :closing
       end
+
+      def supports_close_codes?; false; end
     end
   end
 end

data/lib/em-websocket/close06.rb

@@ -11,6 +11,8 @@ module EventMachine
         end
         @state = :closing
       end
+
+      def supports_close_codes?; true; end
     end
   end
 end

data/lib/em-websocket/close75.rb

@@ -2,9 +2,10 @@ module EventMachine
   module WebSocket
     module Close75
       def close_websocket(code, body)
-        @state = :closed
         @connection.close_connection_after_writing
       end
+
+      def supports_close_codes?; false; end
     end
   end
 end

data/lib/em-websocket/connection.rb

@@ -14,22 +14,22 @@ module EventMachine
       def onpong(&blk);     @onpong = blk;    end
 
       def trigger_on_message(msg)
-        @onmessage.call(msg) if @onmessage
+        @onmessage.call(msg) if defined? @onmessage
       end
       def trigger_on_open(handshake)
-        @onopen.call(handshake) if @onopen
+        @onopen.call(handshake) if defined? @onopen
       end
-      def trigger_on_close
-        @onclose.call if @onclose
+      def trigger_on_close(event = {})
+        @onclose.call(event) if defined? @onclose
       end
       def trigger_on_ping(data)
-        @onping.call(data) if @onping
+        @onping.call(data) if defined? @onping
       end
       def trigger_on_pong(data)
-        @onpong.call(data) if @onpong
+        @onpong.call(data) if defined? @onpong
       end
       def trigger_on_error(reason)
-        return false unless @onerror
+        return false unless defined? @onerror
         @onerror.call(reason)
         true
       end
@@ -41,23 +41,25 @@ module EventMachine
         @secure_proxy = options[:secure_proxy] || false
         @tls_options = options[:tls_options] || {}
 
+        @handler = nil
+
         debug [:initialize]
       end
 
       # 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(code = nil, body = nil)
-        if code && !(4000..4999).include?(code)
-          raise "Application code may only use codes in the range 4000-4999"
+      def close(code = nil, body = nil)
+        if code && !acceptable_close_code?(code)
+          raise "Application code may only use codes from 1000, 3000-4999"
         end
 
-        # If code not defined then set to 1000 (normal closure)
-        code ||= 1000
-
         close_websocket_private(code, body)
       end
 
+      # Deprecated, to be removed in version 0.6
+      alias :close_websocket :close
+
       def post_init
         start_tls(@tls_options) if @secure
       end
@@ -73,14 +75,16 @@ module EventMachine
       rescue WSProtocolError => e
         debug [:error, e]
         trigger_on_error(e)
-        close_websocket_private(e.code)
+        close_websocket_private(e.code, e.message)
       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)
+        close_websocket_private(3000, "Application error")
+
+        # These are application errors - raise unless onerror defined
+        trigger_on_error(e) || raise(e)
       end
 
       def unbind
@@ -219,6 +223,14 @@ module EventMachine
         end
       end
 
+      def supports_close_codes?
+        if @handler
+          @handler.supports_close_codes?
+        else
+          raise WebSocketError, "Cannot test before onopen callback"
+        end
+      end
+
       def state
         @handler ? @handler.state : :handshake
       end
@@ -232,7 +244,7 @@ module EventMachine
       # correct close code (1009) immediately after receiving the frame header
       #
       def max_frame_size
-        @max_frame_size || WebSocket.max_frame_size
+        defined?(@max_frame_size) ? @max_frame_size : WebSocket.max_frame_size
       end
 
       private
@@ -243,7 +255,7 @@ module EventMachine
         close_connection
       end
 
-      def close_websocket_private(code, body = nil)
+      def close_websocket_private(code, body)
         if @handler
           debug [:closing, code]
           @handler.close_websocket(code, body)
@@ -252,6 +264,19 @@ module EventMachine
           abort
         end
       end
+
+      # Accept 1000, 3xxx or 4xxx
+      #
+      # This is consistent with the spec and what browsers have implemented
+      # Frameworks should use 3xxx while applications should use 4xxx
+      def acceptable_close_code?(code)
+        case code
+        when 1000, (3000..4999)
+          true
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/em-websocket/framing03.rb

@@ -6,6 +6,7 @@ module EventMachine
       def initialize_framing
         @data = ''
         @application_data_buffer = '' # Used for MORE frames
+        @frame_type = nil
       end
       
       def process_data(newdata)
@@ -150,7 +151,7 @@ module EventMachine
       end
 
       def opcode_to_type(opcode)
-        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode")
+        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode #{opcode}")
       end
 
       def data_frame?(type)

data/lib/em-websocket/framing05.rb

@@ -6,6 +6,7 @@ module EventMachine
       def initialize_framing
         @data = MaskedString.new
         @application_data_buffer = '' # Used for MORE frames
+        @frame_type = nil
       end
       
       def process_data(newdata)
@@ -151,7 +152,7 @@ module EventMachine
       end
 
       def opcode_to_type(opcode)
-        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode")
+        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode #{opcode}")
       end
 
       def data_frame?(type)

data/lib/em-websocket/framing07.rb

@@ -7,6 +7,7 @@ module EventMachine
       def initialize_framing
         @data = MaskedString.new
         @application_data_buffer = '' # Used for MORE frames
+        @frame_type = nil
       end
       
       def process_data(newdata)
@@ -162,7 +163,7 @@ module EventMachine
       end
 
       def opcode_to_type(opcode)
-        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode")
+        FRAME_TYPES_INVERSE[opcode] || raise(WSProtocolError, "Unknown opcode #{opcode}")
       end
 
       def data_frame?(type)

data/lib/em-websocket/handler.rb

@@ -2,7 +2,7 @@ module EventMachine
   module WebSocket
     class Handler
       def self.klass_factory(version)
-        handler_klass = case version
+        case version
         when 75
           Handler75
         when 76
@@ -52,7 +52,13 @@ module EventMachine
 
       def unbind
         @state = :closed
-        @connection.trigger_on_close
+
+        @close_info = defined?(@close_info) ? @close_info : {
+          :code => 1006,
+          :was_clean => false,
+        }
+
+        @connection.trigger_on_close(@close_info )
       end
 
       def ping

data/lib/em-websocket/handler76.rb

@@ -1,3 +1,5 @@
+# encoding: BINARY
+
 module EventMachine
   module WebSocket
     class Handler76 < Handler

data/lib/em-websocket/handshake.rb

@@ -24,7 +24,7 @@ module EventMachine
       def receive_data(data)
         @parser << data
 
-        if @headers
+        if defined? @headers
           process(@headers, @parser.upgrade_data)
         end
       rescue HTTP::Parser::Error => e
@@ -66,6 +66,10 @@ module EventMachine
         @headers["origin"] || @headers["sec-websocket-origin"] || nil
       end
 
+      def secure?
+        @secure
+      end
+
       private
 
       def process(headers, remains)

data/lib/em-websocket/handshake04.rb

@@ -10,11 +10,6 @@ module EventMachine
           raise HandshakeError, "sec-websocket-key header is required"
         end
 
-        # Optional
-        origin = headers['sec-websocket-origin']
-        protocols = headers['sec-websocket-protocol']
-        extensions = headers['sec-websocket-extensions']
-
         string_to_sign = "#{key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
         signature = Base64.encode64(Digest::SHA1.digest(string_to_sign)).chomp
 

data/lib/em-websocket/masking04.rb

@@ -15,12 +15,8 @@ module EventMachine
         @masking_key = nil
       end
 
-      def slice_mask
-        slice!(0, 4)
-      end
-
       def getbyte(index)
-        if @masking_key
+        if defined?(@masking_key) && @masking_key
           masked_char = super
           masked_char ? masked_char ^ @masking_key.getbyte(index % 4) : nil
         else

data/lib/em-websocket/message_processor_03.rb

@@ -6,17 +6,20 @@ module EventMachine
       def message(message_type, extension_data, application_data)
         case message_type
         when :close
+          @close_info = {
+            :code => 1005,
+            :reason => "",
+            :was_clean => true,
+          }
           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

data/lib/em-websocket/message_processor_06.rb

@@ -19,18 +19,22 @@ module EventMachine
           
           debug [:close_frame_received, status_code, application_data]
           
+          @close_info = {
+            :code => status_code || 1005,
+            :reason => application_data,
+            :was_clean => true,
+          }
+
           if @state == :closing
             # We can close connection immediately since no more data may be
             # sent or received on this connection
             @connection.close_connection
-            @state = :closed
-          else
-            # Acknowlege close
+          elsif @state == :connected
+            # Acknowlege close & echo status back to client
             # The connection is considered closed
-            send_frame(:close, '')
-            @state = :closed
+            close_data = [status_code || 1000].pack('n')
+            send_frame(:close, close_data)
             @connection.close_connection_after_writing
-            # TODO: Send close status code and body to app code
           end
         when :ping
           # Pong back the same data
@@ -41,6 +45,9 @@ module EventMachine
         when :text
           if application_data.respond_to?(:force_encoding)
             application_data.force_encoding("UTF-8")
+            unless application_data.valid_encoding?
+              raise InvalidDataError, "Invalid UTF8 data"
+            end
           end
           @connection.trigger_on_message(application_data)
         when :binary