websocket 1.0.1 → 1.0.2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.0.2
+
+- allow configuration of max frame size via WebSocket.max_frame_size option
+- much better documentation
+- remove handler-specific methods from public list
+- refactor code for easier use
+- make parsers return more consistent values
+- fix server handshake #to_s when no version was found
+- add #uri to server handshake
+
 ## 1.0.1
 
 - allow creating client with :uri and :url options

data/README.md

@@ -9,7 +9,7 @@ Currently WebSocket Ruby supports all existing drafts of WebSocket, which includ
 
 - [hixie-75](http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75)
 - [hixie-76](http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76)
-- [all hybi drafts (00-17)](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17)
+- [all hybi drafts (00-13)](http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17)
 - [RFC 6455](http://datatracker.ietf.org/doc/rfc6455/)
 
 ## Installation

data/autobahn-server.json

@@ -2,7 +2,7 @@
    "options": {"failByDrop": false},
    "outdir": "./autobahn/server",
 
-   "servers": [{"agent": "WebSocket-Ruby v1.0.1", "url": "ws://localhost:9001", "options": {"version": 18}}],
+   "servers": [{"agent": "WebSocket-Ruby v1.0.2", "url": "ws://localhost:9001", "options": {"version": 18}}],
 
    "cases": ["*"],
    "exclude-cases": [],

data/examples/client.rb

@@ -2,7 +2,7 @@ require "#{File.expand_path(File.dirname(__FILE__))}/base"
 require 'uri'
 
 # Example WebSocket Client (using EventMachine)
-# @example Usage
+# @example
 #   ws = WebSocket::EventMachine::Client.connect(:host => "0.0.0.0", :port => 8080)
 #   ws.onmessage { |msg| ws.send "Pong: #{msg}" }
 #   ws.send "data"

data/examples/server.rb

@@ -1,7 +1,7 @@
 require "#{File.expand_path(File.dirname(__FILE__))}/base"
 
 # Example WebSocket Server (using EventMachine)
-# @example Usage
+# @example
 #   WebSocket::EventMachine::Server.start(:host => "0.0.0.0", :port => 8080) do |ws|
 #     ws.onopen    { ws.send "Hello Client!"}
 #     ws.onmessage { |msg| ws.send "Pong: #{msg}" }

data/examples/tests/autobahn_server.rb

@@ -0,0 +1,24 @@
+require "#{File.expand_path(File.dirname(__FILE__))}/../server"
+
+EM.epoll
+EM.run do
+
+  trap("TERM") { stop }
+  trap("INT")  { stop }
+
+  WebSocket::EventMachine::Server.start(:host => "0.0.0.0", :port => 9001) do |ws|
+
+    ws.onmessage do |msg, type|
+      ws.send msg, :type => type
+    end
+
+  end
+
+  puts "Server started at port 9001"
+
+  def stop
+    puts "Terminating WebSocket Server"
+    EventMachine.stop
+  end
+
+end

data/lib/websocket.rb

@@ -6,6 +6,7 @@
 module WebSocket
   class Error < RuntimeError; end
 
+  # Default WebSocket version to use
   DEFAULT_VERSION = 13
   ROOT = File.expand_path(File.dirname(__FILE__))
 
@@ -13,4 +14,14 @@ module WebSocket
   autoload :Handler,   "#{ROOT}/websocket/handler"
   autoload :Handshake, "#{ROOT}/websocket/handshake"
 
+  # Limit of frame size payload in bytes
+  def self.max_frame_size
+    @max_frame_size ||= 20 * 1024 * 1024 # 20MB
+  end
+
+  # Set limit of frame size payload in bytes
+  def self.max_frame_size=(val)
+    @max_frame_size = val
+  end
+
 end

data/lib/websocket/frame/base.rb

@@ -1,19 +1,20 @@
 module WebSocket
   module Frame
+    # @abstract Subclass and override to implement custom frames
     class Base
 
       attr_reader :data, :type, :version, :error
 
       # Initialize frame
       # @param args [Hash] Arguments for frame
+      # @option args [String]  :data default data for frame
+      # @option args [String]  :type Type of frame - available types are "text", "binary", "ping", "pong" and "close"(support depends on draft version)
       # @option args [Integer] :version Version of draft. Currently supported version are 75, 76 and 00-13.
-      # @option args [String] :type Type of frame - available types are "text", "binary", "ping", "pong" and "close"(support depends on draft version)
-      # @option args [String] :data default data for frame
       def initialize(args = {})
         @type = args[:type]
         @data = Data.new(args[:data].to_s)
         @version = args[:version] || DEFAULT_VERSION
-        set_handler
+        include_version
       end
 
       # Check if some errors occured
@@ -22,9 +23,21 @@ module WebSocket
         !!@error
       end
 
+      # Is selected type supported for selected handler?
+      def support_type?
+        supported_frames.include?(@type)
+      end
+
+      # Implement in submodules
+      def supported_frames
+        raise NotImplementedError
+      end
+
       private
 
-      def set_handler
+      # 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
@@ -36,6 +49,8 @@ module WebSocket
         end
       end
 
+      # Changes state to error and sets error message
+      # @param [String] message Error message to set
       def set_error(message)
         @error = message
       end

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

@@ -3,34 +3,30 @@ module WebSocket
     module Handler
       module Base
 
-        MAX_FRAME_SIZE = 20 * 1024 * 1024 # 20MB
-
-        # Is selected type supported for selected handler?
-        def support_type?
-          supported_frames.include?(@type)
-        end
-
-        # Implement in submodules
-        def supported_frames
-          raise NotImplementedError
-        end
-
         private
 
         # Convert data to raw frame ready to send to client
+        # @return [String] Encoded frame
         def encode_frame
           raise NotImplementedError
         end
 
         # Convert raw data to decoded frame
+        # @return [WebSocket::Frame::Incoming] Frame if found, nil otherwise
         def decode_frame
           raise NotImplementedError
         end
 
+        # Check if frame is one of control frames
+        # @param [Symbol] frame_type Frame type
+        # @return [Boolean] True if given frame type is control frame
         def control_frame?(frame_type)
           ![:text, :binary, :continuation].include?(frame_type)
         end
 
+        # Check if frame is one of data frames
+        # @param [Symbol] frame_type Frame type
+        # @return [Boolean] True if given frame type is data frame
         def data_frame?(frame_type)
           [:text, :binary].include?(frame_type)
         end

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

@@ -7,12 +7,14 @@ module WebSocket
 
         include Base
 
+        # @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 = ''
 
@@ -38,6 +40,7 @@ module WebSocket
           set_error(e.message.to_sym) and return
         end
 
+        # @see WebSocket::Frame::Handler::Base#decode_frame
         def decode_frame
           while @data.size > 1
             pointer = 0
@@ -85,7 +88,7 @@ module WebSocket
             frame_length = pointer + payload_length
             frame_length += 4 if mask
 
-            raise(WebSocket::Error, :frame_too_long) if frame_length > MAX_FRAME_SIZE
+            raise(WebSocket::Error, :frame_too_long) if frame_length > WebSocket.max_frame_size
 
             # Check buffer size
             return if @data.getbyte(frame_length-1) == nil # Buffer incomplete
@@ -135,8 +138,10 @@ module WebSocket
         # 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,
@@ -146,12 +151,21 @@ module WebSocket
           :binary => 5
         }
 
