faye-websocket 0.3.0 → 0.4.0

data/CHANGELOG.txt

@@ -1,3 +1,10 @@
+=== 0.4.0 / 2012-02-13
+
+* Add ping() method to server-side WebSocket and EventSource
+* Buffer send() calls until the draft-76 handshake is complete
+* Fix HTTPS problems on Node 0.7
+
+
 === 0.3.0 / 2012-01-13
 
 * Add support for EventSource connections

data/README.rdoc

@@ -1,5 +1,8 @@
 = Faye::WebSocket
 
+* Travis CI build: {<img src="https://secure.travis-ci.org/faye/faye-websocket-ruby.png" />}[http://travis-ci.org/faye/faye-websocket-ruby]
+* Autobahn tests: {server}[http://faye.jcoglan.com/autobahn/servers/], {client}[http://faye.jcoglan.com/autobahn/clients/]
+
 This is a robust, general-purpose WebSocket implementation extracted from the
 {Faye}[http://faye.jcoglan.com] project. It provides classes for easily building
 WebSocket servers and clients in Ruby. It does not provide a server itself, but
@@ -72,6 +75,26 @@ appropriate adapters automatically.
     Faye::WebSocket.load_adapter('thin')
     run App
 
+Note that under certain circumstances (notably a draft-76 client connecting
+through an HTTP proxy), the WebSocket handshake will not be complete after you
+call `Faye::WebSocket.new` because the server will not have received the entire
+handshake from the client yet. In this case, calls to `ws.send` will buffer the
+message in memory until the handshake is complete, at which point any buffered
+messages will be sent to the client.
+
+If you need to detect when the WebSocket handshake is complete, you can use the
+`onopen` event.
+
+If the connection's protocol version supports it, you can call <tt>ws.ping()</tt>
+to send a ping message and wait for the client's response. This method takes a
+message string, and an optional callback that fires when a matching pong message
+is received. It returns +true+ iff a ping message was sent. If the client does
+not support ping/pong, this method sends no data and returns +false+.
+
+    ws.ping 'Mic check, one, two' do
+      # fires when pong is received
+    end
+
 
 == Using the WebSocket client
 
@@ -206,6 +229,10 @@ retryable every 10 seconds if the connection is broken:
 
     es = Faye::EventSource.new(es, :ping => 15, :retry => 10)
 
+You can send a ping message at any time by calling <tt>es.ping()</tt>. Unlike
+WebSocket the client does not send a response to this; it is merely to send some
+data over the wire to keep the connection alive.
+
 
 == Running your socket application
 

data/examples/app.rb

@@ -5,7 +5,7 @@ static = Rack::File.new(File.dirname(__FILE__))
 
 App = lambda do |env|
   if Faye::WebSocket.websocket?(env)
-    ws = Faye::WebSocket.new(env, ['irc', 'xmpp'])
+    ws = Faye::WebSocket.new(env, ['irc', 'xmpp'], :ping => 5)
     p [:open, ws.url, ws.version, ws.protocol]
     
     ws.onmessage = lambda do |event|

data/lib/faye/eventsource.rb

@@ -2,11 +2,9 @@ require File.expand_path('../websocket', __FILE__) unless defined?(Faye::WebSock
 
 module Faye
   class EventSource
-    DEFAULT_PING  = 10
     DEFAULT_RETRY = 5
     
-    include WebSocket::API::EventTarget
-    include WebSocket::API::ReadyStates
+    include WebSocket::API
     attr_reader :env, :url, :ready_state
     
     def self.eventsource?(env)
@@ -27,12 +25,14 @@ module Faye
     
     def initialize(env, options = {})
       @env    = env
-      @ping   = options[:ping] || DEFAULT_PING
+      @ping   = options[:ping]
       @retry  = (options[:retry] || DEFAULT_RETRY).to_f
       @url    = EventSource.determine_url(env)
       @stream = Stream.new(self)
       
       @ready_state = CONNECTING
+      @send_buffer = []
+      EventMachine.next_tick { open }
       
       callback = @env['async.callback']
       callback.call([101, {}, @stream])
@@ -43,11 +43,11 @@ module Faye
                     "\r\n\r\n" +
                     "retry: #{ (@retry * 1000).floor }\r\n\r\n")
       
-      @ping_timer = EventMachine.add_periodic_timer(@ping) do
-        @stream.write(":\r\n\r\n")
-      end
-      
       @ready_state = OPEN
+      
+      if @ping
+        @ping_timer = EventMachine.add_periodic_timer(@ping) { ping }
+      end
     end
     
     def last_event_id
@@ -73,6 +73,11 @@ module Faye
       true
     end
     
+    def ping(message = nil)
+      @stream.write(":\r\n\r\n")
+      true
+    end
+    
     def close
       return if [CLOSING, CLOSED].include?(@ready_state)
       @ready_state = CLOSED

data/lib/faye/websocket.rb

@@ -91,9 +91,11 @@ module Faye
     attr_reader :env
     include API
     
-    def initialize(env, supported_protos = nil)
-      @env    = env
-      @stream = Stream.new(self)
+    def initialize(env, supported_protos = nil, options = {})
+      @env     = env
+      @stream  = Stream.new(self)
+      @ping    = options[:ping]
+      @ping_id = 0
       
       @url = WebSocket.determine_url(@env)
       @ready_state = CONNECTING
@@ -101,15 +103,26 @@ module Faye
       
       @parser = WebSocket.parser(@env).new(self, :protocols => supported_protos)
       
+      @send_buffer = []
+      EventMachine.next_tick { open }
+      
       @callback = @env['async.callback']
       @callback.call([101, {}, @stream])
       @stream.write(@parser.handshake_response)
       
-      @ready_state = OPEN
+      @ready_state = OPEN if @parser.open?
       
-      event = Event.new('open')
-      event.init_event('open', false, false)
-      dispatch_event(event)
+      if @ping
+        @ping_timer = EventMachine.add_periodic_timer(@ping) do
+          @ping_id += 1
+          ping(@ping_id.to_s)
+        end
+      end
+    end
+    
+    def ping(message = '', &callback)
+      return false unless @parser.respond_to?(:ping)
+      @parser.ping(message, &callback)
     end
     
     def protocol
@@ -124,7 +137,9 @@ module Faye
     
     def parse(data)
       response = @parser.parse(data)
-      @stream.write(response) if response
+      return unless response
+      @stream.write(response)
+      open
     end
   end
   

data/lib/faye/websocket/api.rb

@@ -9,6 +9,9 @@ module Faye
         CLOSED     = 3
       end
       
+      class IllegalStateError < StandardError
+      end
+      
       require File.expand_path('../api/event_target', __FILE__)
       require File.expand_path('../api/event', __FILE__)
       include EventTarget
@@ -16,8 +19,26 @@ module Faye
       
       attr_reader :url, :ready_state, :buffered_amount
       
+    private
+      
+      def open
+        return if @parser and not @parser.open?
+        @ready_state = OPEN
+        
+        buffer = @send_buffer || []
+        while message = buffer.shift
+          send(*message)
+        end
+        
+        event = Event.new('open')
+        event.init_event('open', false, false)
+        dispatch_event(event)
+      end
+      
+    public
+      
       def receive(data)
-        return false unless ready_state == OPEN
+        return false unless @ready_state == OPEN
         event = Event.new('message')
         event.init_event('message', false, false)
         event.data = data
@@ -25,19 +46,30 @@ module Faye
       end
       
       def send(data, type = nil, error_type = nil)
-        return false if ready_state == CLOSED
+        if @ready_state == CONNECTING
+          if @send_buffer
+            @send_buffer << [data, type, error_type]
+            return true
+          else
+            raise IllegalStateError, 'Cannot call send(), socket is not open yet'
+          end
+        end
+        
+        return false if @ready_state == CLOSED
+        
         data = WebSocket.encode(data) if String === data
         frame = @parser.frame(data, type, error_type)
         @stream.write(frame) if frame
       end
       
       def close(code = nil, reason = nil, ack = true)
-        return if [CLOSING, CLOSED].include?(ready_state)
+        return if [CLOSING, CLOSED].include?(@ready_state)
         
         @ready_state = CLOSING
         
         close = lambda do
           @ready_state = CLOSED
+          EventMachine.cancel_timer(@ping_timer) if @ping_timer
           @stream.close_connection_after_writing
           event = Event.new('close', :code => code || 1000, :reason => reason || '')
           event.init_event('close', false, false)

data/lib/faye/websocket/draft75_parser.rb

@@ -23,6 +23,10 @@ module Faye
         upgrade
       end
       
+      def open?
+        true
+      end
+      
       def parse(buffer)
         buffer.each_byte do |data|
           case @stage

data/lib/faye/websocket/draft76_parser.rb

@@ -22,8 +22,6 @@ module Faye
       
       def handshake_signature(head)
         return nil if head.empty?
-        @handshake_complete = true
-        
         env = @socket.env
         
         key1   = env['HTTP_SEC_WEBSOCKET_KEY1']
@@ -32,11 +30,17 @@ module Faye
         key2   = env['HTTP_SEC_WEBSOCKET_KEY2']
         value2 = number_from_key(key2) / spaces_in_key(key2)
         
+        @handshake_complete = true
+        
         Digest::MD5.digest(big_endian(value1) +
                            big_endian(value2) +
                            head)
       end
       
+      def open?
+        !!@handshake_complete
+      end
+      
       def parse(data)
         return super if @handshake_complete
         handshake_signature(data)

data/lib/faye/websocket/hybi_parser.rb

@@ -48,8 +48,9 @@ module Faye
         @stage     = 0
         @masking   = options[:masking]
         @protocols = options[:protocols]
-
         @protocols = @protocols.split(/\s*,\s*/) if String === @protocols
+        
+        @ping_callbacks = {}
       end
 
       def version
@@ -87,7 +88,11 @@ module Faye
       def create_handshake
         Handshake.new(@socket.uri, @protocols)
       end
-
+      
+      def open?
+        true
+      end
+      
       def parse(data)
         @reader.put(data.bytes.to_a)
         buffer = true
@@ -172,6 +177,11 @@ module Faye
 
         WebSocket.encode(frame)
       end
+      
+      def ping(message = '', &callback)
+        @ping_callbacks[message] = callback if callback
+        @socket.send(message, :ping)
+      end
 
       def close(code = nil, reason = nil, &callback)
         return if @closed
@@ -283,6 +293,12 @@ module Faye
           when OPCODES[:ping] then
             return @socket.close(ERRORS[:protocol_error], nil, false) if payload.size > 125
             @socket.send(payload, :pong)
+
+          when OPCODES[:pong] then
+            message = WebSocket.encode(payload, true)
+            callback = @ping_callbacks[message]
+            @ping_callbacks.delete(message)
+            callback.call if callback
         end
       end
 

data/spec/faye/websocket/draft75_parser_examples.rb

@@ -0,0 +1,48 @@
+# encoding=utf-8
+
+require "spec_helper"
+
+shared_examples_for "draft-75 parser" do
+  it "parses text frames" do
+    @web_socket.should_receive(:receive).with("Hello")
+    parse [0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
+  end
+  
+  it "parses multiple frames from the same packet" do
+    @web_socket.should_receive(:receive).with("Hello").exactly(2)
+    parse [0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff, 0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
+  end
+  
+  it "parses text frames beginning 0x00-0x7F" do
+    @web_socket.should_receive(:receive).with("Hello")
+    parse [0x66, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
+  end
+  
+  it "ignores frames with a length header" do
+    @web_socket.should_not_receive(:receive)
+    parse [0x80, 0x05, 0x48, 0x65, 0x6c, 0x6c, 0x6f]
+  end
+  
+  it "parses text following an ignored block" do
+    @web_socket.should_receive(:receive).with("Hello")
+    parse [0x80, 0x02, 0x48, 0x65, 0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
+  end
+  
+  it "parses multibyte text frames" do
+    @web_socket.should_receive(:receive).with(encode "Apple = ")
+    parse [0x00, 0x41, 0x70, 0x70, 0x6c, 0x65, 0x20, 0x3d, 0x20, 0xef, 0xa3, 0xbf, 0xff]
+  end
+  
+  it "parses frames received in several packets" do
+    @web_socket.should_receive(:receive).with(encode "Apple = ")
+    parse [0x00, 0x41, 0x70, 0x70, 0x6c, 0x65]
+    parse [0x20, 0x3d, 0x20, 0xef, 0xa3, 0xbf, 0xff]
+  end
+  
+  it "parses fragmented frames" do
+    @web_socket.should_receive(:receive).with("Hello")
+    parse [0x00, 0x48, 0x65, 0x6c]
+    parse [0x6c, 0x6f, 0xff]
+  end
+end
+

data/spec/faye/websocket/draft75_parser_spec.rb

@@ -11,50 +11,6 @@ describe Faye::WebSocket::Draft75Parser do
   end
   
   describe :parse do
-    shared_examples_for "draft-75 parser" do
-      it "parses text frames" do
-        @web_socket.should_receive(:receive).with("Hello")
-        parse [0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
-      end
-      
-      it "parses multiple frames from the same packet" do
-        @web_socket.should_receive(:receive).with("Hello").exactly(2)
-        parse [0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff, 0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
-      end
-      
-      it "parses text frames beginning 0x00-0x7F" do
-        @web_socket.should_receive(:receive).with("Hello")
-        parse [0x66, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
-      end
-      
-      it "ignores frames with a length header" do
-        @web_socket.should_not_receive(:receive)
-        parse [0x80, 0x05, 0x48, 0x65, 0x6c, 0x6c, 0x6f]
-      end
-      
-      it "parses text following an ignored block" do
-        @web_socket.should_receive(:receive).with("Hello")
-        parse [0x80, 0x02, 0x48, 0x65, 0x00, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xff]
-      end
-      
-      it "parses multibyte text frames" do
-        @web_socket.should_receive(:receive).with(encode "Apple = ")
-        parse [0x00, 0x41, 0x70, 0x70, 0x6c, 0x65, 0x20, 0x3d, 0x20, 0xef, 0xa3, 0xbf, 0xff]
-      end
-      
-      it "parses frames received in several packets" do
-        @web_socket.should_receive(:receive).with(encode "Apple = ")
-        parse [0x00, 0x41, 0x70, 0x70, 0x6c, 0x65]
-        parse [0x20, 0x3d, 0x20, 0xef, 0xa3, 0xbf, 0xff]
-      end
-      
-      it "parses fragmented frames" do
-        @web_socket.should_receive(:receive).with("Hello")
-        parse [0x00, 0x48, 0x65, 0x6c]
-        parse [0x6c, 0x6f, 0xff]
-      end
-    end
-    
     it_should_behave_like "draft-75 parser"
   end
   

data/spec/spec_helper.rb

@@ -4,6 +4,7 @@ require 'thin'
 require 'rainbows'
 require File.expand_path('../../lib/faye/websocket', __FILE__)
 require File.expand_path('../../vendor/em-rspec/lib/em-rspec', __FILE__)
+require File.expand_path('../faye/websocket/draft75_parser_examples', __FILE__)
 
 Thin::Logging.silent = true
 Unicorn::Configurator::DEFAULTS[:logger] = Logger.new(StringIO.new)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faye-websocket
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-13 00:00:00.000000000 Z
+date: 2012-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &18778460 !ruby/object:Gem::Requirement
+  requirement: &21030040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 0.12.0
   type: :runtime
   prerelease: false
-  version_requirements: *18778460
+  version_requirements: *21030040
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &18778060 !ruby/object:Gem::Requirement
+  requirement: &21055040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18778060
+  version_requirements: *21055040
 - !ruby/object:Gem::Dependency
   name: rainbows
-  requirement: &18777520 !ruby/object:Gem::Requirement
+  requirement: &21054500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *18777520
+  version_requirements: *21054500
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &18777020 !ruby/object:Gem::Requirement
+  requirement: &21054000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 2.8.0
   type: :development
   prerelease: false
-  version_requirements: *18777020
+  version_requirements: *21054000
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &18776640 !ruby/object:Gem::Requirement
+  requirement: &21053620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18776640
+  version_requirements: *21053620
 - !ruby/object:Gem::Dependency
   name: thin
-  requirement: &18776100 !ruby/object:Gem::Requirement
+  requirement: &21053080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +76,7 @@ dependencies:
         version: 1.2.0
   type: :development
   prerelease: false
-  version_requirements: *18776100
+  version_requirements: *21053080
 description: 
 email: jcoglan@gmail.com
 executables: []
@@ -115,6 +115,7 @@ files:
 - examples/autobahn_client.rb
 - spec/faye/websocket/draft75_parser_spec.rb
 - spec/faye/websocket/client_spec.rb
+- spec/faye/websocket/draft75_parser_examples.rb
 - spec/faye/websocket/draft76_parser_spec.rb
 - spec/faye/websocket/hybi_parser_spec.rb
 - spec/server.key