onstomp 1.0.0 → 1.0.1

data/lib/onstomp/connections/stomp_1_0.rb

@@ -15,7 +15,7 @@ class OnStomp::Connections::Stomp_1_0 < OnStomp::Connections::Base
     @serializer = OnStomp::Connections::Serializers::Stomp_1_0.new
   end
   
-  # Creates a SUBSCRIBE frame. Sets +ack+ header to 'auto' unless it is
+  # 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

data/lib/onstomp/connections/stomp_1_1.rb

@@ -31,7 +31,7 @@ class OnStomp::Connections::Stomp_1_1 < OnStomp::Connections::Base
     super && pulse?
   end
   
-  # Creates a SUBSCRIBE frame. Sets +ack+ header to 'auto' unless it is
+  # 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

data/lib/onstomp/failover.rb

@@ -5,6 +5,10 @@ module OnStomp::Failover
   # Raised if the supplied failover: URI is not properly formatted as
   # +failover:(uri,uri,...)?optionalParams=values+
   class InvalidFailoverURIError < OnStomp::OnStompError; end
+  
+  # Raised if the maximum number of retries is exceed when calling
+  # {OnStomp::Failover::Client#connect}
+  class MaximumRetriesExceededError < OnStomp::OnStompError; end
 end
 
 require 'onstomp/failover/uri'

data/lib/onstomp/failover/buffers.rb

@@ -6,3 +6,4 @@ module OnStomp::Failover::Buffers
 end
 
 require 'onstomp/failover/buffers/written'
+require 'onstomp/failover/buffers/receipts'

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