+        # Hash of frame opcodes and it's names
         FRAME_TYPES_INVERSE = FRAME_TYPES.invert
 
+        # 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)
         end
 
+        # Convert frame opcode to type name
+        # @param [Integer] opcode Opcode
+        # @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)
         end

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

@@ -9,6 +9,7 @@ module WebSocket
 
         private
 
+        # Since handler 5 masking should be enabled by default
         def masking?; true; end
 
       end

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

@@ -9,6 +9,7 @@ module WebSocket
 
         private
 
+        # Hash of frame names and it's opcodes
         FRAME_TYPES = {
           :continuation => 0,
           :text => 1,
@@ -18,12 +19,21 @@ module WebSocket
           :pong => 10,
         }
 
+        # Hash of frame opcodes and it's names
         FRAME_TYPES_INVERSE = FRAME_TYPES.invert
 
+        # 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)
         end
 
+        # Convert frame opcode to type name
+        # @param [Integer] opcode Opcode
+        # @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)
         end

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

@@ -7,12 +7,14 @@ module WebSocket
 
         include Base
 
+        # @see WebSocket::Frame::Base#supported_frames
         def supported_frames
           [:text, :close]
         end
 
         private
 
+        # @see WebSocket::Frame::Handler::Base#encode_frame
         def encode_frame
           case @type
             when :close then "\xff\x00"
