websocket 1.0.7 → 1.1.0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.1.0
+
+- allow raising ruby errors instead of setting `error` flag
+- allow access to handshake headers
+- add from_rack method
+- add from_hash method
+- stop extending handlers - it should improve performance for opening connection
+
 ## 1.0.7
 
 - fix requiring url under Ruby 1.9.1

data/Gemfile

@@ -3,3 +3,4 @@ source "http://rubygems.org"
 gemspec
 
 gem 'rake'
+gem 'rspec', '~> 2.11'

data/README.md

@@ -104,6 +104,7 @@ frame.next # "world!""
 
 - [WebSocket-EventMachine-Client](https://github.com/imanel/websocket-eventmachine-client) - client based on EventMachine
 - [WebSocket-EventMachine-Server](https://github.com/imanel/websocket-eventmachine-server) - server based on EventMachine (drop-in replacement for EM-WebSocket)
+- [Selenium-WebDriver](https://rubygems.org/gems/selenium-webdriver) - tool for writing automated tests of websites
 - [Rubame](https://github.com/saward/Rubame) - websocket game server
 
 ## Native extension

data/lib/websocket.rb

@@ -4,15 +4,15 @@
 # @author Bernard "Imanel" Potocki
 # @see http://github.com/imanel/websocket-ruby main repository
 module WebSocket
-  class Error < RuntimeError; end
 
   # Default WebSocket version to use
   DEFAULT_VERSION = 13
   ROOT = File.expand_path(File.dirname(__FILE__))
 
-  autoload :Frame,     "#{ROOT}/websocket/frame"
-  autoload :Handler,   "#{ROOT}/websocket/handler"
-  autoload :Handshake, "#{ROOT}/websocket/handshake"
+  autoload :Error,            "#{ROOT}/websocket/error"
+  autoload :ExceptionHandler, "#{ROOT}/websocket/exception_handler"
+  autoload :Frame,            "#{ROOT}/websocket/frame"
+  autoload :Handshake,        "#{ROOT}/websocket/handshake"
 
   # Limit of frame size payload in bytes
   def self.max_frame_size
@@ -24,6 +24,17 @@ module WebSocket
     @max_frame_size = val
   end
 
+  # If set to true error will be raised instead of setting `error` method.
+  # All errors inherit from WebSocket::Error.
+  def self.should_raise
+    @should_raise ||= false
+  end
+
+  # Should protocol errors raise ruby errors? If false then `error` flag is set instead.
+  def self.should_raise=(val)
+    @should_raise = val
+  end
+
 end
 
 # Try loading websocket-native if available

data/lib/websocket/error.rb

@@ -0,0 +1,85 @@
+module WebSocket
+  class Error < RuntimeError
+
+    class Frame < ::WebSocket::Error
+
+      class ControlFramePayloadTooLong < ::WebSocket::Error::Frame
+        def message; :control_frame_payload_too_long; end
+      end
+
+      class DataFrameInsteadContinuation < ::WebSocket::Error::Frame
+        def message; :data_frame_instead_continuation; end
+      end
+
+      class FragmentedControlFrame < ::WebSocket::Error::Frame
+        def message; :fragmented_control_frame; end
+      end
+
+      class Invalid < ::WebSocket::Error::Frame
+        def message; :invalid_frame; end
+      end
+
+      class InvalidPayloadEncoding < ::WebSocket::Error::Frame
+        def message; :invalid_payload_encoding; end
+      end
+
+      class MaskTooShort < ::WebSocket::Error::Frame
+        def message; :mask_is_too_short; end
+      end
+
+      class ReservedBitUsed < ::WebSocket::Error::Frame
+        def message; :reserved_bit_used; end
+      end
+
+      class TooLong < ::WebSocket::Error::Frame
+        def message; :frame_too_long; end
+      end
+
+      class UnexpectedContinuationFrame < ::WebSocket::Error::Frame
+        def message; :unexpected_continuation_frame; end
+      end
+
+      class UnknownFrameType < ::WebSocket::Error::Frame
+        def message; :unknown_frame_type; end
+      end
+
+      class UnknownOpcode < ::WebSocket::Error::Frame
+        def message; :unknown_opcode; end
+      end
+
+      class UnknownVersion < ::WebSocket::Error::Frame
+        def message; :unknown_protocol_version; end
+      end
+
+    end
+
+    class Handshake < ::WebSocket::Error
+
+      class GetRequestRequired < ::WebSocket::Error::Handshake
+        def message; :get_request_required; end
+      end
+
+      class InvalidAuthentication < ::WebSocket::Error::Handshake
+        def message; :invalid_handshake_authentication; end
+      end
+
+      class InvalidHeader < ::WebSocket::Error::Handshake
+        def message; :invalid_header; end
+      end
+
+      class InvalidStatusCode < ::WebSocket::Error::Handshake
+        def message; :invalid_status_code; end
+      end
+
+      class NoHostProvided < ::WebSocket::Error::Handshake
+        def message; :no_host_provided; end
+      end
+
+      class UnknownVersion < ::WebSocket::Error::Handshake
+        def message; :unknown_protocol_version; end
+      end
+
+    end
+
+  end
+end

data/lib/websocket/exception_handler.rb

@@ -0,0 +1,36 @@
+module WebSocket
+  module ExceptionHandler
+
+    attr_reader :error
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    private
+
+    # Changes state to error and sets error message
+    # @param [String] message Error message to set
+    def set_error(message)
+      @error = message
+    end
+
+    module ClassMethods
+
+      def rescue_method(method_name, options = {})
+        define_method "#{method_name}_with_rescue" do |*args|
+          begin
+            send("#{method_name}_without_rescue", *args)
+          rescue WebSocket::Error => e
+            set_error(e.message.to_sym)
+            WebSocket.should_raise ? raise : options[:return]
+          end
+        end
+        alias_method "#{method_name}_without_rescue", method_name
+        alias_method method_name, "#{method_name}_with_rescue"
+      end
+
+    end
+
+  end
+end

data/lib/websocket/frame/base.rb

@@ -2,8 +2,9 @@ module WebSocket
   module Frame
     # @abstract Subclass and override to implement custom frames
     class Base
+      include ExceptionHandler
 
-      attr_reader :data, :type, :version, :error
+      attr_reader :data, :type, :version
 
       # Initialize frame
       # @param args [Hash] Arguments for frame
@@ -16,8 +17,10 @@ module WebSocket
         @code = args[:code]
         @data = Data.new(args[:data].to_s)
         @version = args[:version] || DEFAULT_VERSION
+        @handler = nil
         include_version
       end
+      rescue_method :initialize
 
       # Check if some errors occured
       # @return [Boolean] True if error is set
@@ -27,7 +30,7 @@ module WebSocket
 
       # Is selected type supported for selected handler?
       def support_type?
-        supported_frames.include?(@type)
+        @handler.supported_frames.include?(@type)
       end
 
       # Implement in submodules
@@ -47,23 +50,17 @@ module WebSocket
       # Include set of methods for selected protocol version
       # @return [Boolean] false if protocol number is unknown, otherwise true
       def include_version
-        case @version
-          when 75..76 then extend Handler::Handler75
-          when 0..2 then extend Handler::Handler75
-          when 3 then extend Handler::Handler03
-          when 4 then extend Handler::Handler04
-          when 5..6 then extend Handler::Handler05
-          when 7..13 then extend Handler::Handler07
-          else set_error(:unknown_protocol_version) and return
+        @handler = case @version
+          when 75..76 then Handler::Handler75.new(self)
+          when 0..2 then Handler::Handler75.new(self)
+          when 3 then Handler::Handler03.new(self)
+          when 4 then Handler::Handler04.new(self)
+          when 5..6 then Handler::Handler05.new(self)
+          when 7..13 then Handler::Handler07.new(self)
+          else raise WebSocket::Error::Frame::UnknownVersion
         end
       end
 
-      # Changes state to error and sets error message
-      # @param [String] message Error message to set
-      def set_error(message)
-        @error = message
-      end
-
     end
   end
 end

data/lib/websocket/frame/data.rb

@@ -11,7 +11,7 @@ module WebSocket
       end
 
       def set_mask
-        raise "Too short" if bytesize < 4 # TODO - change
+        raise WebSocket::Error::Frame::MaskTooShort if bytesize < 4
         @masking_key = self[0..3].bytes.to_a
       end
 

data/lib/websocket/frame/handler/base.rb

@@ -1,9 +1,11 @@
 module WebSocket
   module Frame
     module Handler
-      module Base
+      class Base
 
-        private
+        def initialize(frame)
+          @frame = frame
+        end
 
         # Convert data to raw frame ready to send to client
         # @return [String] Encoded frame
@@ -17,6 +19,8 @@ module WebSocket
           raise NotImplementedError
         end
 
+        private
+
         # Check if frame is one of control frames
         # @param [Symbol] frame_type Frame type
         # @return [Boolean] True if given frame type is control frame

data/lib/websocket/frame/handler/handler03.rb

@@ -3,28 +3,37 @@
 module WebSocket
   module Frame
     module Handler
-      module Handler03
+      class Handler03 < Base
 
-        include Base
+        # Hash of frame names and it's opcodes
+        FRAME_TYPES = {
+          :continuation => 0,
+          :close => 1,
+          :ping => 2,
+          :pong => 3,
+          :text => 4,
+          :binary => 5
+        }
+
+        # Hash of frame opcodes and it's names
+        FRAME_TYPES_INVERSE = FRAME_TYPES.invert
 
         # @see WebSocket::Frame::Base#supported_frames
         def supported_frames
           [:text, :binary, :close, :ping, :pong]
         end
 
-        private
-
         # @see WebSocket::Frame::Handler::Base#encode_frame
         def encode_frame
           frame = ''
 
-          opcode = type_to_opcode(@type)
+          opcode = type_to_opcode(@frame.type)
           byte1 = opcode | (fin ? 0b10000000 : 0b00000000) # since more, rsv1-3 are 0 and 0x80 for Draft 4
           frame << byte1
 
-          mask = outgoing_masking? ? 0b10000000 : 0b00000000
+          mask = @frame.outgoing_masking? ? 0b10000000 : 0b00000000
 
-          length = @data.size
+          length = @frame.data.size
           if length <= 125
             byte2 = length # since rsv4 is 0
             frame << (byte2 | mask)
@@ -36,58 +45,56 @@ module WebSocket
             frame << [length >> 32, length & 0xFFFFFFFF].pack("NN")
           end
 
-          if outgoing_masking?
+          if @frame.outgoing_masking?
             masking_key = [rand(256).chr, rand(256).chr, rand(256).chr, rand(256).chr].join
-            tmp_data = Data.new([masking_key, @data.to_s].join)
+            tmp_data = Data.new([masking_key, @frame.data.to_s].join)
             tmp_data.set_mask
             frame << masking_key + tmp_data.getbytes(4, tmp_data.size)
           else
-            frame << @data
+            frame << @frame.data
           end
 
           frame
-        rescue WebSocket::Error => e
-          set_error(e.message.to_sym) and return
         end
 
         # @see WebSocket::Frame::Handler::Base#decode_frame
         def decode_frame
-          while @data.size > 1
+          while @frame.data.size > 1
             pointer = 0
 
-            more = ((@data.getbyte(pointer) & 0b10000000) == 0b10000000) ^ fin
+            more = ((@frame.data.getbyte(pointer) & 0b10000000) == 0b10000000) ^ fin
 
-            raise(WebSocket::Error, :reserved_bit_used) if @data.getbyte(pointer) & 0b01110000 != 0b00000000
+            raise(WebSocket::Error::Frame::ReservedBitUsed) if @frame.data.getbyte(pointer) & 0b01110000 != 0b00000000
 
-            opcode = @data.getbyte(pointer) & 0b00001111
+            opcode = @frame.data.getbyte(pointer) & 0b00001111
             frame_type = opcode_to_type(opcode)
             pointer += 1
 
-            raise(WebSocket::Error, :fragmented_control_frame) if more && control_frame?(frame_type)
-            raise(WebSocket::Error, :data_frame_instead_continuation) if data_frame?(frame_type) && !@application_data_buffer.nil?
+            raise(WebSocket::Error::Frame::FragmentedControlFrame) if more && control_frame?(frame_type)
+            raise(WebSocket::Error::Frame::DataFrameInsteadContinuation) if data_frame?(frame_type) && !@application_data_buffer.nil?
 
-            mask = incoming_masking? && (@data.getbyte(pointer) & 0b10000000) == 0b10000000
-            length = @data.getbyte(pointer) & 0b01111111
+            mask = @frame.incoming_masking? && (@frame.data.getbyte(pointer) & 0b10000000) == 0b10000000
+            length = @frame.data.getbyte(pointer) & 0b01111111
 
-            raise(WebSocket::Error, :control_frame_payload_too_long) if length > 125 && control_frame?(frame_type)
+            raise(WebSocket::Error::Frame::ControlFramePayloadTooLong) if length > 125 && control_frame?(frame_type)
 
             pointer += 1
 
             payload_length = case length
             when 127 # Length defined by 8 bytes
               # Check buffer size
-              return if @data.getbyte(pointer+8-1) == nil # Buffer incomplete
+              return if @frame.data.getbyte(pointer+8-1) == nil # Buffer incomplete
 
               # 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
+              l = @frame.data.getbytes(pointer+4, 4).unpack('N').first
               pointer += 8
               l
             when 126 # Length defined by 2 bytes
               # Check buffer size
-              return if @data.getbyte(pointer+2-1) == nil # Buffer incomplete
+              return if @frame.data.getbyte(pointer+2-1) == nil # Buffer incomplete
 
-              l = @data.getbytes(pointer, 2).unpack('n').first
+              l = @frame.data.getbytes(pointer, 2).unpack('n').first
               pointer += 2
               l
             else
@@ -98,27 +105,27 @@ module WebSocket
             frame_length = pointer + payload_length
             frame_length += 4 if mask
 
-            raise(WebSocket::Error, :frame_too_long) if frame_length > WebSocket.max_frame_size
+            raise(WebSocket::Error::Frame::TooLong) if frame_length > WebSocket.max_frame_size
 
             # Check buffer size
-            return if @data.getbyte(frame_length-1) == nil # Buffer incomplete
+            return if @frame.data.getbyte(frame_length-1) == nil # Buffer incomplete
 
             # Remove frame header
-            @data.slice!(0...pointer)
+            @frame.data.slice!(0...pointer)
             pointer = 0
 
             # Read application data (unmasked if required)
-            @data.set_mask if mask
+            @frame.data.set_mask if mask
             pointer += 4 if mask
-            application_data = @data.getbytes(pointer, payload_length)
+            application_data = @frame.data.getbytes(pointer, payload_length)
             application_data.force_encoding('UTF-8') if application_data.respond_to?(:force_encoding)
             pointer += payload_length
-            @data.unset_mask if mask
+            @frame.data.unset_mask if mask
 
             # Throw away data up to pointer
-            @data.slice!(0...pointer)
+            @frame.data.slice!(0...pointer)
 
-            raise(WebSocket::Error, :unexpected_continuation_frame) if frame_type == :continuation && !@frame_type
+            raise(WebSocket::Error::Frame::UnexpectedContinuationFrame) if frame_type == :continuation && !@frame_type
 
             if more
               @application_data_buffer ||= ''
@@ -129,47 +136,34 @@ module WebSocket
               if frame_type == :continuation
                 @application_data_buffer << application_data
                 # Test valid UTF-8 encoding
-                raise(WebSocket::Error, :invalid_payload_encoding) if @frame_type == :text && @application_data_buffer.respond_to?(:valid_encoding?) && !@application_data_buffer.valid_encoding?
-                message = self.class.new(:version => version, :type => @frame_type, :data => @application_data_buffer, :decoded => true)
+                raise(WebSocket::Error::Frame::InvalidPayloadEncoding) if @frame_type == :text && @application_data_buffer.respond_to?(:valid_encoding?) && !@application_data_buffer.valid_encoding?
+                message = @frame.class.new(:version => @frame.version, :type => @frame_type, :data => @application_data_buffer, :decoded => true)
                 @application_data_buffer = nil
                 @frame_type = nil
                 return message
               else
-                raise(WebSocket::Error, :invalid_payload_encoding) if frame_type == :text && application_data.respond_to?(:valid_encoding?) && !application_data.valid_encoding?
-                return self.class.new(:version => version, :type => frame_type, :data => application_data, :decoded => true)
+                raise(WebSocket::Error::Frame::InvalidPayloadEncoding) if frame_type == :text && application_data.respond_to?(:valid_encoding?) && !application_data.valid_encoding?
+                return @frame.class.new(:version => @frame.version, :type => frame_type, :data => application_data, :decoded => true)
               end
             end
           end
           return nil
-        rescue WebSocket::Error => e
-          set_error(e.message.to_sym) and return
         end
 
-        # This allows flipping the more bit to fin for draft 04
-        def fin; false; end
-
         # Allow turning on or off masking
         def masking?; false; end
 
-        # Hash of frame names and it's opcodes
-        FRAME_TYPES = {
-          :continuation => 0,
-          :close => 1,
-          :ping => 2,
-          :pong => 3,
-          :text => 4,
-          :binary => 5
-        }
+        private
 
-        # Hash of frame opcodes and it's names
-        FRAME_TYPES_INVERSE = FRAME_TYPES.invert
+        # This allows flipping the more bit to fin for draft 04
+        def fin; false; end
 
         # Convert frame type name to opcode
         # @param [Symbol] frame_type Frame type name
         # @return [Integer] opcode or nil
         # @raise [WebSocket::Error] if frame opcode is not known
         def type_to_opcode(frame_type)
-          FRAME_TYPES[frame_type] || raise(WebSocket::Error, :unknown_frame_type)
+          FRAME_TYPES[frame_type] || raise(WebSocket::Error::Frame::UnknownFrameType)
         end
 
         # Convert frame opcode to type name
@@ -177,7 +171,7 @@ module WebSocket
         # @return [Symbol] Frame type name or nil
         # @raise [WebSocket::Error] if frame type name is not known
         def opcode_to_type(opcode)
-          FRAME_TYPES_INVERSE[opcode] || raise(WebSocket::Error, :unknown_opcode)
+          FRAME_TYPES_INVERSE[opcode] || raise(WebSocket::Error::Frame::UnknownOpcode)
         end
 
       end