@@ -0,0 +1,101 @@
+# -*- encoding: utf-8 -*-
+
+# A buffer that ensures frames are RECEIPTed against a
+# {OnStomp::Client client}'s {OnStomp::Connections::Base connection} and
+# replays the ones that were not when the
+# {OnStomp::Failover::Client failover} client reconnects.
+# @todo Quite a lot of this code is shared between Written and Receipts,
+#   we'll want to factor the common stuff out.
+class OnStomp::Failover::Buffers::Receipts
+  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)
+    failover.on_receipt &method(:debuffer_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
+      # Don't re-buffer frames that are being replayed.
+      unless f.header? :'x-onstomp-failover-replay'
+        # Create a receipt header, unless the frame already has one.
+        f[:receipt] = OnStomp.next_serial unless f.header?(:receipt)
+        @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 frames that neither transactional nor SUBSCRIBEs from the buffer
+  # by looking the buffered frames up by their `receipt` header.
+  def debuffer_frame r, *_
+    orig = @buffer_mutex.synchronize do
+      @buffer.detect { |f| f[:receipt] == r[:'receipt-id'] }
+    end
+    if orig
+      # COMMIT and ABORT debuffer the whole transaction sequence
+      if ['COMMIT', 'ABORT'].include? orig.command
+        debuffer_transaction orig
+      # Otherwise, if this isn't part of a transaction, debuffer the
+      # particular frame (if it's not a SUBSCRIBE)
+      elsif orig.command != 'SUBSCRIBE' && !orig.header?(:transaction)
+        @buffer_mutex.synchronize { @buffer.delete orig }
+      end
+    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

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

@@ -10,7 +10,7 @@ class OnStomp::Failover::Buffers::Written
     @buffer_mutex = Mutex.new
     @buffer = []
     @txs = {}
-    
+
     failover.before_send &method(:buffer_frame)
     failover.before_commit &method(:buffer_frame)
     failover.before_abort &method(:buffer_frame)
@@ -78,7 +78,7 @@ class OnStomp::Failover::Buffers::Written
   end
   
   # Called when the {OnStomp::Failover::Client failover} client triggers
-  # +on_failover_connected+ to start replaying any frames in the buffer.
+  # `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 }

data/lib/onstomp/failover/client.rb

@@ -28,25 +28,21 @@ class OnStomp::Failover::Client
   # @return [Fixnum]
   attr_configurable_int :retry_attempts, :default => 0
   # Whether or not to randomize the {#client_pool} before connecting through
-  # any of its {OnStomp::Client clients}. Defaults to +false+
+  # any of its {OnStomp::Client clients}. Defaults to `false`
   # @return [true,false]
   attr_configurable_bool :randomize, :default => false
   
   attr_reader :uri, :client_pool, :active_client, :frame_buffer, :connection
   
   def initialize(uris, options={})
-    if uris.is_a?(Array)
-      uris = "failover:(#{uris.map { |u| u.to_s }.join(',')})"
-    end
+    @uri = OnStomp::Failover::URI::FAILOVER.parse uris
     @client_mutex = Mutex.new
-    @uri = URI.parse(uris)
     configure_configurable options
     create_client_pool
     @active_client = nil
     @connection = nil
     @frame_buffer = buffer.new self
     @disconnecting = false
-    @client_ready = false
   end
   
   # Returns true if there is an {#active_client} and it is
@@ -76,22 +72,26 @@ class OnStomp::Failover::Client
   # {OnStomp::Client#disconnect disconnect} on the {#active_client}
   def disconnect *args, &block
     return unless active_client
-    @disconnecting = true
-    Thread.pass until @client_ready
-    active_client.disconnect *args, &block
+    # If we're not connected, let `reconnect` handle it.
+    #@disconnecting = [args, block]
+    #if connected?
+      @client_mutex.synchronize do
+        @disconnecting = true
+        active_client.disconnect *args, &block
+      end
+    #end
   end
   
   private
   def reconnect
     @client_mutex.synchronize do
-      @client_ready = false
       attempt = 1
       until connected? || retry_exceeded?(attempt)
         sleep_for_retry attempt
         begin
           trigger_failover_retry :before, attempt
           @active_client = client_pool.next_client
-          # +reconnect+ could be called again within the marked range.
+          # `reconnect` could be called again within the marked range.
           active_client.connect # <--- From here
           @connection = active_client.connection
         rescue Exception
@@ -102,7 +102,10 @@ class OnStomp::Failover::Client
       end
       connected?.tap do |b|
         b && trigger_failover_event(:connected, :on, active_client)
-        @client_ready = b
+        #if @disconnecting.is_a?(Array)
+        #  args, block = @disconnect
+        #  active_client.disconnect *args, &block
+        #end
       end # <--- Until here
     end
   end

data/lib/onstomp/failover/failover_configurable.rb

@@ -3,7 +3,7 @@
 # Module for configurable attributes specific to
 # {OnStomp::Failover::Client failover} clients.
 module OnStomp::Failover::FailoverConfigurable
-  # Includes {OnStomp::Interfaces::ClientConfigurable} into +base+ and
+  # Includes {OnStomp::Interfaces::ClientConfigurable} into `base` and
   # extends {OnStomp::Failover::FailoverConfigurable::ClassMethods}
   # @param [Module] base
   def self.included(base)
@@ -23,8 +23,8 @@ module OnStomp::Failover::FailoverConfigurable
     
     # Creates readable and writeable attributes that are automatically
     # converted into boolean values. Assigning the attributes any of
-    # +true+, +'true'+, +'1'+ or +1+ will set the attribute to +true+, all
-    # other values with be treated as +false+. This method will also alias
+    # `true`, +'true'+, +'1'+ or +1+ will set the attribute to `true`, all
+    # other values with be treated as `false`. This method will also alias
     # the reader methods with +attr_name?+
     def attr_configurable_bool *args, &block
       trans = attr_configurable_wrap lambda { |v|

data/lib/onstomp/failover/pools/base.rb

@@ -2,7 +2,7 @@
 
 # An abstract pool of clients. This class manages the shared behaviors
 # of client pools, but has no means of picking successive clients.
-# Subclasses must define +next_client+ or pool will not function.
+# Subclasses must define `next_client` or pool will not function.
 class OnStomp::Failover::Pools::Base
   attr_reader :clients
   

data/lib/onstomp/failover/uri.rb

@@ -3,27 +3,52 @@
 # Namespace for failover related URI classes.
 module OnStomp::Failover::URI
   # A URI class for representing URIs with a 'failover' scheme.
+  # We don't need to worry about hooking into Ruby's URI parsing jazz since
+  # we have full control over when failover URIs will be created.
   class FAILOVER < OnStomp::Components::URI::STOMP
-    # Matches the internal URIs and query contained in
-    # the +opaque+ part of a failover: URI
-    FAILOVER_OPAQUE_REG = /^\(([^\)]+)\)(?:\?(.*))?/
+    # Matches a failover URI string, grouping the list of real URIs and
+    # any query parameters for the failover URI.
+    FAILOVER_REG = /^failover:(?:\/\/)?\(?([^\)]+)\)?(?:\?(.*))?/
     
     attr_reader :failover_uris