@@ -23,6 +25,7 @@ module WebSocket
           end
         end
 
+        # @see WebSocket::Frame::Handler::Base#decode_frame
         def decode_frame
           return if @data.size == 0
 
@@ -43,7 +46,7 @@ module WebSocket
               break unless (b & 0x80) == 0x80
             end
 
-            set_error(:frame_too_long) and return if length > MAX_FRAME_SIZE
+            set_error(:frame_too_long) and return if length > ::WebSocket.max_frame_size
 
             unless @data.getbyte(pointer+length-1) == nil
               # Straight from spec - I'm sure this isn't crazy...
@@ -62,7 +65,7 @@ module WebSocket
             set_error(:invalid_frame) and return if @data.getbyte(0) != 0x00
 
             # Addition to the spec to protect against malicious requests
-            set_error(:frame_too_long) and return if @data.size > MAX_FRAME_SIZE
+            set_error(:frame_too_long) and return if @data.size > ::WebSocket.max_frame_size
 
             msg = @data.slice!(/\A\x00[^\xff]*\xff/)
             if msg

data/lib/websocket/frame/incoming.rb

@@ -1,5 +1,13 @@
 module WebSocket
   module Frame
+    # Construct or parse incoming WebSocket Frame.
+    # @note You should NEVER use this class directly - use Client or Server subclasses instead, as they contain additional frame options(i.e. Client-side masking in draft 04)
+    #
+    # @example
+    #   frame = WebSocket::Frame::Incoming::Server.new(:version => @handshake.version)
+    #   frame << "\x81\x05\x48\x65\x6c\x6c\x6f\x81\x06\x77\x6f\x72\x6c\x64\x21"
+    #   frame.next # "Hello"
+    #   frame.next # "world!""
     class Incoming < Base
 
       autoload :Client, "#{::WebSocket::ROOT}/websocket/frame/incoming/client"

data/lib/websocket/frame/outgoing.rb

@@ -1,5 +1,11 @@
 module WebSocket
   module Frame
+    # Construct or parse incoming WebSocket Frame.
+    # @note You should NEVER use this class directly - use Client or Server subclasses instead, as they contain additional frame options(i.e. Client-side masking in draft 04)
+    #
+    # @example
+    #   frame = WebSocket::Frame::Outgoing::Server.new(:version => @handshake.version, :data => "Hello", :type => :text)
+    #   frame.to_s # "\x81\x05\x48\x65\x6c\x6c\x6f"
     class Outgoing < Base
 
       autoload :Client, "#{::WebSocket::ROOT}/websocket/frame/outgoing/client"

data/lib/websocket/handshake/base.rb

@@ -1,10 +1,12 @@
 module WebSocket
   module Handshake
+    # @abstract Subclass and override to implement custom handshakes
     class Base
 
       attr_reader :host, :port, :path, :query,
                   :error, :state, :version, :secure
 
+      # Initialize new WebSocket Handshake and set it's state to :new
       def initialize(args = {})
         @state = :new
 
@@ -12,32 +14,63 @@ module WebSocket
         @headers = {}
       end
 
+      # @abstract Add data to handshake
       def <<(data)
         raise NotImplementedError
       end
 
+      # Return textual representation of handshake request or response
+      # @return [String] text of response
+      def to_s
+        ""
+      end
+
+      # Is parsing of data finished?
+      # @return [Boolena] True if request was completely parsed or error occured. False otherwise
       def finished?
         @state == :finished || @state == :error
       end
 
+      # Is parsed data valid?
+      # @return [Boolean] False if some errors occured. Reason for error could be found in error method
       def valid?
         finished? && @error == nil
       end
 
+      # @abstract Should send data after parsing is finished?
       def should_respond?
         raise NotImplementedError
       end
 
+      # Data left from parsing. Sometimes data that doesn't belong to handshake are added - use this method to retrieve them.
+      # @return [String] String if some data are available. Nil otherwise
       def leftovers
         @leftovers.split("\n", reserved_leftover_lines + 1)[reserved_leftover_lines]
       end
 
+      # URI of request.
+      # @return [String] Full URI with protocol
+      # @example
+      #   @handshake.uri #=> "ws://example.com/path?query=true"
+      def uri
+        uri =  secure ? "wss://" : "ws://"
+        uri << host
+        uri << ":#{port}" if port
+        uri << path
+        uri << "?#{query}" if query
+        uri
+      end
+
       private
 
