websocket_parser 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in websocket_parser.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Alberto Fernandez-Capel
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,62 @@
+# WebSocketParser
+
+WebsocketParser is a RFC6455 compliant parser for websocket messages written in Ruby. It
+is intended to write websockets servers in Ruby, but it only handles the parsing of the
+WebSocket protocol, leaving I/O to the server.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'websocket_parser'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install websocket_parser
+
+## Usage
+
+```
+require 'websocket_parser'
+
+socket = # Handle I/O with your server/event loop.
+
+parser = WebSocket::Parser.new
+
+parser.on_message do |m|
+  puts "Received message #{m}"
+end
+
+parser.on_error do |m|
+  puts "Received error #{m}"
+  socket.close!
+end
+
+parser.on_close do |m|
+  puts "Client closed connection. Reason: #{m}"
+  socket.close!
+end
+
+parser.on_ping do |m|
+  socket << WebSocket::Message.pong.to_data
+end
+
+parser << socket.read(4096)
+
+# To send a message:
+
+socket << WebSocket::Message.new('Hi there!').to_data
+
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/websocket/client_handshake.rb

@@ -0,0 +1,36 @@
+require 'digest/sha1'
+
+module WebSocket
+  class ClientHandshake < Http::Request
+
+    def initialize(method, uri, headers = {}, proxy = {}, body = nil, version = "1.1")
+      @method = method.to_s.downcase.to_sym
+      @uri = uri.is_a?(URI) ? uri : URI(uri.to_s)
+
+      @headers = headers
+      @proxy, @body, @version = proxy, body, version
+    end
+
+    def valid?
+      headers['Connection'] == 'Upgrade'   &&
+      headers['Upgrade']    == 'websocket' &&
+      headers['Sec-WebSocket-Version'].to_i == PROTOCOL_VERSION
+    end
+
+    def accept_response
+      response_headers = {
+        'Upgrade'    => 'websocket',
+        'Connection' => 'Upgrade',
+        'Sec-WebSocket-Accept' => accept_token
+      }
+
+      ServerHandshake.new(101, '1.1', response_headers)
+    end
+
+    private
+
+    def accept_token
+      Digest::SHA1.base64digest(headers['Sec-WebSocket-Key'].strip + GUID)
+    end
+  end
+end

data/lib/websocket/message.rb

@@ -0,0 +1,74 @@
+module WebSocket
+  class Message
+    attr_reader :type, :payload
+
+    # Return a new ping message
+    def self.ping(message = '')
+      new(message, :ping)
+    end
+
+    # Return a new pong message
+    def self.pong(message = '')
+      new(message, :pong)
+    end
+
+    # Return a new close message
+    def self.close(reason = '')
+      new(reason, :close)
+    end
+
+    def initialize(message, type = :text)
+      @type, @payload = type, message.force_encoding("ASCII-8BIT")
+    end
+
+    def first_byte
+      @first_byte ||= if type == :continuation
+        OPCODE_VALUES[type]
+      else
+        0b10000000 | OPCODE_VALUES[type] # set FIN bit to true
+      end
+    end
+
+    def message_size
+      if payload_length < 126
+        :small
+      elsif payload_length < 65_536 # fits in 2 bytes
+        :medium
+      else
+        :large
+      end
+    end
+
+    def second_byte
+      case message_size
+      when :small  then payload_length
+      when :medium then 126
+      when :large  then 127
+      end
+    end
+
+    def payload_length
+      @payload.length
+    end
+
+    def extended_payload_length
+      message_size == :small ? nil : payload_length
+    end
+
+    def to_a
+      [first_byte, second_byte, extended_payload_length, payload].compact
+    end
+
+    def pack_format
+      "#{FRAME_FORMAT[message_size]}#{payload_length}"
+    end
+
+    def to_data
+      to_a.pack(pack_format)
+    end
+
+    def write(io)
+      io << to_data
+    end
+  end
+end

data/lib/websocket/parser.rb

@@ -0,0 +1,239 @@
+module WebSocket
+  #
+  # This class parses WebSocket messages and frames.
+  #
+  # Each message is divied in frames as described in RFC 6455.
+  #
+  #    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+  #   +-+-+-+-+-------+-+-------------+-------------------------------+
+  #   |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
+  #   |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
+  #   |N|V|V|V|       |S|             |   (if payload len==126/127)   |
+  #   | |1|2|3|       |K|             |                               |
+  #   +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
+  #   |     Extended payload length continued, if payload len == 127  |
+  #   + - - - - - - - - - - - - - - - +-------------------------------+
+  #   |                               |Masking-key, if MASK set to 1  |
+  #   +-------------------------------+-------------------------------+
+  #   | Masking-key (continued)       |          Payload Data         |
+  #   +-------------------------------- - - - - - - - - - - - - - - - +
+  #   :                     Payload Data continued ...                :
+  #   + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+  #   |                     Payload Data continued ...                |
+  #   +---------------------------------------------------------------+
+  #
+  # for more info on the frame format see: http://tools.ietf.org/html/rfc6455#section-5
+  #
+  class Parser
+    def initialize
+      @data =  ''.force_encoding("ASCII-8BIT")
+
+      @on_message = Proc.new do |msg|
+        puts "Received message: #{msg}"
+      end
+
+      @on_error = Proc.new do |error|
+        puts "WebSocket error: #{error}"
+      end
+
+      @on_close = Proc.new do |reason|
+        puts "Should close connection. Reason: #{reason}"
+      end
+
+      @on_ping = Proc.new do |ping|
+        puts "Ping received"
+      end
+
+      @on_pong = Proc.new do |pong|
+        puts "Pong received"
+      end
+
+      @state = :header
+    end
+
+    def on_message(&callback)
+      @on_message = callback
+    end
+
+    def on_error(&callback)
+      @on_error = callback
+    end
+
+    def on_close(&callback)
+      @on_close = callback
+    end
+
+    def on_ping(&callback)
+      @on_ping = callback
+    end
+
+    def on_pong(&callback)
+      @on_pong = callback
+    end
+
+    def receive(data)
+      @data << data
+
+      read_header         if @state == :header
+      read_payload_length if @state == :payload_length
+      read_payload        if @state == :payload
+
+      process_frame if @state == :complete
+    end
+
+    alias_method :<<, :receive
+
+    def read_header
+      return unless @data.length >= 2 # Not enough data
+
+      @first_byte, @second_byte = @data.slice!(0,2).unpack('C2')
+      @state = :payload_length
+    end
+
+    def read_payload_length
+      @payload_length = if message_size == :small
+         payload_length_field
+      else
+        read_extended_payload_length
+      end
+
+      @state = :payload if @payload_length
+    end
+
+    def read_extended_payload_length
+      if message_size == :medium && @data.size >= 2
+         unpack_bytes(2,'S<')
+      elsif message_size == :large && @data.size >= 4
+        unpack_bytes(8,'Q<')
+      end
+    end
+
+    def read_payload
+      return unless @data.length >= @payload_length # Not enough data
+
+      payload_data = unpack_bytes(@payload_length, "a#{@payload_length}")
+      @payload = masked? ? unmask(payload_data) : payload_data
+
+      @state = :complete if @payload
+    end
+
+    def unpack_bytes(num, format)
+      @data.slice!(0,num).unpack(format).first
+    end
+
+    def completed_message?
+      fin? || payload
+    end
+
+    def control_frame?
+      [:close, :ping, :pong].include?(opcode)
+    end
+
+    def process_frame
+      if @current_message
+        @current_message << @payload
+      else
+        @current_message = @payload
+      end
+
+      if fin?
+        process_message
+      end
+
+      reset_frame!
+    end
+
+    def process_message
+      case opcode
+      when :text
+        @on_message.call(@current_message.force_encoding("UTF-8"))
+      when :binary
+        @on_message.call(@current_message)
+      when :close
+        @on_close.call(@current_message.encode("UTF-8"))
+      when :ping
+        @on_ping.call(@current_message.encode("UTF-8"))
+      when :pong
+        @on_pong.call(@current_message.encode("UTF-8"))
+      end
+
+      @current_message = nil
+    end
+
+    # Whether the FIN bit is set. The FIN bit indicates that
+    # this is the final fragment in a message
+    def fin?
+      @first_byte & 0b10000000 != 0
+    end
+
+    def svr1?
+      @first_byte & 0b01000000 != 0
+    end
+
+    def svr2?
+      @first_byte & 0b00100000 != 0
+    end
+
+    def svr3?
+      @first_byte & 0b00010000 != 0
+    end
+
+    def opcode
+      @opcode ||= OPCODES[@first_byte & 0b00001111]
+    end
+
+    def masked?
+      @second_byte & 0b10000000 != 0
+    end
+
+    def payload_length_field
+      @second_byte & 0b01111111
+    end
+
+    def mask_key
+      @mask_key ||= if masked?
+        @second_byte && read_uint32!
+      else
+        nil
+      end
+    end
+
+    def message_size
+      if payload_length_field < 126
+        :small
+      elsif payload_length_field == 126
+        :medium
+      elsif payload_length_field == 127
+        :large
+      end
+    end
+
+    def pack_format
+      "#{FRAME_FORMAT[message_size]}#{actual_payload_length}"
+    end
+
+    def mask(data)
+      masked_data = ''.encode!("ASCII-8BIT")
+
+      data.each_byte.each_with_index do |byte, i|
+        masked_data << byte ^ mask_key.chars[i%4]
+      end
+    end
+
+    # The same algorithm applies regardless of the direction of the translation,
+    # e.g., the same steps are applied to mask the data as to unmask the data.
+    alias_method :unmask, :mask
+
+    def reset_frame!
+      @state = :header
+
+      @first_byte  = nil
+      @second_byte = nil
+
+      @mask = nil
+
+      @payload_length = nil
+      @payload        = nil
+    end
+  end
+end

data/lib/websocket/server_handshake.rb

@@ -0,0 +1,9 @@
+module WebSocket
+  class ServerHandshake < Http::Response
+
+    def initialize(status = nil, version = "1.1", headers = {}, body = nil, &body_proc)
+      @status, @version, @body, @body_proc = status, version, body, body_proc
+      @headers = headers
+    end
+  end
+end

data/lib/websocket/version.rb

@@ -0,0 +1,3 @@
+module WebSocket
+  VERSION = "0.0.1"
+end

data/lib/websocket_parser.rb

@@ -0,0 +1,35 @@
+require "websocket/version"
+require "websocket/client_handshake"
+require "websocket/server_handshake"
+require "websocket/message"
+require "websocket/parser"
+
+module WebSocket
+  PROTOCOL_VERSION = 13 # RFC 6455
+  GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+  # see http://tools.ietf.org/html/rfc6455#section-11.8
+  OPCODES = {
+    0  => :continuation,
+    1  => :text,
+    2  => :binary,
+    8  => :close,
+    9  => :ping,
+    10 => :pong
+  }
+
+  OPCODE_VALUES = {
+    :continuation => 0,
+    :text         => 1,
+    :binary       => 2,
+    :close        => 8,
+    :ping         => 9,
+    :pong         => 10
+  }
+
+  FRAME_FORMAT = {
+    :small  => 'CCa',   # 2 bytes for header. N bytes for payload.
+    :medium => 'CCS<a', # 2 bytes for header. 2 bytes for extended length. N bytes for payload.
+    :large  => 'CCQ<a'  # 2 bytes for header. 4 bytes for extended length. N bytes for payload.
+  }
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'bundler/setup'
+require 'http'
+require 'websocket_parser'

data/spec/websocket/handshake_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe WebSocket::ClientHandshake do
+
+  let :handshake_headers do
+    {
+      "Host"                   => "server.example.com",
+      "Upgrade"                => "websocket",
+      "Connection"             => "Upgrade",
+      "Sec-WebSocket-Key"      => "dGhlIHNhbXBsZSBub25jZQ==",
+      "Origin"                 => "http://example.com",
+      "Sec-WebSocket-Protocol" => "chat, superchat",
+      "Sec-WebSocket-Version"  => "13"
+    }
+  end
+
+  let(:client_handshake) { WebSocket::ClientHandshake.new(:get, '/', handshake_headers) }
+
+  it "can validate handshake format" do
+    client_handshake.valid?.should be_true
+  end
+
+  it "can generate an accept response for the client" do
+    response = client_handshake.accept_response
+
+    response.status.should == 101
+    response.headers['Upgrade'].should == 'websocket'
+    response.headers['Connection'].should == 'Upgrade'
+    response.headers['Sec-WebSocket-Accept'].should == 's3pPLMBiTxaQ9kYGzzhZRbK+xOo='
+  end
+end

data/spec/websocket/message_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe WebSocket::Message do
+
+  it "knows its binary representation" do
+    text = 1500.times.collect { 'All work and no play makes Jack a dull boy.' }.join("\n\n")
+    message = WebSocket::Message.new(text)
+    data = message.to_data
+
+    # 2 bytes from header + 8 bytes from extended payload length + payload
+    data.size.should == 2 + 8 + text.length
+
+    first_byte, second_byte, ext_length, payload = data.unpack("CCQ<a#{text.length}")
+
+    first_byte.should  == 0b10000001 # Text frame with FIN bit set
+    second_byte.should == 0b01111111 # Unmasked. Payload length 127.
+    ext_length.should  == text.length
+    payload.should     == text
+  end
+end

data/spec/websocket/parser_spec.rb

@@ -0,0 +1,112 @@
+require 'spec_helper'
+
+describe WebSocket::Parser do
+
+  let(:received_messages) { [] }
+  let(:received_errors)   { [] }
+  let(:received_closes)   { [] }
+  let(:received_pings)    { [] }
+  let(:received_pongs)    { [] }
+
+  let(:parser) do
+    parser = WebSocket::Parser.new
+
+    parser.on_message { |m| received_messages << m }
+    parser.on_error   { |m| received_errors << m }
+    parser.on_close   { |m| received_closes << m }
+    parser.on_ping    { |m| received_pings << m }
+    parser.on_pong    { |m| received_pongs << m }
+
+    parser
+  end
+
+  it "recognizes a text message" do
+    parser << WebSocket::Message.new('Once upon a time').to_data
+
+    received_messages.first.should == 'Once upon a time'
+  end
+
+  it "can receive a message in parts" do
+    data = WebSocket::Message.new('Once upon a time').to_data
+    parser << data.slice!(0, 5)
+
+    received_messages.should be_empty
+
+    parser << data
+
+    received_messages.first.should == 'Once upon a time'
+  end
+
+  it "can receive succesive messages" do
+    msg1 = WebSocket::Message.new('Now is the winter of our discontent')
+    msg2 = WebSocket::Message.new('Made glorious summer by this sun of York')
+
+    parser << msg1.to_data
+    parser << msg2.to_data
+
+    received_messages[0].should == 'Now is the winter of our discontent'
+    received_messages[1].should == 'Made glorious summer by this sun of York'
+  end
+
+  it "can receive medium size messages" do
+    # Medium size messages has a payload length between 127 and 65_535 bytes
+
+    text = 4.times.collect { 'All work and no play makes Jack a dull boy.' }.join("\n\n")
+    text.length.should > 127
+    text.length.should < 65_536
+
+    parser << WebSocket::Message.new(text).to_data
+    received_messages.first.should == text
+  end
+
+  it "can receive large size messages" do
+    # Large size messages has a payload length greater than 65_535 bytes
+
+    text = 1500.times.collect { 'All work and no play makes Jack a dull boy.' }.join("\n\n")
+    text.length.should > 65_536
+
+    parser << WebSocket::Message.new(text).to_data
+
+    # Check lengths first to avoid gigantic error message
+    received_messages.first.length.should == text.length
+    received_messages.first.should == text
+  end
+
+  it "can receive multiframe messages" do
+    frame1 = WebSocket::Message.new("It is a truth universally acknowledged,", :continuation)
+    frame2 = WebSocket::Message.new("that a single man in possession of a good fortune,", :continuation)
+    frame3 = WebSocket::Message.new("must be in want of a wife.")
+
+    parser << frame1.to_data
+
+    received_messages.should be_empty
+
+    parser << frame2.to_data
+
+    received_messages.should be_empty
+
+    parser << frame3.to_data
+
+    received_messages.first.should == "It is a truth universally acknowledged," +
+    "that a single man in possession of a good fortune," +
+    "must be in want of a wife."
+  end
+
+  it "recognizes a ping message" do
+    parser << WebSocket::Message.ping('Oh, hai!').to_data
+
+    received_pings.first.should == 'Oh, hai!'
+  end
+
+  it "recognizes a pong message" do
+    parser << WebSocket::Message.pong('Hi there!').to_data
+
+    received_pongs.first.should == 'Hi there!'
+  end
+
+  it "recognizes a close message" do
+    parser << WebSocket::Message.close('Browser leaving page').to_data
+
+    received_closes.first.should == 'Browser leaving page'
+  end
+end

data/websocket_parser.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/websocket/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Alberto Fernandez-Capel"]
+  gem.email         = ["afcapel@gmail.com"]
+  gem.description   = %q{WebsocketParser is a RFC6455 compliant parser for websocket messages}
+  gem.summary       = %q{Parse websockets messages in Ruby}
+  gem.homepage      = "http://github.com/afcapel/websocket_parser"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "websocket_parser"
+  gem.require_paths = ["lib"]
+  gem.version       = WebSocket::VERSION
+
+  gem.add_runtime_dependency 'http'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: websocket_parser
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Alberto Fernandez-Capel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: WebsocketParser is a RFC6455 compliant parser for websocket messages
+email:
+- afcapel@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/websocket/client_handshake.rb
+- lib/websocket/message.rb
+- lib/websocket/parser.rb
+- lib/websocket/server_handshake.rb
+- lib/websocket/version.rb
+- lib/websocket_parser.rb
+- spec/spec_helper.rb
+- spec/websocket/handshake_spec.rb
+- spec/websocket/message_spec.rb
+- spec/websocket/parser_spec.rb
+- websocket_parser.gemspec
+homepage: http://github.com/afcapel/websocket_parser
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3979494630006513518
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3979494630006513518
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Parse websockets messages in Ruby
+test_files:
+- spec/spec_helper.rb
+- spec/websocket/handshake_spec.rb
+- spec/websocket/message_spec.rb
+- spec/websocket/parser_spec.rb