-    def initialize(*args)
-      super
-      _split_opaque_
+    def initialize uris, query
+      @failover_uris = uris.map do |u|
+        u.is_a?(::URI) ? u : ::URI.parse(u.strip)
+      end
+      super 'failover', nil, nil, nil, nil, '', "(#{uris.join(',')})", query, nil
+    end
+    
+    # Converts a failover URI into a string. Ruby's Generic URIs don't seem
+    # to allow mixing opaques and queries.
+    # @return [String]
+    def to_s
+      base = "#{scheme}:#{opaque}"
+      query.nil? || query.empty? ? base : "#{base}?#{query}"
     end
     
-    private
-    def _split_opaque_
-      if opaque =~ FAILOVER_OPAQUE_REG
-        furis, fquery = $1, $2
-        @failover_uris = furis.split(',').map { |u| ::URI.parse(u.strip) }
-        self.set_opaque nil
-        self.set_path ''
-        self.set_query fquery
-      else
-        raise OnStomp::Failover::InvalidFailoverURIError, self.to_s
+    class << self
+      # Parses a failover URI string or an array of URIs into a
+      # {OnStomp::Failover::URI::FAILOVER} object. Ruby's URI parser works
+      # fine with +failover:(uri1,uri2,..)?params=..+ style URIs, but chokes
+      # on +failover://uri1,uri2,..+ forms. This method gives us a bit more
+      # flexibility.
+      # @note If you are using the +open-uri+ extension with `failover`, you
+      #   MUST use the +failover:(uri1,uri2,..)+ form because +open-uri+
+      #   relies on +URI.parse+ to convert strings into `URI` objects.
+      # @overload parse(str)
+      #   @param [String] str
+      #   @return [FAILOVER]
+      # @overload parse(uri_arr)
+      #   @param [Array<String or URI>] uri_arr
+      #   @return [FAILOVER]
+      def parse uri_str
+        if uri_str.is_a? Array
+          self.new uri_str, nil
+        elsif uri_str =~ FAILOVER_REG
+          self.new $1.split(','), $2
+        else
+          raise OnStomp::Failover::InvalidFailoverURIError, uri_str
+        end
       end
     end
   end

data/lib/onstomp/interfaces/client_configurable.rb

@@ -2,7 +2,7 @@
 
 # Module for configurable attributes specific to {OnStomp::Client client} objects.
 module OnStomp::Interfaces::ClientConfigurable
-  # Includes {OnStomp::Interfaces::UriConfigurable} into +base+ and
+  # Includes {OnStomp::Interfaces::UriConfigurable} into `base` and
   # extends {OnStomp::Interfaces::ClientConfigurable::ClassMethods}
   # @param [Module] base
   def self.included(base)

data/lib/onstomp/interfaces/client_events.rb

@@ -3,64 +3,77 @@
 # Mixin for {OnStomp::Client client} events
 # There are a few special event methods that will be passed on
 # to the client's connection, they are:
-# * +on_connection_established+ => {OnStomp::Interfaces::ConnectionEvents#on_established}
-# * +on_connection_died+ => {OnStomp::Interfaces::ConnectionEvents#on_died}
-# * +on_connection_terminated+ => {OnStomp::Interfaces::ConnectionEvents#on_terminated}
-# * +on_connection_closed+ => {OnStomp::Interfaces::ConnectionEvents#on_closed}
+# * `on_connection_established` => {OnStomp::Interfaces::ConnectionEvents#on_established}
+# * `on_connection_died` => {OnStomp::Interfaces::ConnectionEvents#on_died}
+# * `on_connection_terminated` => {OnStomp::Interfaces::ConnectionEvents#on_terminated}
+# * `on_connection_closed` => {OnStomp::Interfaces::ConnectionEvents#on_closed}
 module OnStomp::Interfaces::ClientEvents
   include OnStomp::Interfaces::EventManager
 
   # @group Client Frame Event Bindings
   
-  # Can't get +before+ because the CONNECT frame isn't transmitted by
+  # @api gem:1 STOMP:1.0,1.1
+  # Can't get `before` because the CONNECT frame isn't transmitted by
   # the client.
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
   create_event_methods :connect, :on
-  
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when an ACK frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :ack, :before, :on
+  # @api gem:1 STOMP:1.1
   # Binds a callback to be invoked when a NACK frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :nack, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a BEGIN frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :begin, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when an ABORT frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :abort, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a COMMIT frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :commit, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a SEND frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :send, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a SUBSCRIBE frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :subscribe, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when an UNSUBSCRIBE frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :unsubscribe, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a DISCONNECT frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :disconnect, :before, :on
+  # @api gem:1 STOMP:1.1
   # Binds a callback to be invoked when a client heartbeat is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
@@ -68,22 +81,26 @@ module OnStomp::Interfaces::ClientEvents
   create_event_methods :client_beat, :before, :on
   
   # @group Broker Frame Event Bindings
-  
+
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when an ERROR frame is received
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :error, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a MESSAGE frame is received
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :message, :before, :on
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when a RECEIPT frame is received
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :receipt, :before, :on
+  # @api gem:1 STOMP:1.1
   # Binds a callback to be invoked when a broker heartbeat is received
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
@@ -92,11 +109,13 @@ module OnStomp::Interfaces::ClientEvents
 
   # @group Frame Exchange Event Bindings
   
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when any frame is transmitted
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
   # @yieldparam [OnStomp::Client] client
   create_event_methods :transmitting, :before, :after
+  # @api gem:1 STOMP:1.0,1.1
   # Binds a callback to be invoked when any frame is received
   # @yield [frame, client] callback invoked when event is triggered
   # @yieldparam [OnStomp::Components::Frame] frame
@@ -139,7 +158,7 @@ module OnStomp::Interfaces::ClientEvents
   end
   
   # Triggers the :before_receiving event and the
-  # +before+ prefixed frame specific event (eg: +:before_error+).
+  # `before` prefixed frame specific event (eg: +:before_error+).
   # @param [OnStomp::Components::Frame] f
   def trigger_before_receiving f
     trigger_event :before_receiving, f, self
@@ -147,7 +166,7 @@ module OnStomp::Interfaces::ClientEvents
   end
   
   # Triggers the :after_receiving event and the
-  # +on+ prefixed frame specific event (eg: +:on_message+)
+  # `on` prefixed frame specific event (eg: +:on_message+)
   # @param [OnStomp::Components::Frame] f
   def trigger_after_receiving f
     trigger_event :after_receiving, f, self
@@ -155,7 +174,7 @@ module OnStomp::Interfaces::ClientEvents
   end
   
   # Triggers the :before_transmitting event and the
-  # +before+ prefixed frame specific event (eg: +:before_disconnect+).
+  # `before` prefixed frame specific event (eg: +:before_disconnect+).
   # @param [OnStomp::Components::Frame] f
   def trigger_before_transmitting f
     trigger_event :before_transmitting, f, self
@@ -163,7 +182,7 @@ module OnStomp::Interfaces::ClientEvents
   end
   
   # Triggers the :after_transmitting event and the
-  # +on+ prefixed frame specific event (eg: +:on_send+).
+  # `on` prefixed frame specific event (eg: +:on_send+).
   # @param [OnStomp::Components::Frame] f
   def trigger_after_transmitting f
     trigger_event :after_transmitting, f, self