+      # Number of lines after header that should be handled as belonging to handshake. Any data after those lines will be handled as leftovers.
+      # @return [Integer] Number of lines
       def reserved_leftover_lines
         0
       end
 
+      # Changes state to error and sets error message
+      # @param [String] message Error message to set
       def set_error(message)
         @state = :error
         @error = message
@@ -45,14 +78,16 @@ module WebSocket
 
       HEADER = /^([^:]+):\s*(.+)$/
 
+      # Parse data imported to handshake and sets state to finished if necessary.
+      # @return [Boolean] True if finished parsing. False if not all data received yet.
       def parse_data
         header, @leftovers = @data.split("\r\n\r\n", 2)
-        return unless @leftovers # The whole header has not been received yet.
+        return false unless @leftovers # The whole header has not been received yet.
 
         lines = header.split("\r\n")
 
         first_line = lines.shift
-        return unless parse_first_line(first_line)
+        return false unless parse_first_line(first_line)
 
         lines.each do |line|
           h = HEADER.match(line)
@@ -60,6 +95,7 @@ module WebSocket
         end
 
         @state = :finished
+        true
       end
 
     end

data/lib/websocket/handshake/client.rb

@@ -2,8 +2,53 @@ require 'URI' unless defined?(URI)
 
 module WebSocket
   module Handshake
+    # Construct or parse a client WebSocket handshake.
+    #
+    # @example
+    #   @handshake = WebSocket::Handshake::Client.new(:url => 'ws://example.com')
+    #
+    #   # Create request
+    #   @handshake.to_s # GET /demo HTTP/1.1
+    #                   # Upgrade: websocket
+    #                   # Connection: Upgrade
+    #                   # Host: example.com
+    #                   # Sec-WebSocket-Origin: http://example.com
+    #                   # Sec-WebSocket-Version: 17
+    #                   # Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
+    #
+    #   # Parse server response
+    #   @handshake << <<EOF
+    #   HTTP/1.1 101 Switching Protocols
+    #   Upgrade: websocket
+    #   Connection: Upgrade
+    #   Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
+    #
+    #   EOF
+    #
+    #   # All data received?
+    #   @handshake.finished?
+    #
+    #   # No parsing errors?
+    #   @handshake.valid?
+    #
     class Client < Base
 
+      # Initialize new WebSocket Client
+      #
+      # @param [Hash] args Arguments for client
+      #
+      # @option args [String]  :host Host of request. Required if no :url param was provided.
+      # @option args [String]  :origin Origin of request. Optional, should be used mostly by browsers. Default: nil
+      # @option args [String]  :path Path of request. Should start with '/'. Default: '/'
+      # @option args [Integer] :port Port of request. Default: nil
+      # @option args [String]  :query. Query for request. Should be in format "aaa=bbb&ccc=ddd"
+      # @option args [Boolean] :secure Defines protocol to use. If true then wss://, otherwise ws://. This option will not change default port - it should be handled by programmer.
+      # @option args [String]  :url URL of request. Must by in format like ws://example.com/path?query=true. Every part of this url will be overriden by more specific arguments.
+      # @option args [String]  :uri Alias to :url
+      # @option args [Integer] :version Version of WebSocket to use. Default: 13 (this is version from RFC)
+      #
+      # @example
+      #   Websocket::Handshake::Client.new(:url => "ws://example.com/path?query=true")
       def initialize(args = {})
         super
 
@@ -32,6 +77,18 @@ module WebSocket
         include_version
       end
 
+      # Add text of response from Server. This method will parse content immediately and update state and error(if neccessary)
+      #
+      # @param [String] data Data to add
+      #
+      # @example
+      #   @handshake << <<EOF
+      #   HTTP/1.1 101 Switching Protocols
+      #   Upgrade: websocket
+      #   Connection: Upgrade
+      #   Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
+      #
+      #   EOF
       def <<(data)
         @data << data
         if parse_data
@@ -39,21 +96,16 @@ module WebSocket
         end
       end
 
+      # Should send content to server after finished parsing?
+      # @return [Boolean] false
       def should_respond?
         false
       end
 
-      def uri
-        uri = @secure ? "wss://" : "ws://"
-        uri << @host
-        uri << ":#{@port}" if @port
-        uri << @path
-        uri << "?#{@query}" if @query
-        uri
-      end
-
       private
 
