em-websocket 0.3.0 → 0.3.1

data/CHANGELOG.rdoc

@@ -1,5 +1,10 @@
 = Changelog
 
+== 0.3.1 / 2011-07-28
+
+- new features:
+  - Support WebSocket drafts 07 & 08
+
 == 0.3.0 / 2011-05-06
 
 - new features:

data/README.md

@@ -6,23 +6,25 @@ EventMachine based, async, Ruby WebSocket server. Take a look at examples direct
 
 ## Simple server example
 
-    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
-    }
+```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
+}
+```
 
 ## Secure server
 
@@ -30,17 +32,19 @@ It is possible to accept secure wss:// connections by passing :secure => true wh
 
 For example,
 
-    EventMachine::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
+```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"
+    }
+}) do |ws|
+...
+end
+```
 
 ## Handling errors
 
@@ -48,11 +52,13 @@ There are two kinds of errors that need to be handled - errors caused by incompa
 
 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
-    }
+```ruby
+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`.
 
@@ -68,25 +74,4 @@ It is also possible to log all errors when developing by including the `:debug =
 
 # License
 
-(The MIT License)
-
-Copyright (c) 2009 Ilya Grigorik
-
-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.
+The MIT License - Copyright (c) 2009 Ilya Grigorik

data/lib/em-websocket/framing03.rb

@@ -146,7 +146,7 @@ module EventMachine
       end
 
       def opcode_to_type(opcode)
-        FRAME_TYPES_INVERSE[opcode] || raise("Unknown opcode")
+        FRAME_TYPES_INVERSE[opcode] || raise(DataError, "Unknown opcode")
       end
 
       def data_frame?(type)

data/lib/em-websocket/framing05.rb

@@ -16,6 +16,7 @@ module EventMachine
           pointer = 0
 
           @data.read_mask
+          pointer += 4
 
           fin = (@data.getbyte(pointer) & 0b10000000) == 0b10000000
           # Ignoring rsv1-3 for now
@@ -67,7 +68,8 @@ module EventMachine
           pointer += payload_length
           
           # Throw away data up to pointer
-          @data.slice!(0...(pointer + 4))
+          @data.unset_mask
+          @data.slice!(0...pointer)
 
           frame_type = opcode_to_type(opcode)
 
@@ -146,7 +148,7 @@ module EventMachine
       end
 
       def opcode_to_type(opcode)
-        FRAME_TYPES_INVERSE[opcode] || raise("Unknown opcode")
+        FRAME_TYPES_INVERSE[opcode] || raise(DataError, "Unknown opcode")
       end
 
       def data_frame?(type)

data/lib/em-websocket/framing07.rb

@@ -0,0 +1,168 @@
+# encoding: BINARY
+
+module EventMachine
+  module WebSocket
+    module Framing07
+      
+      def initialize_framing
+        @data = MaskedString.new
+        @application_data_buffer = '' # Used for MORE frames
+      end
+      
+      def process_data(newdata)
+        error = false
+
+        while !error && @data.size >= 2
+          pointer = 0
+
+          fin = (@data.getbyte(pointer) & 0b10000000) == 0b10000000
+          # Ignoring rsv1-3 for now
+          opcode = @data.getbyte(pointer) & 0b00001111
+          pointer += 1
+
+          mask = (@data.getbyte(pointer) & 0b10000000) == 0b10000000
+          length = @data.getbyte(pointer) & 0b01111111
+          pointer += 1
+
+          # raise WebSocketError, 'Data from client must be masked' unless mask
+
+          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
+
+          # Compute the expected frame length
+          frame_length = pointer + payload_length
+          frame_length += 4 if mask
+
+          # Check buffer size
+          if @data.getbyte(frame_length - 1) == nil
+            debug [:buffer_incomplete, @data]
+            error = true
+            next
+          end
+
+          # Remove frame header
+          @data.slice!(0...pointer)
+          pointer = 0
+
+          # Read application data (unmasked if required)
+          @data.read_mask if mask
+          pointer += 4 if mask
+          application_data = @data.getbytes(pointer, payload_length)
+          pointer += payload_length
+          @data.unset_mask if mask
+          
+          # Throw away data up to pointer
+          @data.slice!(0...pointer)
+
+          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,
+        :text => 1,
+        :binary => 2,
+        :close => 8,
+        :ping => 9,
+        :pong => 10,
+      }
+      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(DataError, "Unknown opcode")
+      end
+
+      def data_frame?(type)
+        DATA_FRAMES.include?(type)
+      end
+    end
+  end
+end

data/lib/em-websocket/handler07.rb

@@ -0,0 +1,10 @@
+module EventMachine
+  module WebSocket
+    class Handler07 < Handler
+      include Handshake04
+      include Framing07
+      include MessageProcessor06
+      include Close06
+    end
+  end
+end

data/lib/em-websocket/handler08.rb

@@ -0,0 +1,10 @@
+module EventMachine
+  module WebSocket
+    class Handler08 < Handler
+      include Handshake04
+      include Framing07
+      include MessageProcessor06
+      include Close06
+    end
+  end
+end

data/lib/em-websocket/handler_factory.rb

@@ -87,6 +87,10 @@ module EventMachine
           Handler05.new(connection, request, debug)
         when 6
           Handler06.new(connection, request, debug)
+        when 7
+          Handler07.new(connection, request, debug)
+        when 8
+          Handler08.new(connection, request, debug)
         else
           # According to spec should abort the connection
           raise WebSocketError, "Protocol version #{version} not supported"

data/lib/em-websocket/masking04.rb

@@ -1,18 +1,31 @@
 module EventMachine
   module WebSocket
     class MaskedString < String
+      # Read a 4 bit XOR mask - further requested bytes will be unmasked
       def read_mask
+        if respond_to?(:encoding) && encoding.name != "ASCII-8BIT"
+          raise "MaskedString only operates on BINARY strings"
+        end
         raise "Too short" if bytesize < 4 # TODO - change
         @masking_key = String.new(self[0..3])
       end
 
+      # Removes the mask, behaves like a normal string again
+      def unset_mask
+        @masking_key = nil
+      end
+
       def slice_mask
         slice!(0, 4)
       end
 
       def getbyte(index)
-        masked_char = super(index + 4)
-        masked_char ? masked_char ^ @masking_key.getbyte(index % 4) : nil
+        if @masking_key
+          masked_char = super
+          masked_char ? masked_char ^ @masking_key.getbyte(index % 4) : nil
+        else
+          super
+        end
       end
 
       def getbytes(start_index, count)

data/lib/em-websocket/version.rb

@@ -1,5 +1,5 @@
 module EventMachine
   module Websocket
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

data/lib/em-websocket.rb

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

data/spec/unit/framing_spec.rb

@@ -161,3 +161,72 @@ describe EM::WebSocket::Framing04 do
     end
   end
 end
+
+describe EM::WebSocket::Framing07 do
+  class FramingContainer07
+    include EM::WebSocket::Framing07
+
+    def <<(data)
+      @data << data
+      process_data(data)
+    end
+
+    def debug(*args); end
+  end
+
+  before :each do
+    @f = FramingContainer07.new
+    @f.initialize_framing
+  end
+
+  # These examples are straight from the spec
+  # http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07#section-4.6
+  describe "examples from the spec" do
+    it "a single-frame unmakedtext message" do
+      @f.should_receive(:message).with(:text, '', 'Hello')
+      @f << "\x81\x05\x48\x65\x6c\x6c\x6f" # "\x84\x05Hello"
+    end
+
+    it "a single-frame masked text message" do
+      @f.should_receive(:message).with(:text, '', 'Hello')
+      @f << "\x81\x85\x37\xfa\x21\x3d\x7f\x9f\x4d\x51\x58" # "\x84\x05Hello"
+    end
+
+    it "a fragmented unmasked text message" do
+      @f.should_receive(:message).with(:text, '', 'Hello')
+      @f << "\x01\x03Hel"
+      @f << "\x80\x02lo"
+    end
+
+    it "Ping request" do
+      @f.should_receive(:message).with(:ping, '', 'Hello')
+      @f << "\x89\x05Hello"
+    end
+
+    it "a pong response" do
+      @f.should_receive(:message).with(:pong, '', 'Hello')
+      @f << "\x8a\x05Hello"
+    end
+
+    it "256 bytes binary message in a single unmasked frame" do
+      data = "a"*256
+      @f.should_receive(:message).with(:binary, '', data)
+      @f << "\x82\x7E\x01\x00" + data
+    end
+
+    it "64KiB binary message in a single unmasked frame" do
+      data = "a"*65536
+      @f.should_receive(:message).with(:binary, '', data)
+      @f << "\x82\x7F\x00\x00\x00\x00\x00\x01\x00\x00" + data
+    end
+  end
+
+  describe "other tests" do
+    it "should raise a DataError if an invalid frame type is requested" do
+      lambda {
+        # Opcode 3 is not supported by this draft
+        @f << "\x83\x05Hello"
+      }.should raise_error(EventMachine::WebSocket::DataError, "Unknown opcode")
+    end
+  end
+end

data/spec/unit/masking_spec.rb

@@ -1,3 +1,5 @@
+# encoding: BINARY
+
 require 'helper'
 
 describe EM::WebSocket::MaskedString do
@@ -5,14 +7,21 @@ describe EM::WebSocket::MaskedString do
     t = EM::WebSocket::MaskedString.new("\x00\x00\x00\x01\x00\x01\x00\x01")
     t.read_mask
     t.getbyte(3).should == 0x00
-    t.getbytes(0, 4).should == "\x00\x01\x00\x00"
-    t.getbytes(1, 3).should ==     "\x01\x00\x00"
+    t.getbytes(4, 4).should == "\x00\x01\x00\x00"
+    t.getbytes(5, 3).should ==     "\x01\x00\x00"
   end
 
   it "should return nil from getbyte if index requested is out of range" do
     t = EM::WebSocket::MaskedString.new("\x00\x00\x00\x00\x53")
     t.read_mask
-    t.getbyte(0).should == 0x53
-    t.getbyte(1).should == nil
+    t.getbyte(4).should == 0x53
+    t.getbyte(5).should == nil
+  end
+  
+  it "should allow switching masking on and off" do
+    t = EM::WebSocket::MaskedString.new("\x02\x00\x00\x00\x03")
+    t.getbyte(4).should == 0x03
+    t.read_mask
+    t.getbyte(4).should == 0x01
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: em-websocket
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Ilya Grigorik
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-06 00:00:00 +01:00
+date: 2011-07-28 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -101,11 +101,14 @@ files:
 - lib/em-websocket/framing03.rb
 - lib/em-websocket/framing04.rb
 - lib/em-websocket/framing05.rb
+- lib/em-websocket/framing07.rb
 - lib/em-websocket/framing76.rb
 - lib/em-websocket/handler.rb
 - lib/em-websocket/handler03.rb
 - lib/em-websocket/handler05.rb
 - lib/em-websocket/handler06.rb
+- lib/em-websocket/handler07.rb
+- lib/em-websocket/handler08.rb
 - lib/em-websocket/handler75.rb
 - lib/em-websocket/handler76.rb
 - lib/em-websocket/handler_factory.rb