onstomp 1.0.0pre1 → 1.0.0

data/README.md

@@ -62,7 +62,7 @@ See the full {file:docs/LICENSE.md LICENSE} for details.
 There are a few people/groups I'd like to thank for helping me with the
 creation of this gem.
 
-* Lionel Cons the good suggestions while I was implementing support for the
+* Lionel Cons for the good suggestions while I was implementing support for the
   STOMP 1.1 spec. Check out his Perl client [Net::STOMP::Client](http://search.cpan.org/~lcons/Net-STOMP-Client-0.9.5/lib/Net/STOMP/Client.pm)
 * Brian McCallister, Johan Sørensen, Guy M. Allard and Thiago Morello for
   their work on the `stomp` gem which introduced me to the STOMP protocol.

data/Rakefile

@@ -4,3 +4,11 @@ Bundler::GemHelper.install_tasks
 require 'yard'
 require File.expand_path("../yard_extensions", __FILE__)
 YARD::Rake::YardocTask.new
+
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+task :default => :spec

data/examples/openuri.rb

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+$:.unshift(File.expand_path('../../lib', __FILE__))
+require 'onstomp'
+require 'onstomp/open-uri'
+
+open('stomp://localhost/queue/onstomp/openuri') do |c|
+  c.send "hello world!"
+  c.send "a fine day to you"
+  c.send "what rhymes with you?"
+  c.puts "may the rats eat your eyes"
+  c.send "I am now lost to your cause"
+  c.puts "the inquisition is here for a reason"
+end
+
+open('stomp://localhost/queue/onstomp/openuri') do |c|
+  c.each do |m|
+    puts "Got a message: #{m.body}"
+    break if m.body == 'what rhymes with you?'
+  end
+  
+  c.take(2).each { |m| puts "From take(2): #{m.body}" }
+  
+  puts "And finally: #{c.first.body}"
+end
+
+puts "Done with open-uri examples!"
+
+# Example output:
+#
+# Got a message: hello world!
+# Got a message: a fine day to you
+# Got a message: what rhymes with you?
+# From take(2): may the rats eat your eyes
+# From take(2): I am now lost to your cause
+# And finally: the inquisition is here for a reason
+# Done with open-uri examples!

data/lib/onstomp.rb

@@ -33,6 +33,10 @@ require 'monitor'
 
 # Primary namespace for the +onstomp+ gem
 module OnStomp
+  # Class to use for creating enumerator objects, which depends upon the
+  # version of Ruby being used.
+  ENUMERATOR_KLASS = (RUBY_VERSION >= '1.9') ? Enumerator : Enumerable::Enumerator
+  
   # A common base class for errors raised by the OnStomp gem
   # @abstract
   class OnStompError < StandardError; end

data/lib/onstomp/client.rb

@@ -50,7 +50,7 @@ class OnStomp::Client
   # Creates a new client for the specified uri and optional hash of options.
   # @param [String,URI] uri
   # @param [{Symbol => Object}] options
-  def initialize(uri, options={})
+  def initialize uri, options={}
     @uri = uri.is_a?(::URI) ? uri : ::URI.parse(uri)
     @ssl = options.delete(:ssl)
     configure_configurable options
@@ -65,7 +65,7 @@ class OnStomp::Client
   # headers in the CONNECT frame, if specified.
   # @param [{#to_sym => #to_s}] headers
   # @return [self]
-  def connect(headers={})
+  def connect headers={}
     @connection = OnStomp::Connections.connect self, headers,
       { :'accept-version' => @versions.join(','), :host => @host,
         :'heart-beat' => @heartbeats.join(','), :login => @login,
@@ -80,7 +80,8 @@ class OnStomp::Client
   # the broker will get processed barring any IO exceptions.
   # @param [{#to_sym => #to_s}] headers
   # @return [OnStomp::Components::Frame] transmitted DISCONNECT frame
-  def disconnect_with_flush(headers={})
+  def disconnect_with_flush headers={}
+    processor_inst.prepare_to_close
     disconnect_without_flush(headers).tap do
       processor_inst.join
     end
@@ -111,11 +112,11 @@ class OnStomp::Client
   # This method should not be invoked directly. Use the frame methods provided
   # by the {OnStomp::Interfaces:FrameMethod} interface.
   # @return [OnStomp::Components::Frame]
-  def transmit(frame, cbs={})
+  def transmit frame, cbs={}
     frame.tap do
       register_callbacks frame, cbs
       trigger_before_transmitting frame
-      connection.write_frame_nonblock frame
+      connection && connection.write_frame_nonblock(frame)
     end
   end
   

data/lib/onstomp/components.rb

@@ -8,6 +8,5 @@ require 'onstomp/components/uri'
 require 'onstomp/components/frame_headers'
 require 'onstomp/components/frame'
 require 'onstomp/components/subscription'
-require 'onstomp/components/nil_processor'
 require 'onstomp/components/threaded_processor'
 require 'onstomp/components/scopes'

data/lib/onstomp/components/frame_headers.rb

@@ -14,7 +14,7 @@ class OnStomp::Components::FrameHeaders
   # @see #merge!
   def initialize(headers={})
     @values = {}
-    __initialize_names__
+    initialize_names
     merge! headers
   end
   
@@ -115,7 +115,7 @@ class OnStomp::Components::FrameHeaders
   def delete(name)
     name = name.to_sym
     if @values.key? name
-      __delete_name__ name
+      delete_name name
       @values.delete name
     end
   end
@@ -150,7 +150,7 @@ class OnStomp::Components::FrameHeaders
   def []=(name, val)
     name = name.to_sym
     val = val.to_s
-    __add_name__ name
+    add_name name
     @values[name] = [val]
     val
   end
@@ -162,51 +162,48 @@ class OnStomp::Components::FrameHeaders
     @values.inject({}) { |h, (k,v)| h[k] = v.first; h }
   end
   
+  # Iterates over header name / value pairs, yielding them as a pair
+  # of strings to the supplied block.
+  # @yield [header_name, header_value]
+  # @yieldparam [String] header_name
+  # @yieldparam [String] header_value
+  def each &block
+    if block_given?
+      iterate_each &block
+      self
+    else
+      OnStomp::ENUMERATOR_KLASS.new(self)
+    end
+  end
+  
   if RUBY_VERSION >= "1.9"
     def names; @values.keys; end
     
-    def each(&block)
-      if block_given?
-        @values.each do |name, vals|
-          name_str = name.to_s
-          vals.each do |val|
-            yield [name_str, val]
-          end
+    private
+    def iterate_each
+      @values.each do |name, vals|
+        name_str = name.to_s
+        vals.each do |val|
+          yield [name_str, val]
         end
-        self
-      else
-        Enumerator.new(self)
       end
     end
-    
-    private
-    def __initialize_names__; end
-    def __delete_name__(name); end
-    def __add_name__(name); end
+    def initialize_names; end
+    def delete_name(name); end
+    def add_name(name); end
   else
     attr_reader :names
-    
-    # Iterates over header name / value pairs, yielding them as a pair
-    # of strings to the supplied block.
-    # @yield [header_name, header_value]
-    # @yieldparam [String] header_name
-    # @yieldparam [String] header_value
-    def each(&block)
-      if block_given?
-        @names.each do |name|
-          @values[name].each do |val|
-            yield [name.to_s, val]
-          end
+
+    private
+    def iterate_each
+      @names.each do |name|
+        @values[name].each do |val|
+          yield [name.to_s, val]
         end
-        self
-      else
-        Enumerable::Enumerator.new(self)
       end
     end
-
-    private
-    def __initialize_names__; @names = []; end
-    def __delete_name__(name); @names.delete name; end
-    def __add_name__(name); @names << name unless @values.key?(name); end
+    def initialize_names; @names = []; end
+    def delete_name(name); @names.delete name; end
+    def add_name(name); @names << name unless @values.key?(name); end
   end
 end

data/lib/onstomp/components/threaded_processor.rb

@@ -7,6 +7,7 @@ class OnStomp::Components::ThreadedProcessor
   def initialize client
     @client = client
     @run_thread = nil
+    @closing = false
   end
   
   # Returns true if its IO thread has been created and is alive, otherwise
@@ -25,6 +26,7 @@ class OnStomp::Components::ThreadedProcessor
       begin
         while @client.connected?
           @client.connection.io_process
+          Thread.stop if @closing
         end
       rescue OnStomp::StopReceiver
       rescue Exception
@@ -34,6 +36,17 @@ class OnStomp::Components::ThreadedProcessor
     self
   end
   
+  # Prepares the conneciton for closing by flushing its write buffer.
+  def prepare_to_close
+    if running?
+      @closing = true
+      Thread.pass until @run_thread.stop?
+      @client.connection.flush_write_buffer
+      @closing = false
+      @run_thread.wakeup
+    end
+  end
+  
   # Causes the thread this method was invoked in to +pass+ until the
   # processor is no longer {#running? running}.
   # @return [self]

data/lib/onstomp/connections/base.rb

@@ -93,13 +93,19 @@ class OnStomp::Connections::Base
     end
   end
   
+  # Flushes the write buffer by invoking {#io_process_write} until the
+  # buffer is empty.
+  def flush_write_buffer
+    io_process_write until @write_buffer.empty?
+  end
+  
   # Makes a single call to {#io_process_write} and a single call to
   # {#io_process_read}
   def io_process &cb
     io_process_write &cb
     io_process_read &cb
     if @connection_up && !connected?
-      triggered_close :died
+      triggered_close 'connection timed out', :died
     end
   end
   
@@ -162,13 +168,13 @@ class OnStomp::Connections::Base
           unshift_write_buffer data, frame
           break
         rescue Exception
-          triggered_close :terminated
+          triggered_close $!.message, :terminated
           raise
         end
       end
     end
     if @write_buffer.empty? && @closing
-      triggered_close
+      triggered_close 'client disconnected'
     end
   end
   
@@ -189,20 +195,21 @@ class OnStomp::Connections::Base
       rescue Errno::EINTR, Errno::EAGAIN, Errno::EWOULDBLOCK
         # do not
       rescue EOFError
-        triggered_close
+        triggered_close $!.message
       rescue Exception
-        triggered_close :terminated
+        triggered_close $!.message, :terminated
         raise
       end
     end
   end
   
   private
-  def triggered_close *evs
+  def triggered_close msg, *evs
     @connection_up = false
     @closing = false
     socket.close
-    evs.each { |ev| trigger_connection_event ev }
-    trigger_connection_event :closed
+    evs.each { |ev| trigger_connection_event ev, msg }
+    trigger_connection_event :closed, msg
+    @write_buffer.clear
   end
 end

data/lib/onstomp/connections/stomp_1.rb

@@ -38,12 +38,6 @@ module OnStomp::Connections::Stomp_1
     create_frame 'DISCONNECT', [h]
   end
   
-  # Creates a SUBSCRIBE frame
-  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
-  def subscribe_frame d, h
-    create_frame 'SUBSCRIBE', [{:id => OnStomp.next_serial}, h, {:destination => d}]
-  end
-  
   # Creates an UNSUBSCRIBE frame
   # @return [OnStomp::Components::Frame] UNSUBSCRIBE frame
   def unsubscribe_frame f, h

data/lib/onstomp/connections/stomp_1_0.rb

@@ -14,6 +14,14 @@ class OnStomp::Connections::Stomp_1_0 < OnStomp::Connections::Base
     super
     @serializer = OnStomp::Connections::Serializers::Stomp_1_0.new
   end
+  
+  # Creates a SUBSCRIBE frame. Sets +ack+ header to 'auto' unless it is
+  # already set to 'client'.
+  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
+  def subscribe_frame d, h
+    h[:ack] = 'auto' unless h[:ack] == 'client'
+    create_frame 'SUBSCRIBE', [{:id => OnStomp.next_serial}, h, {:destination => d}]
+  end
 
   # Creates an ACK frame
   # @return [OnStomp::Components::Frame] ACK frame

data/lib/onstomp/connections/stomp_1_1.rb

@@ -31,6 +31,14 @@ class OnStomp::Connections::Stomp_1_1 < OnStomp::Connections::Base
     super && pulse?
   end
   
+  # Creates a SUBSCRIBE frame. Sets +ack+ header to 'auto' unless it is
+  # already set to 'client' or 'client-individual'.
+  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
+  def subscribe_frame d, h
+    h[:ack] = 'auto' unless ['client', 'client-individual'].include?(h[:ack])
+    create_frame 'SUBSCRIBE', [{:id => OnStomp.next_serial}, h, {:destination => d}]
+  end
+  
   # Creates an ACK frame
   # @return [OnStomp::Components::Frame] ACK frame
   def ack_frame *args

data/lib/onstomp/failover.rb

@@ -0,0 +1,16 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for failover extensions.
+module OnStomp::Failover
+  # Raised if the supplied failover: URI is not properly formatted as
+  # +failover:(uri,uri,...)?optionalParams=values+
+  class InvalidFailoverURIError < OnStomp::OnStompError; end
+end
+
+require 'onstomp/failover/uri'
+require 'onstomp/failover/failover_configurable'
+require 'onstomp/failover/failover_events'
+require 'onstomp/failover/buffers'
+require 'onstomp/failover/pools'
+require 'onstomp/failover/client'
+require 'onstomp/failover/new_with_failover'

data/lib/onstomp/failover/buffers.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for various frame buffering strategies to keep failover working
+# like it should.
+module OnStomp::Failover::Buffers
+end
+
+require 'onstomp/failover/buffers/written'

data/lib/onstomp/failover/buffers/written.rb

@@ -0,0 +1,91 @@
+# -*- encoding: utf-8 -*-
+
+# A buffer that ensures frames are at least written to a
+# {OnStomp::Client client}'s {OnStomp::Connections::Base connection} and
+# replays the ones that were not when the
+# {OnStomp::Failover::Client failover} client reconnects.
+class OnStomp::Failover::Buffers::Written
+  def initialize failover
+    @failover = failover
+    @buffer_mutex = Mutex.new
+    @buffer = []
+    @txs = {}
+    
+    failover.before_send &method(:buffer_frame)
+    failover.before_commit &method(:buffer_frame)
+    failover.before_abort &method(:buffer_frame)
+    failover.before_subscribe &method(:buffer_frame)
+    failover.before_begin &method(:buffer_transaction)
+    # We can scrub the subscription before UNSUBSCRIBE is fully written
+    # because if we replay before UNSUBSCRIBE was sent, we still don't
+    # want to be subscribed when we reconnect.
+    failover.before_unsubscribe &method(:debuffer_subscription)
+    # We only want to scrub the transactions if ABORT or COMMIT was
+    # at least written fully to the socket.
+    failover.on_commit &method(:debuffer_transaction)
+    failover.on_abort &method(:debuffer_transaction)
+    failover.on_send &method(:debuffer_non_transactional_frame)
+    
+    failover.on_failover_connected &method(:replay)
+  end
+  
+  # Adds a frame to a buffer so that it may be replayed if the
+  # {OnStomp::Failover::Client failover} client re-connects
+  def buffer_frame f, *_
+    @buffer_mutex.synchronize do
+      unless f.header? :'x-onstomp-failover-replay'
+        @buffer << f 
+      end
+    end
+  end
+  
+  # Records the start of a transaction so that it may be replayed if the
+  # {OnStomp::Failover::Client failover} client re-connects
+  def buffer_transaction f, *_
+    @txs[f[:transaction]] = true
+    buffer_frame f
+  end
+  
+  # Removes the recorded transaction from the buffer after it has been
+  # written the broker socket so that it will not be replayed when the
+  # {OnStomp::Failover::Client failover} client re-connects
+  def debuffer_transaction f, *_
+    tx = f[:transaction]
+    if @txs.delete tx
+      @buffer_mutex.synchronize do
+        @buffer.reject! { |bf| bf[:transaction] == tx }
+      end
+    end
+  end
+  
+  # Removes the matching SUBSCRIBE frame from the buffer after the
+  # UNSUBSCRIBE has been added to the connection's write buffer
+  # so that it will not be replayed when the
+  # {OnStomp::Failover::Client failover} client re-connects
+  def debuffer_subscription f, *_
+    @buffer_mutex.synchronize do
+      @buffer.reject! { |bf| bf.command == 'SUBSCRIBE' && bf[:id] == f[:id] }
+    end
+  end
+  
+  # Removes a frame that is not part of a transaction from the buffer
+  # after it has been written the broker socket so that it will not be
+  # replayed when the {OnStomp::Failover::Client failover} client re-connects
+  def debuffer_non_transactional_frame f, *_
+    unless @txs.key?(f[:transaction])
+      @buffer_mutex.synchronize { @buffer.delete f }
+    end
+  end
+  
+  # Called when the {OnStomp::Failover::Client failover} client triggers
+  # +on_failover_connected+ to start replaying any frames in the buffer.
+  def replay fail, client, *_
+    replay_frames = @buffer_mutex.synchronize do
+      @buffer.select { |f| f[:'x-onstomp-failover-replay'] = '1'; true }
+    end
+    
+    replay_frames.each do |f|
+      client.transmit f
+    end
+  end
+end