+      # 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 then extend Handler::Client75
@@ -67,11 +119,14 @@ module WebSocket
 
       FIRST_LINE = /^HTTP\/1\.1 (\d{3})[\w\s]*$/
 
+      # Parse first line of Server response.
+      # @param [String] line Line to parse
+      # @return [Boolean] True if parsed correctly. False otherwise
       def parse_first_line(line)
         line_parts = line.match(FIRST_LINE)
-        set_error(:invalid_header) and return unless line_parts
+        set_error(:invalid_header) and return false unless line_parts
         status = line_parts[1]
-        set_error(:invalid_status_code) and return unless status == '101'
+        set_error(:invalid_status_code) and return false unless status == '101'
 
         return true
       end

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

@@ -1,8 +1,10 @@
 module WebSocket
   module Handshake
     module Handler
+      # This module and it's descendants are included in client or server handshake in order to extend basic functionality
       module Base
 
+        # @see WebSocket::Handshake::Base#to_s
         def to_s
           result = [ header_line ]
           handshake_keys.each do |key|
@@ -15,6 +17,20 @@ module WebSocket
 
         private
 
+        # Set first line of text representation according to specification.
+        # @return [String] First line of HTTP header
+        def header_line
+          ""
+        end
+
+        # Set handshake headers. Provided as array because some protocol version require specific order of fields.
+        # @return [Array] List of headers as arrays [ key, value ]
+        def handshake_keys
+          []
+        end
+
+        # Set data to send after headers. In most cases it will be blank data.
+        # @return [String] data
         def finishing_line
           ""
         end

data/lib/websocket/handshake/handler/client.rb

@@ -7,6 +7,7 @@ module WebSocket
 
         private
 
+        # @see WebSocket::Handshake::Handler::Base#header_line
         def header_line
           path = @path
           path += "?" + @query if @query

data/lib/websocket/handshake/handler/client01.rb

@@ -7,6 +7,9 @@ module WebSocket
 
         include Client76
 
+        private
+
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           keys = super
           keys << ['Sec-WebSocket-Draft', @version]

data/lib/websocket/handshake/handler/client04.rb

@@ -8,12 +8,14 @@ module WebSocket
 
         include Client
 
+        # @see WebSocket::Handshake::Base#valid?
         def valid?
           super && verify_accept
         end
 
         private
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           keys = [
             ["Upgrade", "websocket"],
@@ -23,19 +25,25 @@ module WebSocket
           host += ":#{@port}" if @port
           keys << ["Host", host]
           keys << ["Sec-WebSocket-Origin", @origin] if @origin
-          keys << ["Sec-WebSocket-Version", @version]
+          keys << ["Sec-WebSocket-Version", @version ]
           keys << ["Sec-WebSocket-Key", key]
           keys
         end
 
+        # Sec-WebSocket-Key value
+        # @return [String] key
         def key
           @key ||= Base64.encode64((1..16).map { rand(255).chr } * '').strip
         end
 
+        # Value of Sec-WebSocket-Accept that should be delivered back by server
+        # @return [Sering] accept
         def accept
           @accept ||= Base64.encode64(Digest::SHA1.digest(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')).strip
         end
 
+        # Verify if received header Sec-WebSocket-Accept matches generated one.
+        # @return [Boolean] True if accept is matching. False otherwise(appropriate error is set)
         def verify_accept
           set_error(:invalid_accept) and return false unless @headers['sec-websocket-accept'] == accept
           true

data/lib/websocket/handshake/handler/client75.rb

@@ -7,6 +7,7 @@ module WebSocket
 
         private
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           keys = [
             ["Upgrade", "WebSocket"],

data/lib/websocket/handshake/handler/client76.rb

@@ -7,28 +7,19 @@ module WebSocket
 
         include Client75
 
-        def key1
-          @key1 ||= generate_key(:key1)
-        end
-
-        def key2
-          @key2 ||= generate_key(:key2)
-        end
-
-        def key3
-          @key3 ||= generate_key3
-        end
-
+        # @see WebSocket::Handshake::Base#valid?
         def valid?
           super && verify_challenge
         end
 
         private
 
+        # @see WebSocket::Handshake::Base#reserved_leftover_lines
         def reserved_leftover_lines
           1
         end
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           keys = super
           keys << ['Sec-WebSocket-Key1', key1]
@@ -36,11 +27,31 @@ module WebSocket
           keys
         end
 
-        def verify_challenge
-          set_error(:invalid_challenge) and return false unless @leftovers == challenge
-          true
+        # @see WebSocket::Handshake::Handler::Base#finishing_line
+        def finishing_line
+          key3
         end
 
+        # Sec-WebSocket-Key1 value
+        # @return [String] key
+        def key1
+          @key1 ||= generate_key(:key1)
+        end
+
+        # Sec-WebSocket-Key2 value
+        # @return [String] key
+        def key2
+          @key2 ||= generate_key(:key2)
+        end
+
+        # Value of third key, sent in body
+        # @return [String] key
+        def key3
+          @key3 ||= generate_key3
+        end
+
+        # Expected challenge that should be sent by server
+        # @return [String] challenge
         def challenge
           return @challenge if defined?(@challenge)
           key1 && key2
@@ -51,12 +62,18 @@ module WebSocket
           @challenge = Digest::MD5.digest(sum)
         end
 
-        def finishing_line
-          key3
+        # Verify if challenge sent by server match generated one
+        # @return [Boolena] True if challenge matches, false otherwise(sets appropriate error)
+        def verify_challenge
+          set_error(:invalid_challenge) and return false unless @leftovers == challenge
+          true
         end
 
         NOISE_CHARS = ("\x21".."\x2f").to_a() + ("\x3a".."\x7e").to_a()
 
+        # Generate Sec-WebSocket-Key1 and Sec-WebSocket-Key2
+        # @param [String] name of key. Will be used to set number variable needed later. Valid values: key1, key2
+        # @return [String] generated key
         def generate_key(key)
           spaces = 1 + rand(12)
           max = 0xffffffff / spaces
@@ -75,6 +92,7 @@ module WebSocket
           return key
         end
 
+        # Generate third key
         def generate_key3
           return [rand(0x100000000)].pack("N") + [rand(0x100000000)].pack("N")
         end

data/lib/websocket/handshake/handler/server.rb

@@ -5,25 +5,6 @@ module WebSocket
 
         include Base
 
-        def host
-          @headers["host"].to_s.split(":")[0].to_s
-        end
-
-        def port
-          @headers["host"].to_s.split(":")[1]
-        end
-
-        private
-
-        def handshake_location
-          location = @secure ? "wss://" : "ws://"
-          location << host
-          location << ":#{port}" if port
-          location << path
-          location << "?#{@query}" if @query
-          location
-        end
-
       end
     end
   end

data/lib/websocket/handshake/handler/server04.rb

@@ -8,16 +8,19 @@ module WebSocket
 
         include Server
 
+        # @see WebSocket::Handshake::Base#valid?
         def valid?
           super && (@headers['sec-websocket-key'] ? true : (set_error(:invalid_handshake_authentication) and false))
         end
 
         private
 
+        # @see WebSocket::Handshake::Handler::Base#header_line
         def header_line
           "HTTP/1.1 101 Switching Protocols"
         end
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           [
             ["Upgrade", "websocket"],
@@ -26,6 +29,8 @@ module WebSocket
           ]
         end
 
+        # Signature of response, created from client request Sec-WebSocket-Key
+        # @return [String] signature
         def signature
           return unless key = @headers['sec-websocket-key']
           string_to_sign = "#{key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

data/lib/websocket/handshake/handler/server75.rb

@@ -7,16 +7,18 @@ module WebSocket
 
         private
 
+        # @see WebSocket::Handshake::Handler::Base#header_line
         def header_line
           "HTTP/1.1 101 Web Socket Protocol Handshake"
         end
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           [
             ["Upgrade", "WebSocket"],
             ["Connection", "Upgrade"],
             ["WebSocket-Origin", @headers['origin']],
-            ["WebSocket-Location", handshake_location]
+            ["WebSocket-Location", uri]
           ]
         end
 

data/lib/websocket/handshake/handler/server76.rb

@@ -7,35 +7,42 @@ module WebSocket
 
         include Server
 
+        # @see WebSocket::Handshake::Base#valid?
         def valid?
           super && !!finishing_line
         end
 
         private
 
+        # @see WebSocket::Handshake::Base#reserved_leftover_lines
         def reserved_leftover_lines
           1
         end
 
+        # @see WebSocket::Handshake::Handler::Base#header_line
         def header_line
           "HTTP/1.1 101 WebSocket Protocol Handshake"
         end
 
+        # @see WebSocket::Handshake::Handler::Base#handshake_keys
         def handshake_keys
           [
             ["Upgrade", "WebSocket"],
             ["Connection", "Upgrade"],
             ["Sec-WebSocket-Origin", @headers['origin']],
-            ["Sec-WebSocket-Location", handshake_location]
+            ["Sec-WebSocket-Location", uri]
           ]
         end
 
+        # @see WebSocket::Handshake::Handler::Base#finishing_line
         def finishing_line
           @finishing_line ||= challenge_response
         end
 
         private
 
+        # Response to client challenge from request Sec-WebSocket-Key1, Sec-WebSocket-Key2 and leftovers
+        # @return [String] Challenge response or nil if error occured
         def challenge_response
           # Refer to 5.2 4-9 of the draft 76
           first = numbers_over_spaces(@headers['sec-websocket-key1']) || return
@@ -48,6 +55,9 @@ module WebSocket
           Digest::MD5.digest(sum)
         end
 
+        # Calculate numbers over spaces, according to spec 5.2
+        # @param [String] string Key to parse
+        # @return [Integer] Result of calculations or nil if error occured
         def numbers_over_spaces(string)
           numbers = string.scan(/[0-9]/).join.to_i
 

data/lib/websocket/handshake/server.rb

@@ -1,12 +1,64 @@
 module WebSocket
   module Handshake
+    # Construct or parse a server WebSocket handshake.
+    #
+    # @example
+    #   handshake = WebSocket::Handshake::Server.new
+    #
+    #   # Parse client request
+    #   @handshake << <<EOF
+    #   GET /demo HTTP/1.1
+    #   Upgrade: websocket
+    #   Connection: Upgrade
+    #   Host: example.com
+    #   Sec-WebSocket-Origin: http://example.com
+    #   Sec-WebSocket-Version: 17
+    #   Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
+    #
+    #   EOF
+    #
+    #   # All data received?
+    #   @handshake.finished?
+    #
+    #   # No parsing errors?
+    #   @handshake.valid?
+    #
+    #   # Create response
+    #   @handshake.to_s # HTTP/1.1 101 Switching Protocols
+    #                   # Upgrade: websocket
+    #                   # Connection: Upgrade
+    #                   # Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
+    #
     class Server < Base
 
+      # Initialize new WebSocket Server
+      #
+      # @param [Hash] args Arguments for server
+      #
+      # @option args [Boolean] :secure If true then server will use wss:// protocol
+      #
+      # @example
+      #   Websocket::Handshake::Server.new(:secure => true)
       def initialize(args = {})
         super
         @secure = !!args[:secure]
       end
 
+      # Add text of request from Client. This method will parse content immediately and update version, state and error(if neccessary)
+      #
+      # @param [String] data Data to add
+      #
+      # @example
+      #   @handshake << <<EOF
+      #   GET /demo HTTP/1.1
+      #   Upgrade: websocket
+      #   Connection: Upgrade
+      #   Host: example.com
+      #   Sec-WebSocket-Origin: http://example.com
+      #   Sec-WebSocket-Version: 13
+      #   Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
+      #
+      #   EOF
       def <<(data)
         @data << data
         if parse_data
@@ -14,12 +66,27 @@ module WebSocket
         end
       end
 
+      # Should send content to client after finished parsing?
+      # @return [Boolean] true
       def should_respond?
         true
       end
 
+      # Host of server according to client header
+      # @return [String] host
+      def host
+        @headers["host"].to_s.split(":")[0].to_s
+      end
+
+      # Port of server according to client header
+      # @return [String] port
+      def port
+        @headers["host"].to_s.split(":")[1]
+      end
+
       private
 
+      # Set version of protocol basing on client requets. AFter cotting method calls include_version.
       def set_version
         @version = @headers['sec-websocket-version'].to_i if @headers['sec-websocket-version']
         @version ||= @headers['sec-websocket-draft'].to_i if @headers['sec-websocket-draft']
@@ -28,6 +95,8 @@ module WebSocket
         include_version
       end
 
+      # 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 then extend Handler::Server75
@@ -40,6 +109,9 @@ module WebSocket
 
       PATH = /^(\w+) (\/[^\s]*) HTTP\/1\.1$/
 
+      # Parse first line of Client response.
+      # @param [String] line Line to parse
+      # @return [Boolean] True if parsed correctly. False otherwise
       def parse_first_line(line)
         line_parts = line.match(PATH)
         set_error(:invalid_header) and return unless line_parts

data/lib/websocket/version.rb

@@ -1,3 +1,3 @@
 module WebSocket
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 end

data/spec/frame/incoming_03_spec.rb

@@ -99,7 +99,7 @@ describe 'Incoming frame draft 03' do
   end
 
   context "should raise error with too long frame" do
-    let(:encoded_text) { "\x04\x7F" + "a" * WebSocket::Frame::Handler::Base::MAX_FRAME_SIZE }
+    let(:encoded_text) { "\x04\x7F" + "a" * WebSocket.max_frame_size }
     let(:decoded_text) { nil }
     let(:error) { :frame_too_long }
 

data/spec/frame/incoming_04_spec.rb

@@ -99,7 +99,7 @@ describe 'Incoming frame draft 04' do
   end
 
   context "should raise error with too long frame" do
-    let(:encoded_text) { "\x84\x7F" + "a" * WebSocket::Frame::Handler::Base::MAX_FRAME_SIZE }
+    let(:encoded_text) { "\x84\x7F" + "a" * WebSocket.max_frame_size }
     let(:decoded_text) { nil }
     let(:error) { :frame_too_long }
 

data/spec/frame/incoming_05_spec.rb

@@ -115,7 +115,7 @@ describe 'Incoming frame draft 05' do
   end
 
   context "should raise error with too long frame" do
-    let(:encoded_text) { "\x84\x7F" + "a" * WebSocket::Frame::Handler::Base::MAX_FRAME_SIZE }
+    let(:encoded_text) { "\x84\x7F" + "a" * WebSocket.max_frame_size }
     let(:decoded_text) { nil }
     let(:error) { :frame_too_long }
 

data/spec/frame/incoming_07_spec.rb

@@ -115,7 +115,7 @@ describe 'Incoming frame draft 07' do
   end
 
   context "should raise error with too long frame" do
-    let(:encoded_text) { "\x81\x7F" + "a" * WebSocket::Frame::Handler::Base::MAX_FRAME_SIZE }
+    let(:encoded_text) { "\x81\x7F" + "a" * WebSocket.max_frame_size }
     let(:decoded_text) { nil }
     let(:error) { :frame_too_long }
 

data/spec/frame/incoming_75_spec.rb

@@ -50,7 +50,7 @@ describe 'Incoming frame draft 75' do
   end
 
   context "with too long frame" do
-    let(:encoded_text) { "\x00" + "a" * WebSocket::Frame::Handler::Base::MAX_FRAME_SIZE + "\xFF" }
+    let(:encoded_text) { "\x00" + "a" * WebSocket.max_frame_size + "\xFF" }
     let(:error) { :frame_too_long }
 
     it_should_behave_like('valid_incoming_frame') unless RUBY_PLATFORM == "java"

data/spec/handshake/client_76_spec.rb

@@ -4,7 +4,7 @@ describe 'Client draft 76 handshake' do
   let(:handshake) { WebSocket::Handshake::Client.new({ :uri => 'ws://example.com/demo', :origin => 'http://example.com', :version => version }.merge(@request_params || {})) }
 
   let(:version) { 76 }
-  let(:client_request) { client_handshake_76({ :key1 => handshake.key1, :key2 => handshake.key2, :key3 => handshake.key3 }.merge(@request_params || {})) }
+  let(:client_request) { client_handshake_76({ :key1 => handshake.send(:key1), :key2 => handshake.send(:key2), :key3 => handshake.send(:key3) }.merge(@request_params || {})) }
   let(:server_response) { server_handshake_76({ :challenge => handshake.send(:challenge) }.merge(@request_params || {})) }
 
   it_should_behave_like 'all client drafts'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: websocket
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -46,6 +46,7 @@ files:
 - examples/client.rb
 - examples/server.rb
 - examples/tests/autobahn_client.rb
+- examples/tests/autobahn_server.rb
 - examples/tests/echo_client.rb
 - examples/tests/echo_server.rb
 - lib/websocket.rb
@@ -120,7 +121,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2471372616907526003
+      hash: 221385565863631789
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -129,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2471372616907526003
+      hash: 221385565863631789
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24